detections/.cursor/skills/autopilot/SKILL.md

---
name: autopilot
description: |
  Auto-chaining orchestrator that drives the full BUILD-SHIP workflow from problem gathering through deployment.
  Detects current project state from _docs/ folder, resumes from where it left off, and flows through
  problem → research → plan → decompose → implement → deploy without manual skill invocation.
  Maximizes work per conversation by auto-transitioning between skills.
  Trigger phrases:
  - "autopilot", "auto", "start", "continue"
  - "what's next", "where am I", "project status"
category: meta
tags: [orchestrator, workflow, auto-chain, state-machine, meta-skill]
disable-model-invocation: true
---

# Autopilot 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 `/autopilot` once — the engine handles sequencing, transitions, and re-entry.

## 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**: all progress is persisted to `_docs/_autopilot_state.md` and cross-checked against `_docs/` folder structure
- **Rich re-entry**: on every invocation, read the state file for full context 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-input-sound.mdc` — play a notification sound before every pause that requires human input
- **Minimize interruptions**: only ask the user when the decision genuinely cannot be resolved automatically
- **Jira MCP recommended**: steps that create Jira artifacts (Plan Step 6, Decompose) should have authenticated Jira MCP — if unavailable, offer user the choice to continue with local-only task tracking

## Jira MCP Authentication

Several workflow steps create Jira artifacts (epics, tasks, links). The Jira MCP server must be authenticated **before** any step that writes to Jira.

### Steps That Require Jira MCP

| Step | Sub-Step | Jira Action |
|------|----------|-------------|
| 2 (Plan) | Step 6 — Jira Epics | Create epics for each component |
| 3 (Decompose) | Step 1–3 — All tasks | Create Jira ticket per task, link to epic |

### Authentication Gate

Before entering **Step 2 (Plan)** or **Step 3 (Decompose)** for the first time, the autopilot must:

1. Call `mcp_auth` on the Jira MCP server
2. If authentication succeeds → proceed normally
3. If the user **skips** or authentication fails → present using Choose format:

```
══════════════════════════════════════
 Jira MCP authentication failed
══════════════════════════════════════
 A) Retry authentication (retry mcp_auth)
 B) Continue without Jira (tasks saved locally only)
══════════════════════════════════════
 Recommendation: A — Jira IDs drive task referencing,
 dependency tracking, and implementation batching.
 Without Jira, task files use numeric prefixes instead.
══════════════════════════════════════
```

If user picks **B** (continue without Jira):
- Set a flag in the state file: `jira_enabled: false`
- All skills that would create Jira tickets instead save metadata locally in the task/epic files with `Jira: pending` status
- Task files keep numeric prefixes (e.g., `01_initial_structure.md`) instead of Jira ID prefixes
- The workflow proceeds normally in all other respects

### Re-Authentication

If Jira MCP was already authenticated in a previous invocation (verify by listing available Jira tools beyond `mcp_auth`), skip the auth gate.

## User Interaction Protocol

Every time the autopilot or a sub-skill needs a user decision, use the **Choose A / B / C / D** format. This applies to:

- State transitions where multiple valid next actions exist
- Sub-skill BLOCKING gates that require user judgment
- Any fork where the autopilot cannot confidently pick the right path
- Trade-off decisions (tech choices, scope, risk acceptance)

### When to Ask (MUST ask)

- The next action is ambiguous (e.g., "another research round or proceed?")
- The decision has irreversible consequences (e.g., architecture choices, skipping a step)
- The user's intent or preference cannot be inferred from existing artifacts
- A sub-skill's BLOCKING gate explicitly requires user confirmation
- Multiple valid approaches exist with meaningfully different trade-offs

### When NOT to Ask (auto-transition)

- Only one logical next step exists (e.g., Problem complete → Research is the only option)
- The transition is deterministic from the state (e.g., Plan complete → Decompose)
- The decision is low-risk and reversible
- Existing artifacts or prior decisions already imply the answer

### Choice Format

Always present decisions in this format:

```
══════════════════════════════════════
 DECISION REQUIRED: [brief context]
══════════════════════════════════════
 A) [Option A — short description]
 B) [Option B — short description]
 C) [Option C — short description, if applicable]
 D) [Option D — short description, if applicable]
══════════════════════════════════════
 Recommendation: [A/B/C/D] — [one-line reason]
