@sniper.ai/core 1.0.1 → 3.0.0

package/skills/sniper-flow/SKILL.md

@@ -0,0 +1,243 @@
+---
+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.
+
+## Protocol Selection
+
+If `--protocol` is specified, use it directly. Otherwise, auto-detect:
+
+1. Read `.sniper/config.yaml` for routing rules
+2. If this is a new project (no source files), use `full`
+3. If resuming (`--resume`), read the last checkpoint to determine protocol
+4. Otherwise, estimate scope:
+   - Analyze the user's request complexity
+   - `hotfix` — Critical/urgent production fix ("critical", "urgent", "production down", "hotfix")
+   - `patch` — Bug fix or small change (< 5 files likely affected)
+   - `feature` — New feature or significant enhancement (5-20 files)
+   - `full` — New project, major rework, or multi-component change (20+ files)
+   - `ingest` — User wants to understand/document an existing codebase
+   - `explore` — Exploratory analysis, understanding, or research ("what is", "how does", "analyze", "explore")
+   - `refactor` — Code improvement without new features ("refactor", "clean up", "improve", "reorganize")
+
+Announce the selected protocol and ask for confirmation before proceeding.
+
+### Trigger Table Evaluation
+
+After auto-detection, evaluate trigger tables from `.sniper/config.yaml`:
+
+1. Read `triggers` array from config
+2. Get changed files via `git diff --name-only` (or `git status` for new files)
+3. For each trigger entry, glob-match changed files against `pattern`
+4. If a trigger matches:
+   - If `protocol` is specified, it can override the auto-detected protocol
+   - If `agent` is specified, that agent is added to the phase's agent list
+5. Trigger matches are additive — they refine the selection, not replace it
+6. Log which triggers matched and what they changed
+
+## Resume Support
+
+When `--resume` is specified:
+1. Read the latest checkpoint from `.sniper/checkpoints/`
+2. Determine which phase was in progress and which agents were active
+3. Re-spawn agents that had incomplete tasks
+4. Continue from the checkpoint state
+
+## Protocol Resolution (Custom Protocols — Feature 6)
+
+When resolving a protocol name, check in order:
+1. `.sniper/protocols/<name>.yaml` — User-defined custom protocols take priority
+2. Core protocols from `@sniper.ai/core/protocols/<name>.yaml` — Built-in protocols
+
+This allows users to override built-in protocols or define entirely new ones.
+
+## Phase Execution Loop
+
+For each phase in the protocol:
+
+### 0. Pre-Phase Setup
+
+**Load Workspace Context (Feature 1):**
+If a workspace exists (`.sniper-workspace/` in a parent directory):
+1. Read `.sniper-workspace/config.yaml`
+2. Extract `shared.conventions` and `shared.anti_patterns`
+3. These will be injected into agent context in step 2
+
+**Load Relevant Signals (Feature 8):**
+1. Read `.sniper/memory/signals/` for signal records
+2. Match signals by `affected_files` (files that will be touched in this phase) and `relevance_tags`
+3. Select top 10 most relevant signals
+4. These will be injected as "## Recent Learnings" in agent context in step 2
+
+**Check Workspace Conflicts (Feature 5):**
+If a workspace exists:
+1. Check `.sniper-workspace/locks/` for advisory file locks
+2. If any files that this phase's agents will modify are locked by another project, flag the conflict
+3. Present conflicts to the user and wait for resolution before proceeding
+4. Acquire advisory locks for files this phase will modify
+
+### 1. Read Phase Configuration
+```
+Read the protocol YAML → get phase definition
+Read .sniper/config.yaml → get agent config, ownership, commands
+Read .sniper/memory/velocity.yaml → check for calibrated budget (if exists)
+```
+
+**Velocity-Aware Budget Selection:**
+- Check `.sniper/memory/velocity.yaml` for a `calibrated_budget` for the current protocol
+- If a calibrated budget exists and differs from the configured budget, use the calibrated budget
+- Log which budget source is being used: "Using calibrated budget (X tokens)" or "Using configured budget (X tokens)"
+- The calibrated budget takes precedence over `config.routing.budgets`
+
+### 2. Compose Agents
+For each agent in the phase:
+1. Read the base agent definition from `.claude/agents/<name>.md`
+2. Check config for mixins: `config.agents.mixins.<agent-name>`
+3. If mixins exist, read each mixin from `.claude/personas/cognitive/<mixin>.md`
+4. The agent's full prompt = base definition + concatenated mixins
+
+**Load Domain Knowledge (Feature 9):**
+After composing the base agent:
+1. Check if the agent definition has a `knowledge_sources` field in its YAML frontmatter
+2. If present, read `.sniper/knowledge/manifest.yaml`
+3. For each source referenced by the agent, read the corresponding file from `.sniper/knowledge/`
+4. Truncate content to stay within `config.knowledge.max_total_tokens` (default: 50000 tokens)
+5. Append matched knowledge as `## Domain Knowledge` section in the agent's prompt
+
+**Inject Workspace Conventions (Feature 1):**
+If workspace conventions were loaded in step 0:
+1. Append shared conventions as `## Workspace Conventions` section
+2. Append anti-patterns as `## Anti-Patterns (Workspace)` section
+
+**Inject Recent Signals (Feature 8):**
+If relevant signals were loaded in step 0:
+1. Format each signal as: `- [<type>] <summary> (<affected_files>)`
+2. Append as `## Recent Learnings` section in the agent's prompt
+
+### 3. Determine Spawn Strategy
+Based on the protocol's `spawn_strategy` for this phase:
+- `single` — Use the Task tool directly (one agent, no team overhead)
+- `team` — Use TeamCreate + Task tool (multiple agents working in parallel)
+
+### 4. Spawn Agents
+For `single` spawn:
+```
+Task tool with:
+  - subagent_type: general-purpose
+  - model: from agent frontmatter or config default
+  - prompt: composed agent prompt + task assignment
+  - mode: "plan" if plan_approval is true, else "bypassPermissions"
+  - isolation: "worktree" if agent has isolation: worktree
+```
+
+For `team` spawn:
+```
+TeamCreate → create team for this phase
+TaskCreate → create tasks with dependencies from protocol
+Task tool → spawn each teammate with team_name
+```
+
+### 5. Monitor Progress
+- Use TaskList to monitor agent task completion
+- If an agent is blocked, investigate and provide guidance via SendMessage
+- If an agent fails, note the failure and continue with other agents
+
+### 6. Write Checkpoint
+After all agents complete (or fail), write a checkpoint:
+```yaml
+# .sniper/checkpoints/<protocol>-<phase>-<timestamp>.yaml
+protocol: <name>
+phase: <phase>
+timestamp: <ISO 8601>
+status: completed | failed
+agents: [status per agent]
+token_usage: [phase + cumulative]
+commits: [git SHAs produced during this phase]
+```
+
+**Record Git Commits (Feature 2):**
+After agents complete, capture commits for logical revert support:
+1. Run `git log --oneline <start-sha>..HEAD` to find new commits since the phase started
+2. Record each commit's SHA, message, and the agent that produced it
+3. Include the `commits` array in the checkpoint YAML
+
+### 7. Run Gate
+Trigger the gate-reviewer for this phase:
+1. Write `.sniper/pending-gate.yaml` with the phase name and checklist reference
+2. Spawn gate-reviewer agent (or let the Stop hook trigger it)
+3. Read the gate result from `.sniper/gates/`
+
+### 8. Process Gate Result
+- If gate passes AND `human_approval: false` → advance to next phase
+- If gate passes AND `human_approval: true` → present results to user, wait for approval
+- If gate fails → identify blocking failures, reassign to appropriate agents, re-run gate
+
+### 9. Advance Phase
+Move to the next phase in the protocol. If this was the last phase, complete the protocol.
+
+## Protocol Completion
+
+When all phases complete:
+1. Write final checkpoint
+2. Update `.sniper/live-status.yaml` with `status: completed`
+3. If `auto_retro: true` in the protocol, trigger retro-analyst
+4. Present summary to user: phases completed, gate results, token usage
+
+## Cost Tracking
+
+Throughout execution:
+1. Maintain `.sniper/cost.yaml` with token usage per phase and agent
+2. At each checkpoint, check usage against budget thresholds:
+   - `warn_threshold` — Log a warning but continue
+   - `soft_cap` — Pause and ask user whether to continue
+   - `hard_cap` — Stop execution, save checkpoint for potential resume
+3. Read thresholds from `.sniper/config.yaml` cost section
+
+## Merge Coordination
+
+For agents working in worktrees:
+1. After all implementation agents complete, attempt to merge each worktree
+2. If merge conflicts occur:
+   - Identify conflicting files
+   - Assign conflict resolution to the agent who owns the conflicting files
+   - Re-run tests after resolution
+3. The orchestrator coordinates merges — agents never merge their own worktrees
+
+## Live Status Updates
+
+Keep `.sniper/live-status.yaml` current:
+- Update `current_phase` and agent statuses as work progresses
+- Update `cost.percent` at checkpoints
+- Set `next_action` to a human-readable description of what's happening
+
+## Error Handling
+
+- If an agent crashes, note the failure and checkpoint state
+- If a gate fails 3 times, escalate to the user with a summary of failures
+- If cost exceeds hard cap, save checkpoint and stop gracefully
+- Never lose work — always checkpoint before stopping
+
+## Rules
+
+- ALWAYS read `.sniper/config.yaml` before spawning any agent
+- ALWAYS checkpoint between phases
+- ALWAYS respect token budgets
+- 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

