@sniper.ai/core 2.0.0 → 3.1.0

package/schemas/retro.schema.yaml

@@ -0,0 +1,95 @@
+$schema: "https://json-schema.org/draft/2020-12/schema"
+$id: "https://sniper.ai/schemas/retro"
+title: Retrospective Report
+description: Schema for SNIPER retrospective reports generated after a lifecycle run completes.
+type: object
+required:
+  - protocol
+  - completed_at
+properties:
+  protocol:
+    type: string
+    description: The SNIPER protocol version identifier.
+  completed_at:
+    type: string
+    format: date-time
+    description: ISO 8601 timestamp of when the lifecycle run completed.
+  duration_phases:
+    type: array
+    description: Per-phase duration and execution summary.
+    items:
+      type: object
+      required:
+        - phase
+        - agents
+        - gate_attempts
+        - gate_result
+      properties:
+        phase:
+          type: string
+          description: Phase name.
+        agents:
+          type: integer
+          minimum: 0
+          description: Number of agents that participated in this phase.
+        gate_attempts:
+          type: integer
+          minimum: 0
+          description: Number of times the gate review was attempted.
+        gate_result:
+          type: string
+          enum:
+            - pass
+            - fail
+          description: Final gate review outcome for this phase.
+  metrics:
+    type: object
+    description: Aggregate metrics for the entire lifecycle run.
+    properties:
+      total_tokens:
+        type: integer
+        minimum: 0
+        description: Total tokens consumed across all phases.
+      total_agents_spawned:
+        type: integer
+        minimum: 0
+        description: Total number of agents spawned across all phases.
+      gate_pass_rate:
+        type: number
+        minimum: 0
+        maximum: 1
+        description: Fraction of gate reviews that passed on the first attempt.
+  findings:
+    type: object
+    description: Retrospective findings and action items.
+    properties:
+      went_well:
+        type: array
+        description: Things that went well during the lifecycle run.
+        items:
+          type: string
+      needs_improvement:
+        type: array
+        description: Areas that need improvement.
+        items:
+          type: string
+      action_items:
+        type: array
+        description: Concrete action items for future runs.
+        items:
+          type: string
+  velocity:
+    type: object
+    description: Velocity metrics for this execution, used for budget calibration.
+    properties:
+      wall_clock_seconds:
+        type: number
+        minimum: 0
+        description: Total wall clock time for the protocol execution in seconds.
+      tokens_per_phase:
+        type: object
+        description: Token usage broken down by phase name.
+        additionalProperties:
+          type: integer
+          minimum: 0
+additionalProperties: false

package/schemas/revert-plan.schema.yaml

@@ -0,0 +1,40 @@
+$schema: "https://json-schema.org/draft/2020-12/schema"
+$id: "https://sniper.ai/schemas/revert-plan"
+title: Revert Plan
+description: Schema for SNIPER logical revert plans that track which commits to revert.
+type: object
+required:
+  - protocol
+  - commits_to_revert
+  - backup_branch
+  - target_state
+properties:
+  protocol:
+    type: string
+    description: Protocol ID being reverted.
+  phase:
+    type: string
+    description: Optional specific phase being reverted.
+  commits_to_revert:
+    type: array
+    items:
+      type: object
+      required: [sha, message, agent]
+      properties:
+        sha: { type: string }
+        message: { type: string }
+        agent: { type: string }
+    description: Commits to revert in reverse chronological order.
+  backup_branch:
+    type: string
+    description: Branch name for backup before revert.
+  target_state:
+    type: string
+    description: Description of the target state after revert.
+  created_at:
+    type: string
+    format: date-time
+  dry_run:
+    type: boolean
+    description: Whether this was a dry run only.
+additionalProperties: false

package/schemas/signal.schema.yaml

