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. Overwrite agents-docs/HANDOFF.md entirely (Status: active) — never append. See .cursor/rules/handoff.mdc.
2. Ask the user to start a new chat and attach @agents-docs/HANDOFF.md.

At session start: if Status: active, read it first and continue Next steps. Do not redo Completed work.

When the task is finished: clear the handoff — set Status: none and empty all sections (same short template). Never leave a growing archive in HANDOFF.md.

Named Obsidian bugs

When the user says fix bug "…", follow agents-docs/BUG_TRACKER.md § Named fix: open that one vault note, interview before implementing, then fix in default scope and set status: Resolved. Do not scan the whole bug inbox.

Interview before implement (user in control)

Before changing product code for a bug or feature:

1. Read the ask / named bug note (cheap orientation only — not a monorepo dig).
2. Post a short interview: your understanding, gaps, A/B/C choices with a recommended default, proposed scope, how you’ll prove done.
3. Wait for the user’s choices. Do not guess past ambiguity.
4. Implement only what they approved.

Skip only if they say “just fix it” / “no interview”, or an active handoff already has approved decisions and they said continue. See .cursor/rules/interview-before-fix.mdc.

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. Auto-fix style first: npm run lint:fix from repo root (format + sort:props + eslint . --fix). Do not hand-edit formatting/import-sort/eslint-fixable issues — re-run lint:fix. Then confirm clean with npm run lint only if you need a no-write check; prefer trusting lint:fix exit 0.
3. Do not paste entire lint logs into the chat — fix via lint:fix / minimal code changes for non-auto issues.
4. 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

• Interview completed (or user opted out); implemented only approved choices
• 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 via npm run lint:fix (not hand-fixed style); build only touched packages
• Docs only if contracts changed
• Lesson + index entry if corrected this session
• If the thread is long and work remains: overwrite HANDOFF.md and ask user for a new chat
• If work from an active handoff is finished: clear HANDOFF.md to Status: none (empty sections)
• PR when requesting merge (Fixes #<n> / Relates to #<n>)