@esoteric-logic/praxis-harness 1.1.0

package/base/commands/gsd-verify.md

@@ -0,0 +1,78 @@
+---
+description: Validation phase — runs test/lint/typecheck/build and reports PASS or FAIL. Use after each milestone completion.
+---
+
+You are running the GSD verification phase for the current milestone.
+
+**Step 1 — Run validation sequence**
+Execute in order, showing actual output (never assertions):
+1. **Test suite** → run the project test command → show output
+2. **Linter** → run the project lint command → show output, fix ALL warnings
+3. **Typecheck** (if applicable) → show output
+4. **Build** (if applicable) → show output
+5. **Functional check** — ask: "Is there a smoke test, `terraform plan` output, or browser check needed for this milestone?" If yes: block until user confirms it passed. If no: proceed.
+
+Read test/lint/build commands from the project CLAUDE.md `## Commands` section.
+If no commands are defined: warn and ask user for the correct commands.
+
+**Step 2 — Report result**
+- **PASS**: All checks green. Proceed to Step 3.
+- **FAIL**: Trigger repair (Step 4).
+
+**Step 3 — On PASS**
+1. Update the active plan file: mark milestone status as complete
+2. Prompt: "Milestone verified. Ready to commit — proceed?"
+3. After commit: check if more milestones remain
+   - Yes → "Run `/gsd:execute` for the next milestone."
+   - No → "All milestones complete. Running self-review."
+4. After ALL milestones: trigger Self-Review Protocol
+   - Launch a subagent to review the full diff as a critical code reviewer
+   - Subagent receives ONLY: the diff, the SPEC, relevant rules files
+   - Address all Critical and Major findings before reporting done
+
+**Step 3b — UNIFY (mandatory after all milestones verified)**
+After self-review passes, write phase summary:
+- Write `{vault_path}/plans/current-phase-summary.md`:
+  ```markdown
+  ---
+  tags: [unify, {project-slug}]
+  date: {YYYY-MM-DD}
+  source: agent
+  ---
+  # Phase Summary: {plan title}
+
+  ## Planned vs Actual
+  - Original milestones: {list from plan}
+  - Completed: {list with dates}
+  - Changed or dropped: {list with reasons}
+
+  ## Decisions Made
+  - {decision}: {rationale}
+
+  ## Acceptance Criteria
+  | Criterion | Status |
+  |-----------|--------|
+  | {from Done When} | PASS / FAIL |
+
+  ## Deferred Items
+  - {item}: {reason deferred, suggested next step}
+  ```
+- Run `/simplify` on the full diff to clean up implementation
+- Report: "Phase summary written. Run `/verify-app` for e2e checks, then `/ship` to commit+push+PR."
+
+**Rules:**
+- UNIFY fires after ALL milestones verified, not per-milestone. session-retro still runs at session end for learnings — complementary, not redundant.
+- `/simplify` runs after UNIFY, before shipping. It is the quality gate between "it works" and "it's clean".
+
+**Step 4 — On FAIL (Stop-and-Fix)**
+1. Identify the failure: exact error, file, line
+2. Fix NOW. Do not proceed to the next milestone.
+3. Re-run the full validation sequence (Step 1)
+4. If still failing after 3 attempts: STOP.
+   Report: **What** (full error + 3 attempts) → **So What** (root cause) → **Now What** (next steps)
+5. Write failure details to the active plan file if >1 attempt was needed
+
+**Rules:**
+- Never say "tests pass" without showing output.
+- Never skip lint warnings — they compound into tech debt.
+- Validation is the evidence. Conversation claims are not.

package/base/commands/kit.md

