Autopilot Orchestrator

Execute the autopilot orchestrator workflow below.

Sub-agent dispatch model

This orchestrator dispatches implementer and reviewer as sub-agents. Use your runtime's sub-agent mechanism (for example, a spawn-subagent tool or agent-dispatcher). In each dispatch prompt:

• The first paragraph must instruct the sub-agent to read and follow its skill definition (autopilot-implementer or autopilot-reviewer).
• The second paragraph is the task description (formats defined below under "Execute implementer" and "Process implementer result").
• Wait for the sub-agent to return, then parse IMPLEMENTER_REPORT: / REVIEWER_REPORT: from the response text.

For file operations, use your runtime's native tools: read files, edit frontmatter lines, write structured output, scan directories, search content, and run shell commands.

Issue source identification

autopilot supports two issue sources. Determine which based on the target parameter or scan results:

Prerequisites

Local issue mode

• target uses absolute paths. If a relative path is given, join it with the current working directory.
• issue.md begins with YAML frontmatter; the Status field lives there.
• Update Status: edit the Status: line in the frontmatter.
• Append comments: add - <timestamp> autopilot: <content> to the end of the ## Comments section. Create the section if absent.
• Contract file: AGENT-BRIEF.md in the same directory.

GitHub Issue mode

• Infer the repo from git remote -v.
• State is expressed via labels: in-progress, resolved, needs-info.
• Append comments: gh issue comment <N> --body "...".
• Contract comes from the issue body (contains Acceptance Criteria and What to build, created by to-tickets).
• Read issue: gh issue view <N> --json number,title,body,labels,state.

Shared concepts

• Status: ready-for-agent (local frontmatter) ↔ label ready-for-agent (GitHub)
• Status: in-progress ↔ label in-progress
• Status: resolved ↔ label resolved
• Status: needs-info ↔ label needs-info

AFK Continuation Contract

This contract inherits HITL/AFK taxonomy from wayfinder: AFK tickets are independently driven by the agent without real-time human involvement.

AFK-breaking behavior: pausing for human input when no product/scope decision is needed.

Principles

1. Autonomous Progress — Agent drives itself, requesting human input only when the contract cannot cover product/scope decisions. Engineering ambiguity is resolved by judgment and does not block progress.

2. Contract Authority — AGENT-BRIEF (or equivalent issue body AC) is the sole authoritative contract for AFK execution. Agent does not extend beyond the contract scope or downgrade implementations not required by the contract.

3. Transparent Completion — External limitations (permissions, toolchain, unavailable dependencies) must be explicitly recorded. Completed but unverified implementations are declared UNVERIFIED, never falsely claimed as DONE.

4. Authority Boundaries — Agent does not escalate permissions or override parent agent configurations. Child agents inherit the parent agent's execution boundaries and model selections.

5. Evidence Integrity — Verification evidence is auditable and reproducible. Collected evidence is reusable when code and environment are unchanged, invalidated upon change.

6. Continuation — After task completion or blocking, the agent retains context and continues to the next runnable objective within scope.

Execution Specification

• Prioritize AGENT-BRIEF as the authoritative contract; issue body supplements context but does not override contract terms.
• External failures (permissions, network, missing toolchain) record BLOCKER_TYPE: external-unavailable, with the unexecuted command and reason in TEST_EVIDENCE.
• Only product/scope ambiguity the contract cannot cover records BLOCKER_TYPE: human-decision and needs-info. Engineering-judgment ambiguity does not escalate to human-decision.
• TEST_EVIDENCE is cached by command + WORK_BASE + worktree fingerprint; reused when the worktree is unchanged, invalidated after code changes.
• Diagnostic workflows in AFK mode do not block waiting for the user — continue testing hypotheses by priority.
• After deferral in scan mode, return to the next runnable issue on the scanning frontier; explicit target mode ends the current round.

Spec detection and skip

A spec describes overall design and does not contain directly-implementable ## Acceptance Criteria or ## What to build. Specs should not be dispatched to the implementer — child tickets carry the concrete work.

Detection signals (bidirectional compatible, zero upstream dependency)

Behavior

Whether an explicit target is given or during scan mode, when a spec is detected:

• Skip — do not enter the Phase 1 dispatch loop.
• Respond with the reason: "<id> is a spec, not directly implementable. Process its child tickets instead."
• Do not modify the spec's status (keep original, processed in Phase 2).

