@sniper.ai/core 1.0.0

package/README.md

@@ -0,0 +1,73 @@
+# @sniper.ai/core
+
+Framework core for SNIPER — provides personas, team compositions, templates, checklists, workflows, and spawn prompts as raw YAML and Markdown files.
+
+## Overview
+
+This package contains no executable code. It ships the framework content that the CLI scaffolds into target projects and that Claude Code agents consume at runtime. Everything lives in the `framework/` directory.
+
+## Installation
+
+```bash
+npm install @sniper.ai/core
+```
+
+## Contents
+
+```
+framework/
+├── personas/           # Agent persona layers
+│   ├── cognitive/      # Thinking styles (analytical, creative, security-first, etc.)
+│   ├── domain/         # Domain knowledge (from packs or built-in)
+│   ├── process/        # Process roles (architect, implementer, reviewer, etc.)
+│   └── technical/      # Technical expertise (frontend, backend, infra, etc.)
+├── teams/              # Team compositions per phase
+│   ├── discover.yaml   # Discovery phase team
+│   ├── plan.yaml       # Planning phase team
+│   ├── solve.yaml      # Story sharding (sequential)
+│   ├── sprint.yaml     # Implementation sprint team
+│   └── doc.yaml        # Documentation team
+├── workflows/          # Phase workflow definitions
+│   ├── full-lifecycle.md
+│   ├── discover-only.md
+│   ├── quick-feature.md
+│   └── sprint-cycle.md
+├── templates/          # Artifact templates (PRD, architecture, stories, etc.)
+├── checklists/         # Quality gate checklists for review
+├── spawn-prompts/      # Pre-composed spawn prompts for agent roles
+├── commands/           # Slash command definitions
+├── config.template.yaml
+├── claude-md.template
+└── settings.template.json
+```
+
+## Usage
+
+Import framework files directly via the `./framework/*` export:
+
+```js
+import { readFileSync } from 'fs';
+import { createRequire } from 'module';
+
+// Resolve the path to a framework file
+const require = createRequire(import.meta.url);
+const teamPath = require.resolve('@sniper.ai/core/framework/teams/sprint.yaml');
+const teamYaml = readFileSync(teamPath, 'utf-8');
+```
+
+## Persona Layers
+
+Agents are composed from four persona layers:
+
+| Layer | Purpose | Example |
+|-------|---------|---------|
+| **Cognitive** | Thinking style and approach | `analytical`, `security-first` |
+| **Process** | Role in the workflow | `architect`, `implementer`, `reviewer` |
+| **Technical** | Technical expertise area | `frontend`, `backend`, `infra` |
+| **Domain** | Project-specific knowledge | Provided by domain packs |
+
+The `/sniper-compose` command combines these layers into a complete spawn prompt for an agent.
+
+## License
+
+MIT

package/framework/checklists/code-review.md

@@ -0,0 +1,33 @@
+# Per-Story Code Review Checklist
+
+Used by QA engineer and team lead to review individual story implementations.
+
+## Functionality
+- [ ] All acceptance criteria from the story are implemented
+- [ ] Error cases are handled (not just the happy path)
+- [ ] Edge cases considered (empty input, max values, concurrent access)
+
+## Code Quality
+- [ ] Code is readable — another developer can understand it without explanation
+- [ ] No dead code, commented-out code, or TODO items left behind
+- [ ] Functions are focused — each does one thing
+- [ ] Naming is clear and consistent with codebase conventions
+- [ ] No unnecessary complexity — simplest solution that works
+
+## Testing
+- [ ] Unit tests cover the public API of new modules
+- [ ] Integration tests verify end-to-end behavior
+- [ ] Tests are deterministic (no timing dependencies, no flakiness)
+- [ ] Test names describe the behavior being tested
+
+## Security
+- [ ] User input is validated before processing
+- [ ] SQL queries use parameterized statements
+- [ ] No secrets in code or config
+- [ ] Auth checks in place for protected endpoints
+
+## Performance
+- [ ] No N+1 query patterns
+- [ ] Database queries are indexed appropriately
+- [ ] Large datasets use pagination
+- [ ] No blocking operations on the main thread

