ArchiTools/SESSION-GUIDE.md

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)

git clone http://10.10.10.166:3002/gitadmin/ArchiTools.git
cd ArchiTools
npm install
npm run dev

Every session start (pull latest)

git pull origin main
npm install          # in case dependencies changed
npm run dev

After completing work (push)

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

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:

### 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):

## 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:

### 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:

# 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: