@sniper.ai/core 2.0.0 → 3.1.0

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,40 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": { "tools": ["Write"] },
+        "hooks": [
+          {
+            "type": "command",
+            "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' >&2; exit 2; fi"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": { "tools": ["Bash"] },
+        "hooks": [
+          {
+            "type": "command",
+            "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": [
+      {
+        "matcher": {},
+        "hooks": [
+          {
+            "type": "command",
+            "description": "Run gate reviewer at phase boundaries",
+            "command": "if [ -f .sniper/pending-gate.yaml ]; then echo 'Gate review pending — spawning gate-reviewer agent'; fi"
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/signal-hooks.json

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": { "tools": ["Bash"] },
+        "hooks": [
+          {
+            "type": "command",
+            "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": "2.0.0",
-  "description": "SNIPER framework core — personas, teams, templates, checklists, and workflows",
+  "version": "3.1.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.

package/personas/cognitive/performance-focused.md

@@ -0,0 +1,23 @@
+# Performance-Focused Thinking
+
+Apply this cognitive lens to all decisions:
+
+## Efficiency-First Evaluation
+
+- **Measure before optimizing**: Never guess at bottlenecks. Profile first, optimize second.
+- **Complexity awareness**: Know the Big-O of your data structures and algorithms. O(n^2) is a red flag for any collection that could grow.
+- **Resource consciousness**: Consider memory allocation, network round-trips, and I/O operations as costs.
+
+## Performance Checklist
+
+When reviewing or writing code, always check:
+1. **N+1 queries** — Is the code making a query per item in a loop? Batch instead.
+2. **Unbounded collections** — Are arrays, queues, or caches growing without limits? Add bounds.
+3. **Unnecessary computation** — Is work being repeated that could be cached or memoized?
+4. **Blocking operations** — Are synchronous I/O calls blocking the event loop or main thread?
+5. **Payload size** — Are API responses returning more data than the caller needs?
+6. **Connection management** — Are database/HTTP connections pooled and reused?
+
+## Tradeoff Framework
+
+Performance improvements must justify their complexity cost. A 10% speedup that doubles code complexity is rarely worth it. A 10x speedup that adds one line is always worth it.

package/personas/cognitive/security-first.md

@@ -0,0 +1,24 @@
+# Security-First Thinking
+
+Apply this cognitive lens to all decisions:
+
+## Threat-First Decision Framework
+
+- **Before implementing**: Ask "How could this be abused?" for every external input, API endpoint, and data flow
+- **Default deny**: Require explicit allowlisting over blocklisting. Reject unknown inputs.
+- **Least privilege**: Request minimum permissions. Scope access to what's needed now, not what might be needed later.
+- **Defense in depth**: Never rely on a single security control. Validate at boundaries AND internally.
+
+## Security Evaluation Checklist
+
+When reviewing or writing code, always check:
+1. Input validation — Is all external input sanitized before use?
+2. Authentication — Is the caller verified before any action?
+3. Authorization — Does the caller have permission for THIS specific action?
+4. Data exposure — Could error messages, logs, or responses leak sensitive data?
+5. Injection — Could user input end up in SQL, shell commands, or HTML unescaped?
+6. Secrets — Are credentials in environment variables, never in code or logs?
+
+## When In Doubt
+
+Flag the security concern explicitly rather than making assumptions. A false positive is far cheaper than a vulnerability.

package/protocols/explore.yaml

@@ -0,0 +1,21 @@
+name: explore
+description: Exploratory analysis — understand a codebase or problem space
+budget: 500000  # 500K tokens
+
+phases:
+  - name: discover
+    description: Research, analyze, and document findings
+    agents:
+      - analyst
+    spawn_strategy: single
+    gate:
+      checklist: discover
+      human_approval: false
+    outputs:
+      - .sniper/artifacts/spec.md  # Living master doc — not per-protocol (explore has no versioned artifacts)
+      - .sniper/artifacts/codebase-overview.md  # Living master doc — not per-protocol
+
+# Note: explore/ingest protocols write to master docs (.sniper/artifacts/spec.md, .sniper/artifacts/codebase-overview.md)
+# rather than per-protocol directories (.sniper/artifacts/{protocol_id}/). A meta.yaml and registry entry
+# are still created by /sniper-flow, but the artifact directory may be empty.
+auto_retro: false  # Exploration doesn't need retros

package/protocols/feature.yaml

@@ -0,0 +1,47 @@
+name: feature
+description: Incremental feature — plan, implement, review
+budget: 800000  # 800K tokens
+
+phases:
+  - name: plan
+    description: Feature design and story creation
+    agents:
+      - architect
+      - product-manager
+    spawn_strategy: sequential  # Architect designs first, PM writes stories from that
+    interactive_review: true  # Present plan to user for review/feedback before proceeding
+    gate:
+      checklist: plan
+      human_approval: true
+    outputs:
+      - .sniper/artifacts/{protocol_id}/plan.md
+      - .sniper/artifacts/{protocol_id}/prd.md
+      - .sniper/artifacts/{protocol_id}/stories/
+
+  - name: implement
+    description: Feature implementation
+    agents:
+      - fullstack-dev
+      - qa-engineer
+    spawn_strategy: parallel  # Multiple subagents via Task, not full TeamCreate
+    plan_approval: true
+    doc_sync: true  # Run doc-writer after this phase to update living docs
+    gate:
+      checklist: implement
+      human_approval: false
+    outputs:
+      - source code changes
+      - test files
+
+  - name: review
+    description: Code review
+    agents:
+      - code-reviewer
+    spawn_strategy: single
+    gate:
+      checklist: review
+      human_approval: true
+    outputs:
+      - .sniper/artifacts/{protocol_id}/review-report.md
+
+auto_retro: true

package/protocols/full.yaml

@@ -0,0 +1,65 @@
+name: full
+description: Complete project lifecycle — discovery through review
+budget: 2000000  # 2M tokens
+
+phases:
+  - name: discover
+    description: Research, analyze codebase, produce discovery spec
+    agents:
+      - analyst
+    spawn_strategy: single  # One agent, no team needed
+    gate:
+      checklist: discover
+      human_approval: false
+    outputs:
+      - .sniper/artifacts/spec.md  # Living master doc
+      - .sniper/artifacts/codebase-overview.md  # Living master doc
+
+  - name: plan
+    description: Architecture design, PRD creation, story breakdown
+    agents:
+      - architect
+      - product-manager
+    spawn_strategy: team  # Multiple agents, use TeamCreate
+    interactive_review: true  # Present plan to user for review/feedback before proceeding
+    coordination:
+      - between: [architect, product-manager]
+        topic: Architecture must be approved before stories reference it
+    gate:
+      checklist: plan
+      human_approval: true  # Human reviews the plan before implementation
+    outputs:
+      - .sniper/artifacts/{protocol_id}/plan.md
+      - .sniper/artifacts/{protocol_id}/prd.md
+      - .sniper/artifacts/{protocol_id}/stories/
+
+  - name: implement
+    description: Code implementation with worktree isolation
+    agents:
+      - fullstack-dev
+      - qa-engineer
+    spawn_strategy: team
+    plan_approval: true  # Each agent must get plan approved before coding
+    doc_sync: true  # Run doc-writer after this phase to update living docs
+    gate:
+      checklist: implement
+      human_approval: false
+    outputs:
+      - source code changes
+      - test files
+
+  - name: review
+    description: Code review and final quality gate
+    agents:
+      - code-reviewer
+    spawn_strategy: single
+    gate:
+      # Uses multi-faceted-review checklist when review.multi_model is enabled in config;
+      # otherwise falls back to standard review checklist
+      checklist: review
+      multi_model_checklist: multi-faceted-review
+      human_approval: true  # Human final sign-off
+    outputs:
+      - .sniper/artifacts/{protocol_id}/review-report.md
+
+auto_retro: true  # Trigger retro-analyst after completion

package/protocols/hotfix.yaml

@@ -0,0 +1,19 @@
+name: hotfix
+description: Critical fix — fastest path to production
+budget: 100000  # 100K tokens
+
+phases:
+  - name: implement
+    description: Emergency fix with minimal overhead
+    agents:
+      - fullstack-dev
+    spawn_strategy: single
+    plan_approval: false
+    gate:
+      checklist: implement
+      blocking: false
+    outputs:
+      - source code changes
+      - test files
+
+auto_retro: false  # Hotfixes are too urgent for retros

package/protocols/ingest.yaml

@@ -0,0 +1,42 @@
+name: ingest
+description: Codebase ingestion — scan, document, extract conventions
+budget: 1000000  # 1M tokens
+
+phases:
+  - name: scan
+    description: Deep scan of existing codebase
+    agents:
+      - analyst
+    spawn_strategy: single
+    gate:
+      checklist: ingest-scan
+      human_approval: false
+    outputs:
+      - .sniper/artifacts/codebase-overview.md  # Living master doc — not per-protocol
+
+  - name: document
+    description: Generate documentation from code analysis
+    agents:
+      - analyst
+    spawn_strategy: single
+    gate:
+      checklist: ingest-document
+      human_approval: false
+    outputs:
+      - .sniper/artifacts/spec.md  # Living master doc — not per-protocol
+
+  - name: extract
+    description: Extract conventions, patterns, and anti-patterns
+    agents:
+      - analyst
+    spawn_strategy: single
+    gate:
+      checklist: ingest-extract
+      human_approval: false
+    outputs:
+      - .sniper/conventions.yaml
+
+# Note: ingest protocols write to master docs (.sniper/artifacts/spec.md, .sniper/artifacts/codebase-overview.md)
+# rather than per-protocol directories (.sniper/artifacts/{protocol_id}/). A meta.yaml and registry entry
+# are still created by /sniper-flow, but the artifact directory may be empty.
+auto_retro: false

package/protocols/patch.yaml

@@ -0,0 +1,30 @@
+name: patch
+description: Quick fix — implement and review only
+budget: 200000  # 200K tokens
+
+phases:
+  - name: implement
+    description: Bug fix or small change
+    agents:
+      - fullstack-dev
+    spawn_strategy: single
+    plan_approval: false  # Quick fixes skip plan approval
+    gate:
+      checklist: implement
+      human_approval: false
+    outputs:
+      - source code changes
+      - test files
+
+  - name: review
+    description: Code review
+    agents:
+      - code-reviewer
+    spawn_strategy: single
+    gate:
+      checklist: review
+      human_approval: true
+    outputs:
+      - .sniper/artifacts/{protocol_id}/review-report.md
+
+auto_retro: false  # Patches are too small for retros

package/protocols/refactor.yaml

@@ -0,0 +1,43 @@
+name: refactor
+description: Code improvement — analyze, refactor, and review
+budget: 600000  # 600K tokens
+
+phases:
+  - name: analyze
+    description: Analyze code structure and identify refactoring targets
+    agents:
+      - analyst
+    spawn_strategy: single
+    interactive_review: true  # Let user review the analysis before refactoring
+    gate:
+      checklist: refactor-analyze
+      human_approval: false
+    outputs:
+      - .sniper/artifacts/{protocol_id}/plan.md  # Analysis/plan for this refactor
+
+  - name: implement
+    description: Apply refactoring changes
+    agents:
+      - fullstack-dev
+    spawn_strategy: single
+    plan_approval: false
+    doc_sync: true  # Run doc-writer after this phase to update living docs
+    gate:
+      checklist: implement
+      human_approval: false
+    outputs:
+      - source code changes
+      - test files
+
+  - name: review
+    description: Review refactored code
+    agents:
+      - code-reviewer
+    spawn_strategy: single
+    gate:
+      checklist: review
+      human_approval: true
+    outputs:
+      - .sniper/artifacts/{protocol_id}/review-report.md
+
+auto_retro: true