══════════════════════════════════════
```

Rules:
1. Always provide 2–4 concrete options (never open-ended questions)
2. Always include a recommendation with a brief justification
3. Keep option descriptions to one line each
4. If only 2 options make sense, use A/B only — do not pad with filler options
5. Play the notification sound (per `human-input-sound.mdc`) before presenting the choice
6. Record every user decision in the state file's `Key Decisions` section
7. After the user picks, proceed immediately — no follow-up confirmation unless the choice was destructive

## State File: `_docs/_autopilot_state.md`

The autopilot persists its state to `_docs/_autopilot_state.md`. This file is the primary source of truth for re-entry. Folder scanning is the fallback when the state file doesn't exist.

### Format

```markdown
# Autopilot State

## Current Step
step: [0-5 or "done"]
name: [Problem / Research / Plan / Decompose / Implement / Deploy / Done]
status: [not_started / in_progress / completed]
sub_step: [optional — sub-skill internal step number + name if interrupted mid-step]

## Step ↔ SubStep Reference
| Step | Name       | Sub-Skill              | Internal SubSteps                        |
|------|------------|------------------------|------------------------------------------|
| 0    | Problem    | problem/SKILL.md       | Phase 1–4                                |
| 1    | Research   | research/SKILL.md      | Mode A: Phase 1–4 · Mode B: Step 0–8    |
| 2    | Plan       | plan/SKILL.md          | Step 1–6                                 |
| 3    | Decompose  | decompose/SKILL.md     | Step 1–4                                 |
| 4    | Implement  | implement/SKILL.md     | (batch-driven, no fixed sub-steps)       |
| 5    | Deploy     | deploy/SKILL.md        | Step 1–7                                 |

When updating `Current Step`, always write it as:
  step: N          ← autopilot step (0–5)
  sub_step: M      ← sub-skill's own internal step/phase number + name
Example:
  step: 2
  name: Plan
  status: in_progress
  sub_step: 4 — Architecture Review & Risk Assessment

## Completed Steps

| Step | Name | Completed | Key Outcome |
|------|------|-----------|-------------|
| 0 | Problem | [date] | [one-line summary] |
| 1 | Research | [date] | [N drafts, final approach summary] |
| 2 | Plan | [date] | [N components, architecture summary] |
| 3 | Decompose | [date] | [N tasks, total complexity points] |
| 4 | Implement | [date] | [N batches, pass/fail summary] |
| 5 | Deploy | [date] | [artifacts produced] |

## Key Decisions
- [decision 1: e.g. "Tech stack: Python + Rust for perf-critical, Postgres DB"]
- [decision 2: e.g. "6 research rounds, final draft: solution_draft06.md"]
- [decision N]

## Last Session
date: [date]
ended_at: Step [N] [Name] — SubStep [M] [sub-step name]
reason: [completed step / session boundary / user paused / context limit]
notes: [any context for next session, e.g. "User asked to revisit risk assessment"]

## Blockers
- [blocker 1, if any]
- [none]
```

### State File Rules

1. **Create** the state file on the very first autopilot invocation (after state detection determines Step 0)
2. **Update** the state file after every step completion, every session boundary, and every BLOCKING gate confirmation
3. **Read** the state file as the first action on every invocation — before folder scanning
4. **Cross-check**: after reading the state file, verify against actual `_docs/` folder contents. If they disagree (e.g., state file says Step 2 but `_docs/02_document/architecture.md` already exists), trust the folder structure and update the state file to match
5. **Never delete** the state file. It accumulates history across the entire project lifecycle

## Execution Entry Point

Every invocation of this skill follows the same sequence:

```
1. Read _docs/_autopilot_state.md (if exists)
2. Cross-check state file against _docs/ folder structure
3. Resolve current step (state file + folder scan)
4. Present Status Summary (from state file context)
5. Enter Execution Loop:
   a. Read and execute the current skill's SKILL.md
   b. When skill completes → update state file
   c. Re-detect next step
   d. If next skill is ready → auto-chain (go to 5a with next skill)
   e. If session boundary reached → update state file with session notes → suggest new conversation
   f. If all steps done → update state file → report completion
```

## 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. Check rules in order — first match wins.

### Detection Rules

**Pre-Step — Existing Codebase Detection**
Condition: `_docs/` does not exist AND the workspace contains source code files (e.g., `*.py`, `*.cs`, `*.rs`, `*.ts`, `src/`, `Cargo.toml`, `*.csproj`, `package.json`)

Action: An existing codebase without documentation was detected. Present using Choose format:

```
══════════════════════════════════════
 DECISION REQUIRED: Existing codebase detected
══════════════════════════════════════
 A) Start fresh — define the problem from scratch (normal workflow)
 B) Document existing codebase first — run /document to reverse-engineer docs, then continue
══════════════════════════════════════
 Recommendation: B — the /document skill analyzes your code
 bottom-up and produces _docs/ artifacts automatically,
 then you can continue with refactor or the normal workflow.
