detections/.cursor/skills/autopilot/state.md

Autopilot State Management

State File: _docs/_autopilot_state.md

The autopilot persists its position to _docs/_autopilot_state.md. This is a lightweight pointer — only the current step. All history lives in _docs/ artifacts and git log. Folder scanning is the fallback when the state file doesn't exist.

Template

# Autopilot State

## Current Step
flow: [greenfield | existing-code]
step: [1-10 for greenfield, 1-13 for existing-code, or "done"]
name: [step name from the active flow's Step Reference Table]
status: [not_started / in_progress / completed / skipped / failed]
sub_step: [0, or sub-skill internal step number + name if interrupted mid-step]
retry_count: [0-3 — consecutive auto-retry attempts, reset to 0 on success]

Examples

flow: greenfield
step: 3
name: Plan
status: in_progress
sub_step: 4 — Architecture Review & Risk Assessment
retry_count: 0

flow: existing-code
step: 2
name: Test Spec
status: failed
sub_step: 1b — Test Case Generation
retry_count: 3

State File Rules

1. Create on the first autopilot invocation (after state detection determines Step 1)
2. Update after every change — this includes: batch completion, sub-step progress, step completion, session boundary, failed retry, or any meaningful state transition. The state file must always reflect the current reality.
3. Read as the first action on every invocation — before folder scanning
4. Cross-check: verify against actual _docs/ folder contents. If they disagree, trust the folder structure and update the state file
5. Never delete the state file
6. Retry tracking: increment retry_count on each failed auto-retry; reset to 0 on success. If retry_count reaches 3, set status: failed
7. Failed state on re-entry: if status: failed with retry_count: 3, do NOT auto-retry — present the issue to the user first
8. Skill-internal state: when the active skill maintains its own state file (e.g., document skill's _docs/02_document/state.json), the autopilot's sub_step field should reflect the skill's internal progress. On re-entry, cross-check the skill's state file against the autopilot's sub_step for consistency.

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 (Step 1 detection), then greenfield flow rules. First match wins.

Re-Entry Protocol

When the user invokes /autopilot and work already exists:

1. Read _docs/_autopilot_state.md
2. Cross-check against _docs/ folder structure
3. Present Status Summary (use the active flow's Status Summary Template)
4. If the detected step has a sub-skill with built-in resumability, the sub-skill handles mid-step recovery
5. Continue execution from detected state

Session Boundaries

After any decompose/planning step completes, do not auto-chain to implement. Instead:

1. Update state file: mark the step as completed, set current step to the next implement step with status not_started
   • Existing-code flow: After Step 4 (Decompose Tests) → set current step to 5 (Implement Tests)
   • Existing-code flow: After Step 8 (New Task) → set current step to 9 (Implement)
   • Greenfield flow: After Step 5 (Decompose) → set current step to 6 (Implement)
2. Present a summary: number of tasks, estimated batches, total complexity points
3. 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.