@@ -0,0 +1,39 @@
+$schema: "https://json-schema.org/draft/2020-12/schema"
+$id: "https://sniper.ai/schemas/signal"
+title: External Signal Record
+description: Schema for SNIPER signal records that capture learnings from CI failures, PR reviews, and production errors.
+type: object
+required:
+  - type
+  - source
+  - timestamp
+  - summary
+properties:
+  type:
+    type: string
+    enum: [ci_failure, pr_review_comment, production_error, manual]
+    description: Signal type classification.
+  source:
+    type: string
+    description: Where the signal came from (e.g., "github-actions", "pr-42", "datadog").
+  timestamp:
+    type: string
+    format: date-time
+  summary:
+    type: string
+    description: One-line summary of the signal.
+  details:
+    type: string
+    description: Full details (error message, review comment text, etc.).
+  learning:
+    type: string
+    description: Extracted learning or pattern to apply in future.
+  relevance_tags:
+    type: array
+    items: { type: string }
+    description: Tags for matching against agent context.
+  affected_files:
+    type: array
+    items: { type: string }
+    description: File paths affected by this signal.
+additionalProperties: false

package/schemas/velocity.schema.yaml

@@ -0,0 +1,52 @@
+$schema: "https://json-schema.org/draft/2020-12/schema"
+$id: "https://sniper.ai/schemas/velocity"
+title: Velocity
+description: Protocol execution history and calibrated budgets for adaptive budget selection.
+type: object
+required:
+  - executions
+properties:
+  executions:
+    type: array
+    description: History of protocol executions with timing and token data.
+    items:
+      type: object
+      required:
+        - protocol
+        - completed_at
+        - tokens_used
+      properties:
+        protocol:
+          type: string
+          description: Protocol name that was executed.
+        completed_at:
+          type: string
+          format: date-time
+          description: ISO 8601 timestamp of when the execution completed.
+        wall_clock_seconds:
+          type: number
+          minimum: 0
+          description: Wall clock duration of the execution in seconds.
+        tokens_used:
+          type: integer
+          minimum: 0
+          description: Total tokens consumed during the execution.
+        tokens_per_phase:
+          type: object
+          description: Token usage broken down by phase name.
+          additionalProperties:
+            type: integer
+            minimum: 0
+  calibrated_budgets:
+    type: object
+    description: p75 of token usage from last 5+ executions, keyed by protocol name.
+    additionalProperties:
+      type: integer
+      minimum: 0
+  rolling_averages:
+    type: object
+    description: Exponential moving average of token usage, keyed by protocol name.
+    additionalProperties:
+      type: number
+      minimum: 0
+additionalProperties: false

package/schemas/workspace-lock.schema.yaml

@@ -0,0 +1,34 @@
+$schema: "https://json-schema.org/draft/2020-12/schema"
+$id: "https://sniper.ai/schemas/workspace-lock"
+title: Workspace File Lock
+description: Schema for advisory file locks in SNIPER workspace coordination.
+type: object
+required:
+  - file
+  - locked_by
+  - since
+properties:
+  file:
+    type: string
+    description: Relative file path being locked.
+  locked_by:
+    type: object
+    required: [project, agent, protocol]
+    properties:
+      project:
+        type: string
+        description: Project name that holds the lock.
+      agent:
+        type: string
+        description: Agent that acquired the lock.
+      protocol:
+        type: string
+        description: Protocol execution that holds the lock.
+  since:
+    type: string
+    format: date-time
+    description: When the lock was acquired.
+  reason:
+    type: string
+    description: Why the lock was acquired.
+additionalProperties: false

package/schemas/workspace.schema.yaml

