@sniper.ai/core 1.0.1 → 3.0.0

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,18 @@
+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:
+      - docs/spec.md
+      - docs/codebase-overview.md
+
+auto_retro: false  # Exploration doesn't need retros

package/protocols/feature.yaml

@@ -0,0 +1,45 @@
+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: team
+    gate:
+      checklist: plan
+      human_approval: true
+    outputs:
+      - docs/architecture.md
+      - docs/prd.md
+      - docs/stories/
+
+  - name: implement
+    description: Feature implementation
+    agents:
+      - fullstack-dev
+      - qa-engineer
+    spawn_strategy: team
+    plan_approval: true
+    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:
+      - docs/review-report.md
+
+auto_retro: true

package/protocols/full.yaml

@@ -0,0 +1,63 @@
+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:
+      - docs/spec.md
+      - docs/codebase-overview.md
+
+  - name: plan
+    description: Architecture design, PRD creation, story breakdown
+    agents:
+      - architect
+      - product-manager
+    spawn_strategy: team  # Multiple agents, use TeamCreate
+    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:
+      - docs/architecture.md
+      - docs/prd.md
+      - docs/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
+    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:
+      - docs/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,39 @@
+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:
+      - docs/codebase-overview.md
+
+  - name: document
+    description: Generate documentation from code analysis
+    agents:
+      - analyst
+    spawn_strategy: single
+    gate:
+      checklist: ingest-document
+      human_approval: false
+    outputs:
+      - docs/spec.md
+
+  - 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
+
+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:
+      - docs/review-report.md
+
+auto_retro: false  # Patches are too small for retros

package/protocols/refactor.yaml

@@ -0,0 +1,41 @@
+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
+    gate:
+      checklist: refactor-analyze
+      human_approval: false
+    outputs:
+      - docs/spec.md
+
+  - name: implement
+    description: Apply refactoring changes
+    agents:
+      - fullstack-dev
+    spawn_strategy: single
+    plan_approval: false
+    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:
+      - docs/review-report.md
+
+auto_retro: true

package/schemas/checkpoint.schema.yaml

@@ -0,0 +1,133 @@
+$schema: "https://json-schema.org/draft/2020-12/schema"
+$id: "https://sniper.ai/schemas/checkpoint"
+title: Phase Checkpoint
+description: Schema for SNIPER phase checkpoint files that track progress through lifecycle phases.
+type: object
+required:
+  - protocol
+  - phase
+  - timestamp
+  - status
+properties:
+  protocol:
+    type: string
+    description: The SNIPER protocol version identifier.
+  phase:
+    type: string
+    description: The lifecycle phase this checkpoint belongs to (e.g. discover, plan, implement, review).
+  timestamp:
+    type: string
+    format: date-time
+    description: ISO 8601 timestamp of when this checkpoint was recorded.
+  status:
+    type: string
+    enum:
+      - in_progress
+      - completed
+      - failed
+    description: Current status of the phase.
+  agents:
+    type: array
+    description: List of agents participating in this phase.
+    items:
+      type: object
+      required:
+        - name
+        - status
+        - tasks_completed
+        - tasks_total
+      properties:
+        name:
+          type: string
+          description: Agent persona name.
+        status:
+          type: string
+          enum:
+            - active
+            - completed
+            - failed
+          description: Current status of the agent.
+        tasks_completed:
+          type: integer
+          minimum: 0
+          description: Number of tasks the agent has completed.
+        tasks_total:
+          type: integer
+          minimum: 0
+          description: Total number of tasks assigned to the agent.
+  gate_result:
+    oneOf:
+      - type: "null"
+      - type: object
+        required:
+          - result
+          - blocking_failures
+        properties:
+          result:
+            type: string
+            enum:
+              - pass
+              - fail
+            description: Overall gate review result.
+          blocking_failures:
+            type: integer
+            minimum: 0
+            description: Number of blocking check failures.
+    description: Gate review result, or null if the gate has not been run yet.
+  artifacts_produced:
+    type: array
+    description: List of artifacts produced during this phase.
+    items:
+      type: object
+      required:
+        - path
+        - status
+      properties:
+        path:
+          type: string
+          description: File path of the produced artifact.
+        status:
+          type: string
+          enum:
+            - 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.
+    items:
+      type: object
+      required:
+        - sha
+        - message
+        - agent
+      properties:
+        sha:
+          type: string
+          description: Git commit SHA.
+        message:
+          type: string
+          description: Commit message.
+        agent:
+          type: string
+          description: Agent that produced this commit.
+  notes:
+    type: string
+    description: Free-form notes about the checkpoint.
+additionalProperties: false

