Autonomous Workflow

Phase-based autonomous feature development: each phase has a gate that must pass before the next. This file is an index; procedures live in rules/*.md and load on demand.

Contents

• Before Starting Any Work — Step 1 tier detection, Step 2 prerequisites
• Workflow Phases
• Core Principles
• Artifacts
• Lite and Micro path
• Companions and parallelization
• Units and install

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:

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:

• Q4's OR is 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.

Questions 1–2 ground the decision in complexity rather than raw file count (one large change can exceed four trivial edits in scope); question 3 is the file-count tie-breaker. Phase 0 and Phase 2 stay mandatory in every tier, including Micro.

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 and rules/phase-0-validation.md emit it field-for-field.

Step 2: Verify Prerequisites

gh is one of two GitHub paths; in cloud sessions it is absent and the mcp__github__* tools both agents carry are the path. Details: rules/prerequisites.md — read when a prerequisite is missing.

Workflow Phases

Phase 0 and Phase 2 are MANDATORY. All others gate progression to the next. --no-confirm (or "proceed without confirmation") makes Phase 0 post its summary and proceed without waiting; it never covers a blocking missing-information gap — phase-0-validation.md.

Core Principles

1. Detect the tier first — Micro, Lite, or Full before any other action.
2. Phase 0 and Phase 2 are mandatory — no skipping validation or the worktree.
3. Plan as a brief, review after the fact. The brief is at most 60 lines of outcomes and sourced limits — Task, Requirements, Guardrails, Acceptance Criteria (Definition of Done), Turn Cap, and starting File Changes — never a design; a fresh-context reviewer and the human's one-page walkthrough check the result.
4. Done is a command, not a judgment. In Full Mode, Phase 4 ends only on the run-checks.mjs sentinel CHECKS M/M PASS (<sha>); check definitions are sealed and executor-immutable, and all-green is necessary, never sufficient.
5. Print the goal and the evidence. At the end of planning print a paste-ready /goal line; before the terminal contract print the AW EVIDENCE block — rules/goal-emission.md.
6. Verify after editing — the brief's After-editing command before continuing.
7. Stuck-loop cap is mode-aware: 3 (Lite) / 5 (Full) iterations on the same failing area trigger Skill("confidence", "analysis"), then one auto-replan or escalation.
8. Companions never block, and never skip silently.
9. Stop and ask when blocked. A blocking missing-information gap halts even under --no-confirm.
10. User-requested changes are never scope creep — fold post-completion improvements in as a new iteration — rules/safety-guardrails.md.

Artifacts

Full Mode artifacts live in .agent/{branch}/ (add .agent/ to .gitignore):

Snapshots (plan.v{N}.md) are opt-in via Skill("aw-create-plan", "snapshot"). Artifact details: rules/artifacts-overview.md — read when resuming a run or reading artifacts cold.

Lite and Micro path

Single-pass in the caller's context; no checks.yaml, no confidence(plan). Lite writes its brief to .agent/{branch}/plan.md inside the worktree, after Phase 2 creates it, so aw-verify and telemetry-verify read stated criteria instead of guessing them from the diff; Micro keeps its brief in the conversation.

---
tier: Lite
turn_cap: 12
---
## Task
Debounce the search box so typing does not fire a request per keystroke.
## Guardrails
- Keep unchanged: the `?q=` URL contract — docs/search.md
## Acceptance Criteria
- [ ] AC-1 — When the user types "otel" quickly, the system shall send one search request.
- [ ] AC-2 — When the user clears the box, the system shall show the recent-searches list.
- **Before PR**: `pnpm vitest run src/search`
## File Changes
- `src/search/SearchBox.tsx`

Keep it at most 20 lines: tier: Lite frontmatter, Task, Guardrails, AC-{n} outcome criteria (a telemetry: prefix where the change adds a signal), the Before-PR command, and the files. Never write checks.yaml or checks.lock on Lite: checks.lock is what marks a Full brief.

Lite verify

Lite proves a UI change in the browser before the PR, the same way Full Step 4.1 does; Micro never runs it.

1. .agents/aw/environments.yml exists → Skill("aw-verify", "run local --no-push --no-comment --foreign-stack abort"). It copies the AC-{n} criteria from the Lite plan.md, writes the specs, runs them through ui-verify, fixes what it finds as separate commits, and leaves its screenshots and recordings where create-pr Step 6.2 picks them up.
2. A failed ui: criterion, a BROKEN verdict, or a telemetry: AC whose receipt is contradicts re-enters Phase 3 under the same turn cap. Any other telemetry: receipt that is not confirms goes under Degraded:, as Full Step 4.1 leaves it unpassed.
3. No .agents/aw/environments.yml → verify run: not configured under Degraded: and run /aw-verify setup under Needs you:; never block on setup.
4. Print the verify run: line from Full's AW EVIDENCE block (aw/rules/full-tier.md § Step 4) in Lite's AW EVIDENCE block.

✗ Wrong — Lite UI diff, verify configured, PR opened with no browser evidence
✓ Right — aw-verify run local → create-pr attaches its captures → aw-verify report <pr-url> posts the report

Companions and parallelization

The registry — triggers, args, the mandatory companion: <name> — ran | skipped (<reason>) report line, and how to disable a companion — is rules/companion-skills.md; each agent template carries the rows for its phases. Lessons: the fast tier (loop::aw-lessons on LoreKit) and the slow tier (/create-skill diagnose autonomous-workflow) are in rules/self-improvement-loop.md; the diagnoser reads rules/diagnostic-surface.md.

Fan-out points, each read when it applies:

• Phase 1 — at most two Explore sub-agents, only for an unfamiliar area: phase-1-planning.md.
• Phase 3 — up to 3 concurrent sub-agents on file-disjoint slices, each embedding the resource-discipline line: parallel-coordination.md.
• Phase 7 — one ci-auto-fix sub-agent per independent failure, cap 2 handoffs per PR: phase-7-ci-gate.md.

Units and install

The skill ships one dispatcher skill and two agents (aw- = autonomous-workflow):

Other files: routing.rule.md (auto-trigger rule), specs.md.template, intent-spec.md.template, scripts/run-checks.mjs (the check runner; --self-test proves it). Related skills: aw-verify (run /aw-verify setup once per project; it writes .agents/aw/, which aw-tester targets come from), aw-tester-chrome (in-session Chrome runner), aw-create-plan, aw-create-walkthrough. Design rationale: CLAUDE.md and references/anthropic-architecture-research.md.

Install the skill, its companions, and the agents:

git clone https://github.com/mthines/agent-skills.git
cd agent-skills
bash scripts/sync-symlinks.sh --aw

Other install modes and per-companion disabling: README.md.