Ai Task

---
name: ai-task
description: Run one task through the agentic pipeline with the gates its risk tier requires. In the default solo profile T0–T3 run in direct mode (name the files, edit, one verification run at the end, failures fixed as one batch, one BALANCED-tier review at T2; at T3 the plan is written in plan mode and approved by the human, and the one review is STRONG) and T4–T5 run the full SDLC pipeline — discovery, context, impact, risk tier, plan, plan review, implementation, test, adversarial review, security review, release report, human approval. Resumes an interrupted task from .ai/state/current.json. Use for any change in a repository that has .ai/.
argument-hint: <what you want done> | --resume | --abandon
---

# /ai-task $ARGUMENTS

You are the **manager**. You orchestrate the pipeline, keep your own context
small, and stop at human approval. Read `.ai/agents/manager.md` and
`.ai/policies/safety.md` before the first stage.

The pipeline, its stages and its gates are identical under Claude Code and under
Codex; only the install root and the model ladder differ. Resolve the root once:

```bash
for AI_HOME in "${CLAUDE_CONFIG_DIR:-$HOME/.claude}" "${CODEX_HOME:-$HOME/.codex}"; do
  [ -d "$AI_HOME/skills/ai-task" ] && break
done
```

`STATE` below means:

```bash
python3 "$AI_HOME/skills/ai-task/state.py"
```

The state file is the project's `.ai/state/current.json` either way, so a task
started in one runtime resumes in the other.

## 0. Resume or start

```bash
$STATE get --quiet
```

If that says `no task in flight`, skip to **Nothing in flight** below. Otherwise
read the handoff **before** anything else:

```bash
$STATE handoff --print
```

It is the cheapest way back into an interrupted task: stage, current step and its
allowed files, the last decisions, the pending questions, the resume point and
the last prompt of the session that was interrupted, in at most thirty lines.
Read it instead of re-reading the repository, and trust it over a compaction
summary where the two disagree — it is rendered from the state, not remembered.

- **A task is in flight** (stage is not `done`): print its id, goal, stage,
  next action and open risks. If `updated_at` is old and the stage is
  `implementation`, warn that it may have stopped mid-step and say which step.
  Ask whether to resume, close it, or abandon it. **Never silently discard it** —
  a live state file is what the scope guard is enforcing against.
- **The handoff says `Handed to <this runtime>`**: the task was moved here on
  purpose. Resume at its resume point; your first state change completes the
  handoff. If `cross_vendor_review` (`$STATE get --field cross_vendor_review`)
  is `requested` with `to` = this runtime, go straight to **ADVERSARIAL
  REVIEW** with this runtime's own reviewer on the STRONG tier, record it with
  `$STATE set review_status <passed|blockers_open>` (that marks the review
  `done` and stores your verdict as its `result`; an owner's `blockers_open`
  stays), then hand it back: `$STATE handoff --to <from>`.
- **It says `Handed to <the other runtime>`**: do not work on it here. Every
  state change exits 7 `RUNTIME_HANDOFF_PENDING` until that runtime resumes it.
  Tell the user where to resume; take it back with `$STATE handoff --to <this
  runtime>` only when they ask.
- **`--abandon`**: `$STATE done` then `$STATE archive`, and say what was left
  unfinished.
- **Nothing in flight**: classify the request into one of the five workflows —
  feature, bugfix, refactoring, hotfix, investigation — say which and why, then:

```bash
$STATE init --goal "<one sentence>" --workflow <workflow>
```

Read `.ai/workflows/<workflow>.md`. It tells you what is specific to this shape
of work.

`init`, `quick` and `risk` may print `preferred runtime: <runtime> (<reason>)`
on stderr — the plan's table or the quota rule names the other runtime. It is
advice: say it to the user, and move the task only when they agree, with
`$STATE handoff --to <runtime> --why "<reason>"` (`--for review` to ask the
other vendor for the T4+ review). It prints the command to resume there; it
never runs it.

Then read the profile:

