gitadmin/ArchiTools
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: make SESSION-GUIDE.md device-agnostic with Gitea URLs

Browse Source 
All prompts now use repo URL instead of local paths.
Works from any device: Mac, PC, phone, any AI tool.
Two access points: internal (10.10.10.166:3002) and external (git.beletage.ro).
Added tool-specific notes for Claude Code, ChatGPT Codex, Copilot, Cursor, Antigravity, phone.
Raw file URLs for AI tools that can fetch web content.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Marius Tarau
2026-02-18 19:34:49 +02:00
parent 9904804097
commit 501de5161e
1 changed files with 135 additions and 121 deletions
Download Patch File Download Diff File Expand all files Collapse all files

256
SESSION-GUIDE.md
View File

@@ -1,94 +1,93 @@
# ArchiTools — Session Guide for AI Assistants
# ArchiTools — Session Guide
> How to start, resume, and hand off coding sessions. Keep this file updated.
> Device-agnostic prompts for any AI tool, from anywhere.
---
## Project Location
## Repository URLs
| 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 |
| Access | Git Clone URL | Web UI |
|---|---|---|
| `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 |
| **Internal (office)** | `http://10.10.10.166:3002/gitadmin/ArchiTools.git` | http://10.10.10.166:3002/gitadmin/ArchiTools |
| **External (internet)** | `https://git.beletage.ro/gitadmin/ArchiTools.git` | https://git.beletage.ro/gitadmin/ArchiTools |
### Raw File URLs (for AI tools that can fetch URLs)
Replace `{GITEA}` with whichever base works for you:
- Internal: `http://10.10.10.166:3002`
- External: `https://git.beletage.ro`
| File | URL |
|---|---|
| CLAUDE.md | `{GITEA}/gitadmin/ArchiTools/raw/branch/main/CLAUDE.md` |
| ROADMAP.md | `{GITEA}/gitadmin/ArchiTools/raw/branch/main/ROADMAP.md` |
| SESSION-LOG.md | `{GITEA}/gitadmin/ArchiTools/raw/branch/main/SESSION-LOG.md` |
| SESSION-GUIDE.md | `{GITEA}/gitadmin/ArchiTools/raw/branch/main/SESSION-GUIDE.md` |
**Production app:** http://10.10.10.166:3000
---
## Prompt: Starting a Brand New Session
Copy-paste this to any AI coding assistant (Claude Code, Cursor, Windsurf, Copilot, etc.):
## PROMPT 1: New Session (any device, any AI)
```
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
Repository: https://git.beletage.ro/gitadmin/ArchiTools.git (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
Before doing anything, read these 4 files from the repo:
- CLAUDE.md (project context, stack, architecture, conventions)
- ROADMAP.md (complete task list — tasks with ✅ are done, pick the next one without ✅)
- SESSION-LOG.md (what previous sessions did)
- 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).
Setup: clone the repo (or pull latest if already cloned), run npm install.
Then pick the next uncompleted task from ROADMAP.md (work 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
- Run `npx next build` before every commit — zero errors required
- Push to main when done — Portainer auto-deploys to production
- Update ROADMAP.md: mark completed tasks with ✅ and the date
- Update SESSION-LOG.md: add an entry at the TOP describing what you did
- Commit and push these log updates too
- Notify me when a 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
- Code in English, UI text in Romanian
```
---
## Prompt: Resuming Where You Left Off
## PROMPT 2: Resume Previous Work
```
I'm continuing work on ArchiTools.
Repo: http://10.10.10.166:3002/gitadmin/ArchiTools (branch: main)
Local path: /Users/mariustarau/Development/ArchiTools
Repository: https://git.beletage.ro/gitadmin/ArchiTools.git (branch: main)
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
Read these files from the repo:
- CLAUDE.md (project context)
- ROADMAP.md (find the next task without ✅)
- SESSION-LOG.md (what was done in previous sessions)
Run: git pull origin main && npm install
Then continue with the next uncompleted task from ROADMAP.md.
Pull latest, npm install, then continue with the next uncompleted task.
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.
Same rules: build must pass, push when done, update ROADMAP.md (✅ + date)
and SESSION-LOG.md, notify me for review before moving to next task.
```
---
## Prompt: Specific Task
## PROMPT 3: Specific Task
```
I'm working on ArchiTools.
Local path: /Users/mariustarau/Development/ArchiTools
Repository: https://git.beletage.ro/gitadmin/ArchiTools.git (branch: main)
Read /Users/mariustarau/Development/ArchiTools/CLAUDE.md and
/Users/mariustarau/Development/ArchiTools/ROADMAP.md first.
Read CLAUDE.md and ROADMAP.md from the repo first.
Pull latest, npm install.
Run: git pull origin main && npm install
Then work on task [NUMBER] ([TASK NAME]) from ROADMAP.md.
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.
@@ -96,145 +95,160 @@ update ROADMAP.md (✅ + date) and SESSION-LOG.md, then notify me.
---
## Prompt: Bug Fix
## PROMPT 4: Bug Fix
```
I'm working on ArchiTools.
Local path: /Users/mariustarau/Development/ArchiTools
Repository: https://git.beletage.ro/gitadmin/ArchiTools.git (branch: main)
Read /Users/mariustarau/Development/ArchiTools/CLAUDE.md first.
Read CLAUDE.md from the repo first. Pull latest.
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.
Bug: [DESCRIBE THE BUG]
Fix it, run `npx next build`, push to main.
Don't change anything unrelated. Update SESSION-LOG.md.
```
---
## Prompt: Code Review (no changes)
## PROMPT 5: Code Review (no changes)
```
I'm working on ArchiTools.
Local path: /Users/mariustarau/Development/ArchiTools
Repository: https://git.beletage.ro/gitadmin/ArchiTools.git (branch: main)
Read /Users/mariustarau/Development/ArchiTools/CLAUDE.md first.
Read CLAUDE.md from the repo. Pull latest.
Run: git pull origin main
Review the last 3 commits on main. Check for:
Review the last 3 commits. Check for:
- TypeScript strict mode issues
- Missing null guards on Record/array access
- Missing null guards
- UI text that should be in Romanian
- Unused imports or dead code
- Security issues (XSS, injection)
- Security issues
Don't change anything, just report findings.
```
---
## Prompt: New Module from Scratch
## PROMPT 6: New Module from Scratch
```
I'm working on ArchiTools.
Local path: /Users/mariustarau/Development/ArchiTools
Repository: https://git.beletage.ro/gitadmin/ArchiTools.git (branch: main)
Read /Users/mariustarau/Development/ArchiTools/CLAUDE.md and
/Users/mariustarau/Development/ArchiTools/ROADMAP.md first.
Read CLAUDE.md and ROADMAP.md from the repo first.
Pull latest, npm install.
Run: git pull origin main && npm install
I want to build [MODULE NAME] as described in task [NUMBER] of ROADMAP.md.
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:
Use the module at src/modules/registratura/ as reference for the pattern:
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
Also create: route page, update modules.ts, navigation.ts, flags.ts.
Run `npx next build`, push to main, update ROADMAP.md + SESSION-LOG.md, notify me.
```
---
## Git Workflow
## Tool-Specific Notes
### First time (clone)
### Claude Code (CLI)
Works natively. Clone/pull, read files, edit, build, push — all built in.
### ChatGPT Codex
Give it the repo URL. It can clone via git, read files, and push.
Use the external URL: `https://git.beletage.ro/gitadmin/ArchiTools.git`
### VS Code + Copilot / Cursor / Windsurf
Clone the repo locally first, then open in the IDE. The AI agent reads files from disk.
```bash
git clone http://10.10.10.166:3002/gitadmin/ArchiTools.git
cd ArchiTools
npm install
npm run dev # http://localhost:3000
git clone https://git.beletage.ro/gitadmin/ArchiTools.git
cd ArchiTools && npm install && code .
```
### Every session start (pull)
```bash
cd /Users/mariustarau/Development/ArchiTools
git pull origin main
npm install
npm run dev
### Google Antigravity
Give it the repo URL. It can clone and work autonomously.
Use: `https://git.beletage.ro/gitadmin/ArchiTools.git`
### Phone (ChatGPT app, Claude app)
Can't run code directly, but can read files via raw URLs and give guidance:
```
### 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
Read these URLs and help me plan the next task:
https://git.beletage.ro/gitadmin/ArchiTools/raw/branch/main/CLAUDE.md
https://git.beletage.ro/gitadmin/ArchiTools/raw/branch/main/ROADMAP.md
https://git.beletage.ro/gitadmin/ArchiTools/raw/branch/main/SESSION-LOG.md
```
---
## Files to Keep Updated After Every Session
## Git Workflow
### 1. `ROADMAP.md` — Mark completed tasks
### First time (any device)
```bash
git clone https://git.beletage.ro/gitadmin/ArchiTools.git
cd ArchiTools
npm install
npm run dev
```
### Session start (pull latest)
```bash
git pull origin main
npm install
```
### Session end (push)
```bash
npx next build
git add <specific-files>
git commit -m "feat(module): description
Co-Authored-By: <model-name>"
git push origin main
```
---
## Files to Update After Every Session
### 1. `ROADMAP.md` — Mark done 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
- 1.01: Verified logo files
- 1.02: Added address toggle
### In Progress
- 1.03: Prompt Generator templates — 4 of 10 done
- 1.03: Prompt templates — 4 of 10 done
### Blockers
- Need US/SDT logo files from user
- Need logo files from user
### Notes
- Build passes, pushed commit abc1234
- Build passes, 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)
```
### 4. Commit + push all log updates before ending the session
---
## Tips for Smooth Handoffs
## Handoff Rules
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
3. **Update SESSION-LOG.md** — the next AI has zero memory
4. **Mark ROADMAP.md** — ✅ with date is the source of truth
5. **Don't skip tasks** — ordered by dependency
6. **Ask 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:`