@sniper.ai/core 1.0.0 → 2.0.0

package/framework/teams/test.yaml

@@ -0,0 +1,59 @@
+# ─────────────────────────────────────────
+# SNIPER Test & Coverage Audit Team
+# Structured test quality analysis
+# ─────────────────────────────────────────
+
+# Phase 1 (Analysis) spawns 2 agents in parallel:
+#   - coverage-analyst: identifies coverage gaps ranked by risk
+#   - flake-hunter: investigates flaky tests and diagnoses root causes
+#
+# Phase 2 (Planning) is run by the lead to generate improvement stories.
+# Phase 3 (Execution) uses the standard sprint infrastructure.
+#
+# This team YAML is used by /sniper-audit --target tests.
+
+team_name: sniper-test-audit-{audit_id}
+description: "Test & Coverage Audit: {audit_title}"
+model_override: null
+
+teammates:
+  - name: coverage-analyst
+    compose:
+      process: coverage-analyst
+      technical: null
+      cognitive: systems-thinker
+    tasks:
+      - id: coverage-analysis
+        name: "Coverage Gap Analysis"
+        description: >
+          Analyze test coverage across the codebase. Identify untested code paths,
+          rank coverage gaps by risk (business-critical paths first), and produce
+          a coverage report with prioritized recommendations for new tests.
+        output: coverage-report.md
+        blocked_by: []
+        plan_approval: false
+
+  - name: flake-hunter
+    compose:
+      process: flake-hunter
+      technical: null
+      cognitive: devils-advocate
+    tasks:
+      - id: flake-investigation
+        name: "Flaky Test Investigation"
+        description: >
+          Investigate flaky tests in the test suite. Identify tests with
+          non-deterministic behavior, diagnose root causes (timing, shared state,
+          external dependencies), and produce a report with specific fixes for
+          each flaky test.
+        output: flaky-report.md
+        blocked_by: []
+        plan_approval: false
+
+# Phase 3 (Execution) reuses sprint teammates from sprint.yaml
+
+coordination: []
+
+review_gate:
+  checklist: .sniper/checklists/test-review.md
+  mode: flexible

package/framework/teams/workspace-feature.yaml

@@ -0,0 +1,69 @@
+team_name: sniper-workspace-feature
+phase: workspace-feature
+
+teammates:
+  - name: orchestrator
+    compose:
+      process: workspace-orchestrator
+      technical: null
+      cognitive: systems-thinker
+      domain: null
+    tasks:
+      - id: workspace-brief
+        name: "Workspace Feature Brief"
+        output: "features/WKSP-{XXXX}/brief.md"
+        template: ".sniper/templates/workspace-brief.md"
+        reads:
+          - "workspace.yaml"
+          - "repositories/*/docs/architecture.md"
+        plan_approval: true
+        description: >
+          Analyze the workspace to determine which repositories are affected by the
+          feature. Read each repo's architecture docs. Produce a workspace feature
+          brief that identifies affected repos, required interface changes, and
+          implementation wave ordering based on the dependency graph.
+
+      - id: cross-repo-plan
+        name: "Cross-Repo Implementation Plan"
+        output: "features/WKSP-{XXXX}/plan.md"
+        template: ".sniper/templates/workspace-plan.md"
+        reads:
+          - "features/WKSP-{XXXX}/brief.md"
+          - "contracts/"
+        blocked_by: [contract-generation]
+        plan_approval: true
+        description: >
+          After contracts are designed, produce the cross-repo implementation plan.
+          Break down work per repository, define sprint wave ordering, and specify
+          integration validation criteria between waves.
+
+  - name: contract-designer
+    compose:
+      process: contract-designer
+      technical: api-design
+      cognitive: systems-thinker
+      domain: null
+    tasks:
+      - id: contract-generation
+        name: "Interface Contract Design"
+        output: "contracts/"
+        template: ".sniper/templates/contract.yaml"
+        reads:
+          - "features/WKSP-{XXXX}/brief.md"
+          - "contracts/"
+          - "repositories/*/docs/architecture.md"
+        blocked_by: [workspace-brief]
+        plan_approval: true
+        description: >
+          Based on the workspace feature brief, design interface contracts for
+          all cross-repo communication. Define API endpoints with full schemas,
+          shared type specifications, and event contracts. Version appropriately
+          and ensure each side can be implemented independently.
+
+coordination:
+  - between: [orchestrator, contract-designer]
+    topic: "Interface boundaries and contract scope — what needs formal contracts vs. what can be informal"
+
+review_gate:
+  checklist: ".sniper/checklists/workspace-review.md"
+  mode: strict

