From 501de5161e85b3c47b760a5b07d1a73c640630c4 Mon Sep 17 00:00:00 2001 From: Marius Tarau Date: Wed, 18 Feb 2026 19:34:49 +0200 Subject: [PATCH] docs: make SESSION-GUIDE.md device-agnostic with Gitea URLs All prompts now use repo URL instead of local paths. Works from any device: Mac, PC, phone, any AI tool. Two access points: internal (10.10.10.166:3002) and external (git.beletage.ro). Added tool-specific notes for Claude Code, ChatGPT Codex, Copilot, Cursor, Antigravity, phone. Raw file URLs for AI tools that can fetch web content. Co-Authored-By: Claude Opus 4.6 --- SESSION-GUIDE.md | 256 +++++++++++++++++++++++++---------------------- 1 file changed, 135 insertions(+), 121 deletions(-) diff --git a/SESSION-GUIDE.md b/SESSION-GUIDE.md index 9d30289..2d436fd 100644 --- a/SESSION-GUIDE.md +++ b/SESSION-GUIDE.md @@ -1,94 +1,93 @@ -# ArchiTools — Session Guide for AI Assistants +# ArchiTools — Session Guide -> How to start, resume, and hand off coding sessions. Keep this file updated. +> Device-agnostic prompts for any AI tool, from anywhere. --- -## Project Location +## Repository URLs -| What | Where | -|---|---| -| **Gitea repo** | `http://10.10.10.166:3002/gitadmin/ArchiTools` | -| **Branch** | `main` | -| **Local path (Mac)** | `/Users/mariustarau/Development/ArchiTools` | -| **Production** | `http://10.10.10.166:3000` | -| **Dev server** | `http://localhost:3000` | - -### Key Files (all in repo root) - -| File | What it does | Read when | +| Access | Git Clone URL | Web UI | |---|---|---| -| `CLAUDE.md` | Project context, stack, architecture, conventions | Every session start | -| `ROADMAP.md` | Complete task list — tasks with ✅ are done, others are pending | Every session start | -| `SESSION-LOG.md` | What was done in each previous session | Every session start | -| `SESSION-GUIDE.md` | This file — prompts, workflow, rules | First time only | +| **Internal (office)** | `http://10.10.10.166:3002/gitadmin/ArchiTools.git` | http://10.10.10.166:3002/gitadmin/ArchiTools | +| **External (internet)** | `https://git.beletage.ro/gitadmin/ArchiTools.git` | https://git.beletage.ro/gitadmin/ArchiTools | + +### Raw File URLs (for AI tools that can fetch URLs) + +Replace `{GITEA}` with whichever base works for you: +- Internal: `http://10.10.10.166:3002` +- External: `https://git.beletage.ro` + +| File | URL | +|---|---| +| CLAUDE.md | `{GITEA}/gitadmin/ArchiTools/raw/branch/main/CLAUDE.md` | +| ROADMAP.md | `{GITEA}/gitadmin/ArchiTools/raw/branch/main/ROADMAP.md` | +| SESSION-LOG.md | `{GITEA}/gitadmin/ArchiTools/raw/branch/main/SESSION-LOG.md` | +| SESSION-GUIDE.md | `{GITEA}/gitadmin/ArchiTools/raw/branch/main/SESSION-GUIDE.md` | + +**Production app:** http://10.10.10.166:3000 --- -## Prompt: Starting a Brand New Session - -Copy-paste this to any AI coding assistant (Claude Code, Cursor, Windsurf, Copilot, etc.): +## PROMPT 1: New Session (any device, any AI) ``` I'm working on ArchiTools, an internal web dashboard for an architecture office. -Repo: http://10.10.10.166:3002/gitadmin/ArchiTools (branch: main) -Local path: /Users/mariustarau/Development/ArchiTools +Repository: https://git.beletage.ro/gitadmin/ArchiTools.git (branch: main) -Read these files from the repo root first (in this order): -1. /Users/mariustarau/Development/ArchiTools/CLAUDE.md — project context, stack, architecture -2. /Users/mariustarau/Development/ArchiTools/ROADMAP.md — task list (tasks with ✅ are done, pick the next one without ✅) -3. /Users/mariustarau/Development/ArchiTools/SESSION-LOG.md — what previous sessions did -4. /Users/mariustarau/Development/ArchiTools/SESSION-GUIDE.md — workflow rules +Before doing anything, read these 4 files from the repo: +- CLAUDE.md (project context, stack, architecture, conventions) +- ROADMAP.md (complete task list — tasks with ✅ are done, pick the next one without ✅) +- SESSION-LOG.md (what previous sessions did) +- SESSION-GUIDE.md (workflow rules) -Start by running: git pull origin main && npm install -Then pick the next uncompleted task from ROADMAP.md (top to bottom, skip ✅ tasks). +Setup: clone the repo (or pull latest if already cloned), run npm install. + +Then pick the next uncompleted task from ROADMAP.md (work top to bottom, skip ✅ tasks). Rules: -- Run `npx next build` before every commit (zero errors required) -- Push to main when done (Portainer auto-deploys to http://10.10.10.166:3000) -- Update ROADMAP.md: mark completed tasks with ✅ and date -- Update SESSION-LOG.md: add entry at the TOP with what you did -- Notify me when a module/task is ready for my review on http://10.10.10.166:3000 +- Run `npx next build` before every commit — zero errors required +- Push to main when done — Portainer auto-deploys to production +- Update ROADMAP.md: mark completed tasks with ✅ and the date +- Update SESSION-LOG.md: add an entry at the TOP describing what you did +- Commit and push these log updates too +- Notify me when a task is ready for my review - Do NOT move to the next task until I approve the current one -- Code in English, UI in Romanian +- Code in English, UI text in Romanian ``` --- -## Prompt: Resuming Where You Left Off +## PROMPT 2: Resume Previous Work ``` I'm continuing work on ArchiTools. -Repo: http://10.10.10.166:3002/gitadmin/ArchiTools (branch: main) -Local path: /Users/mariustarau/Development/ArchiTools +Repository: https://git.beletage.ro/gitadmin/ArchiTools.git (branch: main) -Read these files first: -1. /Users/mariustarau/Development/ArchiTools/CLAUDE.md — project context -2. /Users/mariustarau/Development/ArchiTools/ROADMAP.md — find the next task without ✅ -3. /Users/mariustarau/Development/ArchiTools/SESSION-LOG.md — see what was done before +Read these files from the repo: +- CLAUDE.md (project context) +- ROADMAP.md (find the next task without ✅) +- SESSION-LOG.md (what was done in previous sessions) -Run: git pull origin main && npm install -Then continue with the next uncompleted task from ROADMAP.md. +Pull latest, npm install, then continue with the next uncompleted task. -Same rules: build must pass, push when done, update ROADMAP.md and SESSION-LOG.md, -notify me for review on http://10.10.10.166:3000 before moving to next task. +Same rules: build must pass, push when done, update ROADMAP.md (✅ + date) +and SESSION-LOG.md, notify me for review before moving to next task. ``` --- -## Prompt: Specific Task +## PROMPT 3: Specific Task ``` I'm working on ArchiTools. -Local path: /Users/mariustarau/Development/ArchiTools +Repository: https://git.beletage.ro/gitadmin/ArchiTools.git (branch: main) -Read /Users/mariustarau/Development/ArchiTools/CLAUDE.md and -/Users/mariustarau/Development/ArchiTools/ROADMAP.md first. +Read CLAUDE.md and ROADMAP.md from the repo first. +Pull latest, npm install. -Run: git pull origin main && npm install -Then work on task [NUMBER] ([TASK NAME]) from ROADMAP.md. +Work on task [NUMBER] ([TASK NAME]) from ROADMAP.md. Implement it, run `npx next build` (must pass), push to main, update ROADMAP.md (✅ + date) and SESSION-LOG.md, then notify me. @@ -96,145 +95,160 @@ update ROADMAP.md (✅ + date) and SESSION-LOG.md, then notify me. --- -## Prompt: Bug Fix +## PROMPT 4: Bug Fix ``` I'm working on ArchiTools. -Local path: /Users/mariustarau/Development/ArchiTools +Repository: https://git.beletage.ro/gitadmin/ArchiTools.git (branch: main) -Read /Users/mariustarau/Development/ArchiTools/CLAUDE.md first. +Read CLAUDE.md from the repo first. Pull latest. -Run: git pull origin main -There's a bug: [DESCRIBE THE BUG]. -Investigate, fix it, run `npx next build`, push to main. -Don't change anything unrelated to the bug. -Update SESSION-LOG.md with what you fixed. +Bug: [DESCRIBE THE BUG] + +Fix it, run `npx next build`, push to main. +Don't change anything unrelated. Update SESSION-LOG.md. ``` --- -## Prompt: Code Review (no changes) +## PROMPT 5: Code Review (no changes) ``` I'm working on ArchiTools. -Local path: /Users/mariustarau/Development/ArchiTools +Repository: https://git.beletage.ro/gitadmin/ArchiTools.git (branch: main) -Read /Users/mariustarau/Development/ArchiTools/CLAUDE.md first. +Read CLAUDE.md from the repo. Pull latest. -Run: git pull origin main -Review the last 3 commits on main. Check for: +Review the last 3 commits. Check for: - TypeScript strict mode issues -- Missing null guards on Record/array access +- Missing null guards - UI text that should be in Romanian - Unused imports or dead code -- Security issues (XSS, injection) +- Security issues + Don't change anything, just report findings. ``` --- -## Prompt: New Module from Scratch +## PROMPT 6: New Module from Scratch ``` I'm working on ArchiTools. -Local path: /Users/mariustarau/Development/ArchiTools +Repository: https://git.beletage.ro/gitadmin/ArchiTools.git (branch: main) -Read /Users/mariustarau/Development/ArchiTools/CLAUDE.md and -/Users/mariustarau/Development/ArchiTools/ROADMAP.md first. +Read CLAUDE.md and ROADMAP.md from the repo first. +Pull latest, npm install. -Run: git pull origin main && npm install -I want to build [MODULE NAME] as described in task [NUMBER] of ROADMAP.md. +Build [MODULE NAME] as described in task [NUMBER] of ROADMAP.md. -Read the module pattern in /Users/mariustarau/Development/ArchiTools/src/modules/registratura/ -as reference. Follow the same structure: +Use the module at src/modules/registratura/ as reference for the pattern: types.ts, config.ts, services/, hooks/, components/, index.ts -Also create: - src/app/(modules)/[route]/page.tsx - Update src/config/modules.ts, navigation.ts, flags.ts +Also create: route page, update modules.ts, navigation.ts, flags.ts. Run `npx next build`, push to main, update ROADMAP.md + SESSION-LOG.md, notify me. ``` --- -## Git Workflow +## Tool-Specific Notes -### First time (clone) +### Claude Code (CLI) +Works natively. Clone/pull, read files, edit, build, push — all built in. + +### ChatGPT Codex +Give it the repo URL. It can clone via git, read files, and push. +Use the external URL: `https://git.beletage.ro/gitadmin/ArchiTools.git` + +### VS Code + Copilot / Cursor / Windsurf +Clone the repo locally first, then open in the IDE. The AI agent reads files from disk. ```bash -git clone http://10.10.10.166:3002/gitadmin/ArchiTools.git -cd ArchiTools -npm install -npm run dev # http://localhost:3000 +git clone https://git.beletage.ro/gitadmin/ArchiTools.git +cd ArchiTools && npm install && code . ``` -### Every session start (pull) -```bash -cd /Users/mariustarau/Development/ArchiTools -git pull origin main -npm install -npm run dev +### Google Antigravity +Give it the repo URL. It can clone and work autonomously. +Use: `https://git.beletage.ro/gitadmin/ArchiTools.git` + +### Phone (ChatGPT app, Claude app) +Can't run code directly, but can read files via raw URLs and give guidance: ``` - -### After completing work (push) -```bash -npx next build # MUST pass with zero errors -git add # never git add -A -git commit -m "feat(module): description - -Co-Authored-By: " -git push origin main # auto-deploys to http://10.10.10.166:3000 +Read these URLs and help me plan the next task: +https://git.beletage.ro/gitadmin/ArchiTools/raw/branch/main/CLAUDE.md +https://git.beletage.ro/gitadmin/ArchiTools/raw/branch/main/ROADMAP.md +https://git.beletage.ro/gitadmin/ArchiTools/raw/branch/main/SESSION-LOG.md ``` --- -## Files to Keep Updated After Every Session +## Git Workflow -### 1. `ROADMAP.md` — Mark completed tasks +### First time (any device) +```bash +git clone https://git.beletage.ro/gitadmin/ArchiTools.git +cd ArchiTools +npm install +npm run dev +``` +### Session start (pull latest) +```bash +git pull origin main +npm install +``` + +### Session end (push) +```bash +npx next build +git add +git commit -m "feat(module): description + +Co-Authored-By: " +git push origin main +``` + +--- + +## Files to Update After Every Session + +### 1. `ROADMAP.md` — Mark done tasks ```markdown ### 1.01 ✅ (2026-02-18) `[LIGHT]` Verify Email Signature Logo Files ``` ### 2. `SESSION-LOG.md` — Add entry at the TOP - ```markdown ## Session — 2026-02-18 (Sonnet 4.6) ### Completed -- 1.01: Verified logo files, created placeholders for US/SDT -- 1.02: Added address toggle for Urban Switch +- 1.01: Verified logo files +- 1.02: Added address toggle ### In Progress -- 1.03: Prompt Generator templates — 4 of 10 done +- 1.03: Prompt templates — 4 of 10 done ### Blockers -- Need US/SDT logo files from user +- Need logo files from user ### Notes -- Build passes, pushed commit abc1234 +- Build passes, commit abc1234 --- ``` ### 3. `CLAUDE.md` — Only if architecture changes -Update when: new module added, core system changed, new conventions, new TS gotchas. - -### 4. `ROADMAP.md` — Add new tasks if discovered during work - -```markdown -### 1.14 `[LIGHT]` Fix z-index on color picker (discovered during 1.02) -``` +### 4. Commit + push all log updates before ending the session --- -## Tips for Smooth Handoffs +## Handoff Rules 1. **Always pull before starting** — another session may have pushed 2. **Always push before ending** — don't leave uncommitted work -3. **Update SESSION-LOG.md** — the next AI has no memory of this session -4. **Mark tasks in ROADMAP.md** — ✅ with date is the source of truth -5. **Don't skip tasks** — they're ordered by dependency -6. **Ask the user if blocked** — don't guess on design decisions +3. **Update SESSION-LOG.md** — the next AI has zero memory +4. **Mark ROADMAP.md** — ✅ with date is the source of truth +5. **Don't skip tasks** — ordered by dependency +6. **Ask user if blocked** — don't guess on design decisions 7. **One task at a time** — implement, build, push, get approval, then next -8. **Commit messages** — `feat(module):`, `fix(module):`, `docs:`