@sniper.ai/core 1.0.1 → 3.0.0

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:
+      - docs/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:
+      - docs/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/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/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

package/framework/checklists/doc-review.md

@@ -1,39 +0,0 @@
-# Documentation Review Checklist
-
-Gate mode: **FLEXIBLE** (auto-advance, async review)
-
-## README.md
-- [ ] Has a clear one-line project description
-- [ ] Quick-start instructions use real commands that work from project root
-- [ ] Prerequisites list actual runtime requirements with versions
-- [ ] Features list matches actual project capabilities
-- [ ] Tech stack table is accurate
-- [ ] Project structure tree matches actual directory layout
-- [ ] No placeholder text or unfilled template sections
-
-## Setup Guide (`docs/setup.md`)
-- [ ] Installation steps produce a running environment
-- [ ] Environment variables documented with descriptions
-- [ ] Database setup instructions are complete (if applicable)
-- [ ] All referenced scripts and commands exist
-
-## Architecture Overview (`docs/architecture.md`)
-- [ ] Component diagram or description matches actual codebase
-- [ ] Data flow description is accurate
-- [ ] Technology choices listed match actual stack
-- [ ] Directory structure matches reality
-
-## API Reference (`docs/api.md`)
-- [ ] All public endpoints are documented
-- [ ] Request/response examples use realistic data
-- [ ] Authentication method is accurately described
-- [ ] Error codes match actual API behavior
-
-## General Quality
-- [ ] All code examples are syntactically valid
-- [ ] All internal links between docs resolve correctly
-- [ ] Consistent terminology across all documentation
-- [ ] No contradictions between docs
-- [ ] No TODO markers or placeholder text remaining
-- [ ] Managed section tags (`<!-- sniper:managed -->`) are properly formed
-- [ ] Documentation is concise — no filler or marketing language

package/framework/checklists/plan-review.md

@@ -1,52 +0,0 @@
-# Planning Review Checklist
-
-Gate mode: **STRICT** (human MUST approve before Phase 3)
-
-## PRD (`docs/prd.md`)
-- [ ] Problem statement includes evidence (not just assertions)
-- [ ] User stories follow "As a [persona], I want, so that" format
-- [ ] P0 requirements are minimal — only what's critical for v1
-- [ ] Every requirement has testable acceptance criteria
-- [ ] Non-functional requirements have specific measurable targets
-- [ ] Success metrics have numbers (not vague "improve X")
-- [ ] Out-of-scope explicitly names features users might expect
-- [ ] No duplicate requirements
-
-## Architecture (`docs/architecture.md`)
-- [ ] Every technology choice includes: what, why, alternatives considered
-- [ ] Component diagram shows clear boundaries and interfaces
-- [ ] Data models include field types, constraints, indexes, relationships
-- [ ] API contracts are specific enough for independent frontend/backend implementation
-- [ ] Infrastructure specifies sizing, scaling triggers, cost estimates
-- [ ] Cross-cutting concerns addressed (auth, logging, errors, config)
-- [ ] Non-functional targets have implementation strategies
-- [ ] Security architecture aligns with `docs/security.md`
-
-## UX Specification (`docs/ux-spec.md`)
-- [ ] Information architecture maps all pages/views
-- [ ] Screen inventory covers all user-facing screens
-- [ ] User flows include error paths, not just happy paths
-- [ ] Component specs include all states (default, hover, active, disabled, loading, error)
-- [ ] Responsive breakpoints specify actual layout changes
-- [ ] Accessibility requirements name specific WCAG criteria
-- [ ] UX flows align with PRD user stories
-
-## Security Requirements (`docs/security.md`)
-- [ ] Authentication model specified (OAuth, JWT, session, etc.)
-- [ ] Authorization model specified (RBAC, ABAC, etc.)
-- [ ] Data encryption strategy covers at-rest and in-transit
-- [ ] Compliance requirements name specific regulations
-- [ ] Threat model identifies top attack vectors
-- [ ] Security testing requirements are defined
-
-## Cross-Document Consistency
-- [ ] Architecture API contracts match UX component data needs
-- [ ] Security requirements are implementable within architecture choices
-- [ ] PRD requirements are fully coverable by architecture design
-- [ ] No orphaned requirements (in PRD but not in architecture)
-
-## Approval
-**Reviewer:** _______________
-**Date:** _______________
-**Decision:** APPROVED / NEEDS REVISION
-**Feedback:**

package/framework/checklists/sprint-review.md

