# 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.
- **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 only when ambiguity is real

- Plan for unclear architecture or when the user asks.
- Skip plan mode for focused, in-scope edits with clear acceptance criteria.

### 2. Subagents sparingly

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

### 3. Handoff / short sessions

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

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.

New chat: if handoff is active, read it first; continue Next steps; do not redo Completed work.

### 4. 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).

### 5. CONTEXT.md upkeep

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

### 6. ADR upkeep

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

### 7. Verification Before Done (behavior first)

Done = asked functionality works. Unit green ≠ done for product asks. Prefer in-scope proof; don’t pull e2e/server “just to be sure.”

### 8. Demand Elegance (Balanced)

One pause for non-trivial design; skip for obvious fixes.

### 9. Autonomous Bug Fixing

Fix with evidence in default scope. If root cause is clearly `server/` (or similar), say so and ask to expand scope.

---

## 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**