| name | autonomous-workflow |
| description | Execute complete feature development cycles autonomously — from task intake through tested PR delivery — using isolated Git worktrees. Phase-based workflow (0–7) with optional companion skills for planning, quality gates, TDD, UX, code quality, docs, and CI verification. Companions skip silently if not installed. Triggers on "implement autonomously", "end-to-end", "in isolation", "in a worktree", or independent feature work. Invoke with /autonomous-workflow.
|
| disable-model-invocation | false |
| argument-hint | <task-description> [--no-confirm] [--critical] |
| license | MIT |
| metadata | {"author":"mthines","version":"3.18.0","workflow_type":"orchestrator","tags":["autonomous","workflow","worktree","feature-development","pr"]} |
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.md is a thin index. Detailed procedures
live in rules/*.md and load on demand. Companion-skill triggers and
disable instructions live in rules/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? | 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 | Required | planner → plan.md | all applicable |
| Lite | 2–3 files, simple logic | None | brief mental plan | per signal |
| Micro | 1 file, purely mechanical (typo, copy, bump) | None | none (skip planning) | none (docs if drift) |
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 dispatcher template, the planner template, and
rules/phase-0-validation.md emit it
field-for-field identically.
Step 2: Verify Prerequisites
| Tool | Status | Check | If missing |
|---|
gh | REQUIRED | which gh | Stop, prompt user to install |
gw | Recommended | which gw | Continue with native git worktree fallback (warn user once) |
gh is hard-required for Phase 6 (PR creation) and Phase 7 (CI gate).
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 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 |
|---|
| 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 | reviewer (agent) | Always before push — dispatched directly via the Agent tool (Fix Mode on own branch; auto-fix all Simple findings across every severity) | --critical + auto-fix-all prompt |
| 6 | aw-review-quality-gate | After the reviewer agent returns findings — false-positive filter (advisory) | — |
| 6 | aw-create-walkthrough | Full Mode only | — |
| 6 | create-pr | Always | — |
| 7 | ci-auto-fix | CI run completes with status failure | <run-id|pr-url> |
| 7 | lorekit-memory | End-of-run (CI green / user stop / post-merge bug) — record durable run lessons; check promotion | memory.write loop::aw-lessons |
| 7 | reviewer (agent) | After CI green — auto-dispatch in PR Mode (self-review sub-mode for self-authored PRs: inline report + auto-fix every Simple finding regardless of severity, incl. Nitpick / Nice-to-have; cross-author PR redirects to pr-reviewer) | <pr-url> --critical + auto-fix-all prompt |
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.yaml is the living contract; plan.md is the handoff document in Full Mode — both generated by Skill("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
blocking missing-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), planned creates carry an Existing Code Survey verdict (rule #10), and checks.yaml (rule #11) is Phase 4's mechanical termination condition. Check definitions are executor-immutable; all-green is necessary, never sufficient.
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
Explore sub-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-fix sub-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 | Restate-and-diff the requirements, run the missing-information gate (blocking halts even under --no-confirm), ask clarifying questions, 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 | Dispatch reviewer agent (--critical, auto-fix every Simple finding across all severities) → Skill("aw-create-walkthrough") → Skill("create-pr") |
| 7 | Watch CI → Skill("ci-auto-fix") per failure (parallel) → after CI green dispatch reviewer agent (<pr-url> --critical, PR Mode self-review sub-mode: auto-fix every Simple finding incl. Nitpick / Nice-to-have, emit inline report; 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 auto-dispatch reviewer agent with --critical + auto-fix-all-Simple-severities prompt (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 installs four agents under the aw- namespace prefix (short
for "autonomous-workflow") so they group together in .claude/agents/ and are
unmistakable when listed alongside unrelated agents:
| Agent | Role | Terminal artifact | Exit gate |
|---|
aw | 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 | Full-tier, phases 0–2 | .agent/{branch}/plan.md + checks.yaml + specs.md (UI tasks) | confidence(plan) ≥ 90% (or user-approved) |
aw-executor | Full-tier, phases 3–7 | .agent/{branch}/walkthrough.md + draft PR | Walkthrough shown inline, Phase 7 CI gate run |
aw-tester | 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 aw's
own 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.
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.
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 and its 12 companion skills
into ~/.claude/skills/, plus the aw / aw-planner / aw-executor agents
into ~/.claude/agents/. The reviewer agent (optional Phase 6/7 review) is
also linked; remove its symlink and Phase 7 logs reviewer — not available, continuing and proceeds. Edits to the cloned repo are picked up live on the
next agent turn.
The routing rule dispatches 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.md artifact generatoraw-create-walkthrough — walkthrough.md artifact generatoraw-setup — one-time UI aw-target scaffolding (prerequisite for aw-tester; run /aw-setup once per project before the first autonomous UI task)code-quality — readability and complexity reviewtdd — RED-GREEN-REFACTOR enforcementux — UI / accessibility reviewholistic-analysis — execution-path analysis for complex tasksdocs — keeps CLAUDE.md, .claude/rules/, README.md, and docs/ in sync with code changesreview-changes — pre-PR reviewcreate-pr — narrative PR description + push + watchci-auto-fix — diagnose and fix failed CI checkslorekit-memory (LoreKit memory.* tools) — backs the aw-lessons and aw-tester-lessons fast-tier self-improvement loops. See also persistent-memory for the LoreKit backend docs (rules/scaling-tiers.md)e2e-testing — Generator for promoting critical-path specs to saved *.spec.ts at end of Phase 4
Related Agents
aw-tester — spec-driven UI verification 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-setup first.reviewer — optional Phase 6 pre-push review AND Phase 7 post-CI auto-review. Both passes are dispatched with --critical (forces the adversarial pre-mortem via Skill("critical", "code")) and an auto-fix-everything prompt — every Simple finding is applied to the working tree regardless of severity (Critical / High / Medium / Low / Nitpick / Nice-to-have), per agents/reviewer/rules/auto-fix-policy.md. Phase 6 lands in Fix Mode (own branch); Phase 7 lands in PR (self-review) sub-mode (self-authored PR — inline terminal report, no GitHub posts). On someone else's PR the reviewer redirects to the pr-reviewer agent. Install the agent alongside the skill and the workflow will dispatch it automatically.
Research Sources
