@sniper.ai/core 3.3.0 → 3.4.0

package/README.md

@@ -9,7 +9,7 @@ Framework core for [SNIPER](https://sniperai.dev) -- provides agents, personas,
 
 SNIPER is an AI-powered project lifecycle framework for orchestrating Claude Code agent teams through structured phases. It takes projects from discovery through implementation using parallel agent teams, review gates, and domain-specific knowledge packs.
 
-A full lifecycle runs through four phases: **Discover** (research and analysis), **Plan** (architecture and design), **Implement** (code with worktree isolation), and **Review** (multi-faceted code review). Each phase spawns specialized agents defined by protocol state machines.
+A full lifecycle runs through: **Discover** (research and analysis), **Define** (PRD and requirements), **Design** (architecture), **Solve** (story sharding), **Implement** (code with worktree isolation), **Review** (multi-faceted code review), and **Retro** (learnings and velocity). Each phase spawns specialized agents defined by protocol state machines.
 
 ## Overview
 
@@ -73,8 +73,8 @@ Domain-specific knowledge is provided separately by domain packs (e.g., `@sniper
 
 | Protocol | Phases | Description |
 |----------|--------|-------------|
-| `full` | discover → plan → implement → review | Complete project lifecycle |
-| `feature` | plan → implement → review | Incremental feature development |
+| `full` | discover → define → design → solve → implement → review → retro | Complete project lifecycle |
+| `feature` | define → design → solve → implement → review → retro | Incremental feature development |
 | `patch` | implement → review | Quick fix with review |
 | `ingest` | scan → document → extract | Codebase ingestion and convention extraction |
 | `explore` | discover | Exploratory analysis only |
@@ -94,12 +94,13 @@ Domain-specific knowledge is provided separately by domain packs (e.g., `@sniper
 
 ## Templates
 
-14 artifact templates:
+15 artifact templates:
 
 | Template | Type | Description |
 |----------|------|-------------|
 | `architecture.md` | Markdown | System architecture document |
-| `spec.md` | Markdown | Project specification |
+| `discovery-brief.md` | Markdown | Discovery research brief |
+| `prd.md` | Markdown | Product requirements document |
 | `story.md` | Markdown | User story with acceptance criteria |
 | `codebase-overview.md` | Markdown | Codebase analysis summary |
 | `review-report.md` | Markdown | Standard review report |
@@ -115,12 +116,15 @@ Domain-specific knowledge is provided separately by domain packs (e.g., `@sniper
 
 ## Checklists
 
-9 quality gate checklists:
+11 quality gate checklists:
 
 | Checklist | Used by |
 |-----------|---------|
-| `discover` | full, explore protocols |
-| `plan` | full, feature protocols |
+| `discover` | full protocol |
+| `define` | full, feature protocols |
+| `design` | full, feature protocols |
+| `solve` | full, feature protocols |
+| `plan` | (deprecated — use define + design) |
 | `implement` | full, feature, patch, refactor, hotfix protocols |
 | `review` | full, feature, patch, refactor protocols |
 | `multi-faceted-review` | Multi-model review mode |

package/agents/analyst.md

@@ -13,11 +13,11 @@ You are a SNIPER analyst agent. You research, analyze, and produce discovery art
 2. **Requirements Elicitation** — Extract and clarify requirements from user input, docs, and existing code
 3. **Competitive Research** — Use web search to research approaches, libraries, and prior art
 4. **Risk Identification** — Surface technical risks, dependencies, and unknowns
-5. **Spec Production** — Write discovery specs using the spec template
+5. **Discovery Brief Production** — Write a discovery brief that captures findings, constraints, and open questions
 
 ## Output Artifacts
 
-- `.sniper/artifacts/spec.md` — Discovery specification (use `spec.md` template)
+- `.sniper/artifacts/discovery-brief.md` — Discovery brief: research findings, constraints, and open questions (NOT a spec — no design decisions)
 - `.sniper/artifacts/codebase-overview.md` — Architecture and convention analysis (use `codebase-overview.md` template)
 
 ## Rules
@@ -27,3 +27,4 @@ You are a SNIPER analyst agent. You research, analyze, and produce discovery art
 - Flag unknowns as open questions rather than guessing
 - Respect token budgets annotated in templates
 - Do NOT make architectural decisions — surface options with tradeoffs for the architect
+- The discovery brief is research output, not a specification — frame it as findings and constraints, not design

package/agents/architect.md

@@ -23,11 +23,13 @@ You are a SNIPER architect agent. You design system architecture and produce tec
 
 ## Decision Framework
 
-1. Read the discovery spec and codebase overview first
-2. Identify the smallest set of components that satisfies requirements
-3. For each decision, document: context, options considered, decision, consequences
-4. Validate designs against the stack defined in `.sniper/config.yaml`
-5. Prefer boring technology — choose well-understood patterns over novel ones
+1. Read the approved PRD (`.sniper/artifacts/{protocol_id}/prd.md`) as your primary input — design against these requirements
+2. Read the discovery brief (`.sniper/artifacts/discovery-brief.md`) and codebase overview for context
+3. Identify the smallest set of components that satisfies the PRD requirements
+4. For each decision, document: context, options considered, decision, consequences
+5. Validate designs against the stack defined in `.sniper/config.yaml`
+6. Prefer boring technology — choose well-understood patterns over novel ones
+7. Reference the PRD in your plan document
 
 ## Rules
 
@@ -35,4 +37,5 @@ You are a SNIPER architect agent. You design system architecture and produce tec
 - Every API contract must include error cases
 - Do NOT over-architect — design for current requirements, not hypothetical futures
 - Do NOT implement — produce designs only
+- Do NOT add requirements — design against the approved PRD, nothing more
 - Flag any requirement that cannot be met within the current stack

package/agents/code-reviewer.md

@@ -54,19 +54,20 @@ Risk categories to evaluate:
 
 ## Spec Reconciliation
 
-After completing the code review, reconcile the spec with the implementation:
+After completing the code review, reconcile the PRD with the implementation:
 
-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
+1. Compare `.sniper/artifacts/{protocol_id}/prd.md` requirements against actual implementation
+2. If implementation differs from PRD (intentionally or due to discoveries during implementation), update the PRD to reflect reality
+3. Add a "Last reconciled: YYYY-MM-DD" line at the bottom of the PRD
+4. This is a reconciliation (docs track reality), NOT a compliance check
+5. Only update if there are meaningful differences; don't touch docs if they're already accurate
+6. Do NOT modify `.sniper/artifacts/discovery-brief.md` — that is the analyst's responsibility
 
 ## Rules
 
 - Categorize findings as: `blocking` (must fix), `suggestion` (should fix), `nit` (optional)
 - Cite specific file paths and line numbers for every finding
-- If the implementation matches the spec and passes all checks, say so clearly
+- If the implementation matches the PRD and passes all checks, say so clearly
 - Do NOT nitpick style when conventions aren't established
 - 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
+- Only modify `.sniper/artifacts/{protocol_id}/prd.md` during spec reconciliation — never modify project source code or the discovery brief

package/agents/product-manager.md

@@ -5,16 +5,30 @@ write_scope:
 
 # Product Manager
 
-You are a SNIPER product manager agent. You translate requirements into structured stories with EARS acceptance criteria.
+You are a SNIPER product manager agent. You define product requirements and translate them into structured stories with EARS acceptance criteria.
 
 ## Responsibilities
 
-1. **PRD Writing** — Produce product requirements documents from specs and architecture
+1. **PRD Writing** — Produce product requirements documents from the discovery brief
 2. **Story Creation** — Break PRDs into implementable stories with EARS acceptance criteria
 3. **Scope Management** — Clearly delineate in-scope vs out-of-scope items
 4. **Priority Ordering** — Order stories by dependency and user value
 5. **Success Metrics** — Define measurable success criteria for each requirement
 
+## Workflow
+
+### During `define` phase (PRD writing)
+1. Read the discovery brief (`.sniper/artifacts/discovery-brief.md`) as your primary input
+2. Produce a PRD that defines WHAT to build and WHY — not HOW
+3. The PRD **must** include a `## Out of Scope` section — this is not optional
+4. The PRD **must** include a `## Success Criteria` section with measurable outcomes
+5. Do NOT coordinate with or wait for the architect — you run before them
+
+### During `solve` phase (story creation)
+1. Read the approved PRD and architecture plan as inputs
+2. Break the PRD into implementable stories with EARS acceptance criteria
+3. Order stories by dependency, then user value
+
 ## EARS Criteria Format
 
 Use the EARS (Easy Approach to Requirements Syntax) patterns:
@@ -26,7 +40,7 @@ Use the EARS (Easy Approach to Requirements Syntax) patterns:
 
 ## Output Artifacts
 
-- `.sniper/artifacts/{protocol_id}/prd.md` — Product requirements for this protocol run (use `spec.md` template adapted for PRD)
+- `.sniper/artifacts/{protocol_id}/prd.md` — Product requirements for this protocol run (use `prd.md` template)
 - `.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

package/checklists/define.yaml

@@ -0,0 +1,28 @@
+name: define
+description: PRD quality gate — requirements completeness and scope clarity
+
+checks:
+  - id: prd_produced
+    description: PRD document exists
+    check: file:.sniper/artifacts/{protocol_id}/prd.md
+    blocking: true
+
+  - id: requirements_defined
+    description: PRD has a Requirements section
+    check: grep:.sniper/artifacts/{protocol_id}/prd.md:"## Requirements"
+    blocking: true
+
+  - id: success_criteria_defined
+    description: PRD has measurable success criteria
+    check: grep:.sniper/artifacts/{protocol_id}/prd.md:"## Success Criteria"
+    blocking: true
+
+  - id: scope_boundaries
+    description: PRD explicitly defines what is out of scope
+    check: grep:.sniper/artifacts/{protocol_id}/prd.md:"## Out of Scope"
+    blocking: true  # Out of scope must be explicit — this is where scope creep dies
+
+  - id: token_budget
+    description: PRD is concise (under 12000 chars)
+    check: wc:.sniper/artifacts/{protocol_id}/prd.md:<12000
+    blocking: false

package/checklists/design.yaml

@@ -0,0 +1,43 @@
+name: design
+description: Architecture quality gate — design completeness
+
+checks:
+  - id: plan_produced
+    description: Architecture plan exists
+    check: file:.sniper/artifacts/{protocol_id}/plan.md
+    blocking: true
+
+  - id: has_context_section
+    description: Plan includes context and constraints
+    check: grep:.sniper/artifacts/{protocol_id}/plan.md:"## Context"
+    blocking: true
+
+  - id: has_decisions_section
+    description: Plan documents key architectural decisions
+    check: grep:.sniper/artifacts/{protocol_id}/plan.md:"## Decisions"
+    blocking: true
+
+  - id: has_components_section
+    description: Plan breaks down into components
+    check: grep:.sniper/artifacts/{protocol_id}/plan.md:"## Components"
+    blocking: true
+
+  - id: has_data_model_section
+    description: Plan defines data model (or explicitly states N/A)
+    check: grep:.sniper/artifacts/{protocol_id}/plan.md:"## Data Model"
+    blocking: false  # Not every feature requires a data model
+
+  - id: references_prd
+    description: Plan references the approved PRD
+    check: grep:.sniper/artifacts/{protocol_id}/plan.md:"prd.md"
+    blocking: false
+
+  - id: open_questions
+    description: No unresolved open questions remain
+    check: "!grep:.sniper/artifacts/{protocol_id}/plan.md:\\*\\*TBD\\*\\*|\\*\\*TODO\\*\\*|\\*\\*OPEN\\*\\*"
+    blocking: false
+
+  - id: token_budget
+    description: Architecture plan within character budget (~4000 tokens = 16000 chars)
+    check: wc:.sniper/artifacts/{protocol_id}/plan.md:<16000
+    blocking: false

package/checklists/discover.yaml

@@ -2,19 +2,29 @@ name: discover
 description: Discovery phase quality gate
 
 checks:
-  - id: spec_produced
-    description: Discovery spec exists
-    check: file:.sniper/artifacts/spec.md
+  - id: discovery_brief_produced
+    description: Discovery brief exists
+    check: file:.sniper/artifacts/discovery-brief.md
     blocking: true
 
-  - id: scope_defined
-    description: Spec defines in-scope requirements
-    check: grep:.sniper/artifacts/spec.md:"## Requirements"
+  - id: findings_defined
+    description: Brief defines key findings
+    check: grep:.sniper/artifacts/discovery-brief.md:"## Findings"
     blocking: true
 
+  - id: constraints_identified
+    description: Brief identifies constraints
+    check: grep:.sniper/artifacts/discovery-brief.md:"## Constraints"
+    blocking: false
+
+  - id: risks_identified
+    description: Brief identifies risks
+    check: grep:.sniper/artifacts/discovery-brief.md:"## Risks"
+    blocking: false
+
   - id: out_of_scope_explicit
-    description: Spec explicitly lists out-of-scope items
-    check: grep:.sniper/artifacts/spec.md:"## Out of Scope"
+    description: Brief explicitly lists out-of-scope items
+    check: grep:.sniper/artifacts/discovery-brief.md:"## Out of Scope"
     blocking: false
 
   - id: codebase_overview

package/checklists/multi-faceted-review.yaml

@@ -4,9 +4,9 @@ description: Multi-dimensional review gate — scope, standards, and risk
 
 checks:
   # Scope Validation — does the implementation match requirements?
-  - id: scope_spec_match
-    description: Implementation addresses all spec requirements
-    check: file:.sniper/artifacts/spec.md
+  - id: scope_prd_match
+    description: PRD exists (scope validation is performed by code-reviewer agent)
+    check: file:.sniper/artifacts/{protocol_id}/prd.md
     blocking: true
 
   - id: scope_acceptance_criteria

package/checklists/plan.yaml

@@ -1,5 +1,7 @@
 name: plan
-description: Planning phase quality gate
+description: Planning phase quality gate (DEPRECATED — use define.yaml + design.yaml instead)
+# DEPRECATED: This checklist is retained for backward compatibility with custom protocols
+# that reference the combined "plan" phase. New protocols use separate "define" and "design" phases.
 # Note: {protocol_id} is resolved at gate-review time from the active checkpoint
 
 checks:
@@ -22,7 +24,7 @@ checks:
 
   - id: open_questions
     description: No unresolved open questions remain
-    check: "!grep:.sniper/artifacts/{protocol_id}/:\\*\\*TBD\\*\\*|\\*\\*TODO\\*\\*|\\*\\*OPEN\\*\\*"
+    check: "!grep:.sniper/artifacts/{protocol_id}/plan.md:\\*\\*TBD\\*\\*|\\*\\*TODO\\*\\*|\\*\\*OPEN\\*\\*"
     blocking: false
 
   - id: token_budget

package/checklists/review.yaml

@@ -24,6 +24,6 @@ checks:
     blocking: true
 
   - id: spec_reconciled
-    description: Spec has been reconciled with implementation
-    check: "grep:.sniper/artifacts/spec.md:Last reconciled:"
+    description: PRD has been reconciled with implementation
+    check: "grep:.sniper/artifacts/{protocol_id}/prd.md:Last reconciled:"
     blocking: false

package/package.json

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

package/protocols/feature.yaml

@@ -1,30 +1,41 @@
 name: feature
-description: Incremental feature — plan, implement, review
+description: Incremental feature — define, design, solve, implement, review, retro
 budget: 800000  # 800K tokens
 
 phases:
-  - name: plan
-    description: Feature design and architecture
+  - name: define
+    description: Product requirements for the feature
     agents:
-      - architect
       - product-manager
-    spawn_strategy: sequential  # Architect designs first, PM refines PRD from that
+    spawn_strategy: single
+    interactive_review: true  # User reviews PRD before architecture
+    gate:
+      checklist: define
+      human_approval: true
+    outputs:
+      - .sniper/artifacts/{protocol_id}/prd.md
+
+  - name: design
+    description: Technical design against approved requirements
+    agents:
+      - architect
+    spawn_strategy: single
     interactive_review: true  # User reviews architecture before story sharding
     gate:
-      checklist: plan
+      checklist: design
       human_approval: true
     outputs:
       - .sniper/artifacts/{protocol_id}/plan.md
-      - .sniper/artifacts/{protocol_id}/prd.md
 
   - name: solve
     description: Story creation from approved architecture
     agents:
       - product-manager
     spawn_strategy: single
+    interactive_review: true  # User reviews story decomposition before implementation
     gate:
       checklist: solve
-      human_approval: false
+      human_approval: true  # Review story decomposition before implementation
     outputs:
       - .sniper/artifacts/{protocol_id}/stories/
 

package/protocols/full.yaml

@@ -4,43 +4,51 @@ budget: 2000000  # 2M tokens
 
 phases:
   - name: discover
-    description: Research, analyze codebase, produce discovery spec and PRD
+    description: Research problem space, analyze codebase, identify constraints
     agents:
       - analyst
-    spawn_strategy: single  # One agent, no team needed
-    interactive_review: true  # User reviews spec/PRD before architecture begins
+    spawn_strategy: single
+    interactive_review: true  # User reviews discovery brief before PRD begins
     gate:
       checklist: discover
       human_approval: true
     outputs:
-      - .sniper/artifacts/spec.md  # Living master doc
+      - .sniper/artifacts/discovery-brief.md  # Living master doc
       - .sniper/artifacts/codebase-overview.md  # Living master doc
 
-  - name: plan
-    description: Architecture design and PRD refinement
+  - name: define
+    description: Product requirements — what to build, success criteria, scope boundaries
     agents:
-      - architect
       - product-manager
-    spawn_strategy: team  # Multiple agents, use TeamCreate
+    spawn_strategy: single
+    interactive_review: true  # User reviews PRD before architecture begins — highest-leverage gate
+    gate:
+      checklist: define
+      human_approval: true
+    outputs:
+      - .sniper/artifacts/{protocol_id}/prd.md
+
+  - name: design
+    description: Architecture design against approved PRD requirements
+    agents:
+      - architect
+    spawn_strategy: single
     interactive_review: true  # User reviews architecture before story sharding
-    coordination:
-      - between: [architect, product-manager]
-        topic: Architecture must be finalized before PRD is updated
     gate:
-      checklist: plan
-      human_approval: true  # Human reviews architecture before stories are created
+      checklist: design
+      human_approval: true
     outputs:
       - .sniper/artifacts/{protocol_id}/plan.md
-      - .sniper/artifacts/{protocol_id}/prd.md
 
   - name: solve
     description: Epic sharding and story creation from approved architecture
     agents:
       - product-manager
     spawn_strategy: single
+    interactive_review: true  # User reviews story decomposition before implementation
     gate:
       checklist: solve
-      human_approval: false
+      human_approval: true  # Bad decomposition causes expensive rework — worth 5 minutes
     outputs:
       - .sniper/artifacts/{protocol_id}/stories/
 

package/skills/sniper-flow/SKILL.md

@@ -63,10 +63,11 @@ For each phase in the protocol, execute these 5 steps:
 ### Execute
 
 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)
+2. Spawn **ONLY** the agents listed in the protocol phase's `agents` array — no more, no fewer. Do NOT infer additional agents from the phase description or outputs. The `agents` list is the single source of truth for who participates in each phase.
+3. Spawn agents per [Reference: Spawn Strategies](#reference-spawn-strategies)
+4. Monitor via TaskList — if an agent is blocked, investigate and guide via SendMessage
+5. If an agent crashes: note the failure, continue with remaining agents
+6. After all parallel agents complete: coordinate worktree merges per [Reference: Merge Coordination](#reference-merge-coordination)
 
 ### Checkpoint
 
@@ -199,10 +200,12 @@ For agents working in worktrees (after all implementation agents complete):
 
 When a phase has `interactive_review: true`:
 
-1. Read produced artifacts from `.sniper/artifacts/{protocol_id}/` (e.g., `spec.md`, `plan.md`, `prd.md`)
+1. Read produced artifacts from `.sniper/artifacts/` or `.sniper/artifacts/{protocol_id}/` as appropriate
 2. Present a structured summary appropriate to the phase:
-   - **discover:** scope, requirements, key findings, open questions
-   - **plan:** key architectural decisions, component overview, data model, trade-offs
+   - **discover:** findings, constraints, codebase landscape, open questions
+   - **define:** requirements, success criteria, scope boundaries, out-of-scope items
+   - **design:** key architectural decisions, component overview, data model, trade-offs
+   - **solve:** story list, dependencies, acceptance criteria summary
 3. Offer options:
    - **Approve** — continue to next phase
    - **Request changes** — describe changes (architect/PM will revise, then re-present)

package/templates/discovery-brief.md

@@ -0,0 +1,23 @@
+# Discovery Brief
+<!-- Budget: 3000 tokens max -->
+<!-- This is research output, not a specification. Frame as findings and constraints, not design decisions. -->
+
+## Context
+<!-- ~300 tokens: What exists today, what triggered this investigation -->
+
+## Findings
+<!-- ~800 tokens: Key discoveries from codebase analysis, research, and requirements elicitation -->
+<!-- Ground every finding in evidence — cite file paths, line numbers, or URLs -->
+
+## Constraints
+<!-- ~400 tokens: Technical constraints, dependencies, and limitations discovered -->
+
+## Risks
+<!-- ~300 tokens: Technical risks, unknowns, and potential blockers -->
+
+## Out of Scope
+<!-- ~200 tokens: Explicitly list what this work should NOT cover -->
+
+## Open Questions
+<!-- ~200 tokens: Unresolved questions that need answers before defining requirements -->
+<!-- Distinguish facts from assumptions explicitly -->

package/templates/prd.md

@@ -0,0 +1,30 @@
+# Product Requirements Document
+<!-- Budget: 3000 tokens max -->
+<!-- This defines WHAT to build and WHY — not HOW. Architecture comes later. -->
+
+## Context
+<!-- ~300 tokens: What exists today and why this work is needed -->
+
+## Problem
+<!-- ~400 tokens: What specific problem are we solving -->
+
+## Users
+<!-- ~200 tokens: Who are the users and what do they need -->
+
+## Requirements
+<!-- ~800 tokens: EARS-format requirements -->
+<!-- Use: "The <system> shall <action>" for each requirement -->
+
+### Functional Requirements
+
+### Non-Functional Requirements
+
+## Out of Scope
+<!-- ~200 tokens: Explicitly list what this work does NOT cover -->
+<!-- This section is mandatory — scope creep dies here -->
+
+## Success Criteria
+<!-- ~300 tokens: Measurable outcomes that define "done" -->
+
+## Open Questions
+<!-- ~200 tokens: Unresolved questions that need answers before design -->