package/framework/checklists/discover-review.md

@@ -0,0 +1,33 @@
+# Discovery Review Checklist
+
+Gate mode: **FLEXIBLE** (auto-advance, async review)
+
+## Project Brief (`docs/brief.md`)
+- [ ] Problem statement is specific and evidence-based
+- [ ] At least 3 direct competitors identified with features and pricing
+- [ ] Unique value proposition clearly differentiates from competitors
+- [ ] Target market segment is defined with size estimates
+- [ ] Key assumptions are listed explicitly
+- [ ] Technical constraints are identified
+- [ ] v1 scope recommendation separates in-scope from out-of-scope
+- [ ] Open questions are documented for planning phase
+
+## Risk Assessment (`docs/risks.md`)
+- [ ] Technical feasibility risks are identified with specifics
+- [ ] Integration risks are assessed (third-party APIs, services)
+- [ ] Compliance and regulatory risks are documented
+- [ ] Scalability concerns are noted with thresholds
+- [ ] Each risk has a mitigation strategy
+- [ ] Assumptions are challenged — at least 2 devil's advocate findings
+
+## User Personas (`docs/personas.md`)
+- [ ] At least 2 distinct user personas defined
+- [ ] Each persona has: role, goals, pain points, workflows
+- [ ] Primary user journey mapped for each persona
+- [ ] Key friction points identified
+- [ ] Personas are realistic (not idealized)
+
+## Overall
+- [ ] All three artifacts are internally consistent
+- [ ] No critical contradictions between brief, risks, and personas
+- [ ] Sufficient depth for planning phase to begin

package/framework/checklists/doc-review.md

@@ -0,0 +1,39 @@
+# Documentation Review Checklist
+
+Gate mode: **FLEXIBLE** (auto-advance, async review)
+
+## README.md
+- [ ] Has a clear one-line project description
+- [ ] Quick-start instructions use real commands that work from project root
+- [ ] Prerequisites list actual runtime requirements with versions
+- [ ] Features list matches actual project capabilities
+- [ ] Tech stack table is accurate
+- [ ] Project structure tree matches actual directory layout
+- [ ] No placeholder text or unfilled template sections
+
+## Setup Guide (`docs/setup.md`)
+- [ ] Installation steps produce a running environment
+- [ ] Environment variables documented with descriptions
+- [ ] Database setup instructions are complete (if applicable)
+- [ ] All referenced scripts and commands exist
+
+## Architecture Overview (`docs/architecture.md`)
+- [ ] Component diagram or description matches actual codebase
+- [ ] Data flow description is accurate
+- [ ] Technology choices listed match actual stack
+- [ ] Directory structure matches reality
+
+## API Reference (`docs/api.md`)
+- [ ] All public endpoints are documented
+- [ ] Request/response examples use realistic data
+- [ ] Authentication method is accurately described
+- [ ] Error codes match actual API behavior
+
+## General Quality
+- [ ] All code examples are syntactically valid
+- [ ] All internal links between docs resolve correctly
+- [ ] Consistent terminology across all documentation
+- [ ] No contradictions between docs
+- [ ] No TODO markers or placeholder text remaining
+- [ ] Managed section tags (`<!-- sniper:managed -->`) are properly formed
+- [ ] Documentation is concise — no filler or marketing language

package/framework/checklists/plan-review.md