```bash
jq -r '.pipeline_profile // "team"' .ai/policies/risk-tiers.json
```

The stages are the same in every profile; the profile decides **who does each
one**. `pipeline_profiles.<profile>.delegated_stages[<tier>]` in that file lists
the stages that go to a subagent. `solo`, the default, has two modes:

- **direct** (T0–T3): no ceremony. You name the files, edit, run each step's
  own scoped tests, then the verification command once at the end and the e2e
  suite once after it, and fix every failure as one batch.
  The only subagents are cheap readers (`Explore`, `log-reader`) and, at T2,
  one review on the BALANCED tier (`ai-reviewer` with
  `model: $($STATE profile --tier BALANCED)` on Claude Code,
  `ai-reviewer-balanced` on Codex). Nothing runs on STRONG below T3. At T3 the
  same path gains three things, and only three: the plan is written in plan
  mode and the human approves it before any edit, characterization tests come
  first where legacy behaviour changes, and the one review runs on STRONG.
  No `ai-planner`, no plan-review agent, no `ai-release`. `quick` exits 8
  `DIRECT_MODE_CAP` when the plan caps direct mode below the tier: then use
  `init` and the pipeline.
- **sdlc** (T4–T5): the full pipeline below, recorded stage by stage, with the
  delegations the profile lists.

Decide the tier **first**, from the trigger table, before anything else; when
two tiers are arguable take the higher. Until it is known, act as for T2.

## 1a. Direct mode — T0, T1, T2, T3

Skip `$STATE init` above for T0–T3; direct mode has its own single call.

1. **Tier and files.** Take the entry points from the request; confirm them with
   `grep -n`. Say the tier, the trigger and the files you will touch, in one to
   five lines. At T2 that is the plan. **At T3** write it in plan mode: a
   numbered list of steps with their files, the characterization tests as the
   first step when legacy behaviour changes, and a one-line rollback (usually
   `git revert`). The human accepting plan mode is the plan approval — no
   agent reviews the plan. Call `ai-planner` on STRONG only on the T3 trigger
   in `delegate_anyway_when`. Use `Explore` (FAST) when a file is not
   found in a few `grep` calls, never a six-agent fan-out — and when a file is
   too large to open, that reader brings back the excerpt, not the file.
   If this task needs a tool or MCP server the project does not enable by
   default, say so here in one line and turn it off when the task ends:

   ```
   tools_for_this_task: <server-or-tool> — <why> — <when it goes off again>
   ```

   Most tasks need none. See `.ai/policies/tooling.md`.
2. **Record — T2 and T3.** One call arms the scope guard and writes the audit
   trail; T0 and T1 keep no state file at all, the commit is the record. At T3
   run it only after the human accepted the plan, list every file of every
   step, and say so in the note:

   ```bash
   $STATE quick --goal "<one sentence>" --workflow <workflow> --tier T2 --files "<a>,<b>" --note "<trigger>"
   $STATE quick --goal "<one sentence>" --workflow <workflow> --tier T3 --files "<a>,<b>,<c>" --note "<trigger>; plan approved in plan mode"
   ```

3. **Implement**, yourself, in this session. `ai-implementer` (BALANCED, low) only
   for a mechanical pattern-copy the human asks for. When you finish a piece of
   work, run **only its own tests** — `step_test_command` from
   `.ai/policies/testing.md` scoped to the files you just touched — and fix
   those failures there. Never the full suite mid-edit, never e2e. A bugfix
   shows its failing test first, that one test.
4. **Verify once, to the end.** Run the verification command from
   `.ai/policies/testing.md` with no fail-fast flag, through `tail -40`, or
   through `log-reader` when the output is long. T0 runs nothing. Collect
   **every** failure, classify each (new regression, existing, environment),
   then fix all new regressions in **one** remediation step and run once more:

   ```bash
   $STATE step-done 1 && $STATE remediate --files "<failing tests>" --note "<n> regressions"   # T2, T3
   ```

   At T0/T1 there is no state: just fix the batch and re-run. Two rounds at
   most; a third means the human decides. One failure never restarts the task.

   Then, **once**, after the fast suite is green: `e2e_command`. T0 and T1 skip
   it. At T2 and T3 run it when the change can reach a flow the e2e suite
   covers; when it cannot, say so in one line instead. It never runs inside
   step 3.

   ```bash
   $STATE set e2e_status <passing|failing|not_applicable>   # T2, T3
   ```
