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.

2026-04-23 05:06:33 +00:00 · 2026-03-22 16:15:49 +02:00
parent 60ebe686ff
commit 3165a88f0b
60 changed files with 6324 additions and 1550 deletions
@@ -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