Autonomous Workflow

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](./rules/companion-skills.md).

---

Self-Improvement

The workflow improves across runs through a two-tier loop (full contract in [rules/self-improvement-loop.md](./rules/self-improvement-loop.md)):

Fast tier — episodic lessons (persistent-memory, optional companion). The workflow reads accumulated lessons before planning (Phase 1) and writes new ones when it gets stuck (Phase 4) or finishes (Phase 7), in the committed aw-lessons scope. Lessons are advisory — they bias the plan, never silently change a gate. Skips silently if persistent-memory is not installed. 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](../../authoring/create-skill/SKILL.md#diagnose-workflow) while the failing session is still in context. The diagnoser reads this skill's [diagnostic surface](./rules/diagnostic-surface.md) (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](./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](./rules/prerequisites.md) for the full feature comparison and installation steps.

---

Workflow Phases

| Phase | Name | Rule file | Gate | | ----- | -------------------------- | -------------------------------------------------------------- | --------------------------------------------- | | 0 | Validation | [phase-0-validation.md](./rules/phase-0-validation.md) | User confirmed understanding | | 1 | Planning | [phase-1-planning.md](./rules/phase-1-planning.md) | confidence(plan) ≥ 90% or user-approved | | 2 | Worktree Setup | [phase-2-worktree.md](./rules/phase-2-worktree.md) | Worktree created, plan.md written | | 3 | Implementation | [phase-3-implementation.md](./rules/phase-3-implementation.md) | Code complete, fast checks pass | | 4 | Testing | [phase-4-testing.md](./rules/phase-4-testing.md) | All tests pass OR user-approved stop | | 5 | Documentation | [phase-5-documentation.md](./rules/phase-5-documentation.md) | Docs reflect changes (incl. CLAUDE.md) | | 6 | PR Creation | [phase-6-pr-creation.md](./rules/phase-6-pr-creation.md) | Walkthrough shown, draft PR opened | | 7 | CI Gate + Optional Cleanup | [phase-7-ci-gate.md](./rules/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](./rules/phase-0-validation.md#step-5-get-explicit-confirmation).

---

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](./rules/companion-skills.md) for the full registry, trigger conditions, and how to disable any companion.

| Phase | Companion | Trigger | Args | | ----- | ---------------------- | ------------------------------------------------------ | ---------------- | | 1 | persistent-memory | Always — read accumulated workflow lessons before design (fast-tier self-improvement) | read aw-lessons --tier home | | 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 | confidence | Always (plan gate, MANDATORY) | plan | | 2 | aw-create-plan | Full Mode only | — | | 3 | persistent-memory | Executor entry — read lessons when plan.md has no ## Lessons applied (no-planner paths) | read aw-lessons --tier home | | 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 | persistent-memory | At stuck-loop escalation — record failing area + resolution as a lesson | write aw-lessons --tier home --auto | | 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 | ` | | 7 | persistent-memory | End-of-run (CI green / user stop / post-merge bug) — record durable run lessons; check promotion | write aw-lessons --tier home --auto | | 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) | --critical` + auto-fix-all prompt |

---

Core Principles

1. Detect the tier FIRST — Micro vs Lite vs Full before any other action.
2. Phase 0 and Phase 2 are MANDATORY — no skipping validation or worktree.
3. plan.md is the single source of truth in Full Mode — generated by Skill("aw-create-plan").
4. Verify after editing — fast check before continuing.
5. 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.
6. Companions are optional — never block on a missing companion.
7. Stop and ask when blocked — don't guess on ambiguity. A blocking missing-information gap (Phase 0 Step 3c) halts even under --no-confirm.
8. No AI co-author tags — never add Co-Authored-By lines to commits or PRs.
9. 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)

Three artifacts in .agent/{branch-name}/, each generated by a dedicated skill:

| File(s) | Generated by | When | | -------------------------------------- | -------------------------------- | ------------------------------------------------- | | plan.md + plan.v{N}.md snapshots | Skill("aw-create-plan") | After Phase 2 — and on every plan iteration | | checks.yaml | Skill("aw-create-plan") (Step 2b) | With the plan — one executable check per AC-{n}; Phase 4's termination condition | | walkthrough.md | Skill("aw-create-walkthrough") | Phase 6 |

plan.md always points at the latest version. Each call to aw-create-plan also writes an immutable plan.v{N}.md snapshot (plan.v1.md on the first run, plan.v2.md on the next, …) so iteration history is preserved. See [rules/artifacts-overview.md#plan-versioning](./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](./rules/phase-1-planning.md#parallel-research).
• 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](./rules/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](./rules/phase-7-ci-gate.md#parallel-ci-fixes).

---

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; para

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: mthines
• Source: mthines/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.