Code Changes

Code Changes

The workflow for going from an issue, pull request, idea, or feature request to shipped code. Follow the phases in order. Analysis always comes first; code comes last.

Each phase has a reference file with the full instructions. Read the reference file when you enter the phase — not before, and never skip it because the phase "looks obvious". Every phase boundary carries a named artifact — see references/artifacts.md — so a phase can be re-entered later (a Verify failure, an escalation answer) without re-deriving context from scratch.

Roles

Assign work based on model capability. The coordinator is not the strongest model — it's the one that stays resident, owns every phase by default, and knows when it's out of its depth.

• Role: Coordinator

  • Capability tier: Capable mid-tier, resident for the whole task
  • Owns: Analysis, plan, delegation, supervision, verification, delivery — by default

• Role: Escalation

  • Capability tier: Strongest reasoning model available; invoked only on trigger
  • Owns: The specific judgment call the coordinator flagged, then control returns

• Role: Implementer

  • Capability tier: Same tier as coordinator, or smaller for trivial edits
  • Owns: Executing one pinned, self-contained task

• Role: Trivial

  • Capability tier: Small, fast model for mechanical, unambiguous edits
  • Owns: Batched renames, config tweaks, typo fixes, doc touch-ups — never judgment calls

Concrete model names per vendor (Anthropic, OpenAI, Google) and how to run the split in Claude Code, GitHub Copilot, Codex, or IDE agents: references/model-tiers.md.

When the current agent already runs at implementer tier, there's no separate delegation step for standard work: plan and execute directly, still following every phase. Escalate to the strongest model only when a trigger fires — see references/escalate.md — never by default and never for a routine judgment call the coordinator is equipped to make itself.

The flow

1. Analyze (references/analyze.md) — root cause and scope, validated against the code, never against the report alone.
2. Plan (references/plan.md) — pinned spec, task split, parallel vs sequential, workspace per task.
3. Delegate (references/delegate.md) — match each task to the right executor, coordinator-tier by default.
4. Supervise (references/supervise.md) — monitor, unblock, and critically review implementer output.
5. Verify (references/verify.md) — quality gates plus functional proof, on the merged state, never delegated downward. A second consecutive failed cycle escalates instead of looping a third time.
6. Deliver (references/deliver.md) — conventional commits and an outcome-first report.

Analyze, Supervise, and Verify each carry an escalation checkpoint — see references/escalate.md — for handing one specific judgment call to the strongest available model without giving up ownership of the phase.

Stop gate: Phase 1 ends with reporting the analysis and proposed approach to the user and waiting for a go. Skip the gate only when the user already gave the go in the request itself ("do it", "fix it and commit", "implement with Sonnet").

Special cases

These are alternate Phase 1 entry points, not a separate track: each one must still produce the same analysis-report artifact defined in references/artifacts.md, so Plan can consume it without knowing which door the task came in through. The rest of the flow (Phases 2–6) applies unchanged. Use references/analyze.md directly whenever the request already implies a fix (its opening section states the exact predicate); reserve these two for their narrower deliverable:

• Pull request review comments → references/pr-review-comments.md
• Issue triage → references/issue-triage.md