Toju/AGENTS.md

AGENTS.md

Keep this file small. Detail lives in linked docs — load those only when the task needs them.

Session handoff (new chats)

Agents cannot open a new Cursor chat. To reset context:

1. Write/update agents-docs/HANDOFF.md (Status: active) — see .cursor/rules/handoff.mdc.
2. Ask the user to start a new chat and attach @agents-docs/HANDOFF.md.

At session start: if agents-docs/HANDOFF.md has Status: active, read it first and continue Next steps. Do not redo Completed work.

Default work scope (token fence)

Unless the user explicitly expands scope, stay inside:

• toju-app/ (primary)
• electron/ — targeted only (desktop shell is coupled to the client; see below)
• CI: .gitea/workflows/
• Agent/docs as needed: this file, agents-docs/ (index-first / handoff), toju-app/CONTEXT.md; electron/CONTEXT.md only when touching Electron

Electron — relevant files only

electron/ is in default scope because the renderer talks to it via preload/IPC/local DB. Do not browse the whole tree.

When a toju-app change needs the desktop bridge:

1. Start from the renderer call site (window.api / Electron bridge usage).
2. Open only the matching surface: usually electron/preload.ts, then the specific handler under electron/ipc/, electron/cqrs*, or the one module/entity/migration involved.
3. Prefer ripgrep with path electron/ + a concrete symbol over listing directories.
4. Skip unrelated areas (electron/api/ docs server, game-detection/, update/, other migrations, etc.) unless the bug points there.

Still out of scope by default (do not search/read/edit unless the user names them):

• server/, e2e/, website/, docs-site/
• Root noise: dist*/, node_modules/, images/, project-files/, test-results/

If the root cause looks like server/ or e2e-only, ask once instead of exploring those trees.

Search with path filters. Prefer toju-app/src/app/domains/<name>/ over repo-wide greps.

Session start (cheap bootstrap)

1. Skim this file.
2. If handoff Status: active → read agents-docs/HANDOFF.md.
3. Open agents-docs/LESSONS-INDEX.md only — match tags; open matching bodies in LESSONS.md.
4. Read toju-app/CONTEXT.md for client work; electron/CONTEXT.md only if this task touches Electron.
5. Other docs on demand only.

Models: use the latest problem-solving model the user selected. Save tokens with scope, handoffs, and short chats — not by silently downgrading model quality.

Do not auto-read: ENGINEERING.md, AGENTS_FEATURES.md, FEATURES.md, CONTEXT-MAP.md, full AGENT_WORKFLOW.md, feature docs, ADRs — unless needed.

On-demand: agents-docs/AGENT_WORKFLOW.md, AGENTS_FEATURES.md, FEATURES.md, ENGINEERING.md, AGENTS_CONTEXT.md, AGENTS_ADRS.md, BUG_TRACKER.md.

---

MetoYou / Toju: desktop-first P2P chat. Default surface: Angular client (toju-app/) + targeted Electron bridge + CI.

CRITICAL — Done means the asked behavior works

Unit/spec green is support, not done.

1. Restate acceptance in one sentence.
2. Prove the behavior (user-visible path, focused test at the right level, or explicit manual check).
3. Prefer a regression that fails if the asked behavior regresses.

Test-backed development (balanced)

For domain/logic: failing behavior-level test → minimal fix → green.
Skip full red-green for docs/copy/agent text, formatting, trivial wiring already covered higher up.

Do not: ship implementation-shaped mocks as the feature; stop at unit-green for product asks; run full monorepo / full e2e on every tiny change — targeted specs first.

Lint / type correctness (scoped)

1. Targeted Vitest under toju-app/ (and colocated Electron specs only if you changed those files).
2. npm run lint — fix errors; do not paste entire lint logs into the chat.
3. npm run build when client types/templates could break; npm run build:electron only if you changed Electron sources.

Do not run cd server && npm run build or npm run test:e2e unless scope expanded or the bug is proven there.

Feature docs

Internal domain changes → toju-app/src/app/domains/<name>/README.md.
IPC/preload/WS contract changes → agents-docs/features/<slug>.md when that contract actually changed.

Completion checklist

• Asked behavior proven (not only unit tests green)
• Stayed in scope (toju-app + targeted electron + CI) unless user expanded it
• Appropriate targeted tests for logic changes
• Lint/build only for touched packages
• Docs only if contracts changed
• Lesson + index entry if corrected this session
• If the thread is long and work remains: write HANDOFF.md and ask user for a new chat
• PR when requesting merge (Fixes #<n> / Relates to #<n>)