package/framework/teams/workspace-validation.yaml

@@ -0,0 +1,27 @@
+team_name: sniper-workspace-validation
+phase: workspace-validation
+
+teammates:
+  - name: validator
+    compose:
+      process: integration-validator
+      technical: backend
+      cognitive: devils-advocate
+      domain: null
+    tasks:
+      - id: contract-validation
+        name: "Contract Compliance Validation"
+        output: "features/WKSP-{XXXX}/validation-wave-{N}.md"
+        template: ".sniper/templates/contract-validation-report.md"
+        reads:
+          - "contracts/"
+          - "repositories/*/src/"
+        description: >
+          Validate that each repository's implementation matches the agreed-upon
+          contracts. Check API endpoints, shared types, and event schemas. Report
+          pass/fail for each contract item with specific mismatch details. Generate
+          fix stories for any failures.
+
+coordination: []
+
+review_gate: null

package/framework/templates/arch-delta.md

@@ -0,0 +1,74 @@
+# Architecture Delta: {title}
+
+> **Feature ID:** SNPR-{XXXX}
+> **Version:** 1
+> **Status:** Draft
+> **Date:** {date}
+> **Author:** Feature Planning Team — Architect
+> **Base Architecture:** `docs/architecture.md` (version {N})
+> **Change Log:**
+> - v1 ({date}): Initial version
+
+## Summary of Changes
+<!-- sniper:managed:summary:start -->
+<!-- 2-3 sentence overview of what changes to the architecture -->
+<!-- sniper:managed:summary:end -->
+
+## New Components
+<!-- sniper:managed:new-components:start -->
+<!-- Components being added to the system -->
+
+### {Component Name}
+- **Responsibility:**
+- **Interfaces:**
+- **Dependencies:**
+
+<!-- sniper:managed:new-components:end -->
+
+## Modified Components
+<!-- sniper:managed:modified-components:start -->
+<!-- Existing components that need changes -->
+
+### {Existing Component Name}
+- **Current behavior:**
+- **New behavior:**
+- **Migration notes:**
+
+<!-- sniper:managed:modified-components:end -->
+
+## New Data Models
+<!-- sniper:managed:new-data-models:start -->
+<!-- New entities or modified schemas -->
+
+| Field | Type | Constraints | Index | Notes |
+|-------|------|------------|-------|-------|
+| | | | | |
+
+<!-- sniper:managed:new-data-models:end -->
+
+## New/Modified API Endpoints
+<!-- sniper:managed:api-endpoints:start -->
+```
+METHOD /api/v1/{resource}
+Request: { }
+Response: { }
+Status Codes: 200, 400, 401, 404, 500
+Auth: Required
+```
+<!-- sniper:managed:api-endpoints:end -->
+
+## Infrastructure Changes
+<!-- sniper:managed:infrastructure:start -->
+<!-- Any new services, queues, caches, etc. -->
+<!-- sniper:managed:infrastructure:end -->
+
+## Patterns to Follow
+<!-- sniper:managed:patterns:start -->
+<!-- Reference existing architecture patterns that should be followed -->
+<!-- From docs/conventions.md if available -->
+<!-- sniper:managed:patterns:end -->
+
+## Risks
+<!-- sniper:managed:risks:start -->
+<!-- Architecture risks specific to this feature -->
+<!-- sniper:managed:risks:end -->

package/framework/templates/architecture.md

@@ -1,14 +1,20 @@
 # System Architecture: {project_name}
 
+> **Version:** 1
 > **Status:** Draft
+> **Last Updated:** {date}
 > **Author:** Planning Team — Architect
-> **Date:** {date}
 > **Source:** `docs/prd.md`, `docs/brief.md`
+> **Change Log:**
+> - v1 ({date}): Initial version
 
 ## 1. Architecture Overview
+<!-- sniper:managed:overview:start -->
 <!-- High-level system description. Include an ASCII or Mermaid component diagram. -->
+<!-- sniper:managed:overview:end -->
 
 ## 2. Technology Choices
+<!-- sniper:managed:technology-choices:start -->
 | Component | Choice | Why | Alternatives Considered |
 |-----------|--------|-----|------------------------|
 | Language | | | |
@@ -18,24 +24,30 @@
 | Cache | | | |
 | Queue | | | |
 | Infrastructure | | | |
+<!-- sniper:managed:technology-choices:end -->
 
 ## 3. Component Architecture