package/skills/sniper-flow-headless/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: sniper-flow-headless
+description: Execute a SNIPER protocol non-interactively for CI/CD environments
+arguments:
+  - name: protocol
+    description: Protocol to run (full, feature, patch, ingest, explore, refactor, hotfix)
+    required: true
+  - name: output
+    description: Output format (json, yaml, text)
+    required: false
+  - name: auto-approve
+    description: Auto-approve all gates
+    required: false
+    type: boolean
+  - name: timeout
+    description: Timeout in minutes
+    required: false
+---
+
+# /sniper-flow-headless
+
+You are the SNIPER headless protocol execution engine. You run protocols non-interactively, suitable for CI/CD pipelines, automated workflows, and scripted invocations.
+
+This skill follows the same Phase Execution Loop as `/sniper-flow` but with all interactive decisions resolved automatically. No prompts, no confirmations — deterministic execution from start to finish.
+
+## Key Differences from /sniper-flow
+
+- **No interactive prompts** — protocol must be specified via `--protocol`, never auto-detected interactively
+- **Automatic gate approval** — when `--auto-approve` is set, gates pass without human review
+- **Structured output** — results are written to stdout in the requested `--output` format (json, yaml, or text)
+- **Exit codes** — process exits with a code indicating the result:
+  - `0` — Success: all phases and gates passed
+  - `1` — Gate failure: a blocking gate check failed
+  - `2` — Cost exceeded: token usage hit the hard cap
+  - `3` — Timeout: execution exceeded the `--timeout` duration
+  - `4` — Config error: invalid config, missing protocol, or initialization failure
+
+## Execution
+
+### 1. Validate Configuration
+
+```
+Read .sniper/config.yaml
+Validate the specified --protocol exists (built-in or custom)
+If config is missing or invalid, exit with code 4
+```
+
+### 2. Phase Execution Loop
+
+For each phase in the protocol, execute the same steps as `/sniper-flow`:
+
+1. **Read Phase Configuration** — load protocol YAML, config, and velocity data
+2. **Compose Agents** — assemble base agent definitions with configured mixins
+3. **Determine Spawn Strategy** — `single` or `team` per the protocol phase definition
+4. **Spawn Agents** — delegate work via Task tool or TeamCreate
+5. **Monitor Progress** — track agent completion via TaskList; no interactive guidance
+6. **Write Checkpoint** — persist phase state to `.sniper/checkpoints/`
+7. **Run Gate** — spawn gate-reviewer for the phase
+8. **Process Gate Result**:
+   - If `--auto-approve` is set: gate always passes, log the result
+   - If `--auto-approve` is NOT set: gate must pass on its own merits; failure exits with code 1
+9. **Advance Phase** — proceed to the next phase or complete
+
+### 3. Timeout Enforcement
+
+- Track elapsed wall-clock time from execution start
+- If `--timeout` minutes is exceeded at any checkpoint boundary, save checkpoint and exit with code 3
+- Timeout is checked between phases, not mid-phase
+
+### 4. Cost Enforcement
+
+- Follow the same cost tracking as `/sniper-flow`
+- At `warn_threshold`: log warning to stderr, continue
+- At `soft_cap`: in headless mode, treat as hard cap (no interactive prompt available)
+- At `hard_cap`: save checkpoint, exit with code 2
+
+### 5. Output
+
+On completion (success or failure), write structured output to stdout:
+
+```yaml
+protocol: <name>
+status: success | gate_fail | cost_exceeded | timeout | config_error
+phases:
+  - name: <phase>
+    status: completed | failed | skipped
+    gate_result: passed | failed | auto_approved
+    tokens: <number>
+total_tokens: <number>
+duration_seconds: <number>
+errors: []
+```
+
+Format this structure according to `--output`: JSON (default in CI), YAML, or plain text table.
+
+## Rules
+
+- ALWAYS read `.sniper/config.yaml` before spawning any agent
+- ALWAYS checkpoint between phases
+- ALWAYS respect token budgets — soft cap is treated as hard cap in headless mode
+- ALWAYS exit with the correct exit code
+- NEVER prompt for user input — all decisions must be automatic
+- NEVER skip a gate — evaluate every gate, auto-approve only if `--auto-approve` is set
+- NEVER implement code yourself — delegate all work to agents
+- Output structured results to stdout; diagnostics and logs go to stderr

