# 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

```markdown
# 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.