5. **Review — T2 and T3.** After the tests pass, one review over `git diff`.
   T2: the BALANCED tier — `ai-reviewer` with `model: $($STATE profile --tier
   BALANCED)` on Claude Code, `ai-reviewer-balanced` on Codex — no ledger and
   no probe. T3: `ai-reviewer` on STRONG (`model: $($STATE profile --tier
   STRONG)`, `ai-reviewer` under Codex), after `$STATE review-gate`; add
   `ai-security` only when the diff touches authentication, authorization or
   personal data. Fix BLOCKER and
   HIGH findings as one batch (`$STATE remediate`), re-run the verification
   command, and ask for one scoped re-review only when a BLOCKER was fixed.
6. **Close.** Print what changed, the verification command and its result, the
   review verdict and the rollback (`git revert`), as the commit message body.
   Then stop for the human. At T2: `$STATE close`. At T3 the human approves the
   result as well: `$STATE stage human_approval` after the summary is shown,
   and the task closes once they have.

That is the whole path. The sections below are for T4 and above, and for the
`team` profile. A T3 whose diff is re-scored to T4 by the sensors leaves direct
mode here: say so and continue with the sections below from ADVERSARIAL REVIEW.

## 1. Walk the pipeline

The stages, in order. Which of them exist for a task is the tier's answer, and
which of them you delegate is the profile's; none is skipped because the change
"looks easy" — that judgement is what the risk classification replaces.

```
REQUEST
  → DISCOVERY            what exists, where, who calls it
  → CONTEXT              the compressed, structured summary
  → IMPACT ANALYSIS      what this change reaches
  → RISK CLASSIFICATION  T0 … T5, from .ai/policies/risk-tiers.json
  → PLAN                 steps, each with the files it may touch
  → PLAN REVIEW          T3 and above
  → IMPLEMENTATION       one approved step at a time
  → TEST                 the step's own tests, then the suite once, then e2e once
  → ADVERSARIAL REVIEW   assumes the implementation is wrong
  → SECURITY REVIEW      mandatory at T4 and T5
  → RELEASE REPORT
  → HUMAN APPROVAL
```

Everything an agent writes into `.ai/project/` carries an evidence label — KNOWN
FACT with `file:line`, INFERENCE with what it was drawn from, UNKNOWN, RISK. An
inference is never recorded as a fact; where the documentation and the code
disagree, both are written down and a human decides which is the bug.

Record every stage transition, so the state file is a true audit trail:

```bash
$STATE stage <stage> --note "<what happened>"
```

### TRIAGE — discovery, context, impact and risk

**solo, T0–T3:** direct mode, section 1a. If a task that started as T3 or below
turns out to be T4+, say so, `$STATE close` the quick record and start it here.

**`team` below T3:** record the four stages in one call and go on to PLAN:

```bash
$STATE triage T<n> --note "<the trigger>" --context "<entry points, callers, what must stay unaffected — a few lines>"
```

**T4 and above, or `team` from T3:** the stages run one at a time and are recorded one
at a time. `ai-discovery` — one agent per area in parallel, after `ai-indexer`
when the area is large — into `discovery.md`; `ai-context` for the summary; a
second `ai-discovery` pass for `.ai/templates/impact-report.md`; `ai-risk` on
STRONG — `model: $($STATE profile --tier STRONG)` — for the tier (`ai-risk-strong` under Codex, whose agent files
outrank a spawn-time model), re-run when it says `confidence: uncertain`.
In `solo` you may still write context and impact yourself at T4 when the area
is one you know; the risk call at STRONG is not optional there.

