diff --git a/SESSION-GUIDE.md b/SESSION-GUIDE.md index bdce0e0..9d30289 100644 --- a/SESSION-GUIDE.md +++ b/SESSION-GUIDE.md @@ -4,145 +4,223 @@ --- -## Starting a Brand New Session +## Project Location -Copy-paste this prompt to any AI coding assistant (Claude Code, Cursor, Windsurf, Copilot, etc.): +| 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 | +|---|---|---| +| `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 | + +--- + +## Prompt: Starting a Brand New Session + +Copy-paste this to any AI coding assistant (Claude Code, Cursor, Windsurf, Copilot, etc.): ``` I'm working on ArchiTools, an internal web dashboard for an architecture office. -Read these files first (in this order): -1. CLAUDE.md — full project context, stack, architecture, conventions -2. ROADMAP.md — complete task list with phases, dependencies, model recommendations -3. SESSION-GUIDE.md — this file, session workflow +Repo: http://10.10.10.166:3002/gitadmin/ArchiTools (branch: main) +Local path: /Users/mariustarau/Development/ArchiTools -The repo is at: http://10.10.10.166:3002/gitadmin/ArchiTools (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 -Start by pulling the latest code, then pick the next uncompleted task from ROADMAP.md -(tasks are ordered by priority — work top to bottom). +Start by running: git pull origin main && npm install +Then pick the next uncompleted task from ROADMAP.md (top to bottom, skip ✅ tasks). Rules: - Run `npx next build` before every commit (zero errors required) -- Push to main when done (Portainer auto-deploys) +- 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 with what you did -- Notify me when a module/task is ready for my review +- 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 - Do NOT move to the next task until I approve the current one - Code in English, UI in Romanian ``` --- -## Resuming Where You Left Off - -Copy-paste this prompt when continuing from a previous session: +## Prompt: Resuming Where You Left Off ``` I'm continuing work on ArchiTools. +Repo: http://10.10.10.166:3002/gitadmin/ArchiTools (branch: main) +Local path: /Users/mariustarau/Development/ArchiTools + Read these files first: -1. CLAUDE.md — project context -2. ROADMAP.md — find the next uncompleted task (no ✅) -3. SESSION-LOG.md — see what was done in previous sessions +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 -Pull latest from main first: git pull origin main - -Then continue with the next task from ROADMAP.md. +Run: git pull origin main && npm install +Then continue with the next uncompleted task from ROADMAP.md. Same rules: build must pass, push when done, update ROADMAP.md and SESSION-LOG.md, -notify me when ready for review. +notify me for review on http://10.10.10.166:3000 before moving to next task. ``` --- -## Git Workflow (Pull / Push from Gitea) +## Prompt: Specific Task -### First time setup (clone) +``` +I'm working on ArchiTools. +Local path: /Users/mariustarau/Development/ArchiTools + +Read /Users/mariustarau/Development/ArchiTools/CLAUDE.md and +/Users/mariustarau/Development/ArchiTools/ROADMAP.md first. + +Run: git pull origin main && npm install +Then 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. +``` + +--- + +## Prompt: Bug Fix + +``` +I'm working on ArchiTools. +Local path: /Users/mariustarau/Development/ArchiTools + +Read /Users/mariustarau/Development/ArchiTools/CLAUDE.md first. + +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. +``` + +--- + +## Prompt: Code Review (no changes) + +``` +I'm working on ArchiTools. +Local path: /Users/mariustarau/Development/ArchiTools + +Read /Users/mariustarau/Development/ArchiTools/CLAUDE.md first. + +Run: git pull origin main +Review the last 3 commits on main. Check for: +- TypeScript strict mode issues +- Missing null guards on Record/array access +- UI text that should be in Romanian +- Unused imports or dead code +- Security issues (XSS, injection) +Don't change anything, just report findings. +``` + +--- + +## Prompt: New Module from Scratch + +``` +I'm working on ArchiTools. +Local path: /Users/mariustarau/Development/ArchiTools + +Read /Users/mariustarau/Development/ArchiTools/CLAUDE.md and +/Users/mariustarau/Development/ArchiTools/ROADMAP.md first. + +Run: git pull origin main && npm install +I want to 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: + 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 + +Run `npx next build`, push to main, update ROADMAP.md + SESSION-LOG.md, notify me. +``` + +--- + +## Git Workflow + +### First time (clone) ```bash git clone http://10.10.10.166:3002/gitadmin/ArchiTools.git cd ArchiTools npm install -npm run dev +npm run dev # http://localhost:3000 ``` -### Every session start (pull latest) +### Every session start (pull) ```bash +cd /Users/mariustarau/Development/ArchiTools git pull origin main -npm install # in case dependencies changed +npm install npm run dev ``` ### After completing work (push) ```bash npx next build # MUST pass with zero errors -git add # never git add -A (avoid secrets) +git add # never git add -A git commit -m "feat(module): description Co-Authored-By: " -git push origin main # triggers Portainer auto-deploy -``` - -### If working from a different machine -```bash -git clone http://10.10.10.166:3002/gitadmin/ArchiTools.git -cd ArchiTools -npm install -# read CLAUDE.md, ROADMAP.md, SESSION-LOG.md -# continue working +git push origin main # auto-deploys to http://10.10.10.166:3000 ``` --- -## Files to Keep Updated +## Files to Keep Updated After Every Session -### After EVERY session, update these files: - -#### 1. `ROADMAP.md` — Mark completed tasks - -When a task is done and approved by the user, add ✅ and the date: +### 1. `ROADMAP.md` — Mark completed tasks ```markdown ### 1.01 ✅ (2026-02-18) `[LIGHT]` Verify Email Signature Logo Files ``` -This is how the next session knows where to pick up. - -#### 2. `SESSION-LOG.md` — Append a session entry - -Add a new entry at the TOP of the file (newest first): +### 2. `SESSION-LOG.md` — Add entry at the TOP ```markdown -## Session — 2026-02-18 (Opus 4.6) +## 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 ### In Progress -- 1.03: Prompt Generator templates — 4 of 10 done, paused for user feedback +- 1.03: Prompt Generator templates — 4 of 10 done ### Blockers -- Need US/SDT logo files from user (task 1.01) +- Need US/SDT logo files from user ### Notes -- Discovered that `signature-configurator.tsx` has a z-index issue on the color picker - Build passes, pushed commit abc1234 - --- ``` -#### 3. `CLAUDE.md` — Update if architecture changes +### 3. `CLAUDE.md` — Only if architecture changes -Only update when: -- A new module is added (add to the module table) -- A core system changes (storage, auth, etc.) -- New conventions are established -- New TypeScript gotchas are discovered +Update when: new module added, core system changed, new conventions, new TS gotchas. -#### 4. `ROADMAP.md` — Add new tasks if discovered - -During implementation you may find bugs or missing features not in the xlsx. -Add them to the appropriate phase with a note: +### 4. `ROADMAP.md` — Add new tasks if discovered during work ```markdown ### 1.14 `[LIGHT]` Fix z-index on color picker (discovered during 1.02) @@ -150,82 +228,13 @@ Add them to the appropriate phase with a note: --- -## Session Log Template - -Create `SESSION-LOG.md` if it doesn't exist: - -```markdown -# ArchiTools — Session Log - -> Newest sessions first. Each AI session appends an entry here. - ---- - -## Session — YYYY-MM-DD (Model Name) - -### Completed -- Task X.XX: Description of what was done - -### In Progress -- Task X.XX: What's partially done, where it stopped - -### Blockers -- What's needed from the user - -### Notes -- Anything useful for the next session - ---- -``` - ---- - -## Prompt Variants - -### For a specific task -``` -I'm working on ArchiTools. Read CLAUDE.md and ROADMAP.md. -I want to work on task 1.05 (Mini Utilities — Add Missing Tools). -Pull latest, implement it, build, push, and notify me when done. -``` - -### For bug fixing -``` -I'm working on ArchiTools. Read CLAUDE.md. -There's a bug: [describe the bug]. -Pull latest, investigate, fix it, build, push. -Don't change anything else. -``` - -### For code review -``` -I'm working on ArchiTools. Read CLAUDE.md. -Review the last commit on main. Check for: -- TypeScript strict mode issues -- Missing null guards -- UI text in Romanian -- Unused imports -Don't change anything, just report findings. -``` - -### For starting a brand new module -``` -I'm working on ArchiTools. Read CLAUDE.md and ROADMAP.md. -I want to build [Module Name] as described in task X.XX. -Read the existing module pattern in src/modules/registratura/ as reference. -Follow the same structure: types.ts, config.ts, services/, hooks/, components/, index.ts. -Build, test, push, notify me. -``` - ---- - ## Tips for Smooth Handoffs -1. **Always pull before starting** — another session may have pushed changes +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 7. **One task at a time** — implement, build, push, get approval, then next -8. **Commit messages follow convention** — `feat(module):`, `fix(module):`, `docs:` +8. **Commit messages** — `feat(module):`, `fix(module):`, `docs:`