@sniper.ai/core 1.0.0 → 2.0.0

package/README.md

@@ -1,6 +1,15 @@
 # @sniper.ai/core
 
-Framework core for SNIPER — provides personas, team compositions, templates, checklists, workflows, and spawn prompts as raw YAML and Markdown files.
+[![npm version](https://img.shields.io/npm/v/@sniper.ai/core)](https://www.npmjs.com/package/@sniper.ai/core)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+Framework core for [SNIPER](https://virkt25.github.io/sniper/) -- provides personas, team compositions, templates, checklists, workflows, and spawn prompts as raw YAML and Markdown files.
+
+## What is SNIPER?
+
+SNIPER (**S**pawn, **N**avigate, **I**mplement, **P**arallelize, **E**valuate, **R**elease) is an AI-powered project lifecycle framework for orchestrating Claude Code agent teams through structured phases. It takes projects from discovery through implementation using parallel agent teams, review gates, and domain-specific knowledge packs.
+
+A full lifecycle runs through four phases: **Discover** (research and analysis), **Plan** (architecture and design), **Solve** (epic and story sharding), and **Sprint** (parallel implementation). Each phase spawns a coordinated team of specialized agents composed from layered personas.
 
 ## Overview
 
@@ -16,31 +25,121 @@ npm install @sniper.ai/core
 
 ```
 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
+├── personas/           # Agent persona layers (42 total)
+├── teams/              # Team compositions (17 teams)
+├── workflows/          # Phase workflow definitions (4 workflows)
+├── templates/          # Artifact templates (38 templates)
+├── checklists/         # Quality gate checklists (15 checklists)
+├── spawn-prompts/      # Pre-composed spawn prompts
+├── commands/           # Slash command definitions (18 commands)
 ├── config.template.yaml
 ├── claude-md.template
 └── settings.template.json
 ```
 
+## Persona Layers
+
+Agents are composed from four persona layers, combined via the `/sniper-compose` command into complete spawn prompts:
+
+| Layer | Count | Purpose | Examples |
+|-------|-------|---------|----------|
+| **Cognitive** | 6 | Thinking style and approach | `analytical`, `security-first`, `systems-thinker`, `devils-advocate`, `user-empathetic`, `performance-focused` |
+| **Process** | 29 | Role in the workflow | `architect`, `developer`, `code-reviewer`, `product-manager`, `scrum-master`, `qa-engineer`, `release-manager` |
+| **Technical** | 7 | Technical expertise area | `frontend`, `backend`, `database`, `infrastructure`, `security`, `api-design`, `ai-ml` |
+| **Domain** | -- | Project-specific knowledge | Provided by domain packs (e.g., `@sniper.ai/pack-sales-dialer`) |
+
+## Teams
+
+SNIPER defines 17 team compositions for different workflows:
+
+| Team | File | Description |
+|------|------|-------------|
+| **Discover** | `discover.yaml` | Discovery phase -- analyst, risk-researcher, user-researcher |
+| **Plan** | `plan.yaml` | Planning phase -- PM, architect, UX, security (uses Opus model) |
+| **Solve** | `solve.yaml` | Story sharding -- single scrum-master agent |
+| **Sprint** | `sprint.yaml` | Implementation -- backend-dev, frontend-dev, and other specialists |
+| **Doc** | `doc.yaml` | Documentation generation -- doc-analyst, doc-writer, doc-reviewer |
+| **Ingest** | `ingest.yaml` | Codebase ingestion -- reverse-engineers project artifacts |
+| **Feature Plan** | `feature-plan.yaml` | Incremental feature spec and architecture delta |
+| **Debug** | `debug.yaml` | Production debugging -- parallel investigation agents |
+| **Review PR** | `review-pr.yaml` | Multi-perspective pull request review |
+| **Review Release** | `review-release.yaml` | Multi-perspective release readiness assessment |
+| **Refactor** | `refactor.yaml` | Structured large-scale code refactoring |
+| **Security** | `security.yaml` | Structured security analysis |
+| **Perf** | `perf.yaml` | Structured performance analysis |
+| **Test** | `test.yaml` | Test and coverage audit |
+| **Retro** | `retro.yaml` | Sprint retrospective analysis |
+| **Workspace Feature** | `workspace-feature.yaml` | Cross-repo feature orchestration |
+| **Workspace Validation** | `workspace-validation.yaml` | Interface contract validation |
+
+## Commands
+
+18 slash commands organized by category:
+
+### Lifecycle
+
+| Command | Description |
+|---------|-------------|
+| `/sniper-init` | Initialize SNIPER in a new or existing project |
+| `/sniper-discover` | Phase 1: Discovery and analysis (parallel team) |
+| `/sniper-plan` | Phase 2: Planning and architecture (parallel team) |
+| `/sniper-solve` | Phase 3: Epic sharding and story creation (single agent) |
+| `/sniper-sprint` | Phase 4: Implementation sprint (parallel team) |
+| `/sniper-review` | Run review gate for the current phase |
+| `/sniper-status` | Show lifecycle status and artifact state |
+
+### Extended
+
+| Command | Description |
+|---------|-------------|
+| `/sniper-feature` | Incremental feature lifecycle |
+| `/sniper-ingest` | Codebase ingestion (parallel team) |
+| `/sniper-doc` | Generate or update project documentation (parallel team) |
+| `/sniper-debug` | Production debugging (phased investigation) |
+| `/sniper-audit` | Audit: refactoring, review, and QA |
+
+### Workspace
+
+| Command | Description |
+|---------|-------------|
+| `/sniper-workspace init` | Initialize a SNIPER workspace |
+| `/sniper-workspace feature` | Plan and execute a cross-repo feature |
+| `/sniper-workspace status` | Show workspace status |
+| `/sniper-workspace validate` | Validate interface contracts |
+
+### Utility
+
+| Command | Description |
+|---------|-------------|
+| `/sniper-compose` | Compose a spawn prompt from persona layers |
+| `/sniper-memory` | Manage agent memory (conventions, anti-patterns, decisions) |
+
+## Templates
+
+38 artifact templates covering:
+
+| Category | Templates |
+|----------|-----------|
+| **Discovery** | `brief.md`, `risks.md`, `personas.md` |
+| **Planning** | `prd.md`, `architecture.md`, `ux-spec.md`, `security.md`, `conventions.md` |
+| **Stories** | `epic.md`, `story.md` |
+| **Features** | `feature-brief.md`, `feature-spec.md`, `arch-delta.md` |
+| **Reviews** | `pr-review.md`, `sprint-review.md`, `release-readiness.md` |
+| **Documentation** | `doc-api.md`, `doc-guide.md`, `doc-readme.md` |
+| **Debugging** | `investigation.md`, `postmortem.md`, `bug-report.md` |
+| **Security** | `threat-model.md`, `vulnerability-report.md` |
+| **Performance** | `performance-profile.md`, `optimization-plan.md` |
+| **Refactoring** | `refactor-scope.md`, `migration-plan.md` |
+| **Memory** | `memory-convention.yaml`, `memory-anti-pattern.yaml`, `memory-decision.yaml`, `retro.yaml` |
+| **Workspace** | `workspace-brief.md`, `workspace-plan.md`, `contract.yaml`, `contract-validation-report.md` |
+| **Testing** | `coverage-report.md`, `flaky-report.md` |
+
+## Checklists
+
+15 quality gate checklists for review workflows:
+
+`code-review`, `debug-review`, `discover-review`, `doc-review`, `feature-review`, `ingest-review`, `memory-review`, `perf-review`, `plan-review`, `refactor-review`, `security-review`, `sprint-review`, `story-review`, `test-review`, `workspace-review`
+
 ## Usage
 
 Import framework files directly via the `./framework/*` export:
@@ -55,18 +154,9 @@ 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 |
+## Documentation
 
-The `/sniper-compose` command combines these layers into a complete spawn prompt for an agent.
+Full documentation is available at [virkt25.github.io/sniper](https://virkt25.github.io/sniper/).
 
 ## License
 

package/framework/checklists/debug-review.md

@@ -0,0 +1,34 @@
+# Debug Review Checklist
+
+Use this checklist to review artifacts produced during a bug investigation.
+
+## Bug Report (`docs/bugs/BUG-{NNN}/report.md`)
+
+- [ ] **Summary clarity:** Bug is described in terms of observed behavior, not implementation
+- [ ] **Severity justified:** Severity level matches the described user impact
+- [ ] **Affected components identified:** Components are traced to actual architecture doc entries
+- [ ] **Reproduction steps:** Steps are specific enough to reproduce (or clearly marked "unable to determine")
+- [ ] **Investigation plan:** Specific guidance for log analyst and code investigator
+
+## Investigation (`docs/bugs/BUG-{NNN}/investigation.md`)
+
+- [ ] **Log findings present:** Error patterns documented with specific messages and locations
+- [ ] **Code findings present:** Execution path traced with file:line references
+- [ ] **Root cause identified:** A specific root cause is proposed (not vague)
+- [ ] **Evidence-based:** Findings are backed by specific code references, not speculation
+- [ ] **Recommended fix:** A concrete fix approach is proposed
+- [ ] **Consistency:** Log findings and code findings point to the same root cause
+
+## Post-Mortem (`docs/bugs/BUG-{NNN}/postmortem.md`)
+
+- [ ] **Fix addresses root cause:** The fix targets the actual root cause, not just symptoms
+- [ ] **Files changed listed:** All modified files are documented
+- [ ] **Regression tests added:** Tests specifically prevent this bug from recurring
+- [ ] **Prevention strategy:** At least one process or code change to prevent similar bugs
+- [ ] **Timeline accurate:** Key events are timestamped
+
+## Overall
+
+- [ ] **Artifacts consistent:** Report, investigation, and postmortem tell a coherent story
+- [ ] **No speculation presented as fact:** Hypotheses are clearly labeled
+- [ ] **Actionable:** Another developer could understand and verify the fix

package/framework/checklists/feature-review.md

@@ -0,0 +1,42 @@
+# Feature Review Checklist
+
+Use this checklist to review artifacts produced during a feature lifecycle.
+
+## Feature Brief (`docs/features/SNPR-{XXXX}/brief.md`)
+
+- [ ] **Feature description:** Clearly describes what the feature does in user-facing terms
+- [ ] **Motivation:** Explains why the feature is needed and what problem it solves
+- [ ] **Affected areas:** Lists components and files that will be impacted
+- [ ] **Scope:** In-scope and out-of-scope are clearly delineated
+- [ ] **Risks:** Known risks and open questions are documented
+
+## Feature Spec (`docs/features/SNPR-{XXXX}/spec.md`)
+
+- [ ] **Requirements completeness:** All functional requirements have acceptance criteria
+- [ ] **User stories:** Each story follows the "As a... I want to... So that..." format
+- [ ] **API changes:** New or modified endpoints are fully specified
+- [ ] **Data model changes:** Schema changes are documented with field types and constraints
+- [ ] **Brief alignment:** Spec is consistent with the feature brief (no scope creep)
+
+## Architecture Delta (`docs/features/SNPR-{XXXX}/arch-delta.md`)
+
+- [ ] **Base version:** References the correct version of `docs/architecture.md`
+- [ ] **New components:** Each new component has responsibility, interfaces, and dependencies
+- [ ] **Modified components:** Changes to existing components note current vs new behavior
+- [ ] **Pattern consistency:** New code follows patterns from `docs/conventions.md`
+- [ ] **No over-engineering:** Changes are proportional to the feature scope
+- [ ] **Spec alignment:** Architecture delta addresses all requirements from the spec
+
+## Stories (`docs/features/SNPR-{XXXX}/stories/`)
+
+- [ ] **Coverage:** Stories cover all functional requirements from the spec
+- [ ] **Sizing:** Each story is small enough for a single sprint (S/M complexity preferred)
+- [ ] **Dependencies:** Story dependencies are correctly ordered
+- [ ] **Acceptance criteria:** Each story has clear, testable acceptance criteria
+- [ ] **No gaps:** No requirements from the spec are missing from stories
+
+## Overall
+
+- [ ] **Consistency:** Brief, spec, arch-delta, and stories don't contradict each other
+- [ ] **Proportionality:** Effort matches the feature scope (not over-planned or under-planned)
+- [ ] **Actionable:** An agent reading these artifacts could implement the feature without ambiguity

package/framework/checklists/ingest-review.md

@@ -0,0 +1,42 @@
+# Ingestion Review Checklist
+
+Use this checklist to review artifacts produced by `/sniper-ingest`.
+
+## Project Brief (`docs/brief.md`)
+
+- [ ] **Accuracy:** Brief accurately describes what the project does (not aspirational or hallucinated)
+- [ ] **Problem statement:** Clearly identifies the problem the project solves
+- [ ] **Target users:** Identifies who uses the project (inferred from code, not guessed)
+- [ ] **Current scope:** Lists features that actually exist in the codebase
+- [ ] **Constraints:** Notes technologies and external dependencies that are locked in
+- [ ] **Honest gaps:** Sections that couldn't be inferred are marked "Unable to determine"
+
+## System Architecture (`docs/architecture.md`)
+
+- [ ] **Component diagram:** Includes an ASCII or Mermaid diagram that matches actual code structure
+- [ ] **Directory alignment:** Component boundaries match the actual directory structure
+- [ ] **Data models:** Extracted data models match actual ORM/migration/schema files
+- [ ] **API contracts:** Documented endpoints match actual route definitions
+- [ ] **Technology choices:** Listed technologies match actual dependencies (package.json, etc.)
+- [ ] **Infrastructure:** Infrastructure description matches Docker/Terraform/K8s files (if present)
+- [ ] **Cross-cutting concerns:** Auth, logging, error handling patterns are documented
+- [ ] **No hallucinations:** No components, APIs, or data models that don't exist in the code
+
+## Coding Conventions (`docs/conventions.md`)
+
+- [ ] **Code examples:** Every convention cites a real code example with file path
+- [ ] **Representative sampling:** Conventions are derived from multiple files, not just one
+- [ ] **Inconsistencies noted:** Where patterns conflict, both are documented
+- [ ] **Complete coverage:** Naming, code org, error handling, testing, API, imports, config, logging
+- [ ] **Conventions vs accidents:** Patterns appear in 80%+ of relevant files to qualify as conventions
+
+## Config Ownership (`config.yaml`)
+
+- [ ] **Ownership paths updated:** The `ownership` section in `.sniper/config.yaml` reflects the actual project directory structure, not the template defaults
+- [ ] **All directories covered:** Major source directories are assigned to an ownership category
+
+## Overall
+
+- [ ] **Consistency:** Brief, architecture, and conventions don't contradict each other
+- [ ] **Sufficient depth:** Artifacts provide enough context for agents to work on the codebase
+- [ ] **Actionable:** A developer or agent reading only these artifacts could understand the project's structure and patterns

package/framework/checklists/memory-review.md

@@ -0,0 +1,30 @@
+# Memory Review Checklist
+
+Gate mode: **flexible** (memory entries are informational, auto-advance)
+
+## Conventions (`.sniper/memory/conventions.yaml`)
+- [ ] Every convention has a non-empty `rule` field with a clear, imperative statement
+- [ ] Every convention has a `rationale` explaining why it exists
+- [ ] Every convention has at least one role in `applies_to`
+- [ ] Every convention has `enforcement` set to one of: review_gate, spawn_prompt, both
+- [ ] No two conventions have identical or contradictory rules
+- [ ] Convention IDs are unique and follow the `conv-XXX` pattern
+
+## Anti-Patterns (`.sniper/memory/anti-patterns.yaml`)
+- [ ] Every anti-pattern has a non-empty `description`
+- [ ] Every anti-pattern has a `fix_pattern` describing the correct approach
+- [ ] Every anti-pattern has `severity` set to one of: high, medium, low
+- [ ] Every anti-pattern has at least one role in `applies_to`
+- [ ] Anti-pattern IDs are unique and follow the `ap-XXX` pattern
+
+## Decisions (`.sniper/memory/decisions.yaml`)
+- [ ] Every decision has `title`, `context`, and `decision` fields filled
+- [ ] Every decision has at least one alternative in `alternatives_considered`
+- [ ] Every decision has `status` set to one of: active, superseded, deprecated
+- [ ] Superseded decisions reference the replacing decision in `superseded_by`
+- [ ] Decision IDs are unique and follow the `dec-XXX` pattern
+
+## Overall
+- [ ] No duplicate entries across conventions, anti-patterns, and decisions
+- [ ] All source references are valid (type and ref fields populated)
+- [ ] Candidate entries have sufficient evidence to remain as candidates

package/framework/checklists/perf-review.md

@@ -0,0 +1,33 @@
+# Performance Audit Review Checklist
+
+Use this checklist to review artifacts produced during a performance audit lifecycle.
+
+## Profile Report (`docs/audits/PERF-{NNN}/profile-report.md`)
+
+- [ ] **Actual bottlenecks:** Findings are based on code analysis, not premature optimization guesses
+- [ ] **Specific locations:** Each bottleneck includes file:line or file:function references
+- [ ] **Categorized:** Bottlenecks are categorized (N+1, missing index, sync I/O, etc.)
+- [ ] **Impact assessed:** Severity based on path frequency and latency contribution
+- [ ] **Critical paths traced:** Request handling chains are fully traced
+- [ ] **Existing optimizations noted:** Current caching and indexing acknowledged
+
+## Optimization Plan (`docs/audits/PERF-{NNN}/optimization-plan.md`)
+
+- [ ] **Expected improvement stated:** Each recommendation includes specific improvement description
+- [ ] **Trade-offs documented:** Caching complexity, consistency risks, etc. are noted
+- [ ] **Quick wins identified:** Low-effort, high-impact optimizations separated
+- [ ] **Benchmark requirements:** Each optimization has a corresponding benchmark requirement
+- [ ] **Priority matrix sensible:** Impact/effort ratio drives the ordering
+
+## Stories (`docs/audits/PERF-{NNN}/stories/`)
+
+- [ ] **Paired with benchmarks:** Each optimization story has a companion benchmark story
+- [ ] **Quick wins first:** Low-effort optimizations are prioritized
+- [ ] **Self-contained:** Each story can be implemented and verified independently
+- [ ] **Measurable:** Success criteria include specific performance metrics
+
+## Overall
+
+- [ ] **Data-driven:** No premature optimization — all changes backed by profiling evidence
+- [ ] **Consistency:** Profile, plan, and stories tell a coherent story
+- [ ] **Verification plan:** Clear strategy for measuring improvement after implementation

package/framework/checklists/refactor-review.md

@@ -0,0 +1,33 @@
+# Refactor Review Checklist
+
+Use this checklist to review artifacts produced during a refactoring lifecycle.
+
+## Impact Analysis (`docs/refactors/REF-{NNN}/scope.md`)
+
+- [ ] **Complete inventory:** All instances of the pattern being changed are counted
+- [ ] **Files listed:** Every affected file is listed, not estimated
+- [ ] **Risk assessment:** Risks are specific, not generic boilerplate
+- [ ] **Compatibility concerns:** API consumers and downstream dependencies are identified
+- [ ] **Effort estimate:** Effort is justified by actual file/instance counts
+
+## Migration Plan (`docs/refactors/REF-{NNN}/plan.md`)
+
+- [ ] **Strategy justified:** Migration strategy choice (big-bang/incremental/strangler) has clear rationale
+- [ ] **Order makes sense:** Steps follow dependency order (e.g., shared code before consuming code)
+- [ ] **Coexistence plan:** Describes how old and new patterns coexist during migration
+- [ ] **Verification at each step:** Each step has specific tests or checks
+- [ ] **Rollback plan:** Each step can be reversed independently
+- [ ] **No data loss risk:** Database migrations are reversible or have a safety net
+
+## Stories (`docs/refactors/REF-{NNN}/stories/`)
+
+- [ ] **Coverage:** Stories cover all instances from the pattern inventory
+- [ ] **Order matches plan:** Story dependencies follow the migration plan order
+- [ ] **Self-contained:** Each story can be implemented and verified independently
+- [ ] **Tests included:** Each story includes test updates for the migrated code
+
+## Overall
+
+- [ ] **Consistency:** Scope, plan, and stories tell a coherent story
+- [ ] **Completeness:** No instances of the old pattern will remain after all stories complete
+- [ ] **Safety:** At no point during the migration will the system be in a broken state

package/framework/checklists/security-review.md

@@ -0,0 +1,34 @@
+# Security Audit Review Checklist
+
+Use this checklist to review artifacts produced during a security audit lifecycle.
+
+## Threat Model (`docs/audits/SEC-{NNN}/threat-model.md`)
+
+- [ ] **Complete attack surface:** All entry points from the architecture doc are mapped
+- [ ] **Trust boundaries identified:** Authentication and authorization boundaries are clearly documented
+- [ ] **Data classified:** Sensitive data types are identified with storage and flow documentation
+- [ ] **STRIDE applied systematically:** All six categories evaluated for each component
+- [ ] **Dependencies assessed:** High-risk packages identified with CVE status
+- [ ] **Threats prioritized:** Top threats ranked by likelihood x impact with justification
+
+## Vulnerability Report (`docs/audits/SEC-{NNN}/vulnerability-report.md`)
+
+- [ ] **Evidence-based findings:** Each vulnerability includes specific file:line and code pattern
+- [ ] **Severity justified:** Severity ratings account for context (auth requirements, exposure)
+- [ ] **OWASP categorized:** Findings mapped to OWASP Top 10 categories
+- [ ] **Remediation included:** Each finding has a concrete fix with code example
+- [ ] **Patterns identified:** Systemic issues (not just individual instances) are flagged
+- [ ] **Positive findings noted:** Existing security practices are acknowledged
+
+## Stories (`docs/audits/SEC-{NNN}/stories/`)
+
+- [ ] **Severity-ordered:** Critical remediation stories come before high, medium, low
+- [ ] **Systemic first:** Middleware and validation layer fixes before individual fixes
+- [ ] **Secure code:** Remediation code follows secure coding practices
+- [ ] **Test coverage:** Each story includes security test requirements
+
+## Overall
+
+- [ ] **Consistency:** Threat model and vulnerability report align (threats have corresponding findings)
+- [ ] **Completeness:** All critical and high findings have remediation stories
+- [ ] **Practicality:** Recommendations are actionable within the project's constraints

package/framework/checklists/test-review.md

@@ -0,0 +1,32 @@
+# Test & Coverage Review Checklist
+
+Use this checklist to review artifacts produced during a test audit lifecycle.
+
+## Coverage Report (`docs/audits/TST-{NNN}/coverage-report.md`)
+
+- [ ] **Coverage data sourced:** Coverage numbers come from actual test runner output, not estimates
+- [ ] **Critical gaps identified:** Uncovered code paths in high-risk areas (auth, payments, data handling) are flagged
+- [ ] **Risk-based ranking:** Gaps are ranked by production impact, not just by coverage percentage
+- [ ] **Integration boundaries mapped:** Cross-module interaction points are checked against architecture components
+- [ ] **Pattern analysis present:** Testing consistency (assertion styles, mocks, naming) is assessed
+
+## Flaky Report (`docs/audits/TST-{NNN}/flaky-report.md`)
+
+- [ ] **Root causes identified:** Each flaky test has a specific root cause, not just "flaky"
+- [ ] **Evidence provided:** Flakiness is demonstrated with evidence (dual-run results or code pattern analysis)
+- [ ] **No retry-only fixes:** Suggested fixes address root causes, not just add retries
+- [ ] **Systemic issues flagged:** Patterns causing multiple flaky tests are identified
+- [ ] **Quick wins separated:** Low-effort fixes are clearly distinguished from larger refactors
+
+## Stories (`docs/audits/TST-{NNN}/stories/`)
+
+- [ ] **Priority order:** Critical gap fixes and quick-win flake fixes come first
+- [ ] **Scoped improvements:** Each story handles one logical test improvement
+- [ ] **Follows conventions:** Suggested tests follow the project's existing test patterns
+- [ ] **Actionable:** Each story has specific file:line references and concrete test approaches
+
+## Overall
+
+- [ ] **Consistency:** Coverage report and flaky report don't contradict each other
+- [ ] **Completeness:** All critical gaps and systemic flake issues have corresponding stories
+- [ ] **Practicality:** Recommendations are achievable (not "rewrite all tests from scratch")

package/framework/checklists/workspace-review.md

@@ -0,0 +1,34 @@
+# Workspace Feature Review Checklist
+
+Gate mode: **strict** (cross-repo features require approval before implementation)
+
+## Workspace Feature Brief
+- [ ] All affected repositories are identified with clear justification
+- [ ] Repositories not affected are explicitly excluded with reasoning
+- [ ] New interfaces are documented with type (REST/Type/Event) and participating repos
+- [ ] Modified interfaces reference existing contract versions
+- [ ] Wave ordering respects the dependency graph — no repo sprints before its dependencies
+- [ ] Repos in the same dependency tier are grouped for parallel execution
+- [ ] Risks and considerations are identified for cross-repo coordination
+
+## Interface Contracts
+- [ ] Every new cross-repo interface has a formal contract
+- [ ] Every contract has full request/response schemas for all endpoints
+- [ ] Error responses are defined, not just success cases
+- [ ] Shared types specify exactly one owning repository
+- [ ] Event contracts specify producer and consumer(s) with payload schemas
+- [ ] Contract versions follow semver (breaking changes = major bump)
+- [ ] Contracts are self-contained — implementable without reading other repo code
+
+## Cross-Repo Implementation Plan
+- [ ] Per-repo work breakdown covers all affected repositories
+- [ ] Each repo's stories reference specific contract items
+- [ ] Sprint wave ordering matches the dependency ordering in the brief
+- [ ] Integration validation criteria are defined for each wave boundary
+- [ ] Rollback plan exists for contract validation failures
+
+## Overall
+- [ ] No circular dependencies in the wave ordering
+- [ ] Workspace memory conventions are consistent across repos
+- [ ] All contract files are valid YAML
+- [ ] Feature numbering follows WKSP-XXXX pattern