@@ -0,0 +1,52 @@
+# Planning Review Checklist
+
+Gate mode: **STRICT** (human MUST approve before Phase 3)
+
+## PRD (`docs/prd.md`)
+- [ ] Problem statement includes evidence (not just assertions)
+- [ ] User stories follow "As a [persona], I want, so that" format
+- [ ] P0 requirements are minimal — only what's critical for v1
+- [ ] Every requirement has testable acceptance criteria
+- [ ] Non-functional requirements have specific measurable targets
+- [ ] Success metrics have numbers (not vague "improve X")
+- [ ] Out-of-scope explicitly names features users might expect
+- [ ] No duplicate requirements
+
+## Architecture (`docs/architecture.md`)
+- [ ] Every technology choice includes: what, why, alternatives considered
+- [ ] Component diagram shows clear boundaries and interfaces
+- [ ] Data models include field types, constraints, indexes, relationships
+- [ ] API contracts are specific enough for independent frontend/backend implementation
+- [ ] Infrastructure specifies sizing, scaling triggers, cost estimates
+- [ ] Cross-cutting concerns addressed (auth, logging, errors, config)
+- [ ] Non-functional targets have implementation strategies
+- [ ] Security architecture aligns with `docs/security.md`
+
+## UX Specification (`docs/ux-spec.md`)
+- [ ] Information architecture maps all pages/views
+- [ ] Screen inventory covers all user-facing screens
+- [ ] User flows include error paths, not just happy paths
+- [ ] Component specs include all states (default, hover, active, disabled, loading, error)
+- [ ] Responsive breakpoints specify actual layout changes
+- [ ] Accessibility requirements name specific WCAG criteria
+- [ ] UX flows align with PRD user stories
+
+## Security Requirements (`docs/security.md`)
+- [ ] Authentication model specified (OAuth, JWT, session, etc.)
+- [ ] Authorization model specified (RBAC, ABAC, etc.)
+- [ ] Data encryption strategy covers at-rest and in-transit
+- [ ] Compliance requirements name specific regulations
+- [ ] Threat model identifies top attack vectors
+- [ ] Security testing requirements are defined
+
+## Cross-Document Consistency
+- [ ] Architecture API contracts match UX component data needs
+- [ ] Security requirements are implementable within architecture choices
+- [ ] PRD requirements are fully coverable by architecture design
+- [ ] No orphaned requirements (in PRD but not in architecture)
+
+## Approval
+**Reviewer:** _______________
+**Date:** _______________
+**Decision:** APPROVED / NEEDS REVISION
+**Feedback:**

package/framework/checklists/sprint-review.md

@@ -0,0 +1,41 @@
+# Sprint Review Checklist
+
+Gate mode: **STRICT** (human MUST review code before merge)
+
+## Code Quality
+- [ ] All code passes linting (no warnings or errors)
+- [ ] All code passes static type checking (language-appropriate strict mode)
+- [ ] No type escape hatches introduced (e.g. `any` in TS, `Any` in Python, `interface{}` in Go)
+- [ ] No hardcoded secrets, API keys, or credentials
+- [ ] Error handling on all async operations
+- [ ] Follows existing codebase patterns and conventions
+
+## Testing
+- [ ] All stories have corresponding tests
+- [ ] Tests pass (0 failures)
+- [ ] Test coverage meets project minimum threshold
+- [ ] Integration tests cover API endpoints
+- [ ] Edge cases and error paths are tested
+- [ ] No flaky tests introduced
+
+## Acceptance Criteria
+- [ ] Every acceptance criterion from every sprint story is verified
+- [ ] Deviations from acceptance criteria are documented and justified
+
+## Architecture Compliance
+- [ ] Code follows the architecture patterns from `docs/architecture.md`
+- [ ] API contracts match the spec (endpoints, payloads, status codes)
+- [ ] Data models match the schema design
+- [ ] File ownership boundaries respected (no cross-boundary edits)
+
+## Security
+- [ ] No new security vulnerabilities introduced (OWASP Top 10)
+- [ ] Input validation on all user-facing endpoints
+- [ ] Authentication and authorization enforced where required
+- [ ] Sensitive data encrypted and handled properly
+
+## Approval
+**Reviewer:** _______________
+**Date:** _______________
+**Decision:** APPROVED / NEEDS REVISION
+**Feedback:**

package/framework/checklists/story-review.md