@@ -1,41 +0,0 @@
-# Sprint Review Checklist
-
-Gate mode: **STRICT** (human MUST review code before merge)
-
-## Code Quality
-- [ ] All code passes linting (no warnings or errors)
-- [ ] All code passes static type checking (language-appropriate strict mode)
-- [ ] No type escape hatches introduced (e.g. `any` in TS, `Any` in Python, `interface{}` in Go)
-- [ ] No hardcoded secrets, API keys, or credentials
-- [ ] Error handling on all async operations
-- [ ] Follows existing codebase patterns and conventions
-
-## Testing
-- [ ] All stories have corresponding tests
-- [ ] Tests pass (0 failures)
-- [ ] Test coverage meets project minimum threshold
-- [ ] Integration tests cover API endpoints
-- [ ] Edge cases and error paths are tested
-- [ ] No flaky tests introduced
-
-## Acceptance Criteria
-- [ ] Every acceptance criterion from every sprint story is verified
-- [ ] Deviations from acceptance criteria are documented and justified
-
-## Architecture Compliance
-- [ ] Code follows the architecture patterns from `docs/architecture.md`
-- [ ] API contracts match the spec (endpoints, payloads, status codes)
-- [ ] Data models match the schema design
-- [ ] File ownership boundaries respected (no cross-boundary edits)
-
-## Security
-- [ ] No new security vulnerabilities introduced (OWASP Top 10)
-- [ ] Input validation on all user-facing endpoints
-- [ ] Authentication and authorization enforced where required
-- [ ] Sensitive data encrypted and handled properly
-
-## Approval
-**Reviewer:** _______________
-**Date:** _______________
-**Decision:** APPROVED / NEEDS REVISION
-**Feedback:**

package/framework/checklists/story-review.md

@@ -1,30 +0,0 @@
-# Story Review Checklist
-
-Gate mode: **FLEXIBLE** (auto-advance, async review)
-
-## Epic Structure (`docs/epics/*.md`)
-- [ ] Epics number between 6-12 (enough granularity, not too fragmented)
-- [ ] No overlap between epics — each requirement maps to exactly one epic
-- [ ] Epic dependencies form a DAG (no circular dependencies)
-- [ ] Each epic has clear scope boundaries (in/out)
-- [ ] Architecture context is EMBEDDED in each epic, not just referenced
-- [ ] Complexity estimates are realistic
-
-## Story Quality (`docs/stories/*.md`)
-- [ ] Each story is self-contained — a developer can implement from the story file alone
-- [ ] PRD context is EMBEDDED (copied), not just referenced
-- [ ] Architecture context is EMBEDDED (data models, API contracts, patterns)
-- [ ] UX context is EMBEDDED for frontend stories
-- [ ] Acceptance criteria use Given/When/Then format
-- [ ] Every acceptance criterion is testable
-- [ ] Test requirements are specified (unit, integration, e2e)
-- [ ] File ownership is assigned (which directories the story touches)
-- [ ] Dependencies on other stories are declared
-- [ ] Complexity estimate (S/M/L/XL) is assigned
-- [ ] No story is XL — if so, it should be split
-
-## Coverage
-- [ ] All P0 PRD requirements are covered by stories
-- [ ] All P1 PRD requirements are covered by stories
-- [ ] All architecture components have at least one implementing story
-- [ ] Story dependency chains allow reasonable sprint planning

package/framework/claude-md.template

@@ -1,37 +0,0 @@
-# SNIPER Project
-
-## Framework
-This project uses SNIPER (Spawn, Navigate, Implement, Parallelize, Evaluate, Release).
-See `.sniper/config.yaml` for project settings.
-
-## Quick Reference
-- Framework workflows: `.sniper/workflows/`
-- Persona layers: `.sniper/personas/`
-- Team definitions: `.sniper/teams/`
-- Artifact templates: `.sniper/templates/`
-- Quality gates: `.sniper/checklists/`
-- Project artifacts: `docs/`
-- Domain context: `.sniper/domain-packs/{pack-name}/`
-
-## Commands
-- `/sniper-init` — Initialize SNIPER in a new project
-- `/sniper-discover` — Phase 1: Discovery & Analysis (parallel team)
-- `/sniper-plan` — Phase 2: Planning & Architecture (parallel team)
-- `/sniper-solve` — Phase 3: Epic Sharding & Story Creation (sequential)
-- `/sniper-sprint` — Phase 4: Implementation Sprint (parallel team)
-- `/sniper-review` — Run review gate for current phase
-- `/sniper-compose` — Create a spawn prompt from persona layers
-- `/sniper-status` — Show lifecycle status and artifact state
-
-## Agent Teams Rules
-When spawning teammates, always:
-1. Read the relevant team YAML from `.sniper/teams/`
-2. Compose spawn prompts using `/sniper-compose` with the layers specified in the YAML
-3. Assign file ownership boundaries from `config.yaml` ownership rules
-4. Create tasks with dependencies from the team YAML
-5. Enter delegate mode (Shift+Tab) — the lead coordinates, it does not code
-6. Require plan approval for tasks marked `plan_approval: true`
-7. When a phase completes, run `/sniper-review` before advancing
-
-## Code Standards
-See `.sniper/config.yaml` → stack section for language/framework specifics.