annotations/.cursor/skills/autodev/state.md

Autodev State Management

State File: _docs/_autodev_state.md

The autodev persists its position to _docs/_autodev_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

Saved at: _docs/_autodev_state.md (workspace-relative, one file per project). Created on the first /autodev invocation; updated in place on every state transition; never deleted.

# Autodev State

## Current Step
flow: [greenfield | existing-code | meta-repo]
step: [1-11 for greenfield, 1-17 for existing-code, 1-6 for meta-repo, or "done"]
name: [step name from the active flow's Step Reference Table]
status: [not_started / in_progress / completed / skipped / failed]
sub_step:
  phase: [integer — sub-skill internal phase/step number, or 0 if not started]
  name: [kebab-case short identifier from the sub-skill, or "awaiting-invocation"]
  detail: [optional free-text note, may be empty]
retry_count: [0-3 — consecutive auto-retry attempts, reset to 0 on success]
cycle: [1-N — feature cycle counter for existing-code flow; increments on each "Re-Entry After Completion" loop; always 1 for greenfield and meta-repo]

The sub_step field is structured. Every sub-skill must save both phase (integer) and name (kebab-case token matching the skill's documented phase names). detail is optional human-readable context. On re-entry the orchestrator parses phase and name to resume; if parsing fails, fall back to folder scan and log the parse failure.

Sub-Skill Phase Persistence — Rules (not a registry)

Each sub-skill is authoritative for its own phase list. Phase names and numbers live inside the sub-skill's own SKILL.md (and any steps/ / phases/ files). The orchestrator does not maintain a central phase table — it reads whatever phase / name the sub-skill last wrote.

Every sub-skill MUST follow these rules when persisting sub_step:

1. phase — a strictly monotonic integer per invocation, starting at 0 (awaiting-invocation) and incrementing by 1 at each internal save point. No fractional values are ever persisted. If the skill's own docs use half-step numbering (e.g., "Phase 4.5", decompose's "Step 1.5"), the persisted integer is simply the next integer, and all subsequent phases shift up by one in that skill's own file.
2. name — a kebab-case short identifier unique within that sub-skill. Use the phase's heading or step title in kebab-case (e.g., component-decomposition, auto-fix-gate, cross-task-consistency). Different modes of the same skill may reuse a phase integer with distinct name values (e.g., decompose phase 1 is bootstrap-structure in default mode, test-infrastructure-bootstrap in tests-only mode).
3. detail — optional free-text note (batch index, mode flag, retry hint); may be empty.
4. Reserved name — name: awaiting-invocation with phase: 0 is the universal "skill was chained but has not started" marker. Every sub-skill implicitly supports it; no sub-skill should reuse the token for anything else.

On re-entry, the orchestrator parses the structured field and resumes at (phase, name). If parsing fails, it falls back to folder scan and logs the parse error — it does NOT guess a phase.

The cycle counter is used by existing-code flow Step 10 (Implement) detection and by implementation report naming (implementation_report_{feature_slug}_cycle{N}.md). It starts at 1 when a project enters existing-code flow (either by routing from greenfield's Done branch, or by first invocation on an existing codebase). It increments on each completed Retrospective → New Task loop.

Examples

flow: greenfield
step: 3
name: Plan
status: in_progress
sub_step:
  phase: 4
  name: architecture-review-risk-assessment
  detail: ""
retry_count: 0
cycle: 1

flow: existing-code
step: 3
name: Test Spec
status: failed
sub_step:
  phase: 1
  name: test-case-generation
  detail: "variant 1b"
retry_count: 3
cycle: 1

flow: meta-repo
step: 2
name: Config Review
status: in_progress
sub_step:
  phase: 0
  name: awaiting-human-review
  detail: "awaiting review of _docs/_repo-config.yaml"
retry_count: 0
cycle: 1

flow: existing-code
step: 10
name: Implement
status: in_progress
sub_step:
  phase: 7
  name: batch-loop
  detail: "batch 2 of ~4"
retry_count: 0
cycle: 3

State File Rules

1. Create on the first autodev 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 autodev's sub_step field should reflect the skill's internal progress. On re-entry, cross-check the skill's state file against the autodev's sub_step for consistency.

State Detection

Read _docs/_autodev_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 the workspace and _docs/ to determine the current workflow position. The detection rules are defined in each flow file (flows/greenfield.md, flows/existing-code.md, flows/meta-repo.md). Resolution order:

1. Apply the Flow Resolution rules in SKILL.md to pick the flow first (meta-repo detection takes priority over greenfield/existing-code).
2. Within the selected flow, check its detection rules in order — first match wins.

Re-Entry Protocol

When the user invokes /autodev and work already exists:

1. Read _docs/_autodev_state.md
2. Cross-check against _docs/ folder structure
3. Present Status Summary (render using the banner template in protocols.md → "Banner Template", filled in with the active flow's "Status Summary — Step List" fragment)
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

A session boundary is a transition that explicitly breaks auto-chain. Which transitions are boundaries is declared in each flow file's Auto-Chain Rules table — rows marked **Session boundary**. The details live with the steps they apply to; this section defines only the shared mechanism.

Invariant: a flow row without the Session boundary marker auto-chains unconditionally. Missing marker = missing boundary.

Orchestrator mechanism at a boundary

1. Update the state file: mark the current step completed; set the next step with status: not_started; reset sub_step: {phase: 0, name: awaiting-invocation, detail: ""}; keep retry_count: 0.
2. Present a brief summary of what just finished (tasks produced, batches expected, etc., as relevant to the boundary).
3. Present the shared Choose block (template below) — or a flow-specific override if the flow file supplies one.
4. End the session — do not start the next skill in the same conversation.

Shared Choose template

══════════════════════════════════════
 DECISION REQUIRED: <what just completed> — start <next phase>?
══════════════════════════════════════
 A) Start a new conversation for <next phase> (recommended for context freshness)
 B) Continue in this conversation (NOT recommended — context may degrade)
    Warning: if context fills mid-<next phase>, state will be saved and you will
    still be asked to resume in a new conversation — option B only delays that.
══════════════════════════════════════
 Recommendation: A — <next phase> is long; fresh context helps
══════════════════════════════════════

Individual boundaries MAY override this template with a flow-specific Choose block when the pause has different semantics (e.g., meta-repo.md Step 2 Config Review pauses for human review of a config flag, not for context freshness). The flow file is authoritative for any such override.