@sniper.ai/core 3.3.1 → 4.0.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 |
@@ -108,19 +109,20 @@ Domain-specific knowledge is provided separately by domain packs (e.g., `@sniper
 | `workspace-config.yaml` | YAML | Workspace configuration |
 | `knowledge-manifest.yaml` | YAML | Knowledge base manifest |
 | `checkpoint.yaml` | YAML | Protocol checkpoint state |
-| `cost.yaml` | YAML | Token cost tracking |
 | `live-status.yaml` | YAML | Live protocol status |
-| `velocity.yaml` | YAML | Velocity calibration data |
 | `signal-record.yaml` | YAML | Signal event record |
 
 ## 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
@@ -25,5 +25,5 @@ You are a SNIPER analyst agent. You research, analyze, and produce discovery art
 - Ground every finding in evidence — cite file paths, line numbers, or URLs
 - Distinguish facts from assumptions explicitly
 - 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

@@ -17,17 +17,19 @@ You are a SNIPER architect agent. You design system architecture and produce tec
 
 ## Output Artifacts
 
-- `.sniper/artifacts/{protocol_id}/plan.md` — Architecture plan for this protocol run (use `architecture.md` template, 4000 token budget)
+- `.sniper/artifacts/{protocol_id}/plan.md` — Architecture plan for this protocol run (use `architecture.md` template)
   - 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
 
-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,8 +40,8 @@ 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}/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 `prd.md` template)
+- `.sniper/artifacts/{protocol_id}/stories/*.md` — Individual stories (use `story.md` template)
   - 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/agents/retro-analyst.md

@@ -11,10 +11,9 @@ You are a SNIPER retro analyst agent. You run automated retrospectives after pro
 
 1. **Protocol Analysis** — Review what happened during the completed protocol execution
 2. **Pattern Extraction** — Identify what worked well and what didn't
-3. **Metric Collection** — Gather token usage, duration, agent count, and gate results
+3. **Metric Collection** — Gather duration, agent count, and gate results
 4. **Recommendation Generation** — Suggest concrete improvements for next time
 5. **Retro Report** — Write structured retro to `.sniper/retros/`
-6. **Velocity Tracking** — Record execution metrics to `.sniper/memory/velocity.yaml` for budget calibration
 
 ## Invocation
 
@@ -25,10 +24,9 @@ The orchestrator provides you with the `protocol_id` (e.g., `SNPR-20260307-a3f2`
 
 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. 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`
+3. Read `.sniper/artifacts/{protocol_id}/meta.yaml` for protocol metadata
+4. Analyze: Which gates failed first? Were there re-runs?
+5. Write retro report to `.sniper/retros/{protocol_id}.yaml`
 
 ## Retro Report Schema
 
@@ -41,7 +39,6 @@ duration_phases:
     gate_attempts: <count>
     gate_result: pass | fail
 metrics:
-  total_tokens: <number>
   total_agents_spawned: <number>
   gate_pass_rate: <percentage>
 findings:
@@ -58,7 +55,7 @@ findings:
 - Be specific — cite actual data, not vague observations
 - Focus on actionable improvements, not blame
 - Write to `.sniper/retros/` only — never modify project code
-- Keep the report concise — under 1000 tokens
+- Keep the report concise
 - Compare against previous retros if they exist to track trends
 
 ## Learning Extraction
@@ -132,25 +129,3 @@ During the retrospective, analyze external signals from both legacy and new stor
        recurrence: <count>
    ```
 
-## Velocity Tracking
-
-After writing the retro report, update velocity data:
-
-1. Read `.sniper/memory/velocity.yaml` (create if it doesn't exist)
-2. Append a new execution record:
-   ```yaml
-   - protocol: <protocol_name>
-     completed_at: <ISO 8601>
-     wall_clock_seconds: <duration>
-     tokens_used: <total_tokens>
-     tokens_per_phase:
-       <phase_name>: <tokens>
-   ```
-3. After 5+ executions of the same protocol, compute `calibrated_budgets`:
-   - Collect all `tokens_used` values for that protocol
-   - Calculate the p75 (75th percentile) value
-   - Set `calibrated_budgets.<protocol>` to that value
-4. Update `rolling_averages.<protocol>` with exponential moving average:
-   - Formula: `new_avg = 0.3 * latest_tokens + 0.7 * previous_avg`
-   - If no previous average, use the latest value
-5. Write updated velocity data back to `.sniper/memory/velocity.yaml`

package/checklists/define.yaml

@@ -0,0 +1,23 @@
+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

package/checklists/design.yaml

@@ -0,0 +1,38 @@
+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

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:
@@ -24,8 +26,3 @@ checks:
     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/retro.yaml

@@ -7,9 +7,3 @@ checks:
     type: file_exists
     path: ".sniper/retros/{protocol_id}.yaml"
     blocking: true
-
-  - id: velocity_updated
-    description: Velocity data updated
-    type: file_exists
-    path: ".sniper/memory/velocity.yaml"
-    blocking: true

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/config.template.yaml

@@ -44,16 +44,6 @@ routing:
   # Default protocol when auto-detect is ambiguous
   default: feature
 
-  # Protocol token budgets (override protocol defaults)
-  budgets:
-    full: 2000000
-    feature: 800000
-    patch: 200000
-    ingest: 1000000
-    explore: 500000
-    refactor: 600000
-    hotfix: 100000
-
 # Trigger tables — map file patterns to agents or protocols
 # Example:
 #   - pattern: "src/api/**"
@@ -64,12 +54,6 @@ routing:
 #     protocol: full
 triggers: []
 
-# Cost enforcement
-cost:
-  warn_threshold: 0.7       # Warn at 70% of budget
-  soft_cap: 0.9              # Soft cap at 90% — agents must justify continuing
-  hard_cap: 1.0              # Hard cap at 100% — stop execution
-
 # Review configuration
 review:
   multi_model: false           # Enable multi-model review for gate checks
@@ -161,5 +145,4 @@ learning:
 visibility:
   live_status: true          # Maintain .sniper/live-status.yaml
   checkpoints: true          # Write phase checkpoints
-  cost_tracking: true        # Track token usage
   # auto_retro: true         # DEPRECATED — use retro phase in protocols instead

package/package.json

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

package/protocols/explore.yaml

@@ -1,6 +1,5 @@
 name: explore
 description: Exploratory analysis — understand a codebase or problem space
-budget: 500000  # 500K tokens
 
 phases:
   - name: discover

package/protocols/feature.yaml

@@ -1,30 +1,40 @@
 name: feature
-description: Incremental feature — plan, implement, review
-budget: 800000  # 800K tokens
+description: Incremental feature — define, design, solve, implement, review, retro
 
 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/
 
@@ -64,5 +74,4 @@ phases:
       human_approval: false
     outputs:
       - .sniper/retros/{protocol_id}.yaml
-      - .sniper/memory/velocity.yaml
       - .sniper/memory/learnings/

package/protocols/full.yaml

@@ -1,46 +1,53 @@
 name: full
 description: Complete project lifecycle — discovery through review
-budget: 2000000  # 2M tokens
 
 phases:
   - name: discover
-    description: Research and analyze codebase to produce discovery spec
+    description: Research problem space, analyze codebase, identify constraints
     agents:
       - analyst
-    spawn_strategy: single  # One agent, no team needed
-    interactive_review: true  # User reviews spec 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/
 
@@ -83,7 +90,6 @@ phases:
       human_approval: false
     outputs:
       - .sniper/retros/{protocol_id}.yaml
-      - .sniper/memory/velocity.yaml
       - .sniper/memory/learnings/
 
   - name: curate

package/protocols/hotfix.yaml

@@ -1,6 +1,5 @@
 name: hotfix
 description: Critical fix — fastest path to production
-budget: 100000  # 100K tokens
 
 phases:
   - name: implement

package/protocols/ingest.yaml

@@ -1,6 +1,5 @@
 name: ingest
 description: Codebase ingestion — scan, document, extract conventions
-budget: 1000000  # 1M tokens
 
 phases:
   - name: scan

package/protocols/patch.yaml

@@ -1,6 +1,5 @@
 name: patch
 description: Quick fix — implement and review only
-budget: 200000  # 200K tokens
 
 phases:
   - name: implement

package/protocols/refactor.yaml

@@ -1,6 +1,5 @@
 name: refactor
 description: Code improvement — analyze, refactor, and review
-budget: 600000  # 600K tokens
 
 phases:
   - name: analyze
@@ -50,5 +49,4 @@ phases:
       human_approval: false
     outputs:
       - .sniper/retros/{protocol_id}.yaml
-      - .sniper/memory/velocity.yaml
       - .sniper/memory/learnings/

package/schemas/checkpoint.schema.yaml

@@ -92,22 +92,6 @@ properties:
             - draft
             - complete
           description: Whether the artifact is a draft or complete.
-  token_usage:
-    type: object
-    description: Token consumption metrics for this phase.
-    properties:
-      phase_tokens:
-        type: integer
-        minimum: 0
-        description: Tokens consumed during this phase.
-      cumulative_tokens:
-        type: integer
-        minimum: 0
-        description: Total tokens consumed across all phases up to and including this one.
-      budget_remaining:
-        type: number
-        minimum: 0
-        description: Remaining token budget.
   commits:
     type: array
     description: Git commits made during this phase, used for logical revert.

package/schemas/live-status.schema.yaml

@@ -126,23 +126,6 @@ properties:
           type: string
           format: date-time
           description: ISO 8601 timestamp of when the gate review completed.
-  cost:
-    type: object
-    description: Current cost snapshot.
-    properties:
-      tokens_used:
-        type: integer
-        minimum: 0
-        description: Total tokens consumed so far.
-      budget:
-        type: number
-        minimum: 0
-        description: Total token budget.
-      percent:
-        type: number
-        minimum: 0
-        maximum: 100
-        description: Percentage of budget consumed.
   next_action:
     type: string
     description: Description of the next expected action or step.

package/schemas/protocol.schema.yaml

@@ -6,7 +6,6 @@ type: object
 required:
   - name
   - description
-  - budget
   - phases
 properties:
   name:
@@ -15,10 +14,6 @@ properties:
   description:
     type: string
     description: Human-readable description of the protocol's purpose.
-  budget:
-    type: integer
-    minimum: 1
-    description: Maximum token budget for the entire protocol execution.
   phases:
     type: array
     minItems: 1

package/schemas/retro.schema.yaml

@@ -82,18 +82,4 @@ properties:
         type: array
         items: { type: string }
         description: IDs of learnings created from this retro's findings.
-  velocity:
-    type: object
-    description: Velocity metrics for this execution, used for budget calibration.
-    properties:
-      wall_clock_seconds:
-        type: number
-        minimum: 0
-        description: Total wall clock time for the protocol execution in seconds.
-      tokens_per_phase:
-        type: object
-        description: Token usage broken down by phase name.
-        additionalProperties:
-          type: integer
-          minimum: 0
 additionalProperties: false

package/skills/sniper-flow/SKILL.md

@@ -57,8 +57,7 @@ For each phase in the protocol, execute these 5 steps:
 
 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)
+3. Compose agents per [Reference: Agent Composition](#reference-agent-composition)
 
 ### Execute
 
@@ -79,11 +78,10 @@ phase: <phase>
 timestamp: <ISO 8601>
 status: completed | failed
 agents: [status per agent]
-token_usage: [phase + cumulative]
 commits: [git SHAs produced]
 ```
 
-Update `.sniper/live-status.yaml` with current phase, agent statuses, and cost percentage.
+Update `.sniper/live-status.yaml` with current phase and agent statuses.
 
 After the `solve` phase completes, populate the `stories` array in `.sniper/live-status.yaml` by reading story files from `.sniper/artifacts/{protocol_id}/stories/`. During `implement`, update each story's status (`in_progress` → `completed`) as agents finish work on it.
 
@@ -107,25 +105,15 @@ After the `solve` phase completes, populate the `stories` array in `.sniper/live
 
 1. Write final checkpoint
 2. Update `.sniper/live-status.yaml` with `status: completed`
-3. Update `.sniper/artifacts/{protocol_id}/meta.yaml` with final status, token usage, commits, agents used
+3. Update `.sniper/artifacts/{protocol_id}/meta.yaml` with final status, commits, agents used
 4. Update `.sniper/artifacts/registry.md` entry from `in_progress` to `completed`
-5. Present summary: phases completed, gate results, token usage, learnings created
+5. Present summary: phases completed, gate results, learnings created
 6. **Backward compatibility:** If the protocol has `auto_retro: true` but no `retro` phase in its phases list (custom protocols), spawn retro-analyst as a single-agent phase before completing
 
-## Cost Tracking
-
-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
-
-Read thresholds from `.sniper/config.yaml` cost section.
-
 ## Rules
 
 - 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
@@ -200,10 +188,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)
@@ -215,9 +205,9 @@ When a phase has `interactive_review: true`:
 > **Note:** The retro is now a first-class phase in protocols (full, feature, refactor). This reference is retained for backward compatibility with custom protocols using `auto_retro: true`.
 
 When `auto_retro: true` and no `retro` phase exists in the protocol:
-1. Spawn `retro-analyst` as a single-agent phase with: protocol ID, checkpoint history, gate results, cost data
-2. The retro-analyst writes a report to `.sniper/retros/{protocol_id}.yaml`, extracts learnings to `.sniper/memory/learnings/`, updates `.sniper/memory/velocity.yaml`, and checks effectiveness of previously applied learnings
-3. Run the retro gate checklist (retro report exists + velocity updated)
+1. Spawn `retro-analyst` as a single-agent phase with: protocol ID, checkpoint history, gate results
+2. The retro-analyst writes a report to `.sniper/retros/{protocol_id}.yaml`, extracts learnings to `.sniper/memory/learnings/`, and checks effectiveness of previously applied learnings
+3. Run the retro gate checklist (retro report exists)
 
 ## Reference: Review Gate Feedback Capture
 

package/skills/sniper-init/SKILL.md

@@ -76,7 +76,6 @@ Create the following directory structure:
   memory/
     learnings/             ← Unified learning store (replaces signals/)
     signals/               ← Legacy — kept for backward compat, migrated by memory-curator
-    velocity.yaml
     archive/               ← Deprecated learnings archived here
 .claude/
   agents/                  ← Copied from @sniper.ai/core/agents/

package/skills/sniper-status/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: sniper-status
-description: Show current SNIPER protocol progress and cost
+description: Show current SNIPER protocol progress
 arguments: []
 ---
 
@@ -15,7 +15,6 @@ Display the current state of SNIPER in this project.
 Read the following files (skip if they don't exist):
 - `.sniper/config.yaml` — Project configuration
 - `.sniper/live-status.yaml` — Active protocol progress
-- `.sniper/cost.yaml` — Token usage tracking
 
 If `.sniper/config.yaml` doesn't exist, display: "SNIPER is not initialized. Run `/sniper-init` first."
 
@@ -34,21 +33,10 @@ Format and display:
 - Agent status per active phase
 - Gate results for completed phases
 
-**Cost Summary** (if tracking enabled):
-- Tokens used vs budget
-- Budget percentage with visual bar
-- Warning if approaching soft/hard cap
-
 **Recent Activity**:
 - Last 3 checkpoints with timestamps
 - Last gate result
 
-**Velocity Trends** (if velocity data exists):
-- Read `.sniper/memory/velocity.yaml`
-- Show last 5 executions per protocol with tokens used
-- Show calibrated budget vs configured budget comparison
-- Show trend direction: ↑ (increasing usage), ↓ (decreasing usage), → (stable)
-
 ### 3. Format Output
 
 Use clear formatting:
@@ -63,17 +51,9 @@ Phase:    implement [===========-----] 68%
 
 Gates:
   plan:      PASS (2025-01-15)
-
-Cost: 245K / 800K tokens (31%)
-[======--------------] 31%
-
-Velocity:
-  feature: 612K avg (calibrated: 750K, configured: 800K) →
-  patch:   145K avg (calibrated: 180K, configured: 200K) ↓
 ```
 
 ## Rules
 
 - Read-only — this skill never modifies any files
 - If no protocol is active, show config summary only
-- If cost tracking is disabled, skip cost section

package/templates/architecture.md

@@ -1,23 +1,16 @@
 # Architecture
-<!-- Budget: 4000 tokens max -->
 
 ## Context
-<!-- ~400 tokens: Technical context, constraints, existing system landscape -->
 
 ## Decisions
-<!-- ~800 tokens: Key architectural decisions with rationale -->
 <!-- For each decision: Context | Options Considered | Decision | Consequences -->
 
 ## Components
-<!-- ~1000 tokens: Component breakdown with responsibilities -->
 <!-- For each component: Name | Responsibility | Dependencies | Owner -->
 
 ## Data Model
-<!-- ~600 tokens: Core entities and relationships -->
 
 ## API Contracts
-<!-- ~800 tokens: Key API interfaces including error cases -->
 <!-- For each endpoint: Method | Path | Request | Response | Errors -->
 
 ## Infrastructure
-<!-- ~400 tokens: Deployment, scaling, monitoring considerations -->

package/templates/checkpoint.yaml

@@ -19,9 +19,4 @@ artifacts_produced: []
 # - path: .sniper/artifacts/spec.md
 #   status: draft | complete
 
-token_usage:
-  phase_tokens: 0
-  cumulative_tokens: 0
-  budget_remaining: 0
-
 notes: ""

package/templates/custom-protocol.yaml

@@ -13,10 +13,6 @@ name: my-protocol
 # description (required): What this protocol accomplishes.
 description: Describe the goal of your custom protocol
 
-# budget (required): Maximum token budget for the entire execution.
-# Common ranges: 100K (hotfix), 800K (feature), 2M (full lifecycle)
-budget: 500000
-
 # phases (required): Ordered list of phases. Each phase runs sequentially.
 # The protocol engine executes phases top-to-bottom, gating between each.
 phases:
@@ -94,10 +90,10 @@ phases:
       - .sniper/artifacts/{protocol_id}/review-report.md
 
   # ── Phase 4: Retro (recommended) ──────────────────────────
-  # Runs the retro-analyst to extract learnings, update velocity, and check
+  # Runs the retro-analyst to extract learnings and check
   # learning effectiveness. Replaces the old auto_retro flag.
   - name: retro
-    description: Retrospective — extract learnings and update velocity
+    description: Retrospective — extract learnings
     agents:
       - retro-analyst
     spawn_strategy: single
@@ -106,7 +102,6 @@ phases:
       human_approval: false
     outputs:
       - .sniper/retros/{protocol_id}.yaml
-      - .sniper/memory/velocity.yaml
       - .sniper/memory/learnings/
 
   # ── Phase 5: Curate (optional) ────────────────────────────

package/templates/discovery-brief.md

@@ -0,0 +1,16 @@
+# Discovery Brief
+<!-- This is research output, not a specification. Frame as findings and constraints, not design decisions. -->
+
+## Context
+
+## Findings
+<!-- Ground every finding in evidence — cite file paths, line numbers, or URLs -->
+
+## Constraints
+
+## Risks
+
+## Out of Scope
+
+## Open Questions
+<!-- Distinguish facts from assumptions explicitly -->

package/templates/live-status.yaml

@@ -24,9 +24,4 @@ gate_results: []
 #   result: pass
 #   timestamp: ""
 
-cost:
-  tokens_used: 0
-  budget: 0
-  percent: 0
-
 next_action: ""  # Human-readable description of what's next

package/templates/prd.md

@@ -0,0 +1,22 @@
+# Product Requirements Document
+<!-- This defines WHAT to build and WHY — not HOW. Architecture comes later. -->
+
+## Context
+
+## Problem
+
+## Users
+
+## Requirements
+<!-- Use: "The <system> shall <action>" for each requirement -->
+
+### Functional Requirements
+
+### Non-Functional Requirements
+
+## Out of Scope
+<!-- This section is mandatory — scope creep dies here -->
+
+## Success Criteria
+
+## Open Questions

package/templates/story.md

@@ -6,16 +6,12 @@ completed_at:
 ---
 
 # Story: [TITLE]
-<!-- Budget: 1500 tokens max -->
 
 ## Context
-<!-- ~200 tokens: Why this story exists, link to architecture/spec -->
 
 ## Task
-<!-- ~400 tokens: What needs to be done, specific and actionable -->
 
 ## Acceptance Criteria
-<!-- ~600 tokens: EARS-format criteria -->
 <!-- Each criterion must be independently testable -->
 
 1. When [event], the system shall [action]
@@ -23,4 +19,3 @@ completed_at:
 3. If [condition], then the system shall [action]
 
 ## Technical Notes
-<!-- ~300 tokens: Implementation hints, relevant code locations, gotchas -->

package/schemas/cost.schema.yaml

@@ -1,97 +0,0 @@
-$schema: "https://json-schema.org/draft/2020-12/schema"
-$id: "https://sniper.ai/schemas/cost"
-title: Cost Tracking
-description: Schema for SNIPER cost tracking that monitors token usage and budget across phases.
-type: object
-required:
-  - protocol
-  - started_at
-  - budget
-properties:
-  protocol:
-    type: string
-    description: The SNIPER protocol version identifier.
-  started_at:
-    type: string
-    format: date-time
-    description: ISO 8601 timestamp of when cost tracking began.
-  budget:
-    type: number
-    minimum: 0
-    description: Total token budget allocated for the project.
-  phases:
-    type: array
-    description: Per-phase cost breakdown.
-    items:
-      type: object
-      required:
-        - name
-      properties:
-        name:
-          type: string
-          description: Phase name (e.g. discover, plan, implement, review).
-        started_at:
-          type: string
-          format: date-time
-          description: ISO 8601 timestamp of when this phase started.
-        completed_at:
-          type: string
-          format: date-time
-          description: ISO 8601 timestamp of when this phase completed.
-        tokens_used:
-          type: integer
-          minimum: 0
-          description: Total tokens consumed during this phase.
-        agents:
-          type: array
-          description: Per-agent cost breakdown within this phase.
-          items:
-            type: object
-            required:
-              - name
-              - tokens_used
-            properties:
-              name:
-                type: string
-                description: Agent persona name.
-              tokens_used:
-                type: integer
-                minimum: 0
-                description: Tokens consumed by this agent.
-  totals:
-    type: object
-    description: Aggregate cost totals.
-    properties:
-      tokens_used:
-        type: integer
-        minimum: 0
-        description: Total tokens consumed across all phases.
-      budget_remaining:
-        type: number
-        minimum: 0
-        description: Remaining token budget.
-      budget_percent_used:
-        type: number
-        minimum: 0
-        maximum: 100
-        description: Percentage of budget consumed.
-  enforcement:
-    type: object
-    description: Budget enforcement thresholds expressed as fractions of the total budget.
-    properties:
-      warn_threshold:
-        type: number
-        minimum: 0
-        maximum: 1
-        description: Fraction of budget at which a warning is issued.
-      soft_cap:
-        type: number
-        minimum: 0
-        maximum: 1
-        description: Fraction of budget at which soft enforcement begins (e.g. require confirmation).
-      hard_cap:
-        type: number
-        minimum: 0
-        maximum: 1
-        description: Fraction of budget at which execution is halted.
-additionalProperties: false

package/schemas/velocity.schema.yaml

@@ -1,52 +0,0 @@
-$schema: "https://json-schema.org/draft/2020-12/schema"
-$id: "https://sniper.ai/schemas/velocity"
-title: Velocity
-description: Protocol execution history and calibrated budgets for adaptive budget selection.
-type: object
-required:
-  - executions
-properties:
-  executions:
-    type: array
-    description: History of protocol executions with timing and token data.
-    items:
-      type: object
-      required:
-        - protocol
-        - completed_at
-        - tokens_used
-      properties:
-        protocol:
-          type: string
-          description: Protocol name that was executed.
-        completed_at:
-          type: string
-          format: date-time
-          description: ISO 8601 timestamp of when the execution completed.
-        wall_clock_seconds:
-          type: number
-          minimum: 0
-          description: Wall clock duration of the execution in seconds.
-        tokens_used:
-          type: integer
-          minimum: 0
-          description: Total tokens consumed during the execution.
-        tokens_per_phase:
-          type: object
-          description: Token usage broken down by phase name.
-          additionalProperties:
-            type: integer
-            minimum: 0
-  calibrated_budgets:
-    type: object
-    description: p75 of token usage from last 5+ executions, keyed by protocol name.
-    additionalProperties:
-      type: integer
-      minimum: 0
-  rolling_averages:
-    type: object
-    description: Exponential moving average of token usage, keyed by protocol name.
-    additionalProperties:
-      type: number
-      minimum: 0
-additionalProperties: false

package/templates/cost.yaml

@@ -1,23 +0,0 @@
-# Cost tracking for protocol execution
-protocol: ""
-started_at: ""
-budget: 0
-
-phases: []
-# - name: discover
-#   started_at: ""
-#   completed_at: ""
-#   tokens_used: 0
-#   agents:
-#     - name: analyst
-#       tokens_used: 0
-
-totals:
-  tokens_used: 0
-  budget_remaining: 0
-  budget_percent_used: 0
-
-enforcement:
-  warn_threshold: 0.7    # Warn at 70% budget
-  soft_cap: 0.9          # Soft cap at 90% — agents must justify continuation
-  hard_cap: 1.0          # Hard cap at 100% — stop execution

package/templates/velocity.yaml

@@ -1,9 +0,0 @@
-# Velocity — protocol execution history and calibrated budgets
-# Auto-populated by retro-analyst after each protocol completion
-# Read by /sniper-flow for adaptive budget selection
-
-executions: []
-
-calibrated_budgets: {}
-
-rolling_averages: {}