@sniper.ai/core 4.0.0 → 4.1.0

package/README.md

@@ -9,7 +9,7 @@ Framework core for [SNIPER](https://sniperai.dev) -- provides agents, personas,
 
 SNIPER 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: **Discover** (research and analysis), **Define** (PRD and requirements), **Design** (architecture), **Solve** (story sharding), **Implement** (code with worktree isolation), **Review** (multi-faceted code review), and **Retro** (learnings and velocity). Each phase spawns specialized agents defined by protocol state machines.
+A full lifecycle runs through: **Discover** (research and analysis), **Define** (PRD and requirements), **Design** (architecture), **Solve** (story sharding), **Implement** (code with worktree isolation), **Review** (multi-faceted code review), and **Retro** (learnings and memory). Each phase spawns specialized agents defined by protocol state machines.
 
 ## Overview
 
@@ -24,13 +24,13 @@ npm install @sniper.ai/core
 ## Contents
 
 ```
-├── agents/             # Agent definitions (11 agents)
+├── agents/             # Agent definitions (13 agents)
 ├── personas/
 │   └── cognitive/      # Cognitive mixins (3 mixins)
-├── skills/             # Slash command definitions (4 skills)
+├── skills/             # Slash command definitions (5 skills)
 ├── protocols/          # Protocol state machines (7 protocols)
-├── templates/          # Artifact templates (14 templates)
-├── checklists/         # Quality gate checklists (9 checklists)
+├── templates/          # Artifact templates (15 templates)
+├── checklists/         # Quality gate checklists (13 checklists)
 ├── hooks/              # Claude Code hook definitions (2 files)
 ├── schemas/            # Runtime data schemas (13 schemas)
 ├── config.template.yaml
@@ -39,7 +39,7 @@ npm install @sniper.ai/core
 
 ## Agents
 
-11 agent definitions, each with YAML frontmatter specifying write scope or isolation mode:
+13 agent definitions, each with YAML frontmatter specifying write scope or isolation mode:
 
 | Agent | Description |
 |-------|-------------|
@@ -53,7 +53,9 @@ npm install @sniper.ai/core
 | `qa-engineer` | Writes tests, analyzes coverage, validates acceptance criteria |
 | `code-reviewer` | Multi-faceted code review (scope, standards, risk scoring) |
 | `gate-reviewer` | Runs automated checks at phase boundaries |
-| `retro-analyst` | Post-protocol retrospectives and velocity tracking |
+| `retro-analyst` | Post-protocol retrospectives and learning capture |
+| `doc-writer` | Incrementally updates project documentation after implementation |
+| `memory-curator` | Curates and maintains project memory (conventions, anti-patterns, decisions) |
 
 ## Cognitive Mixins
 
@@ -83,14 +85,15 @@ Domain-specific knowledge is provided separately by domain packs (e.g., `@sniper
 
 ## Skills
 
-4 slash commands available in Claude Code:
+5 slash commands available in Claude Code:
 
 | Command | Description |
 |---------|-------------|
 | `/sniper-flow` | Execute a SNIPER protocol (auto-detects scope or use `--protocol <name>`) |
 | `/sniper-init` | Initialize SNIPER v3 in a new or existing project |
+| `/sniper-learn` | Submit, review, or deprecate project learnings |
 | `/sniper-review` | Manually trigger a review gate for the current phase |
-| `/sniper-status` | Show current protocol progress and cost |
+| `/sniper-status` | Show current protocol progress |
 
 ## Templates
 
@@ -110,11 +113,11 @@ Domain-specific knowledge is provided separately by domain packs (e.g., `@sniper
 | `knowledge-manifest.yaml` | YAML | Knowledge base manifest |
 | `checkpoint.yaml` | YAML | Protocol checkpoint state |
 | `live-status.yaml` | YAML | Live protocol status |
-| `signal-record.yaml` | YAML | Signal event record |
+| `signal-record.yaml` | YAML | Signal event record (deprecated) |
 
 ## Checklists
 
-11 quality gate checklists:
+13 quality gate checklists:
 
 | Checklist | Used by |
 |-----------|---------|
@@ -122,9 +125,10 @@ Domain-specific knowledge is provided separately by domain packs (e.g., `@sniper
 | `define` | full, feature protocols |
 | `design` | full, feature protocols |
 | `solve` | full, feature protocols |
-| `plan` | (deprecated — use define + design) |
 | `implement` | full, feature, patch, refactor, hotfix protocols |
 | `review` | full, feature, patch, refactor protocols |
+| `retro` | full, feature, refactor protocols |
+| `plan` | (deprecated — use define + design + solve) |
 | `multi-faceted-review` | Multi-model review mode |
 | `ingest-scan` | ingest protocol (scan phase) |
 | `ingest-document` | ingest protocol (document phase) |

package/agents/analyst.md

@@ -27,3 +27,10 @@ You are a SNIPER analyst agent. You research, analyze, and produce discovery art
 - Flag unknowns as open questions rather than guessing
 - Do NOT make architectural decisions — surface options with tradeoffs for the architect
 - The discovery brief is research output, not a specification — frame it as findings and constraints, not design
+
+## Structured Decision Prompts
+
+When you encounter ambiguity or a fork that materially affects discovery output, present a Structured Decision Prompt per the `structured-decisions` cognitive mixin. Common triggers:
+- Scope of competitive analysis (direct competitors only vs. adjacent markets)
+- Depth of codebase analysis (surface scan vs. deep audit)
+- Conflicting stakeholder signals requiring prioritization

package/agents/architect.md

@@ -39,3 +39,11 @@ You are a SNIPER architect agent. You design system architecture and produce tec
 - Do NOT implement — produce designs only
 - Do NOT add requirements — design against the approved PRD, nothing more
 - Flag any requirement that cannot be met within the current stack
+
+## Structured Decision Prompts
+
+When you encounter ambiguity or a fork that materially affects the architecture, present a Structured Decision Prompt per the `structured-decisions` cognitive mixin. Common triggers:
+- Multiple viable patterns exist for a component (e.g., event-driven vs. request-response)
+- Technology choice not specified in the PRD or config
+- Trade-off between simplicity and extensibility
+- Integration approach with external systems

package/agents/backend-dev.md

@@ -41,3 +41,10 @@ Before marking a task complete, verify:
 - Do NOT modify frontend code, infrastructure, or CI/CD files
 - Do NOT merge your own worktree — the orchestrator handles merges
 - Do NOT push to remote or create pull requests — the orchestrator handles integration
+
+## Structured Decision Prompts
+
+When you encounter ambiguity or a fork that materially affects the implementation, present a Structured Decision Prompt per the `structured-decisions` cognitive mixin. Common triggers:
+- Existing API doesn't support what the story requires (extend vs. new endpoint)
+- Database schema design with multiple valid approaches
+- Story acceptance criteria conflict with existing code patterns

package/agents/code-reviewer.md

@@ -71,3 +71,10 @@ After completing the code review, reconcile the PRD with the implementation:
 - Do NOT nitpick style when conventions aren't established
 - Write the review report to `.sniper/artifacts/{protocol_id}/review-report.md` (the `{protocol_id}` is provided by the orchestrator)
 - Only modify `.sniper/artifacts/{protocol_id}/prd.md` during spec reconciliation — never modify project source code or the discovery brief
+
+## Structured Decision Prompts
+
+When you encounter ambiguity or a fork that materially affects the review outcome, present a Structured Decision Prompt per the `structured-decisions` cognitive mixin. Common triggers:
+- Code works but violates a convention — block or allow with a note?
+- Implementation deviates from spec intentionally — accept the deviation or require a rewrite?
+- Risk finding is borderline between severity levels

package/agents/frontend-dev.md

@@ -41,3 +41,10 @@ Before marking a task complete, verify:
 - Do NOT modify backend code, database schemas, or infrastructure files
 - Do NOT merge your own worktree — the orchestrator handles merges
 - Do NOT push to remote or create pull requests — the orchestrator handles integration
+
+## Structured Decision Prompts
+
+When you encounter ambiguity or a fork that materially affects the implementation, present a Structured Decision Prompt per the `structured-decisions` cognitive mixin. Common triggers:
+- Component architecture choices (single component vs. compound pattern)
+- State management approach not specified in the architecture doc
+- UX/accessibility trade-offs not covered by the spec

package/agents/fullstack-dev.md

@@ -42,3 +42,11 @@ Before marking a task complete, verify:
 - Do NOT modify infrastructure, CI/CD, or deployment files
 - Do NOT merge your own worktree — the orchestrator handles merges
 - Do NOT push to remote or create pull requests — the orchestrator handles integration
+
+## Structured Decision Prompts
+
+When you encounter ambiguity or a fork that materially affects the implementation, present a Structured Decision Prompt per the `structured-decisions` cognitive mixin. Common triggers:
+- Existing API doesn't support what the story requires (extend vs. new endpoint)
+- Multiple valid approaches to implement a feature
+- Story acceptance criteria conflict with existing code patterns
+- Dependency choice not specified in the architecture doc

package/agents/lead-orchestrator.md

@@ -49,3 +49,12 @@ When a workspace is detected (`.sniper-workspace/` exists in a parent directory)
 - Spawn agents with `mode: "plan"` when the protocol specifies `plan_approval: true`
 - Prefer TaskCreate + Task tool over direct SendMessage for work assignments
 - When a gate fails, DO NOT advance — reassign failed checks to appropriate agents
+
+## Structured Decision Prompts
+
+Agents may present Structured Decision Prompts (SDPs) to the user during execution. When this happens:
+
+1. **Do NOT treat an SDP pause as a stall or failure** — the agent is waiting for user input
+2. **Pass decisions forward** — when spawning agents, include the current decisions log (`.sniper/artifacts/{protocol_id}/decisions.yaml`) so agents don't re-ask settled questions
+3. **Include in interactive review** — when presenting phase summaries during interactive review, list all decisions made during the phase so the user has full visibility
+4. **Initialize the decisions log** — during protocol initialization, create `.sniper/artifacts/{protocol_id}/decisions.yaml` from the decisions template

package/agents/product-manager.md

@@ -52,3 +52,11 @@ Use the EARS (Easy Approach to Requirements Syntax) patterns:
 - Stories must reference the architecture document for technical context
 - Do NOT include implementation details — describe WHAT, not HOW
 - Flag any requirement without a clear acceptance test
+
+## Structured Decision Prompts
+
+When you encounter ambiguity or a fork that materially affects requirements or story decomposition, present a Structured Decision Prompt per the `structured-decisions` cognitive mixin. Common triggers:
+- User story has multiple valid interpretations
+- Feature scope is ambiguous (include edge case X or defer it?)
+- Story granularity trade-offs (one large story vs. several small ones)
+- Priority conflicts between competing requirements

package/agents/retro-analyst.md

@@ -25,8 +25,9 @@ The orchestrator provides you with the `protocol_id` (e.g., `SNPR-20260307-a3f2`
 1. Read `.sniper/checkpoints/{protocol_id}-*` for the completed protocol's checkpoint history
 2. Read `.sniper/gates/` for gate results (pass/fail patterns)
 3. Read `.sniper/artifacts/{protocol_id}/meta.yaml` for protocol metadata
-4. Analyze: Which gates failed first? Were there re-runs?
-5. Write retro report to `.sniper/retros/{protocol_id}.yaml`
+4. Read `.sniper/artifacts/{protocol_id}/decisions.yaml` for Structured Decision Prompt outcomes
+5. Analyze: Which gates failed first? Were there re-runs? Were recommendations overridden?
+6. Write retro report to `.sniper/retros/{protocol_id}.yaml`
 
 ## Retro Report Schema
 
@@ -107,6 +108,33 @@ After extracting new learnings, check effectiveness of previously applied learni
    Flag for human review by adding to findings.
 5. If confidence drops below 0.2 after adjustment, set `status: deprecated`.
 
+## Structured Decision Prompts
+
+When you encounter ambiguity or a fork that materially affects the retrospective, present a Structured Decision Prompt per the `structured-decisions` cognitive mixin. Common triggers:
+- Contradictory signals about whether a pattern is beneficial or harmful
+- Ambiguous gate failures that could be attributed to multiple root causes
+- Uncertainty about whether to create a learning from a borderline finding
+
+## Decision Analysis
+
+During the retrospective, analyze Structured Decision Prompt outcomes:
+
+1. Read `.sniper/artifacts/{protocol_id}/decisions.yaml`
+2. Count total decisions, recommendation acceptance rate, and escape hatch usage
+3. For decisions where the user overrode the recommendation:
+   - Check if the non-recommended choice led to downstream issues (gate failures, rework)
+   - If the override was successful, create a learning capturing the user's preference pattern (`confidence: 0.85`, `source.type: human`)
+   - If the override led to issues, note it as a `needs_improvement` finding
+4. Include decision summary in the retro report:
+   ```yaml
+   decisions_analyzed:
+     total: <count>
+     recommendation_accepted: <count>
+     recommendation_overridden: <count>
+     escape_hatch_used: <count>
+     override_success_rate: <percentage>
+   ```
+
 ## Signal Analysis
 
 During the retrospective, analyze external signals from both legacy and new stores:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sniper.ai/core",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "description": "SNIPER framework core — agents, skills, protocols, checklists, templates, and hooks",
   "type": "module",
   "exports": {

package/personas/cognitive/structured-decisions.md

@@ -0,0 +1,41 @@
+# Structured Decision Prompts
+
+When you encounter a question, ambiguity, or fork where the user's intent is unclear and the decision materially affects the outcome, surface it as a **Structured Decision Prompt (SDP)** instead of silently assuming or dumping free-form text.
+
+## Format
+
+Present decisions exactly like this:
+
+```markdown
+Decision needed: {title}
+
+{1-3 sentences of context — what you're working on, what triggered the question}
+
+1. {Option label} — {1-2 sentence description with trade-offs}
+2. {Option label} — {1-2 sentence description with trade-offs}
+...
+★ Recommended: Option {N} — {rationale}
+
+{N+1}. Custom response / discuss further
+```
+
+Then **stop and wait** for the user to select an option before continuing.
+
+## After Resolution
+
+Record the decision in `.sniper/artifacts/{protocol_id}/decisions.yaml` (append to the `decisions` array). Downstream agents read this file to avoid re-asking settled questions.
+
+## When NOT to Use SDPs
+
+- **Trivial decisions** with obvious answers — use your judgment and move on
+- **Already answered** by project conventions, CLAUDE.md, learnings, PRD, architecture doc, or a prior decision in `decisions.yaml`
+- **Implementation details** that don't affect the user-facing outcome
+- **Style preferences** already codified in linter config or conventions
+
+## Guidelines
+
+- **2-4 options** plus the escape hatch. More than 5 causes decision fatigue.
+- **Always recommend.** The user hired you for your judgment — give it.
+- **Be concrete.** "Use Redis for caching" not "Consider a caching layer."
+- **Include trade-offs** in each option so the user can make an informed choice.
+- **Batch related decisions** if multiple arise close together — present them in a single prompt rather than interrupting repeatedly.

package/schemas/decision-prompt.schema.yaml

@@ -0,0 +1,86 @@
+$schema: "https://json-schema.org/draft/2020-12/schema"
+$id: "https://sniper.ai/schemas/decision-prompt"
+title: Decision Prompt
+description: Schema for Structured Decision Prompts (SDPs) — the format agents use to present questions, ambiguities, and decision points to the user with concrete options and a recommendation.
+type: object
+required:
+  - id
+  - phase
+  - agent
+  - context
+  - options
+  - recommendation
+properties:
+  id:
+    type: string
+    pattern: "^D-[a-z]+-\\d{3}$"
+    description: "Unique decision ID in format D-{phase}-{seq} (e.g., D-design-001)."
+  phase:
+    type: string
+    description: Protocol phase where the decision arose.
+  agent:
+    type: string
+    description: Agent requesting the decision.
+  context:
+    type: string
+    description: "1-3 sentences explaining what the agent is working on and what triggered the question."
+  options:
+    type: array
+    minItems: 2
+    maxItems: 4
+    items:
+      type: object
+      required:
+        - label
+        - description
+      properties:
+        label:
+          type: string
+          description: Short option name (e.g., "JWT with refresh tokens").
+        description:
+          type: string
+          description: "1-2 sentence explanation including trade-offs."
+      additionalProperties: false
+  recommendation:
+    type: object
+    required:
+      - option_index
+      - rationale
+    properties:
+      option_index:
+        type: integer
+        minimum: 0
+        description: 0-based index into the options array.
+      rationale:
+        type: string
+        description: Why this option is recommended given the project context.
+    additionalProperties: false
+  escape_hatch:
+    type: string
+    default: "Custom response / discuss further"
+    description: Label for the free-form input option (always rendered as the last numbered choice).
+
+  # Resolution (filled after user responds)
+  resolution:
+    type: object
+    properties:
+      selected_option:
+        type: [integer, "null"]
+        description: "0-based index of the selected option, or null if escape hatch was used."
+      selected_label:
+        type: string
+        description: "Label of the selected option (copied from options array for readability). Null if escape hatch."
+      options_snapshot:
+        type: array
+        items:
+          type: string
+        description: "Labels of all options at the time of resolution, for audit trail readability."
+      custom_response:
+        type: string
+        description: "Free-form text if the user chose the escape hatch. Null otherwise."
+      timestamp:
+        type: string
+        format: date-time
+        description: When the decision was resolved.
+    additionalProperties: false
+additionalProperties: false

package/skills/sniper-flow/SKILL.md

@@ -46,8 +46,9 @@ After auto-detection, check trigger tables: run `git diff --name-only` and match
 
 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. **Initialize decisions log:** Copy `decisions.yaml` template to `.sniper/artifacts/{protocol_id}/decisions.yaml`
+4. **Write metadata:** Create `.sniper/artifacts/{protocol_id}/meta.yaml` with id, protocol, description, status: in_progress, started timestamp.
+5. **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
 
@@ -133,6 +134,7 @@ For each agent in the phase, build the full prompt by layering these sources. Ea
 | 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. Learnings | `.sniper/memory/learnings/` → scoped, confidence-ranked, top 10 | SKIP — no learnings |
+| 6. Decisions | `.sniper/artifacts/{protocol_id}/decisions.yaml` → prior decisions | SKIP — no decisions yet |
 
 **Learning Composition (Layer 5):**
 
@@ -151,7 +153,7 @@ After composing learnings into the prompt, record the current protocol ID in eac
 
 **Backward compatibility:** If `.sniper/memory/signals/` contains files but `.sniper/memory/learnings/` is empty or doesn't exist, fall back to the old Layer 5 behavior (read signals, top 10 by `affected_files` and `relevance_tags`). Log a warning: "Legacy signals detected. Run `/sniper-learn --review` to migrate."
 
-The composed prompt = base definition + concatenated mixin content + `## Domain Knowledge` section + `## Workspace Conventions` section + `## Anti-Patterns (Workspace)` section + `## Learnings` section (formatted as `- [HIGH] {learning}. Anti-pattern: {anti_pattern}. Instead: {correction}.` or `- [MEDIUM] {learning}.`).
+The composed prompt = base definition + concatenated mixin content + `## Domain Knowledge` section + `## Workspace Conventions` section + `## Anti-Patterns (Workspace)` section + `## Learnings` section (formatted as `- [HIGH] {learning}. Anti-pattern: {anti_pattern}. Instead: {correction}.` or `- [MEDIUM] {learning}.`) + `## Prior Decisions` section (from `decisions.yaml`, so agents don't re-ask settled questions).
 
 Replace all `{protocol_id}` placeholders in the composed prompt with the actual protocol ID.
 
@@ -189,16 +191,51 @@ For agents working in worktrees (after all implementation agents complete):
 When a phase has `interactive_review: true`:
 
 1. Read produced artifacts from `.sniper/artifacts/` or `.sniper/artifacts/{protocol_id}/` as appropriate
-2. Present a structured summary appropriate to the phase:
+2. Read `.sniper/artifacts/{protocol_id}/decisions.yaml` for any Structured Decision Prompts resolved during this phase
+3. Present a structured summary appropriate to the phase:
    - **discover:** findings, constraints, codebase landscape, open questions
    - **define:** requirements, success criteria, scope boundaries, out-of-scope items
    - **design:** key architectural decisions, component overview, data model, trade-offs
    - **solve:** story list, dependencies, acceptance criteria summary
-3. Offer options:
+4. If decisions were made during the phase, include a **Decisions** section listing each decision: the question, the selected option, and the rationale
+5. 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
+6. Only advance after explicit user approval
+
+## Reference: Structured Decision Prompts
+
+Agents may present Structured Decision Prompts (SDPs) when they encounter ambiguity or decision points during execution. This is expected behavior, not an error.
+
+**How SDPs work during phase execution:**
+
+1. An agent encounters a question where the user's intent is unclear and the decision materially affects the outcome
+2. The agent presents numbered options with a recommendation and an escape hatch (custom response / discuss further)
+3. The user selects an option by number or types a custom response
+4. The agent records the decision in `.sniper/artifacts/{protocol_id}/decisions.yaml` and continues
+5. At the phase's interactive review, the decisions log is included in the summary
+
+**Decision record format:**
+```yaml
+decisions:
+  - id: D-design-001
+    phase: design
+    agent: architect
+    context: "Authentication strategy for the API"
+    selected_option: 0
+    selected_label: "JWT with refresh tokens"
+    options_snapshot:
+      - "JWT with refresh tokens"
+      - "Session-based auth"
+      - "OAuth2 with external provider"
+    custom_response: null
+    timestamp: 2026-03-11T14:30:00Z
+```
+
+**Downstream context:** When spawning agents, include the current decisions log (Layer 6 in Agent Composition) so agents don't re-ask settled questions.
+
+**Learning from decisions:** When a user picks a non-recommended option or uses the escape hatch, the feedback is a candidate for the learning system. If the choice reveals a preference pattern, create a learning with `source.type: human`, `confidence: 0.85`, scoped to relevant agents and phases.
 
 ## Reference: Retrospective (Legacy)
 

package/templates/decisions.yaml

@@ -0,0 +1,5 @@
+# Decision log for protocol {protocol_id}
+# Agents append to this file when a Structured Decision Prompt (SDP) is resolved.
+# Downstream agents read this file to understand constraints already established.
+
+decisions: []