mthines Autonomous Workflow
Phase-based autonomous feature development. Each phase has a gate that must pass before continuing. Phases optionally invoke companion skills based on the task — companions skip silently if not installed.
Source of truth. This
SKILL.mdis a thin index. Detailed procedures live inrules/*.mdand load on demand. Companion-skill triggers and disable instructions live inrules/companion-skills.md.
Self-Improvement
The workflow improves across runs through a two-tier loop (full contract in
rules/self-improvement-loop.md):
Fast tier — episodic lessons (LoreKit memory.* tools, optional companion).
The workflow reads accumulated loop::aw-lessons lessons before planning
(Phase 1) and writes new ones when it gets stuck (Phase 4) or finishes (Phase 7),
mapping universal lessons to LoreKit's global scope and repo-bound lessons to
repo::{owner}/{repo}. Lessons are advisory — they bias the plan, never
silently change a gate. Skips silently when LoreKit's memory.* tools are not
connected.
When invoked through the aw dispatcher, the read/write is hoisted to the
dispatcher (intake + exit) so every tier — Micro, Lite, and Full — both
benefits from and contributes lessons; the phase-level reads/writes are the
Full-tier specialization. This is how self-improvement stays universal without
forcing planning on simple tasks.
Slow tier — retrospective diagnosis. When a run shipped wrong code despite
all gates passing — or a post-merge bug traces back to a missed check, or a
lesson recurs seen_count >= 3 — invoke
/create-skill diagnose autonomous-workflow
while the failing session is still in context. The diagnoser reads this
skill's diagnostic surface (phase model,
failure taxonomy, existing-guards table, hard invariants) — and the aw-lessons
history as evidence — then emits a confidence-gated unified-diff proposal
against this skill's source, applied only at confidence(analysis) ≥ 90 % with
explicit user confirmation.
The fast tier captures lessons cheaply and reversibly; recurrence promotes a
proven lesson into a permanent guard through the gated slow tier. The diagnose
engine is owned by create-skill so the same procedure works across every
skill in the repo (fix-bug, batch-linear-tickets, future ones) — they each
declare their own diagnostic surface.
CRITICAL: Before Starting Any Work
Step 1: Detect Workflow Mode (MANDATORY)
Complexity is the primary signal. File count is the tie-breaker. Walk these
questions in order — the first yes selects Full Mode:
| # | Question | If yes → | If no → |
|---|---|---|---|
| 1 | Is this task architectural / cross-cutting / does it require significant design decisions? | Full | go to next |
| 2 | Does the task involve unfamiliar code or domains the agent hasn't worked in before, or is the cause or location not yet known — an investigation rather than a known edit? | Full | go to next |
| 3 | Is the change touching 4+ files OR 2+ packages? | Full | go to next |
| 4 | Is the change 2–3 files, OR any non-trivial logic change? | Lite | Micro |
| Tier | Files / shape | Artifacts | Planning | Companions |
|---|---|---|---|---|
| Full | complex / 4+ files / unfamiliar / cause or location unknown | Required | planner → plan.md |
all applicable |
| Lite | 2–3 files, or 1 file carrying non-trivial logic | None | brief mental plan | per signal |
| Micro | 1 file and purely mechanical (typo, copy, bump, string change) | None | none (skip planning) | none (docs if drift) |
The walk decides; the table only describes its outcomes. Where the two seem to disagree, the walk wins. Two readings this exists to rule out, because the earlier wording invited both:
- Q4's
ORis load-bearing. A one-file change with non-trivial logic is Lite, not Micro — Micro needs both one file and nothing to reason about. Adding a prop and forwarding it, adding a CLI flag that changes behaviour, or debouncing an input are all Lite at one file, because each has logic to get wrong. - Q2 covers not knowing where, not only not knowing the code. "Fix the leak somewhere in the streaming pipeline, not sure which layer" is Full: the edit may turn out to be one line, but the work is an investigation, and its file count is unknown until the investigation finishes. Tiering on the guessed size of the eventual patch is what Q1 and Q2 exist to prevent.
Micro follows the same phase path as Lite but skips planning and all quality companions — it is the "skip planning when it's trivial" tier. Phase 0 and Phase 2 stay mandatory in every tier, including Micro.
The first two questions ground the decision in complexity rather than raw file count (one large monolithic change can exceed four trivial edits in scope). Question 3 is the file-count tie-breaker — only fires when complexity is low.
When in doubt, choose Full. Output mode selection in this exact format:
MODE SELECTION:
- Tier: [Micro | Lite | Full]
- Reasoning: [why]
- Estimated files: [number]
- Complexity: [trivial | simple | moderate | architectural]
- Lessons applied: [N matched, or none]
This block is canonical — the aw dispatcher skill, the
planner template, and
rules/phase-0-validation.md emit it
field-for-field identically.
Step 2: Verify Prerequisites
| Capability | Status | Check | If missing |
|---|---|---|---|
| GitHub access | REQUIRED (the capability, not the binary) | Resolve ACCESS_PATH per github-access.md § Step 0 — never which gh, never gh auth status |
Only ACCESS_PATH = none degrades Phases 6–7; name it in Degraded: and never report a GitHub step you could not perform as done |
gw |
Recommended | which gw |
Continue with native git worktree fallback (warn user once) |
gh is not hard-required — it is one of two GitHub paths, and it is absent
in Claude Code cloud sessions where the mcp__github__* tools are present (both
aw-planner and aw-executor carry them in their tools: frontmatter). Gating
on which gh turns a workable cloud session into a hard stop; detail in
rules/prerequisites.md.
gw is recommended — it adds auto-copy of secrets, pre/post-checkout hooks,
and smart cleanup — but the workflow falls back to native git worktree if
it's not installed. See rules/prerequisites.md
for the full feature comparison and installation steps.
Workflow Phases
| Phase | Name | Rule file | Gate |
|---|---|---|---|
| 0 | Validation | phase-0-validation.md | User confirmed understanding |
| 1 | Planning | phase-1-planning.md | confidence(plan) ≥ 90% or user-approved |
| 2 | Worktree Setup | phase-2-worktree.md | Worktree created, plan.md written |
| 3 | Implementation | phase-3-implementation.md | Code complete, fast checks pass |
| 4 | Testing | phase-4-testing.md | All tests pass OR user-approved stop |
| 5 | Documentation | phase-5-documentation.md | Docs reflect changes (incl. CLAUDE.md) |
| 6 | PR Creation | phase-6-pr-creation.md | Walkthrough shown, draft PR opened |
| 7 | CI Gate + Optional Cleanup | phase-7-ci-gate.md | CI green OR user-approved stop |
Phase 0 and Phase 2 are MANDATORY. All others gate progression to the next.
Phase 0 pre-authorization (--no-confirm).
If the invocation contains an explicit autonomy grant — the phrase "proceed without confirmation" or the --no-confirm flag — Phase 0 still runs, but posts its understanding summary and proceeds immediately instead of waiting for the user's "proceed".
The grant never covers a blocking missing-information gap: a load-bearing unknown (Phase 0 Step 3c) halts and asks regardless.
Default behavior without the grant is unchanged.
See phase-0-validation.md.
Companion Skills
Optional companions are invoked at specific phases based on task signals.
All companions skip silently if not installed — the workflow continues
without them. See rules/companion-skills.md
for the full registry, trigger conditions, and how to disable any companion.
| Phase | Companion | Trigger | Args |
|---|---|---|---|
| 0 | interview |
Full Mode default-on (adaptive — silent on a crisp request; skip on --no-interview, force on --interview). SSOT for restate-and-diff + Missing-Information Gate; writes .agent/{branch}/brief.md + readiness verdict |
— |
| 1 | lorekit-memory |
Always — read accumulated workflow lessons before design (fast-tier self-improvement) | memory.list loop::aw-lessons |
| 1 | holistic-analysis |
Complex / multi-domain / unfamiliar task | — |
| 1 | code-quality |
Always (informs design) | plan |
| 1 | critical |
Opt-in only (user passed --critical to the workflow). Single adversarial pre-mortem pass between code-quality(plan) and confidence(plan). Findings flow into aw-create-plan as plan defects (must-fix) and considered-alternatives notes (steelman). Advisory — does not gate. |
plan |
| 1 | optimize-approach |
Default-on in Full Mode (quiet early-exit; skip on --no-optimize). "Is this the most optimal approach?" pass between the pre-mortem and confidence(plan). Adopted proposals trigger a bounded re-plan via aw-create-plan. Advisory — does not gate. |
plan |
| 1 | confidence |
Always (plan gate, MANDATORY) | plan |
| 2 | aw-create-plan |
Full Mode only | — |
| 3 | lorekit-memory |
Executor entry — read lessons when plan.md has no ## Lessons applied (no-planner paths) |
memory.list loop::aw-lessons |
| 3 | tdd |
Pure logic / business rules / "test-driven" | — |
| 3 | ux |
UI files touched (*.tsx, *.jsx, *.vue, RN) |
— |
| 3 | code-quality |
Once at end of Phase 3 (not per-file) | code |
| 4 | test-provenance-guard |
After Step 5 — any new *.test.* / *.unit.* / *.spec.* file written |
--diff --base $(git merge-base HEAD main) --fix (autofix gated by confidence(code) ≥ 90 %) |
| 4 | confidence |
At iteration cap (3 Lite / 5 Full) on same failing area | analysis |
| 4 | holistic-analysis |
After confidence at Phase 4 if user asks for retry | — |
| 4 | lorekit-memory |
At stuck-loop escalation — record failing area + resolution as a lesson | memory.write loop::aw-lessons |
| 5 | docs |
Always (self-improving doc loop — updates CLAUDE.md, README.md, docs/) |
update --auto |
| 6 | aw-review-quality-gate |
After create-pr's review-loop returns findings — false-positive filter (advisory) |
— |
| 6 | aw-create-walkthrough |
Full Mode only | — |
| 6 | create-pr |
Always — push, open draft PR, run review-loop, watch CI | — |
| 6 (UI) | preview-spec |
Via create-pr Step 6.4 on a UI diff — PR-body verification spec, seeded from specs.md when present |
author |
| 7 | ci-auto-fix |
CI run completes with status failure |
<run-id|pr-url> |
| 7 | review-loop (skill) |
After CI green — bounded pr-reviewer → implement-suggestion → polish simplify convergence (self-relation; pr-reviewer detects authorship automatically) |
<pr-url> --critical |
| 7 | lorekit-memory |
End-of-run (CI green / user stop / post-merge bug) — record durable run lessons; check promotion | memory.write loop::aw-lessons |
Core Principles
- Detect the tier FIRST — Micro vs Lite vs Full before any other action.
- Phase 0 and Phase 2 are MANDATORY — no skipping validation or worktree.
checks.yamlis the living contract;plan.mdis the handoff document in Full Mode — both generated bySkill("aw-create-plan"). Gate on the checks; keep the plan lean and current (write drift back — see Phase 3).- Verify after editing — fast check before continuing.
- Stuck-loop has a mode-aware limit: 3 iterations (Lite) / 5 iterations (Full) on the same failing area triggers
Skill("confidence", "analysis")and auto-replan or escalation. - Companions are optional — never block on a missing companion.
- Stop and ask when blocked — don't guess on ambiguity. A
blockingmissing-information gap (Phase 0 Step 3c) halts even under--no-confirm. - Acceptance criteria are traceable and executable in Full Mode —
AC-{n}IDs cover every user-stated requirement (rule #9), plannedcreates carry an Existing Code Survey verdict (rule #10), andchecks.yaml(rule #11) is Phase 4's mechanical termination condition. Check definitions are executor-immutable; all-green is necessary, never sufficient. - User-requested changes are never scope creep — a change the user asks for is a new requirement, welcome at any lifecycle point including after the work is "done". Fold post-completion improvements in (re-detect the tier for the delta, reuse the existing branch/PR); the scope-creep guard restrains only your own unrequested expansion. See
rules/safety-guardrails.md.
Artifact System (Full Mode)
Artifacts in .agent/{branch-name}/, each generated by a dedicated skill:
| File(s) | Generated by | When |
|---|---|---|
checks.yaml |
Skill("aw-create-plan") (Step 2b) |
With the plan — one executable check per AC-{n}; the living contract and Phase 4's termination condition |
plan.md |
Skill("aw-create-plan") |
After Phase 2 — and on every plan iteration; the planner→executor handoff document |
walkthrough.md |
Skill("aw-create-walkthrough") |
Phase 6 |
checks.yaml is the artifact the executor is held to — it self-validates
against reality on every Phase 4 loop, so it never goes silently stale. plan.md
is a self-contained-but-lean handoff document (not an exhaustive knowledge base);
the executor writes decision/AC drift back into it so it stays honest (Phase 3).
Plan snapshots are opt-in. By default aw-create-plan writes only plan.md
(overwritten each iteration; the version: frontmatter still increments). Pass
the snapshot arg — Skill("aw-create-plan", "snapshot") — to also write an
immutable plan.v{N}.md audit trail; it is off by default because .agent/ is
gitignored scratch and the chain is rarely re-read. See
rules/artifacts-overview.md#plan-versioning.
Add .agent/ to .gitignore. Files are grouped by branch for easy browsing.
The directory is named
.agent/(singular) to align with the~/.agents/skills/cross-tool discovery convention used by Codex, Cursor, OpenCode, and other Agent Skills–compatible clients. The agent identity is implicit in artifact frontmatter; the directory itself is a per-project agent workspace.
Parallelization
Three phases benefit from sub-agent fan-out:
- Phase 1 (Planning) — when the task is complex/multi-domain, spawn parallel
Exploresub-agents during research (one per package, one for past PRs, one for related docs). See phase-1-planning.md. - Phase 3 (Implementation) — when the task decomposes into file-disjoint slices, fan out up to 3 concurrent sub-agents (hard cap, RAM-bounded). Each sub-agent MUST embed the Sub-Agent Resource Discipline line — scoped commands only, no whole-project
tsc/lint/test/build. See parallel-coordination.md#sub-agent-resource-discipline. - Phase 7 (CI Gate) — when multiple CI checks fail, spawn one
ci-auto-fixsub-agent per independent failure. Cap: 2 handoffs per PR. See phase-7-ci-gate.md.
Quick Reference
Full Mode
| Phase | Action |
|---|---|
| Setup | MODE SELECTION + prerequisite check |
| 0 | Scope alignment via interview (Full default; --no-interview falls back to inline) — restate-and-diff, missing-information gate (blocking halts even under --no-confirm), clarifying questions, brief.md; get explicit "proceed" |
| 1 | Analyze codebase (dependency-graph localization first; parallel Explore if complex), Existing Code Survey per planned create, traceable EARS-shaped ACs, design with code-quality(plan), optimize-approach(plan) approach check, confidence(plan) gate |
| 2 | gw add, gw cd, install deps, Skill("aw-create-plan") inside worktree (writes plan.md + checks.yaml) |
| 3 | Code per plan.md → companions per task type (tdd, ux) → fast-check after each edit; code-quality(code) once at end |
| 4 (UI) | First: aw-tester cold pass at Phase 4 entry (full sub-agent, structured verdict); subsequent iterations run the persisted last-run.spec.ts directly via Bash (hot loop, no sub-agent) until green/inconclusive; promote critical-path specs via e2e-testing Generator |
| 4 | Run tests → iterate (cap: 5 same area in Full Mode) → run checks.yaml checks (all must pass; definitions immutable; unsatisfiable escalates) → confidence(analysis) at cap → one-shot auto-replan or escalate to user |
| 5 | Skill("docs", "update --auto") always — refreshes CLAUDE.md, .claude/rules/, README.md, docs/, CHANGELOG.md |
| 6 | Skill("aw-create-walkthrough") → Skill("create-pr") (push → open draft PR → review-loop convergence → watch CI) |
| 7 | Watch CI → Skill("ci-auto-fix") per failure (parallel) → after CI green Skill("review-loop", "<pr-url> --critical --no-ci --no-preview-run") (self-relation; optional, skips if not installed) → gw remove after merge (optional) |
Lite Mode
Skip artifacts and most companions. Phase 0, Phase 2, Phase 5 (docs update), and Phase 6 (create-pr) still required.
| Phase | Action |
|---|---|
| Setup | MODE SELECTION |
| 0 | Quick clarification |
| 1 | Brief mental plan (no plan.md) |
| 2 | gw add fix/bug-name |
| 3 | Code, commit |
| 4 | Test, fix failures (3-iteration limit applies) |
| 5 | Skill("docs", "update --auto") |
| 6 | Skill("create-pr") |
| 7 | Watch CI, ci-auto-fix if needed, then Skill("review-loop", "<pr-url> --critical --no-ci --no-preview-run") (self-relation; skips if not installed) |
Customization
Disable companions by editing rules/companion-skills.md
(single source of truth for which skills run when) or by removing the
invocation block from the relevant phase rule. See README.md
for the full how-to.
Templates
The skill ships one dispatcher skill and three agents. The agents use the
aw- namespace prefix (short for "autonomous-workflow") so they group
together in .claude/agents/ and are unmistakable when listed alongside
unrelated agents:
| Unit | Kind | Role | Terminal artifact | Exit gate |
|---|---|---|---|---|
aw |
skill | Opt-in dispatcher. Reads lessons, detects tier (Micro/Lite/Full), routes single-pass vs the split, owns the self-improvement loop for every tier. | — (delegates) | Task routed + exit lesson written |
aw-planner |
agent | Full-tier, phases 0–2 | .agent/{branch}/plan.md + checks.yaml + specs.md (UI tasks) |
confidence(plan) ≥ 90% (or user-approved) |
aw-executor |
agent | Full-tier, phases 3–7 | .agent/{branch}/walkthrough.md + draft PR |
Walkthrough shown inline, Phase 7 CI gate run |
aw-tester |
agent | Phase 4 (UI) spec verification — cold pass only (Phase 4 entry, escalation, Phase 7 rehearsal). Iteration uses the persisted last-run.spec.ts directly via Bash, not a sub-agent. |
Verdict block (~200 tokens) with hot_loop: paths for direct re-run |
green or inconclusive before lint/type/test |
aw is the single entry point developers opt into (a trigger phrase or
/aw). It is adaptive, not always-heavy: Micro/Lite run single-pass in the
caller's context; Full hands off to the planner→executor split. The split is
along the Phase 2 → Phase 3 context boundary, mediated by plan.md, and is
reserved for Full because its context-isolation + resumable-artifact benefits
only pay for complex/long tasks (always-planning wastes compute and degrades
long-horizon performance — see references/anthropic-architecture-research.md). The handoff is gated: high-confidence plans flow through
automatically; borderline plans pause for user approval. The design rationale
(with verbatim Anthropic citations) lives in
references/anthropic-architecture-research.md;
the full handoff contract is in
rules/planner-executor-handoff.md.
The dispatcher is a skill, not an agent (since v3.23). It fails the repo's
own third-agent test — 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" — and being an agent cost it a delegation rung, a
duplicated tier table with an L1 guard to police it, and a triplicated tool
grant. As a skill it runs in the caller's context, so aw-planner /
aw-executor are dispatched from the top-level session. Rationale:
CLAUDE.md.
When the harness disables sub-agent dispatch (no available tool dispatches a
sub-agent — Task, Agent, or another spelling — e.g. Claude Code on the web),
the split is structurally unavailable and Full does not
drop to the Micro/Lite single-pass path. aw runs a single-context Full
instead: it plays the planner role (Phases 0–2, producing plan.md +
checks.yaml and clearing confidence(plan) ≥ 90%) then the executor role
(Phases 3–7) in one window, preserving the plan artifact and the confidence gate
and conceding only context isolation. Note the dispatcher itself needs no
dispatch tool to start — that is the difference from the agent form, which could
not be reached at all. The step-by-step procedure — and the rule that this is never a
licence to skip an available split — lives in
aw/SKILL.md under "When sub-agent dispatch is unavailable".
UI verification prerequisite: run /aw-setup once per project before the
first autonomous UI task. This scaffolds .claude/aw-targets/local.yml and
validates it with a smoke spec. The planner halts and prompts if no aw-target
exists — do not auto-scaffold.
| Template | Purpose |
|---|---|
| aw/SKILL.md (a skill, not a template) | aw dispatcher (tier routing + loop) — installed as a skill, invoked /aw |
| aw-planner.agent.md | Planner agent definition (phases 0-2) — emits specs.md for UI tasks |
| aw-executor.agent.md | Executor agent definition (phases 3-7) |
| aw-tester.agent.md | Spec-driven UI verification (Phase 4) — dispatched by executor |
| routing.rule.md | Auto-trigger rule for .claude/rules/ |
| aw-target.yml.template | Aw-Target schema (base URL, auth, fixtures) |
| specs.md.template | Specs file schema with example blocks |
Auto-Trigger Setup (Recommended)
Install the skill, its companions, and the aw-* agents in one step:
git clone https://github.com/mthines/agent-skills.git
cd agent-skills
bash scripts/sync-symlinks.sh --aw
--aw symlinks the autonomous-workflow skill, the aw dispatcher skill, and
the companion skills into ~/.claude/skills/, plus the aw-planner /
aw-executor / aw-tester agents into ~/.claude/agents/. The review-loop
skill (Phase 6/7 review passes) is also linked; if absent Phase 7 logs
review-loop — not available, continuing and proceeds. Edits to the cloned repo
are picked up live on the next agent turn.
The routing rule invokes Skill("aw"), which detects the tier and routes —
Micro/Lite single-pass, or planner→executor for Full. After install, Claude
auto-triggers on phrases like "implement X independently", "in isolation",
"end-to-end".
To install the full repo (not just the AW bundle) drop the --aw flag. For
the per-project install, the no-clone npx skills add alternative, or
per-companion disabling, see the README and
rules/companion-skills.md.
Related Skills
confidence— quality gate (plan, code, analysis)aw-create-plan—plan.mdartifact generatoraw-create-walkthrough—walkthrough.mdartifact generatoraw-setup— one-time UI aw-target scaffolding (prerequisite foraw-tester; run/aw-setuponce per project before the first autonomous UI task)aw-tester-chrome— in-session Chrome runner; the fast local sibling of theaw-testeragent. Same spec grammar and verdict, driven through the claude-in-chrome extension instead of Playwright. Picked bypreview-spec run --driver chrome|auto; not for sub-agent / CI flows (no extension there)code-quality— readability and complexity reviewtdd— RED-GREEN-REFACTOR enforcementux— UI / accessibility reviewholistic-analysis— execution-path analysis for complex tasksdocs— keepsCLAUDE.md,.claude/rules/,README.md, anddocs/in sync with code changesreview-changes— routes toreview-loop(convergence) orpr-reviewer(one-shot)review-loop— boundedpr-reviewer→implement-suggestion→polish simplifyconvergence loop; Phase 6/7 review passescreate-pr— narrative PR description + push + open draft PR + review-loop + watchci-auto-fix— diagnose and fix failed CI checkslorekit-memory(LoreKitmemory.*tools) — backs theaw-lessonsandaw-tester-lessonsfast-tier self-improvement loops. See alsopersistent-memoryfor the LoreKit backend docs (rules/scaling-tiers.md)e2e-testing— Generator for promotingcritical-pathspecs to saved*.spec.tsat end of Phase 4
Related Agents
aw-tester— spec-driven UI verification agent (Playwright, sub-agent). Dispatched by the executor in Phase 4 (before lint/type/test) and optionally in Phase 7 (spec rehearsal against preview). Requires an aw-target at.claude/aw-targets/— run/aw-setupfirst. Shares the engine-agnostic spec-run contract with the in-sessionaw-tester-chromerunner.pr-reviewer— Phase 6 and Phase 7 review passes, invoked via thereview-loopskill. Handles both self-relation (own PR —REVIEW_RELATION = self) and cross-relation (someone else's PR). Stays read-only; apply passes are delegated toimplement-suggestionandpolish simplify.
Research Sources
- Addy Osmani's LLM Workflow — fast feedback loops
- Claude Code Worktree Support — worktree practices
- Full Anthropic architecture citations:
references/anthropic-architecture-research.md