@@ -0,0 +1,82 @@
+$schema: "https://json-schema.org/draft/2020-12/schema"
+$id: "https://sniper.ai/schemas/workspace"
+title: Workspace Configuration
+description: Schema for SNIPER workspace config files that coordinate multi-project orchestration.
+type: object
+required:
+  - name
+  - projects
+properties:
+  name:
+    type: string
+    description: Human-readable workspace name.
+  projects:
+    type: array
+    description: List of projects managed by this workspace.
+    items:
+      type: object
+      required:
+        - name
+        - path
+      properties:
+        name:
+          type: string
+          description: Project identifier within the workspace.
+        path:
+          type: string
+          description: Relative directory path from workspace root to the project.
+        type:
+          type: string
+          description: Optional project type label (e.g. api, frontend, library).
+  shared:
+    type: object
+    description: Shared conventions and decisions applied across all workspace projects.
+    properties:
+      conventions:
+        type: array
+        description: Coding conventions enforced across all projects.
+        items:
+          type: string
+      anti_patterns:
+        type: array
+        description: Patterns to avoid across all projects.
+        items:
+          type: string
+      architectural_decisions:
+        type: array
+        description: Architecture Decision Records shared across the workspace.
+        items:
+          type: object
+          required:
+            - id
+            - title
+            - decision
+            - rationale
+            - date
+          properties:
+            id:
+              type: string
+              description: Unique ADR identifier (e.g. ADR-001).
+            title:
+              type: string
+              description: Short title of the decision.
+            decision:
+              type: string
+              description: The decision that was made.
+            rationale:
+              type: string
+              description: Why this decision was made.
+            date:
+              type: string
+              format: date
+              description: Date the decision was recorded (YYYY-MM-DD).
+    additionalProperties: false
+  memory:
+    type: object
+    description: Configuration for shared workspace memory.
+    properties:
+      directory:
+        type: string
+        description: Path to the shared memory directory relative to workspace root.
+    additionalProperties: false
+additionalProperties: false