+<!-- sniper:managed:components:start -->
 <!-- Describe each major component, its responsibility, and its interfaces -->
 
 ### 3.1 {Component Name}
 - **Responsibility:**
 - **Interfaces:**
 - **Dependencies:**
+<!-- sniper:managed:components:end -->
 
 ## 4. Data Models
+<!-- sniper:managed:data-models:start -->
 <!-- Entity-relationship descriptions with field types, constraints, indexes -->
 
 ### 4.1 {Entity Name}
 | Field | Type | Constraints | Index | Notes |
 |-------|------|------------|-------|-------|
 | | | | | |
+<!-- sniper:managed:data-models:end -->
 
 ## 5. API Contracts
+<!-- sniper:managed:api-contracts:start -->
 <!-- RESTful endpoints with methods, paths, request/response payloads -->
 
 ### 5.1 {Resource}
@@ -46,27 +58,38 @@ Response: { }
 Status Codes: 200, 400, 401, 404, 500
 Auth: Required
 ```
+<!-- sniper:managed:api-contracts:end -->
 
 ## 6. Infrastructure Topology
+<!-- sniper:managed:infrastructure:start -->
 <!-- Compute, storage, networking, scaling strategy -->
+<!-- sniper:managed:infrastructure:end -->
 
 ## 7. Cross-Cutting Concerns
 
+<!-- sniper:managed:cross-cutting:start -->
 ### 7.1 Authentication & Authorization
 ### 7.2 Logging & Monitoring
 ### 7.3 Error Handling
 ### 7.4 Configuration Management
+<!-- sniper:managed:cross-cutting:end -->
 
 ## 8. Non-Functional Requirements
+<!-- sniper:managed:nfr:start -->
 | Requirement | Target | Strategy |
 |-------------|--------|----------|
 | Response time (p95) | | |
 | Availability | | |
 | Throughput | | |
 | Data retention | | |
+<!-- sniper:managed:nfr:end -->
 
 ## 9. Migration & Deployment Strategy
+<!-- sniper:managed:deployment:start -->
 <!-- How the system gets deployed. CI/CD, blue-green, rollback strategy. -->
+<!-- sniper:managed:deployment:end -->
 
 ## 10. Security Architecture
+<!-- sniper:managed:security:start -->
 <!-- Reference docs/security.md for detailed security requirements -->
+<!-- sniper:managed:security:end -->

package/framework/templates/brief.md

@@ -1,17 +1,25 @@
 # Project Brief: {project_name}
 
+> **Version:** 1
 > **Status:** Draft
+> **Last Updated:** {date}
 > **Author:** Discovery Team — Analyst
-> **Date:** {date}
+> **Change Log:**
+> - v1 ({date}): Initial version
 
 ## Executive Summary
+<!-- sniper:managed:executive-summary:start -->
 <!-- 2-3 sentence overview of the project and its value proposition -->
+<!-- sniper:managed:executive-summary:end -->
 
 ## Problem Statement
+<!-- sniper:managed:problem-statement:start -->
 <!-- What problem does this solve? Who has this problem? How is it currently solved? -->
+<!-- sniper:managed:problem-statement:end -->
 
 ## Market Landscape
 
+<!-- sniper:managed:market-landscape:start -->
 ### Direct Competitors
 | Competitor | Key Features | Pricing | Market Position | Weaknesses |
 |-----------|-------------|---------|-----------------|------------|
@@ -19,25 +27,35 @@
 
 ### Indirect Competitors / Alternatives
 <!-- How are users solving this problem today without a dedicated tool? -->
+<!-- sniper:managed:market-landscape:end -->
 
 ## Target Market
+<!-- sniper:managed:target-market:start -->
 - **Primary segment:** <!-- Who is the ideal customer? -->
 - **Market size:** <!-- TAM/SAM/SOM estimates if available -->
 - **Growth trends:** <!-- Is this market growing? Why? -->
+<!-- sniper:managed:target-market:end -->
 
 ## Unique Value Proposition
+<!-- sniper:managed:value-proposition:start -->
 <!-- What makes this product different from everything else? Be specific. -->
+<!-- sniper:managed:value-proposition:end -->
 
 ## Key Assumptions
+<!-- sniper:managed:assumptions:start -->
 <!-- List assumptions that need validation. These are things you believe but haven't proven. -->
 1.
 2.
 3.
+<!-- sniper:managed:assumptions:end -->
 
 ## Technical Constraints
+<!-- sniper:managed:technical-constraints:start -->
 <!-- Known technical limitations, required integrations, regulatory requirements -->
+<!-- sniper:managed:technical-constraints:end -->
 
 ## Initial Scope Recommendation
+<!-- sniper:managed:scope:start -->
 <!-- What should v1 include? What should it NOT include? -->
 
 ### In Scope (v1)
@@ -45,8 +63,11 @@
 
 ### Out of Scope (v1)
 -
+<!-- sniper:managed:scope:end -->
 
 ## Open Questions
+<!-- sniper:managed:open-questions:start -->
 <!-- Questions that need answers before planning can begin -->
 1.
 2.
+<!-- sniper:managed:open-questions:end -->

package/framework/templates/bug-report.md

@@ -0,0 +1,55 @@
+# Bug Report: {title}
+
+> **Bug ID:** BUG-{NNN}
+> **Severity:** {critical/high/medium/low}
+> **Status:** Triaging
+> **Date:** {date}
+> **Author:** Triage Lead
+> **Source:** {user description / GitHub issue GH-{NNN}}
+
+## Bug Summary
+<!-- sniper:managed:summary:start -->
+<!-- One-paragraph description of the observed behavior -->
+<!-- sniper:managed:summary:end -->
+
+## Severity Assessment
+<!-- sniper:managed:severity:start -->
+<!-- Severity level with justification based on user impact -->
+<!-- sniper:managed:severity:end -->
+
+## Affected Components
+<!-- sniper:managed:affected-components:start -->
+
+| Component | Impact | Notes |
+|-----------|--------|-------|
+| | Direct / Indirect | |
+
+<!-- sniper:managed:affected-components:end -->
+
+## Reproduction Steps
+<!-- sniper:managed:reproduction:start -->
+<!-- Inferred from bug description. Note "Unable to determine" for unknown steps -->
+1.
+<!-- sniper:managed:reproduction:end -->
+
+## Error Context
+<!-- sniper:managed:error-context:start -->
+<!-- Error messages, stack traces, affected endpoints, HTTP status codes -->
+<!-- sniper:managed:error-context:end -->
+
+## Hypothesis
+<!-- sniper:managed:hypothesis:start -->
+<!-- Initial theory about what might be causing the issue -->
+<!-- sniper:managed:hypothesis:end -->
+
+## Investigation Plan
+<!-- sniper:managed:investigation-plan:start -->
+<!-- What the investigation team should look at -->
+
+### For Log Analyst
+-
+
+### For Code Investigator
+-
+
+<!-- sniper:managed:investigation-plan:end -->

package/framework/templates/contract-validation-report.md

@@ -0,0 +1,68 @@
+# Contract Validation Report
+
+> **Feature:** WKSP-{XXXX}
+> **Wave:** {N}
+> **Date:** {date}
+> **Validator:** Integration Validator
+
+## Summary
+<!-- sniper:managed:summary:start -->
+| Metric | Count |
+|--------|-------|
+| Contracts validated | 0 |
+| Endpoints checked | 0 |
+| Shared types checked | 0 |
+| Events checked | 0 |
+| **Passed** | 0 |
+| **Failed** | 0 |
+| **Warnings** | 0 |
+<!-- sniper:managed:summary:end -->
+
+## Contract Results
+<!-- sniper:managed:contract-results:start -->
+
+### {contract-name} (v{version})
+
+#### Endpoints
+| Endpoint | Method | Status | Notes |
+|----------|--------|--------|-------|
+| | | ✅ / ❌ | |
+
+#### Shared Types
+| Type | Owner | Status | Notes |
+|------|-------|--------|-------|
+| | | ✅ / ❌ | |
+
+#### Events
+| Event | Producer | Status | Notes |
+|-------|----------|--------|-------|
+| | | ✅ / ❌ | |
+
+<!-- sniper:managed:contract-results:end -->
+
+## Mismatches
+<!-- sniper:managed:mismatches:start -->
+
+### {mismatch-title}
+- **Contract:** {what the contract specifies}
+- **Actual:** {what the implementation does}
+- **Location:** `{repo}/{file}:{line}`
+- **Severity:** Breaking / Non-Breaking
+- **Fix:** {what needs to change}
+
+<!-- sniper:managed:mismatches:end -->
+
+## Fix Stories
+<!-- sniper:managed:fix-stories:start -->
+| Repo | Story Title | Priority |
+|------|-------------|----------|
+| | | |
+<!-- sniper:managed:fix-stories:end -->
+
+## Verdict
+<!-- sniper:managed:verdict:start -->
+**{PASS / FAIL}** — {summary statement}
+
+{If FAIL: "The following must be resolved before Wave {N+1} can begin."}
+{If PASS: "All contracts validated. Wave {N+1} may proceed."}
+<!-- sniper:managed:verdict:end -->

package/framework/templates/contract.yaml

@@ -0,0 +1,60 @@
+# Interface Contract Template
+# Produced by: contract-designer
+# Consumed by: per-repo feature leads, integration-validator
+
+contract:
+  name: ""                          # e.g., api-web, api-shared
+  between: []                       # e.g., [api-service, web-app]
+  version: "1.0.0"                  # semver — breaking changes increment major
+  last_updated: ""                  # ISO 8601 date
+  updated_by: ""                    # WKSP-XXXX feature that created/modified this
+
+# REST API endpoints
+endpoints:
+  # - path: /api/v1/resource
+  #   method: GET | POST | PUT | PATCH | DELETE
+  #   description: ""
+  #   request_body:                 # For POST/PUT/PATCH
+  #     type: object
+  #     properties:
+  #       field_name:
+  #         type: string | number | boolean | object | array
+  #         required: true | false
+  #         description: ""
+  #   query_params:                 # For GET
+  #     - name: ""
+  #       type: string
+  #       required: false
+  #   response:
+  #     200:
+  #       type: object
+  #       properties: {}
+  #     400:
+  #       type: object
+  #       properties:
+  #         error: { type: string }
+  #     404:
+  #       type: object
+  #       properties:
+  #         error: { type: string }
+  []
+
+# Shared type definitions
+shared_types:
+  # - name: TypeName
+  #   repo: shared-lib              # Which repo owns and exports this type
+  #   path: src/types/type-name.ts  # File path within the owning repo
+  #   definition:                   # TypeScript-style type shape
+  #     field: "type"
+  []
+
+# Asynchronous event contracts
+events:
+  # - name: entity.action.completed  # e.g., user.preferences.updated
+  #   producer: api-service          # Which repo emits this event
+  #   consumers: [web-app]           # Which repos listen for this event
+  #   payload:
+  #     field:
+  #       type: string
+  #       description: ""
+  []

package/framework/templates/conventions.md

@@ -0,0 +1,59 @@
+# Coding Conventions: {project_name}
+
+> **Version:** 1
+> **Status:** Draft
+> **Last Updated:** {date}
+> **Author:** Ingestion Team — Convention Miner
+> **Source:** Extracted from codebase analysis
+> **Change Log:**
+> - v1 ({date}): Initial version
+
+## Naming Conventions
+<!-- sniper:managed:naming:start -->
+<!-- Variable naming (camelCase/snake_case), file naming, directory naming, exported symbols -->
+<!-- Include code examples from the actual codebase -->
+<!-- sniper:managed:naming:end -->
+
+## Code Organization
+<!-- sniper:managed:code-org:start -->
+<!-- How files are structured within directories, barrel exports, index files, feature-based vs layer-based -->
+<!-- sniper:managed:code-org:end -->
+
+## Error Handling Patterns
+<!-- sniper:managed:error-handling:start -->
+<!-- Custom error classes, error codes, error boundaries, try/catch patterns -->
+<!-- Include code examples -->
+<!-- sniper:managed:error-handling:end -->
+
+## Testing Patterns
+<!-- sniper:managed:testing:start -->
+<!-- Test file location, test naming, mock patterns, fixtures, test utilities -->
+<!-- Include code examples -->
+<!-- sniper:managed:testing:end -->
+
+## API Patterns
+<!-- sniper:managed:api-patterns:start -->
+<!-- Request validation, response formatting, middleware usage, auth checks -->
+<!-- Include code examples -->
+<!-- sniper:managed:api-patterns:end -->
+
+## Import & Module Patterns
+<!-- sniper:managed:imports:start -->
+<!-- Absolute vs relative imports, import ordering, path aliases -->
+<!-- Include code examples -->
+<!-- sniper:managed:imports:end -->
+
+## Configuration & Environment
+<!-- sniper:managed:config:start -->
+<!-- How env vars are accessed, config files, validation -->
+<!-- Include code examples -->
+<!-- sniper:managed:config:end -->
+
+## Logging
+<!-- sniper:managed:logging:start -->
+<!-- Logging library, log levels, structured logging patterns -->
+<!-- Include code examples -->
+<!-- sniper:managed:logging:end -->
+
+## Additional Conventions
+<!-- Add project-specific conventions not covered above -->