Sync .cursor from detections

.cursor/skills/autopilot/state.md

@@ -0,0 +1,92 @@
+# 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.