From f6fd5f58e3f70918eec9ec2d1f683e52d7bf5338 Mon Sep 17 00:00:00 2001 From: Marius Tarau Date: Wed, 18 Feb 2026 19:11:06 +0200 Subject: [PATCH] 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 --- SESSION-GUIDE.md | 231 +++++++++++++++++++++++++++++++++++++++++++++++ SESSION-LOG.md | 31 +++++++ 2 files changed, 262 insertions(+) create mode 100644 SESSION-GUIDE.md create mode 100644 SESSION-LOG.md diff --git a/SESSION-GUIDE.md b/SESSION-GUIDE.md new file mode 100644 index 0000000..bdce0e0 --- /dev/null +++ b/SESSION-GUIDE.md @@ -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 # never git add -A (avoid secrets) +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 +``` + +--- + +## 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:` diff --git a/SESSION-LOG.md b/SESSION-LOG.md new file mode 100644 index 0000000..57ff165 --- /dev/null +++ b/SESSION-LOG.md @@ -0,0 +1,31 @@ +# ArchiTools — Session Log + +> Newest sessions first. Each AI session appends an entry at the top. + +--- + +## Session — 2026-02-18 (Claude Opus 4.6) + +### Completed +- **Registratura Legal Deadline Tracking** — Full implementation: + - 9 new files: working-days.ts (Romanian holidays + Orthodox Easter), deadline-catalog.ts (16 deadline types), deadline-service.ts, use-deadline-filters.ts, deadline-card.tsx, deadline-add-dialog.tsx, deadline-resolve-dialog.tsx, deadline-table.tsx, deadline-dashboard.tsx + - 6 modified files: types.ts, use-registry.ts, registratura-module.tsx (tabbed), registry-entry-form.tsx (inline deadlines), registry-table.tsx (clock badge), index.ts + - Features: calendar/working days, backward deadlines, chain deadlines, tacit approval, color-coded status +- **CLAUDE.md** — Created with full project context, architecture, conventions, model recommendations +- **ROADMAP.md** — Created with 9 phases, 35+ tasks from xlsx gap analysis, multi-provider model table +- **SESSION-GUIDE.md** — Created with start/resume prompts, git workflow, file update rules + +### Commits +- `bb01268` feat(registratura): add legal deadline tracking system (Termene Legale) +- `d6a5852` docs: add ROADMAP.md with detailed future task plan +- `b1df15b` docs: rewrite ROADMAP.md with complete xlsx gap analysis + multi-model recommendations +- (this session) docs: add SESSION-GUIDE.md + SESSION-LOG.md + +### Notes +- Build passes with zero errors +- Dev server on localhost:3000 shows tabs correctly +- Production at 10.10.10.166:3000 requires Portainer redeploy after push +- The `app_modules_overview.xlsx` is in the repo root but not committed (it's a reference file) +- No tasks from ROADMAP.md Phase 1+ have been started yet — next session should begin with task 1.01 + +---