The Autonomy Progression

Don't start at full autonomy. Work through this in order.

Stage 1 — Supervised

Run adw_plan_build.py manually for every issue. Read every spec before it builds. Review every PR line by line.

Goal: Understand what the planner produces for your codebase. Correct bad patterns in your issue writing.

# Supervised workflow
cd adws
uv run adw_plan_build.py <issue>
# Review the spec file in specs/
# Review the PR on GitHub
# Merge manually

Signs you're ready for Stage 2:

• The specs are well-structured and match your expectations
• You stop finding architectural mistakes in the implementations
• You've corrected your issue writing style at least once

Stage 2 — Test-Gated

Switch to adw_plan_build_test.py. Tests validate automatically. Start the cron trigger for simple issues.

Goal: Trust the test phase. Stop reviewing test output manually.

# Test-gated workflow
uv run adw_plan_build_test.py <issue>

# Or start cron for simple issues
uv run adw_triggers/trigger_cron.py

Signs you're ready for Stage 3:

• Tests are passing consistently without manual intervention
• You've seen the auto-fix loop resolve test failures correctly
• You only check GitHub issue comments, not every test log

Stage 3 — Review-Gated

Switch to adw_sdlc.py. Set up the webhook. Review PRs by reading the review screenshots and spec comparison — not every line of code.

Goal: Trust the review phase. Set up Cloudflare R2 so screenshots appear inline in GitHub PR comments.

# Full SDLC
uv run adw_sdlc.py <issue>

# Start webhook for real-time processing
uv run adw_triggers/trigger_webhook.py

Signs you're ready for Stage 4:

• Review screenshots match what you expected
• The auto-patch loop is resolving blockers correctly
• You're reviewing PRs in under 5 minutes

Stage 4 — Out-Loop

Trigger via webhook comment with adw_sdlc. Your interface is GitHub issues. You write what you want. You come back to a PR.

Goal: The system builds it. You review and merge.

GitHub Issues → write issue → comment "adw_sdlc" → come back to PR

The full workflow at Stage 4:

1. Open a GitHub issue with a well-written spec
2. Comment adw_sdlc (or let cron pick it up automatically)
3. Bot posts confirmation with ADW ID
4. Bot posts phase completion messages as work progresses
5. Bot posts PR link with review screenshots
6. You read the review summary and check key files
7. Merge

Why Not Start at Stage 4?

The system makes decisions. If you haven't calibrated it to your codebase:

• The planner might choose wrong architectural patterns for your project
• The implementor might put code in the wrong files
• The reviewer might miss project-specific constraints

Working through the stages teaches you what to put in your issue to guide the agent correctly. After 10-20 supervised runs, you'll have calibrated your issue-writing style and the system will produce reliable output at full autonomy.

Improving the System

When an agent fails repeatedly on a type of task, fix the slash command prompt — not the individual run:

.claude/commands/feature.md      — planner prompt for features
.claude/commands/bug.md          — planner prompt for bugs
.claude/commands/implement.md    — implementor prompt
.claude/commands/test.md         — test runner prompt
.claude/commands/review.md       — reviewer prompt

Every improvement to a prompt propagates to all future runs. The prompts are the system.