```bash
$STATE risk T<n> --note "<the trigger that decided it>"
```

Delegate below T4 only on a trigger from `delegate_anyway_when`: one
`ai-discovery` for an area the developer says is unfamiliar, or for an
`UNKNOWN` the plan depends on. Never the six-agent fan-out — that is
`/ai-init`'s job, once.

If the task needs a tool or MCP server beyond what the project enables by
default, record it now, once, as `tools_for_this_task: <server-or-tool> — <why>
— <when it goes off again>` in the task record, and disable it again when the
task closes (`.ai/policies/tooling.md`). Agents keep the tool list their
definition gives them; an agent short of a tool answers `SCOPE_CHANGE_REQUIRED`.

Now state which later stages the tier makes mandatory and which of them this
profile delegates. Everything after this point follows that answer, not your
impression of how big the task feels.

### PLAN — only when the tier needs one

**T0–T3 in solo:** handled in direct mode (1a). **`team` below T3:** a short
numbered list of steps, each with its files, registered with:

```bash
$STATE plan --ref ".ai/reports/<task-id>/task.md" --steps /tmp/steps.json
```

**T4, and T3 in `team`:** `ai-planner` on STRONG — `model: $($STATE profile --tier STRONG)` — (`ai-planner-strong` under
Codex), in plan mode. **T5:** `ai-expert`. Save to `.ai/reports/<task-id>/implementation-plan.md` following
`.ai/templates/implementation-plan.md`, register the steps as above.

`allowed_files` is enforced by a hook from T2 up, so it must be accurate. A
plan with a **(blocking)** open question is not approved. Turn every one of them
into an `ask` call **before** `$STATE plan` registers the steps — once a question
is pending, `plan` exits 4 anyway, so asking first is the shorter road:

```bash
$STATE ask --batch /tmp/questions.json     # several at once — see Questions below
$STATE questions --pending --format md     # render for the human, then stop
```

A plan registered with its blocking questions still open is a plan that was
approved on an assumption. See **Questions** below.

### PLAN REVIEW (T4 and above; T3 in `team`)

In `solo` a T3 plan is reviewed by the human in plan mode (1a) — no agent.

`ai-reviewer` on the plan itself, before any code exists. Then show the human the
plan and the review — both, in the conversation — and only **after** they have
been shown:

```bash
$STATE stage human_approval
```

That command is what opens the gate: it appends gate question `G1`, stamps
`requested_at` and emits `gate_requested`. Running it before the human has seen
what they are approving asks them to sign a blank page, and the journal records
that it happened in that order. For T4+ this approval is required, not optional.

### IMPLEMENTATION

```bash
$STATE stage implementation
```

For each step in order:

```bash
$STATE step <step_id>          # arms the scope guard for this step
```

Implement it **yourself**, in this session. Use `ai-implementer` only for
mechanical pattern-copying work, or when the human asks.

If an edit is refused with `SCOPE_CHANGE_REQUIRED`: stop, do not work around it.
Say which file is needed and why, return to PLAN for that one step, amend it,
re-register the plan, and continue. One step's scope is amended — not the task
replanned.

Close the step with **its own tests only** — the ones the plan named for it,
through `step_test_command` scoped to that step's files (`$STATE step` prints
them). Not the full suite, not e2e: those belong to the end of the task. The
scoped run still goes to the end, and its failures are fixed inside the step —
no `remediate` step for them. If the plan named no test for the step, nothing
runs.

```bash
$STATE step-done <step_id>
```

`step-done` measures what the step actually changed, between the tree it began
with and the tree now, and refuses two things with **exit 6**:
`DIFF_BUDGET_EXCEEDED` when the step outgrew its tier's budget, and
`SCOPE_CHANGE_REQUIRED` when it touched a file outside its own. Neither is a
refusal to do the work — the step stays in progress and the way out is printed:

```bash
$STATE step-split <step_id> --files "<the part that is its own step>" --note "<why>"
```

