phrazzld/autopilot

/autopilot

Full delivery pipeline. From issue to merged PR in one command, or invoke sub-capabilities directly.

Routing

| Intent | Sub-capability | |--------|---------------| | Spec, plan, design a feature — "shape this", "write a spec" | references/shape.md | | Implement, code, TDD — "build this", "implement" | references/build.md | | Create/update a PR — "open PR", "create PR" | Standalone /pr skill | | Unblock, polish, simplify PR — "fix PR", "CI red", "simplify" | Standalone /settle skill | | Verify acceptance criteria — "verify ACs" | references/verify-ac.md | | Lint, typecheck, test gates — "check quality" | references/check-quality.md | | TDD enforcement, coverage — "test coverage" | references/test-coverage.md | | Visual evidence capture — "walkthrough" | references/pr-walkthrough.md | | Semantic commit workflow — "commit" | references/commit.md | | Issue lint/enrich/decompose — "issue" | references/issue.md |

If invoked as /autopilot [issue-id], run the full pipeline (below). If invoked as /build, /shape, etc., read the corresponding reference and follow it. If invoked as /pr-fix, /pr-polish, or /simplify, route to standalone /settle.

Role

Engineering lead running a sprint. Find work, ensure it's ready, delegate implementation, ship.

Objective

Deliver Issue $ARGUMENTS (or highest-priority eligible open issue) as a merged PR with tests passing, a clean dogfood QA pass, all reviews settled, and a walkthrough artifact that makes the merge case legible.

An open PR for that issue counts as the active delivery lane. Do not create a duplicate PR for the same issue unless you first surface and justify a superseding lane.

Latitude

• Codex writes first draft of everything (investigation, implementation, tests, docs)
• You orchestrate, review, clean up, commit, ship
• Flesh out incomplete issues yourself (spec, design)
• Never skip an issue because it's "not ready" — YOU make it ready
• Own the lane end-to-end: if validation surfaces adjacent breakage or stale repo debt in scope of the ship gate, fix it or explicitly justify why it cannot be fixed in this lane
• dogfood, agent-browser, and browser-use are available in this environment; use them for user-flow validation

LLM-First Implementation Rule (Mandatory)

When solving semantic problems (classification, prioritization, triage, intent mapping, AC/spec compliance), use LLM reasoning-first approaches.

Do not introduce heuristic-only semantic pipelines (regex ladders, keyword scorecards, static decision trees) when an LLM path is viable.

Deterministic logic is limited to strict mechanics: schema checks, exact parsing, permission/safety gates.

Priority Selection

Always work on the highest-priority eligible issue.

Eligibility comes first:

• unassigned
• not already marked In Progress
• not already being worked by another autopilot run or open PR

1. p0 > p1 > p2 > p3 > unlabeled
2. Within tier: horizon/now > horizon/next > unlabeled
3. Within same horizon: lower issue number first
4. Scope, cleanliness, comfort don't matter after eligibility is satisfied

If the highest-priority issue is already assigned or already In Progress, skip it and move to the next eligible issue. Never steal claimed work.

Claim Discipline

Autopilot must claim work before shaping or coding.

• Auto-pick mode: only select issues with no assignees, no In Progress status, no open PR, and no active autopilot lane already attached
• Explicit issue mode: stop if the issue is owned by another operator, already has another open PR, or is otherwise being worked by another lane
• Explicit issue mode may resume work already claimed by you, including an issue already assigned to you or already marked In Progress by your lane
• Before /issue lint, assign the issue to yourself
• Before /issue lint, mark the issue's project status as In Progress
• If the issue is not in a project or the project has no Status field, attach it to the canonical delivery project first, then set Status
• If assignment, project attach, or status mutation fails, stop before implementation and report the blocker explicitly

The point is single ownership. One issue should map to one active autopilot lane.

Workflow

1. Find eligible issue —
   • Explicit issue: inspect assignees, project status, and open PRs before doing anything else
   • Auto-pick: choose the highest-priority open issue that is unassigned, not In Progress, and has no open PR or active autopilot lane
   • If there are no open issues, stop and report that the queue is empty
   • If open issues exist but none are eligible, stop and report that all open work is already claimed
   • Preferred lane check: run python3 scripts/issue_lane.py --repo <owner/name> --issue <N> when the repo provides it
   • Fallback: query open PRs with gh pr list --state open --json number,title,body,headRefName,url
2. Claim issue —
   • Assign the issue to yourself
   • Ensure the issue is attached to the canonical delivery project
   • Mark the linked project item Status as In Progress
   • Re-read the issue and confirm the claim stuck before proceeding
   • If the issue is already claimed by your lane, treat this as resume and continue
   • If the issue is claimed by another lane, stop instead of competing
3. Load context — Read project.md for product vision, domain glossary, quality bar
4. Readiness gate — Run /issue lint $1:
   • Score >= 70: proceed
   • Score 50-69: run /issue enrich $1 first, then re-lint
   • Score < 50: flag to user, attempt enrichment, re-lint
   • Never skip an issue because it scored low — YOU make it ready