══════════════════════════════════════
```

- If user picks A → proceed to Step 0 (Problem Gathering) as normal
- If user picks B → read and execute `.cursor/skills/document/SKILL.md`. After document skill completes, re-detect state (the produced `_docs/` artifacts will place the project at Step 2 or later).

---

**Step 0 — Problem Gathering**
Condition: `_docs/00_problem/` does not exist, OR any of these are missing/empty:
- `problem.md`
- `restrictions.md`
- `acceptance_criteria.md`
- `input_data/` (must contain at least one file)

Action: Read and execute `.cursor/skills/problem/SKILL.md`

---

**Step 1 — Research (Initial)**
Condition: `_docs/00_problem/` is complete AND `_docs/01_solution/` has no `solution_draft*.md` files

Action: Read and execute `.cursor/skills/research/SKILL.md` (will auto-detect Mode A)

---

**Step 1b — Research Decision**
Condition: `_docs/01_solution/` contains `solution_draft*.md` files AND `_docs/01_solution/solution.md` does not exist AND `_docs/02_document/architecture.md` does not exist

Action: Present the current research state to the user:
- How many solution drafts exist
- Whether tech_stack.md and security_analysis.md exist
- One-line summary from the latest draft

Then present using the **Choose format**:

```
══════════════════════════════════════
 DECISION REQUIRED: Research complete — next action?
══════════════════════════════════════
 A) Run another research round (Mode B assessment)
 B) Proceed to planning with current draft
══════════════════════════════════════
 Recommendation: [A or B] — [reason based on draft quality]
══════════════════════════════════════
```

- If user picks A → Read and execute `.cursor/skills/research/SKILL.md` (will auto-detect Mode B)
- If user picks B → auto-chain to Step 2 (Plan)

---

**Step 2 — Plan**
Condition: `_docs/01_solution/` has `solution_draft*.md` files AND `_docs/02_document/architecture.md` does not exist

Action:
1. The plan skill's Prereq 2 will rename the latest draft to `solution.md` — this is handled by the plan skill itself
2. Read and execute `.cursor/skills/plan/SKILL.md`

If `_docs/02_document/` exists but is incomplete (has some artifacts but no `FINAL_report.md`), the plan skill's built-in resumability handles it.

---

**Step 3 — Decompose**
Condition: `_docs/02_document/` contains `architecture.md` AND `_docs/02_document/components/` has at least one component AND `_docs/02_tasks/` does not exist or has no task files (excluding `_dependencies_table.md`)

Action: Read and execute `.cursor/skills/decompose/SKILL.md`

If `_docs/02_tasks/` has some task files already, the decompose skill's resumability handles it.

---

**Step 4 — Implement**
Condition: `_docs/02_tasks/` contains task files AND `_dependencies_table.md` exists AND `_docs/03_implementation/FINAL_implementation_report.md` does not exist

Action: Read and execute `.cursor/skills/implement/SKILL.md`

If `_docs/03_implementation/` has batch reports, the implement skill detects completed tasks and continues.

---

**Step 5 — Deploy**
Condition: `_docs/03_implementation/FINAL_implementation_report.md` exists AND `_docs/04_deploy/` does not exist or is incomplete

Action: Read and execute `.cursor/skills/deploy/SKILL.md`

---

**Done**
Condition: `_docs/04_deploy/` contains all expected artifacts (containerization.md, ci_cd_pipeline.md, environment_strategy.md, observability.md, deployment_procedures.md)

Action: Report project completion with summary.

## Status Summary

On every invocation, before executing any skill, present a status summary built from the state file (with folder scan fallback).

Format:

```
═══════════════════════════════════════════════════
 AUTOPILOT STATUS
═══════════════════════════════════════════════════
 Step 0  Problem      [DONE / IN PROGRESS / NOT STARTED]
 Step 1  Research     [DONE (N drafts) / IN PROGRESS / NOT STARTED]
 Step 2  Plan         [DONE / IN PROGRESS / NOT STARTED]
 Step 3  Decompose    [DONE (N tasks) / IN PROGRESS / NOT STARTED]
 Step 4  Implement    [DONE / IN PROGRESS (batch M of ~N) / NOT STARTED]
 Step 5  Deploy       [DONE / IN PROGRESS / NOT STARTED]
═══════════════════════════════════════════════════
 Current: Step N — Name
 SubStep: M — [sub-skill internal step name]
 Action:  [what will happen next]
