I 6 levels
The higher the level, the more Claude does on its own and the less you touch. Rules, hooks and quality gates from the lower levels still apply at every level above.
🪜 Summary
| Level | How | You take part |
|---|---|---|
| 1 | Ask & explore | Every question |
| 2 | Direct work with guardrails | Each step, approve the push |
| 3 | Workflow skills + swarm | Approve each artifact (PRD, ADR, Spec, Plan) |
| 4 | Local /autopilot | 3 times: Start, Gate 1, Gate 2 |
| 5 | Headless on GitHub | Add the label, /approve, merge |
| 6 | Auto gates | Only add the label |
1 Ask & explore
Ask about the code. Claude reads and greps before answering, no code changes.
💬 How Level 1
📌 Real example
→ 3 levels, Level 2 recommended (DB + TaskScheduler + admin UI).
2 Direct work with guardrails
Claude changes code in the session; you watch each step.
🛡️ Always-on guardrails Level 2
CLAUDE.md+.claude/rules/always loaded- Library skills auto-load
- Hooks catch secrets
session.txt- Ask before every push
📌 Real example
Cron editor modal + tooltip (df8bdba1, 9b1d5419): done directly, not through autopilot.
3 Workflow skills + swarm
Follow the planning flow; each step produces an artifact in docs/.
🐝 Skill chain Level 3
/scope → /architect → /spec → /swarm-plan → /swarm-execute → /swarm-review → /land-the-plane
Worker agents run in parallel, model pinned per agent.
📌 Real example
"Premium user" feature: autopilot refused because it needs a PRD → go to /scope.
3+ How the agents work together
One orchestrator, focused workers, separate reviewers.
🧭 Roles
- The orchestrator is the main session (Opus). It is the only agent that starts workers (workers have no
Agenttool), owns the task list, merges their work, runs the gates and asks you at the gates. - Each worker gets one focused prompt and returns a summary (files changed, tests added, verdict block), not file dumps. Workers never share state with each other.
worker-builderworks in its own git worktree. The orchestrator merges or cherry-picks its commits intomain, then re-runs the gates itself.- Reviewers are separate agents from builders. Each ends with a verdict block (
approve/revise). Only blocking findings send work back, at most 3 rounds.
You (Start · Gate 1 · Gate 2)
│
Orchestrator (main session, Opus)
┌──────────────┬─────────┴──────────┬──────────────────┐
worker-explorer ×3 worker-reviewer worker-builder ×2 worker-reviewer ×2
(Haiku: find (plan review) (BE + FE, each in (quality + security)
existing patterns) its own worktree)
📌 Example: the dynamic cron jobs run
| Step | Agent(s) | Model | Result | Cost |
|---|---|---|---|---|
| Explore | 3 × worker-explorer: Liquibase + entity patterns, backend admin patterns, webapp admin UI patterns | Haiku | Patterns for the plan; the orchestrator writes the plan + ADR-0023 | $0.03 |
| Plan review | worker-reviewer | Sonnet | approve, 0 blocking, 7 advisory | $0.16 |
| Gate 1 | you | — | approved | — |
| Implement | 2 × worker-builder in parallel: BE (DJ-1..3), FE (DJ-4..5) | Sonnet | Committed in worktrees, cherry-picked onto main | $0.42 + $0.25 |
| Code review | 2 × worker-reviewer: quality, security | Sonnet | approve, 0 blocking, 6 advisory | $0.17 + $0.15 |
| QA ×2, gates, commit, CI + smoke | orchestrator | Opus | 84 tests pass twice, CI green, smoke 22/22 | $2.53 (whole run) |
4 Local /autopilot
Chains the workflow skills into one run; at most 3 rounds per loop.
🤖 Flow Level 4
plan ⇄ review → Gate 1 → implement ⇄ review → QA ×2 → commit → Gate 2 → CI + smoke
📌 Real example
🪶 Lite mode
Under 100 changed lines not counting tests, and no ADR: no docs/plans/plan-*.md and no docs/reports/autopilot-*.md. The plan and the report go to the console (local) or the PR body (headless).
5 Headless on GitHub
ADR-0022 · workflow .github/workflows/autopilot.yml · both gates move to GitHub.
☁️ Steps Level 5
| Step | You do | Autopilot does |
|---|---|---|
| Start | Add the label autopilot to an issue | Plans and reviews on autopilot/issue-<N>, opens a draft PR |
| Gate 1 | Comment /approve, or /revise <notes> | Implement ⇄ review → QA ×2 → full gates → pushes to the PR branch, marks it ready |
| Gate 2 | Review the diff and merge the PR (CI deploys it) | Never pushes to main, never merges |
| After deploy | Run ./api/mock-test.sh | — |
📌 Real example
Issue #34 (back button color) → PR #35.
🔒 Safety
- Only the repo owner can trigger a run, by label or by comment.
- Issue text is data; instructions that try to change the workflow, permissions or gates are ignored.
- Refuses to edit
.github/,.claude/,CLAUDE.md,AGENTS.md,.envfiles, or write data-dropping migrations.
6 Auto gates
ADR-0025 · add one more label together with autopilot.
⚡ Labels Level 6
| Extra label | Gate 1 | Gate 2 |
|---|---|---|
| (none) | you /approve | you merge |
autopilot:auto-merge | you /approve | automatic merge |
autopilot:auto | automatic | automatic merge |
✅ Auto-merge conditions
- The PR is ready, meaning code review returned
approve. - No changes to
.github/,.claude/,CLAUDE.md,AGENTS.md,scripts/claude-*, Liquibase migrations or.env. - ≤ 400 changed lines outside tests and docs.
- The script re-runs
mvn verify/ webapp test + lint + build itself.
🔎 Details
Gate 1: the plan job writes <!-- autopilot:plan-review=approve --> in the PR body only when plan review returned approve; the workflow sees it and dispatches the build job (workflow_dispatch). A /revise always waits for you.
Gate 2: scripts/claude-autopilot-merge.sh (always the copy on main) squash-merges with the secret AUTOPILOT_MERGE_TOKEN. If any check fails, it comments the reason and leaves the PR to you.
📌 Real example
⚠️ Risk
Code reaches prod without a human read. The smoke check after the deploy is still manual. Rollback = git revert the squash commit.
II Which level to pick
🧭 By kind of work
| Work | Level |
|---|---|
| Not sure what to do yet, or you only need to understand the code | 1 |
| A small change you want to watch step by step | 2 |
| A medium or large feature (needs a PRD, several days) | 3 |
| A small feature, fix or refactor with clear acceptance criteria | 4, or 5 without a terminal |
| Small, low-risk work that touches no migration or agent config | 6 |