@@ -0,0 +1,30 @@
+# Story Review Checklist
+
+Gate mode: **FLEXIBLE** (auto-advance, async review)
+
+## Epic Structure (`docs/epics/*.md`)
+- [ ] Epics number between 6-12 (enough granularity, not too fragmented)
+- [ ] No overlap between epics — each requirement maps to exactly one epic
+- [ ] Epic dependencies form a DAG (no circular dependencies)
+- [ ] Each epic has clear scope boundaries (in/out)
+- [ ] Architecture context is EMBEDDED in each epic, not just referenced
+- [ ] Complexity estimates are realistic
+
+## Story Quality (`docs/stories/*.md`)
+- [ ] Each story is self-contained — a developer can implement from the story file alone
+- [ ] PRD context is EMBEDDED (copied), not just referenced
+- [ ] Architecture context is EMBEDDED (data models, API contracts, patterns)
+- [ ] UX context is EMBEDDED for frontend stories
+- [ ] Acceptance criteria use Given/When/Then format
+- [ ] Every acceptance criterion is testable
+- [ ] Test requirements are specified (unit, integration, e2e)
+- [ ] File ownership is assigned (which directories the story touches)
+- [ ] Dependencies on other stories are declared
+- [ ] Complexity estimate (S/M/L/XL) is assigned
+- [ ] No story is XL — if so, it should be split
+
+## Coverage
+- [ ] All P0 PRD requirements are covered by stories
+- [ ] All P1 PRD requirements are covered by stories
+- [ ] All architecture components have at least one implementing story
+- [ ] Story dependency chains allow reasonable sprint planning

package/framework/claude-md.template

@@ -0,0 +1,37 @@
+# SNIPER Project
+
+## Framework
+This project uses SNIPER (Spawn, Navigate, Implement, Parallelize, Evaluate, Release).
+See `.sniper/config.yaml` for project settings.
+
+## Quick Reference
+- Framework workflows: `.sniper/workflows/`
+- Persona layers: `.sniper/personas/`
+- Team definitions: `.sniper/teams/`
+- Artifact templates: `.sniper/templates/`
+- Quality gates: `.sniper/checklists/`
+- Project artifacts: `docs/`
+- Domain context: `.sniper/domain-packs/{pack-name}/`
+
+## Commands
+- `/sniper-init` — Initialize SNIPER in a new project
+- `/sniper-discover` — Phase 1: Discovery & Analysis (parallel team)
+- `/sniper-plan` — Phase 2: Planning & Architecture (parallel team)
+- `/sniper-solve` — Phase 3: Epic Sharding & Story Creation (sequential)
+- `/sniper-sprint` — Phase 4: Implementation Sprint (parallel team)
+- `/sniper-review` — Run review gate for current phase
+- `/sniper-compose` — Create a spawn prompt from persona layers
+- `/sniper-status` — Show lifecycle status and artifact state
+
+## Agent Teams Rules
+When spawning teammates, always:
+1. Read the relevant team YAML from `.sniper/teams/`
+2. Compose spawn prompts using `/sniper-compose` with the layers specified in the YAML
+3. Assign file ownership boundaries from `config.yaml` ownership rules
+4. Create tasks with dependencies from the team YAML
+5. Enter delegate mode (Shift+Tab) — the lead coordinates, it does not code
+6. Require plan approval for tasks marked `plan_approval: true`
+7. When a phase completes, run `/sniper-review` before advancing
+
+## Code Standards
+See `.sniper/config.yaml` → stack section for language/framework specifics.

package/framework/commands/sniper-compose.md

