ArchiTools/SESSION-GUIDE.md

# ArchiTools — Session Guide for AI Assistants

> How to start, resume, and hand off coding sessions. Keep this file updated.

---

## Project Location

| 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.

Repo: http://10.10.10.166:3002/gitadmin/ArchiTools (branch: main)
Local path: /Users/mariustarau/Development/ArchiTools

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 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 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
- Do NOT move to the next task until I approve the current one
- Code in English, UI in Romanian
```

---

## 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. /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

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 for review on http://10.10.10.166:3000 before moving to next task.
```

---

## Prompt: Specific Task

```
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    # http://localhost:3000
```

### Every session start (pull)
```bash
cd /Users/mariustarau/Development/ArchiTools
git pull origin main
npm install
npm run dev
```

### After completing work (push)
```bash
npx next build                    # MUST pass with zero errors
git add <specific-files>          # never git add -A
git commit -m "feat(module): description

Co-Authored-By: <model-name>"
git push origin main              # auto-deploys to http://10.10.10.166:3000
```

---

## Files to Keep Updated After Every Session

### 1. `ROADMAP.md` — Mark completed 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

### In Progress
- 1.03: Prompt Generator templates — 4 of 10 done

### Blockers
- Need US/SDT logo files from user

### Notes
- Build passes, pushed 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)
```

---

## Tips for Smooth Handoffs

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** — `feat(module):`, `fix(module):`, `docs:`