5. Intent gate — Ensure issue has ## Product Spec and ### Intent Contract. If missing, invoke /shape --spec-only $1 and re-check before coding.
6. Design — Invoke /shape --design-only if no ## Technical Design section. If design contains a state machine or concurrent protocol, consider /formal-verify loop before proceeding to build.
7. Build (TDD Enforced) — Invoke /build and require RED→GREEN evidence per acceptance criterion:
   • RED: failing targeted tests before implementation
   • GREEN: same tests passing after implementation
   • If test harness is broken, stop and flag blocker (no implementation without explicit user bypass)
   • Delete compatibility scaffolding in greenfield/pre-user paths unless a real contract requires it
8. Visual QA — If diff touches frontend files (app/, components/, *.css), run /visual-qa --fix. Fix P0/P1 before proceeding.
9. Agentic QA — If diff touches prompts, model routing, tool schemas, or agent instructions, run /llm-infrastructure and inspect trace/eval coverage before shipping.
10. Refine — /pr-fix --refactor, update docs inline, then run simplification pass:
    • Mandatory when diff >200 LOC net: run /simplify — no exceptions
    • For smaller diffs: manual module-depth review + simplification edits using Ousterhout checks: shallow modules, information leakage, pass-throughs, and compatibility shims with no active contract
    • Optional accelerator: use an ousterhout persona/agent if the harness provides one
11. Dogfood QA — Run automated QA against local dev server (see Dogfood QA section below). Iterate until no P0/P1 issues remain. Do not open a PR until QA passes. 11a. Verify ACs — Invoke verify-ac against the linked issue's ## Acceptance Criteria.

• Honor explicit AC tags ([test], [command], [behavioral]) when present; otherwise let verify-ac choose the narrowest credible strategy from the diff and repo context
• Retry UNVERIFIED checks once (2 attempts total)
• If any AC remains UNVERIFIED after attempt 2: keep remediating the code, tests, or docs and rerun verify-ac; do not commit or ship while the gate is failing
• Escalate to the user only when further progress is genuinely blocked after reasonable remediation attempts
• PARTIAL may proceed only if no AC is UNVERIFIED, but it must be reported in the final handoff and PR body

12. Walkthrough — Run /pr-walkthrough and produce the mandatory walkthrough package for the branch. Every PR needs an artifact, even if the change is internal or architectural.
13. Commit — Create semantic commits for all remaining changes:
    • Categorize files: commit, gitignore, delete, consolidate
    • Group into logical commits: feat:, fix:, docs:, refactor:, test:, chore:
    • Subject: imperative, lowercase, no period, ~50 chars. Body: why not what.
    • Run quality gates (lint, typecheck, test) before pushing
    • git fetch origin && git push origin HEAD (rebase if behind)
    • Never force push. Never push to main without confirmation.
14. Ship — Open or update a live PR:
    • Stage and commit any uncommitted changes with semantic message
    • Read linked issue from branch name or recent commits
    • Re-run python3 scripts/issue_lane.py --repo <owner/name> --issue <N> immediately before opening the PR when available
    • Otherwise re-run the in-flight gate immediately before opening the PR
    • If an open PR already exists for the branch, use gh pr edit, not gh pr create
    • If another open PR already exists for the same issue, stop and surface the duplication instead of creating a second lane
    • Load ../pr/references/pr-body-template.md and follow it
    • The Walkthrough section must link the artifact and name the persistent verification that protects the demonstrated path
    • PR body must contain all sections:
      • Why This Matters: Problem, value added, why now, issue link. This is top-of-line.
      • Trade-offs / Risks: Costs accepted, remaining concerns, why the trade is worthwhile.
      • Intent Reference: Copy/paste issue intent contract summary + link to source issue section.
      • Changes: Concise list of what was done. Key files/functions.
      • Alternatives Considered: Do nothing, credible alternative(s), and why current approach won.
      • Acceptance Criteria: From linked issue. Checkboxes.
      • Manual QA: Step-by-step verification. Commands, expected output.
      • What Changed: Mermaid flow chart for base branch, Mermaid flow chart for this PR, and a third Mermaid architecture/state/sequence diagram, plus explanation of why the new shape is better.
      • Before / After: Text description mandatory. Screenshots for UI changes. Use <details> for heavy evidence.
      • Test Coverage: Specific test files/functions. Note gaps.
      • Merge Confidence: Confidence level, strongest evidence, residual risk.
    • Keep deep sections under <details> where useful, but do not hide the topline significance/trade-off story
    • Use --body-file for gh pr create, gh pr edit, and PR comments
    • gh pr create --assignee phrazzld --body-file <path>
    • Add context comment if notable decisions were made
    • Opening or updating the PR creates the review lane. It does not mean the PR is review-clean.
    • If your final push, gh pr ready, or PR edit triggers async reviewers, do not post any "PR Unblocked" or "ready for merge" signal unless /pr-fix has passed its live settlement gate on that PR