package/skills/sniper-init/SKILL.md

@@ -0,0 +1,103 @@
+---
+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/
+docs/
+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

package/skills/sniper-status/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: sniper-status
+description: Show current SNIPER protocol progress and cost
+arguments: []
+---
+
+# /sniper-status
+
+Display the current state of SNIPER in this project.
+
+## Process
+
+### 1. Read State Files
+
+Read the following files (skip if they don't exist):
+- `.sniper/config.yaml` — Project configuration
+- `.sniper/live-status.yaml` — Active protocol progress
+- `.sniper/cost.yaml` — Token usage tracking
+
+If `.sniper/config.yaml` doesn't exist, display: "SNIPER is not initialized. Run `/sniper-init` first."
+
+### 2. Display Status
+
+Format and display:
+
+**Project Info**:
+- Project name and type
+- Stack summary (language, framework, database)
+- Plugins installed
+
+**Protocol Status** (if active):
+- Protocol name and current phase
+- Phase progress (completed/total phases)
+- Agent status per active phase
+- Gate results for completed phases
+
+**Cost Summary** (if tracking enabled):
+- Tokens used vs budget
+- Budget percentage with visual bar
+- Warning if approaching soft/hard cap
+
+**Recent Activity**:
+- Last 3 checkpoints with timestamps
+- Last gate result
+
+**Velocity Trends** (if velocity data exists):
+- Read `.sniper/memory/velocity.yaml`
+- Show last 5 executions per protocol with tokens used
+- Show calibrated budget vs configured budget comparison
+- Show trend direction: ↑ (increasing usage), ↓ (decreasing usage), → (stable)
+
+### 3. Format Output
+
+Use clear formatting:
+```
+Project: my-app (saas)
+Stack:   TypeScript, Next.js, PostgreSQL
+
+Protocol: feature (phase 2/3)
+Phase:    implement [===========-----] 68%
+  backend-dev:  implementing (3/5 tasks)
+  qa-engineer:  waiting
+
+Gates:
+  plan:      PASS (2025-01-15)
+
+Cost: 245K / 800K tokens (31%)
+[======--------------] 31%
+
+Velocity:
+  feature: 612K avg (calibrated: 750K, configured: 800K) →
+  patch:   145K avg (calibrated: 180K, configured: 200K) ↓
+```
+
+## Rules
+
+- Read-only — this skill never modifies any files
+- If no protocol is active, show config summary only
+- If cost tracking is disabled, skip cost section

package/templates/architecture.md

@@ -0,0 +1,23 @@
+# Architecture
+<!-- Budget: 4000 tokens max -->
+
+## Context
+<!-- ~400 tokens: Technical context, constraints, existing system landscape -->
+
+## Decisions
+<!-- ~800 tokens: Key architectural decisions with rationale -->
+<!-- For each decision: Context | Options Considered | Decision | Consequences -->
+
+## Components
+<!-- ~1000 tokens: Component breakdown with responsibilities -->
+<!-- For each component: Name | Responsibility | Dependencies | Owner -->
+
+## Data Model
+<!-- ~600 tokens: Core entities and relationships -->
+
+## API Contracts
+<!-- ~800 tokens: Key API interfaces including error cases -->
+<!-- For each endpoint: Method | Path | Request | Response | Errors -->
+
+## Infrastructure
+<!-- ~400 tokens: Deployment, scaling, monitoring considerations -->

package/templates/checkpoint.yaml

@@ -0,0 +1,27 @@
+# Phase checkpoint — snapshot of protocol state
+protocol: ""
+phase: ""
+timestamp: ""
+status: ""  # in_progress | completed | failed
+
+agents:
+  - name: ""
+    status: ""  # active | completed | failed
+    tasks_completed: 0
+    tasks_total: 0
+
+gate_result: null  # null if gate not yet run
+# gate_result:
+#   result: pass | fail
+#   blocking_failures: 0
+
+artifacts_produced: []
+# - path: docs/spec.md
+#   status: draft | complete
+
+token_usage:
+  phase_tokens: 0
+  cumulative_tokens: 0
+  budget_remaining: 0
+
+notes: ""

package/templates/codebase-overview.md

@@ -0,0 +1,19 @@
+# Codebase Overview
+<!-- Budget: 2000 tokens max -->
+
+## Architecture
+<!-- ~400 tokens: High-level architecture pattern and key design decisions -->
+
+## Key Modules
+<!-- ~500 tokens: Core modules/packages with responsibilities -->
+| Module | Path | Responsibility |
+|--------|------|---------------|
+
+## Data Flow
+<!-- ~400 tokens: How data moves through the system -->
+
+## Conventions
+<!-- ~400 tokens: Coding patterns, naming conventions, project-specific rules -->
+
+## Risks
+<!-- ~300 tokens: Technical debt, fragile areas, known issues -->

package/templates/cost.yaml

@@ -0,0 +1,23 @@
+# Cost tracking for protocol execution
+protocol: ""
+started_at: ""
+budget: 0
+
+phases: []
+# - name: discover
+#   started_at: ""
+#   completed_at: ""
+#   tokens_used: 0
+#   agents:
+#     - name: analyst
+#       tokens_used: 0
+
+totals:
+  tokens_used: 0
+  budget_remaining: 0
+  budget_percent_used: 0
+
+enforcement:
+  warn_threshold: 0.7    # Warn at 70% budget
+  soft_cap: 0.9          # Soft cap at 90% — agents must justify continuation
+  hard_cap: 1.0          # Hard cap at 100% — stop execution