Core Concepts

SNIPER is built on a set of interlocking concepts. Understanding these will help you get the most out of the framework.

Phases

A phase is a distinct stage in the project lifecycle. Each phase has a specific purpose, agents assigned to it, defined outputs, and a review gate.

All phases are executed through /sniper-flow, the core protocol engine. There are no standalone phase commands -- /sniper-flow auto-detects the appropriate protocol or you specify one explicitly with --protocol <name>.

Phase Catalog

Phase	Used In	Agents	Outputs	Gate
discover	full, explore	analyst	discovery brief, codebase overview	Flexible
define	full, feature	product-manager	PRD, requirements	Strict
design	full, feature	architect	architecture document	Strict
solve	full, feature	product-manager	stories with acceptance criteria	Strict
implement	full, feature, patch, refactor, hotfix	fullstack-dev, qa-engineer	source code, tests	Flexible
review	full, feature, patch, refactor	code-reviewer	review report	Strict
retro	full, feature, refactor	retro-analyst	retrospective, memory updates	Auto
scan	ingest	analyst	codebase overview	Auto
document	ingest	analyst	spec	Auto
extract	ingest	analyst	conventions	Auto
analyze	refactor	analyst	spec	Auto

Phases are tracked in the state.phase_log array in .sniper/config.yaml. Each entry records when it started, when it completed, and who approved it.

Protocols

A protocol is a YAML state machine that chains phases together into a complete workflow. SNIPER ships seven built-in protocols:

Protocol	Command	Phases	Use Case
full	/sniper-flow	discover → define → design → solve → implement → review → retro	Greenfield projects, major features
feature	/sniper-flow --protocol feature	define → design → solve → implement → review → retro	Incremental feature on an existing codebase
patch	/sniper-flow --protocol patch	implement → review	Bug fix or small change
ingest	/sniper-flow --protocol ingest	scan → document → extract	Reverse-engineer artifacts from existing code
explore	/sniper-flow --protocol explore	discover	Read-only codebase analysis
refactor	/sniper-flow --protocol refactor	analyze → implement → review → retro	Code improvement and cleanup
hotfix	/sniper-flow --protocol hotfix	implement	Critical fix, no gates

When you run /sniper-flow without --protocol, the lead-orchestrator auto-detects the best protocol based on your intent. Use --protocol <name> to override. Interrupted protocols can be resumed with /sniper-flow --resume.

See Custom Protocols for how to define your own.

Agents

In v3, agents are defined as standalone files in packages/core/agents/. Each agent has a YAML frontmatter specifying its model, tools, and constraints, followed by Markdown instructions. The 13 built-in agents are:

• lead-orchestrator — coordinates agent teams, read-only (only writes to .sniper/)
• analyst — researches markets, competitors, and user needs during discovery
• architect — designs system architecture and component boundaries
• product-manager — writes PRDs and requirement specifications
• backend-dev — implements backend logic, APIs, and data layers
• frontend-dev — implements UI components, client-side logic
• fullstack-dev — handles cross-cutting concerns spanning front and back
• qa-engineer — writes and runs tests, validates acceptance criteria
• code-reviewer — reviews code quality, patterns, and standards
• gate-reviewer — evaluates phase artifacts against quality checklists
• retro-analyst — produces retrospectives and captures learnings
• doc-writer — incrementally updates project documentation after implementation
• memory-curator — curates and maintains project memory (conventions, anti-patterns, decisions)

Cognitive Personas

Cognitive personas are optional mixins that shape how an agent thinks. They overlay a reasoning style onto any agent:

• devils-advocate — challenges assumptions, identifies what could go wrong
• security-first — evaluates every decision through a security lens
• performance-focused — optimizes for speed, efficiency, and resource usage

Domain Packs

Domain packs inject industry-specific knowledge into agents. For example, the sales-dialer pack provides telephony, CRM integration, and compliance context.

Applying Cognitive Personas

Configure a cognitive persona on any agent in .sniper/config.yaml:

3 lines

agents:
  architect:
    cognitive: security-first

