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 | | Access | Git Clone URL | Web UI |
|---|---|
| **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 | | **Internal (office)** | `http://10.10.10.166:3002/gitadmin/ArchiTools.git` | http://10.10.10.166:3002/gitadmin/ArchiTools |
| `ROADMAP.md` | Complete task list — tasks with ✅ are done, others are pending | Every session start | | **External (internet)** | `https://git.beletage.ro/gitadmin/ArchiTools.git` | https://git.beletage.ro/gitadmin/ArchiTools |
| `SESSION-LOG.md` | What was done in each previous session | Every session start |
| `SESSION-GUIDE.md` | This file — prompts, workflow, rules | First time only | ### 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 ## PROMPT 1: New Session (any device, any AI)
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. I'm working on ArchiTools, an internal web dashboard for an architecture office.
Repo: http://10.10.10.166:3002/gitadmin/ArchiTools (branch: main) Repository: https://git.beletage.ro/gitadmin/ArchiTools.git (branch: main)
Local path: /Users/mariustarau/Development/ArchiTools
Read these files from the repo root first (in this order): Before doing anything, read these 4 files from the repo:
1. /Users/mariustarau/Development/ArchiTools/CLAUDE.md — project context, stack, architecture - CLAUDE.md (project context, stack, architecture, conventions)
2. /Users/mariustarau/Development/ArchiTools/ROADMAP.md — task list (tasks with ✅ are done, pick the next one without ✅) - ROADMAP.md (complete task list — tasks with ✅ are done, pick the next one without ✅)
3. /Users/mariustarau/Development/ArchiTools/SESSION-LOG.md — what previous sessions did - SESSION-LOG.md (what previous sessions did)
4. /Users/mariustarau/Development/ArchiTools/SESSION-GUIDE.md — workflow rules - SESSION-GUIDE.md (workflow rules)
Start by running: git pull origin main && npm install Setup: clone the repo (or pull latest if already cloned), run npm install.
Then pick the next uncompleted task from ROADMAP.md (top to bottom, skip ✅ tasks).
Then pick the next uncompleted task from ROADMAP.md (work top to bottom, skip ✅ tasks).
Rules: Rules:
- Run `npx next build` before every commit (zero errors required) - 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) - Push to main when done — Portainer auto-deploys to production
- Update ROADMAP.md: mark completed tasks with ✅ and date - Update ROADMAP.md: mark completed tasks with ✅ and the date
- Update SESSION-LOG.md: add entry at the TOP with what you did - Update SESSION-LOG.md: add an entry at the TOP describing what you did
- Notify me when a module/task is ready for my review on http://10.10.10.166:3000 - 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 - 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. I'm continuing work on ArchiTools.
Repo: http://10.10.10.166:3002/gitadmin/ArchiTools (branch: main) Repository: https://git.beletage.ro/gitadmin/ArchiTools.git (branch: main)
Local path: /Users/mariustarau/Development/ArchiTools
Read these files first: Read these files from the repo:
1. /Users/mariustarau/Development/ArchiTools/CLAUDE.md — project context - CLAUDE.md (project context)
2. /Users/mariustarau/Development/ArchiTools/ROADMAP.md — find the next task without ✅ - ROADMAP.md (find the next task without ✅)
3. /Users/mariustarau/Development/ArchiTools/SESSION-LOG.md — see what was done before - SESSION-LOG.md (what was done in previous sessions)
Run: git pull origin main && npm install Pull latest, npm install, then continue with the next uncompleted task.
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, Same rules: build must pass, push when done, update ROADMAP.md (✅ + date)
notify me for review on http://10.10.10.166:3000 before moving to next task. 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. 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 Read CLAUDE.md and ROADMAP.md from the repo first.
/Users/mariustarau/Development/ArchiTools/ROADMAP.md first. Pull latest, npm install.
Run: git pull origin main && npm install Work on task [NUMBER] ([TASK NAME]) from ROADMAP.md.
Then work on task [NUMBER] ([TASK NAME]) from ROADMAP.md.
Implement it, run `npx next build` (must pass), push to main, Implement it, run `npx next build` (must pass), push to main,
update ROADMAP.md (✅ + date) and SESSION-LOG.md, then notify me. 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. 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 Bug: [DESCRIBE THE BUG]
There's a bug: [DESCRIBE THE BUG].
Investigate, fix it, run `npx next build`, push to main. Fix it, run `npx next build`, push to main.
Don't change anything unrelated to the bug. Don't change anything unrelated. Update SESSION-LOG.md.
Update SESSION-LOG.md with what you fixed.
``` ```
--- ---
## Prompt: Code Review (no changes) ## PROMPT 5: Code Review (no changes)
``` ```
I'm working on ArchiTools. 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. Check for:
Review the last 3 commits on main. Check for:
- TypeScript strict mode issues - TypeScript strict mode issues
- Missing null guards on Record/array access - Missing null guards
- UI text that should be in Romanian - UI text that should be in Romanian
- Unused imports or dead code - Unused imports or dead code
- Security issues (XSS, injection) - Security issues
Don't change anything, just report findings. Don't change anything, just report findings.
``` ```
--- ---
## Prompt: New Module from Scratch ## PROMPT 6: New Module from Scratch
``` ```
I'm working on ArchiTools. 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 Read CLAUDE.md and ROADMAP.md from the repo first.
/Users/mariustarau/Development/ArchiTools/ROADMAP.md first. Pull latest, npm install.
Run: git pull origin main && npm install Build [MODULE NAME] as described in task [NUMBER] of ROADMAP.md.
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/ Use the module at src/modules/registratura/ as reference for the pattern:
as reference. Follow the same structure:
types.ts, config.ts, services/, hooks/, components/, index.ts types.ts, config.ts, services/, hooks/, components/, index.ts
Also create: Also create: route page, update modules.ts, navigation.ts, flags.ts.
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. 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 ```bash
git clone http://10.10.10.166:3002/gitadmin/ArchiTools.git git clone https://git.beletage.ro/gitadmin/ArchiTools.git
cd ArchiTools cd ArchiTools && npm install && code .
npm install
npm run dev # http://localhost:3000
``` ```
### Every session start (pull) ### Google Antigravity
```bash Give it the repo URL. It can clone and work autonomously.
cd /Users/mariustarau/Development/ArchiTools Use: `https://git.beletage.ro/gitadmin/ArchiTools.git`
git pull origin main
npm install ### Phone (ChatGPT app, Claude app)
npm run dev Can't run code directly, but can read files via raw URLs and give guidance:
``` ```
Read these URLs and help me plan the next task:
### After completing work (push) https://git.beletage.ro/gitadmin/ArchiTools/raw/branch/main/CLAUDE.md
```bash https://git.beletage.ro/gitadmin/ArchiTools/raw/branch/main/ROADMAP.md
npx next build # MUST pass with zero errors https://git.beletage.ro/gitadmin/ArchiTools/raw/branch/main/SESSION-LOG.md
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 ## 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 ```markdown
### 1.01 ✅ (2026-02-18) `[LIGHT]` Verify Email Signature Logo Files ### 1.01 ✅ (2026-02-18) `[LIGHT]` Verify Email Signature Logo Files
``` ```
### 2. `SESSION-LOG.md` — Add entry at the TOP ### 2. `SESSION-LOG.md` — Add entry at the TOP
```markdown ```markdown
## Session — 2026-02-18 (Sonnet 4.6) ## Session — 2026-02-18 (Sonnet 4.6)
### Completed ### Completed
- 1.01: Verified logo files, created placeholders for US/SDT - 1.01: Verified logo files
- 1.02: Added address toggle for Urban Switch - 1.02: Added address toggle
### In Progress ### In Progress
- 1.03: Prompt Generator templates — 4 of 10 done - 1.03: Prompt templates — 4 of 10 done
### Blockers ### Blockers
- Need US/SDT logo files from user - Need logo files from user
### Notes ### Notes
- Build passes, pushed commit abc1234 - Build passes, commit abc1234
--- ---
``` ```
### 3. `CLAUDE.md` — Only if architecture changes ### 3. `CLAUDE.md` — Only if architecture changes
Update when: new module added, core system changed, new conventions, new TS gotchas. ### 4. Commit + push all log updates before ending the session
### 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 ## Handoff Rules
1. **Always pull before starting** — another session may have pushed 1. **Always pull before starting** — another session may have pushed
2. **Always push before ending** — don't leave uncommitted work 2. **Always push before ending** — don't leave uncommitted work
3. **Update SESSION-LOG.md** — the next AI has no memory of this session 3. **Update SESSION-LOG.md** — the next AI has zero memory
4. **Mark tasks in ROADMAP.md** — ✅ with date is the source of truth 4. **Mark ROADMAP.md** — ✅ with date is the source of truth
5. **Don't skip tasks** — they're ordered by dependency 5. **Don't skip tasks** — ordered by dependency
6. **Ask the user if blocked** — don't guess on design decisions 6. **Ask user if blocked** — don't guess on design decisions
7. **One task at a time** — implement, build, push, get approval, then next 7. **One task at a time** — implement, build, push, get approval, then next
8. **Commit messages** — `feat(module):`, `fix(module):`, `docs:`