Autopilot State Management

State File: `_docs/_autopilot_state.md`

The autopilot persists its state to _docs/_autopilot_state.md. This file is the primary source of truth for re-entry. Folder scanning is the fallback when the state file doesn't exist.

Format

# Autopilot State

## Current Step
step: [0-6 or "2b" / "2c" / "2d" / "2e" / "2f" / "2g" / "2h" / "2hb" / "2i" or "5b" or "done"]
name: [Problem / Research / Plan / Blackbox Test Spec / Decompose Tests / Implement Tests / Refactor / New Task / Implement / Run Tests / Security Audit / Deploy / Decompose / Done]
status: [not_started / in_progress / completed / skipped]
sub_step: [optional — sub-skill internal step number + name if interrupted mid-step]

## Step ↔ SubStep Reference
(include the step reference table from the active flow file)

When updating `Current Step`, always write it as:
  step: N          ← autopilot step (0–6 or 2b/2c/2d/2e/2f/2g/2h/2hb/2i or 5b)
  sub_step: M      ← sub-skill's own internal step/phase number + name
Example:
  step: 2
  name: Plan
  status: in_progress
  sub_step: 4 — Architecture Review & Risk Assessment

## Completed Steps

| Step | Name | Completed | Key Outcome |
|------|------|-----------|-------------|
| 0 | Problem | [date] | [one-line summary] |
| 1 | Research | [date] | [N drafts, final approach summary] |
| ... | ... | ... | ... |

## Key Decisions
- [decision 1: e.g. "Tech stack: Python + Rust for perf-critical, Postgres DB"]
- [decision N]

## Last Session
date: [date]
ended_at: Step [N] [Name] — SubStep [M] [sub-step name]
reason: [completed step / session boundary / user paused / context limit]
notes: [any context for next session]

## Blockers
- [blocker 1, if any]
- [none]

State File Rules

Create the state file on the very first autopilot invocation (after state detection determines Step 0)
Update the state file after every step completion, every session boundary, and every BLOCKING gate confirmation
Read the state file as the first action on every invocation — before folder scanning
Cross-check: after reading the state file, verify against actual _docs/ folder contents. If they disagree (e.g., state file says Step 2 but _docs/02_document/architecture.md already exists), trust the folder structure and update the state file to match
Never delete the state file. It accumulates history across the entire project lifecycle

State Detection

Read _docs/_autopilot_state.md first. If it exists and is consistent with the folder structure, use the Current Step from the state file. If the state file doesn't exist or is inconsistent, fall back to folder scanning.

Folder Scan Rules (fallback)

Scan _docs/ to determine the current workflow position. The detection rules are defined in each flow file (flows/greenfield.md and flows/existing-code.md). Check the existing-code flow first (Pre-Step detection), then greenfield flow rules. First match wins.

Re-Entry Protocol

When the user invokes /autopilot and work already exists:

Read _docs/_autopilot_state.md
Cross-check against _docs/ folder structure
Present Status Summary with context from state file (key decisions, last session, blockers)
If the detected step has a sub-skill with built-in resumability (plan, decompose, implement, deploy all do), the sub-skill handles mid-step recovery
Continue execution from detected state

Session Boundaries

After any decompose/planning step completes (Step 2c, Step 2f, or Step 3), do not auto-chain to implement. Instead:

Update state file: mark the step as completed, set current step to the next implement step with status not_started
- After Step 2c (Decompose Tests) → set current step to 2d (Implement Tests)
- After Step 2f (New Task) → set current step to 2g (Implement)
- After Step 3 (Decompose) → set current step to 4 (Implement)
Write Last Session section: reason: session boundary, notes: Decompose complete, implementation ready
Present a summary: number of tasks, estimated batches, total complexity points
Use Choose format:

══════════════════════════════════════
 DECISION REQUIRED: Decompose complete — start implementation?
══════════════════════════════════════
 A) Start a new conversation for implementation (recommended for context freshness)
 B) Continue implementation in this conversation
══════════════════════════════════════
 Recommendation: A — implementation is the longest phase, fresh context helps
══════════════════════════════════════

These are the only hard session boundaries. All other transitions auto-chain.

4.9 KiB Raw Blame History Unescape Escape