package/skills/sniper-flow/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: sniper-flow
+description: Execute a SNIPER protocol — the core execution engine
+arguments:
+  - name: protocol
+    description: Protocol to run (full, feature, patch, ingest, explore, refactor, hotfix). Auto-detected if omitted.
+    required: false
+  - name: resume
+    description: Resume from last checkpoint
+    required: false
+    type: boolean
+  - name: phase
+    description: Start from a specific phase (skips earlier phases)
+    required: false
+---
+
+# /sniper-flow
+
+You are the SNIPER protocol execution engine. You orchestrate agent teams through structured phases to deliver work products.
+
+## 1. Select Protocol
+
+```
+--protocol given?  → Use it directly
+--resume given?    → Read latest checkpoint from .sniper/checkpoints/, resume from that phase
+--phase given?     → Use auto-detected protocol, skip to specified phase
+Otherwise          → Auto-detect (see below), confirm with user before proceeding
+```
+
+**Auto-detection** — match user intent, no file reads needed:
+| Keywords | Protocol |
+|----------|----------|
+| "critical", "urgent", "production down", "hotfix" | `hotfix` |
+| Bug fix, small change (< 5 files) | `patch` |
+| New feature, significant enhancement | `feature` |
+| New project, major rework, multi-component | `full` |
+| Understand, document existing codebase | `ingest` |
+| "what is", "how does", "analyze", research | `explore` |
+| "refactor", "clean up", "improve", "reorganize" | `refactor` |
+
+After auto-detection, check trigger tables: run `git diff --name-only` and match against `.sniper/config.yaml` `triggers` section. Trigger overrides take precedence.
+
+**Protocol resolution order:** `.sniper/protocols/<name>.yaml` (custom) → `@sniper.ai/core/protocols/<name>.yaml` (built-in).
+
+## 2. Initialize Protocol
+
+1. **Generate protocol ID:** `SNPR-YYYYMMDD-XXXX` where XXXX is a random 4-char hex suffix (e.g., `SNPR-20260307-a3f2`). No registry parsing needed.
+2. **Create artifact directory:** `mkdir -p .sniper/artifacts/{protocol_id}/`
+3. **Write metadata:** Create `.sniper/artifacts/{protocol_id}/meta.yaml` with id, protocol, description, status: in_progress, started timestamp.
+4. **Append to registry:** Add a row to `.sniper/artifacts/registry.md`. If registry doesn't exist, create it with a header row first.
+
+## 3. Phase Execution Loop
+
+For each phase in the protocol, execute these 5 steps:
+
+### Setup
+
+1. Read protocol YAML for the current phase definition
+2. Read `.sniper/config.yaml` for agent config, ownership, commands
+3. Check `.sniper/memory/velocity.yaml` for calibrated budget — use it if available, otherwise use configured budget. Log which source is used.
+4. Compose agents per [Reference: Agent Composition](#reference-agent-composition)
+
+### Execute
+
+1. Determine spawn strategy from protocol phase definition (`single`, `sequential`, `parallel`, or `team`)
+2. Spawn agents per [Reference: Spawn Strategies](#reference-spawn-strategies)
+3. Monitor via TaskList — if an agent is blocked, investigate and guide via SendMessage
+4. If an agent crashes: note the failure, continue with remaining agents
+5. After all parallel agents complete: coordinate worktree merges per [Reference: Merge Coordination](#reference-merge-coordination)
+
+### Checkpoint
+
+Write checkpoint to `.sniper/checkpoints/{protocol_id}-{phase}-{timestamp}.yaml`:
+```yaml
+protocol: <name>
+protocol_id: <SNPR-YYYYMMDD-XXXX>
+phase: <phase>
+timestamp: <ISO 8601>
+status: completed | failed
+agents: [status per agent]
+token_usage: [phase + cumulative]
+commits: [git SHAs produced]
+```
+
+Update `.sniper/live-status.yaml` with current phase, agent statuses, and cost percentage.
+
+### Gate
+
+1. Write `.sniper/pending-gate.yaml` with phase name and checklist reference
+2. Spawn gate-reviewer agent with the `{protocol_id}` for path resolution
+3. Read gate result from `.sniper/gates/`
+4. **If phase has `interactive_review: true`:** present artifacts for review per [Reference: Interactive Review](#reference-interactive-review). User must explicitly approve before advancing.
+5. **Gate pass + `human_approval: false`:** advance
+6. **Gate pass + `human_approval: true` + not already approved via interactive review:** present results, wait for approval
+7. **Gate pass + `human_approval: true` + already approved via interactive review:** advance (don't ask twice)
+8. **Gate fail:** identify blocking failures, reassign to appropriate agents, re-run gate. After 3 failures: escalate to user.
+
+### Advance
+
+1. If phase has `doc_sync: true`: spawn `doc-writer` agent to update `CLAUDE.md`, `README.md`, and `docs/architecture.md` based on the git diff from this phase. Use `Edit` for surgical updates.
+2. Move to next phase. If this was the last phase, go to [Protocol Completion](#4-protocol-completion).
+
+## 4. Protocol Completion
+
+1. Write final checkpoint
+2. Update `.sniper/live-status.yaml` with `status: completed`
+3. Update `.sniper/artifacts/{protocol_id}/meta.yaml` with final status, token usage, commits, agents used
+4. Update `.sniper/artifacts/registry.md` entry from `in_progress` to `completed`
+5. Present summary: phases completed, gate results, token usage
+6. If `auto_retro: true` in protocol: spawn `retro-analyst` as background task (see [Reference: Retrospective](#reference-retrospective))
+
+## Cost Tracking
+
+Maintain `.sniper/cost.yaml` throughout execution. At each checkpoint:
+- `warn_threshold` → log warning, continue
+- `soft_cap` → pause, ask user whether to continue
+- `hard_cap` → checkpoint and stop gracefully
+
+Read thresholds from `.sniper/config.yaml` cost section.
+
+## Rules
+
+- ALWAYS generate a protocol ID and create `.sniper/artifacts/{protocol_id}/` before spawning any agent
+- ALWAYS checkpoint between phases
+- ALWAYS respect token budgets
+- ALWAYS present the plan for interactive review when `interactive_review: true`
+- NEVER skip a gate — every phase transition goes through its gate
+- NEVER advance past a failed blocking gate check
+- NEVER implement code yourself — delegate all work to agents
+- When `human_approval` is required, present clear options and wait
+
+---
+
+## Reference: Agent Composition
+
+For each agent in the phase, build the full prompt by layering these sources. Each layer is optional except the base.
+
+| Layer | Source | If missing |
+|-------|--------|------------|
+| 1. Base agent | `.claude/agents/<name>.md` | FATAL — abort phase |
+| 2. Mixins | `.claude/personas/cognitive/<mixin>.md` (from `config.agents.mixins.<agent>`) | WARN — skip mixin, continue |
+| 3. Domain knowledge | `.sniper/knowledge/manifest.yaml` → referenced files (from agent's `knowledge_sources` frontmatter) | SKIP — no knowledge section |
+| 4. Workspace conventions | `.sniper-workspace/config.yaml` → `shared.conventions` and `shared.anti_patterns` | SKIP — no workspace section |
+| 5. Signals | `.sniper/memory/signals/` → top 10 most relevant by `affected_files` and `relevance_tags` | SKIP — no signals section |
+
+The composed prompt = base definition + concatenated mixin content + `## Domain Knowledge` section + `## Workspace Conventions` section + `## Anti-Patterns (Workspace)` section + `## Recent Learnings` section (formatted as `- [<type>] <summary> (<affected_files>)`).
+
+Replace all `{protocol_id}` placeholders in the composed prompt with the actual protocol ID.
+
+Truncate domain knowledge content to stay within `config.knowledge.max_total_tokens` (default: 50000 tokens).
+
+## Reference: Spawn Strategies
+
+**`single`** — One agent via Task tool. No team overhead.
+```
+Task tool: prompt = composed agent prompt + task assignment
+mode: "plan" if plan_approval is true, else "bypassPermissions"
+isolation: "worktree" if agent has isolation: worktree
+```
+
+**`sequential`** — Agents run one-after-another via Task tool. Output from each feeds into the next as context.
+
+**`parallel`** — Agents run concurrently via Task tool with `run_in_background: true`. Each agent works in its own worktree. Wait for all to complete.
+
+**`team`** — Full Agent Team via TeamCreate + shared task list + messaging. Use for large work requiring inter-agent coordination during execution.
+```
+TeamCreate → create team for this phase
+TaskCreate → create tasks with dependencies from protocol
+Task tool → spawn each teammate with team_name
+```
+
+## Reference: Merge Coordination
+
+For agents working in worktrees (after all implementation agents complete):
+1. Attempt to merge each worktree
+2. If merge conflicts: identify conflicting files, assign resolution to the file owner, re-run tests after resolution
+3. The orchestrator coordinates merges — agents never merge their own worktrees
+
+## Reference: Interactive Review
+
+When a phase has `interactive_review: true`:
+
+1. Read produced artifacts from `.sniper/artifacts/{protocol_id}/` (e.g., `plan.md`, `prd.md`, `stories/`)
+2. Present a structured summary: key architectural decisions, component overview, story count, open questions
+3. Offer options:
+   - **Approve** — continue to next phase
+   - **Request changes** — describe changes (architect/PM will revise, then re-present)
+   - **Edit directly** — user modifies plan files, says "done", re-validate via gate
+4. Only advance after explicit user approval
+
+## Reference: Retrospective
+
+When `auto_retro: true`, after protocol completion:
+1. Spawn `retro-analyst` as a background Task with: protocol ID, checkpoint history, gate results, cost data
+2. The retro-analyst writes a report to `.sniper/retros/{protocol_id}.yaml`, updates `.sniper/memory/velocity.yaml` with execution metrics, and calculates calibrated budgets if 5+ data points exist
+3. Runs in background — user doesn't wait for it

package/skills/sniper-init/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: sniper-init
+description: Initialize SNIPER v3 in a new or existing project
+arguments:
+  - name: language
+    description: Primary language (auto-detected if omitted)
+    required: false
+---
+
+# /sniper-init
+
+Initialize SNIPER v3 framework in the current project.
+
+## Process
+
+### 1. Check Existing State
+
+- If `.sniper/config.yaml` exists, ask user: "SNIPER is already initialized. Reinitialize? (existing config will be backed up)"
+- If reinitializing, copy `.sniper/config.yaml` to `.sniper/config.yaml.bak`
+
+### 2. Auto-Detect Project
+
+Scan the project directory to detect:
+
+**Language** (check in order):
+- `tsconfig.json` or `*.ts` files → TypeScript
+- `package.json` → JavaScript
+- `pyproject.toml` or `requirements.txt` → Python
+- `go.mod` → Go
+- `Cargo.toml` → Rust
+- `pom.xml` or `build.gradle` → Java
+- Fall back to `--language` argument or ask user
+
+**Package Manager**:
+- `pnpm-lock.yaml` → pnpm
+- `yarn.lock` → yarn
+- `bun.lockb` → bun
+- `package-lock.json` → npm
+- `uv.lock` → uv
+- `poetry.lock` → poetry
+
+**Framework**:
+- `next.config.*` → Next.js
+- `nuxt.config.*` → Nuxt
+- `vite.config.*` → Vite
+- `angular.json` → Angular
+
+**Test Runner**:
+- `vitest.config.*` → Vitest
+- `jest.config.*` → Jest
+- `pytest.ini` or `conftest.py` → Pytest
+
+**Commands** (from package.json scripts or Makefile):
+- Look for `test`, `lint`, `build`, `typecheck` scripts
+
+### 3. Gather User Input
+
+Ask the user (with auto-detected defaults pre-filled):
+1. Project name (default: directory name)
+2. Project type (saas, api, mobile, cli, library, monorepo)
+3. One-line description
+4. Max concurrent teammates (default: 5)
+5. Confirm detected stack
+
+### 4. Scaffold Structure
+
+Create the following directory structure:
+```
+.sniper/
+  config.yaml              ← Generated from template + user input + auto-detection
+  checkpoints/
+  gates/
+  retros/
+  self-reviews/
+  checklists/              ← Copied from @sniper.ai/core/checklists/
+.claude/
+  agents/                  ← Copied from @sniper.ai/core/agents/
+  settings.json            ← Merge hooks from @sniper.ai/core/hooks/
+CLAUDE.md                  ← Generated from template
+```
+
+### 5. Apply Plugins
+
+If plugins are configured (or auto-detected):
+1. Read each plugin's `plugin.yaml`
+2. Merge plugin commands into config
+3. Copy plugin mixins to `.claude/personas/cognitive/`
+4. Merge plugin hooks into `.claude/settings.json`
+
+### 6. Confirm
+
+Display summary:
+- Files created/modified
+- Detected stack
+- Suggested next step: "Run `/sniper-flow` to start your first protocol"
+
+## Rules
+
+- NEVER overwrite existing project source files
+- ALWAYS back up existing config before reinitializing
+- ALWAYS show the user what will be created before doing it
+- Respect `.gitignore` — add `.sniper/checkpoints/` and `.sniper/gates/` if not present

package/skills/sniper-review/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: sniper-review
+description: Manually trigger a review gate for the current phase
+arguments:
+  - name: phase
+    description: Phase to review (defaults to current phase from live-status)
+    required: false
+---
+
+# /sniper-review
+
+Manually trigger a quality gate review. Use this when you want to run gate checks outside of the normal protocol flow.
+
+## Process
+
+### 1. Determine Phase
+
+- If `--phase` is specified, use it
+- Otherwise, read `.sniper/live-status.yaml` for the current phase
+- If no active phase, ask the user which phase checklist to run
+
+### 2. Load Checklist
+
+Read the checklist from `.sniper/checklists/<phase>.yaml` (or from `.claude/` if scaffolded there).
+
+### 3. Run Checks
+
+Spawn a gate-reviewer agent to execute the checklist:
+- Use the Task tool with the gate-reviewer agent definition
+- Pass the checklist path and phase name
+- Wait for the gate result
+
+### 4. Present Results
+
+Display the gate result:
+- Overall: PASS or FAIL
+- Each check with status and any output
+- Blocking failures highlighted
+- Suggestions for fixing failures
+
+### 5. Write Result
+
+Save the gate result to `.sniper/gates/<phase>-<timestamp>.yaml`.
+
+## Rules
+
+- This is a manual trigger — it does NOT advance the protocol phase
+- Always write results to `.sniper/gates/` for audit trail
+- If checks reference commands that don't exist in config, skip with a warning