mirror of
https://github.com/azaion/detections.git
synced 2026-04-23 04:06:32 +00:00
Add detailed file index and enhance skill documentation for autopilot, decompose, deploy, plan, and research skills. Introduce tests-only mode in decompose skill, clarify required files for deploy and plan skills, and improve prerequisite checks across skills for better user guidance and workflow efficiency.
This commit is contained in:
Oleksandr Bezdieniezhnykh
@@ -17,6 +17,17 @@ disable-model-invocation: true
|
||||
|
||||
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.
|
||||
|
||||
## 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 |
|
||||
| `state.md` | State file format, rules, re-entry protocol, session boundaries |
|
||||
| `protocols.md` | User interaction, Jira MCP auth, choice format, error handling, status summary |
|
||||
|
||||
**On every invocation**: read all four files above before executing any logic.
|
||||
|
||||
## Core Principles
|
||||
|
||||
- **Auto-chain**: when a skill completes, immediately start the next one — no pause between skills
|
||||
@@ -26,411 +37,50 @@ Auto-chaining execution engine that drives the full BUILD → SHIP workflow. Det
|
||||
- **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
|
||||
## Flow Resolution
|
||||
|
||||
Several workflow steps create Jira artifacts (epics, tasks, links). The Jira MCP server must be authenticated **before** any step that writes to Jira.
|
||||
Determine which flow to use:
|
||||
|
||||
### Steps That Require Jira MCP
|
||||
1. If workspace has source code files **and** `_docs/` does not exist → **existing-code flow** (Pre-Step detection)
|
||||
2. If `_docs/_autopilot_state.md` exists and records Document in `Completed Steps` → **existing-code flow**
|
||||
3. If `_docs/_autopilot_state.md` exists and `step: done` AND workspace contains source code → **existing-code flow** (completed project re-entry — loops to New Task)
|
||||
4. Otherwise → **greenfield flow**
|
||||
|
||||
| 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 |
|
||||
After selecting the flow, apply its detection rules (first match wins) to determine the current step.
|
||||
|
||||
### Authentication Gate
|
||||
## Execution Loop
|
||||
|
||||
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:
|
||||
Every invocation follows this 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
|
||||
2. Read all File Index files above
|
||||
3. Cross-check state file against _docs/ folder structure (rules in state.md)
|
||||
4. Resolve flow (see Flow Resolution above)
|
||||
5. Resolve current step (detection rules from the active flow file)
|
||||
6. Present Status Summary (format in protocols.md)
|
||||
7. Execute:
|
||||
a. Delegate to current skill (see Skill Delegation below)
|
||||
b. When skill completes → update state file (rules in state.md)
|
||||
c. Re-detect next step from the active flow's detection rules
|
||||
d. If next skill is ready → auto-chain (go to 7a with next skill)
|
||||
e. If session boundary reached → update state, suggest new conversation (rules in state.md)
|
||||
f. If all steps done → update state → 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
|
||||
1. Update state file: set `step` to the autopilot step number, status to `in_progress`, set `sub_step` to the sub-skill's current internal step/phase
|
||||
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
|
||||
4. Execute the skill's workflow exactly as written, including all BLOCKING gates, self-verification checklists, save actions, and escalation rules. Update `sub_step` in state each time the sub-skill advances.
|
||||
5. When complete: mark step `completed`, record date + key outcome, add key decisions to state file, return to auto-chain rules (from active flow file)
|
||||
|
||||
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:
|
||||
@@ -454,35 +104,27 @@ This skill activates when the user wants to:
|
||||
│ 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) │
|
||||
│ 1. Read state file + module files │
|
||||
│ 2. Resolve flow & current step │
|
||||
│ 3. Status Summary → Execute → Auto-chain (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 │
|
||||
│ GREENFIELD FLOW (flows/greenfield.md): │
|
||||
│ Step 0 Problem → Step 1 Research → Step 2 Plan │
|
||||
│ → Step 3 Decompose → [SESSION] → Step 4 Implement │
|
||||
│ → Step 5 Run Tests → Step 6 Deploy → DONE │
|
||||
│ │
|
||||
│ STATE FILE: _docs/_autopilot_state.md │
|
||||
│ FALLBACK: _docs/ folder structure scan │
|
||||
│ EXISTING CODE FLOW (flows/existing-code.md): │
|
||||
│ Pre-Step Document → 2b Test Spec → 2c Decompose Tests │
|
||||
│ → [SESSION] → 2d Implement Tests → 2e Refactor │
|
||||
│ → 2f New Task → [SESSION] → 2g Implement │
|
||||
│ → 2h Run Tests → 2i Deploy → DONE │
|
||||
│ │
|
||||
│ STATE: _docs/_autopilot_state.md (see state.md) │
|
||||
│ PROTOCOLS: choice format, Jira auth, errors (see protocols.md) │
|
||||
│ 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 │
|
||||
│ SESSION BREAK: after Decompose/New Task (before Implement) │
|
||||
├────────────────────────────────────────────────────────────────┤
|
||||
│ Principles: Auto-chain · State to file · Rich re-entry │
|
||||
│ Delegate don't duplicate · Pause at decisions only │
|
||||
│ Minimize interruptions · Choose format for decisions │
|
||||
│ Auto-chain · State to file · Rich re-entry · Delegate │
|
||||
│ Pause at decisions only · Minimize interruptions │
|
||||
└────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
@@ -0,0 +1,181 @@
|
||||
# Existing Code Workflow
|
||||
|
||||
Workflow for projects with an existing codebase. Starts with documentation, produces test specs, decomposes and implements tests, refactors with that safety net, then adds new functionality and deploys.
|
||||
|
||||
## Step Reference Table
|
||||
|
||||
| Step | Name | Sub-Skill | Internal SubSteps |
|
||||
|------|-------------------------|---------------------------------|---------------------------------------|
|
||||
| — | Document (pre-step) | document/SKILL.md | Steps 1–8 |
|
||||
| 2b | Blackbox Test Spec | blackbox-test-spec/SKILL.md | Phase 1a–1b |
|
||||
| 2c | Decompose Tests | decompose/SKILL.md (tests-only) | Step 1t + Step 3 + Step 4 |
|
||||
| 2d | Implement Tests | implement/SKILL.md | (batch-driven, no fixed sub-steps) |
|
||||
| 2e | Refactor | refactor/SKILL.md | Phases 0–5 (6-phase method) |
|
||||
| 2f | New Task | new-task/SKILL.md | Steps 1–8 (loop) |
|
||||
| 2g | Implement | implement/SKILL.md | (batch-driven, no fixed sub-steps) |
|
||||
| 2h | Run Tests | (autopilot-managed) | Unit tests → Integration/blackbox tests |
|
||||
| 2i | Deploy | deploy/SKILL.md | Steps 1–7 |
|
||||
|
||||
After Step 2i, the existing-code workflow is complete.
|
||||
|
||||
## Detection Rules
|
||||
|
||||
Check rules in order — first match wins.
|
||||
|
||||
---
|
||||
|
||||
**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 (greenfield 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 test specs, refactor, and new features.
|
||||
══════════════════════════════════════
|
||||
```
|
||||
|
||||
- If user picks A → proceed to Step 0 (Problem Gathering) in the greenfield flow
|
||||
- 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 2b or later).
|
||||
|
||||
---
|
||||
|
||||
**Step 2b — Blackbox Test Spec**
|
||||
Condition: `_docs/02_document/FINAL_report.md` exists AND workspace contains source code files (e.g., `*.py`, `*.cs`, `*.rs`, `*.ts`) AND `_docs/02_document/integration_tests/traceability_matrix.md` does not exist AND the autopilot state shows Document was run (check `Completed Steps` for "Document" entry)
|
||||
|
||||
Action: Read and execute `.cursor/skills/blackbox-test-spec/SKILL.md`
|
||||
|
||||
This step applies when the codebase was documented via the `/document` skill. Test specifications must be produced before refactoring or further development.
|
||||
|
||||
---
|
||||
|
||||
**Step 2c — Decompose Tests**
|
||||
Condition: `_docs/02_document/integration_tests/traceability_matrix.md` exists AND workspace contains source code files AND the autopilot state shows Document was run AND (`_docs/02_tasks/` does not exist or has no task files)
|
||||
|
||||
Action: Read and execute `.cursor/skills/decompose/SKILL.md` in **tests-only mode** (pass `_docs/02_document/integration_tests/` as input). The decompose skill will:
|
||||
1. Run Step 1t (test infrastructure bootstrap)
|
||||
2. Run Step 3 (integration test task decomposition)
|
||||
3. Run Step 4 (cross-verification against test coverage)
|
||||
|
||||
If `_docs/02_tasks/` has some task files already, the decompose skill's resumability handles it.
|
||||
|
||||
---
|
||||
|
||||
**Step 2d — Implement Tests**
|
||||
Condition: `_docs/02_tasks/` contains task files AND `_dependencies_table.md` exists AND the autopilot state shows Step 2c (Decompose Tests) is completed AND `_docs/03_implementation/FINAL_implementation_report.md` does not exist
|
||||
|
||||
Action: Read and execute `.cursor/skills/implement/SKILL.md`
|
||||
|
||||
The implement skill reads test tasks from `_docs/02_tasks/` and implements them.
|
||||
|
||||
If `_docs/03_implementation/` has batch reports, the implement skill detects completed tasks and continues.
|
||||
|
||||
---
|
||||
|
||||
**Step 2e — Refactor**
|
||||
Condition: `_docs/03_implementation/FINAL_implementation_report.md` exists AND the autopilot state shows Step 2d (Implement Tests) is completed AND `_docs/04_refactor/FINAL_refactor_report.md` does not exist
|
||||
|
||||
Action: Read and execute `.cursor/skills/refactor/SKILL.md`
|
||||
|
||||
The refactor skill runs the full 6-phase method using the implemented tests as a safety net.
|
||||
|
||||
If `_docs/04_refactor/` has phase reports, the refactor skill detects completed phases and continues.
|
||||
|
||||
---
|
||||
|
||||
**Step 2f — New Task**
|
||||
Condition: `_docs/04_refactor/FINAL_refactor_report.md` exists AND the autopilot state shows Step 2e (Refactor) is completed AND the autopilot state does NOT show Step 2f (New Task) as completed
|
||||
|
||||
Action: Read and execute `.cursor/skills/new-task/SKILL.md`
|
||||
|
||||
The new-task skill interactively guides the user through defining new functionality. It loops until the user is done adding tasks. New task files are written to `_docs/02_tasks/`.
|
||||
|
||||
---
|
||||
|
||||
**Step 2g — Implement**
|
||||
Condition: the autopilot state shows Step 2f (New Task) is completed AND `_docs/03_implementation/` does not contain a FINAL report covering the new tasks (check state for distinction between test implementation and feature implementation)
|
||||
|
||||
Action: Read and execute `.cursor/skills/implement/SKILL.md`
|
||||
|
||||
The implement skill reads the new tasks from `_docs/02_tasks/` and implements them. Tasks already implemented in Step 2d are skipped (the implement skill tracks completed tasks in batch reports).
|
||||
|
||||
If `_docs/03_implementation/` has batch reports from this phase, the implement skill detects completed tasks and continues.
|
||||
|
||||
---
|
||||
|
||||
**Step 2h — Run Tests**
|
||||
Condition: the autopilot state shows Step 2g (Implement) is completed AND the autopilot state does NOT show Step 2h (Run Tests) as completed
|
||||
|
||||
Action: Run the full test suite to verify the implementation before deployment.
|
||||
|
||||
1. **Unit tests**: detect the project's test runner (e.g., `pytest`, `dotnet test`, `cargo test`, `npm test`) and run all unit tests
|
||||
2. **Integration / blackbox tests**: if `docker-compose.test.yml` or an equivalent test environment exists, spin it up and run the integration test suite
|
||||
3. **Report results**: present a summary of passed/failed/skipped tests
|
||||
|
||||
If all tests pass → auto-chain to Step 2i (Deploy).
|
||||
|
||||
If tests fail → present using Choose format:
|
||||
|
||||
```
|
||||
══════════════════════════════════════
|
||||
TEST RESULTS: [N passed, M failed, K skipped]
|
||||
══════════════════════════════════════
|
||||
A) Fix failing tests and re-run
|
||||
B) Proceed to deploy anyway (not recommended)
|
||||
C) Abort — fix manually
|
||||
══════════════════════════════════════
|
||||
Recommendation: A — fix failures before deploying
|
||||
══════════════════════════════════════
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Step 2i — Deploy**
|
||||
Condition: the autopilot state shows Step 2h (Run Tests) is completed AND (`_docs/04_deploy/` does not exist or is incomplete)
|
||||
|
||||
Action: Read and execute `.cursor/skills/deploy/SKILL.md`
|
||||
|
||||
After deployment completes, the existing-code workflow is done.
|
||||
|
||||
---
|
||||
|
||||
**Re-Entry After Completion**
|
||||
Condition: the autopilot state shows `step: done` OR all steps through 2i (Deploy) are completed
|
||||
|
||||
Action: The project completed a full cycle. Present status and loop back to New Task:
|
||||
|
||||
```
|
||||
══════════════════════════════════════
|
||||
PROJECT CYCLE COMPLETE
|
||||
══════════════════════════════════════
|
||||
The previous cycle finished successfully.
|
||||
You can now add new functionality.
|
||||
══════════════════════════════════════
|
||||
A) Add new features (start New Task)
|
||||
B) Done — no more changes needed
|
||||
══════════════════════════════════════
|
||||
```
|
||||
|
||||
- If user picks A → set `step: 2f`, `status: not_started` in the state file, then auto-chain to Step 2f (New Task). Previous cycle history stays in Completed Steps.
|
||||
- If user picks B → report final project status and exit.
|
||||
|
||||
## Auto-Chain Rules
|
||||
|
||||
| Completed Step | Next Action |
|
||||
|---------------|-------------|
|
||||
| Document (existing code) | Auto-chain → Blackbox Test Spec (Step 2b) |
|
||||
| Blackbox Test Spec (Step 2b) | Auto-chain → Decompose Tests (Step 2c) |
|
||||
| Decompose Tests (Step 2c) | **Session boundary** — suggest new conversation before Implement Tests |
|
||||
| Implement Tests (Step 2d) | Auto-chain → Refactor (Step 2e) |
|
||||
| Refactor (Step 2e) | Auto-chain → New Task (Step 2f) |
|
||||
| New Task (Step 2f) | **Session boundary** — suggest new conversation before Implement |
|
||||
| Implement (Step 2g) | Auto-chain → Run Tests (Step 2h) |
|
||||
| Run Tests (Step 2h, all pass) | Auto-chain → Deploy (Step 2i) |
|
||||
| Deploy (Step 2i) | **Workflow complete** — existing-code flow done |
|
||||
@@ -0,0 +1,146 @@
|
||||
# Greenfield Workflow
|
||||
|
||||
Workflow for new projects built from scratch. Flows linearly: Problem → Research → Plan → Decompose → Implement → Run Tests → Deploy.
|
||||
|
||||
## Step Reference Table
|
||||
|
||||
| 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 | Run Tests | (autopilot-managed) | Unit tests → Integration/blackbox tests |
|
||||
| 6 | Deploy | deploy/SKILL.md | Step 1–7 |
|
||||
|
||||
## Detection Rules
|
||||
|
||||
Check rules in order — first match wins.
|
||||
|
||||
---
|
||||
|
||||
**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`) AND (workspace has no source code files OR the user explicitly chose normal workflow in Step 2c)
|
||||
|
||||
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 — Run Tests**
|
||||
Condition: `_docs/03_implementation/FINAL_implementation_report.md` exists AND the autopilot state does NOT show Step 5 (Run Tests) as completed AND (`_docs/04_deploy/` does not exist or is incomplete)
|
||||
|
||||
Action: Run the full test suite to verify the implementation before deployment.
|
||||
|
||||
1. **Unit tests**: detect the project's test runner (e.g., `pytest`, `dotnet test`, `cargo test`, `npm test`) and run all unit tests
|
||||
2. **Integration / blackbox tests**: if `docker-compose.test.yml` or an equivalent test environment exists, spin it up and run the integration test suite
|
||||
3. **Report results**: present a summary of passed/failed/skipped tests
|
||||
|
||||
If all tests pass → auto-chain to Step 6 (Deploy).
|
||||
|
||||
If tests fail → present using Choose format:
|
||||
|
||||
```
|
||||
══════════════════════════════════════
|
||||
TEST RESULTS: [N passed, M failed, K skipped]
|
||||
══════════════════════════════════════
|
||||
A) Fix failing tests and re-run
|
||||
B) Proceed to deploy anyway (not recommended)
|
||||
C) Abort — fix manually
|
||||
══════════════════════════════════════
|
||||
Recommendation: A — fix failures before deploying
|
||||
══════════════════════════════════════
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Step 6 — Deploy**
|
||||
Condition: the autopilot state shows Step 5 (Run Tests) is completed 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. If the user runs autopilot again after greenfield completion, Flow Resolution rule 3 routes to the existing-code flow (re-entry after completion) so they can add new features.
|
||||
|
||||
## Auto-Chain 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 → Run Tests (Step 5) |
|
||||
| Run Tests (all pass) | Auto-chain → Deploy (Step 6) |
|
||||
| Deploy | Report completion |
|
||||
@@ -0,0 +1,158 @@
|
||||
# Autopilot Protocols
|
||||
|
||||
## 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
|
||||
|
||||
## 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 |
|
||||
| 2c (Decompose Tests) | Step 1t + Step 3 — All test tasks | Create Jira ticket per task, link to epic |
|
||||
| 2f (New Task) | Step 7 — Jira ticket | Create Jira ticket per task, link to epic |
|
||||
| 3 (Decompose) | Step 1–3 — All tasks | Create Jira ticket per task, link to epic |
|
||||
|
||||
### Authentication Gate
|
||||
|
||||
Before entering **Step 2 (Plan)**, **Step 2c (Decompose Tests)**, **Step 2f (New Task)**, 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.
|
||||
|
||||
## 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 |
|
||||
|
||||
## Status Summary
|
||||
|
||||
On every invocation, before executing any skill, present a status summary built from the state file (with folder scan fallback). Use the template matching the active flow (see Flow Resolution in SKILL.md).
|
||||
|
||||
### Greenfield Flow
|
||||
|
||||
```
|
||||
═══════════════════════════════════════════════════
|
||||
AUTOPILOT STATUS (greenfield)
|
||||
═══════════════════════════════════════════════════
|
||||
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 Run Tests [DONE (N passed, M failed) / IN PROGRESS / NOT STARTED]
|
||||
Step 6 Deploy [DONE / IN PROGRESS / NOT STARTED]
|
||||
═══════════════════════════════════════════════════
|
||||
Current: Step N — Name
|
||||
SubStep: M — [sub-skill internal step name]
|
||||
Action: [what will happen next]
|
||||
═══════════════════════════════════════════════════
|
||||
```
|
||||
|
||||
### Existing Code Flow
|
||||
|
||||
```
|
||||
═══════════════════════════════════════════════════
|
||||
AUTOPILOT STATUS (existing-code)
|
||||
═══════════════════════════════════════════════════
|
||||
Pre Document [DONE / IN PROGRESS / NOT STARTED]
|
||||
Step 2b Blackbox Test Spec [DONE / IN PROGRESS / NOT STARTED]
|
||||
Step 2c Decompose Tests [DONE (N tasks) / IN PROGRESS / NOT STARTED]
|
||||
Step 2d Implement Tests [DONE / IN PROGRESS (batch M) / NOT STARTED]
|
||||
Step 2e Refactor [DONE / IN PROGRESS (phase N) / NOT STARTED]
|
||||
Step 2f New Task [DONE (N tasks) / IN PROGRESS / NOT STARTED]
|
||||
Step 2g Implement [DONE / IN PROGRESS (batch M of ~N) / NOT STARTED]
|
||||
Step 2h Run Tests [DONE (N passed, M failed) / IN PROGRESS / NOT STARTED]
|
||||
Step 2i 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
|
||||
@@ -0,0 +1,102 @@
|
||||
# Autopilot State Management
|
||||
|
||||
## 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-6 or "2b" / "2c" / "2d" / "2e" / "2f" / "2g" / "2h" / "2i" or "done"]
|
||||
name: [Problem / Research / Plan / Blackbox Test Spec / Decompose Tests / Implement Tests / Refactor / New Task / Implement / Run Tests / Deploy / Decompose / Done]
|
||||
status: [not_started / in_progress / completed]
|
||||
sub_step: [optional — sub-skill internal step number + name if interrupted mid-step]
|
||||
|
||||
## Step ↔ SubStep Reference
|
||||
(include the step reference table from the active flow file)
|
||||
|
||||
When updating `Current Step`, always write it as:
|
||||
step: N ← autopilot step (0–6 or 2b/2c/2d/2e/2f/2g/2h/2i)
|
||||
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] |
|
||||
| ... | ... | ... | ... |
|
||||
|
||||
## Key Decisions
|
||||
- [decision 1: e.g. "Tech stack: Python + Rust for perf-critical, Postgres DB"]
|
||||
- [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]
|
||||
|
||||
## 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
|
||||
|
||||
## 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 (Pre-Step 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 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
|
||||
|
||||
## Session Boundaries
|
||||
|
||||
After any decompose/planning step completes (Step 2c, Step 2f, or Step 3), **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`
|
||||
- After Step 2c (Decompose Tests) → set current step to 2d (Implement Tests)
|
||||
- After Step 2f (New Task) → set current step to 2g (Implement)
|
||||
- After Step 3 (Decompose) → set current step to 4 (Implement)
|
||||
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
|
||||
══════════════════════════════════════
|
||||
```
|
||||
|
||||
These are the only hard session boundaries. All other transitions auto-chain.
|
||||
Reference in New Issue
Block a user