chore: cut agent token burn with scoped bootstrap and handoffs

Slim always-on agent docs, default to toju-app plus targeted electron, and add HANDOFF.md plus a Cursor rule so long chats reset cleanly without agents opening new chats.

Co-authored-by: Cursor <cursoragent@cursor.com>

agents-docs/AGENT_WORKFLOW.md

@@ -1,110 +1,74 @@
 # Agent Workflow & Operating Instructions
 
-These rules apply to **all AI agents** working on this project, regardless of platform or model.
+These rules apply to **all AI agents** working on this project.
 
-Read this file at the start of every session.
+**Token budget (mandatory):**
+
+- Default scope: **`toju-app/` + targeted `electron/` + `.gitea/workflows/`** — see `/AGENTS.md`. No `server/`, `e2e/`, `website/`, `docs-site/` unless the user expands scope.
+- Electron: follow the renderer → preload → one handler path; never dump the whole `electron/` tree.
+- Prefer path-scoped search; one focused agent; no Bugbot / security / best-of-N unless asked.
+- **Handoff > fat chats:** agents cannot open new chats. Write `agents-docs/HANDOFF.md` and ask the user to start a new chat with that file attached.
+- **Models:** keep the user’s latest problem-solving model. Cut cost with scope + handoffs, not weaker models.
+
+Do **not** re-read this whole file every turn after the first skim.
 
 ---
 
 ## Workflow Orchestration
 
-### 1. Plan Mode Default
+### 1. Plan only when ambiguity is real
 
-- Enter plan mode for ANY non-trivial task (3+ steps or architectural decisions)
-- If something goes sideways, STOP and re-plan immediately — don't keep pushing
-- Use plan mode for verification steps, not just building
-- Write detailed specs upfront to reduce ambiguity
+- Plan for unclear architecture or when the user asks.
+- Skip plan mode for focused, in-scope edits with clear acceptance criteria.
 
-### 2. Subagent Strategy
+### 2. Subagents sparingly
 
-- Use subagents liberally to keep the main context window clean
-- Offload research, exploration, and parallel analysis to subagents
-- For complex problems, throw more compute at it via subagents
-- One task per subagent for focused execution
+- Default: one agent.
+- Subagents only for true parallel search inside allowed paths.
+- Never spawn extra review agents unless the user asks.
 
-### 3. Self-Improvement Loop
+### 3. Handoff / short sessions
 
-The goal is a small, sharp file of project-specific rules in `agents-docs/LESSONS.md` that future sessions read and apply. The format of a lesson is defined at the top of `agents-docs/LESSONS.md` — read it before writing one.
+Triggers: user says handoff / new chat; thread is long with more major work left; switching objectives.
 
-**Read at session start.** Open `agents-docs/LESSONS.md` and apply any rules that match the work you're about to do. This is non-optional; the file exists so the same mistake isn't made twice.
+Action: overwrite `agents-docs/HANDOFF.md` with `Status: active` (Goal, Completed, Changed files, Decisions, Failed approaches, Current issue, Next steps, Commands). Then stop major work and ask the user to open a new chat.
 
-**Triggers — record a lesson when any of these happen.** Don't wait for a formal request; these are the signals:
+New chat: if handoff is active, read it first; continue Next steps; do not redo Completed work.
 
-- User says "no", "actually", "don't", "stop", "that's wrong", or "instead do X"
-- User reverts, rewrites, or asks you to redo your edit
-- User re-prompts you with the same or similar instruction (signal that the first attempt missed something)
-- User points out a hidden constraint, past incident, or convention you didn't know
-- Code review (human or `/review`) surfaces an issue caused by your approach
-- You catch yourself about to do the same thing the project has been corrected on before
+### 4. Self-Improvement Loop
 
-If unsure whether it's worth recording: write it. Sharper is better than missing, and grooming the file is cheap.
+**At session start:** `LESSONS-INDEX.md` only; open matching lesson bodies by tag.
 
-**Write before reporting done.** A session that produced a correction must produce a lesson — record it in the same turn the work is completed, not "later". The `AGENTS.md` completion checklist has a line for this; don't tick the box without it.
+Record a lesson + index line when corrected. Prefer fewer sharp rules (~20).
 
-**Groom periodically.** When `agents-docs/LESSONS.md` passes ~20 entries, propose consolidations to the user — merge duplicates, delete rules that no longer apply, shorten anything vague.
+### 5. CONTEXT.md upkeep
 
-### 4. CONTEXT.md upkeep
+Default: `toju-app/CONTEXT.md`. Read `electron/CONTEXT.md` only when touching Electron. Other packages only when in scope.
 