The moved files leave the original step and become a sibling that inherits the
tree it started from. After every step the task's diff is re-scored from
`path_scopes`: a change that reached `**/Payment/**` is T4 from then on,
whatever it was called at the start. A re-score only ever raises — lowering a
tier needs a human, in their own terminal, with `--by`.

### TEST — the step's tests inside the step, the suite once, e2e once

After the **last** step, not after each one. Run the verification command from
the **Verification** section of `.ai/policies/testing.md`; if that section is
empty, take it from the project `CLAUDE.md` or the CI config and write it into
`testing.md` as part of this task, so the next task has it. Run it through `test-run`, which runs
it **to the end** — no fail-fast flag, no stopping at the first red test —
writes every line to `.ai/reports/<task-id>/tests-suite-<n>.log`, records the
run against the tree it ran on, and prints six lines:

```bash
$STATE test-run --scope suite        # and, at the end of the task, --scope e2e
```

A **green** run needs no agent at all: exit 0 is the verdict and `test_status`
is set from it. A **red** run is where `ai-tester` (FAST) earns its keep —
hand it the log path, not the output; it classifies and never re-runs anything.
An environment failure it calls transient gets exactly one
`--env-retry`. The suite is capped at `sensors.max_suite_runs`: running it a
sixth time is not the next move, and the cap says so.

Only the step's own scoped tests run during a step — never the full suite and
never e2e. For a bugfix the failing test is written and **shown failing**
before the fix — that one test, not the suite.

```bash
$STATE set test_status <existing_failure|new_regression|env_failure|unknown>
```

**Fix as one batch.** Classify every failure first. Then open **one**
remediation step whose scope is every finished step plus the failing tests,
fix all the new regressions in it, and run the verification command once more:

```bash
$STATE remediate --files "<failing test files>" --note "<n> regressions: <one line each>"
… fix them all …
$STATE step-done R1
```

A remediation never re-triages or re-plans: the tier, the plan and the finished
steps stand. Two rounds at most; a third round means the human decides.
`existing_failure` is recorded and reported, not fixed inside this task. Never
let a test be edited to make it pass.

**E2E — once, at the end of the task.** After the fast suite is green and
before the adversarial review, run `e2e_command` from `testing.md`, once, to
the end, output through `tail -40` or `log-reader`. It never runs inside a step
and never twice. Skip it when the change cannot reach a flow it covers and say
which, in one line; at T4/T5 it is not skipped, and its result goes into the
release report. Its failures are classified and fixed as one batch, like the
suite's.

```bash
$STATE set e2e_status <passing|failing|not_applicable>
```

### ADVERSARIAL REVIEW (T2 and above)

First ask whether it has to be a model at all:

```bash
$STATE review-gate
```

It runs every sensor on the tree as it is now — the recorded suite result, the
linter and type checker the project wrote down, the diff against the budget,
the tier re-scored from the real diff, step-to-test traceability, repeated
blocks, and whether the named tests **fail without the change** — writes
`.ai/reports/<task-id>/sensors.json` and one ledger row per settled sensor, and
answers one of two things. At T2 and below, all green records
`review_status: skipped_green` and the review is done: the sensors are the
review (decision 6, `review-economy.md` §8). Anything else — a red sensor, a
tool nobody wrote down, a result from an older tree, a tier above T2 — prints
`review: required` with the reason, and you delegate exactly as before. From
T3 it always says required.

Nothing here weakens a review: `unavailable` is not green, and
`set review_status skipped_green` is refused — only the gate writes it, from
measurements.

Then, when it is required: one `ai-reviewer` on the diff — a fresh context that did not write the code —
on the tier from `pipeline_profiles.<profile>.review_model[<tier>]`: BALANCED
at T2 in solo (`ai-reviewer` with `model: $($STATE profile --tier BALANCED)`
on Claude Code, `ai-reviewer-balanced` on Codex), STRONG above. Save findings to
`.ai/reports/<task-id>/review-report.md`.