When a phase launches the architect agent, the lead-orchestrator merges the security-first cognitive mixin into the agent's spawn prompt at runtime.

Teams

When a protocol phase requires multiple agents, SNIPER spawns a team using Claude Code's TeamCreate and Task tools. The protocol YAML defines which agents participate and how they coordinate.

33 lines

# From protocols/full.yaml — define phase
- name: define
  description: PRD and requirements specification
  agents:
    - product-manager
  spawn_strategy: single
  gate:
    checklist: define
    human_approval: true
  outputs:
    - docs/prd.md

- name: design
  description: System architecture aligned with PRD
  agents:
    - architect
  spawn_strategy: single
  gate:
    checklist: design
    human_approval: true
  outputs:
    - docs/architecture.md

- name: solve
  description: Story sharding with acceptance criteria
  agents:
    - product-manager
  spawn_strategy: single
  gate:
    checklist: solve
    human_approval: true
  outputs:
    - docs/stories/

Key fields:

• agents -- which agent definitions to spawn for this phase
• spawn_strategy -- single (one agent, no team) or team (multiple agents via TeamCreate)
• coordination -- pairs of agents that must align before proceeding
• plan_approval -- whether the lead-orchestrator must approve each agent's approach before coding
• gate -- the quality checklist and whether human sign-off is required

Spawn Prompts

A spawn prompt is the fully assembled instruction given to an agent when it is created. It combines:

1. The agent definition (from packages/core/agents/)
2. An optional cognitive mixin (e.g., security-first, devils-advocate)
3. An optional domain pack (e.g., sales-dialer)
4. Project memory (conventions, anti-patterns, decisions from .sniper/memory/)
5. File ownership boundaries
6. Task-specific instructions and context
7. Coordination partners from the protocol definition

The lead-orchestrator assembles spawn prompts at runtime when launching agents for each phase.

Artifacts

Artifacts are the documents and code produced by each phase. They persist on disk in the docs/ directory:

Phase	Artifacts
discover	docs/discovery-brief.md, docs/codebase-overview.md
define	docs/prd.md
design	docs/architecture.md
solve	docs/stories/
implement	Source code and test files in the project's source directories
review	docs/review-report.md
retro	.sniper/memory/ updates
ingest (scan)	docs/codebase-overview.md
ingest (document)	docs/spec.md
ingest (extract)	.sniper/conventions.yaml

Each artifact's status (null, draft, approved) and version number are tracked in state.artifacts in the config file.

TIP

Artifacts persist on disk between phase runs. If a phase is re-run, agents enter amendment mode -- updating existing artifacts rather than starting from scratch. Completed stories are never overwritten.

Review Gates

Review gates are quality checkpoints between phases. Each gate has:

• A checklist -- markdown file with specific criteria to evaluate
• A mode -- strict, flexible, or auto
• Evaluation results -- PASS, WARN, or FAIL for each criterion

Gate Modes

Mode	Behavior
strict	Full stop. Human must explicitly approve. Cannot be skipped.
flexible	Auto-advance if no failures. Human reviews asynchronously.
auto	No gate. Advances immediately. Not recommended for architecture or code.

The default configuration uses strict gates for plan and review phases (where bad decisions are costly) and flexible gates for discover and implement phases (where output can be refined later).

See Review Gates for detailed configuration and checklist examples.

File Ownership

File ownership rules prevent agents from stepping on each other's work. Each teammate is assigned directories they can modify:

13 lines

ownership:
  backend:
    - "src/backend/"
    - "src/api/"
    - "src/services/"
    - "src/db/"
  frontend:
    - "src/frontend/"
    - "src/components/"
    - "src/hooks/"
  tests:
    - "tests/"
    - "*.test.*"

When an implement-phase agent is spawned, their ownership boundaries are injected into their spawn prompt. The agent is instructed to only modify files within those boundaries.

Next Steps

• Configuration -- customize every section of config.yaml
• Full Lifecycle -- detailed walkthrough of all phases
• Personas -- deep dive into the persona composition system
• Teams -- understand team YAML structure and coordination