Toju/agents-docs/AGENT_WORKFLOW.md

Agent Workflow & Operating Instructions

These rules apply to all AI agents working on this project.

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.
• Named bugs: fix bug "…" → one Obsidian note (BUG_TRACKER.md § Named fix), then default repo scope — not the whole vault or monorepo.
• 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. Interview before implement (default)

• For bugs/features: short interview first (understanding, gaps, choices + recommended default, scope, proof) — then wait. See /AGENTS.md and .cursor/rules/interview-before-fix.mdc.
• Do not guess past ambiguity; the user controls the implementation choices.
• Skip only when the user opts out (“just fix it”) or an approved handoff already decided.

2. Plan mode

• Use plan mode when architecture is unclear or the user asks — the interview often replaces a heavy plan for normal bug fixes.
• Skip long planning essays; prefer bullet choices.

3. Subagents sparingly

• Default: one agent.
• Subagents only for true parallel search inside allowed paths.
• Never spawn extra review agents unless the user asks.

4. Handoff / short sessions

Triggers: user says handoff / new chat; thread is long with more major work left; switching objectives.

Action: overwrite (never append) agents-docs/HANDOFF.md with Status: active and short sections. Then stop major work and ask the user to open a new chat.

New chat: if handoff is active, read it first; continue Next steps; do not redo Completed work. If Next steps still need choices, re-interview — don’t invent them.

When finished: clear HANDOFF.md to Status: none with empty sections so the file stays tiny for the next session.

5. Self-Improvement Loop

At session start: LESSONS-INDEX.md only; open matching lesson bodies by tag.

Record a lesson + index line when corrected. Prefer fewer sharp rules (~20).

6. CONTEXT.md upkeep

Default: toju-app/CONTEXT.md. Read electron/CONTEXT.md only when touching Electron. Other packages only when in scope.

7. ADR upkeep

Only when hard-to-reverse + surprising + real trade-offs. Contract: agents-docs/AGENTS_ADRS.md.

8. Verification Before Done (behavior first)

Done = asked functionality works as the user confirmed in the interview. Unit green ≠ done for product asks.

9. Demand Elegance (Balanced)

One pause for non-trivial design; skip for obvious fixes once the user has chosen a direction.

10. Bug fixing (after interview)

Implement the approved plan with evidence in default scope. If root cause is clearly outside scope, say so and ask to expand — don’t silently crawl.

---

Pull Requests

Gitea: git.azaaxin.com/myxelium/Toju. Branch <type>/<short-description>; PR with summary + test plan; Fixes #<n> / Relates to #<n>.

---

Core Principles

• Simplicity First · No Laziness · Minimal Impact · Cheap Context · Default Scope Fence · Handoff Beats Fat Context · Interview Before Guessing