@sniper.ai/core 3.0.0 → 3.1.0

package/protocols/ingest.yaml

@@ -12,7 +12,7 @@ phases:
       checklist: ingest-scan
       human_approval: false
     outputs:
-      - docs/codebase-overview.md
+      - .sniper/artifacts/codebase-overview.md  # Living master doc — not per-protocol
 
   - name: document
     description: Generate documentation from code analysis
@@ -23,7 +23,7 @@ phases:
       checklist: ingest-document
       human_approval: false
     outputs:
-      - docs/spec.md
+      - .sniper/artifacts/spec.md  # Living master doc — not per-protocol
 
   - name: extract
     description: Extract conventions, patterns, and anti-patterns
@@ -36,4 +36,7 @@ phases:
     outputs:
       - .sniper/conventions.yaml
 
+# Note: ingest protocols write to master docs (.sniper/artifacts/spec.md, .sniper/artifacts/codebase-overview.md)
+# rather than per-protocol directories (.sniper/artifacts/{protocol_id}/). A meta.yaml and registry entry
+# are still created by /sniper-flow, but the artifact directory may be empty.
 auto_retro: false

package/protocols/patch.yaml

@@ -25,6 +25,6 @@ phases:
       checklist: review
       human_approval: true
     outputs:
-      - docs/review-report.md
+      - .sniper/artifacts/{protocol_id}/review-report.md
 
 auto_retro: false  # Patches are too small for retros

package/protocols/refactor.yaml

@@ -8,11 +8,12 @@ phases:
     agents:
       - analyst
     spawn_strategy: single
+    interactive_review: true  # Let user review the analysis before refactoring
     gate:
       checklist: refactor-analyze
       human_approval: false
     outputs:
-      - docs/spec.md
+      - .sniper/artifacts/{protocol_id}/plan.md  # Analysis/plan for this refactor
 
   - name: implement
     description: Apply refactoring changes
@@ -20,6 +21,7 @@ phases:
       - fullstack-dev
     spawn_strategy: single
     plan_approval: false
+    doc_sync: true  # Run doc-writer after this phase to update living docs
     gate:
       checklist: implement
       human_approval: false
@@ -36,6 +38,6 @@ phases:
       checklist: review
       human_approval: true
     outputs:
-      - docs/review-report.md
+      - .sniper/artifacts/{protocol_id}/review-report.md
 
 auto_retro: true

package/schemas/protocol-meta.schema.yaml

@@ -0,0 +1,58 @@
+$schema: "https://json-schema.org/draft/2020-12/schema"
+$id: "https://sniper.ai/schemas/protocol-meta"
+title: ProtocolMeta
+description: Metadata for a protocol run, stored at .sniper/artifacts/{protocol_id}/meta.yaml.
+type: object
+required:
+  - id
+  - protocol
+  - status
+  - started
+properties:
+  id:
+    type: string
+    pattern: "^SNPR-\\d{8}-[a-f0-9]{4}$"
+    description: Timestamp-based protocol ID (e.g., SNPR-20260307-a3f2).
+  protocol:
+    type: string
+    description: Protocol name (full, feature, patch, etc.).
+  description:
+    type: string
+    description: Human-readable description of what this protocol run does.
+  status:
+    type: string
+    enum: [in_progress, completed, failed, cancelled]
+    description: Current status of the protocol run.
+  started:
+    type: string
+    format: date-time
+    description: ISO 8601 timestamp of when the protocol started.
+  completed:
+    type: string
+    format: date-time
+    description: ISO 8601 timestamp of when the protocol completed.
+  agents:
+    type: array
+    items:
+      type: string
+    description: List of agent names used in this run.
+  token_usage:
+    type: integer
+    minimum: 0
+    description: Total tokens consumed during this run.
+  gate_results:
+    type: object
+    additionalProperties:
+      type: string
+      enum: [pass, fail]
+    description: Gate results per phase.
+  stories_count:
+    type: integer
+    minimum: 0
+    description: Number of stories created.
+  commits:
+    type: array
+    items:
+      type: string
+    description: Git commit SHAs produced during this run.
+additionalProperties: true