The sensor rows are already in the ledger, so the reviewer inherits them
instead of re-deriving them. Before you delegate, probe the change yourself for
a minute: the handful of
inputs its own threat model makes interesting, run through the real code in the
scratchpad, outcomes noted in `.ai/reports/<task-id>/review-ledger.md`. The
reviewer starts where you stopped. A re-review after a remediation is scoped —
do the named findings close, and what did the remediation introduce — never a
second full pass. One reviewer per pass; fan out narrow reviewers only at T4/T5
when the change is wide. Full rules: `.ai/policies/review-economy.md`.

```bash
$STATE set review_status <passed|blockers_open>
```

Every BLOCKER and HIGH is fixed together, in one `$STATE remediate` step, then
the verification command runs once and one scoped re-review closes the named
findings — never one finding, one fix, one re-review at a time. A finding whose
cause is the plan goes back to PLAN for that step only. Findings that are real but out of scope go to `.ai/project/known-risks.md`.
When a finding is a mistake this repository has seen before, add one line to the
project `CLAUDE.md` in this task: the second occurrence is when a correction
belongs there.

### SECURITY REVIEW (T4, T5, and anything touching auth or personal data)

`ai-security`. Save to `.ai/reports/<task-id>/security-report.md`.

```bash
$STATE set security_status <passed|failed|not_applicable>
```

When it is not applicable, say why in the note. Silence is not a verdict.

### RELEASE REPORT

**solo, T0–T3:** the short form written in direct mode, step 6 — what changed,
what was deliberately preserved, the verification command and its result, the
review verdict, the rollback (usually one `git revert`), open risks. It becomes
the commit message body; at T3 it is also appended to `task.md`. **T4, T5, and
`team` from T2 up:** `ai-release` fills the full template into
`.ai/reports/<task-id>/release-report.md`.

### HUMAN APPROVAL

Print the summary, the open findings, the rollback, and the exact commands that
*would* run next — then **stop**. Do not commit, merge, push or deploy.

**You cannot grant this approval, and running `approve` yourself will not work.**
The command refuses with exit 5 unless it sees a terminal on stdin, or
`AI_UNATTENDED` in its own environment — neither of which a tool call from this
session has. The path guard denies it too. Print the command and hand it over:

```bash
python3 "$AI_HOME/skills/ai-task/state.py" --root "<project root>" approve --by "<name>"
```

Print it with `$AI_HOME` and the project root expanded to real absolute paths,
quoted — the human pastes it into their own shell, where those variables are not
set. There are two other routes, and naming them is part of the hand-over:

- the human edits `[Answer]: A` into gate question `G1` in
  `.ai/reports/<task-id>/questions.md`, then tells you to run
  `$STATE questions --sync`. That route needs a prompt recorded *after* the gate
  was requested, so it works in a live session and not in a replay.
- an unattended runner exports `AI_UNATTENDED=1` in the launcher's environment.
  The approval is then recorded as `unattended: true` in the state and the
  journal — it is an audit mark, not a way to make the gate quieter.

A rejection is `$STATE reject --by "<name>" --why "<reason>"`; the stage stays
where it is and the reason is journalled.

Only **after** the human has approved out of band:

```bash
$STATE done
$STATE archive
```

Suggest the commit command; let the human run it, or run it only when they ask
in this turn.

## Questions

A subagent never asks the user. When it cannot continue without a human decision
it returns a `QUESTIONS_NEEDED` section and stops there, with whatever partial
output did not depend on the answer. Converting that into a real question is
yours, and `state.py` is the only thing that may write the questions file — the
path guard denies an edit to `.ai/reports/*/questions.md`, including a shell
redirect into it. **Never hand-edit it, and never answer on the human's behalf.**

**Convert.** One question:

```bash
$STATE ask "<one line>" --option "A: <text>" --option "B: <text>" \
  --recommend A --context "src/Foo.php:120"
```

Several at once — a JSON array of `{question, options:[{key,text}], recommend,
context}`, which is the direct shape of a `QUESTIONS_NEEDED` block:

```bash
$STATE ask --batch /tmp/questions.json
```

Option keys are single letters `A`–`W`, at least two, A first. Do not put
`(recommended)` in an option's text; that is what `--recommend` is for.

**Render.** Show the human the questions, not the file:

```bash
$STATE questions --pending --format md
```

**Then stop.** While any non-gate question is pending, nine commands exit 4 and
change nothing: `stage`, `triage`, `plan`, `step`, `step-done`, `remediate`,
`approve`, `done`, `close`. Reading, recording and answering still work — `get`,
`events`, `handoff`, `note`, `risks`, `set`, `ask`, `answer`, `questions` — and
`done --abandon` is exempt, because abandoning the task is how a question that
cannot be answered gets closed. That is the point: the pipeline halts rather
than drifting on an assumption you invented. Under `AI_UNATTENDED=1`, `ask`
ends the turn with the literal line `WAITING_FOR_ANSWERS <file> <ids>` and the
runner takes over.

**Record the answer** in the form the human gave it:

```bash
$STATE answer Q1=B Q2:"free text"          # letters and free text mix
$STATE answer --prose "1B 2A 3: keep the old column"
$STATE questions --sync                    # they filled [Answer]: into the file
```

`--sync` re-reads the file, so a human who answered by editing `[Answer]:` lines
is recorded as the author. Re-syncing an already-answered question is a no-op;
the trailer is parsed back and ignored.

**Outside a task** — the brainstorm in `/sdlc-intent` — questions are per topic
and live in `docs/sdlc/intent/<slug>.questions.md`:

```bash
$STATE ask --topic <slug> "<one line>" --option "A: …" --option "B: …"
```

Topic questions block nothing and emit no journal event. They work in a
repository with no `.ai/` at all.

## Keeping context small

- Inline does not mean verbose: a stage you do yourself is a few lines, and
  below T2 not even a file — the state archive is the record.
- One tool call where one will do: `quick` up to T3, `triage` instead of four
  `stage` calls, one `task.md` instead of four report files, one verification
  run and one e2e run instead of one per step, one `remediate` step instead of
  one per failure.
- Never read logs, test output or large files into this session. `grep -n`
  first and read the ranges that matched; past that, `tail`, then a FAST reader
  on the cheapest model — `log-reader` for output, `Explore` for code — which
  returns the excerpt with `file:line`, never the file.
- Tools and MCP servers are context too. Anything the task does not name stays
  off, and deferred tools are loaded in one batched call, not one per tool.
- Keep the agents' structured outputs as files under `.ai/reports/<task-id>/`
  and refer to them by path; do not carry their full text through the
  conversation.
- Do not rediscover what `.ai/project/` already records. If it is wrong, fix that
  file as part of the task.
- Between stages, your own context should hold: the goal, the tier, the current
  step and the last verdict. Everything else lives on disk.

## Rules

- No required stage is skipped. `stages_required` per tier says which exist —
  T0 and T1 have no plan stage at all — and the profile decides who does each.
  Cheap tasks get cheap stages, not skipped ones: in direct mode they are a
  line each, not a file each.
- Failures are fixed in batches. One red test or one review finding never
  restarts the task, re-runs the suite on its own, or re-opens the plan. A
  step's own scoped tests are the exception: they are fixed in that step.
- A step runs its own tests, and only those. The full suite runs once after the
  last step; the e2e suite runs once after that. Never per step.
- Nothing below T3 runs on STRONG. Readers and runners are FAST; the T2
  review is BALANCED; STRONG is paid for from T3. Large files are read by the
  cheapest model, and only the relevant part comes back.
- Tools and MCP servers are off unless the task named them, and go off again
  when it closes.
- The tier decides the gates. Your sense of how risky it feels does not.
- The scope guard is not an obstacle to route around; it is the plan being
  enforced.
- Problems found outside the task get written down, not fixed.
- The pipeline ends at human approval. Always.