docs: add SESSION-GUIDE.md and SESSION-LOG.md for AI session handoffs
SESSION-GUIDE.md: start/resume prompts, git workflow, file update rules SESSION-LOG.md: session history log (newest first) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Marius Tarau
231
SESSION-GUIDE.md
Normal file
231
SESSION-GUIDE.md
Normal file
@@ -0,0 +1,231 @@
|
||||
# ArchiTools — Session Guide for AI Assistants
|
||||
|
||||
> How to start, resume, and hand off coding sessions. Keep this file updated.
|
||||
|
||||
---
|
||||
|
||||
## Starting a Brand New Session
|
||||
|
||||
Copy-paste this prompt 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
|
||||
|
||||
The repo is at: http://10.10.10.166:3002/gitadmin/ArchiTools (branch: main)
|
||||
|
||||
Start by pulling the latest code, then pick the next uncompleted task from ROADMAP.md
|
||||
(tasks are ordered by priority — work top to bottom).
|
||||
|
||||
Rules:
|
||||
- Run `npx next build` before every commit (zero errors required)
|
||||
- Push to main when done (Portainer auto-deploys)
|
||||
- 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
|
||||
- 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:
|
||||
|
||||
```
|
||||
I'm continuing work on 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
|
||||
|
||||
Pull latest from main first: git pull origin main
|
||||
|
||||
Then continue with the next 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.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Git Workflow (Pull / Push from Gitea)
|
||||
|
||||
### First time setup (clone)
|
||||
```bash
|
||||
git clone http://10.10.10.166:3002/gitadmin/ArchiTools.git
|
||||
cd ArchiTools
|
||||
npm install
|
||||
npm run dev
|
||||
```
|
||||
|
||||
### Every session start (pull latest)
|
||||
```bash
|
||||
git pull origin main
|
||||
npm install # in case dependencies changed
|
||||
npm run dev
|
||||
```
|
||||
|
||||
### After completing work (push)
|
||||
```bash
|
||||
npx next build # MUST pass with zero errors
|
||||
git add <changed-files> # never git add -A (avoid secrets)
|
||||
git commit -m "feat(module): description
|
||||
|
||||
Co-Authored-By: <model-name>"
|
||||
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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Files to Keep Updated
|
||||
|
||||
### 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:
|
||||
|
||||
```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):
|
||||
|
||||
```markdown
|
||||
## Session — 2026-02-18 (Opus 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
|
||||
|
||||
### Blockers
|
||||
- Need US/SDT logo files from user (task 1.01)
|
||||
|
||||
### 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
|
||||
|
||||
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
|
||||
|
||||
#### 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:
|
||||
|
||||
```markdown
|
||||
### 1.14 `[LIGHT]` Fix z-index on color picker (discovered during 1.02)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
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:`
|
||||
Reference in New Issue
Block a user