@@ -0,0 +1,62 @@
+---
+description: Activate or deactivate a domain AI-Kit. Use /kit:web-designer to activate, /kit:off to deactivate, /kit:list to show installed kits.
+allowed-tools: Bash(ls ~/.claude/kits/*)
+---
+
+You are managing AI-Kit activation.
+
+## /kit:list
+List all installed kits by reading `~/.claude/kits/*/KIT.md` manifests.
+Print a table:
+```
+  Kit              Status    Domain
+  web-designer     inactive  Design system → components → accessibility → lint
+```
+If `~/.claude/praxis.config.json` has `installed_kits`, cross-reference to show install status.
+
+## /kit:<name> (activate)
+
+1. Check if `~/.claude/kits/<name>/KIT.md` exists. If not: report "Kit not found. Run /kit:list."
+2. Read `KIT.md` manifest to get skills_chain, rules, and mcp_servers.
+3. **Idempotency check**: If this kit is already active in the current session, report "Kit already active" and do nothing. This is critical for Ralph integration where every iteration may re-activate.
+4. Print the skills chain:
+   ```
+   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+     AI-Kit activated: web-designer
+   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+     Skills chain:
+     1. Design system init  → ui-ux-pro-max, design-system-patterns
+     2. Component build     → frontend-design, shadcn-ui, 21st.dev MCP
+     3. Audit               → web-accessibility, ui-skills
+     4. Final lint           → web-design-guidelines
+
+     Domain rules loaded: web-design.md
+     MCP servers: 21st-magic
+
+   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+   ```
+5. Load the kit's rules from `~/.claude/kits/<name>/rules/`.
+6. Note: MCP servers registered via `claude mcp add` persist globally. The kit activation confirms they are available but does not re-register.
+
+## /kit:off (deactivate)
+
+1. Report which kit is being deactivated.
+2. Unload kit-specific rules from the active context.
+3. Note: MCP servers persist globally — they are not unregistered on deactivation.
+4. Print: `✓ Kit deactivated. Universal base (GSD + Superpowers) still active.`
+
+## /kit:update <name>
+
+1. Run `~/.claude/kits/<name>/install.sh` to pull latest skill versions.
+2. Update `installed_kits` in `~/.claude/praxis.config.json`.
+3. Report results.
+
+## Error Handling
+
+| Condition | Action |
+|-----------|--------|
+| Kit not found | Report available kits from /kit:list |
+| Kit dependencies not installed | Suggest running `~/.claude/kits/<name>/install.sh` |
+| Double activation | No-op — report already active |
+| KIT.md malformed | Report parse error, do not activate |

package/base/commands/plan.md

@@ -0,0 +1,91 @@
+---
+description: Create a dated work plan for the current project. Writes to vault plans/ directory and updates status.md current_plan field. Use when starting any multi-step task.
+---
+
+You are creating a work plan for the current project.
+
+**Step 1 — Detect project**
+- Read vault_path from `~/.claude/praxis.config.json`
+- Match CWD to `local_path` in vault `_index.md`
+- Read `status.md` — check if `current_plan:` is already set
+- If current_plan is set: warn. Ask if starting a new plan or updating the existing one.
+
+**Step 2 — Gather plan details**
+Ask in a single message:
+- What is the task or feature this plan covers?
+- What is the target completion date (or "open" if no deadline)?
+- Any known blockers or dependencies upfront?
+
+**Step 3 — Build the plan**
+
+```markdown
+---
+tags: [plan, {project-slug}]
+date: {YYYY-MM-DD}
+status: active
+target: {date or open}
+execution_type: execute | tdd | research
+source: agent
+---
+# Plan: {title}
+
+## Objective
+One sentence.
+
+## Context
+Why this work is happening now.
+
+## Milestones
+- [ ] {milestone 1} — {date}
+- [ ] {milestone 2} — {date} | depends_on: milestone 1
+- [ ] {milestone 3} — {date} | depends_on: milestone 2 | checkpoint: decision
+- [ ] {milestone 4} — {date} | checkpoint: human-verify
+
+## Steps
+### {Milestone 1}
+1. {step}
+2. {step}
+
+## Done When
+- [ ] {specific verifiable check}
+
+## Boundaries
+<!-- Required. Files/systems that MUST NOT change during this plan. -->
+<!-- Override requires explicit "OVERRIDE: {reason}" from user. -->
+- DO NOT CHANGE: {file or system list}
+
+## Blockers
+<!-- Known blockers at plan creation time -->
+
+## Session Log
+<!-- Updated by session-retro -->
+```
+
+Checkpoint types:
+- `checkpoint: decision` — user must confirm a choice before proceeding
+- `checkpoint: human-verify` — user must validate output before proceeding
+- No annotation = autonomous (default)
+
+**Step 3b — Dependency and boundary validation**
+After building the milestone list:
+- Scan for circular dependencies (topological sort). If cycle detected:
+  report the cycle and ask user to break it.
+- Validate that every `depends_on:` reference exists in the milestone list.
+- If user provided milestones out of order: reorder and note the change.
+- Milestones with no `depends_on:` are independent — this is valid.
+- Validate Boundaries: if user did not specify any, ask:
+  "What files or systems should NOT be touched during this plan?"
+  Empty boundaries are valid only if explicitly confirmed.
+- Validate checkpoints: milestones with architectural decisions or user-facing output
+  should be annotated as `checkpoint: decision` or `checkpoint: human-verify`.
+
+**Step 4 — Write and wire**
+- Write to: `{vault_path}/plans/{YYYY-MM-DD}_{kebab-title}.md`
+- Update `status.md`: set `current_plan:`, update `last_updated`, update `## Now What`
+- Update `claude-progress.json` milestones array
+- Report:
+```
+✓ Plan created:   {vault_path}/plans/{filename}
+✓ status.md:      current_plan updated
+✓ progress.json:  milestone added
+```

package/base/commands/ralph.md

@@ -0,0 +1,110 @@
+---
+description: Ralph autonomous execution command. Runs multi-story iterations from a PRD with fresh context per story. Use for >5 independent stories or overnight execution.
+---
+
+You are running Ralph — autonomous multi-story execution.
+
+**Step 1 — Read state**
+- Read vault_path from `~/.claude/praxis.config.json`
+- Read `{vault_path}/claude-progress.json` → check `ralph_state`
+- If `ralph_state.mode` is `"active"` and `current_story` is set: resume that story
+- If `ralph_state.mode` is `"idle"`: begin new iteration (Step 2)
+
+**Step 2 — PRD validation**
+- Read the PRD file at `ralph_state.prd_path`
+- Validate each story against size constraints:
+  - Must be completable in ~10k output tokens
+  - Must touch ≤3 file groups
+  - Must require ≤1 architectural decision
+- Reject stories that exceed constraints. Report which stories need splitting.
+- Stories requiring cross-story reasoning belong in GSD, not Ralph.
+
+**Step 2b — PRD format (canonical)**
+Ralph PRDs must follow this structure:
+  ```markdown
+  ---
+  title: {PRD title}
+  date: YYYY-MM-DD
+  status: active
+  stories_total: {n}
+  ---
+  # PRD: {title}
+
+  ## Context
+  Why this work exists. 1-3 sentences.
+
+  ## Stories
+
+  ### Story: {story-id}
+  **As a**: {role}
+  **I want**: {capability}
+  **So that**: {outcome}
+  **Done when**:
+  - [ ] {verifiable check}
+  **File group**: {list of files, max 3 groups}
+  **Dependencies**: {story-ids that must complete first, or "none"}
+  **Estimate**: S / M / L
+  ```
+- Size validation: before starting any Ralph run, scan every story.
+  Any story marked L or missing a File group: STOP. Fix the PRD first.
+- S = <3 files. M = 3-5 files. L = 5+ files (must split before Ralph).
+
+**Step 3 — State bridge**
+- `ralph_state` in `claude-progress.json` is the ONLY state between iterations
+- Never reference conversation history as source of truth
+- Read `ralph_state` at iteration start, write at iteration end
+- Fields:
+  - `mode`: "idle" | "active"
+  - `prd_path`: path to PRD file
+  - `current_story`: story identifier currently being executed
+  - `completed_stories`: array of finished story identifiers
+  - `blocked_stories`: array of stories that could not complete
+  - `learnings`: array of [LEARN:tag] entries discovered during iterations
+  - `last_iteration`: ISO timestamp of last completed iteration
+  - `session_count`: number of iterations completed
+
+**Step 4 — Iteration bootstrap**
+For each story, in a fresh context:
+1. Read project CLAUDE.md (always first)
+2. Read `claude-progress.json` → `ralph_state` (authoritative)
+3. Read PRD → current story ONLY (not full PRD)
+4. Activate kit if specified in project CLAUDE.md (`## Active kit`)
+5. Execute the story using GSD execute + verify phases
+
+**Step 4b — Blocked story protocol**
+When a story cannot complete (test fails after 3 attempts, dependency missing, etc.):
+1. Do NOT retry the story. Ralph stories get one attempt.
+2. Record in `ralph_state.blocked_stories`:
+   ```json
+   { "story": "{story-id}", "reason": "{specific error}", "blocked_at": "{ISO timestamp}" }
+   ```
+3. Write the blocker to the active plan file under the story entry.
+4. Move to the next unblocked story. Never halt the entire Ralph run.
+5. At run end: report all blocked stories as a group for human resolution.
+
+**Step 5 — Iteration end**
+After each story completes:
+1. Run session-retro in Ralph-auto mode (summary + learnings, skip user-facing phases)
+2. Update `ralph_state`:
+   - Push `current_story` to `completed_stories`
+   - Set `current_story` to next story (or null if done)
+   - Update `last_iteration` timestamp
+   - Increment `session_count`
+3. Git commit the story's changes
+4. Advance to next story or report completion
+
+**Step 6 — Decision table**
+
+| Condition | Use Ralph | Use GSD |
+|-----------|-----------|---------|
+| >5 independent stories | Yes | - |
+| Overnight/unattended execution | Yes | - |
+| Mechanical transformations (migrations, renames) | Yes | - |
+| Cross-story reasoning required | - | Yes |
+| Architectural decisions span stories | - | Yes |
+| Human checkpoints needed | - | Yes |
+
+**Rules:**
+- Kit activation is idempotent via `/kit:<name>` — safe to activate every iteration.
+- Ralph never asks for user input mid-story. If blocked: add to `blocked_stories`, skip, continue.
+- Default to GSD. Use Ralph only when stories are clearly independent and well-scoped.

package/base/commands/review.md

@@ -0,0 +1,81 @@
+---
+description: Manual code review trigger. Launches a subagent to review a diff for bugs, security, and convention violations. Use independently of GSD phases.
+---
+
+You are running a manual code review.
+
+**Step 1 — Determine diff scope**
+Ask: "Review staged changes, last commit, or specific SHA?"
+- Default to `git diff HEAD` if no answer within 10 seconds.
+- Accept: `staged`, `HEAD`, `HEAD~N`, or a specific SHA.
+
+**Step 2 — Gather the diff**
+- Run the appropriate `git diff` command.
+- If the diff is empty: "Nothing to review." Exit.
+- If the diff exceeds 2000 lines: warn and ask whether to proceed or narrow scope.
+
+**Step 3 — Load review context**
+- Read project CLAUDE.md (if it exists in the repo root).
+- Read the active plan (if `current_plan:` is set in vault status.md) — extract the SPEC only.
+- Load rules based on file types in the diff:
+  - `.tf` / `.tfvars` → `~/.claude/rules/terraform.md`
+  - `.yml` / `.yaml` in `.github/` → `~/.claude/rules/github-actions.md`
+  - `.ps1` / `.psm1` → `~/.claude/rules/powershell.md`
+  - Any file → `~/.claude/rules/coding.md`, `~/.claude/rules/security.md`
+
+**Step 4 — Launch subagent review**
+Launch a subagent with ONLY these inputs (zero conversation history):
+- The diff
+- The SPEC (if available from Step 3)
+- Relevant rules files (from Step 3)
+
+Subagent prompt:
+> Review this diff for bugs, edge cases, error handling gaps, security issues,
+> and convention violations. Rate each finding:
+> Critical / Major / Minor.
+> Format: `{file}:{line} — {severity} — {description} — {fix}`
+
+**Step 5 — Present findings**
+Structure output by severity:
+
+```
+━━━ REVIEW RESULTS ━━━
+
+CRITICAL ({n})
+  {file}:{line} — {description} — {fix}
+
+MAJOR ({n})
+  {file}:{line} — {description} — {fix}
+
+MINOR ({n})
+  {file}:{line} — {description} — {fix}
+
+CLEAN
+  {files with no findings}
+━━━━━━━━━━━━━━━━━━━━━━
+```
+
+**Step 6 — Remediation guidance**
+- Critical: address immediately before proceeding.
+- Major: recommend fixing before merge.
+- Minor: note for future cleanup.
+- If >3 findings: offer to re-run after fixes (max 3 rounds).
+
+**Step 7 — Write review summary**
+- Read vault_path from `~/.claude/praxis.config.json`
+- Write summary to `{vault_path}/specs/review-{YYYY-MM-DD}-{slug}.md` with frontmatter:
+  ```yaml
+  ---
+  tags: [review, {project-slug}]
+  date: {YYYY-MM-DD}
+  status: complete
+  source: agent
+  ---
+  ```
+- Vault indexing is automatic.
+
+**Rules:**
+- Works independently of GSD phases.
+- Never skip the subagent — review must come from fresh context.
+- Subagent receives zero conversation history.
+- If no project CLAUDE.md exists: proceed with base rules only.

package/base/commands/risk.md

@@ -0,0 +1,53 @@
+---
+description: Add a new risk register entry to the current project vault. Assigns a risk ID, severity, mitigation, and writes to specs/risk-register.md.
+---
+
+You are adding a risk register entry for the current project.
+
+**Step 1 — Detect project and existing risks**
+- Read vault_path from `~/.claude/praxis.config.json`
+- Detect project from CWD
+- Run: `obsidian search query="risk register {project-slug}" limit=3`
+- Check if `{vault_path}/specs/risk-register.md` exists
+- If found: read it to determine next sequential risk ID (R-01, R-02, etc.)
+
+**Step 2 — Gather risk details**
+Ask in a single message:
+- What is the risk? (one sentence)
+- What triggers it?
+- Severity: Critical / High / Medium / Low
+- Who owns this risk?
+- What is the mitigation? (must be specific — "monitor" is not a mitigation)
+
+**Step 3 — Write the entry**
+
+If no risk register exists, create `{vault_path}/specs/risk-register.md`:
+```markdown
+---
+tags: [risk-register, {project-slug}]
+date: {YYYY-MM-DD}
+last_updated: {YYYY-MM-DD}
+source: agent
+---
+# {Project Name} — Risk Register
+```
+
+Append entry:
+```markdown
+## {R-ID} — {title}
+- **Severity**: {Critical | High | Medium | Low}
+- **Status**: Open
+- **Trigger**: {what causes this risk to materialize}
+- **Impact**: {what happens if it does}
+- **Mitigation**: {specific steps — never TBD}
+- **Owner**: {name or role}
+- **Date identified**: {YYYY-MM-DD}
+```
+
+**Step 4 — Surface critical risks**
+- If severity is Critical: add to `status.md` under `## So What` immediately.
+**Step 5 — Report**
+```
+✓ Risk {R-ID} added:    {title} [{severity}]
+✓ Risk register:        {vault_path}/specs/risk-register.md
+```

package/base/commands/ship.md

@@ -0,0 +1,74 @@
+---
+description: Commit, push, and open a PR in one shot. Runs pre-commit checks, crafts a commit message, pushes, and creates a PR with structured description. Use when a milestone or feature is complete and verified.
+---
+
+You are running the ship workflow — commit, push, and PR in one command.
+
+**Step 1 — Pre-flight checks**
+- Read project CLAUDE.md for build/test/lint commands
+- Run in order (all must pass):
+  1. Secret scan: `rg "(sk-|ghp_|pplx-|AKIA|Bearer [A-Za-z0-9+/]{20,})" $(git diff --staged --name-only)`
+  2. Linter (from CLAUDE.md `## Commands`)
+  3. Typecheck (if applicable)
+  4. Test suite (from CLAUDE.md `## Commands`)
+  5. Identity check: `git --no-pager config user.email` must match expected
+- If ANY check fails: STOP. Fix first, then re-run `/ship`.
+
+**Step 2 — Stage and review changes**
+- Run `git status` and `git diff --stat`
+- Show the user what will be committed
+- If nothing to commit: "Nothing to ship." Exit.
+- If unstaged files exist: ask which to include
+
+**Step 3 — Craft commit message**
+- Use conventional commits: `feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`
+- Read the active plan (if set) for context on what was accomplished
+- Format:
+  ```
+  {type}({scope}): {short description}
+
+  {optional body — what changed and why, not how}
+  ```
+- Show the commit message for approval before committing
+
+**Step 4 — Commit and push**
+- `git add` the agreed files
+- `git commit` with the approved message
+- `git push -u origin HEAD`
+- If push fails (no remote, branch conflict): report and suggest fix
+
+**Step 5 — Create PR**
+Ask: "Open a PR?" (default: yes)
+
+If yes:
+- Detect base branch from git config or default to `main`
+- Read vault_path from `~/.claude/praxis.config.json`
+- If active plan exists: extract objective and done-when for PR description
+- Create PR using `gh pr create`:
+  ```
+  ## What changed
+  {summary from commit + plan context}
+
+  ## Why
+  {from plan objective or user context}
+
+  ## How to verify
+  {from plan done-when, or suggest specific commands}
+  ```
+
+**Step 6 — Report**
+```
+SHIPPED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Commit:  {short sha} {message}
+Branch:  {branch} → {base}
+PR:      {url}
+Checks:  secrets ✓  lint ✓  types ✓  tests ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+**Rules:**
+- Never skip pre-flight checks. They are the safety net.
+- Never force-push without explicit user approval.
+- If the diff touches >20 files: warn about PR size and suggest splitting.
+- This command is the end of a GSD cycle — run after `/gsd:verify` passes.

package/base/commands/spec.md

@@ -0,0 +1,121 @@
+---
+description: Create a structured spec or ADR for the current project. Writes directly to vault specs/ directory. Use for any significant decision, design, or work item that needs documentation before implementation.
+---
+
+You are creating a spec for the current project.
+
+**Step 1 — Identify project context**
+- Read vault_path from `~/.claude/praxis.config.json`
+- Detect project from CWD matching `local_path` in vault `_index.md`
+- Read `status.md` to understand current state
+- If no project detected: ask which project before continuing
+
+**Step 2 — Gather spec details**
+Ask the following in a single message:
+- What is this spec for? (one sentence)
+- Type: ADR (architecture decision) / PLAN (work plan) / RISK (risk register entry) / SPEC (technical spec)
+- Is there an existing related spec in `specs/`? (run `obsidian search query="{topic}" limit=3` first)
+
+**Step 2b — Cross-spec conflict check**
+After the vault search from Step 2, check for conflicts with accepted ADRs:
+- Run: `obsidian search query="{topic}" limit=10`
+- For each result with `status: accepted` or `status: proposed`:
+  - Compare the decision direction. Does the new spec contradict an accepted decision?
+- If conflict detected, present:
+  ```
+  This conflicts with {spec-path} (accepted {date}).
+  Options:
+  1. Supersede — update existing ADR status to 'superseded', link to this one
+  2. Extend — amend the existing ADR instead of creating a new one
+  3. Proceed with awareness — document the tension in ## Consequences
+  ```
+- Never silently create a spec that contradicts an accepted ADR.
+- If no conflicts: proceed silently.
+
+**Step 3 — Answer the four SPEC questions**
+- **WHAT**: Concrete deliverable
+- **DONE-WHEN**: Specific checks that prove completion
+- **CONSTRAINTS**: Performance, compatibility, compliance requirements
+- **NON-GOALS**: What this explicitly does NOT include
+
+**Step 4 — Write the spec**
+
+For ADR type:
+```markdown
+---
+tags: [adr, {project-slug}]
+date: {YYYY-MM-DD}
+status: proposed
+source: agent
+---
+# ADR: {title}
+
+## Decision
+One sentence. What was decided.
+
+## Context
+Why this decision was needed. What constraints applied.
+
+## Options Considered
+| Option | Pros | Cons |
+|--------|------|------|
+
+## Consequences
+What this makes easier, harder, or impossible going forward.
+```
+
+For SPEC type:
+```markdown
+---
+tags: [spec, {project-slug}]
+date: {YYYY-MM-DD}
+status: draft
+source: agent
+---
+# Spec: {title}
+
+## What
+{concrete deliverable}
+
+## Done When
+- [ ] {specific verifiable check}
+
+## Constraints
+{requirements}
+
+## Non-Goals
+{what this explicitly does NOT include}
+
+## Design
+{technical detail}
+```
+
+For RISK type:
+```markdown
+---
+tags: [risk, {project-slug}]
+date: {YYYY-MM-DD}
+severity: critical | high | medium | low
+status: open
+source: agent
+---
+# Risk: {R-ID} — {title}
+
+## Description
+What the risk is and what triggers it.
+
+## Impact
+What happens if this materializes.
+
+## Mitigation
+Specific steps — never "TBD".
+
+## Owner
+Who is responsible.
+```
+
+**Step 5 — Write to vault**
+- Filename: `{YYYY-MM-DD}_{kebab-title}.md`
+- Location: `{vault_path}/specs/`
+- Vault indexing is automatic
+- Report: `✓ Spec written to {vault_path}/specs/{filename}`