@sniper.ai/core 1.0.1 → 3.0.0

package/agents/retro-analyst.md

@@ -0,0 +1,98 @@
+---
+write_scope:
+  - ".sniper/"
+---
+
+# Retro Analyst
+
+You are a SNIPER retro analyst agent. You run automated retrospectives after protocol completion to capture lessons learned.
+
+## Responsibilities
+
+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
+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
+
+## Analysis Process
+
+1. Read `.sniper/checkpoints/` for the completed protocol's checkpoint history
+2. Read `.sniper/gates/` for gate results (pass/fail patterns)
+3. Read `.sniper/cost.yaml` for token usage data
+4. Analyze: What took the most tokens? Which gates failed first? Were there re-runs?
+5. Write retro report
+
+## Retro Report Schema
+
+```yaml
+protocol: <protocol_name>
+completed_at: <ISO 8601>
+duration_phases:
+  - phase: <name>
+    agents: <count>
+    gate_attempts: <count>
+    gate_result: pass | fail
+metrics:
+  total_tokens: <number>
+  total_agents_spawned: <number>
+  gate_pass_rate: <percentage>
+findings:
+  went_well:
+    - <finding>
+  needs_improvement:
+    - <finding>
+  action_items:
+    - <concrete suggestion>
+```
+
+## Rules
+
+- 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
+- Compare against previous retros if they exist to track trends
+
+## Signal Analysis
+
+During the retrospective, analyze external signals:
+
+1. Read `.sniper/memory/signals/` for signal records captured during this protocol execution
+2. Correlate signals with protocol phases: which CI failures occurred during which phase?
+3. Identify recurring patterns: are the same files or tests failing repeatedly?
+4. Promote high-confidence learnings: if a signal's learning applies broadly, note it in the retro findings
+5. Include signal summary in the retro report under a `signals_analyzed` section:
+   ```yaml
+   signals_analyzed:
+     total: <count>
+     by_type:
+       ci_failure: <count>
+       pr_review_comment: <count>
+     promoted_learnings:
+       - <learning that should be applied going forward>
+   ```
+
+## 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/discover.yaml

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

package/checklists/implement.yaml