package/schemas/cost.schema.yaml

@@ -0,0 +1,97 @@
+$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/dependency-graph.schema.yaml

@@ -0,0 +1,37 @@
+$schema: "https://json-schema.org/draft/2020-12/schema"
+$id: "https://sniper.ai/schemas/dependency-graph"
+title: Cross-Project Dependency Graph
+description: Schema for tracking API dependencies between projects in a SNIPER workspace.
+type: object
+required:
+  - projects
+properties:
+  projects:
+    type: array
+    items:
+      type: object
+      required: [name, exports, imports]
+      properties:
+        name:
+          type: string
+        exports:
+          type: array
+          items:
+            type: object
+            required: [api, file]
+            properties:
+              api: { type: string, description: "API endpoint or export name" }
+              file: { type: string, description: "Source file path" }
+              version: { type: string }
+        imports:
+          type: array
+          items:
+            type: object
+            required: [api, from_project]
+            properties:
+              api: { type: string }
+              from_project: { type: string }
+  updated_at:
+    type: string
+    format: date-time
+additionalProperties: false

package/schemas/gate-result.schema.yaml

@@ -0,0 +1,101 @@
+$schema: "https://json-schema.org/draft/2020-12/schema"
+$id: "https://sniper.ai/schemas/gate-result"
+title: Gate Result
+description: Schema for SNIPER gate review results that determine whether a phase passes its quality gate.
+type: object
+required:
+  - gate
+  - timestamp
+  - result
+  - blocking_failures
+  - total_checks
+properties:
+  gate:
+    type: string
+    description: The phase name this gate review applies to.
+  timestamp:
+    type: string
+    format: date-time
+    description: ISO 8601 timestamp of when the gate review was performed.
+  result:
+    type: string
+    enum:
+      - pass
+      - fail
+    description: Overall gate review result.
+  checks:
+    type: array
+    description: Individual check results that make up the gate review.
+    items:
+      type: object
+      required:
+        - id
+        - status
+        - blocking
+        - output
+      properties:
+        id:
+          type: string
+          description: Unique identifier for this check.
+        status:
+          type: string
+          enum:
+            - pass
+            - fail
+          description: Whether this individual check passed or failed.
+        blocking:
+          type: boolean
+          description: Whether this check is a blocking check (failure prevents gate pass).
+        output:
+          type: string
+          description: Descriptive output or message from the check.
+  blocking_failures:
+    type: integer
+    minimum: 0
+    description: Number of blocking checks that failed.
+  total_checks:
+    type: integer
+    minimum: 0
+    description: Total number of checks that were evaluated.
+  model_results:
+    type: array
+    description: Individual model assessments when multi-model review is enabled.
+    items:
+      type: object
+      required:
+        - model
+        - result
+        - timestamp
+      properties:
+        model:
+          type: string
+          description: Model identifier used for this assessment.
+        result:
+          type: string
+          enum:
+            - pass
+            - fail
+          description: This model's gate result.
+        checks:
+          type: array
+          description: Check results from this model's assessment.
+          items:
+            type: object
+            properties:
+              id:
+                type: string
+              status:
+                type: string
+                enum:
+                  - pass
+                  - fail
+              output:
+                type: string
+        timestamp:
+          type: string
+          format: date-time
+          description: When this model's assessment was performed.
+  consensus:
+    type: boolean
+    description: Whether all models agreed on the result. Only present when multi-model review is enabled.
+additionalProperties: false