package/skills/sniper-flow/SKILL.md

@@ -18,226 +18,179 @@ arguments:
 
 You are the SNIPER protocol execution engine. You orchestrate agent teams through structured phases to deliver work products.
 
-## Protocol Selection
+## 1. Select Protocol
 
-If `--protocol` is specified, use it directly. Otherwise, auto-detect:
-
-1. Read `.sniper/config.yaml` for routing rules
-2. If this is a new project (no source files), use `full`
-3. If resuming (`--resume`), read the last checkpoint to determine protocol
-4. Otherwise, estimate scope:
-   - Analyze the user's request complexity
-   - `hotfix` — Critical/urgent production fix ("critical", "urgent", "production down", "hotfix")
-   - `patch` — Bug fix or small change (< 5 files likely affected)
-   - `feature` — New feature or significant enhancement (5-20 files)
-   - `full` — New project, major rework, or multi-component change (20+ files)
-   - `ingest` — User wants to understand/document an existing codebase
-   - `explore` — Exploratory analysis, understanding, or research ("what is", "how does", "analyze", "explore")
-   - `refactor` — Code improvement without new features ("refactor", "clean up", "improve", "reorganize")
-
-Announce the selected protocol and ask for confirmation before proceeding.
-
-### Trigger Table Evaluation
-
-After auto-detection, evaluate trigger tables from `.sniper/config.yaml`:
-
-1. Read `triggers` array from config
-2. Get changed files via `git diff --name-only` (or `git status` for new files)
-3. For each trigger entry, glob-match changed files against `pattern`
-4. If a trigger matches:
-   - If `protocol` is specified, it can override the auto-detected protocol
-   - If `agent` is specified, that agent is added to the phase's agent list
-5. Trigger matches are additive — they refine the selection, not replace it
-6. Log which triggers matched and what they changed
-
-## Resume Support
-
-When `--resume` is specified:
-1. Read the latest checkpoint from `.sniper/checkpoints/`
-2. Determine which phase was in progress and which agents were active
-3. Re-spawn agents that had incomplete tasks
-4. Continue from the checkpoint state
-
-## Protocol Resolution (Custom Protocols — Feature 6)
+```
+--protocol given?  → Use it directly
+--resume given?    → Read latest checkpoint from .sniper/checkpoints/, resume from that phase
+--phase given?     → Use auto-detected protocol, skip to specified phase
+Otherwise          → Auto-detect (see below), confirm with user before proceeding
+```
 
-When resolving a protocol name, check in order:
-1. `.sniper/protocols/<name>.yaml` — User-defined custom protocols take priority
-2. Core protocols from `@sniper.ai/core/protocols/<name>.yaml` — Built-in protocols
+**Auto-detection** — match user intent, no file reads needed:
+| Keywords | Protocol |
+|----------|----------|
+| "critical", "urgent", "production down", "hotfix" | `hotfix` |
+| Bug fix, small change (< 5 files) | `patch` |
+| New feature, significant enhancement | `feature` |
+| New project, major rework, multi-component | `full` |
+| Understand, document existing codebase | `ingest` |
+| "what is", "how does", "analyze", research | `explore` |
+| "refactor", "clean up", "improve", "reorganize" | `refactor` |
 
-This allows users to override built-in protocols or define entirely new ones.
+After auto-detection, check trigger tables: run `git diff --name-only` and match against `.sniper/config.yaml` `triggers` section. Trigger overrides take precedence.
 
-## Phase Execution Loop
+**Protocol resolution order:** `.sniper/protocols/<name>.yaml` (custom) → `@sniper.ai/core/protocols/<name>.yaml` (built-in).
 
-For each phase in the protocol:
+## 2. Initialize Protocol
 
-### 0. Pre-Phase Setup
+1. **Generate protocol ID:** `SNPR-YYYYMMDD-XXXX` where XXXX is a random 4-char hex suffix (e.g., `SNPR-20260307-a3f2`). No registry parsing needed.
+2. **Create artifact directory:** `mkdir -p .sniper/artifacts/{protocol_id}/`
+3. **Write metadata:** Create `.sniper/artifacts/{protocol_id}/meta.yaml` with id, protocol, description, status: in_progress, started timestamp.
+4. **Append to registry:** Add a row to `.sniper/artifacts/registry.md`. If registry doesn't exist, create it with a header row first.
 