@@ -0,0 +1,28 @@
+name: implement
+description: Implementation phase quality gate
+
+checks:
+  - id: tests_pass
+    description: All tests pass
+    command: "${test_command}"
+    blocking: true
+
+  - id: lint_clean
+    description: No linting errors
+    command: "${lint_command}"
+    blocking: true
+
+  - id: typecheck
+    description: Type checking passes (if applicable)
+    command: "${typecheck_command}"
+    blocking: false
+
+  - id: self_reviews_exist
+    description: Each developer ran a self-review (git diff checked)
+    check: glob:.sniper/self-reviews/*.md
+    blocking: true
+
+  - id: diff_nonempty
+    description: Implementation produced actual code changes
+    command: "git diff --stat HEAD~1 | grep -q ."
+    blocking: false

package/checklists/ingest-document.yaml

@@ -0,0 +1,18 @@
+name: ingest-document
+description: Ingest document phase quality gate — verifies spec was produced from code analysis
+
+checks:
+  - id: spec_produced
+    description: Discovery spec exists
+    check: file:docs/spec.md
+    blocking: true
+
+  - id: scope_defined
+    description: Spec defines in-scope requirements
+    check: grep:docs/spec.md:"## Requirements"
+    blocking: true
+
+  - id: out_of_scope_explicit
+    description: Spec explicitly lists out-of-scope items
+    check: grep:docs/spec.md:"## Out of Scope"
+    blocking: false

package/checklists/ingest-extract.yaml

@@ -0,0 +1,13 @@
+name: ingest-extract
+description: Ingest extract phase quality gate — verifies conventions were extracted
+
+checks:
+  - id: conventions_exist
+    description: Conventions file exists
+    check: file:.sniper/conventions.yaml
+    blocking: true
+
+  - id: conventions_nonempty
+    description: Conventions file is not empty
+    command: "test -s .sniper/conventions.yaml"
+    blocking: true

package/checklists/ingest-scan.yaml

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

package/checklists/multi-faceted-review.yaml

@@ -0,0 +1,56 @@
+name: multi-faceted-review
+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:docs/spec.md
+    blocking: true
+
+  - id: scope_acceptance_criteria
+    description: All acceptance criteria from stories are addressed
+    check: "grep:docs/stories/:shall"
+    blocking: true
+
+  - id: scope_no_creep
+    description: No undocumented features added beyond spec
+    check: file:docs/review-report.md
+    blocking: false
+
+  # Standards Enforcement — does the code follow conventions?
+  - id: standards_conventions
+    description: Code follows project conventions
+    check: file:.sniper/conventions.yaml
+    blocking: false
+
+  - id: standards_test_coverage
+    description: Tests exist for new functionality
+    command: "find . -name '*.test.*' -o -name '*.spec.*' | grep -q ."
+    blocking: true
+
+  - id: standards_lint_clean
+    description: No lint errors in changed files
+    command: "${lint_command}"
+    blocking: true
+
+  # Risk Scoring — are there security, performance, or reliability risks?
+  - id: risk_security
+    description: No OWASP Top 10 vulnerabilities detected
+    check: 'grep:docs/review-report.md:"## Security"'
+    blocking: true
+
+  - id: risk_performance
+    description: No obvious performance regressions
+    check: 'grep:docs/review-report.md:"## Performance"'
+    blocking: false
+
+  - id: risk_error_handling
+    description: Error cases are handled gracefully
+    check: 'grep:docs/review-report.md:"## Error Handling"'
+    blocking: false
+
+  - id: risk_data_integrity
+    description: No data loss or corruption risks
+    check: 'grep:docs/review-report.md:"## Data Integrity"'
+    blocking: true

package/checklists/plan.yaml

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

package/checklists/refactor-analyze.yaml

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

package/checklists/review.yaml

@@ -0,0 +1,28 @@
+name: review
+description: Review phase quality gate
+
+checks:
+  - id: gate_checks_pass
+    description: Implementation gate passed
+    check: grep:.sniper/gates/implement-*.yaml:"result: pass"
+    blocking: true
+
+  - id: spec_reconciliation
+    description: Review report confirms spec compliance
+    check: file:docs/review-report.md
+    blocking: true
+
+  - id: no_regressions
+    description: No test regressions introduced
+    command: "${test_command}"
+    blocking: true
+
+  - id: no_blocking_findings
+    description: No blocking findings in review report
+    check: "!grep:docs/review-report.md:### Blocking"
+    blocking: true
+
+  - id: spec_reconciled
+    description: Spec has been reconciled with implementation
+    check: "grep:docs/spec.md:Last reconciled:"
+    blocking: false

package/claude-md.template

@@ -0,0 +1,42 @@
+# {{PROJECT_NAME}}
+
+## SNIPER v3 Configuration
+
+This project uses the SNIPER framework for AI-assisted project lifecycle management.
+
+### Quick Start
+
+- `/sniper-flow` — Run the appropriate protocol (auto-detects scope, or use `--protocol <name>`)
+- `/sniper-flow --resume` — Resume an interrupted protocol from the last checkpoint
+- `/sniper-init` — Re-initialize or update SNIPER configuration
+- `/sniper-status` — Show current protocol progress and cost
+- `/sniper-review` — Manually trigger a review gate
+
+### Project Structure
+
+```
+.sniper/
+  config.yaml          — Project configuration
+  live-status.yaml     — Real-time protocol progress
+  checkpoints/         — Phase checkpoint snapshots
+  gates/               — Gate review results
+  retros/              — Retrospective reports
+  self-reviews/        — Developer self-review artifacts
+.claude/
+  agents/              — Agent definitions (scaffolded from @sniper.ai/core)
+  settings.json        — Claude Code settings with hooks
+```
+
+### Configuration
+
+Edit `.sniper/config.yaml` to customize:
+- Agent roster and cognitive mixins
+- Protocol routing and token budgets
+- File ownership boundaries
+- Stack-specific commands (test, lint, build)
+
+### Ownership Rules
+
+Agents respect file ownership boundaries. See `.sniper/config.yaml` `ownership` section.
+
+{{CUSTOM_INSTRUCTIONS}}

package/config.template.yaml

@@ -0,0 +1,156 @@
+# SNIPER v3 Configuration
+# Generated by `sniper init`
+
+project:
+  name: ""
+  type: ""           # saas | api | mobile | cli | library | monorepo
+  description: ""
+
+# Agent configuration
+agents:
+  max_teammates: 5
+  plan_approval: true        # Require plan approval for implementation agents
+  coordination_timeout: 30   # Seconds to wait for agent coordination
+
+  # Base agents to include (from @sniper.ai/core/agents/)
+  base:
+    - lead-orchestrator
+    - analyst
+    - architect
+    - product-manager
+    - backend-dev
+    - frontend-dev
+    - qa-engineer
+    - code-reviewer
+    - gate-reviewer
+    - retro-analyst
+
+  # Cognitive mixins applied to agents during scaffolding
+  # Format: agent-name: [mixin1, mixin2]
+  mixins: {}
+  # Example:
+  #   backend-dev: [security-first, performance-focused]
+  #   architect: [devils-advocate]
+
+# Protocol routing — how /sniper-flow selects a protocol
+routing:
+  # File-count thresholds for auto-detection
+  auto_detect:
+    patch_max_files: 5       # <= 5 files changed → patch protocol
+    feature_max_files: 20    # <= 20 files changed → feature protocol
+    # > 20 files → full protocol
+
+  # 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/**"
+#     agent: backend-dev
+#   - pattern: "*.test.ts"
+#     agent: qa-engineer
+#   - pattern: "infrastructure/**"
+#     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
+  models:                      # Models to use when multi_model is enabled
+    - opus
+    - sonnet
+  require_consensus: true      # All models must agree for a pass (false = majority wins)
+
+# File ownership boundaries
+ownership:
+  backend:
+    - "src/backend/"
+    - "src/api/"
+    - "src/services/"
+    - "src/db/"
+  frontend:
+    - "src/frontend/"
+    - "src/components/"
+    - "src/hooks/"
+    - "src/styles/"
+    - "src/pages/"
+  infrastructure:
+    - "docker/"
+    - ".github/"
+    - "infra/"
+    - "scripts/"
+  tests:
+    - "tests/"
+    - "__tests__/"
+    - "*.test.*"
+    - "*.spec.*"
+  docs:
+    - "docs/"
+
+# Stack detection hints (auto-populated by `sniper init`)
+stack:
+  language: ""
+  frontend: null
+  backend: null
+  database: null
+  infrastructure: null
+  test_runner: null
+  package_manager: ""
+  # Commands used by checklists and gate checks
+  commands:
+    test: ""
+    lint: ""
+    typecheck: ""
+    build: ""
+
+# Plugin configuration
+plugins: []
+# - name: typescript
+#   package: "@sniper.ai/plugin-typescript"
+
+# Domain knowledge configuration (Feature 9)
+# knowledge:
+#   directory: ".sniper/knowledge"
+#   manifest: "manifest.yaml"
+#   max_total_tokens: 50000
+
+# MCP Knowledge Base server (Feature 10)
+# mcp_knowledge:
+#   enabled: false
+#   directory: ".sniper/knowledge"
+#   auto_index: true
+
+# Headless / CI mode defaults (Feature 3)
+# headless:
+#   auto_approve_gates: false
+#   output_format: json
+#   log_level: info
+#   timeout_minutes: 60
+#   fail_on_gate_failure: true
+
+# Workspace reference (Feature 1)
+# workspace:
+#   ref: "../.sniper-workspace"
+
+# Visibility settings
+visibility:
+  live_status: true          # Maintain .sniper/live-status.yaml
+  checkpoints: true          # Write phase checkpoints
+  cost_tracking: true        # Track token usage
+  auto_retro: true           # Run retro after protocol completion

package/hooks/settings-hooks.json

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

package/hooks/signal-hooks.json

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

package/package.json

@@ -1,14 +1,32 @@
 {
   "name": "@sniper.ai/core",
-  "version": "1.0.1",
-  "description": "SNIPER framework core — personas, teams, templates, checklists, and workflows",
+  "version": "3.0.0",
+  "description": "SNIPER framework core — agents, skills, protocols, checklists, templates, and hooks",
   "type": "module",
   "exports": {
     "./package.json": "./package.json",
-    "./framework/*": "./framework/*"
+    "./agents/*": "./agents/*",
+    "./personas/*": "./personas/*",
+    "./skills/*": "./skills/*",
+    "./protocols/*": "./protocols/*",
+    "./checklists/*": "./checklists/*",
+    "./templates/*": "./templates/*",
+    "./hooks/*": "./hooks/*",
+    "./schemas/*": "./schemas/*",
+    "./config.template.yaml": "./config.template.yaml",
+    "./claude-md.template": "./claude-md.template"
   },
   "files": [
-    "framework"
+    "agents",
+    "personas",
+    "skills",
+    "protocols",
+    "checklists",
+    "templates",
+    "hooks",
+    "schemas",
+    "config.template.yaml",
+    "claude-md.template"
   ],
   "keywords": [
     "sniper",
@@ -16,7 +34,7 @@
     "claude",
     "framework",
     "agent",
-    "personas"
+    "protocol"
   ],
   "license": "MIT",
   "repository": {

package/personas/cognitive/devils-advocate.md

@@ -0,0 +1,24 @@
+# Devil's Advocate Thinking
+
+Apply this cognitive lens to all decisions:
+
+## Assumption-Challenging Framework
+
+- **Question the happy path**: For every design or implementation, ask "What happens when this fails?"
+- **Challenge consensus**: When everyone agrees, ask "What are we all missing?"
+- **Stress test assumptions**: Find the input, load, or scenario that breaks the assumption.
+- **Identify single points of failure**: What one thing, if it breaks, takes everything down?
+
+## Edge Case Identification
+
+When reviewing or writing code, actively seek:
+1. **Boundary values** — Empty strings, zero, negative numbers, max int, null, undefined
+2. **Timing issues** — Race conditions, out-of-order events, stale data, clock skew
+3. **Scale breaks** — What happens at 10x current load? 100x? What about zero items?
+4. **Partial failures** — Network timeouts mid-operation, partial writes, interrupted transactions
+5. **State corruption** — What if the system crashes between step 2 and step 3?
+6. **User misbehavior** — Duplicate submissions, back button, multiple tabs, copy-paste attacks
+
+## Constructive Dissent
+
+The goal is not to block progress but to surface risks early. Every challenge should come with a concrete scenario, not vague doubt. "This could fail if X" is useful. "This seems risky" is not.