# Agent Instructions This repo is a **prompt-engineering project**: its artifacts are prompts and the eval suites that certify them, not application source. "Code" below means prompt artifacts — a feature LLD owns `prompts/{family}/**` and `evals/{family}/**`, not `src/`. This policy is deliberately forked from the `code` harness, reframed for prompt work — a capability added to `code` never silently lands here. Rules marked **[override]** deliberately replace a runtime default; the rule here wins. **Policy style: self-improving, scoped to prompt-engineering teams.** The routing table below is living policy: escalation records feed `retro`, `retro` proposes routing amendments, and the table moves. Nothing in this file names a model — tier labels (economy / standard / frontier) are the vocabulary here; the tier → model mapping lives only in `.claude/rules/model-tiers.md`, and enforcement lives in each owned agent's `model:` pin. --- ## The Routing Policy The model decision belongs to this table, not to the human and not to session judgment. Classify the task (the `route` skill), read the row, dispatch the pinned agent. | Task type | Tier | Executing agent | | --- | --- | --- | | Eval execution, regression runs, scoring against golden sets | economy | `eval-runner`, `regression-runner` | | Synthetic test data, edge-case corpora | economy | `data-generator` | | Task classification (`route` itself) | economy | inline, cheapest capable tier | | Prompt drafting and iteration loops | standard | `prompt-iterator` | | Ship gate (judge), user-requested second opinion | frontier | `judge` | | Adversarial probing | frontier | `red-team` | **The escalation ladder.** Every task starts at its row's tier. Promotion requires a **recorded failing eval at the current tier** — run the `escalate` skill, which writes the evidence as a changelog entry (`Class: escalation`). Never promote on judgment alone. Symmetrically, demotion experiments run continuously: `regression-runner` re-runs passing prompts one tier down, and a pass is a `retro`-visible signal to move the routing row. **Routing guardrails:** - ❌ **Model names** — never name a model outside `.claude/rules/model-tiers.md`. Tier labels are free everywhere; a model name anywhere else in this repo's instruction surface is a defect. - ❌ **Frontier fan-out** — never dispatch the frontier tier for mechanical, parallel, or repetitive work; frontier is for judgment (the ship gate, adversarial probing, an explicitly requested second opinion). - ❌ **Unevidenced promotion** — never run a task above its routed tier without the `escalate` record. - ✅ **Escalations are changelog entries**, so `retro` can propose routing-table amendments from escalation counts — the cost policy tunes itself from history. --- ## Maintenance Invoke the `maintenance` agent whenever the docs look like they need it: a missing `docs/structure.md`, a `harness-version` marker behind the installed version, docs contradicting the prompt families they describe, unowned prompt paths, or drift noticed while working. Never reconcile by hand — the agent auto-selects its mode and hands back. **This harness's own parity contract is part of the audit**: the routing table above, the owned agents' `model:` pins, and `.claude/rules/model-tiers.md` must agree three ways — a row with no pinned agent, a pin with no row, or a tier the rule doesn't map is drift to flag. --- ## Getting Started - Read **[`docs/structure.md`](docs/structure.md)** for the documentation map and folder authority. - Read **[`docs/memory/`](docs/memory/)** for agent memory files. - Prefer `docs/` over `README.md` — `docs/` is canonical for agents. - Prompt families live under `prompts/{family}/`; their golden sets under `evals/{family}/`. The feature doc that owns a family is the first read before touching it. --- ## Workflows Three peer modes plus a Completion step — enter wherever the user's thinking already is. Each mode is implemented by an agent + skill; the behavioural detail lives in those files, not here. | Mode | Enter when | Implemented by | Exits to | | --- | --- | --- | --- | | **Brainstorming** | explicit ask (`/brainstorm start`); or offer a session — never auto-enter — when the user brings a large piece of work or an utterance contradicts a recorded pillar | `brainstorm` agent + skill | LLD, Plan, or close + harvest | | **LLD** (low-level design) | a new prompt family, task type, or eval suite | `lld-mode` agent + `documentation` skill | Plan | | **Plan** | an LLD is approved | `documentation` skill → `docs/history/plans/YYYY-MM-DD-{slug}.md` | Completion | **On Plan Completion:** freeze the plan (`Status: Complete`, Completed date); discharge every Doc Obligations row into **updated**, **owes nothing** (with the reason), or **blocked** (→ backlog) — for each row's doc, flip `status: active`, extend it in place, and confirm its `owns:` globs against the actual prompt files; write the changelog entry as a draft immediately. **On Brainstorm Close:** the skill's `stop` procedure — converge, a user-approved harvest manifest, apply, uselessness test; the record moves to `docs/history/brainstorms/{topic}/`. --- ## Ownership & Documentation - **Ownership routes before editing.** A feature doc (flat in `docs/features/`) declares the prompt paths it owns in its `owns:` frontmatter (`prompts/{family}/**`, `evals/{family}/**`); the SessionStart hook injects the union as the ownership index. Match the path or topic, read the owning doc first. No index in context ⇒ the repo isn't reconciled — see Maintenance. - **Every markdown document goes through the `documentation` skill** — templates, the two-natures rule (truth documents present-tense; history only in records), and doc-lint. - **[override]** Keep `docs/` updated when a change alters documented behaviour — creating and updating docs is part of the work. - When moving or renaming a prompt family: update the owning doc's `owns:` globs in the same change. --- ## Prompt Artifacts — eval-first **[override]** The gated-verification posture of the `code` harness is reframed: here the suite discharged at the gate is the eval set. - **A prompt ships with its golden set.** A new prompt family lands with the evals that certify it; a prompt change re-runs its family's evals before it ships. A failing eval is reported honestly, never bypassed by weakening the rubric. - **Certification is per tier.** A prompt-library entry records the tier it is certified for, its eval score, and the certification date (the `prompt-library` skill owns the entry format). A model-generation change invalidates certifications — `regression-runner` re-certifies. - **Throwaway prompt experiments are not library entries** — scratch iterations stay out of `prompts/**` until they pass their evals. - Conventions — golden-set shape, rubric design, pass thresholds: `.claude/rules/evals.md`. House prompt style: `.claude/rules/prompting.md`. --- ## Changelog The working session is the last holder of the refinement context that produced a prompt: the variants rejected, the eval deltas, the escalations and why. The `changelog` rule carries the trigger and lifecycle; the policy here matches the `code` harness — every non-mechanical commit is covered by an entry (`docs/history/changelog/YYYY-MM-DD-{three-words}.md` + a `docs/history/CHANGELOG.md` row), drafts are mutable and commits freeze, and the `retro` agent distills on demand. Two genres are load-bearing for this harness: - **Escalation entries** (`Class: escalation`, written by the `escalate` skill) — the raw data for routing-table tuning. - **Prompt refinement entries** — rejected variants and eval deltas quoted with the same discipline the template's failure fields demand. --- ## Project Memory Project learnings live in `docs/memory/` (git-tracked): `main.md` for project-wide patterns, `{agent-name}.md` for each owned agent's strategy memory (what rubrics drift, which adversarial classes keep working). User facts go to the runtime's user-level store. When recording a learning: _true of this project, or true of this user?_ --- ## Out-of-Scope Discovery Work surfaced outside the current plan's scope: append to `docs/history/backlog.md` under the appropriate priority (P0–P3), format `- **[P1]** Description — discovered by [plan or agent]`. Do NOT ask permission; append and mention it in the reply. --- ## Delegation The single policy for sub-agent dispatch — when to fan out, at what tier, and how far to trust the result. Where the `code` harness leaves tier choice to session judgment, dispatch here runs through **The Routing Policy** above — the table is the first stop for every dispatch, not session judgment. No dispatch mechanism ⇒ inline. - **Delegate to keep bulk out of the main context.** Wide file reads, sweeps, broad research, audits, fixture prep — work whose raw tool output the main session doesn't need — defaults to a sub-agent: output a sub-agent reads dies with it, while output read inline is re-read and re-billed on every later turn. The hand-off is self-contained (the sub-agent sees none of the conversation), so it must still cost less than the work; run independent delegations in parallel. - **Small or judgment work stays inline.** A task finishable in a handful of tool calls is faster done than briefed. **Never delegate judgment by reflex** — a second opinion is for a high-stakes call or an explicit request. - **A delegated result is a report, not verifiable ground truth** — verify load-bearing results directly. - **Tiers run through the routing table, never session judgment** — mechanical fan-out routes to economy, judgment-heavy delegation to standard, frontier only for the ship gate, adversarial probing, or an explicit user-requested second opinion (§ The Routing Policy); the table's own guardrails (❌ Frontier fan-out, ❌ Unevidenced promotion) bind every dispatch. Tier → model mapping lives only in `.claude/rules/model-tiers.md`. - **An explicit user directive about tier, cost, or delegation overrides this section**, subject to the routing table's evidence requirement for promotion (the `escalate` skill records it). --- ## Guardrails & Defaults ❌ prohibitions hold unless the user explicitly asks otherwise; ✅ and ⚠️ items are standing policy: - ❌ **Dependencies** — never upgrade frameworks, libraries, or dependencies. - ❌ **Branches & Worktrees [override]** — never self-create git branches or worktrees; commit straight to the checked-out branch. Exception: a user-requested pull request creates the branch it requires. - ❌ **Protected Files** — if `docs/operations/protected-files.md` exists, read it before editing and never modify a listed path; never modify `AGENTS.md` or that file itself. - ✅ **Delegation** — when to fan out, tiers, and trust are § Delegation. - ⚠️ **Plans** — created in `docs/history/plans/`; frozen at `Complete`/`Abandoned`, never edited after. - ⚠️ **Tool Issues** — report unexpected CLI/MCP tool behavior to the user with the exact tool, command, and error. --- ## Runtime Notes Everything above is runtime-neutral; this section is the only place runtime-specific facts may live. - **Claude Code**: sub-agent dispatch is the Agent tool; the owned agents' frontmatter `model:` pins enforce the routing table's tiers mechanically. Skills are slash commands (`/route`, `/escalate`). The ownership index injects at SessionStart. - **Runtimes without pin support** (Codex and other AGENTS.md readers): agent tier pins are dropped from the projected twins, so the routing table above and each agent's stated tier are the policy — advisory rather than enforced. The table is still binding on the humans and sessions that dispatch.