mirror of
https://github.com/azaion/detections.git
synced 2026-04-23 00:56:32 +00:00
Oleksandr Bezdieniezhnykh
256 lines
13 KiB
Markdown
256 lines
13 KiB
Markdown
# 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 |
|
||
|
||
## Error Recovery Protocol
|
||
|
||
### Stuck Detection
|
||
|
||
When executing a sub-skill, monitor for these signals:
|
||
|
||
- Same artifact overwritten 3+ times without meaningful change
|
||
- Sub-skill repeatedly asks the same question after receiving an answer
|
||
- No new artifacts saved for an extended period despite active execution
|
||
|
||
### Recovery Actions (ordered)
|
||
|
||
1. **Re-read state**: read `_docs/_autopilot_state.md` and cross-check against `_docs/` folders
|
||
2. **Retry current sub-step**: re-read the sub-skill's SKILL.md and restart from the current sub-step
|
||
3. **Escalate**: after 2 failed retries, present diagnostic summary to user using Choose format:
|
||
|
||
```
|
||
══════════════════════════════════════
|
||
RECOVERY: [skill name] stuck at [sub-step]
|
||
══════════════════════════════════════
|
||
A) Retry with fresh context (new conversation)
|
||
B) Skip this sub-step with warning
|
||
C) Abort and fix manually
|
||
══════════════════════════════════════
|
||
Recommendation: A — fresh context often resolves stuck loops
|
||
══════════════════════════════════════
|
||
```
|
||
|
||
### Circuit Breaker
|
||
|
||
If the same autopilot step fails 3 consecutive times across conversations:
|
||
|
||
- Record the failure pattern in the state file's `Blockers` section
|
||
- Do NOT auto-retry on next invocation
|
||
- Present the blocker and ask user for guidance before attempting again
|
||
|
||
## Context Management Protocol
|
||
|
||
### Principle
|
||
|
||
Disk is memory. Never rely on in-context accumulation — read from `_docs/` artifacts, not from conversation history.
|
||
|
||
### Minimal Re-Read Set Per Skill
|
||
|
||
When re-entering a skill (new conversation or context refresh):
|
||
|
||
- Always read: `_docs/_autopilot_state.md`
|
||
- Always read: the active skill's `SKILL.md`
|
||
- Conditionally read: only the `_docs/` artifacts the current sub-step requires (listed in each skill's Context Resolution section)
|
||
- Never bulk-read: do not load all `_docs/` files at once
|
||
|
||
### Mid-Skill Interruption
|
||
|
||
If context is filling up during a long skill (e.g., document, implement):
|
||
|
||
1. Save current sub-step progress to the skill's artifact directory
|
||
2. Update `_docs/_autopilot_state.md` with exact sub-step position
|
||
3. Suggest a new conversation: "Context is getting long — recommend continuing in a fresh conversation for better results"
|
||
4. On re-entry, the skill's resumability protocol picks up from the saved sub-step
|
||
|
||
### Large Artifact Handling
|
||
|
||
When a skill needs to read large files (e.g., full solution.md, architecture.md):
|
||
|
||
- Read only the sections relevant to the current sub-step
|
||
- Use search tools (Grep, SemanticSearch) to find specific sections rather than reading entire files
|
||
- Summarize key decisions from prior steps in the state file so they don't need to be re-read
|
||
|
||
## Rollback Protocol
|
||
|
||
### Implementation Steps (git-based)
|
||
|
||
Handled by `/implement` skill — each batch commit is a rollback checkpoint via `git revert`.
|
||
|
||
### Planning/Documentation Steps (artifact-based)
|
||
|
||
For steps that produce `_docs/` artifacts (problem, research, plan, decompose, document):
|
||
|
||
1. **Before overwriting**: if re-running a step that already has artifacts, the sub-skill's prerequisite check asks the user (resume/overwrite/skip)
|
||
2. **Rollback to previous step**: use Choose format:
|
||
|
||
```
|
||
══════════════════════════════════════
|
||
ROLLBACK: Re-run [step name]?
|
||
══════════════════════════════════════
|
||
A) Re-run the step (overwrites current artifacts)
|
||
B) Stay on current step
|
||
══════════════════════════════════════
|
||
Warning: This will overwrite files in _docs/[folder]/
|
||
══════════════════════════════════════
|
||
```
|
||
|
||
3. **Git safety net**: artifacts are committed with each autopilot step completion. To roll back: `git log --oneline _docs/` to find the commit, then `git checkout <commit> -- _docs/<folder>/`
|
||
4. **State file rollback**: when rolling back artifacts, also update `_docs/_autopilot_state.md` to reflect the rolled-back step (set it to `in_progress`, clear completed date)
|
||
|
||
## 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 5b Security Audit [DONE / SKIPPED / 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 2hb Security Audit [DONE / SKIPPED / 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
|