@sniper.ai/core 2.0.0 → 3.1.0

package/skills/sniper-status/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: sniper-status
+description: Show current SNIPER protocol progress and cost
+arguments: []
+---
+
+# /sniper-status
+
+Display the current state of SNIPER in this project.
+
+## Process
+
+### 1. Read State Files
+
+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."
+
+### 2. Display Status
+
+Format and display:
+
+**Project Info**:
+- Project name and type
+- Stack summary (language, framework, database)
+- Plugins installed
+
+**Protocol Status** (if active):
+- Protocol name and current phase
+- Phase progress (completed/total phases)
+- 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:
+```
+Project: my-app (saas)
+Stack:   TypeScript, Next.js, PostgreSQL
+
+Protocol: feature (phase 2/3)
+Phase:    implement [===========-----] 68%
+  backend-dev:  implementing (3/5 tasks)
+  qa-engineer:  waiting
+
+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

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

@@ -0,0 +1,27 @@
+# Phase checkpoint — snapshot of protocol state
+protocol: ""
+phase: ""
+timestamp: ""
+status: ""  # in_progress | completed | failed
+
+agents:
+  - name: ""
+    status: ""  # active | completed | failed
+    tasks_completed: 0
+    tasks_total: 0
+
+gate_result: null  # null if gate not yet run
+# gate_result:
+#   result: pass | fail
+#   blocking_failures: 0
+
+artifacts_produced: []
+# - path: .sniper/artifacts/spec.md
+#   status: draft | complete
+
+token_usage:
+  phase_tokens: 0
+  cumulative_tokens: 0
+  budget_remaining: 0
+
+notes: ""

package/templates/codebase-overview.md

@@ -0,0 +1,19 @@
+# Codebase Overview
+<!-- Budget: 2000 tokens max -->
+
+## Architecture
+<!-- ~400 tokens: High-level architecture pattern and key design decisions -->
+
+## Key Modules
+<!-- ~500 tokens: Core modules/packages with responsibilities -->
+| Module | Path | Responsibility |
+|--------|------|---------------|
+
+## Data Flow
+<!-- ~400 tokens: How data moves through the system -->
+
+## Conventions
+<!-- ~400 tokens: Coding patterns, naming conventions, project-specific rules -->
+
+## Risks
+<!-- ~300 tokens: Technical debt, fragile areas, known issues -->

package/templates/cost.yaml

@@ -0,0 +1,23 @@
+# 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/custom-protocol.yaml

@@ -0,0 +1,98 @@
+# ─────────────────────────────────────────────────────────────
+# SNIPER Custom Protocol Template
+# ─────────────────────────────────────────────────────────────
+# Copy this file to .sniper/protocols/<name>.yaml and customize.
+# Run `sniper protocol validate <name>` to check your protocol.
+# See built-in protocols in @sniper.ai/core/protocols/ for examples.
+# ─────────────────────────────────────────────────────────────
+
+# name (required): Unique identifier for your protocol.
+# Used in --protocol flag: /sniper-flow --protocol my-protocol
+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:
+  # ── Phase 1: Plan ──────────────────────────────────────────
+  - name: plan
+    # description (required): What this phase accomplishes.
+    description: Design the approach and break down into tasks
+
+    # agents (required): Which agent personas to assign.
+    # Available built-in agents: analyst, architect, product-manager,
+    #   fullstack-dev, backend-dev, frontend-dev, qa-engineer,
+    #   code-reviewer, retro-analyst
+    agents:
+      - architect
+
+    # spawn_strategy (required): How to launch agents.
+    #   "single" — one agent works alone
+    #   "team"   — multiple agents coordinate via TeamCreate
+    spawn_strategy: single
+
+    # gate (optional): Quality gate evaluated before moving to next phase.
+    # Omit to skip gating (like hotfix protocol).
+    gate:
+      # checklist: Name of checklist from packages/core/checklists/
+      # Available: discover, plan, implement, review
+      checklist: plan
+      # human_approval: If true, a human must approve before proceeding.
+      human_approval: true
+
+    # outputs (optional): Expected artifacts this phase produces.
+    # Used for tracking and checkpoint reporting.
+    outputs:
+      - .sniper/artifacts/{protocol_id}/design.md
+
+  # ── Phase 2: Implement ─────────────────────────────────────
+  - name: implement
+    description: Build the feature according to the plan
+
+    agents:
+      - fullstack-dev
+      - qa-engineer
+    spawn_strategy: team
+
+    # plan_approval (optional): If true, each agent must get their
+    # execution plan approved before writing code.
+    plan_approval: true
+
+    gate:
+      checklist: implement
+      human_approval: false
+
+    outputs:
+      - source code changes
+      - test files
+
+    # coordination (optional): Constraints between agents in team phases.
+    # Only meaningful when spawn_strategy is "team".
+    # coordination:
+    #   - between: [fullstack-dev, qa-engineer]
+    #     topic: Tests must cover all new public APIs
+
+  # ── Phase 3: Review ────────────────────────────────────────
+  - name: review
+    description: Code review and final quality check
+
+    agents:
+      - code-reviewer
+    spawn_strategy: single
+
+    gate:
+      checklist: review
+      human_approval: true
+
+    outputs:
+      - .sniper/artifacts/{protocol_id}/review-report.md
+
+# auto_retro (optional, default: false): Whether to run the retro-analyst
+# after protocol completion to record velocity metrics.
+auto_retro: true

package/templates/knowledge-manifest.yaml

@@ -0,0 +1,32 @@
+# Knowledge Manifest — domain knowledge sources for agent injection
+# Place this file at .sniper/knowledge/manifest.yaml
+# Agents consult this manifest to load relevant domain context before execution
+
+# Each source entry declares a Markdown file containing domain expertise.
+# During protocol execution, agents match their task context against topics
+# and tags to selectively load only the knowledge they need.
+
+sources:
+  # topic:       Short identifier for the knowledge domain
+  # file:        Path relative to .sniper/knowledge/
+  # tokens:      Estimated token count (used for budget planning — measure with `wc -w file | awk '{print int($1 * 1.3)}'`)
+  # tags:        Searchable labels for contextual matching (optional)
+  # description: What this knowledge covers, so agents know when to load it (optional)
+
+  - topic: "telephony"
+    file: "telephony-protocols.md"
+    tokens: 2500
+    tags: [voip, sip, pbx, otp]
+    description: "VoIP telephony protocols, SIP signaling, and PBX integration patterns"
+
+  - topic: "compliance"
+    file: "tcpa-rules.md"
+    tokens: 1800
+    tags: [tcpa, compliance, legal, consent]
+    description: "TCPA compliance rules for outbound dialing and consent management"
+
+  - topic: "crm"
+    file: "crm-integration.md"
+    tokens: 1200
+    tags: [salesforce, hubspot, api, leads]
+    description: "CRM integration patterns, lead lifecycle, and API conventions"

package/templates/live-status.yaml

@@ -0,0 +1,26 @@
+# Real-time protocol progress
+protocol: ""
+status: ""  # idle | running | paused | completed | failed
+current_phase: ""
+started_at: ""
+updated_at: ""
+
+phases:
+  - name: ""
+    status: ""  # pending | running | paused | completed | failed
+    agents: []
+    # - name: analyst
+    #   status: active | completed | failed
+    progress: 0  # percentage
+
+gate_results: []
+# - phase: discover
+#   result: pass
+#   timestamp: ""
+
+cost:
+  tokens_used: 0
+  budget: 0
+  percent: 0
+
+next_action: ""  # Human-readable description of what's next

package/templates/multi-faceted-review-report.md

@@ -0,0 +1,28 @@
+# Multi-Faceted Review Report
+<!-- Budget: 2000 tokens max -->
+
+## Summary
+<!-- ~200 tokens: Overall assessment across all dimensions -->
+
+## Scope Validation
+<!-- ~400 tokens: Does the implementation match requirements? -->
+| Requirement | Status | Notes |
+|-------------|--------|-------|
+
+## Standards Enforcement
+<!-- ~400 tokens: Does the code follow project conventions? -->
+| Standard | Status | Finding |
+|----------|--------|---------|
+
+## Risk Assessment
+<!-- ~400 tokens: Security, performance, reliability, and maintenance risks -->
+| Risk | Severity | Mitigation |
+|------|----------|------------|
+
+## Overall Risk Score
+<!-- ~200 tokens: Aggregate risk level (critical/high/medium/low) with justification -->
+
+**Risk Level:** <!-- critical | high | medium | low -->
+
+## Decision
+<!-- ~200 tokens: APPROVE / REQUEST_CHANGES / COMMENT with reasoning -->

package/templates/registry.md

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

package/templates/review-report.md

@@ -0,0 +1,25 @@
+# Review Report
+<!-- Budget: 1000 tokens max -->
+
+## Summary
+<!-- ~200 tokens: Overall assessment — pass/fail with brief rationale -->
+
+## Checks
+<!-- ~300 tokens: Checklist results -->
+| Check | Status | Notes |
+|-------|--------|-------|
+
+## Findings
+<!-- ~400 tokens: Issues found, categorized by severity -->
+
+### Blocking
+<!-- Must fix before merge -->
+
+### Suggestions
+<!-- Should fix, but not blocking -->
+
+### Nits
+<!-- Optional improvements -->
+
+## Decision
+<!-- ~100 tokens: APPROVE / REQUEST_CHANGES / COMMENT -->

package/templates/signal-record.yaml

@@ -0,0 +1,37 @@
+# Signal Record — captures an external learning for future agent context
+#
+# Signals are stored in .sniper/memory/signals/ and are ingested from
+# CI failures, PR review comments, production errors, or manually.
+# Agents query relevant signals before implementation to avoid repeating mistakes.
+
+# Required: one of ci_failure | pr_review_comment | production_error | manual
+type: ci_failure
+
+# Required: where this signal originated (e.g., "github-actions", "pr-42", "datadog")
+source: github-actions
+
+# Required: ISO 8601 timestamp of when the signal was observed
+timestamp: "2026-01-15T10:30:00Z"
+
+# Required: one-line summary of what happened
+summary: "Jest test suite failed — missing mock for PaymentService"
+
+# Optional: full error message, review comment text, or stack trace
+details: |
+  FAIL src/services/payment.test.ts
+  TypeError: Cannot read properties of undefined (reading 'charge')
+  Expected PaymentService to be mocked in test setup.
+
+# Optional: the takeaway to apply in future work
+learning: "Always mock external service dependencies in unit tests before calling the handler."
+
+# Optional: tags for matching this signal to relevant agent context
+relevance_tags:
+  - testing
+  - mocking
+  - payment-service
+
+# Optional: file paths that were involved
+affected_files:
+  - src/services/payment.test.ts
+  - src/services/payment.ts

package/templates/spec.md

@@ -0,0 +1,28 @@
+# Specification
+<!-- Budget: 3000 tokens max -->
+
+## 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
+<!-- ~1000 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 -->
+
+## Success Metrics
+<!-- ~200 tokens: How we measure success -->
+
+## Open Questions
+<!-- ~200 tokens: Unresolved questions that need answers before planning -->

package/templates/story.md

@@ -0,0 +1,19 @@
+# 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]
+2. The system shall [action]
+3. If [condition], then the system shall [action]
+
+## Technical Notes
+<!-- ~300 tokens: Implementation hints, relevant code locations, gotchas -->

package/templates/velocity.yaml

@@ -0,0 +1,9 @@
+# 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: {}

package/templates/workspace-config.yaml

@@ -0,0 +1,44 @@
+# SNIPER Workspace Configuration
+# Place this file at .sniper-workspace/config.yaml in your workspace root.
+# A workspace coordinates multiple SNIPER-enabled projects that share
+# conventions, architectural decisions, and memory.
+
+# Workspace name — used in status output and logs
+name: "my-workspace"
+
+# Projects managed by this workspace.
+# Each entry maps a logical name to a relative directory path.
+projects:
+  - name: api
+    path: ./services/api       # relative to workspace root
+    type: api                  # optional label (api, frontend, library, cli, etc.)
+  - name: web
+    path: ./apps/web
+    type: frontend
+
+# Shared conventions and decisions applied to every project in the workspace.
+# These supplement (not replace) each project's own .sniper/config.yaml.
+shared:
+  # Coding conventions enforced across all projects
+  conventions:
+    - "All public APIs must have OpenAPI specs"
+    - "Use structured logging (JSON) in all services"
+    - "Error responses follow RFC 7807 Problem Details"
+
+  # Patterns to avoid workspace-wide
+  anti_patterns:
+    - "No direct database access from frontend projects"
+    - "No shared mutable state between services"
+
+  # Architecture Decision Records
+  architectural_decisions:
+    - id: ADR-001
+      title: Event-driven communication between services
+      decision: Use an event bus for inter-service communication instead of direct HTTP calls.
+      rationale: Reduces coupling and improves resilience when services are unavailable.
+      date: "2025-12-01"
+
+# Shared memory directory for cross-project context.
+# Agents can read from this directory to understand workspace-wide patterns.
+memory:
+  directory: .sniper-workspace/memory

package/framework/checklists/code-review.md

@@ -1,33 +0,0 @@
-# Per-Story Code Review Checklist
-
-Used by QA engineer and team lead to review individual story implementations.
-
-## Functionality
-- [ ] All acceptance criteria from the story are implemented
-- [ ] Error cases are handled (not just the happy path)
-- [ ] Edge cases considered (empty input, max values, concurrent access)
-
-## Code Quality
-- [ ] Code is readable — another developer can understand it without explanation
-- [ ] No dead code, commented-out code, or TODO items left behind
-- [ ] Functions are focused — each does one thing
-- [ ] Naming is clear and consistent with codebase conventions
-- [ ] No unnecessary complexity — simplest solution that works
-
-## Testing
-- [ ] Unit tests cover the public API of new modules
-- [ ] Integration tests verify end-to-end behavior
-- [ ] Tests are deterministic (no timing dependencies, no flakiness)
-- [ ] Test names describe the behavior being tested
-
-## Security
-- [ ] User input is validated before processing
-- [ ] SQL queries use parameterized statements
-- [ ] No secrets in code or config
-- [ ] Auth checks in place for protected endpoints
-
-## Performance
-- [ ] No N+1 query patterns
-- [ ] Database queries are indexed appropriately
-- [ ] Large datasets use pagination
-- [ ] No blocking operations on the main thread

package/framework/checklists/debug-review.md

@@ -1,34 +0,0 @@
-# Debug Review Checklist
-
-Use this checklist to review artifacts produced during a bug investigation.
-
-## Bug Report (`docs/bugs/BUG-{NNN}/report.md`)
-
-- [ ] **Summary clarity:** Bug is described in terms of observed behavior, not implementation
-- [ ] **Severity justified:** Severity level matches the described user impact
-- [ ] **Affected components identified:** Components are traced to actual architecture doc entries
-- [ ] **Reproduction steps:** Steps are specific enough to reproduce (or clearly marked "unable to determine")
-- [ ] **Investigation plan:** Specific guidance for log analyst and code investigator
-
-## Investigation (`docs/bugs/BUG-{NNN}/investigation.md`)
-
-- [ ] **Log findings present:** Error patterns documented with specific messages and locations
-- [ ] **Code findings present:** Execution path traced with file:line references
-- [ ] **Root cause identified:** A specific root cause is proposed (not vague)
-- [ ] **Evidence-based:** Findings are backed by specific code references, not speculation
-- [ ] **Recommended fix:** A concrete fix approach is proposed
-- [ ] **Consistency:** Log findings and code findings point to the same root cause
-
-## Post-Mortem (`docs/bugs/BUG-{NNN}/postmortem.md`)
-
-- [ ] **Fix addresses root cause:** The fix targets the actual root cause, not just symptoms
-- [ ] **Files changed listed:** All modified files are documented
-- [ ] **Regression tests added:** Tests specifically prevent this bug from recurring
-- [ ] **Prevention strategy:** At least one process or code change to prevent similar bugs
-- [ ] **Timeline accurate:** Key events are timestamped
-
-## Overall
-
-- [ ] **Artifacts consistent:** Report, investigation, and postmortem tell a coherent story
-- [ ] **No speculation presented as fact:** Hypotheses are clearly labeled
-- [ ] **Actionable:** Another developer could understand and verify the fix

package/framework/checklists/discover-review.md

@@ -1,33 +0,0 @@
-# Discovery Review Checklist
-
-Gate mode: **FLEXIBLE** (auto-advance, async review)
-
-## Project Brief (`docs/brief.md`)
-- [ ] Problem statement is specific and evidence-based
-- [ ] At least 3 direct competitors identified with features and pricing
-- [ ] Unique value proposition clearly differentiates from competitors
-- [ ] Target market segment is defined with size estimates
-- [ ] Key assumptions are listed explicitly
-- [ ] Technical constraints are identified
-- [ ] v1 scope recommendation separates in-scope from out-of-scope
-- [ ] Open questions are documented for planning phase
-
-## Risk Assessment (`docs/risks.md`)
-- [ ] Technical feasibility risks are identified with specifics
-- [ ] Integration risks are assessed (third-party APIs, services)
-- [ ] Compliance and regulatory risks are documented
-- [ ] Scalability concerns are noted with thresholds
-- [ ] Each risk has a mitigation strategy
-- [ ] Assumptions are challenged — at least 2 devil's advocate findings
-
-## User Personas (`docs/personas.md`)
-- [ ] At least 2 distinct user personas defined
-- [ ] Each persona has: role, goals, pain points, workflows
-- [ ] Primary user journey mapped for each persona
-- [ ] Key friction points identified
-- [ ] Personas are realistic (not idealized)
-
-## Overall
-- [ ] All three artifacts are internally consistent
-- [ ] No critical contradictions between brief, risks, and personas
-- [ ] Sufficient depth for planning phase to begin