-Read `CONTEXT.md` (or `agents-docs/CONTEXT-MAP.md` → per-subdomain `CONTEXT.md`) when working in a subdomain. Use its vocabulary verbatim **where defined** in code, tests, issues, and commits. If a needed term isn't in the glossary, treat it as a trigger (see below) rather than silently inventing a synonym; the full contract lives in `agents-docs/AGENTS_CONTEXT.md`.
+### 6. ADR upkeep
 
-**Triggers — capture vocabulary in the moment:**
+Only when hard-to-reverse + surprising + real trade-offs. Contract: `agents-docs/AGENTS_ADRS.md`.
 
-- A previously-ambiguous domain term gets a clear resolution → add it (one-sentence definition, aliases to avoid).
-- User corrects your terminology → record the correct term; mark the wrong one as an alias to avoid.
-- A new feature introduces a concept absent from the glossary → add it before claiming the feature done.
-- You catch yourself inventing a synonym because the right term isn't there → flag the gap; don't silently coin a new term.
+### 7. Verification Before Done (behavior first)
 
-**Write before reporting done.** Update the relevant `CONTEXT.md` in the same turn the trigger fires. Append-only — add new entries, don't reshuffle existing ones. The format is documented at the top of each `CONTEXT.md`. See `agents-docs/AGENTS_CONTEXT.md` for the full contract.
+Done = asked functionality works. Unit green ≠ done for product asks. Prefer in-scope proof; don’t pull e2e/server “just to be sure.”
 
-### 5. ADR upkeep
+### 8. Demand Elegance (Balanced)
 
-Read `agents-docs/adr/` when about to change anything that crosses an existing decision boundary. If your work would contradict an ADR, surface it explicitly — never silently override.
+One pause for non-trivial design; skip for obvious fixes.
 
-**Triggers — write an ADR only when all three apply:**
+### 9. Autonomous Bug Fixing
 
-- **Hard to reverse** (schema migration, framework swap, integration redesign).
-- **Surprising without context** (future engineers will question the approach).
-- **Result of genuine trade-offs** (real alternatives existed and you chose deliberately).
-
-If all three apply: write the ADR in the same turn as the decision. Next number (4-digit zero-padded), kebab-case slug, Nygard short form — see `agents-docs/adr/0001-record-architectural-decisions.md` for the canonical example and `agents-docs/AGENTS_ADRS.md` for the contract. If any of the three is missing: don't write one.
-
-**Supersede, don't delete.** Overturned decisions get a new ADR; the old one stays with a `Superseded by ADR-NNNN` note.
-
-### 6. Verification Before Done
-
-- Never mark a task complete without proving it works
-- Diff behavior between main and your changes when relevant
-- Ask yourself: "Would a staff engineer approve this?"
-- Run tests, check logs, demonstrate correctness
-
-### 7. Demand Elegance (Balanced)
-
-- For non-trivial changes: pause and ask "is there a more elegant way?"
-- If a fix feels hacky: "Knowing everything I know now, implement the elegant solution"
-- Skip this for simple, obvious fixes — don't over-engineer
-- Challenge your own work before presenting it
-
-### 8. Autonomous Bug Fixing
-
-- When given a bug report: just fix it. Don't ask for hand-holding
-- Point at logs, errors, failing tests — then resolve them
-- Zero context switching required from the user
+Fix with evidence in default scope. If root cause is clearly `server/` (or similar), say so and ask to expand scope.
 
 ---
 
 ## Pull Requests
 
-This project hosts at Gitea (`git.azaaxin.com/myxelium/Toju`). Gitea PRs and issues use GitHub-style syntax.
-
-- Create a feature branch for every change: `<type>/<short-description>` (e.g. `feat/add-retry-logic`, `fix/null-pointer-webhook`) — `<type>` should match the Conventional Commits prefix (`feat`, `fix`, `chore`, `docs`, `perf`, `refactor`, `test`)
-- Open the PR via the Gitea web UI (or `tea pulls create` if `tea` CLI is installed) — include a summary and a test plan
-- Link issues in the PR body with `Fixes #<number>` for auto-close or `Relates to #<number>` for reference (Gitea honors the same keywords as GitHub)
-- After merge, delete the feature branch
+Gitea: `git.azaaxin.com/myxelium/Toju`. Branch `<type>/<short-description>`; PR with summary + test plan; `Fixes #<n>` / `Relates to #<n>`.
 
 ---
 
 ## Core Principles
 
-- **Simplicity First:** Make every change as simple as possible. Impact minimal code.
-- **No Laziness:** Find root causes. No temporary fixes. Senior developer standards.
-- **Minimal Impact:** Changes should only touch what's necessary. Avoid introducing bugs.
+- **Simplicity First** · **No Laziness** · **Minimal Impact** · **Cheap Context** · **Default Scope Fence** · **Handoff Beats Fat Context**