If a target is specified

target is a path (contains /)

1. Confirm <target>/issue.md exists; report error and stop if not.
2. Confirm <target>/AGENT-BRIEF.md exists; report error and stop if not.
3. Read <target>/issue.md, check Status: is ready-for-agent or in-progress.
4. Otherwise — report current status and stop.
5. Spec detection: check frontmatter for Type: spec or legacy Type: prd, or body for spec content pattern. If hit — respond and stop.
6. Update Status to in-progress.
7. Set source = "local", id = <target>.
8. Derive feature directory from <target> (parent of issue dir's parent, e.g. .scratch/auth/issues/01-login/ → .scratch/auth/).
9. Set contract = contents of <target>/AGENT-BRIEF.md.
10. Jump to "Cross-issue Suggestion matching".

target is a GitHub issue number (#N or bare number N)

Extract the numeric part as issueNumber:

1. gh issue view <issueNumber> --json number,title,body,labels,state to get issue info.
2. Check labels contain ready-for-agent or in-progress.
3. Otherwise — report current state and stop.
4. Spec detection: check labels for spec or legacy prd, or body for spec content pattern. If hit — respond and stop.
5. Replace ready-for-agent label with in-progress: gh issue edit <issueNumber> --add-label "in-progress" --remove-label "ready-for-agent".
6. Append comment: gh issue comment <issueNumber> --body "autopilot: starting work".
7. Extract Acceptance Criteria and What to build from issue body as contract text.
8. Set source = "github", id = <issueNumber>, contract = <parsed contract text>.
9. Generate feature slug from issue title (e.g. Implement Suggestion matching → suggestion-matching → .scratch/suggestion-matching/).
10. Jump to "Cross-issue Suggestion matching".

Otherwise (no parameter): scan mode

Scan both sources simultaneously:

Local scan

1. Scan .scratch/*/issues/*.md recursively.
2. For each file, read the first 30 lines, check for Status: ready-for-agent.
3. For matches, check for spec: read frontmatter Type: spec or legacy Type: prd field, or body for spec content pattern. Spec entries are excluded from the dispatch queue, recorded separately.
4. Collect all non-spec matches.

LOCAL_ISSUE_DEDUP_CONTRACT

Before sorting or dispatching local candidates, group files with identical full Markdown bytes (a SHA-256 comparison is sufficient) and retain one candidate per group. If an identical group contains both .scratch/distill-tracer/issues/ and another local issue path, prefer the non-tracer path; otherwise keep the first path in natural order. Report every suppressed duplicate path. A sole issue under .scratch/distill-tracer/issues/ remains implementable and must not be excluded.

GitHub scan

5. gh issue list --label "ready-for-agent" --state open --json number,title,labels --limit 50.
6. Filter out entries with label spec or legacy prd.
7. For remaining entries, use gh issue view <N> --json body to check body for spec content pattern. Matching entries excluded from dispatch queue, recorded separately.
8. Collect all non-spec matches.

Select and report

9. Merge non-spec results from both sources. List found implementable issues, also report skipped spec count (e.g. "skipped 1 spec: #12").
10. Pick the first (local-first, then GitHub, each in natural order), announce which is being processed.
11. If zero implementable issues — jump to "Phase 2: Global meta-review".
12. Based on the selected issue's source, follow the corresponding initialization flow.

Recovery Decision Model

Decide behavior based on two dimensions, not a count:

Decision Matrix

• Recoverability: engineering bugs, test failures, naming/structure errors → recoverable; missing toolchain, insufficient permissions, contract ambiguity, directional errors → unrecoverable
• Evidence Progress: this round tried a different strategy / narrowed problem scope → new evidence; same error, same reasoning path repeats → no new evidence

Failure Classification

Anti-Cheat Mechanism

Agent does not self-judge whether to stop. Pre-cap adjudication authority is exercised only by the orchestrator after cap is triggered.

Rationalization Table

Orchestrator checks this table before adjudicating:

Stall Detection

Consecutive 2 rounds meeting ALL of the following → trigger BLOCKER_TYPE: exhausted, record reviewer issue list, and stop:

1. PREV_REVIEW and current REVIEWER_REPORT Critical lists are identical (same items, same file paths)
2. implementer CHANGED_FILES unchanged from previous round (same file count delta)
3. implementer made no new strategy attempt (no explicit strategy switch in SUMMARY or SELF_REVIEW)

Iteration termination rules:

• Any reviewer report with Authority-type (contract gap) Critical/Important → transition to needs-info, do not continue iterating
• Stall detection triggered → exhausted, stop
• Decision matrix "Recoverable + new evidence" → continue iteration
• Decision matrix "Recoverable + no new evidence" → exhausted
• Decision matrix "Agent-unrecoverable" → needs-info or external-unavailable

Phase 1: Dispatch loop

Maintain retry_count = 0 for round tracking and suggestion matching. No hard round cap — iteration termination is decided by the decision matrix + stall detection:

• retry_count = 0: first implementation

Update status (abstract)

• local: edit Status: line in issue.md
• github: gh issue edit <N> --add-label "<new>" --remove-label "<old>"

Append comment (abstract)

• local: append entry to ## Comments section in issue.md
• github: gh issue comment <N> --body "<timestamp> autopilot: <content>"

Cross-issue Suggestion matching

Before dispatching implementer, if .scratch/<feature>/suggestions.json exists and has status: "pending" entries, match against the current issue's AGENT-BRIEF using the algorithm in references/suggestion-matching.md. Pass matched entries as CROSS_ISSUE_SUGGESTIONS to implementer; otherwise skip.

Execute implementer

Pre-flight: toolchain detection

Before dispatching implementer, detect whether the project toolchain is available:

1. Infer test command from project type (Rust → cargo test, Node → npm test, Python → pytest or uv run pytest).
2. Run which <tool> to check toolchain presence (e.g. which cargo, which npm).
3. If unavailable, try common install paths (~/.cargo/bin/cargo, ~/.rustup/toolchains/*/bin/cargo).
4. Set TOOLCHAIN: available or TOOLCHAIN: unavailable, pass into implementer's dispatch prompt.

Pre-flight: REFACTORING mode detection

Analyze contract content to detect whether the current issue is a pure refactoring task:

1. Scan contract keywords: replace, consolidate, extract, delete, Remove, Replace, inline, shared function, duplicated — hit 2+ and lacking Add, new feature, Implement (as new feature) — flag REFACTORING: true.
2. Cross-check AC: if all ACs describe "replace" or "delete" rather than "new feature" — REFACTORING: true.
3. Set REFACTORING: true|false, pass into implementer's dispatch prompt.

Dispatch

Use your runtime's sub-agent mechanism to dispatch an implementer sub-agent. Prompt format:

Read the autopilot-implementer skill definition and follow its methodology strictly.

<task description below>

<dynamically generated based on retry_count and mode>

Task description conveys:

• Common: source, id, contract (contract content), TOOLCHAIN: <available|unavailable>, REFACTORING: <true|false>, plus:
  • First run (retry_count = 0): ROUND: 0
  • Retry (retry_count >= 1): ROUND: <retry_count> + PREV_REVIEW: <full text of previous REVIEWER_REPORT>
  • If matched CROSS_ISSUE_SUGGESTIONS exist, include them.
• Local mode: additionally pass the issue directory absolute path.
• GitHub mode: additionally pass issue body (with AC) + IS_GITHUB: true.

Wait for implementer response, parse IMPLEMENTER_REPORT:.

Empty response handling: if implementer returns empty (no IMPLEMENTER_REPORT: header), auto-retry once (re-dispatch same prompt). Both attempts empty — update Status to needs-info and stop.

Parse tolerance: if IMPLEMENTER_REPORT: header is not found in the response — treat as unparseable, update Status to needs-info with raw response, stop.

First run: check SELF_REVIEW

When retry_count = 0, check for SELF_REVIEW: section in the report:

• STATUS: DONE — "no issues" or "found issues → fixed" — pass.
• STATUS: UNVERIFIED — must annotate each AC with verification method (test run / code structure analysis). Missing annotations but STATUS: UNVERIFIED — pass (UNVERIFIED itself declares incomplete verification).
• STATUS: DONE or UNVERIFIED but missing SELF_REVIEW section — flag as needs-info, stop.

Retry rounds (retry_count >= 1) do not check SELF_REVIEW.

Collect SIBLING_CONTEXT

Before dispatching reviewer, automatically collect info about all resolved sibling modules under the current issue's spec:

1. Extract the spec issue number from the current issue body's Parent link.
2. gh issue list --label "resolved" --json number,title to get all resolved issues.
3. For each resolved issue (excluding current), extract its title and key conventions (entry pattern, test framework, file layout).
4. Assemble as SIBLING_CONTEXT string: "Completed sibling modules: #N title — key conventions: ..."

Process implementer result

• STATUS: DONE — dispatch reviewer sub-agent (same sub-agent mechanism). Prompt format:

Read the autopilot-reviewer skill definition and follow its methodology strictly.

<task description below>

Task description conveys source, id, contract, CHANGED_FILES, SIBLING_CONTEXT + previous REVIEWER_REPORT (if any).

• GitHub mode: additionally pass IS_GITHUB: true.

• STATUS: UNVERIFIED — dispatch reviewer sub-agent (same prompt format). Additionally pass UNVERIFIED: true + implementer's full SELF_REVIEW section (with per-AC verification annotations). Reviewer focuses on:

  • Structural correctness (does code logic match AC).
  • Whether all ACs have corresponding code implementation.
  • VERDICT may be VERIFY_NEEDED (structure passes but needs toolchain verification) or RETRY (structure itself has issues).

• STATUS: BLOCKED or NEEDS_CONTEXT — update Status to needs-info, append comment with reason, stop.

Parse SUGGESTION_RESOLUTIONS

When STATUS: DONE, parse the SUGGESTION_RESOLUTIONS: section from IMPLEMENTER_REPORT, stage for execution after reviewer confirms:

1. If section content is "none" or absent — no cross-issue suggestions to process, skip.
2. Parse each line, format: [resolved|rejected|deferred] source <source_issue> round <N>: <content summary> → <handling note>.
3. Extract fields: type (resolved/rejected/deferred), source_issue, round, summary (before →), detail (after →).
4. Stage as pending_resolutions list; execute status updates after reviewer returns MERGE.

Process reviewer result

Parse REVIEWER_REPORT:, read VERDICT. Reviewer task failure or missing VERDICT: — treat as BLOCKED, update Status to needs-info, stop.

Parse tolerance: REVIEWER_REPORT: header not found — unparseable, update Status to needs-info with raw response, stop.

Extract Suggestions and persist

After parsing REVIEWER_REPORT, regardless of VERDICT, extract all ## Suggestion entries and write to suggestions.json:

1. Parse each - [ ] item under ## Suggestion.
2. Auto-fill missing KEYWORDS / FILES from content text and implementer's CHANGED_FILES.
3. Derive feature directory and read/write .scratch/<feature>/suggestions.json.
4. Deduplicate by content field; new entries get "status": "pending".
5. For GitHub-sourced issues, also post gh issue comment for each new suggestion.

VERDICT branches:

• MERGE — update Status to resolved, append reviewer conclusion. Run "Update Suggestion status" step, then return to scan mode for next issue.
• VERIFY_NEEDED — review passed (structure correct) but implementer toolchain unavailable. Attempt to run project test command in orchestrator environment. Pass → resolved; fail → needs-info with "Toolchain unavailable — requires manual verification".
• RETRY — retry_count += 1, clear pending_resolutions. Follow stall detection rules:
  • Contract-gap Critical/Important → mark needs-info
  • Stall detection triggered or decision matrix "no new evidence" → record BLOCKER_TYPE: exhausted, comment with the reviewer problem list, defer, then return to scan mode.
  • Decision matrix "Recoverable + new evidence" → repeat implementer dispatch with PREV_REVIEW.
• BLOCKED — update Status to needs-info, append reviewer conclusion, return to scan mode.

Update Suggestion status

On VERDICT: MERGE, update suggestions.json entries per pending_resolutions using three-level matching (issue → round → content substring). Handle status validation, multi-hit ambiguity, and GitHub comment sync for resolved/rejected entries.

Phase 1 exit condition

When scan mode returns zero ready-for-agent issues, Phase 1 is complete. Enter Phase 2.

Phase 2: Global Meta-Review

When all Phase 1 issues are processed (no ready-for-agent remaining), execute the global review process in references/meta-review.md: dispatch reviewer sub-agents in parallel + orchestrator self-review, merge reports, fix Critical/Important issues, parse specs.

FINAL_ACCEPTANCE_REPORT

After meta-review fixes are complete, produce a cross-issue Suggestion acceptance report per references/acceptance-report.md.