15. CI Gate — Wait for CI to complete on the PR.
    • Poll with gh pr checks <PR> --watch or gh run list --branch <branch> --limit 1
    • If any checks are red/failing: investigate root cause, fix, commit, push, then wait for CI again
    • Repeat until all checks pass
    • Do not proceed to review settlement while CI is red
16. Review Settlement — Read every single PR review and comment. Think critically about each. For every review point, determine one of three dispositions:
    • In scope: Fix it in the branch. Commit, push. Reply to the comment confirming the fix.
    • Valid but out of scope: Create a separate GitHub issue (or add to BACKLOG.md if the repo uses one). Reply to the comment linking the tracking item.
    • Invalid: Reply with clear reasoning for why the feedback doesn't apply.
    • Every review point gets a written response on the PR — none are silently ignored.
    • If fixes were pushed, return to step 15 (CI Gate) and re-verify before proceeding.
17. Polish — Once CI is green and every review comment is addressed:
    • Run /pr-polish
    • Run /simplify
    • If these generate changes, commit and push, then return to step 15 (CI Gate) to re-verify
18. Merge — Once CI is green, all reviews are settled, and polish is complete:
    • Squash merge via gh pr merge --squash
    • Never merge with failing checks
    • Never merge with unaddressed review comments
19. Retro (Optional) — Only capture implementation signals when the repo already uses issue-scoped retro notes and the signal is worth keeping.
    • Use one file per issue under .groom/retro/<issue>.md.
    • Never append to a shared .groom/retro.md; skip retro entirely instead of creating merge-hot churn for low-value notes.
    • If you do append, prefer the repo's issue-scoped retro command/path (for example /done append --issue ...) rather than inventing a new shared log format.

Dogfood QA

Run before every PR. No exceptions.

/dogfood is an agent skill, not a shell binary. Invoke it as /dogfood .... Do not run dogfood --help or declare it unavailable based on shell PATH. Use agent-browser / browser-use for focused manual repro and follow-up verification.

Setup

# Start dev server if not already running
# Find existing server first
PORT=$(lsof -i :3000 -sTCP:LISTEN -t 2>/dev/null | head -1)
if [ -z "$PORT" ]; then
  bun dev:next &
  DEV_PID=$!
  sleep 10  # wait for compilation
fi

# Confirm it's up
curl -s -o /dev/null -w "%{http_code}" http://localhost:3000/

If port 3000 is taken by another project, use bun dev:next -- --port 3001 and adjust the target URL accordingly.

Run

/dogfood http://localhost:3000

Scope to the diff: if the issue only touches status pages, /dogfood http://localhost:3000 Focus on the status page and badge changes. For full-feature work, no scope restriction.

Issue Severity Gate

After /dogfood completes, read the report:

• P0 or P1 issues → fix them, commit, re-run /dogfood on the affected area
• P2 issues → fix if quick (<15 min), otherwise document in PR as known and create a follow-up issue
• P3 issues / no issues → proceed to /pr

Never open a PR with unfixed P0 or P1 issues from the dogfood report.

Iteration Cap

If the same P0/P1 issue resurfaces after two fix attempts, stop, document the blocker, and flag to the user before proceeding. Don't loop indefinitely.

Teardown

# Kill the dev server if we started it
[ -n "$DEV_PID" ] && kill $DEV_PID 2>/dev/null || true

If the user's own dev server was already running (no $DEV_PID), leave it alone.

Parallel Refinement (Agent Teams)

After /build completes, parallelize the refinement phase:

| Teammate | Task | |----------|------| | Simplifier | Run code-simplifier agent, commit | | Depth reviewer | Run manual module-depth review, or ousterhout if available, commit | | Doc updater | Update docs (README, ADRs, API docs), commit |

Lead sequences commits after all teammates finish. Then dogfood QA, then /pr.

Use when: substantial feature with multiple refinement needs. Don't use when: small fix where sequential is fast enough.

If native batch dispatch is available in the harness (e.g. /batch), use it. Otherwise launch teammates sequentially with normal agent calls.

Stopping Conditions

Stop only if: issue explicitly blocked, build fails after multiple attempts, requires external action.

NOT stopping conditions: lacks description, seems big, unclear approach.

Output

Report: issue worked, spec status, design status, TDD evidence (RED/GREEN), dogfood QA summary (issues found/fixed), walkthrough artifact summary, commits made, PR URL, review comments settled (count + dispositions), and merge status.

Review Cadence

Agents accrete bloat when they keep extending stale mental models. Before each new sprint or major chunk:

• Re-read the touched modules fully
• Look for compatibility shims added only to preserve old structure
• Simplify before adding the next layer

Harness Accelerator (Claude Code)

When this skill runs in Claude Code:

1. In workflow step 8 (Refine), run /simplify after /pr-fix --refactor.
2. In Parallel Refinement, use /batch to dispatch teammate tasks in one call when possible.

If either command is unavailable, use the portable fallback path already defined in the base skill.