@@ -0,0 +1,237 @@
+# /sniper-compose -- Compose a Spawn Prompt from Persona Layers
+
+You are executing the `/sniper-compose` command. Your job is to assemble a teammate spawn prompt by merging persona layers into the template. Follow every step below precisely.
+
+The user's arguments are provided in: $ARGUMENTS
+
+---
+
+## Step 0: Parse Arguments
+
+Parse the following flags from `$ARGUMENTS`:
+
+| Flag           | Required | Description                                    | Example                |
+|----------------|----------|------------------------------------------------|------------------------|
+| `--process`    | YES      | Process persona layer name                     | `architect`            |
+| `--technical`  | NO       | Technical persona layer name (null if omitted) | `backend`              |
+| `--cognitive`  | NO       | Cognitive persona layer name (null if omitted) | `security-first`       |
+| `--domain`     | NO       | Domain context name from active domain pack    | `telephony`            |
+| `--name`       | YES      | Display name for the teammate                  | `"Backend Architect"`  |
+| `--ownership`  | NO       | Ownership key from config.yaml                 | `backend`              |
+
+**If `--process` is missing**, print an error:
+```
+ERROR: --process is required. This specifies the process persona layer.
+Usage: /sniper-compose --process architect --technical backend --cognitive security-first --name "Backend Architect"
+Available process layers: analyst, product-manager, architect, ux-designer, scrum-master, developer, qa-engineer
+```
+Then STOP.
+
+**If `--name` is missing**, print an error:
+```
+ERROR: --name is required. This is the display name for the teammate.
+Usage: /sniper-compose --process architect --technical backend --name "Backend Architect"
+```
+Then STOP.
+
+If no arguments are provided at all, print a usage guide:
+```
+SNIPER Compose -- Assemble a spawn prompt from persona layers
+
+Usage:
+  /sniper-compose --process <layer> --name <name> [--technical <layer>] [--cognitive <layer>] [--domain <context>] [--ownership <key>]
+
+Required:
+  --process    Process persona layer (analyst, product-manager, architect, ux-designer, scrum-master, developer, qa-engineer)
+  --name       Display name for the teammate (quoted if spaces)
+
+Optional:
+  --technical  Technical persona layer (backend, frontend, infrastructure, security, ai-ml, database, api-design)
+  --cognitive  Cognitive persona layer (systems-thinker, security-first, performance-focused, user-empathetic, devils-advocate, mentor-explainer)
+  --domain     Domain context from the active domain pack
+  --ownership  Ownership key from config.yaml (backend, frontend, infrastructure, tests, docs)
+
+Examples:
+  /sniper-compose --process architect --technical backend --cognitive security-first --name "Backend Architect" --ownership backend
+  /sniper-compose --process developer --technical frontend --cognitive user-empathetic --name "Frontend Dev" --ownership frontend
+  /sniper-compose --process analyst --cognitive systems-thinker --name "Business Analyst"
+```
+Then STOP.
+
+---
+
+## Step 1: Read the Template
+
+Read the spawn prompt template from:
+```
+.sniper/spawn-prompts/_template.md
+```
+
+If it does not exist, print an error:
+```
+ERROR: Spawn prompt template not found at .sniper/spawn-prompts/_template.md
+Run /sniper-init to set up the framework.
+```
+Then STOP.
+
+Store the template content for merging in Step 4.
+
+---
+
+## Step 2: Read Each Persona Layer
+
+For each specified layer, read the corresponding file. Track which layers were found and which were not.
+
+### 2a: Process Layer (required)
+Read: `.sniper/personas/process/{process_name}.md`
+
+If the file does not exist, print an error listing available process layers:
+```
+ERROR: Process persona '{process_name}' not found.
+Available process layers:
+```
+Then list all `.md` files in `.sniper/personas/process/` (without the extension). Then STOP.
+
+### 2b: Technical Layer (optional)
+If `--technical` was provided, read: `.sniper/personas/technical/{technical_name}.md`
+
+If the file does not exist, print a warning:
+```
+WARNING: Technical persona '{technical_name}' not found. Skipping technical layer.
+Available technical layers:
+```
+Then list all `.md` files in `.sniper/personas/technical/`. Set the technical layer content to:
+```
+No specific technical expertise assigned. Apply general engineering best practices.
+```
+
+### 2c: Cognitive Layer (optional)
+If `--cognitive` was provided, read: `.sniper/personas/cognitive/{cognitive_name}.md`
+
+If the file does not exist, print a warning and list available cognitive layers. Set the cognitive layer content to:
+```
+No specific cognitive style assigned. Apply balanced analytical thinking.
+```
+
+### 2d: Domain Layer (optional)
+If `--domain` was provided:
+1. Read `.sniper/config.yaml` to get the active `domain_pack` value
+2. If `domain_pack` is null, print an error:
+   ```
+   ERROR: No domain pack is configured. Set domain_pack in .sniper/config.yaml or run /sniper-init.
+   ```
+   Set the domain layer content to `No domain-specific context available.`
+3. If `domain_pack` is set, read: `.sniper/domain-packs/{domain_pack}/context/{domain_name}.md`
+4. If the file does not exist, print a warning and list available contexts in that domain pack directory.
+   Set the domain layer content to `No domain-specific context available.`
+
+If `--domain` was NOT provided, set the domain layer content to:
+```
+No domain-specific context loaded. Refer to project documentation for domain knowledge.
+```
+
+---
+
+## Step 3: Read Ownership Rules
+
+Read `.sniper/config.yaml` and extract the `ownership` section.
+
+If `--ownership` was provided:
+1. Look up the ownership key in the config (e.g., `backend`, `frontend`, `infrastructure`, `tests`, `docs`)
+2. Extract the list of directory patterns for that key
+3. Format them as a comma-separated string for the template
+
+If `--ownership` was NOT provided:
+1. Try to infer ownership from the `--technical` flag:
+   - `backend` technical -> `backend` ownership
+   - `frontend` technical -> `frontend` ownership
+   - `infrastructure` technical -> `infrastructure` ownership
+   - `security` technical -> `backend` ownership (security spans backend)
+   - `ai-ml` technical -> `backend` ownership
+   - `database` technical -> `backend` ownership
+   - `api-design` technical -> `backend` ownership
+2. If no technical layer was specified, set ownership to: `"No specific ownership assigned -- coordinate with team lead"`
+
+Format the ownership value as a readable list, for example:
+```
+src/backend/, src/api/, src/services/, src/db/, src/workers/
+```
+
+---
+
+## Step 4: Merge Layers into Template
+
+Take the template content from Step 1 and perform these replacements:
+
+| Placeholder        | Replace With                                  |
+|-------------------|-----------------------------------------------|
+| `{name}`          | The `--name` value                            |
+| `{process_layer}` | Full content of the process persona file      |
+| `{technical_layer}`| Full content of the technical persona file (or default text) |
+| `{cognitive_layer}`| Full content of the cognitive persona file (or default text) |
+| `{domain_layer}`  | Full content of the domain context file (or default text) |
+| `{ownership}`     | Formatted ownership directories from Step 3   |
+
+The merged result is the complete spawn prompt.
+
+---
+
+## Step 5: Write the Composed Prompt
+
+Generate a slug from the `--name` value:
+- Lowercase
+- Replace spaces with hyphens
+- Remove special characters
+- Example: `"Backend Architect"` -> `backend-architect`
+
+Write the composed prompt to:
+```
+.sniper/spawn-prompts/{slug}.md
+```
+
+If a file already exists at that path, overwrite it silently (spawn prompts are regenerated as needed).
+
+---
+
+## Step 6: Display Preview and Summary
+
+Print a summary of what was composed:
+
+```
+============================================
+  Spawn Prompt Composed
+============================================
+
+  Name:       {name}
+  Saved to:   .sniper/spawn-prompts/{slug}.md
+
+  Layers Used:
+    Process:    {process_name} (.sniper/personas/process/{process_name}.md)
+    Technical:  {technical_name or "none"}
+    Cognitive:  {cognitive_name or "none"}
+    Domain:     {domain_name or "none"}
+
+  Ownership:   {ownership_dirs}
+
+============================================
+```
+
+Then print a preview of the composed prompt. Show the FULL content of the generated file so the user can review it.
+
+After the preview, print:
+```
+This spawn prompt is ready to use. It will be loaded when a teammate is created with this persona configuration.
+```
+
+---
+
+## IMPORTANT RULES
+
+- Do NOT modify any persona layer source files -- they are read-only inputs.
+- Do NOT modify the template file -- it is a read-only input.
+- The composed output goes ONLY to `.sniper/spawn-prompts/{slug}.md`.
+- If any required layer file is missing, STOP with a clear error. Do not generate placeholder content for required layers.
+- For optional layers that are missing, use the default text specified above and continue.
+- Always show the full preview so the user can verify before using the prompt.
+- Preserve all markdown formatting from the persona layer files when merging.
+- Do not add any extra content beyond what is in the template and layers.