@sniper.ai/core 3.0.0 → 3.1.0

package/README.md

@@ -27,7 +27,7 @@ npm install @sniper.ai/core
 ├── agents/             # Agent definitions (11 agents)
 ├── personas/
 │   └── cognitive/      # Cognitive mixins (3 mixins)
-├── skills/             # Slash command definitions (5 skills)
+├── skills/             # Slash command definitions (4 skills)
 ├── protocols/          # Protocol state machines (7 protocols)
 ├── templates/          # Artifact templates (14 templates)
 ├── checklists/         # Quality gate checklists (9 checklists)
@@ -83,12 +83,11 @@ Domain-specific knowledge is provided separately by domain packs (e.g., `@sniper
 
 ## Skills
 
-5 slash commands available in Claude Code:
+4 slash commands available in Claude Code:
 
 | Command | Description |
 |---------|-------------|
 | `/sniper-flow` | Execute a SNIPER protocol (auto-detects scope or use `--protocol <name>`) |
-| `/sniper-flow-headless` | Execute a protocol non-interactively for CI/CD environments |
 | `/sniper-init` | Initialize SNIPER v3 in a new or existing project |
 | `/sniper-review` | Manually trigger a review gate for the current phase |
 | `/sniper-status` | Show current protocol progress and cost |

package/agents/analyst.md

@@ -1,6 +1,5 @@
 ---
 write_scope:
-  - "docs/"
   - ".sniper/"
 ---
 
@@ -18,8 +17,8 @@ You are a SNIPER analyst agent. You research, analyze, and produce discovery art
 
 ## Output Artifacts
 
-- `docs/spec.md` — Discovery specification (use `spec.md` template)
-- `docs/codebase-overview.md` — Architecture and convention analysis (use `codebase-overview.md` template)
+- `.sniper/artifacts/spec.md` — Discovery specification (use `spec.md` template)
+- `.sniper/artifacts/codebase-overview.md` — Architecture and convention analysis (use `codebase-overview.md` template)
 
 ## Rules
 

package/agents/architect.md

@@ -1,6 +1,6 @@
 ---
 write_scope:
-  - "docs/"
+  - ".sniper/artifacts/"
 ---
 
 # Architect
@@ -17,7 +17,9 @@ You are a SNIPER architect agent. You design system architecture and produce tec
 
 ## Output Artifacts
 
-- `docs/architecture.md` — Architecture document (use `architecture.md` template, 4000 token budget)
+- `.sniper/artifacts/{protocol_id}/plan.md` — Architecture plan for this protocol run (use `architecture.md` template, 4000 token budget)
+  - The `{protocol_id}` (e.g., `SNPR-20260307-a3f2`) is provided by the orchestrator when spawning you
+  - This is a per-run snapshot; the master `docs/architecture.md` is updated separately by the doc-writer
 
 ## Decision Framework
 

package/agents/code-reviewer.md

@@ -1,6 +1,6 @@
 ---
 write_scope:
-  - "docs/"
+  - ".sniper/artifacts/"
 ---
 
 # Code Reviewer
@@ -56,8 +56,8 @@ Risk categories to evaluate:
 
 After completing the code review, reconcile the spec with the implementation:
 
-1. Compare `docs/spec.md` requirements against actual implementation
-2. If implementation differs from spec (intentionally or due to discoveries during implementation), update `docs/spec.md` to reflect reality
+1. Compare `.sniper/artifacts/spec.md` requirements against actual implementation
+2. If implementation differs from spec (intentionally or due to discoveries during implementation), update `.sniper/artifacts/spec.md` to reflect reality
 3. Add a "Last reconciled: YYYY-MM-DD" line at the bottom of the spec
 4. This is a reconciliation (spec tracks reality), NOT a compliance check
 5. Only update if there are meaningful differences; don't touch the spec if it's already accurate
@@ -68,5 +68,5 @@ After completing the code review, reconcile the spec with the implementation:
 - Cite specific file paths and line numbers for every finding
 - If the implementation matches the spec and passes all checks, say so clearly
 - Do NOT nitpick style when conventions aren't established
-- Write the review report to `docs/review-report.md`
-- Only modify `docs/spec.md` during spec reconciliation — never modify project source code
+- Write the review report to `.sniper/artifacts/{protocol_id}/review-report.md` (the `{protocol_id}` is provided by the orchestrator)
+- Only modify master `.sniper/artifacts/spec.md` during spec reconciliation — never modify project source code

package/agents/doc-writer.md

@@ -0,0 +1,60 @@
+---
+write_scope:
+  - "CLAUDE.md"
+  - "README.md"
+  - "docs/architecture.md"
+---
+
+# Doc Writer
+
+You are a SNIPER doc-writer agent. You perform incremental documentation updates after implementation phases to keep living project docs in sync with the codebase.
+
+## Responsibilities
+
+1. **Incremental Doc Sync** — Update project documentation to reflect code changes from the current phase
+2. **Minimal Changes** — Only modify sections affected by the implementation; preserve all user-written content
+
+## Execution Process
+
+1. Read the git diff of all changes made during the current phase:
+   - Use `git diff <start-sha>..HEAD` (the orchestrator provides the start SHA)
+   - If no start SHA, use `git diff HEAD~<commit-count>..HEAD`
+2. Read the current state of:
+   - `CLAUDE.md`
+   - `README.md`
+   - `docs/architecture.md` (if it exists)
+3. Analyze the diff for:
+   - New files or directories that should be documented
+   - New patterns or conventions introduced
+   - New commands, scripts, or setup steps
+   - Architectural changes (new components, changed data flow, new dependencies)
+4. Apply updates using `Edit` (never `Write`) to make surgical changes
+
+## Update Guidelines
+
+**CLAUDE.md:**
+- Add new key files/directories to the project structure section
+- Add new commands to the commands section
+- Add new conventions or patterns discovered in the implementation
+- Do NOT rewrite existing sections — only append or update specific entries
+
+**README.md:**
+- Add new features to the features section (if one exists)
+- Add new setup steps or dependencies
+- Update usage examples if the API changed
+- Do NOT rewrite the project description or introduction
+
+**docs/architecture.md:**
+- Update component descriptions if new components were added
+- Update data flow diagrams if the flow changed
+- Add new integration points or external dependencies
+- Do NOT restructure the document
+
+## Rules
+
+- ALWAYS use `Edit` (not `Write`) to preserve user-written content
+- NEVER rewrite entire files — make targeted, minimal edits
+- NEVER add documentation for unchanged code
+- NEVER modify source code files — only documentation files
+- If a doc file doesn't exist, skip it (don't create it)
+- Keep updates concise — match the existing style and tone of each document

package/agents/gate-reviewer.md

@@ -5,7 +5,7 @@ write_scope:
 
 # Gate Reviewer
 
-You are a SNIPER gate reviewer agent. You run automated checks at phase boundaries and produce gate results. You are triggered automatically by hooks.
+You are a SNIPER gate reviewer agent. You run automated checks at phase boundaries and produce gate results.
 
 ## Responsibilities
 
@@ -13,9 +13,19 @@ You are a SNIPER gate reviewer agent. You run automated checks at phase boundari
 2. **Result Recording** — Write a gate result YAML to `.sniper/gates/`
 3. **Pass/Fail Decision** — A gate passes only if ALL `blocking: true` checks pass
 
-## Execution Process
+## Protocol ID Resolution
+
+The orchestrator provides the current `protocol_id` (e.g., `SNPR-20260307-a3f2`) when spawning you. Before executing checks:
 
 1. Read the checklist YAML for the current phase from `.sniper/checklists/`
+2. **Replace all `{protocol_id}` placeholders** in check paths **and** commands with the actual protocol ID
+   - Check path example: `grep:.sniper/artifacts/{protocol_id}/plan.md:"## Context"` becomes `grep:.sniper/artifacts/SNPR-20260307-a3f2/plan.md:"## Context"`
+   - Command example: `test $(wc -l < .sniper/artifacts/{protocol_id}/plan.md) -ge 20` becomes `test $(wc -l < .sniper/artifacts/SNPR-20260307-a3f2/plan.md) -ge 20`
+3. If no `protocol_id` is provided, check `.sniper/live-status.yaml` for the active protocol's ID
+
+## Execution Process
+
+1. Load and resolve the checklist (see Protocol ID Resolution above)
 2. For each check:
    - If `command` is specified, run it via Bash and check exit code
    - If `check` is specified, evaluate the condition (file existence, grep match, etc.)

package/agents/product-manager.md

@@ -1,6 +1,6 @@
 ---
 write_scope:
-  - "docs/"
+  - ".sniper/artifacts/"
 ---
 
 # Product Manager
@@ -26,8 +26,10 @@ Use the EARS (Easy Approach to Requirements Syntax) patterns:
 
 ## Output Artifacts
 
-- `docs/prd.md` — Product requirements (use `spec.md` template adapted for PRD)
-- `docs/stories/*.md` — Individual stories (use `story.md` template, 1500 token budget each)
+- `.sniper/artifacts/{protocol_id}/prd.md` — Product requirements for this protocol run (use `spec.md` template adapted for PRD)
+- `.sniper/artifacts/{protocol_id}/stories/*.md` — Individual stories (use `story.md` template, 1500 token budget each)
+  - The `{protocol_id}` (e.g., `SNPR-20260307-a3f2`) is provided by the orchestrator when spawning you
+  - These are per-run snapshots that preserve the plan history
 
 ## Rules
 

package/agents/retro-analyst.md

@@ -16,13 +16,19 @@ You are a SNIPER retro analyst agent. You run automated retrospectives after pro
 5. **Retro Report** — Write structured retro to `.sniper/retros/`
 6. **Velocity Tracking** — Record execution metrics to `.sniper/memory/velocity.yaml` for budget calibration
 
+## Invocation
+
+You are automatically spawned by `/sniper-flow` at protocol completion when `auto_retro: true`.
+The orchestrator provides you with the `protocol_id` (e.g., `SNPR-20260307-a3f2`) and protocol type.
+
 ## Analysis Process
 
-1. Read `.sniper/checkpoints/` for the completed protocol's checkpoint history
+1. Read `.sniper/checkpoints/{protocol_id}-*` for the completed protocol's checkpoint history
 2. Read `.sniper/gates/` for gate results (pass/fail patterns)
 3. Read `.sniper/cost.yaml` for token usage data
-4. Analyze: What took the most tokens? Which gates failed first? Were there re-runs?
-5. Write retro report
+4. Read `.sniper/artifacts/{protocol_id}/meta.yaml` for protocol metadata
+5. Analyze: What took the most tokens? Which gates failed first? Were there re-runs?
+6. Write retro report to `.sniper/retros/{protocol_id}.yaml`
 
 ## Retro Report Schema
 

package/checklists/discover.yaml

@@ -4,20 +4,20 @@ description: Discovery phase quality gate
 checks:
   - id: spec_produced
     description: Discovery spec exists
-    check: file:docs/spec.md
+    check: file:.sniper/artifacts/spec.md
     blocking: true
 
   - id: scope_defined
     description: Spec defines in-scope requirements
-    check: grep:docs/spec.md:"## Requirements"
+    check: grep:.sniper/artifacts/spec.md:"## Requirements"
     blocking: true
 
   - id: out_of_scope_explicit
     description: Spec explicitly lists out-of-scope items
-    check: grep:docs/spec.md:"## Out of Scope"
+    check: grep:.sniper/artifacts/spec.md:"## Out of Scope"
     blocking: false
 
   - id: codebase_overview
     description: Codebase overview exists (if ingesting existing project)
-    check: file:docs/codebase-overview.md
+    check: file:.sniper/artifacts/codebase-overview.md
     blocking: false

package/checklists/ingest-document.yaml

@@ -4,15 +4,15 @@ description: Ingest document phase quality gate — verifies spec was produced f
 checks:
   - id: spec_produced
     description: Discovery spec exists
-    check: file:docs/spec.md
+    check: file:.sniper/artifacts/spec.md
     blocking: true
 
   - id: scope_defined
     description: Spec defines in-scope requirements
-    check: grep:docs/spec.md:"## Requirements"
+    check: grep:.sniper/artifacts/spec.md:"## Requirements"
     blocking: true
 
   - id: out_of_scope_explicit
     description: Spec explicitly lists out-of-scope items
-    check: grep:docs/spec.md:"## Out of Scope"
+    check: grep:.sniper/artifacts/spec.md:"## Out of Scope"
     blocking: false

package/checklists/ingest-scan.yaml

@@ -4,15 +4,15 @@ description: Ingest scan phase quality gate — verifies codebase overview was p
 checks:
   - id: codebase_overview_exists
     description: Codebase overview document exists
-    check: file:docs/codebase-overview.md
+    check: file:.sniper/artifacts/codebase-overview.md
     blocking: true
 
   - id: overview_has_structure
     description: Overview includes project structure section
-    check: grep:docs/codebase-overview.md:"## "
+    check: grep:.sniper/artifacts/codebase-overview.md:"## "
     blocking: false
 
   - id: overview_nonempty
     description: Overview is not a stub (at least 50 lines)
-    command: "test $(wc -l < docs/codebase-overview.md) -ge 50"
+    command: "test $(wc -l < .sniper/artifacts/codebase-overview.md) -ge 50"
     blocking: false

package/checklists/multi-faceted-review.yaml

@@ -1,21 +1,22 @@
 name: multi-faceted-review
 description: Multi-dimensional review gate — scope, standards, and risk
+# Note: {protocol_id} is resolved at gate-review time from the active checkpoint
 
 checks:
   # Scope Validation — does the implementation match requirements?
   - id: scope_spec_match
     description: Implementation addresses all spec requirements
-    check: file:docs/spec.md
+    check: file:.sniper/artifacts/spec.md
     blocking: true
 
   - id: scope_acceptance_criteria
     description: All acceptance criteria from stories are addressed
-    check: "grep:docs/stories/:shall"
+    check: "grep:.sniper/artifacts/{protocol_id}/stories/:shall"
     blocking: true
 
   - id: scope_no_creep
     description: No undocumented features added beyond spec
-    check: file:docs/review-report.md
+    check: file:.sniper/artifacts/{protocol_id}/review-report.md
     blocking: false
 
   # Standards Enforcement — does the code follow conventions?
@@ -37,20 +38,20 @@ checks:
   # Risk Scoring — are there security, performance, or reliability risks?
   - id: risk_security
     description: No OWASP Top 10 vulnerabilities detected
-    check: 'grep:docs/review-report.md:"## Security"'
+    check: 'grep:.sniper/artifacts/{protocol_id}/review-report.md:"## Security"'
     blocking: true
 
   - id: risk_performance
     description: No obvious performance regressions
-    check: 'grep:docs/review-report.md:"## Performance"'
+    check: 'grep:.sniper/artifacts/{protocol_id}/review-report.md:"## Performance"'
     blocking: false
 
   - id: risk_error_handling
     description: Error cases are handled gracefully
-    check: 'grep:docs/review-report.md:"## Error Handling"'
+    check: 'grep:.sniper/artifacts/{protocol_id}/review-report.md:"## Error Handling"'
     blocking: false
 
   - id: risk_data_integrity
     description: No data loss or corruption risks
-    check: 'grep:docs/review-report.md:"## Data Integrity"'
+    check: 'grep:.sniper/artifacts/{protocol_id}/review-report.md:"## Data Integrity"'
     blocking: true

package/checklists/plan.yaml

@@ -1,36 +1,36 @@
 name: plan
 description: Planning phase quality gate
+# Note: {protocol_id} is resolved at gate-review time from the active checkpoint
 
 checks:
   - id: has_context_section
-    check: grep:docs/architecture.md:"## Context"
+    check: grep:.sniper/artifacts/{protocol_id}/plan.md:"## Context"
     blocking: true
-    description: Architecture doc includes Context section
+    description: Architecture plan includes Context section
   - id: has_decisions_section
-    check: grep:docs/architecture.md:"## Decisions"
+    check: grep:.sniper/artifacts/{protocol_id}/plan.md:"## Decisions"
     blocking: true
-    description: Architecture doc includes Decisions section
+    description: Architecture plan includes Decisions section
   - id: has_components_section
-    check: grep:docs/architecture.md:"## Components"
+    check: grep:.sniper/artifacts/{protocol_id}/plan.md:"## Components"
     blocking: true
-    description: Architecture doc includes Components section
+    description: Architecture plan includes Components section
   - id: has_data_model_section
-    check: grep:docs/architecture.md:"## Data Model"
+    check: grep:.sniper/artifacts/{protocol_id}/plan.md:"## Data Model"
     blocking: true
-    description: Architecture doc includes Data Model section
+    description: Architecture plan includes Data Model section
 
   - id: ears_criteria
     description: All stories have EARS acceptance criteria
-    check: grep:docs/stories/:"shall"
+    check: grep:.sniper/artifacts/{protocol_id}/stories/:"shall"
     blocking: true
 
   - id: open_questions
     description: No unresolved open questions remain
-    # '|' separates alternation patterns (grep -E style)
-    check: "!grep:docs/:\\*\\*TBD\\*\\*|\\*\\*TODO\\*\\*|\\*\\*OPEN\\*\\*"
+    check: "!grep:.sniper/artifacts/{protocol_id}/:\\*\\*TBD\\*\\*|\\*\\*TODO\\*\\*|\\*\\*OPEN\\*\\*"
     blocking: false
 
   - id: token_budget
-    description: Architecture doc within character budget (~4000 tokens ≈ 16000 chars)
-    check: wc:docs/architecture.md:<16000
+    description: Architecture plan within character budget (~4000 tokens = 16000 chars)
+    check: wc:.sniper/artifacts/{protocol_id}/plan.md:<16000
     blocking: false

package/checklists/refactor-analyze.yaml

@@ -1,18 +1,19 @@
 name: refactor-analyze
 description: Refactor analysis phase quality gate — verifies analysis artifacts
+# Note: {protocol_id} is resolved at gate-review time from the active checkpoint
 
 checks:
   - id: analysis_produced
-    description: Refactoring analysis spec exists
-    check: file:docs/spec.md
+    description: Refactoring analysis plan exists
+    check: file:.sniper/artifacts/{protocol_id}/plan.md
     blocking: true
 
   - id: refactor_targets_identified
     description: Analysis identifies specific refactoring targets
-    check: grep:docs/spec.md:"## "
+    check: grep:.sniper/artifacts/{protocol_id}/plan.md:"## "
     blocking: false
 
   - id: analysis_nonempty
     description: Analysis is not a stub (at least 20 lines)
-    command: "test $(wc -l < docs/spec.md) -ge 20"
+    command: "test $(wc -l < .sniper/artifacts/{protocol_id}/plan.md) -ge 20"
     blocking: false

package/checklists/review.yaml

@@ -1,5 +1,6 @@
 name: review
 description: Review phase quality gate
+# Note: {protocol_id} is resolved at gate-review time from the active checkpoint
 
 checks:
   - id: gate_checks_pass
@@ -9,7 +10,7 @@ checks:
 
   - id: spec_reconciliation
     description: Review report confirms spec compliance
-    check: file:docs/review-report.md
+    check: file:.sniper/artifacts/{protocol_id}/review-report.md
     blocking: true
 
   - id: no_regressions
@@ -19,10 +20,10 @@ checks:
 
   - id: no_blocking_findings
     description: No blocking findings in review report
-    check: "!grep:docs/review-report.md:### Blocking"
+    check: "!grep:.sniper/artifacts/{protocol_id}/review-report.md:### Blocking"
     blocking: true
 
   - id: spec_reconciled
     description: Spec has been reconciled with implementation
-    check: "grep:docs/spec.md:Last reconciled:"
+    check: "grep:.sniper/artifacts/spec.md:Last reconciled:"
     blocking: false

package/hooks/settings-hooks.json

@@ -2,29 +2,38 @@
   "hooks": {
     "PreToolUse": [
       {
-        "matcher": "Write",
-        "description": "Enforce lead orchestrator write scope restriction",
-        "command": "if echo \"$CLAUDE_TOOL_INPUT\" | grep -q '\"file_path\"' && ! echo \"$CLAUDE_TOOL_INPUT\" | grep -q '.sniper/'; then echo 'BLOCK: Lead orchestrator can only write to .sniper/ directory'; exit 2; fi",
-        "agent": "lead-orchestrator"
+        "matcher": { "tools": ["Write"] },
+        "hooks": [
+          {
+            "type": "command",
+            "description": "Enforce lead orchestrator write scope restriction",
+            "command": "if echo \"$CLAUDE_TOOL_INPUT\" | grep -q '\"file_path\"' && ! echo \"$CLAUDE_TOOL_INPUT\" | grep -q '.sniper/'; then echo 'BLOCK: Lead orchestrator can only write to .sniper/ directory' >&2; exit 2; fi"
+          }
+        ]
       }
     ],
     "PostToolUse": [
       {
-        "matcher": "Bash",
-        "description": "Self-healing CI: detect test/lint failures and instruct agent to fix",
-        "command": "if echo \"$CLAUDE_TOOL_OUTPUT\" | grep -qiE '(FAIL|FAILED|ERROR|AssertionError|SyntaxError|TypeError|ReferenceError|lint.*error|eslint.*error|tsc.*error)'; then echo 'WARN: Test or lint failure detected. Fix the failing test/lint issue before proceeding to the next task.'; fi"
+        "matcher": { "tools": ["Bash"] },
+        "hooks": [
+          {
+            "type": "command",
+            "description": "Self-healing CI: detect test/lint failures and instruct agent to fix",
+            "command": "if echo \"$CLAUDE_TOOL_OUTPUT\" | grep -qiE '(FAIL|FAILED|ERROR|AssertionError|SyntaxError|TypeError|ReferenceError|lint.*error|eslint.*error|tsc.*error)'; then echo 'WARN: Test or lint failure detected. Fix the failing test/lint issue before proceeding to the next task.'; fi"
+          }
+        ]
       }
     ],
     "Stop": [
       {
-        "description": "Run gate reviewer at phase boundaries",
-        "command": "if [ -f .sniper/pending-gate.yaml ]; then echo 'Gate review pending — spawning gate-reviewer agent'; fi",
-        "agent": "gate-reviewer"
-      },
-      {
-        "description": "Run retro analyst after protocol completion",
-        "command": "if [ -f .sniper/protocol-complete.yaml ]; then echo 'Protocol complete — spawning retro-analyst agent'; fi",
-        "agent": "retro-analyst"
+        "matcher": {},
+        "hooks": [
+          {
+            "type": "command",
+            "description": "Run gate reviewer at phase boundaries",
+            "command": "if [ -f .sniper/pending-gate.yaml ]; then echo 'Gate review pending — spawning gate-reviewer agent'; fi"
+          }
+        ]
       }
     ]
   }

package/hooks/signal-hooks.json

@@ -2,9 +2,14 @@
   "hooks": {
     "PostToolUse": [
       {
-        "matcher": "Bash",
-        "description": "Auto-capture CI failure signals from test/lint output",
-        "command": "if echo \"$CLAUDE_TOOL_OUTPUT\" | grep -qiE '(FAIL|FAILED|ERROR|exit code [1-9])'; then SIGNAL_DIR=\".sniper/memory/signals\"; mkdir -p \"$SIGNAL_DIR\"; TS=$(node -e \"process.stdout.write(new Date().toISOString())\"); EPOCH=$(node -e \"process.stdout.write(String(Date.now()))\"); SIGNAL_FILE=\"$SIGNAL_DIR/$(echo $TS | cut -c1-10 | tr -d '-')-ci_failure-${EPOCH}.yaml\"; echo \"type: ci_failure\" > \"$SIGNAL_FILE\"; echo \"source: bash-output\" >> \"$SIGNAL_FILE\"; echo \"timestamp: ${TS}\" >> \"$SIGNAL_FILE\"; echo \"summary: CI failure detected in command output\" >> \"$SIGNAL_FILE\"; echo 'Signal captured to '\"$SIGNAL_FILE\"; fi"
+        "matcher": { "tools": ["Bash"] },
+        "hooks": [
+          {
+            "type": "command",
+            "description": "Auto-capture CI failure signals from test/lint output",
+            "command": "if echo \"$CLAUDE_TOOL_OUTPUT\" | grep -qiE '(FAIL|FAILED|ERROR|exit code [1-9])'; then SIGNAL_DIR=\".sniper/memory/signals\"; mkdir -p \"$SIGNAL_DIR\"; TS=$(node -e \"process.stdout.write(new Date().toISOString())\"); EPOCH=$(node -e \"process.stdout.write(String(Date.now()))\"); SIGNAL_FILE=\"$SIGNAL_DIR/$(echo $TS | cut -c1-10 | tr -d '-')-ci_failure-${EPOCH}.yaml\"; echo \"type: ci_failure\" > \"$SIGNAL_FILE\"; echo \"source: bash-output\" >> \"$SIGNAL_FILE\"; echo \"timestamp: ${TS}\" >> \"$SIGNAL_FILE\"; echo \"summary: CI failure detected in command output\" >> \"$SIGNAL_FILE\"; echo 'Signal captured to '\"$SIGNAL_FILE\"; fi"
+          }
+        ]
       }
     ]
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sniper.ai/core",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "SNIPER framework core — agents, skills, protocols, checklists, templates, and hooks",
   "type": "module",
   "exports": {

package/protocols/explore.yaml

@@ -12,7 +12,10 @@ phases:
       checklist: discover
       human_approval: false
     outputs:
-      - docs/spec.md
-      - docs/codebase-overview.md
+      - .sniper/artifacts/spec.md  # Living master doc — not per-protocol (explore has no versioned artifacts)
+      - .sniper/artifacts/codebase-overview.md  # Living master doc — not per-protocol
 
+# Note: explore/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  # Exploration doesn't need retros

package/protocols/feature.yaml

@@ -8,22 +8,24 @@ phases:
     agents:
       - architect
       - product-manager
-    spawn_strategy: team
+    spawn_strategy: sequential  # Architect designs first, PM writes stories from that
+    interactive_review: true  # Present plan to user for review/feedback before proceeding
     gate:
       checklist: plan
       human_approval: true
     outputs:
-      - docs/architecture.md
-      - docs/prd.md
-      - docs/stories/
+      - .sniper/artifacts/{protocol_id}/plan.md
+      - .sniper/artifacts/{protocol_id}/prd.md
+      - .sniper/artifacts/{protocol_id}/stories/
 
   - name: implement
     description: Feature implementation
     agents:
       - fullstack-dev
       - qa-engineer
-    spawn_strategy: team
+    spawn_strategy: parallel  # Multiple subagents via Task, not full TeamCreate
     plan_approval: true
+    doc_sync: true  # Run doc-writer after this phase to update living docs
     gate:
       checklist: implement
       human_approval: false
@@ -40,6 +42,6 @@ phases:
       checklist: review
       human_approval: true
     outputs:
-      - docs/review-report.md
+      - .sniper/artifacts/{protocol_id}/review-report.md
 
 auto_retro: true

package/protocols/full.yaml

@@ -12,8 +12,8 @@ phases:
       checklist: discover
       human_approval: false
     outputs:
-      - docs/spec.md
-      - docs/codebase-overview.md
+      - .sniper/artifacts/spec.md  # Living master doc
+      - .sniper/artifacts/codebase-overview.md  # Living master doc
 
   - name: plan
     description: Architecture design, PRD creation, story breakdown
@@ -21,6 +21,7 @@ phases:
       - architect
       - product-manager
     spawn_strategy: team  # Multiple agents, use TeamCreate
+    interactive_review: true  # Present plan to user for review/feedback before proceeding
     coordination:
       - between: [architect, product-manager]
         topic: Architecture must be approved before stories reference it
@@ -28,9 +29,9 @@ phases:
       checklist: plan
       human_approval: true  # Human reviews the plan before implementation
     outputs:
-      - docs/architecture.md
-      - docs/prd.md
-      - docs/stories/
+      - .sniper/artifacts/{protocol_id}/plan.md
+      - .sniper/artifacts/{protocol_id}/prd.md
+      - .sniper/artifacts/{protocol_id}/stories/
 
   - name: implement
     description: Code implementation with worktree isolation
@@ -39,6 +40,7 @@ phases:
       - qa-engineer
     spawn_strategy: team
     plan_approval: true  # Each agent must get plan approved before coding
+    doc_sync: true  # Run doc-writer after this phase to update living docs
     gate:
       checklist: implement
       human_approval: false
@@ -58,6 +60,6 @@ phases:
       multi_model_checklist: multi-faceted-review
       human_approval: true  # Human final sign-off
     outputs:
-      - docs/review-report.md
+      - .sniper/artifacts/{protocol_id}/review-report.md
 
 auto_retro: true  # Trigger retro-analyst after completion