Autodev Orchestrator

Auto-chaining execution engine that drives the full BUILD → SHIP workflow. Detects project state from _docs/, resumes from where work stopped, and flows through skills automatically. The user invokes /autodev once — the engine handles sequencing, transitions, and re-entry.

File Index

File	Purpose
`flows/greenfield.md`	Detection rules, step table, and auto-chain rules for new projects
`flows/existing-code.md`	Detection rules, step table, and auto-chain rules for existing codebases
`flows/meta-repo.md`	Detection rules, step table, and auto-chain rules for meta-repositories (submodule aggregators, workspace monorepos)
`state.md`	State file format, rules, re-entry protocol, session boundaries
`protocols.md`	User interaction, tracker auth, choice format, error handling, status summary

On every invocation: read state.md, protocols.md, and the active flow file before executing any logic. You don't need to read flow files for flows you're not in.

Core Principles

Auto-chain: when a skill completes, immediately start the next one — no pause between skills
Only pause at decision points: BLOCKING gates inside sub-skills are the natural pause points; do not add artificial stops between steps
State from disk: current step is persisted to _docs/_autodev_state.md and cross-checked against _docs/ folder structure
Re-entry: on every invocation, read the state file and cross-check against _docs/ folders before continuing
Delegate, don't duplicate: read and execute each sub-skill's SKILL.md; never inline their logic here
Sound on pause: follow .cursor/rules/human-attention-sound.mdc — play a notification sound before every pause that requires human input (AskQuestion tool preferred for structured choices; fall back to plain text if unavailable)
Minimize interruptions: only ask the user when the decision genuinely cannot be resolved automatically
Single project per workspace: all _docs/ paths are relative to workspace root; for multi-component systems, each component needs its own Cursor workspace. Exception: a meta-repo workspace (git-submodule aggregator or monorepo workspace) uses the meta-repo flow and maintains cross-cutting artifacts via monorepo-* skills rather than per-component BUILD-SHIP flows.

Flow Resolution

Determine which flow to use (check in order — first match wins):

If _docs/_autodev_state.md exists → read the flow field and use that flow. (When a greenfield project completes its final cycle, the Done step rewrites flow: existing-code in-band so the next invocation enters the feature-cycle loop — see greenfield "Done".)
If the workspace is a meta-repo → meta-repo flow. Detected by: presence of .gitmodules with ≥2 submodules, OR package.json with workspaces field, OR pnpm-workspace.yaml, OR Cargo.toml with [workspace] section, OR go.work, OR an ad-hoc structure with multiple top-level component folders each containing their own project manifests. Optional tiebreaker: the workspace has little or no source code of its own at the root (just registry + orchestration files).
If workspace has no source code files → greenfield flow
If workspace has source code files and _docs/ does not exist → existing-code flow
If workspace has source code files and _docs/ exists → existing-code flow

After selecting the flow, apply its detection rules (first match wins) to determine the current step.

Note: the meta-repo flow uses a different artifact layout — its source of truth is _docs/_repo-config.yaml, not _docs/NN_*/ folders. Other detection rules assume the BUILD-SHIP artifact layout; they don't apply to meta-repos.

Execution Loop

Every invocation has three phases: Bootstrap (runs once), Resolve (runs once), Execute Loop (runs per step). Exit conditions are explicit.

### Bootstrap (once per invocation)
B1. Process leftovers       — delegate to `.cursor/rules/tracker.mdc` → Leftovers Mechanism
                               (authoritative spec: replay rules, escalation, blocker handling).
B2. Surface Recent Lessons  — print top 3 entries from `_docs/LESSONS.md` if present; skip silently otherwise.
B3. Read state              — `_docs/_autodev_state.md` (if it exists).
B4. Read File Index         — `state.md`, `protocols.md`, and the active flow file.

### Resolve (once per invocation, after Bootstrap)
R1. Reconcile state         — verify state file against `_docs/` contents; on disagreement, trust the folders
                               and update the state file (rules: `state.md` → "State File Rules" #4).
                               After this step, `state.step` / `state.status` are authoritative.
R2. Resolve flow            — see §Flow Resolution above.
R3. Resolve current step    — when a state file exists, `state.step` drives detection.
                               When no state file exists, walk the active flow's detection rules in order;
                               first folder-probe match wins.
R4. Present Status Summary  — banner template in `protocols.md` + step-list fragment from the active flow file.

### Execute Loop (per step)
loop:
  E1. Delegate to the current skill (see §Skill Delegation below).
  E2. On FAILED
        → apply Failure Handling (`protocols.md`): increment retry_count, auto-retry up to 3.
        → if retry_count reaches 3 → set status: failed → EXIT (escalate on next invocation).
  E3. On success
        → reset retry_count, update state file (rules: `state.md`).
  E4. Re-detect next step from the active flow's detection rules.
  E5. If the transition is marked as a session boundary in the flow's Auto-Chain Rules
        → update state, present boundary Choose block, suggest new conversation → EXIT.
  E6. If all steps done
        → update state, report completion → EXIT.
  E7. Else
        → continue loop (go to E1 with the next skill).

Skill Delegation

For each step, the delegation pattern is:

Update state file: set step to the autodev step number, status to in_progress, set sub_step to the sub-skill's current internal phase using the structured {phase, name, detail} schema (see state.md), reset retry_count: 0
Announce: "Starting [Skill Name]..."
Read the skill file: .cursor/skills/[name]/SKILL.md
Execute the skill's workflow exactly as written, including all BLOCKING gates, self-verification checklists, save actions, and escalation rules. Update sub_step.phase, sub_step.name, and optional sub_step.detail in state each time the sub-skill advances to a new internal phase.
If the skill fails: follow Failure Handling in protocols.md — increment retry_count, auto-retry up to 3 times, then escalate.
When complete (success): reset retry_count: 0, update state file to the next step with status: not_started and sub_step: {phase: 0, name: awaiting-invocation, detail: ""}, return to auto-chain rules (from active flow file)

sub_step read fallback: when reading sub_step, parse the structured form. If parsing fails (legacy free-text value) OR the named phase is not recognized, log a warning and fall back to a folder scan of the sub-skill's artifact directory to infer progress. Do not silently treat a malformed sub_step as phase 0 — that would cause a sub-skill to restart from scratch after each resume.

Do NOT modify, skip, or abbreviate any part of the sub-skill's workflow. The autodev is a sequencer, not an optimizer.

State File

The state file (_docs/_autodev_state.md) is a minimal pointer — only the current step. See state.md for the authoritative template, field semantics, update rules, and worked examples. Do not restate the schema here — state.md is the single source of truth.

Trigger Conditions

This skill activates when the user wants to:

Start a new project from scratch
Continue an in-progress project
Check project status
Let the AI guide them through the full workflow

Keywords: "autodev", "auto", "start", "continue", "what's next", "where am I", "project status"

Invocation model: this skill is explicitly user-invoked only (disable-model-invocation: true in the front matter). The keywords above aid skill discovery and tooling (other skills / agents can reason about when /autodev is appropriate), but the model never auto-fires this skill from a keyword match. The user always types /autodev.

Differentiation:

User wants only research → use /research directly
User wants only planning → use /plan directly
User wants to document an existing codebase → use /document directly
User wants the full guided workflow → use /autodev

Flow Reference

See flows/greenfield.md, flows/existing-code.md, and flows/meta-repo.md for step tables, detection rules, auto-chain rules, and each flow's Status Summary step-list fragment. The banner that wraps those fragments lives in protocols.md → "Banner Template (authoritative)".

9.6 KiB Raw Blame History