-**Load Workspace Context (Feature 1):**
-If a workspace exists (`.sniper-workspace/` in a parent directory):
-1. Read `.sniper-workspace/config.yaml`
-2. Extract `shared.conventions` and `shared.anti_patterns`
-3. These will be injected into agent context in step 2
+## 3. Phase Execution Loop
 
-**Load Relevant Signals (Feature 8):**
-1. Read `.sniper/memory/signals/` for signal records
-2. Match signals by `affected_files` (files that will be touched in this phase) and `relevance_tags`
-3. Select top 10 most relevant signals
-4. These will be injected as "## Recent Learnings" in agent context in step 2
+For each phase in the protocol, execute these 5 steps:
 
-**Check Workspace Conflicts (Feature 5):**
-If a workspace exists:
-1. Check `.sniper-workspace/locks/` for advisory file locks
-2. If any files that this phase's agents will modify are locked by another project, flag the conflict
-3. Present conflicts to the user and wait for resolution before proceeding
-4. Acquire advisory locks for files this phase will modify
+### Setup
 
-### 1. Read Phase Configuration
-```
-Read the protocol YAML → get phase definition
-Read .sniper/config.yaml → get agent config, ownership, commands
-Read .sniper/memory/velocity.yaml → check for calibrated budget (if exists)
-```
+1. Read protocol YAML for the current phase definition
+2. Read `.sniper/config.yaml` for agent config, ownership, commands
+3. Check `.sniper/memory/velocity.yaml` for calibrated budget — use it if available, otherwise use configured budget. Log which source is used.
+4. Compose agents per [Reference: Agent Composition](#reference-agent-composition)
 
-**Velocity-Aware Budget Selection:**
-- Check `.sniper/memory/velocity.yaml` for a `calibrated_budget` for the current protocol
-- If a calibrated budget exists and differs from the configured budget, use the calibrated budget
-- Log which budget source is being used: "Using calibrated budget (X tokens)" or "Using configured budget (X tokens)"
-- The calibrated budget takes precedence over `config.routing.budgets`
-
-### 2. Compose Agents
-For each agent in the phase:
-1. Read the base agent definition from `.claude/agents/<name>.md`
-2. Check config for mixins: `config.agents.mixins.<agent-name>`
-3. If mixins exist, read each mixin from `.claude/personas/cognitive/<mixin>.md`
-4. The agent's full prompt = base definition + concatenated mixins
-
-**Load Domain Knowledge (Feature 9):**
-After composing the base agent:
-1. Check if the agent definition has a `knowledge_sources` field in its YAML frontmatter
-2. If present, read `.sniper/knowledge/manifest.yaml`
-3. For each source referenced by the agent, read the corresponding file from `.sniper/knowledge/`
-4. Truncate content to stay within `config.knowledge.max_total_tokens` (default: 50000 tokens)
-5. Append matched knowledge as `## Domain Knowledge` section in the agent's prompt
-
-**Inject Workspace Conventions (Feature 1):**
-If workspace conventions were loaded in step 0:
-1. Append shared conventions as `## Workspace Conventions` section
-2. Append anti-patterns as `## Anti-Patterns (Workspace)` section
-
-**Inject Recent Signals (Feature 8):**
-If relevant signals were loaded in step 0:
-1. Format each signal as: `- [<type>] <summary> (<affected_files>)`
-2. Append as `## Recent Learnings` section in the agent's prompt
-
-### 3. Determine Spawn Strategy
-Based on the protocol's `spawn_strategy` for this phase:
-- `single` — Use the Task tool directly (one agent, no team overhead)
-- `team` — Use TeamCreate + Task tool (multiple agents working in parallel)
-
-### 4. Spawn Agents
-For `single` spawn:
-```
-Task tool with:
-  - subagent_type: general-purpose
-  - model: from agent frontmatter or config default
-  - prompt: composed agent prompt + task assignment
-  - mode: "plan" if plan_approval is true, else "bypassPermissions"
-  - isolation: "worktree" if agent has isolation: worktree
-```
+### Execute
 
-For `team` spawn:
-```
-TeamCreate → create team for this phase
-TaskCreate → create tasks with dependencies from protocol
-Task tool → spawn each teammate with team_name
-```
+1. Determine spawn strategy from protocol phase definition (`single`, `sequential`, `parallel`, or `team`)
+2. Spawn agents per [Reference: Spawn Strategies](#reference-spawn-strategies)
+3. Monitor via TaskList — if an agent is blocked, investigate and guide via SendMessage
+4. If an agent crashes: note the failure, continue with remaining agents
+5. After all parallel agents complete: coordinate worktree merges per [Reference: Merge Coordination](#reference-merge-coordination)
 
-### 5. Monitor Progress
-- Use TaskList to monitor agent task completion
-- If an agent is blocked, investigate and provide guidance via SendMessage
-- If an agent fails, note the failure and continue with other agents
+### Checkpoint
 
-### 6. Write Checkpoint
-After all agents complete (or fail), write a checkpoint:
+Write checkpoint to `.sniper/checkpoints/{protocol_id}-{phase}-{timestamp}.yaml`:
 ```yaml
-# .sniper/checkpoints/<protocol>-<phase>-<timestamp>.yaml
 protocol: <name>
+protocol_id: <SNPR-YYYYMMDD-XXXX>
 phase: <phase>
 timestamp: <ISO 8601>
 status: completed | failed
 agents: [status per agent]
 token_usage: [phase + cumulative]
-commits: [git SHAs produced during this phase]
+commits: [git SHAs produced]
 ```
 
-**Record Git Commits (Feature 2):**
-After agents complete, capture commits for logical revert support:
-1. Run `git log --oneline <start-sha>..HEAD` to find new commits since the phase started
-2. Record each commit's SHA, message, and the agent that produced it
-3. Include the `commits` array in the checkpoint YAML
+Update `.sniper/live-status.yaml` with current phase, agent statuses, and cost percentage.
+
+### Gate
 
-### 7. Run Gate
-Trigger the gate-reviewer for this phase:
-1. Write `.sniper/pending-gate.yaml` with the phase name and checklist reference
-2. Spawn gate-reviewer agent (or let the Stop hook trigger it)
-3. Read the gate result from `.sniper/gates/`
+1. Write `.sniper/pending-gate.yaml` with phase name and checklist reference
+2. Spawn gate-reviewer agent with the `{protocol_id}` for path resolution
+3. Read gate result from `.sniper/gates/`
+4. **If phase has `interactive_review: true`:** present artifacts for review per [Reference: Interactive Review](#reference-interactive-review). User must explicitly approve before advancing.
+5. **Gate pass + `human_approval: false`:** advance
+6. **Gate pass + `human_approval: true` + not already approved via interactive review:** present results, wait for approval
+7. **Gate pass + `human_approval: true` + already approved via interactive review:** advance (don't ask twice)
+8. **Gate fail:** identify blocking failures, reassign to appropriate agents, re-run gate. After 3 failures: escalate to user.
 
-### 8. Process Gate Result
-- If gate passes AND `human_approval: false` → advance to next phase
-- If gate passes AND `human_approval: true` → present results to user, wait for approval
-- If gate fails → identify blocking failures, reassign to appropriate agents, re-run gate
+### Advance
 
-### 9. Advance Phase
-Move to the next phase in the protocol. If this was the last phase, complete the protocol.
+1. If phase has `doc_sync: true`: spawn `doc-writer` agent to update `CLAUDE.md`, `README.md`, and `docs/architecture.md` based on the git diff from this phase. Use `Edit` for surgical updates.
+2. Move to next phase. If this was the last phase, go to [Protocol Completion](#4-protocol-completion).
 
-## Protocol Completion
+## 4. Protocol Completion
 
-When all phases complete:
 1. Write final checkpoint
 2. Update `.sniper/live-status.yaml` with `status: completed`
-3. If `auto_retro: true` in the protocol, trigger retro-analyst
-4. Present summary to user: phases completed, gate results, token usage
+3. Update `.sniper/artifacts/{protocol_id}/meta.yaml` with final status, token usage, commits, agents used
+4. Update `.sniper/artifacts/registry.md` entry from `in_progress` to `completed`
+5. Present summary: phases completed, gate results, token usage
+6. If `auto_retro: true` in protocol: spawn `retro-analyst` as background task (see [Reference: Retrospective](#reference-retrospective))
 
 ## Cost Tracking
 
-Throughout execution:
-1. Maintain `.sniper/cost.yaml` with token usage per phase and agent
-2. At each checkpoint, check usage against budget thresholds:
-   - `warn_threshold` — Log a warning but continue
-   - `soft_cap` — Pause and ask user whether to continue
-   - `hard_cap` — Stop execution, save checkpoint for potential resume
-3. Read thresholds from `.sniper/config.yaml` cost section
-
-## Merge Coordination
-
-For agents working in worktrees:
-1. After all implementation agents complete, attempt to merge each worktree
-2. If merge conflicts occur:
-   - Identify conflicting files
-   - Assign conflict resolution to the agent who owns the conflicting files
-   - Re-run tests after resolution
-3. The orchestrator coordinates merges — agents never merge their own worktrees
-
-## Live Status Updates
-
-Keep `.sniper/live-status.yaml` current:
-- Update `current_phase` and agent statuses as work progresses
-- Update `cost.percent` at checkpoints
-- Set `next_action` to a human-readable description of what's happening
+Maintain `.sniper/cost.yaml` throughout execution. At each checkpoint:
+- `warn_threshold` → log warning, continue
+- `soft_cap` → pause, ask user whether to continue
+- `hard_cap` → checkpoint and stop gracefully
 
-## Error Handling
-
-- If an agent crashes, note the failure and checkpoint state
-- If a gate fails 3 times, escalate to the user with a summary of failures
-- If cost exceeds hard cap, save checkpoint and stop gracefully
-- Never lose work — always checkpoint before stopping
+Read thresholds from `.sniper/config.yaml` cost section.
 
 ## Rules
 
-- ALWAYS read `.sniper/config.yaml` before spawning any agent
+- ALWAYS generate a protocol ID and create `.sniper/artifacts/{protocol_id}/` before spawning any agent
 - ALWAYS checkpoint between phases
 - ALWAYS respect token budgets
+- ALWAYS present the plan for interactive review when `interactive_review: true`
 - NEVER skip a gate — every phase transition goes through its gate
 - NEVER advance past a failed blocking gate check
 - NEVER implement code yourself — delegate all work to agents
 - When `human_approval` is required, present clear options and wait
+
+---
+
+## Reference: Agent Composition
+
+For each agent in the phase, build the full prompt by layering these sources. Each layer is optional except the base.
+
+| Layer | Source | If missing |
+|-------|--------|------------|
+| 1. Base agent | `.claude/agents/<name>.md` | FATAL — abort phase |
+| 2. Mixins | `.claude/personas/cognitive/<mixin>.md` (from `config.agents.mixins.<agent>`) | WARN — skip mixin, continue |
+| 3. Domain knowledge | `.sniper/knowledge/manifest.yaml` → referenced files (from agent's `knowledge_sources` frontmatter) | SKIP — no knowledge section |
+| 4. Workspace conventions | `.sniper-workspace/config.yaml` → `shared.conventions` and `shared.anti_patterns` | SKIP — no workspace section |
+| 5. Signals | `.sniper/memory/signals/` → top 10 most relevant by `affected_files` and `relevance_tags` | SKIP — no signals section |
+
+The composed prompt = base definition + concatenated mixin content + `## Domain Knowledge` section + `## Workspace Conventions` section + `## Anti-Patterns (Workspace)` section + `## Recent Learnings` section (formatted as `- [<type>] <summary> (<affected_files>)`).
+
+Replace all `{protocol_id}` placeholders in the composed prompt with the actual protocol ID.
+
+Truncate domain knowledge content to stay within `config.knowledge.max_total_tokens` (default: 50000 tokens).
+
+## Reference: Spawn Strategies
+
+**`single`** — One agent via Task tool. No team overhead.
+```
+Task tool: prompt = composed agent prompt + task assignment
+mode: "plan" if plan_approval is true, else "bypassPermissions"
+isolation: "worktree" if agent has isolation: worktree
+```
+
+**`sequential`** — Agents run one-after-another via Task tool. Output from each feeds into the next as context.
+
+**`parallel`** — Agents run concurrently via Task tool with `run_in_background: true`. Each agent works in its own worktree. Wait for all to complete.
+
+**`team`** — Full Agent Team via TeamCreate + shared task list + messaging. Use for large work requiring inter-agent coordination during execution.
+```
+TeamCreate → create team for this phase
+TaskCreate → create tasks with dependencies from protocol
+Task tool → spawn each teammate with team_name
+```
+
+## Reference: Merge Coordination
+
+For agents working in worktrees (after all implementation agents complete):
+1. Attempt to merge each worktree
+2. If merge conflicts: identify conflicting files, assign resolution to the file owner, re-run tests after resolution
+3. The orchestrator coordinates merges — agents never merge their own worktrees
+
+## Reference: Interactive Review
+
+When a phase has `interactive_review: true`:
+
+1. Read produced artifacts from `.sniper/artifacts/{protocol_id}/` (e.g., `plan.md`, `prd.md`, `stories/`)
+2. Present a structured summary: key architectural decisions, component overview, story count, open questions
+3. Offer options:
+   - **Approve** — continue to next phase
+   - **Request changes** — describe changes (architect/PM will revise, then re-present)
+   - **Edit directly** — user modifies plan files, says "done", re-validate via gate
+4. Only advance after explicit user approval
+
+## Reference: Retrospective
+
+When `auto_retro: true`, after protocol completion:
+1. Spawn `retro-analyst` as a background Task with: protocol ID, checkpoint history, gate results, cost data
+2. The retro-analyst writes a report to `.sniper/retros/{protocol_id}.yaml`, updates `.sniper/memory/velocity.yaml` with execution metrics, and calculates calibrated budgets if 5+ data points exist
+3. Runs in background — user doesn't wait for it

package/skills/sniper-init/SKILL.md

@@ -76,7 +76,6 @@ Create the following directory structure:
 .claude/
   agents/                  ← Copied from @sniper.ai/core/agents/
   settings.json            ← Merge hooks from @sniper.ai/core/hooks/
-docs/
 CLAUDE.md                  ← Generated from template
 ```
 

package/templates/checkpoint.yaml

@@ -16,7 +16,7 @@ gate_result: null  # null if gate not yet run
 #   blocking_failures: 0
 
 artifacts_produced: []
-# - path: docs/spec.md
+# - path: .sniper/artifacts/spec.md
 #   status: draft | complete
 
 token_usage:

package/templates/custom-protocol.yaml

@@ -49,7 +49,7 @@ phases:
     # outputs (optional): Expected artifacts this phase produces.
     # Used for tracking and checkpoint reporting.
     outputs:
-      - docs/design.md
+      - .sniper/artifacts/{protocol_id}/design.md
 
   # ── Phase 2: Implement ─────────────────────────────────────
   - name: implement
@@ -91,7 +91,7 @@ phases:
       human_approval: true
 
     outputs:
-      - docs/review-report.md
+      - .sniper/artifacts/{protocol_id}/review-report.md
 
 # auto_retro (optional, default: false): Whether to run the retro-analyst
 # after protocol completion to record velocity metrics.

package/templates/registry.md

@@ -0,0 +1,4 @@
+# Protocol Registry
+
+| ID | Protocol | Description | Status | Date | Artifacts |
+|----|----------|-------------|--------|------|-----------|

package/skills/sniper-flow-headless/SKILL.md

@@ -1,105 +0,0 @@
----
-name: sniper-flow-headless
-description: Execute a SNIPER protocol non-interactively for CI/CD environments
-arguments:
-  - name: protocol
-    description: Protocol to run (full, feature, patch, ingest, explore, refactor, hotfix)
-    required: true
-  - name: output
-    description: Output format (json, yaml, text)
-    required: false
-  - name: auto-approve
-    description: Auto-approve all gates
-    required: false
-    type: boolean
-  - name: timeout
-    description: Timeout in minutes
-    required: false
----
-
-# /sniper-flow-headless
-
-You are the SNIPER headless protocol execution engine. You run protocols non-interactively, suitable for CI/CD pipelines, automated workflows, and scripted invocations.
-
-This skill follows the same Phase Execution Loop as `/sniper-flow` but with all interactive decisions resolved automatically. No prompts, no confirmations — deterministic execution from start to finish.
-
-## Key Differences from /sniper-flow
-
-- **No interactive prompts** — protocol must be specified via `--protocol`, never auto-detected interactively
-- **Automatic gate approval** — when `--auto-approve` is set, gates pass without human review
-- **Structured output** — results are written to stdout in the requested `--output` format (json, yaml, or text)
-- **Exit codes** — process exits with a code indicating the result:
-  - `0` — Success: all phases and gates passed
-  - `1` — Gate failure: a blocking gate check failed
-  - `2` — Cost exceeded: token usage hit the hard cap
-  - `3` — Timeout: execution exceeded the `--timeout` duration
-  - `4` — Config error: invalid config, missing protocol, or initialization failure
-
-## Execution
-
-### 1. Validate Configuration
-
-```
-Read .sniper/config.yaml
-Validate the specified --protocol exists (built-in or custom)
-If config is missing or invalid, exit with code 4
-```
-
-### 2. Phase Execution Loop
-
-For each phase in the protocol, execute the same steps as `/sniper-flow`:
-
-1. **Read Phase Configuration** — load protocol YAML, config, and velocity data
-2. **Compose Agents** — assemble base agent definitions with configured mixins
-3. **Determine Spawn Strategy** — `single` or `team` per the protocol phase definition
-4. **Spawn Agents** — delegate work via Task tool or TeamCreate
-5. **Monitor Progress** — track agent completion via TaskList; no interactive guidance
-6. **Write Checkpoint** — persist phase state to `.sniper/checkpoints/`
-7. **Run Gate** — spawn gate-reviewer for the phase
-8. **Process Gate Result**:
-   - If `--auto-approve` is set: gate always passes, log the result
-   - If `--auto-approve` is NOT set: gate must pass on its own merits; failure exits with code 1
-9. **Advance Phase** — proceed to the next phase or complete
-
-### 3. Timeout Enforcement
-
-- Track elapsed wall-clock time from execution start
-- If `--timeout` minutes is exceeded at any checkpoint boundary, save checkpoint and exit with code 3
-- Timeout is checked between phases, not mid-phase
-
-### 4. Cost Enforcement
-
-- Follow the same cost tracking as `/sniper-flow`
-- At `warn_threshold`: log warning to stderr, continue
-- At `soft_cap`: in headless mode, treat as hard cap (no interactive prompt available)
-- At `hard_cap`: save checkpoint, exit with code 2
-
-### 5. Output
-
-On completion (success or failure), write structured output to stdout:
-
-```yaml
-protocol: <name>
-status: success | gate_fail | cost_exceeded | timeout | config_error
-phases:
-  - name: <phase>
-    status: completed | failed | skipped
-    gate_result: passed | failed | auto_approved
-    tokens: <number>
-total_tokens: <number>
-duration_seconds: <number>
-errors: []
-```
-
-Format this structure according to `--output`: JSON (default in CI), YAML, or plain text table.
-
-## Rules
-
-- ALWAYS read `.sniper/config.yaml` before spawning any agent
-- ALWAYS checkpoint between phases
-- ALWAYS respect token budgets — soft cap is treated as hard cap in headless mode
-- ALWAYS exit with the correct exit code
-- NEVER prompt for user input — all decisions must be automatic
-- NEVER skip a gate — evaluate every gate, auto-approve only if `--auto-approve` is set
-- NEVER implement code yourself — delegate all work to agents
-- Output structured results to stdout; diagnostics and logs go to stderr