═══════════════════════════════════════════════════
```

For re-entry (state file exists), also include:
- Key decisions from the state file's `Key Decisions` section
- Last session context from the `Last Session` section
- Any blockers from the `Blockers` section

## Auto-Chain Rules

After a skill completes, apply these rules:

| Completed Step | Next Action |
|---------------|-------------|
| Problem Gathering | Auto-chain → Research (Mode A) |
| Research (any round) | Auto-chain → Research Decision (ask user: another round or proceed?) |
| Research Decision → proceed | Auto-chain → Plan |
| Plan | Auto-chain → Decompose |
| Decompose | **Session boundary** — suggest new conversation before Implement |
| Implement | Auto-chain → Deploy |
| Deploy | Report completion |

### Session Boundary: Decompose → Implement

After decompose completes, **do not auto-chain to implement**. Instead:

1. Update state file: mark Decompose as completed, set current step to 4 (Implement) with status `not_started`
2. Write `Last Session` section: `reason: session boundary`, `notes: Decompose complete, implementation ready`
3. Present a summary: number of tasks, estimated batches, total complexity points
4. 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
══════════════════════════════════════
```

This is the only hard session boundary. All other transitions auto-chain.

## Skill Delegation

For each step, the delegation pattern is:

1. Update state file: set `step` to the autopilot step number (0–5), status to `in_progress`, set `sub_step` to the sub-skill's current internal step/phase number and name
2. Announce: "Starting [Skill Name]..."
3. Read the skill file: `.cursor/skills/[name]/SKILL.md`
4. Execute the skill's workflow exactly as written, including:
   - All BLOCKING gates (present to user, wait for confirmation)
   - All self-verification checklists
   - All save actions
   - All escalation rules
   - Update `sub_step` in the state file each time the sub-skill advances to a new internal step/phase
5. When the skill's workflow is fully complete:
   - Update state file: mark step as `completed`, record date, write one-line key outcome
   - Add any key decisions made during this step to the `Key Decisions` section
   - Return to the auto-chain rules

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

## 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 with context from state file (key decisions, last session, blockers)
4. If the detected step has a sub-skill with built-in resumability (plan, decompose, implement, deploy all do), the sub-skill handles mid-step recovery
5. Continue execution from detected state

## Error Handling

All error situations that require user input MUST use the **Choose A / B / C / D** format.

| Situation | Action |
|-----------|--------|
| State detection is ambiguous (artifacts suggest two different steps) | Present findings and use Choose format with the candidate steps as options |
| Sub-skill fails or hits an unrecoverable blocker | Use Choose format: A) retry, B) skip with warning, C) abort and fix manually |
| User wants to skip a step | Use Choose format: A) skip (with dependency warning), B) execute the step |
| User wants to go back to a previous step | Use Choose format: A) re-run (with overwrite warning), B) stay on current step |
| User asks "where am I?" without wanting to continue | Show Status Summary only, do not start execution |

## 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**: "autopilot", "auto", "start", "continue", "what's next", "where am I", "project status"

**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 `/autopilot`

## Methodology Quick Reference

```
┌────────────────────────────────────────────────────────────────┐
│              Autopilot (Auto-Chain Orchestrator)                │
├────────────────────────────────────────────────────────────────┤
│ EVERY INVOCATION:                                              │
│   1. State Detection (scan _docs/)                             │
│   2. Status Summary (show progress)                            │
│   3. Execute current skill                                     │
│   4. Auto-chain to next skill (loop)                           │
│                                                                │
│ WORKFLOW:                                                       │
│   Step 0  Problem    → .cursor/skills/problem/SKILL.md         │
│     ↓ auto-chain                                               │
│   Step 1  Research   → .cursor/skills/research/SKILL.md        │
│     ↓ auto-chain (ask: another round?)                         │
│   Step 2  Plan       → .cursor/skills/plan/SKILL.md            │
│     ↓ auto-chain                                               │
│   Step 3  Decompose  → .cursor/skills/decompose/SKILL.md       │
│     ↓ SESSION BOUNDARY (suggest new conversation)              │
│   Step 4  Implement  → .cursor/skills/implement/SKILL.md       │
│     ↓ auto-chain                                               │
│   Step 5  Deploy     → .cursor/skills/deploy/SKILL.md          │
│     ↓                                                          │
│   DONE                                                         │
│                                                                │
│ STATE FILE: _docs/_autopilot_state.md                          │
│ FALLBACK: _docs/ folder structure scan                         │
│ PAUSE POINTS: sub-skill BLOCKING gates only                    │
│ SESSION BREAK: after Decompose (before Implement)              │
│ USER INPUT: Choose A/B/C/D format at genuine decisions only    │
│ AUTO-TRANSITION: when path is unambiguous, don't ask            │
├────────────────────────────────────────────────────────────────┤
│ Principles: Auto-chain · State to file · Rich re-entry         │
│             Delegate don't duplicate · Pause at decisions only  │
│             Minimize interruptions · Choose format for decisions │
└────────────────────────────────────────────────────────────────┘
```