autonomous-workflow — Developer Documentation

This file is auto-loaded by Claude Code when working inside skills/workflow/autonomous-workflow/. It captures why this skill exists, how it's shaped, and what to keep in mind when changing it — context that an agent or contributor needs before editing the procedures.

For the runtime instructions the skill follows when executing a task, read SKILL.md and rules/*.md. This file is about design intent, not runtime behavior.

What this skill is

autonomous-workflow is an orchestrator skill. It does not contain the intelligence to plan, code, test, review, or deliver — it contains the sequencing and gates that decide when those things happen and which companion skill handles each one.

Concretely:

• Phase model 0 → 7 — every autonomous task moves through the same phases in order; each phase has a gate that must pass before the next.
• Companion skills — the actual work (planning, TDD, UX review, code quality, doc updates, PR creation, CI fixing) is delegated to specialist skills in this same repo.
• Artifacts — Full Mode produces checks.yaml (the living, executable contract Phase 4 gates on), a lean plan.md handoff document, and walkthrough.md in .agent/{branch}/ so a fresh Claude session can pick up where another left off. Plan snapshots (plan.v{N}.md) are opt-in, not default (see the artifact-lightening design intent below).

If you find yourself adding domain knowledge to this skill (how to write a React component, how to fix a TypeScript error, how to write a good commit message), you're in the wrong place — that knowledge belongs in a companion skill (ux, tdd, create-pr, etc.) which this skill invokes.

Why this skill exists

LLM agents tend to fail in three predictable ways during long-running tasks:

1. Skip validation — start coding before they understand the requirement.
2. Lose context mid-task — a session ends, a new one begins, the new session has no memory of decisions made.
3. Burn tokens on hallucinated fixes — get stuck on a failing test and try increasingly speculative fixes for 20+ iterations.

autonomous-workflow exists to address all three:

1. Phase 0 (Validation) is mandatory — the agent must confirm understanding with the user before any code is written.
2. checks.yaml is the living contract; plan.md is the handoff artifact in Full Mode — both generated by the aw-create-plan companion. checks.yaml carries the executable acceptance criteria Phase 4 gates on and cannot go stale silently (it passes or fails against reality on every loop). plan.md carries the decisions, requirements, and approach a fresh session needs to resume cold after compaction or a session boundary — its evidence-backed payoff is cross-session resumption, not ceremony, so it is tiered into an always-on Core and include-when-needed Extended sections and the executor writes drift back into it (Phase 3) so it stays honest. See references/anthropic-architecture-research.md §5 for the empirical basis (and the honest gaps), and the artifact-lightening design intent below.
3. Phase 4 stuck-loop has a mode-aware hard cap — 3 iterations in Lite Mode, 5 in Full Mode. At the cap, the agent runs confidence(analysis); if confidence is below 90% the workflow re-traces the execution path, regenerates the affected plan.md section, and resumes ONCE more before mandatory user escalation. No more 20-iteration token burns.

Everything else in this skill (companion invocation, mode detection, artifacts, parallelization) is in service of those three goals.

Architecture at a glance

skills/workflow/autonomous-workflow/
├── SKILL.md                    # Thin index. Frontmatter + phase table + companion table.
├── README.md                   # User-facing install / customize / migrate docs.
├── CLAUDE.md                   # ← this file. Developer docs.
├── install.sh                  # Symlinks templates into ~/.claude or ./.claude.
├── rules/
│   ├── companion-skills.md     # Registry of all optional companions + disable links.
│   ├── prerequisites.md        # gh (required) + gw (recommended) install + native fallback.
│   ├── overview.md             # High-level narrative for orientation.
│   ├── phase-0-validation.md   # Each phase rule is self-contained — agents
│   ├── phase-1-planning.md       load on demand. They can include the
│   ├── phase-2-worktree.md       SKILL.md + companion-skills.md as context
│   ├── phase-3-implementation.md and not need any other phase rule.
│   ├── phase-4-testing.md
│   ├── phase-5-documentation.md
│   ├── phase-6-pr-creation.md
│   ├── phase-7-ci-gate.md      # Replaces phase-7-cleanup.md from v2.
│   ├── artifacts-overview.md   # The artifact pattern (plan.md, checks.yaml, walkthrough.md).
│   ├── decision-framework.md   # Branch naming, test strategy, mode detection.
│   ├── error-recovery.md       # Common failures and recovery procedures.
│   ├── parallel-coordination.md# Sub-agent fan-out and multi-agent handoff.
│   ├── safety-guardrails.md    # Hard limits, validation checkpoints.
│   ├── smart-worktree-detection.md # Fuzzy-match task to existing worktree.
│   ├── planner-executor-handoff.md # Handoff contract between the brief (`aw`) and `aw-executor`.
│   ├── corrections.md          # The corrections a capable model needs on Full runs; read before the brief.
│   ├── diagnostic-surface.md   # Phase model + failure taxonomy + guards table consumed by `/create-skill diagnose autonomous-workflow`.
│   ├── self-improvement-loop.md # Episodic-lessons fast tier (LoreKit loop::aw-lessons) + promotion to diagnose. Read Phase 1; write Phase 4/7.
│   └── _template.md            # Boilerplate for new rule files.
├── aw/
│   └── SKILL.md                    # THE DISPATCHER. A nested skill (like aw-tester-chrome), not an agent —
│                                   # opt-in entry, tier routing, universal lessons loop. Invoked /aw.
├── templates/
│   ├── aw-executor.agent.md        # aw-executor agent (phases 3-7, executes the brief). Linked by install.sh as aw-executor.md.
│   ├── _deprecated-single-agent.md # DEPRECATED — kept for backward compat only. Not linked.
│   └── routing.rule.md             # Auto-routing rule (linked into ~/.claude/rules/).
└── references/
    ├── autonomous-workflow-complete.md      # Full end-to-end walked example.
    ├── error-recovery-scenarios.md          # Concrete error → recovery transcripts.
    ├── iterative-refinement.md              # Worked example of stuck-loop recovery.
    ├── self-improvement-walkthrough.md      # Worked example: a lesson's full lifecycle (capture → recur → promote).
    ├── anthropic-architecture-research.md   # Verbatim Anthropic citations + design mapping.
    └── planning-quality-research.md         # 2024–2026 web-research pass on planner quality (anti-reinvention, spec fidelity, clarify-or-abstain, executable checks); evidence base + decision record for the v3.15 plan-quality gates.

The split between SKILL.md (lean index, always in context), rules/ (loaded on demand), and references/ (loaded only when an agent wants worked examples) is deliberate — context budget is finite, and most phases only need their own rule file plus companion-skills.md.

The companion-skills pattern

The defining design decision in v3 is that the workflow is modular by default. Companions are not hard dependencies; they're advisory invocations.

How a companion is wired

A phase rule contains a section like:

## TDD Trigger

When the task involves pure logic, business rules, or "test-driven" was
requested, invoke:

    Skill("tdd")

If the skill is unavailable, log one line and continue:

    - [TIMESTAMP] Phase 3: tdd — skipped (not installed)

Three things matter:

1. The trigger condition is concrete — file globs, keyword match, file counts. Not "if the agent feels appropriate." Subjective triggers leak judgment into runtime and make behavior non-reproducible.
2. The Skill() invocation is wrapped in graceful degradation — if the companion isn't installed, the workflow logs a one-liner and continues. Never block on a missing companion. The only exception is confidence at Phase 1, which is the load-bearing safety gate.
3. The section anchor matches the "Disable by" link in rules/companion-skills.md. If you rename the heading, update the link target — GitHub anchors are slug-derived from headings (with . stripped, so ## Claude.md Trigger becomes #claudemd-trigger not #claude-md-trigger).

Adding a new companion

1. Confirm the companion skill exists in agent-skills.git/skills/<name>/.
2. Add a row to the registry table in rules/companion-skills.md. Include the trigger condition (concrete), args, and the disable link.
3. Add the invocation in the relevant phase-N-*.md rule, with an ## Anchor heading matching the disable link target.
4. Verify the workflow still degrades gracefully when the new companion is missing (uninstall the companion locally, run a task, confirm it skips).
5. Update the install commands in SKILL.md, README.md, and install.sh if the new companion should be in the recommended install set.

Removing a companion

1. Delete the row from rules/companion-skills.md.
2. Delete the invocation block in the relevant phase rule.
3. (Optional) Note in CHANGELOG.md so users know.

Why some companions can't be disabled

No companion is non-removable. The Full tier's one mandatory gate is the deterministic brief validation in aw/rules/full-tier.md plus the sealed run-checks.mjs gate, and neither is a companion — they cannot be uninstalled.

Skill companion for the review pass

Every tier reviews once, locally, before the PR: review-loop in local mode (branch-reviewer → apply → polish simplify, zero GitHub calls), run by create-pr Step 5.5 on Micro/Lite and by aw's Full Step 3. Nothing is posted to the PR unless the user passes --pr-review, which turns on create-pr Step 6.5's one posted pass; Phase 7 runs no review. The rule lives in aw/SKILL.md#review. Detection is implicit — Skill() raises if the skill is missing; catch and log. The full registry entry, dispatch contract, and rationale live in rules/companion-skills.md#agent-companions and aw/SKILL.md#review.

The feature-pr-verifier agent is dispatched as subagent_type: feature-pr-verifier by the aw dispatcher at PR open, not by Phase 7 after CI green — that trigger was never reached in the analysed executor transcripts: the executor's done-condition needs Phase 7 to have run once, not CI to be green, and it holds no dispatch tool of its own. It is the only remaining agent companion in the registry. When adding new agent companions, mirror the same pattern: dispatch from the session that holds the dispatch rung, detect by capability (the dispatch tool accepts the agent type — never a file at an install path), and report a miss by name as not run (<reason>) rather than skipping it.

The .agent/ artifact directory

Artifacts (Full Mode plan.md and walkthrough.md) live in .agent/{branch-name}/ inside the worktree. Not in .gw/ (that's the gw CLI's territory for its own config). Not on the main branch (artifacts are worktree-scoped — committing them to main creates context confusion).

The directory name .agent/ (singular) was chosen to align with the ~/.agents/skills/ cross-tool discovery convention used by Codex, Cursor, OpenCode, and other Agent Skills–compatible clients. Naming consistency across the ecosystem is the goal — so other tools can adopt the same artifact location if they want to.

Earlier versions used .gw/ because the workflow was tied to gw-tools.git. That coupling is gone in v3. The .gw/ reference now appears only in migration notes and "never use this for artifacts" reminders.

The mode-aware stuck-loop cap (3 / 5) and auto-replan

The two most important numbers in this skill are 3 (Lite cap) and 5 (Full cap), and the most important pattern is auto-replan-then-escalate.

Earlier versions of the workflow let agents iterate on a failing test for up to 20 attempts before stopping. Empirically, the agent rarely converges past attempt 3 on the same area — when it does, it's almost always wrong (it's fixing symptoms, not root cause). Continuing past the cap means burning tokens on hallucinated fixes that the user is going to throw away anyway.

v3.2 split the cap by mode (Lite is for simpler tasks; Full Mode tasks are more complex and benefit from one extra attempt) and added an auto-replan guard before mandatory user escalation, drawing on the Plan-and-Act and IoRT literature on replanning when stuck.

The protocol:

iteration_cap = 3 (Lite Mode) | 5 (Full Mode)
auto_replan_used = False

while not all_tests_pass:
  iterations_on_same_area += 1

  # Before each iteration ≥ 2: lightweight self-reflection (R5)
  if iterations_on_same_area >= 2:
    if not (attempt_meaningfully_different and understood_prior_failure):
      goto: stuck_loop_detection   # bias toward replanning early

  if iterations_on_same_area == iteration_cap:
    stuck_loop_detection:
      Skill("confidence", "analysis")
      if confidence_score >= 90%:
        → escalate to user with findings
      else if not auto_replan_used:
        re_trace()   # entry → exit; re-state the root cause
        Update affected plan.md sections
        iterations_on_same_area = 0
        auto_replan_used = True
        resume Phase 4 ONCE MORE
      else:
        → mandatory user escalation

Phase 4 testing is where this fires most often, but the same logic applies anywhere the agent is iterating on the same problem.

When changing the cap numbers, update all of:

• rules/phase-4-testing.md (## Stuck-Loop Detection)
• rules/safety-guardrails.md (## Stuck-Loop Limit (Phase 4))
• rules/companion-skills.md (## Stuck-Loop Protocol)
• rules/error-recovery.md
• rules/overview.md
• SKILL.md Core Principles + companion table (Phase 4 confidence trigger)
• README.md Key Principles + companion table (Phase 4 confidence trigger)
• templates/aw-executor.agent.md — How to work (stuck loop)
• templates/_deprecated-single-agent.md — DEPRECATED but update for consistency
• references/iterative-refinement.md — the worked stuck-loop example referenced from phase-4 must reflect the canonical limits (the "Different rule for stuck-loop iteration" callout under "When to Stop Iterating").

Otherwise the limits drift across surfaces and the agent gets contradictory instructions.

Tier detection (Micro / Lite / Full) and the aw dispatcher

Every task starts with tier detection. The decision changes which artifacts are produced, which companions run, and whether aw writes a brief and hands it to aw-executor.

The criteria live in SKILL.md Step 1 and nowhere else — see "exactly one home" below. What this section owns is the shape of that decision, which is what a reader of the design intent needs:

• It is a four-question walk, not a lookup. The first yes selects the tier, and the table below the walk only describes its outcomes — where the two seem to disagree, the walk wins. That asymmetry is stated in Step 1 itself because the tier-routing L2 suite's misses were readers resolving the table against the walk and picking the table.
• Complexity is the primary signal; file count is the tie-breaker. Questions 1 and 2 (architectural / cross-cutting; unfamiliar code or an unknown cause or location) fire before the 4+-file question, so an investigation whose eventual patch might be one line is still Full — tiering on the guessed size of the patch is exactly what those two questions exist to prevent.
• Micro requires one file and nothing to reason about. A one-file change carrying non-trivial logic is Lite. The OR in question 4 is load-bearing.
• Who runs it: Full is a brief plus sealed checks, worked in the caller's session by aw; Lite is single-pass from a short plan.md brief; Micro is single-pass with no artifacts.

When in doubt, choose the heavier tier. Micro/Lite are for genuinely small changes — not for "the user said it's small." Phase 0 and Phase 2 are mandatory in every tier, Micro included.

The aw dispatcher (aw/SKILL.md — a nested skill, not an agent) is the opt-in, single entry point that owns this decision: it reads aw-lessons, detects the tier, and routes (single-pass for Micro/Lite, a brief plus sealed checks worked in the caller's session for Full). It replaced the old "routing rule dispatches the planner first" behavior, which sent Lite tasks to the planner anyway. See the two design-intent sections below.

The tier table has exactly one home: SKILL.md Step 1. The dispatcher links it rather than restating it. While the dispatcher was an agent it carried an inline copy — an agent boots cold, so having the rows in the prompt was worth something — and the copies were kept honest by a byte-comparison L1 check. A skill runs in the caller's context with SKILL.md already loaded, so the copy buys nothing and can only rot.

Phase 0 and Phase 2 are mandatory regardless of mode. Phase 5 docs update runs in both modes (the self-improving doc loop is cheap and matters for small changes too — they still drift docs).

Parallelization

Three places benefit from sub-agent fan-out:

1. Phase 1 research (Explore sub-agents per package/concern) — when the task is complex, parallel exploration finds context faster than sequential reads. See [rules/phase-1-planning.md#parallel-research].
2. Phase 3 implementation — controlled fan-out when slices are file-disjoint (cap 3 concurrent sub-agents). Each sub-agent MUST receive the Sub-Agent Resource Discipline embedding. If the task does not decompose cleanly, keep Phase 3 sequential. See rules/parallel-coordination.md#sub-agent-resource-discipline.
3. Phase 7 CI fixes (ci-auto-fix sub-agents per failed check) — cap at 2 handoffs per PR; each sub-agent has its own retry budget. See [rules/phase-7-ci-gate.md#parallel-ci-fixes] and [../create-pr/SKILL.md] Step 8.

Things to keep invariant

When editing this skill, do not break these — they're load-bearing:

• Phase 0 and Phase 2 are mandatory. Validation and worktree isolation are not optional.
• confidence at Phase 1 is non-removable. It's the only companion that must always run.
• Companions degrade silently. Never make the workflow block on a missing companion (except the one above).
• checks.yaml is the living contract; plan.md is the handoff document. Phase 4 gates on the checks (they self-validate against reality); plan.md is a self-contained-but-lean handoff artifact, not an exhaustive knowledge base. The executor writes decision/AC drift back into plan.md so it does not go silently stale. Plan snapshots (plan.v{N}.md) are opt-in in aw-create-plan (the snapshot arg), not written by default.
• Anchors must match disable links. Every ## Anchor heading in a phase rule that's referenced from companion-skills.md must produce a slug matching the link. GitHub strips . from slugs (so ## Foo.bar → #foobar, not #foo-bar).
• Artifact paths are .agent/{branch}/, never .gw/{branch}/. The only acceptable mention of .gw/ is a migration note or "never use this" reminder.
• A GitHub access path is required; gh is one of two, and gw is optional with a native fallback. The workflow must never block on a missing gw — Phase 2 detects it at Step 0 and falls back to native git worktree with a one-time warning. Nor may it block on a missing gh: that binary is absent in Claude Code cloud sessions, where mcp__github__* is the path, and aw-executor already carries those tools in its tools: frontmatter. Phases 6–7 resolve ACCESS_PATH (gh | mcp | none) once via agents/shared/rules/github-access.md — never by which gh, never by gh auth status. With none, GitHub steps degrade and are named in Degraded:; they are never reported as done. Do not restate that file's verb mapping in a phase rule — link it.
• The system-prompt for the agent template stays lean. It references SKILL.md for procedures rather than duplicating them. If the agent template grows beyond ~250 lines of system prompt, it's drifting.
• The diagnostic surface is the contract that makes this skill diagnosable. Removing or breaking rules/diagnostic-surface.md silently downgrades /create-skill diagnose autonomous-workflow to its fallback (inferred from SKILL.md H2 sections) — fidelity drops and the diagnoser cannot reason about hard invariants. Treat the surface like companion-skills.md: every change to a phase, gate, taxonomy class, or load-bearing invariant must update the surface in the same PR.
• Sub-Agent Resource Discipline is non-relaxable. Every sub-agent dispatch block must embed the resource-discipline sentinel line. Whole-project tsc, lint, build, and test commands are forbidden inside sub-agents and reserved for orchestrator-only boundaries (Phase 4 Step 6, Phase 6 pre-PR). See rules/parallel-coordination.md#sub-agent-resource-discipline.
• aw is a thin, opt-in router, and it is a skill. It detects the tier and routes (single-pass for Micro/Lite, a brief plus sealed checks worked in the caller's session for Full) and owns the universal lessons loop. It must not accrue domain knowledge, must not force Full on light tasks, and must not silently wrap casual edits. It must not regrow a tools: block, a model: line, or an inline tier table — see the shape design-intent section. On Full, aw writes the brief and works it in the caller's session; it dispatches aw-executor only when the user asks for a background worker or parallel briefs. With no dispatch tool, the review and the PR verifier report not run, never a self-review — it never downgrades to Lite.
• Episodic lessons are advisory-only. An aw-lessons lesson biases the plan but never silently changes a gate, skips a phase, or alters a cap. The only path from a lesson to changed behavior is a confidence-gated, user-approved diagnose apply, and promotion requires seen_count >= 3 (or an explicit structural tag). Never auto-apply lessons to behavior or promote on one run. See rules/self-improvement-loop.md#entrenchment-guards-load-bearing.
• checks.yaml definitions are executor-immutable; gaming a check is never a fix. The executor flips status: (and amends run:/setup: only with a logged check-run-amended entry); id:/requirement:/ears:/expect: are owned by the brief writer. The four forbidden strategies (modify checks/tests, overload comparisons, record/replay state, special-case inputs) and the unsatisfiable abort affordance are non-relaxable. All-green checks never waive the suite, confidence, reviewer, or Phase 7 verification. See rules/phase-4-testing.md#executable-checks-loop.
• A blocking missing-information gap halts even under --no-confirm. The pre-authorization grant waives the Phase 0 confirmation wait, never the missing-information gate. See rules/phase-0-validation.md#step-3c-missing-information-gate.

Diagnose participation — design intent

This skill does not implement Diagnose Mode — it implements the diagnostic surface contract consumed by /create-skill diagnose. The retrospective self-improvement loop itself (the seven-step procedure, the confidence gate, the report format, the apply / PR flow) is owned by create-skill so the same procedure can target any skill in the repo.

The split landed in v3.7. Before that, --diagnose was a flag on this skill, with a hardcoded seven-step procedure baked into rules/diagnose-mode.md. When fix-bug and other workflow skills started needing the same retrospective capability, the procedure had to either be duplicated per-skill or generalized. We chose generalize — the engine moved to create-skill (which already has authoritative knowledge about skill quality), and per-skill knowledge moved into a declared rules/diagnostic-surface.md per consumer.

What this skill still owns:

1. Phase model 0 → 7 — declared in rules/diagnostic-surface.md.
2. Failure taxonomy (F1 + F-novel, append-only) — same file.
3. Existing-guards-per-phase table — same file.
4. Hard invariants the diagnoser must not propose to weaken — same file.
5. Source root the diagnoser writes against — skills/workflow/autonomous-workflow/.

What create-skill owns:

1. The seven-step procedure (collect → classify → attribute → propose → gate → write → apply / PR).
2. The output report format.
3. The confidence(analysis) ≥ 90 % gate before --apply.
4. The hard rules: one proposal per report, earliest-phase wins, mechanical > judgment, never weaken gates.

When changing a phase, gate, taxonomy class, or load-bearing invariant in this skill, always update rules/diagnostic-surface.md in the same PR — otherwise the diagnoser walks a stale matrix and either misses real gaps or proposes redundant checks.

Two-tier self-improvement — design intent

v3.10 added a fast tier of self-improvement to complement the existing diagnose slow tier. The motivation: diagnose is the right mechanism for turning a failure into a permanent skill-source change, but it (a) only fires when a human invokes it and (b) starts cold from a single session with no record that the same failure happened before. The fast tier fills both gaps.

The fast and slow tiers are connected by a recurrence gate: a lesson reaching seen_count >= 3 (or tagged structural) is promotion-eligible. The scope of the lesson determines the promotion target: a global lesson promotes to the skill's source (every consumer benefits via the next install); a repo:: lesson promotes to the cwd repo's own rules (every teammate working in that repo benefits via the next git pull). The workflow surfaces a one-line suggestion in either case — it never acts silently. The full contract, lesson schema, classification rule, scope mapping, and the entrenchment guards live in rules/self-improvement-loop.md.

Why a fast tier that doesn't change behavior? Because the dominant risk in any reflective-memory loop is self-reinforcing error (Reflexion's documented failure mode; the SSGM governance literature). Letting a single run rewrite the skill is exactly that failure. The fast tier captures lessons cheaply and reversibly; only recurrence-proven lessons earn a permanent, human-approved change. The fast tier is a fully optional companion — disconnect LoreKit's memory.* tools and it degrades to nothing while diagnose keeps working.

Design rule for the loop: keep domain knowledge out of this skill. The lessons themselves live in LoreKit, not in the workflow's rules. The workflow only owns when to read / write / promote — the same orchestrator discipline that governs every other companion.

The dispatcher is a skill, not an agent — design intent

v3.23 converted aw from an agent (templates/aw.agent.md, symlinked to ~/.claude/agents/aw.md) into a nested skill (aw/SKILL.md, invoked /aw). The routing decision, the tier table, the Micro/Lite single-pass path, the lessons loop, and the single-context Full fallback are unchanged — only the shape moved. aw-executor remains an agent.

Why. This repo wrote the deciding test before aw existed, in references/anthropic-architecture-research.md §2.2:

any future proposal to add a third agent must demonstrate a third independent context — not a third role. If the third agent would re-read the same plan.md and the same diff that the executor already has, it is a skill, not an agent.

aw was that third agent, and its context boundary is conditional: real when the routing rule fires mid-conversation (Micro/Lite edit churn stays out of the user's window), absent when a developer opens a session specifically to run /aw — where there is nothing to protect, and the single-threaded-continuity argument this skill already cites for making Micro/Lite single-pass argues against isolating them at all. aw-planner / aw-executor pass the same test unconditionally (the planner's exploration history is genuine dead weight for the executor, and plan.md is a real cold-read handoff), which is why they were not touched.

Three costs the agent form was paying, all removed:

1. It burned the delegation rung the executor needs. aw held Task; aw-planner / aw-executor did not. Three documented behaviours were therefore unreachable by construction — the Phase 1 parallel Explore fan-out, the Phase 3 file-disjoint fan-out (cap 3), the Phase 7 ci-auto-fix fan-out (cap 2) — and so was create-pr's Phase 6 review-loop pass, which is what produced the NOT REVIEWED draft PRs recorded in aw-lessons (executor-context-lacks-subagent-dispatch-skips-review-loop, seen_count 2). With the dispatcher in-context, both agents are dispatched from the top-level session — the rung that observably kept Task — so v3.23 grants them Task. Belt-and-braces: aw still re-runs review-loop itself when the executor reports the pass as skipped.
2. A duplicated tier table with a CI guard to police it. L1 Check B byte-compared aw.agent.md's copy against SKILL.md Step 1. The duplication was an artifact of the shape, not of the domain. There is now one copy and a link to it, so there is nothing to compare.
3. A triplicated tool grant. The agent enumerated 4 LoreKit + 11 GitHub tools with two paragraphs explaining that sub-agents inherit neither MCP tools nor gh. A skill inherits the caller's grant.

Costs accepted, stated plainly:

• No model: pinning. The agent pinned model: opus; a skill runs on whatever the session is using.
• Micro/Lite transcripts land in the user's window. Previously isolated. This is the conditional-boundary trade above, taken deliberately.
• No tools: block. aw cannot grant itself anything. Its obligation is to degrade visibly instead — a missing memory.*, gh, or GitHub MCP grant is named in the terminal contract's Degraded: line, never silently swallowed.
• Existing installs get a dangling ~/.claude/agents/aw.md until they re-run install.sh, which removes it (the same legacy-symlink cleanup the pre-aw- namespace rename used). Deleting the agent file outright, rather than leaving it deprecated in place, is deliberate: two aw entries with near-identical auto-trigger descriptions is a worse failure than a dangling symlink.

Design rules that keep this from rotting:

• Do not re-add a tools: block, a model: line, or an inline tier table to aw/SKILL.md. Each one is a step back toward the agent form; the first two are meaningless in a skill and the third can only rot.
• Do not convert aw-executor to a skill. It passes §2.2 on its own merits: it is the background worker for an explicit background or parallel request, with the brief as its cold-read input. The default Full path works in the caller's session and dispatches only the fresh-eyes reviewer.
• Do not reintroduce a planning agent. The Full brief is written in the caller's context, which holds the conversation; a separate planner spent ~45 minutes on a 333-line plan in a three-way comparison and added nothing the brief and the corrections do not — see aw/references/dispatcher-rationale.md.
• aw still must not accrue domain knowledge. The ~200-line ceiling and the thin-router invariant below apply unchanged — the shape changed, the discipline did not.

One natural-language entry point — design intent

v3.24 made aw the sole natural-language destination. Before it, two skills competed for the same request: aw's description advertised "autonomously", "end-to-end", "in a worktree", and the parent autonomous-workflow's description advertised near-identical phrasing ("autonomously", "independently", "end-to-end", "in isolation", "take care of this"). The harness matches descriptions; nothing arbitrated between them.

The cost of losing that race is not cosmetic. A request landing on the parent runs the phase machinery with tier detection skipped (so a Micro typo fix pays the Full brief→executor handoff, or a Full task runs single-pass with no plan.md and no sealed checks) and the universal lessons loop skipped (the read and write were hoisted to the dispatcher in v3.12 precisely so every tier contributes). Those two are the dispatcher's entire job, so bypassing it silently un-does the v3.12 design.

The fix is one-directional: the parent's description now states what it is (the phase machinery), states that it is not the entry point, and names aw — while quoting no trigger phrase and making no Triggers on / Use when claim. /autonomous-workflow still runs the machinery directly for anyone who wants to bypass tier detection deliberately; the marker in the repo inventory moved auto → / to say so.

Why the routing rule still carries the full trigger list, even though it now duplicates aw's description: frontmatter cannot link a canonical home the way aw/SKILL.md links the tier table, so one of the two surfaces has to hold the words — and this file is also the live rubric the L2 aw-should-trigger suite reads (scripts/eval/l2.mjs passes the whole file), so slimming it to a pointer would leave that suite with no vocabulary to decide trigger on. The duplication is forced by the two consumers, so it is kept honest by review instead of eliminated.

Two properties keep it honest:

1. The parent's description quotes none of the trigger vocabulary and makes no Triggers on / Use when claim. Only the claiming forms (a quoted phrase, or those two clauses) count, because the sentence that fixes the problem — "a natural-language request to do work autonomously … belongs to the aw skill" — necessarily names the words it is disclaiming.
2. Every phrase aw advertises appears in the routing rule. Whether a phrase actually routes is behaviour, measured by the L2 aw-should-trigger suite, not by a text-sync check.

Design rules that keep this from rotting:

• Never add trigger vocabulary back to the parent's description. If a phrase should fire the workflow, it goes in aw's description and the routing rule, in the same change.
• Never slim the routing rule's positive trigger list to a pointer. It is the L2 rubric; a pointer would silently gut the aw-should-trigger suite.

Adaptive dispatch (the aw dispatcher) — design intent

v3.11 added aw — a thin, opt-in dispatcher — to resolve two tensions at once. (It shipped as a third agent and became a skill in v3.23; the section above covers that move. The two tensions below, and the design rules that follow, are shape-independent and unchanged.)

1. One entry point, but not always-heavy. Developers wanted a single thing to invoke. But "always write a brief and dispatch an executor" is the wrong answer: the research is explicit that always-planning wastes compute and degrades long-horizon performance (Learning When to Plan, arXiv 2509.03581), and single-threaded continuity beats the multi-agent handoff for simple/sequential work (Cognition's context-engineering argument; single-agent ≥ multi-agent under equal token budgets). So aw is adaptive: it detects the tier and only pays the brief→executor handoff cost on Full, where context isolation + a resumable plan.md actually earn it.
2. Universal self-improvement without universal planning. The fast-tier lessons loop only helped tasks that ran the Full phases. Hoisting the loop's intake-read and exit-write to the dispatcher makes every tier contribute and benefit — even a Micro typo fix — which is the actual goal ("more stable agents after more runs"). Planning depth and learning coverage are now decoupled.

Design rules that keep this from rotting:

• aw stays thin. It routes and owns the loop. It must not accrue planning/coding domain knowledge — that lives in the skill, companions, rules/corrections.md, and the executor. The target is ~200 lines of body (create-skill anti-pattern S1 is a god-skill). This target is currently breached and has been for several versions — the dispatcher is ~294 body lines as of v3.23 (it was ~274 as an agent), because each of v3.19 single-context Full, v3.21 follow-ups, and v3.23 skill-semantics + review-recovery added a section without one being removed. Recorded rather than quietly re-baselined: the next contributor to touch this file should push down, and the reduction most likely to pay is moving the single-context Full procedure into a rule file the way the lessons loop already is.
• Opt-in, not a wrapper. aw runs because the user phrased autonomous work or invoked /aw. It must not intercept casual single-file edits, questions, or interactive coding. The routing rule's exclusion list enforces this.
• Full works in the caller's session. On Full, aw writes the brief, works to its sealed checks itself, and dispatches one branch-reviewer that did not write the code; aw-executor is dispatched only for an explicit background or parallel request. Never route Micro/Lite through the executor (pure handoff overhead). Without a dispatch tool the review is reported not run, never replaced by self-review. It is never a license to skip an available dispatch — the check is "can I dispatch?", not "do I feel like it?".
• "Can I dispatch?" is a capability question, and the tool's NAME is not the answer. The Claude Code CLI calls it Task; the Claude Agent SDK harness behind Claude Code on the web and in cloud sessions calls it Agent. Every availability check across aw, review-loop, and pr-review therefore asks whether any available tool dispatches a sub-agent, never whether one spelling is present. A name check fails in the direction that hides itself: it routes a fully dispatchable session into the single-context fallback and the degraded review path, both of which report as legitimate outcomes. This is not the rejected capability probe below — it decides nothing about whether to run a companion, it only reads the name of a tool the context already holds, and every branch it feeds fails closed (toward a named NOT REVIEWED, toward single-context Full), never toward a silent skip.
• Micro reuses the Lite phase path. Micro is a routing tier, not a fourth set of phase rules — it follows Lite's phase behavior with planning and quality companions skipped. This keeps the phase rules from needing a third column.

Plan-quality gates + executable checks — design intent

v3.15 added four planning-quality mechanisms, each mapping one researched failure mode to the earliest phase that can catch it (full evidence base: references/planning-quality-research.md):

Design rules that keep this from rotting:

• The brief's Core is six headings. plan.md's Core is Task, Requirements, Guardrails, Acceptance Criteria (Definition of Done), Turn Cap, and File Changes (L1 G130a runs the executor's bail grep against the template); everything else is Extended and Full-tier only. Traceability is embedded in the Acceptance Criteria (AC-{n} + covers:), and the survey is an Extended section with a deterministic trigger. The executor's bail check also accepts fix-bug's fast-lane plan, which still carries the legacy eight headings (L1 G130b), and the Definition of Done is the one line run-checks.mjs prints (L1 G130c).
• checks.yaml is additive, never a replacement. It mechanizes the Acceptance-Criteria sprint contract; the suite, confidence, reviewer, and Phase 7 verifiers are unchanged. The check-integrity rules exist because verifier-driven loops are demonstrably gameable (models special-case test inputs and edit tests to force green; an explicit abort affordance is the strongest counter-lever, and it must be prompted for explicitly because Claude under-uses it by default — see research §5).
• Backward compatible by absence. No checks.yaml → the executor logs one line and gates on ACs by judgment (pre-v3.15 behavior). Plans without AC-{n} IDs (fix-bug fast-lane, legacy) skip rule #11 with a logged note.
• The brief pins contracts, not implementations. ears + expect are exact; run is a draft the executor finalizes (logged). Pinning full check bodies upfront would re-introduce the cascading-error failure mode (§2.8).

Artifact lightening — design intent

v3.18 rebalanced the Full-Mode artifacts around one distinction: a written plan does two different jobs, and only one is well-evidenced.

1. Within-run handoff (brief → executor). The executor is a fresh agent with no access to the caller's context, so it needs a self-contained plan.md to start. This is load-bearing — it is why the handoff exists (see §2.3 / §2.12 of references/anthropic-architecture-research.md).
2. Cross-session resumption (a later session picks up cold). This is the benefit the plan file is usually justified on, and it is the weakest-evidenced one — §5.2 concedes the marginal benefit over in-context planning is unproven for a task that finishes inside one un-compacted window.

The 2024–2026 practitioner + research consensus (Cursor's ephemeral-by-default plans, planning-with-files' consumed-every-turn plan, Kiro/spec-kit's ceremony-is-overkill-for-small-tasks finding, Fowler's spec-anchored tier, and the stale-plan drift literature) points at four moves, all adopted here:

• checks.yaml is the primary, living contract. Prose rots faster than reality; an executable check cannot drift silently. So the framing everywhere now leads with checks, and the VS Code extension surfaces checks.yaml first, expanded, above plan.md.
• plan.md is a lean handoff document, not a knowledge base. Kept self-contained (the cold-read guarantee the brief validation enforces), but the brief is not padded against every hypothetical question — the executor discovers details while it works, and the user can be asked.
• The executor consumes and repairs the plan. The dominant failure of a written plan is going write-only and stale, so Phase 3 now mandates a drift write-back: when a decision or AC changes mid-run, update the affected plan.md section (and its checks.yaml entry), not just the Progress Log.
• plan.v{N}.md snapshots are opt-in. .agent/ is gitignored per-developer scratch, so an immutable version chain is a second, weaker VCS for the same file — directory noise plus a redundant write per iteration, rarely re-read, with no measured task-success benefit (§5.4). aw-create-plan writes only plan.md by default; the snapshot arg opts back into the chain.

Design rules that keep this from rotting:

• Do not drop the cold-read guarantee. plan.md must stay executable-from-cold for the Full-tier handoff — a lean brief is never a license to write an incomplete one.
• checks.yaml integrity is unchanged. Elevating it to "the contract" does not relax the executor-immutable / no-gaming / unsatisfiable-abort rules.
• Snapshot opt-in is additive, backward-compatible. Snapshot mode reproduces the pre-v3.18 plan.v{N}.md behavior exactly; the extension already renders the versions group only when snapshots exist, so default runs simply show none.

Confidence-gated autonomous action — design intent

The pattern v3.6 established remains: autonomous actions that change code or skill source are allowed inside the loop, but only behind a confidence gate. Two instances exist today; in v3.7 the first relocated but the contract is unchanged.

Both instances share three contracts:

1. No autonomous action without a passing gate. Below threshold, the action is refused and the existing escalation path (stuck-loop, user prompt, or report-only artifact) takes over.
2. Mechanical post-checks complement the judgment gate. Confidence scores intent; mechanical checks (build, tests, mutation re-verify) confirm the action was implemented correctly.
3. Human override is explicit, not silent. Manual flags (--no-confidence-gate, user-confirmation prompts) exist so a human can deliberately bypass the gate — but the autonomous loop never sets them.

When adding a new self-modifying action, follow the same template: choose a confidence mode, pick a threshold (default 90 %), gate the action, and document the failure cascade. Resist the urge to skip the gate "just this once" — the agent's gates are the only thing standing between autonomy and going rogue.

Working on the skill

Editing a phase rule

1. Read SKILL.md and rules/companion-skills.md first to refresh the contracts.
2. Make the change. Keep the rule file self-contained — an agent should be able to load this one file plus the two above and execute the phase correctly.
3. Verify anchors still match disable links (grep -E "phase-.*\.md#" rules/companion-skills.md).
4. If the change affects companion behavior, update rules/companion-skills.md in the same PR.

Editing the dispatcher

The dispatcher is aw/SKILL.md — a nested skill, discovered by scripts/sync-symlinks.sh's recursive walk and linked as ~/.claude/skills/aw (the same treatment aw-tester-chrome gets; install.sh also links it directly in --development mode). It is edited like any other skill, and it is not an agent — do not give it a tools: block or a model: line, and do not restate the tier table in it. See the shape design-intent section for why. It must stay thin (router + loop only) — see the ~200-line body target and its current breach under design rules.

Editing the agent templates

aw-executor.agent.md and aw-tester.agent.md are what get symlinked into ~/.claude/agents/ as aw-executor.md and aw-tester.md by install.sh (the aw- prefix is the autonomous-workflow namespace — keeps the agents grouped together and unmistakable when listed alongside unrelated agents). Keep both lean — they should reference SKILL.md and rules/companion-skills.md rather than duplicate their content.

The agent name: frontmatter values must match the symlinked file basenames (aw-executor, aw-tester) — Claude Code dispatches by the frontmatter name, and the routing rule references it by the same string. If you ever rename the namespace, update all four (frontmatter name, install.sh symlink target, routing rule dispatch, and every doc reference) in the same PR.

aw-executor holds Task so its documented fan-outs — research and Phase 3 file-disjoint slices (cap 3), aw-tester spec runs, Phase 7 ci-auto-fix, and create-pr's review-loop pass — are reachable at all. It carries no model: line, so it runs on the caller's model. Do not remove the grant without also removing those behaviours from the phase rules; they were dead letters before.

The deprecated _deprecated-single-agent.md (single-agent) is still present for backward compat but is not linked by install.sh. Do not add new behavior there.

Testing changes end-to-end

There's no automated test suite for this skill. The validation pattern is:

1. Symlink the skill locally (bash install.sh --global or --project).
2. Run a small Lite Mode task — verify Phase 0 + Phase 2 + Phase 5 + Phase 6 companions all fire correctly.
3. Run a larger Full Mode task — verify plan.md and walkthrough.md are generated, the brief validates and the checks gate, stuck-loop respects the mode-aware cap (5 iterations in Full Mode).

If you change the stuck-loop number, mode-detection criteria, or the companion list, do both runs.

aw dispatcher smoke test (run after any dispatcher / tier-routing change)

The dispatcher's two load-bearing runtime behaviors have no static check — they must be exercised live (markdown can't prove them). Run this after editing aw/SKILL.md, the tier table, or the routing rule:

1. Install the dispatcher skill + the agents: bash install.sh --development and confirm both chains resolve — readlink ~/.claude/skills/aw (the dispatcher) and readlink ~/.claude/agents/aw-executor.md. Also confirm ~/.claude/agents/aw-planner.md (the retired planning agent) and ~/.claude/agents/aw.md are gone (the pre-v3.23 agent symlink; install.sh removes it). A surviving aw.md means two aw entries compete for the same trigger phrases.
2. Micro routing (single-pass, no split): invoke /aw on a 1-file mechanical change (e.g. fix a typo in a README). Expect: MODE SELECTION: Tier: Micro, no aw-executor dispatch, a worktree + draft PR, no plan.md.
3. Full routing (dispatch from the caller's context — the R1 risk): invoke /aw on a 4-file / architectural task. Expect: Tier: Full, then a short brief (plan.md + sealed checks.yaml) written in the caller's window, then the work in that same window — no aw-executor dispatch — and one local review-loop before the PR, which must not report itself skipped while a dispatch tool exists. If the harness refuses sub-agent dispatch entirely, confirm aw still writes plan.md with sealed checks, reports review: not run (sub-agent dispatch unavailable), and does not downgrade to the Lite/Micro single-pass path.
4. Universal loop + two-scope writes (the R2 risk): run two checks against LoreKit (memory.search { q, scopes: ["repo::{owner}/*", "global"], tags: ["loop::aw-lessons"] } to inspect).
   • Universal lesson: after a run where the lesson is generic (e.g. an Applies when line like *.tsx or monorepo refactor), confirm the lesson was written to the global scope (tag loop::aw-lessons) and NOT to repo::{owner}/{repo}. If it landed in the repo scope, the classifier mis-routed a universal lesson.
   • Project-bound lesson: run a task that produces a repo-bound lesson (an Applies when line referencing a repo path) and confirm the lesson lands in the repo::{owner}/{repo} scope — NOT in global. If it landed in global, the classifier is broken.
   • Storage delegation: confirm the workflow never creates directories or commits lesson files in the cwd repo — where a repo:: lesson physically lives is LoreKit's control model (remote / local .lorekit/), not the loop's. The loop must only call memory.write with a scope.
5. Opt-in boundary: in an interactive session, make a casual single-file edit without a trigger phrase or /aw. Expect: aw does not engage.

Steps 3 and 4 are the gate — they cover the only two behaviors that reading the source cannot verify.

Coupled documentation

This skill's behavior is described in three coordinated files. When changing runtime behavior, update all three:

Phase rules and companion-skills.md are runtime-agent-facing; install.sh is end-user-facing; this file is contributor-facing.

History

• v3.26.0 — Step 1's tier walk says out loud which of its two halves wins, after the tier-routing L2 suite measured 25/30 with all five misses under-tiering (a Full labelled Lite, four Lite labelled Micro). The scorer was ruled out first, empirically: the run prints each miss's raw reply, and those replies show the model filling in the MODE SELECTION: block with a considered tier, not a parse artifact. So the rubric was the defect, in three specific places:
  • The walk and the table could disagree, and the table read as the authority. Q4 says "2–3 files, OR any non-trivial logic change ⇒ Lite" while the table's Lite row said "2–3 files AND simple" — a one-file logic change satisfies the walk and fails the row. Step 1 now states that the walk decides and the table only describes its outcomes, and the Lite row carries the one-file case explicitly.
  • Micro's bar was one condition, not two. "1 file, purely mechanical" reads as a file count with a parenthetical; it is now "1 file and purely mechanical", with the three worked examples (add a prop and forward it, add a behaviour-changing CLI flag, debounce an input) that are Lite at one file.
  • Q2 covered unfamiliar code but not an unknown location. A task whose cause or file set is unknown until it is investigated was being tiered on the guessed size of the eventual patch. Q2 now names the investigation case and the Full row says "cause or location unknown". The design-intent copy of the tier table in this file is gone — it had drifted to contradict Step 1 on both the Lite and the Full row, which is the exact failure the "exactly one home" rule below exists to prevent, and it sat 30 lines above that rule. This section now carries the decision's shape and links Step 1 for the criteria.
• v3.25.0 — Dispatch availability is a capability, not a tool name; and aw's review recovery stops re-running the dispatch that just failed. Field report from a cloud session: a Full run delivered a draft PR with NOT REVIEWED, and the recovery path fired but recovered nothing. Two independent defects, both empirically confirmed by probing this harness rather than reasoned about:
  • The capability gates were name checks. review-loop's Step 0 precondition read "check whether Task appears in your available tools", and pr-review and aw carried the same literal in eight more places. The Claude Agent SDK harness behind Claude Code on the web and in cloud sessions holds the capability and spells the tool Agent, so the gate concluded "no dispatch available" and skipped the review on a PR that was fully reviewable. The failure hid itself: a skip is a documented legitimate outcome, so nothing downstream contradicted it. Every check now asks whether any available tool dispatches a sub-agent — a tool taking a subagent_type (or equivalent) parameter is the dispatch tool whatever it is called — and each file states the anti-pattern as a code example so the name check reads as a defect rather than as the rule.
  • aw's review recovery was a no-op in the case it exists for. It invoked Skill("review-loop", …) bare, so when aw itself held no dispatch tool the loop skipped at iteration 0 exactly as the executor had. The recovery is now a two-row table keyed on aw's own capability, with the no-dispatch row passing --external-review (deliberately, by the caller, which is the shape review-loop's caller contract sanctions) so the loop waits for whatever reviewer is posting and still applies, resolves, and converges those threads. --critical is dropped on that row: it only ever configured pr-reviewer, and the loop warns and ignores it.
  • This is not the capability probe rejected in v3.22. That probe's premise was falsified and it would have gated quality companions failing open. This reads the name of a tool the context already holds, gates nothing, and every branch fails closed — toward --external-review, toward single-context Full — never toward a silent skip.
  • Also fixed in review-loop: the sub-step A comment claimed "the loop always ENDS on a review pass"; two of its four exits (the no-progress guard and the cap) fire after a push, not a review. And the post-loop report keyed on ITERATION == CAP, which is also true of a report-only run (--no-feedback forces CAP=1) and of a clean convergence on the last allowed iteration — both were reported as "cap reached". Exits now set an explicit STOP_REASON the report reads instead of re-deriving one from the iteration count.
• v3.24.0 — aw becomes the only natural-language entry point. v3.23 made the dispatcher a skill but left the parent autonomous-workflow skill's description advertising the same trigger vocabulary, so two skills competed for one request and the harness had nothing to arbitrate with. Losing that race skips tier detection and the universal lessons loop — the dispatcher's entire job. Full rationale and the design rules: design intent.
  • SKILL.md's description rewritten to describe the phase machinery, state that it is not the entry point, and name aw — quoting no trigger phrase and making no Triggers on / Use when claim. /autonomous-workflow still runs the machinery directly for a deliberate bypass.
  • templates/routing.rule.md gained "implement autonomously" (the phrasing deleted from the parent needed a home — G2d caught its absence on the guard's first run) and a note stating that aw is the only natural-language destination, why the duplication with aw's description is forced, and that G2d keeps the two honest.
  • New L1 G2d, two halves. Half 1: the parent quotes no trigger phrase and makes no trigger claim — matched on the claiming forms, since the sentence that fixes the problem must name the words it disclaims. Half 2: every phrase aw advertises exists in the routing rule. Its phrase-count sentinel is pinned to the live count (14), not a floor — the loose-floor defect a reviewer caught in G2c, verified by mutation.
  • Inventory marker auto → / for autonomous-workflow in the root CLAUDE.md and README.md; aw keeps auto.
  • Deliberately NOT changed: the routing rule's positive trigger list stays in full (it is the live L2 aw-should-trigger rubric — a pointer would gut that suite), the exclusion list, the continuation phrases, the tier table's single home, and every gate.
• v3.23.0 — The dispatcher becomes a skill. aw moved from templates/aw.agent.md (symlinked to ~/.claude/agents/aw.md) to aw/SKILL.md (a nested skill, invoked /aw). Routing behaviour, the tier semantics, the Micro/Lite single-pass path, the lessons loop, the follow-ups rule, and the single-context Full fallback are all unchanged — only the shape moved. aw-planner / aw-executor / aw-tester remain agents. Full rationale and the accepted costs: design intent.
  • Why: aw was the third agent §2.2 of references/anthropic-architecture-research.md warned about — its context boundary is conditional (real on auto-routing, absent when a developer opens a session to run /aw), unlike the planner/executor boundary, which is unconditional. It was paying three costs for that: a burned delegation rung, a duplicated tier table with a CI guard to police it, and a triplicated tool grant.
  • aw-planner and aw-executor gained Task. Four documented behaviours were unreachable by construction while the dispatcher occupied the top rung — Phase 1 Explore fan-out, Phase 3 file-disjoint fan-out (cap 3), Phase 7 ci-auto-fix fan-out (cap 2), and create-pr's Phase 6 review-loop pass. The last is the one with a field report: aw-lessons::executor-context-lacks- subagent-dispatch-skips-review-loop (seen_count 2, confidence 92), whose recorded symptom is NOT REVIEWED draft PRs. aw additionally re-runs review-loop itself when the executor reports the pass as skipped.
  • The tier table now has one home. L1 Check B byte-compared the dispatcher's copy against SKILL.md Step 1; it is replaced by G2b, which asserts the absence of a second copy plus a link to the canonical one. The L2 tier-routing suite reads SKILL.md § Step 1 directly.
  • New L1 G24b — the skill-shaped counterpart of G24. A skill cannot grant itself tools, so its obligation is to degrade visibly: aw/SKILL.md must state that it inherits the caller's grant and that a missing tool is named in Degraded:. G24's sentinel drops 3 → 2 accordingly.
  • install.sh stops linking the agent, links the dispatcher skill in --development mode, and adds aw.md to its legacy-symlink cleanup so an upgrading install does not end up with both an aw agent and an aw skill competing for the same trigger phrases. scripts/sync-symlinks.sh gains aw in AW_SKILLS.
  • Costs accepted: no model: opus pinning, Micro/Lite transcripts land in the user's window, and a dangling ~/.claude/agents/aw.md on installs that never re-run install.sh. All three are argued in the design-intent section.
  • Deliberately NOT changed: the planner→executor split (it passes §2.2 on its own merits), the tier table's content, the confidence(plan) gate, every checks.yaml integrity rule, and the routing rule's trigger vocabulary and exclusion list.
• v3.22.0 — Bounded waits, a stateless CI gate, an honest review-loop skip, and a terminal contract for aw. Field report: aw runs on Claude Code for web/mobile stall — long silent stretches, never terminating until the user interrupts. Diagnosis, including the record of a rejected design, in references/cloud-stalling-analysis.md.
  • Every wait is bounded at both levels. The subtle half: the Bash tool defaults to 120 000 ms and 600 000 is opt-in, so timeout 1800 and timeout 540 fail identically unless the call also passes timeout: 600000 — the harness kills it before the inner timeout fires and the documented exit 124 handling is dead code. All nine external-wait sites now state both, enforced per-site by new L1 check G22 (proximity-scoped so a second site cannot free-ride on a first's mention; count pinned; mutation-tested four ways).
  • Phase 7 queries CI state instead of carrying it. One stateless gh pr checks (no --watch) at the current head decides whether to watch at all. Retry caps are counted within one skill invocation; nothing is shared across phases or subagents. New hard invariant watch state is queried, never carried records why, because the first implementation of this change did the opposite and had to be reverted (see below).
  • gh pr checks semantics are now stated — it exits non-zero while merely pending (so classification is by exit code plus literal stderr match, never by output volume), and it does not wait for checks that do not exist yet (so a bounded registration poll precedes the watch; the old bare sleep 10 was silently covering this).
  • review-loop self-reports a clean skip when sub-agent dispatch is unavailable, with a NOT REVIEWED slot in create-pr's report. Deliberately not an in-context substitute — pr-reviewer's independence comes from the isolated context.
  • aw gained AW RUN COMPLETE with a mandatory Degraded: line, present even in the Micro/Lite one-line collapse.
  • Deliberately not built: a capability probe (its premise — that Claude Code on the web disables Task — was falsified by probing; Task was available and gh was not; and a probe gating quality companions fails open), a gh→MCP degradation matrix (a second source of truth that would drift), and a compaction re-anchor (never observed, Full-tier only). (v3.25 refined the first entry rather than reversing it: the premise was falsified in the wrong direction too — a later harness holds the capability under the name Agent, so the literal-Task gates these files kept were themselves the bug. The name-agnostic capability check v3.25 installs gates nothing and fails closed, which is what separates it from the probe rejected here.)
  • A rejected design is recorded, not just removed. The first attempt threaded a shared watch budget through a state file across create-pr, Phase 7 and the ci-auto-fix fan-out. It took six review rounds, was merged with ten live findings still open, and was reverted. Its failure shape — cross-context mutable state coordinated by prose, in files edited one at a time — is documented in the reference so it is not reinvented.
• v3.21.0 — User-requested changes are never scope creep (post-completion improvements welcome). Field report: after a Full run finished (draft PR open), the user proposed an improvement having seen the whole feature; the dispatcher accepted the idea but declined to act on it, tagging it "scope creep" — forcing the user to insist before it was implemented. Root cause: the only scope-creep guidance was the safety-guardrails.md "When to Stop and Ask" trigger #3 ("Scope creep detected"), which conflated the agent inventing work with the user asking for work, and there was no defined path for a follow-up arriving after handback. Fix — one conceptual home + coupled surfaces:
  • rules/safety-guardrails.md — trigger #3 narrowed to agent-initiated expansion; new subsection "User-requested changes are never scope creep" (anchor user-requested-changes-are-never-scope-creep) makes the principle explicit across the whole lifecycle, including post-completion, and defines the fold-in path (re-detect the tier for the delta → Micro/Lite single-pass on the same branch, or Full via the edit-driven iteration loop → gates as normal; "accepted means done"). The only legitimate pause is a genuine blocker/conflict, never scope size.
  • templates/aw.agent.md — new "Follow-ups after completion" routing section: a post-handback improvement is a welcome new iteration; re-detect the tier for the delta only and reuse the existing branch/PR.
  • rules/phase-3-implementation.md — the drift write-back note now states a mid-run user-requested change is conversation drift, not scope creep (fold in; hand back to the planner only if it needs re-planning).
  • rules/diagnostic-surface.md — new post-completion guards row recording the observed failure (improvement refused / accepted-then-deferred; delta tier not re-detected; a second branch/PR opened instead of reusing).
  • SKILL.md (Core Principle #9, version 3.21.0) and README.md (Key Principle #9) surface the principle. Deliberately NOT changed: the scope-creep guard against the agent's own unrequested expansion (still trigger #3), the Phase 0/2 mandatory invariants, and every checks.yaml / confidence gate — a folded-in delta is verified, tested, and reviewed like any other change.
• v3.20.0 — Scope-alignment interview companion (Phase 0). Wired the new interview skill in as a default-on, adaptive Phase 0 companion (Full Mode; --no-interview skips, --interview forces even on Micro/Lite). interview is now the single source of truth for restate-and-diff + the Missing-Information Gate: Phase 0 Step 3a delegates both to Skill("interview"), which researches the codebase, classifies every unknown blocking vs advisory, interviews the user only for load-bearing unknowns (silent on a crisp request), and writes .agent/{branch}/brief.md + a readiness verdict. Phase 1's new ## Scope Brief step seeds Requirements / ACs / Existing Code Survey from the brief instead of re-deriving scope. The inline Step 3b/3c procedure is preserved verbatim as the graceful-degradation fallback (companion missing or --no-interview); the gates are identical either way, and a blocked verdict enforces the load-bearing-unknown hard invariant (halts even under --no-confirm). Reconciled the gate vocabulary: the incumbent assume-and-proceed class was renamed assume-and-proceed → advisory across phase-0-validation.md, diagnostic-surface.md, aw-planner.agent.md, planning-quality-research.md, and this file so both the skill and the workflow speak one vocabulary (no eval or anchor referenced the old token). Coupled surfaces updated in lockstep: phase-0-validation.md (Step 3a + scope-alignment anchor + checklist + 3b/3c fallback pointers), phase-1-planning.md (## Scope Brief + scope-brief anchor + checklist), companion-skills.md (Phase 0 registry row + disable link), templates/aw-planner.agent.md (Phase 0 companion row + gate delegation note), templates/aw.agent.md (flag pass-through + Micro/Lite force path), diagnostic-surface.md (Phase 0 guard row + new typical gaps), SKILL.md (companion table + Phase 0 quick-ref + argument-hint flags + version 3.20.0), README.md (companion table), and the root CLAUDE.md / README.md inventory (interview entry de-caveated to "wired"). interview degrades silently if not installed — the inline gate is untouched, and confidence(plan) remains the only non-removable companion. Deliberately NOT changed: the Phase 0/2 mandatory invariants, the blocking-halts-under- --no-confirm hard invariant, and every checks.yaml / confidence rule.
• v3.19.0 — Single-context Full fallback for harnesses without sub-agent dispatch (e.g. Claude Code on the web, where Task is disabled). Before this, aw's Full-tier fallback was under-specified and self-contradictory: the dispatch section said "invoke them yourself if your tools permit" while the Hard rules forbade aw from ever using Edit/Write on a Full task, so an aw run in the cloud env hit Failed to run agent and had to improvise a justification before doing the work in-context. This makes that emergent behavior the sanctioned, reproducible path: when the split is structurally unavailable, aw runs the Full phases in one window — playing the planner role (Phases 0–2, producing plan.md + checks.yaml, clearing confidence(plan) ≥ 90%) then the executor role (Phases 3–7). It preserves the plan artifact and the confidence gate — the two load-bearing wins of the split — and concedes only context isolation, which the harness has already made impossible. It is explicitly not a downgrade to Lite/Micro single-pass, and never a license to skip an available split (the guard is "can I dispatch?", not preference). The "tell the user to run the agents themselves" text is demoted to a last resort for when Edit/Write/Bash are also unavailable. Coupled surfaces updated in lockstep: templates/aw.agent.md (Full-tier dispatch section, the Routing table's Full row, and the Edit/Write Hard rule — all three now condition on dispatch availability), templates/routing.rule.md (dispatch-unavailable branch pointing at that section), SKILL.md (v3.19.0; the Templates section states the single-context Full fallback and links the agent definition for the procedure), and this file's thin-router invariant, split-is-Full-only design-intent invariant, and the aw dispatcher smoke test (step 3 now exercises the single-context path). Deliberately NOT changed: the tier-detection table (L1 Check B keeps it byte-identical to SKILL.md Step 1), the preferred dispatch-the-split path when Task is available, and every checks.yaml / confidence(plan) integrity rule.
• v3.18.0 — Artifact lightening: checks-primary, lean plan, opt-in snapshots. Rebalanced the Full-Mode artifacts around the two-jobs distinction above (within-run handoff vs cross-session resumption). Four coordinated changes:
  • plan.v{N}.md snapshots are now opt-in. aw-create-plan (v2.2.0) writes only plan.md by default (still bumping the version: frontmatter); the immutable snapshot chain is written only when invoked as Skill("aw-create-plan", "snapshot"). Rationale: .agent/ is gitignored scratch, the chain is rarely re-read, and it has no measured task-success benefit (§5.4). The iterate loop's snapshot-diff step became snapshot-mode only; its comment-walk fallback is now the default path.
  • checks.yaml reframed as the primary living contract, plan.md as the handoff document, everywhere in the docs (SKILL principles, README, overview, artifacts-overview, handoff contract, diagnostic-surface artifacts table).
  • Executor drift write-back. Phase 3 Step 5 now mandates writing decision/AC drift back into plan.md (and checks.yaml), not just the Progress Log — the stale-plan fix so the durable artifact is consumed, not write-only. Wired into the aw-executor template's Universal Rules.
  • Removed the "No AI co-author tags" rule from this skill (user request): dropped from SKILL principles, README, both aw-planner/aw-executor/aw templates, diagnostic-surface.md hard invariants, phase-3/4/6 rules, parallel-coordination.md, the worked reference, and this file's invariants.
  • VS Code extension (v0.73.0): getBranchChildren renders ChecksSummaryItem FIRST (above Tasks/Plan) and it defaults to Expanded so the AC rows are visible without a click; PlanSummaryItem demoted below it; Sessions panel mirrors the order (Checks before Plan). Extension CLAUDE.md + provider test doc updated with the ordering contract. Coupled surfaces updated in lockstep: aw-create-plan/SKILL.md, artifacts-overview.md, planner-executor-handoff.md, phase-1/3/4/6, diagnostic-surface.md, parallel-coordination.md, all three agent templates, references/autonomous-workflow-complete.md, SKILL.md (v3.18.0), README.md, this file, and the root CLAUDE.md/README.md inventory. Deliberately NOT changed: the planner→executor split, the cold-read plan.md guarantee, the confidence(plan) Core-8 contract (L1 Check C), or checks.yaml integrity.
• v3.17.0 — Self-improvement fast tier migrated from persistent-memory to LoreKit (MCP-backed shared agent memory). The two former tiers map onto LoreKit scopes — home → global, project-shared → repo::{owner}/{repo} — and the aw-lessons bucket becomes a LoreKit tag (loop::aw-lessons) plus a key namespace (aw-lessons::<slug>), because LoreKit partitions by repo/branch/global, not named buckets. Reads use memory.list narrow-to-broad (repo:: then global) filtered by tag; writes classify the scope, memory.search to dedup, then memory.write (same scope + key updates in place → the recurrence UPDATE). The filesystem opt-in ceremony (memory/aw-lessons/INDEX.md) is gone — LoreKit's mode (remote / local .lorekit/) decides where a repo:: lesson physically lives; the loop only picks the scope. INDEX 200-line caps and consolidate are gone too (LoreKit owns storage and dedups on write); expiry (the expires field, ignored on read once past) remains the decay mechanism. The lesson schema (five meta fields + four bold fields), the advisory-only semantics, the seen_count >= 3 promotion gate, and all five entrenchment guards are unchanged. Coupled surfaces updated in lockstep: self-improvement-loop.md (canonical SSOT), phase-1/3/4/7, companion-skills.md, diagnostic-surface.md, all four agent templates (aw, aw-planner, aw-executor, aw-tester), SKILL.md, README.md, this file, and references/self-improvement-walkthrough.md. persistent-memory is kept as the general-purpose personal-memory skill and now documents the LoreKit backend (rules/scaling-tiers.md). The same migration was applied to every other loop in the repo (fix-bug, batch-linear-tickets, implement-suggestion, ci-auto-fix, test-auto-fix, e2e-pr-stabilizer, optimize-approach, ideate, and the reviewer / pr-reviewer agents + the review-outcomes bus). LoreKit skips silently when its memory.* tools are not connected — the fast tier degrades to nothing and diagnose is unaffected.
• v3.16.0 — Plan-time optimality lens. Wired the optimize-approach skill's new plan mode into Phase 1 as a default-on companion (Full Mode; quiet early-exit; --no-optimize to skip), running between the adversarial pre-mortem and confidence(plan). It asks the one design-level question the other Phase 1 gates assume away — is this the most optimal approach, and if not what is? — at the cheapest moment to switch (the approach is still words, not code). Positioned against the existing plan-time gates, not overlapping them: it consumes the Existing Code Survey verdicts (codebase-fit reuse is the survey's job, rule #10), does not re-list critical's failure modes, and never re-scores confidence(plan). Its net-new value is the approach-level simplicity / performance / robustness judgment plus a materially-better-approach steelman. Advisory — does not gate; adopted proposals trigger a bounded re-plan via aw-create-plan (one optimality pass per planning cycle — no re-invoke on the plan it revised, the F-plan-loop guard). Coupled surfaces updated in lockstep: phase-1-planning.md (new ## Approach Optimality step + anchor, order-of-operations note, Contents, Planning Checklist, References), companion-skills.md (registry row + disable link), aw-planner.agent.md (companion table), diagnostic-surface.md (Phase 1 guard row + typical gaps), SKILL.md (companion table + Phase 1 quick-ref + version 3.16.0), README.md (companion table). The skill side adds optimize-approach/rules/plan-mode.md plus mode-detection / surface / lessons updates. optimize-approach skips silently if not installed — the lens degrades to nothing and the gate is unaffected. Root CLAUDE.md / README.md inventory updated.
• v3.15.0 — Plan-quality gates + executable checks. Implements the four mechanisms from references/planning-quality-research.md (2024–2026 web-research pass; see that file for citations and caveats):
  • Phase 0: Step 3b restate-and-diff (surface spec-perception deltas before presenting understanding) and Step 3c Missing-Information Gate (blocking vs advisory; blocking halts even under --no-confirm — new hard invariant).
  • Phase 1: dependency-graph-first localization in Step 1; Existing Code Survey (recorded reuse searches + EXTEND/WRAP/BUILD NEW verdict per planned create) as a deterministic-trigger Extended plan section; Acceptance Criteria gain AC-{n} IDs, (covers: R{m}) traceability annotations, and EARS trigger→response preference.
  • Phase 2: aw-create-plan v2.1.0 Step 2b derives .agent/{branch}/checks.yaml — one runnable check per criterion (command/grep/judge), statuses pending, re-derived per iteration.
  • Phase 4: new Executable Checks Loop — checks.yaml is the mechanical termination condition and progress ledger; check definitions are executor-immutable, four gaming strategies forbidden, unsatisfiable abort affordance escalates; all-green is necessary-not-sufficient. Self-skips when no checks.yaml (backward compatible).
  • Gate: confidence v2.3.0 adds deterministic rules #9 (every [user-stated] requirement covered), #10 (create ⇒ survey), #11 (checks.yaml ID sync; skipped for un-IDed plans like fix-bug fast-lane).
  • Coupled surfaces updated in lockstep: phase rules 0/1/2/4, safety-guardrails.md (Executable-Check Integrity section), planner-executor-handoff.md (Core/Extended tables, rule-check list, handoff messages gain a Checks: line, executor entry step 3b), artifacts-overview.md (three-artifact table + tree), all three agent templates, diagnostic-surface.md (guards + 3 hard invariants + artifact row), SKILL.md (v3.15.0, principle #9, artifact table, quick reference), README.md, and L1 evals (l1.mjs runs the actual rule #9/#10/#11 idioms against new fixtures uncovered-req.md, create-no-survey.md, checks-valid.yaml, checks-drifted.yaml; valid-core.md upgraded to the new AC format). Deliberately NOT added: new Core sections (Core-8 is coupled to rule #2, L1 G2, and fix-bug's fast-lane) and any weakening of existing gates (checks are additive).
• v3.13.2 — Agent-template discoverability + role-accurate filenames. The three agent definitions in templates/ are symlinked verbatim by install.sh (no substitution ever happens), so the old *.template.md naming both mislead — they aren't fill-in templates — and hid the agents from search: a repo lookup for aw / aw-planner / aw-executor found nothing because the runtime names lived only inside file contents. Renamed each file so its name states what it is and matches the installed agent: dispatcher.template.md → aw.agent.md, planner.template.md → aw-planner.agent.md, executor.template.md → aw-executor.agent.md. Applied the same role-suffix logic to the rest of templates/: routing-rule.template.md → routing.rule.md and the deprecated single-agent template agent.template.md → _deprecated-single-agent.md. The directory stays templates/ (it means "source files this skill installs into your Claude config"). Pure rename — no behavior change; agent name: frontmatter, install paths (aw.md, aw-planner.md, aw-executor.md, autonomous-workflow-routing.md), and the legacy-cleanup block (still matches the pre-aw- autonomous-planner.md / autonomous-executor.md link targets) are all unchanged. Coupled surfaces updated in lockstep: install.sh (template_required + symlink targets), SKILL.md Templates table, this file, rules/planner-executor-handoff.md, references/anthropic-architecture-research.md, the deprecated file's banner, and the L1/L2 evals + eval README that read the dispatcher template by path. Root README.md / CLAUDE.md additionally add the three aw agents to their agent inventories and feature aw as the flagship entry point. Note: renaming the deprecated single-agent file dangles the symlink for pre-v3.3 single-agent installs that never re-ran install.sh (negligible — those predate the aw agents and install.sh no longer recreates that link). L1: 69/69.
• v3.12 — Adaptive dispatch + universal loop. Added a third agent, aw (templates/aw.agent.md, linked as aw.md) — a thin, opt-in dispatcher that reads aw-lessons, detects the tier, and routes. Added a Micro tier (1-file mechanical: skip planning + quality companions) below Lite/Full, so mode detection is now 3-tier (Micro | Lite | Full); Micro reuses the Lite phase path. The planner→executor split is now Full-only — Micro/Lite run single-pass in aw's context (research: always-planning wastes compute and degrades long-horizon tasks; single-threaded continuity wins for simple/sequential work). The self-improvement loop's intake-read and exit-write are hoisted to the dispatcher so every tier contributes/benefits (phase-level reads/writes become the Full-tier specialization) — planning depth and learning coverage decoupled. Routing rule now dispatches aw instead of "planner first" (fixing the Lite-has-no-plan.md impedance mismatch). aw is opt-in: invoked via a trigger phrase or /aw, never a wrapper on casual edits. Coupled surfaces updated: install.sh (links aw.md + 3-agent summary), routing.rule.md, SKILL.md (3-tier detection + dispatcher in Templates + version 3.12.0), phase-0-validation.md (3-tier MODE SELECTION), this file, README.md, diagnostic-surface.md, and the root inventory. Research: Learning When to Plan (arXiv 2509.03581); Cognition vs Anthropic on single-vs-multi-agent.
• v3.11 — Two-tier self-improvement. Added a fast tier of episodic lessons on top of the existing diagnose slow tier. New rules/self-improvement-loop.md owns the contract: persistent-memory is wired as an optional companion that reads the committed aw-lessons scope at Phase 1 (lessons applied as plan constraints) and writes lessons at Phase 4 stuck-loop escalation and Phase 7 end-of-run. A lesson reaching seen_count >= 3 (or tagged structural) becomes promotion-eligible: the workflow suggests /create-skill diagnose autonomous-workflow, which reads aw-lessons as evidence and applies a source change only behind the unchanged confidence(analysis) ≥ 90 % + user-approval gate. Lessons are advisory — they never auto-change behavior (the entrenchment guard against self-reinforcing error). The committed scope is seeded at ~/.agent-memory/aw-lessons/. Coupled surfaces updated: companion-skills.md (3 rows + Self-Improvement Loop section), phase-1-planning.md (lessons-read), phase-4-testing.md (lessons-write), phase-7-ci-gate.md (lessons-write), diagnostic-surface.md (guards + advisory-only invariant), both agent templates, SKILL.md (Self-Improvement section + companion table + install sets + version 3.11.0), and README.md. Root CLAUDE.md / README.md inventory updated. persistent-memory skips silently if not installed — the fast tier degrades to nothing and diagnose is unaffected. Research basis: CoALA episodic→procedural promotion, ExpeL trajectory-distilled lessons, Agentic Context Engineering (incremental deltas, not rewrites), and the Reflexion / SSGM self-reinforcing-error guards.
• v3.10 — Plan template tiered into Core + Extended; rationale grounded in empirical evidence. The aw-create-plan template no longer forces all ~14 sections on every Full-Mode task. Core (TL;DR, Requirements, Decisions, Acceptance Criteria, Implementation Order, File Changes, Verification, Progress Log) is always emitted; Extended (Background, Technical Approach, Patterns, Edge Cases, API / Interfaces, Tests, Dependencies, Risks) is emitted only when each section's Include when trigger holds — omitted, not stubbed. Root cause / motivation: the over-detailed-upfront-plan failure mode is empirically real (overthinking, inverse-scaling, and as-needed-decomposition literature), now documented in references/anthropic-architecture-research.md §5. The Core set is exactly what the executor reads cold and the confidence gate enforces, so resumption and gating are unchanged; the win is smaller plans on simpler Full-Mode tasks. Coupled surfaces updated in lockstep:
  • skills/workflow/aw-create-plan/SKILL.md — tier table in Step 2, per-section Include when triggers, two-tier validation checklist, omit-don't-stub Common-Failures row.
  • skills/quality/confidence/SKILL.md — plan-mode rule check #2 now requires the 8 Core sections by name (also fixes a latent bug: it counted ## Summary while the template emits ## TL;DR, so the check never matched the human- review heading); LLM dimensions no longer penalize a legitimately-omitted Extended section.
  • rules/planner-executor-handoff.md — handoff contract split into a Core (always) table and an Extended (conditional) table; the executor must not bail when an Extended section is absent.
  • references/anthropic-architecture-research.md — new §5 (empirical evidence, confidence-tiered) + renumbered §6 references; the plan's justification reframed from "single source of truth" to cross-session resumption.
  • rules/diagnostic-surface.md — Phase 2 guard wording updated to name the Core sections. No taxonomy row added (the taxonomy is append-only and no new real failure was observed).
• v3.9 — Reviewer self-review sub-mode. Added Rule 0 (authorship pre-check) to agents/reviewer.md Mode Detection: ME=$(gh api user --jq .login) vs AUTHOR=$(gh pr view ... --jq .author.login). When ME == AUTHOR, the run enters PR (self-review) sub-mode: Step 4 auto-fix re-enabled, Steps 5.1–5.6 (pending GitHub comments) replaced by Step 5.8 (inline terminal report). --critical adversarial findings flow into the inline-report (Must-fix → Critical bucket, Should-fix → High bucket) rather than a separate channel. Cross-review behavior unchanged. Phase 7 Auto Review dispatch prompt and log updated to reflect inline-report deliverable. Root cause: Phase 7 always self-authors its PRs (aw-executor opens them), so "pending review" was enforcement theater — comments visible only to the same user who opened the PR.
• v3.8 — Sub-Agent Resource Discipline. Replaced the "Phase 3 is not parallelized" blanket prohibition with "controlled fan-out under per-slice scoping" (cap 3 concurrent, file-disjoint slices). Added the Sub-Agent Resource Discipline rule (rules/parallel-coordination.md#sub-agent-resource-discipline): sub-agents must use scoped validation commands only; whole-project tsc, lint, build, test are forbidden inside sub-agents and reserved for orchestrator-only boundaries (Phase 4 Step 6, Phase 6 pre-PR). Root cause: N concurrent whole-project tsc processes scale peak RSS ~2.9x per process, crashing developer hosts on multi-slice tasks. Added F2 taxonomy row to rules/diagnostic-surface.md and updated all 7 coupled surfaces that previously asserted "Phase 3 is not parallelized". Enforcement is via diff review at maintenance time and the LLM-readable rule at runtime — no shipped script (skills stay markdown-only per the repo contract).
• v3.7 — Diagnose Mode relocated to create-skill. The --diagnose flag is gone from this skill; the retrospective self-improvement loop is now /create-skill diagnose autonomous-workflow. The seven-step procedure, output report format, confidence gate, and apply / PR flow moved into skills/authoring/create-skill/rules/diagnose-mode.md so the same capability works against any diagnosable skill (fix-bug, batch-linear-tickets, future ones). What stays here is a declared contract — rules/diagnostic-surface.md — that the generic engine reads to parameterize itself: phase model, failure taxonomy (F1 + F-novel, unchanged, append-only), existing-guards-per-phase table, hard invariants, source root, artifacts. Behavior is preserved end-to-end: --apply still gates on confidence(analysis) ≥ 90 % plus explicit user confirmation; one proposal per report; earliest-phase-fix wins; diagnose never modifies user product code. For users, the only surface change is the invocation: /autonomous-workflow --diagnose becomes /create-skill diagnose autonomous-workflow.
• v3.6 — Self-improvement, gated everywhere. Two coordinated changes:
  • Diagnose Mode. New --diagnose flag on the orchestrator runs a retrospective self-analysis after a workflow run produces wrong code. Outputs .agent/{branch}/diagnose-{ts}.md containing a failure classification, a phase-attribution matrix walk, and one applyable unified-diff proposal targeting this skill's source. The proposal is gated by Skill("confidence", "analysis") ≥ 90 %; below the threshold, --apply is refused and the report becomes a discussion artifact. --apply always asks for confirmation even with the gate passing — Auto mode does not bypass this. Procedure originally lived in rules/diagnose-mode.md; in v3.7 it was relocated to skills/authoring/create-skill/rules/diagnose-mode.md (see v3.7 above). The failure taxonomy is intentionally seeded with F1 + F-novel only and grows append-only from real confidence-gated, user-approved diagnoses (no speculative categories). Diagnose Mode never modifies user product code.
  • test-provenance-guard autofix in the loop, behind a confidence gate. The Phase 4 invocation passes --fix, so the guard self-heals autonomously when it can — but the skill MUST clear Skill("confidence", "code") ≥ 90 % on the proposed extract-and-rewrite before mutating any file, and the three existing post-heal mechanical gates (build, target test, mutation re-verify) afterwards. Either gate failing ⇒ no autonomous refactor; the finding is reported as heal-skipped-low-confidence or heal-failed, and the existing Phase 4 stuck-loop / confidence(analysis) / holistic-analysis cascade takes over. The --no-confidence-gate override is reserved for human-driven slash invocations and is never set inside the loop.
• v3.5 — Plan versioning. aw-create-plan now writes an immutable plan.v{N}.md snapshot on every invocation and mirrors it into plan.md (the canonical "latest" pointer). Initial creation produces plan.v1.md + plan.md; user-requested iteration and Phase 4 auto-replan both bump to the next version. Older snapshots are preserved untouched as audit trail. The Phase 4 stuck-loop protocol now re-invokes aw-create-plan after holistic-analysis instead of surgically editing plan.md in place. The VS Code extension surfaces previous versions as expandable children of the Plan node so reviewers can compare iterations.
• v1.x — Initial skill in gw-tools.git. Monolithic SKILL.md.
• v2.x — Split into phase rules + companion artifacts (create-plan, create-walkthrough, confidence). Still in gw-tools.git.
• v3.0 — Migrated to agent-skills.git. Companion-skills registry pattern. .agent/ artifact directory (was .gw/). 3-iteration stuck-loop limit (was 20). Phase 7 = CI Gate + Optional Cleanup (was just Cleanup). Optional companions skip silently.
• v3.1 — gw made optional (recommended), with a native git worktree fallback. gh remains hard-required. Phase 2 detects gw at Step 0 and emits a one-time warning when falling back, listing the features the user is missing (auto-copy, pre/post-checkout hooks, smart cleanup, shell-integrated gw cd). The workflow is now usable in repos that haven't adopted gw.
• v3.3 — Split into two agents (planner + executor) connected by plan.md. The split is along the Phase 2 → Phase 3 context boundary:
  • aw-planner — runs phases 0-2 (validation, planning, worktree + plan.md generation). Tool budget excludes Edit/Write on production code. Terminal deliverable: .agent/{branch}/plan.md, gated on confidence(plan) ≥ 90%.
  • aw-executor — runs phases 3-7 (implementation, testing, docs, PR, CI). Reads plan.md from cold; bails if missing or invalid rather than re-planning. Terminal deliverable: .agent/{branch}/walkthrough.md + draft PR.
  • Handoff contract — see rules/planner-executor-handoff.md. Two messages: high-confidence auto-handoff (≥ 90%) and user-approval (< 90%). Each agent has a single, gated, terminal artifact — when the artifact exists and the gate passed, the agent is done. This pattern matches Anthropic's "structured handoff artifacts" recommendation; full citations are in references/anthropic-architecture-research.md.
  • The agents share companion-skills.md and the phase rules — the split is an architectural lever, not a behavior change.
  • templates/_deprecated-single-agent.md (the original single-agent template) is preserved as a backward-compat artifact for users with existing installs, but is no longer linked by install.sh. New installs use aw-planner.agent.md + aw-executor.agent.md.
• v3.2 — Quality refinements based on field-alignment review:
  • Multi-signal confidence(plan) gate. The confidence skill's plan mode now combines LLM dimensional scoring with deterministic rule checks (file paths resolve, requirements tagged, timestamps are ISO 8601, etc.). A failed rule caps the gate at 89% regardless of LLM score — catches the "high-confidence-but-hallucinated" failure mode.
  • Acceptance Criteria in plan.md. New mandatory section in the aw-create-plan template. Phase 4 testing now has explicit pass/fail conditions to gate against (sprint-contract pattern from Anthropic's harness-design guidance).
  • Auto-replan on stuck-loop. Phase 4 stuck-loop detection now auto-invokes holistic-analysis when confidence(analysis) < 90%, regenerates the affected plan.md section, and resumes once. One-shot guard prevents infinite recursion.
  • Mode-aware iteration cap. 3 iterations for Lite, 5 for Full. Lite keeps the tight loop; Full gives well-scoped tasks one extra attempt before mandatory escalation.
  • Per-iteration self-reflection (lightweight evaluator-optimizer). Before each iteration ≥2, the agent runs a brief two-question self-check ("Is this attempt different from the last?" / "Did I understand why my previous fix didn't work?"). If either fails, jump to stuck-loop detection early — no wasted iterations.
  • Mode detection: complexity primary, file count tie-breaker. Three sequential questions in Phase 0 (architectural? unfamiliar? 4+ files?) replace the conflated "4+ files OR complex" criterion. Complexity decides first; file count is the fallback.
  • docs update opt-out lever. Per-task skip conditions documented (pure dependency bumps, test-only changes, config-only changes, user override). Default remains always-on; the skip is logged.
• v3.4 — Workflow-exclusive companions and agents grouped under an aw- prefix so they cluster in the harness's /-listing. Renamed: create-plan → aw-create-plan, create-walkthrough → aw-create-walkthrough, review-quality-gate → aw-review-quality-gate, autonomous-planner → aw-planner, autonomous-executor → aw-executor. The orchestrator itself (autonomous-workflow) keeps its full name as the user-facing entry. General-purpose skills used outside the workflow (confidence, ci-auto-fix, create-pr, etc.) are unchanged. Pure rename — no behavior changes.

The npm package @gw-tools/autonomous-workflow-agent still exists at the old location for SDK users who prefer a programmatic import. It will be deprecated in a future release once this v3 skill is stable.