claude-dev-env 1.68.0 → 1.69.0

package/skills/refine/CLAUDE.md

@@ -0,0 +1,44 @@
+# refine
+
+Interview-driven plan refiner with a built-in audit loop: fans out research agents, interviews via `AskUserQuestion`, writes the plan to the Obsidian vault, then loops audit and fix until clean.
+
+**Trigger:** `/refine`, "refine this", "turn this into a plan", "flesh this out", "make a spec for this", "let's plan this out".
+
+## Purpose
+
+Walks a half-formed plan to a complete, audited implementation spec. The output always lands in the Obsidian vault at `Research/<topic>/<slug>.md`. The interview step is mandatory and cannot be suppressed by autonomous-mode or no-clarifying-questions directives.
+
+## Key files
+
+| File | Purpose |
+|---|---|
+| `SKILL.md` | Hub — 10-step process, gotchas, constraints, file index |
+| `templates/plan-template.md` | Required structure for the written plan (YAML frontmatter + H1 + sections) |
+| `templates/implementation-notes-template.html` | Skeleton the fix agent appends to during the audit-fix loop |
+
+## Subdirectories
+
+| Directory | Purpose |
+|---|---|
+| `templates/` | Output structures for the plan and the iteration notes file |
+
+## Ten-step process (summary)
+
+1. Resolve the topic (from `$ARGUMENTS`, file path, or conversation)
+2. Layered fan-out via Explore agent (vault + repo + draft)
+3. Existing-match decision (refine a prior plan or start fresh)
+4. Interview loop via `AskUserQuestion` (mandatory, never skipped)
+5. Confirm slug and path (`Research/<topic>/<slug>.md`)
+6. Write the plan inline via `mcp__obsidian__write_note`
+7. First audit via `general-purpose` agent (plan-quality rubric, not code rubric)
+8. Audit-fix loop (up to 10 iterations; fix agent appends to HTML notes file)
+9. Halt and surface open findings if cap reached
+10. Report vault path, iteration count, and notes-file path
+
+## Conventions
+
+- Output goes to the Obsidian vault only — never to `docs/plans/`, `.claude/plans/`, or the cwd.
+- HTML notes file (`<slug>-implementation-notes.html`) is append-only; each iteration adds one `<section>`.
+- Slug and topic must match `^[a-z0-9-]+$`; path separators and uppercase letters are rejected.
+- `Research/` prefix is fixed and cannot be overridden by a local plans folder.
+- Audit uses `general-purpose` — not `code-quality-agent` or `clean-coder`, which target source code.

package/skills/refine/templates/CLAUDE.md

@@ -0,0 +1,17 @@
+# refine/templates
+
+Output structure templates for the `/refine` skill.
+
+## Key files
+
+| File | Purpose |
+|---|---|
+| `plan-template.md` | Required plan structure: YAML frontmatter (project, date, status, tags), H1 title, and sections (Goal, Non-goals, Current state, Implementation, Decisions log, Risks, Open questions, Acceptance). The `/refine` skill loads this on Step 6 and fills every placeholder before writing to the vault. |
+| `implementation-notes-template.html` | Skeleton HTML file the fix agent copies on iteration 1 of the audit-fix loop, then appends to on each later iteration. Each iteration adds one `<section class="iteration">` block before `</body>`. The template has an HTML-commented reference block showing the section markup shape. |
+
+## Conventions
+
+- `plan-template.md` is for `mcp__obsidian__write_note` (Markdown only); the skill writes it to the vault directly.
+- `implementation-notes-template.html` is for filesystem Write/Edit tools; `mcp__obsidian__write_note` cannot write `.html`.
+- Both files have `{{slug}}` and other placeholder tokens that the skill substitutes before writing.
+- Do not write to these templates directly — they are read-only reference structures consumed by the `/refine` workflow.

package/skills/remember/CLAUDE.md

@@ -0,0 +1,31 @@
+# remember
+
+Saves a decision, gotcha, or architectural choice to the Obsidian vault as a structured note.
+
+**Trigger:** User-initiated only. `/remember [what to remember]`.
+
+## Purpose
+
+Writes a decision, fact, procedure, or gotcha to `decisions/[Project] - [Short Title].md` in the Obsidian vault. Each note carries structured frontmatter and a body shaped by its type, making it searchable and readable via `/recall`.
+
+## Key files
+
+| File | Purpose |
+|---|---|
+| `SKILL.md` | The complete skill — six steps (parse input, classify type, infer project, generate title, write to vault, confirm). No companion files. |
+
+## Four note types
+
+| Type | Body format |
+|---|---|
+| `decision` | Decision + Reasoning + Alternatives + Consequences |
+| `gotcha` | Gotcha + Symptom + Fix |
+| `procedural` | 1–3 clear sentences describing the how-to |
+| `fact` | 1–3 clear sentences stating the fact |
+
+## Conventions
+
+- `disable-model-invocation: true` is set — runs without a secondary LLM call.
+- Writes via `mcp__obsidian__write_note` only; never edits existing notes.
+- Path pattern: `decisions/[Project] - [Short Title].md`.
+- Companion to `/recall` (reads vault) and `/session-log` (triggers decision extraction at session end).

package/skills/research-mode/CLAUDE.md

@@ -0,0 +1,35 @@
+# research-mode
+
+Activates three anti-hallucination constraints: cite every claim, say "I don't know" when evidence is lacking, and quote directly from source documents.
+
+**Trigger:** "research mode", "toggle research", `/research-mode`.
+
+## Purpose
+
+Enforces factual accuracy for research tasks by requiring citations and explicit uncertainty. Stays active until the user exits with "exit research mode".
+
+## Key files
+
+| File | Purpose |
+|---|---|
+| `SKILL.md` | The complete skill — three constraints, source authority hierarchy, exit condition. No companion files. |
+
+## Three active constraints (all simultaneous)
+
+1. **Say "I don't know"** when no credible source backs a claim.
+2. **Verify with citations** — every recommendation cites a specific source (project file, URL, named expert, or official docs).
+3. **Direct quotes for factual grounding** — extract actual text before analyzing; ground in word-for-word quotes.
+
+## Source authority hierarchy
+
+1. Official vendor/creator documentation
+2. Files in the current project
+3. Academic papers, named researchers
+4. Reputable external sources with URLs
+5. Blog posts and community content (lowest; never cited alone when official docs exist)
+
+## Conventions
+
+- This mode is not the default; it applies only after the trigger fires.
+- Creative thinking and brainstorming are out of scope for this mode.
+- The global `~/.claude/rules/research-mode.md` carries the same three constraints as always-on background rules; this skill makes them explicit and surfaced during the session.

package/skills/session-log/CLAUDE.md

@@ -0,0 +1,31 @@
+# session-log
+
+Logs a session report as a gallery-shaped HTML file in the Obsidian vault, auto-publishes it as a secret gist, extracts unrecorded decisions, tidies the project session folder, and outputs a `/rename` command.
+
+**Trigger:** `/session-log`, "journal this session", "log this work", "session report", "save session", "capture session", "document what we did".
+
+## Purpose
+
+Produces a self-contained HTML session report shaped to the session's character (feature build, incident, research, etc.) rather than a fixed template. The skill owns the vault path, session numbering, frontmatter contract, decision extraction, and folder hygiene; it delegates HTML authorship to `doc-gist`.
+
+## Key files
+
+| File | Purpose |
+|---|---|
+| `SKILL.md` | Hub — six steps, gotchas, backend detection, frontmatter contract, run-and-report checklist. Single-file skill; no companion files. |
+
+## Six steps
+
+1. **Backend detection** — headless vault (`ob --version` + `OBSIDIAN_VAULT_PATH`) then local vault (`~/.claude/vault/`). Session number from `[N]. *.html` and `[N]. *.md` files in the project folder.
+2. **Session metadata** — project name, session number, session ID from `CLAUDE_CODE_SESSION_ID`, date, title.
+3. **HTML via doc-gist shape principles** — gallery-anchored design (e.g., `17-pr-writeup.html` for feature builds, `12-incident-report.html` for incidents). `<!-- @publish-as-gist -->` marker triggers auto-publish hook on Write/Edit.
+4. **Vault context tracking** — two Edit calls set `vault_context_retrieved` and append a vault-context line. The URL from the final Edit is canonical.
+5. **Decision extraction** — scans conversation for unrecorded decisions; prompts user via `AskUserQuestion` before invoking `/remember`.
+6. **Session tidy** — audits `.html` files in the project folder for naming and frontmatter; auto-fixes minor issues.
+
+## Conventions
+
+- The `<!-- @publish-as-gist -->` marker must appear exactly as shown; each Edit re-fires the hook and produces a new gist ID.
+- Session reports use HTML; `.md` paths are blocked by `md_to_html_blocker` for session paths.
+- `write_existing_file_blocker` rejects Write on existing paths — use Edit for all vault-context updates.
+- Final step copies `/rename [Project] - [Primary Outcome]` to the clipboard via `pwsh Set-Clipboard`.

package/skills/session-tidy/CLAUDE.md

@@ -0,0 +1,36 @@
+# session-tidy
+
+Audits, cleans, and consolidates session logs in the Obsidian vault — fixes format drift, resolves orphaned next-steps, updates stale statuses, and generates project rollup summaries.
+
+**Trigger:** `/session-tidy`, "tidy sessions", "clean up session logs", "session audit".
+
+## Purpose
+
+Maintenance utility for the `sessions/[Project]/` vault directories. Enforces the session-log format contract, moves uncategorized files into project subfolders, and generates `Summary.md` rollup files for projects with 3+ sessions.
+
+## Key files
+
+| File | Purpose |
+|---|---|
+| `SKILL.md` | The complete skill — four phases (preflight, audit, propose changes, execute + verify). No companion files. |
+
+## Format contract enforced
+
+- **Path:** `sessions/[Project]/[N]. [Title].md`
+- **Frontmatter:** `type`, `project`, `session`, `date`, `status`, `blocked`, `tags` — all needed.
+- **Status rules:** `completed` + `blocked: true` is contradictory; `in-progress` or `blocked` older than 7 days is stale.
+- **Content:** outcome-oriented `###` headers with one emoji; no play-by-play narration.
+
+## Four phases
+
+1. **Preflight** — resolve backend (headless vault, Obsidian MCP, or local vault).
+2. **Audit** — check each file for naming, frontmatter completeness, status coherence, orphaned next-steps, and categorization.
+3. **Propose changes** — report findings; wait for user approval before changing anything.
+4. **Execute + verify** — rename files, fix frontmatter, update statuses, clean orphaned next-steps, generate `Summary.md` rollups.
+
+## Conventions
+
+- `disable-model-invocation: true` is set.
+- Changes need explicit user approval from Phase 2's report — the skill never auto-applies without approval.
+- Companion to `/session-log` (creates sessions) and `/recall` (reads vault).
+- `/session-tidy` targets Markdown session format; HTML sessions from `/session-log` may be mis-audited or get incorrect rename proposals.

package/skills/skill-builder/CLAUDE.md

@@ -0,0 +1,45 @@
+# skill-builder
+
+Orchestrates the complete skill-building lifecycle: classify the skill type, scaffold folders, write via `skill-writer`, self-audit against a 38-point checklist, and refine from real usage observations.
+
+**Trigger:** "build a skill", "new skill workflow", "improve this skill", "optimize skill description", "skill development lifecycle".
+
+## Purpose
+
+The expert that enforces craft standards. For quick one-off SKILL.md edits, use `/skill-writer` directly. This skill classifies, scaffolds, gathers context, delegates writing, and self-audits the result.
+
+## Key files
+
+| File | Purpose |
+|---|---|
+| `SKILL.md` | Hub — routing, 9-type taxonomy table, core principles, file index |
+| `references/skill-types.md` | 9-type taxonomy with folder structures per type |
+| `references/progressive-disclosure.md` | Hub pattern, folder conventions, hard rules |
+| `references/self-audit-checklist.md` | 38-point mandatory post-build audit |
+| `references/delegation-map.md` | Subagent handoff patterns and transcript guidance |
+| `references/thariq-x-post-skills.json` | Source reference — lessons from building Claude Code skills |
+| `workflows/new-skill.md` | Full lifecycle for new skills (6 steps) |
+| `workflows/improve-skill.md` | Observation-first flow for existing skills (6 steps) |
+| `workflows/polish-skill.md` | Description audit and final validation (5 steps) |
+| `templates/gap-analysis.md` | Template for documenting skill gaps |
+
+## Subdirectories
+
+| Directory | Purpose |
+|---|---|
+| `references/` | Best-practice specs and the audit checklist |
+| `workflows/` | Step-by-step workflows for each lifecycle phase |
+| `templates/` | Reusable templates for skill artifacts |
+
+## Routing
+
+- **New skill** → `workflows/new-skill.md`
+- **Improve existing** → `workflows/improve-skill.md`
+- **Final polish only** → `workflows/polish-skill.md`
+- **Ambiguous** → ask the user which one applies
+
+## Conventions
+
+- Every build ends with the 38-point self-audit at `references/self-audit-checklist.md`; fix failures before delivery.
+- `skill-builder` orchestrates; `skill-writer` authors. The handoff packet must include type, gap analysis, degree-of-freedom assessment, and constraints.
+- The Claude A / Claude B pattern: Claude A (this session) designs; Claude B (subagents) tests by running the built skill on real tasks.

package/skills/skill-builder/references/CLAUDE.md

@@ -0,0 +1,19 @@
+# skill-builder/references
+
+Best-practice specifications and the mandatory self-audit checklist for the `/skill-builder` skill.
+
+## Key files
+
+| File | Purpose |
+|---|---|
+| `self-audit-checklist.md` | 38-point checklist run after every build, improvement, or polish pass. Every item must pass before delivery. |
+| `skill-types.md` | 9-type skill taxonomy with folder structures per type (Library & API Reference, Product Verification, Data Fetching, Business Process, Code Scaffolding, Code Quality, CI/CD, Runbooks, Infrastructure). |
+| `progressive-disclosure.md` | Hub pattern, folder conventions, and hard rules: SKILL.md under 500 lines, detail in reference/, scripts execute without context load, references one level deep. |
+| `delegation-map.md` | Subagent handoff patterns and transcript guidance for the skill-builder → skill-writer handoff. |
+| `thariq-x-post-skills.json` | Source reference data from Anthropic lessons on building Claude Code skills. |
+
+## Conventions
+
+- These files are loaded on demand by `SKILL.md` routing — not all are loaded on every run.
+- `self-audit-checklist.md` is always loaded at the end of a build cycle.
+- `thariq-x-post-skills.json` is source reference data, not executable content.

package/skills/skill-builder/templates/CLAUDE.md

@@ -0,0 +1,14 @@
+# skill-builder/templates
+
+Reusable template for skill-building artifacts.
+
+## Key files
+
+| File | Purpose |
+|---|---|
+| `gap-analysis.md` | Template for documenting gaps in an existing skill. Used during the "improve existing skill" workflow (Step 2 observation gathering) to structure findings before writing a new version. |
+
+## Conventions
+
+- The gap-analysis template is loaded by the `improve-skill.md` workflow, not the `new-skill.md` workflow.
+- Fill in the template inline during the workflow; do not commit completed gap analyses to this directory.

package/skills/skill-builder/workflows/CLAUDE.md

@@ -0,0 +1,17 @@
+# skill-builder/workflows
+
+Step-by-step workflow files for each skill lifecycle phase, loaded on demand by `SKILL.md` routing.
+
+## Key files
+
+| File | Purpose |
+|---|---|
+| `new-skill.md` | Full lifecycle for creating a new skill: 6 steps from intent capture through type classification, folder scaffolding, writing via skill-writer, self-audit, and delivery. |
+| `improve-skill.md` | Observation-first flow for improving an existing skill: 6 steps starting from real usage failures, gap analysis, targeted rewrite, and re-audit. |
+| `polish-skill.md` | Description audit and final validation: 5 steps for description optimization, trigger phrase review, and checklist sign-off. |
+
+## Conventions
+
+- `SKILL.md` routes to exactly one workflow file per invocation based on the user's intent (new / improve / polish).
+- Each workflow references `../references/self-audit-checklist.md` at its final step.
+- Load only the workflow that matches the active task; the other two stay out of context.

package/skills/structure-prompt/CLAUDE.md

@@ -0,0 +1,42 @@
+# structure-prompt
+
+Restructures a prompt in one pass: orders blocks, converts persona framing to task constraints, enforces per-category dispositions, expands placeholder tokens, adds `file:line` citations, marks the canonical sub-bucket, and sharpens adversarial-pass phrasing.
+
+**Trigger:** `/structure-prompt`, "optimize this prompt", "minimally invasive edit" to a prompt artifact, "tighten this prompt".
+
+## Purpose
+
+Applies a spoke-based ruleset to a prompt artifact. Each spoke targets a specific structural problem (persona framing, narrative directives, missing citations, etc.). One pass per invocation.
+
+## Key files
+
+| File | Purpose |
+|---|---|
+| `SKILL.md` | Hub — pre-flight, first-invocation reads, spoke routing table |
+| `reference/block-classification.md` | How to classify each block in the input prompt |
+| `reference/research.md` | When a spoke needs information not in the input |
+| `reference/output-contract.md` | How to emit the rewritten prompt |
+| `reference/structure.md` | Re-ordering blocks and handling large content regions |
+| `reference/persona.md` | Converting role assignments to task constraints |
+| `reference/per-category.md` | Enforcing per-category dispositions |
+| `reference/directives.md` | Rewriting performance directives |
+| `reference/constraints.md` | Rewriting narrative directives |
+| `reference/instantiation.md` | Expanding placeholder tokens |
+| `reference/citation-depth.md` | Adding `file:line` citations |
+| `reference/canonical-case.md` | Marking the canonical sub-bucket with ⭐ |
+| `reference/adversarial-tuning.md` | Sharpening adversarial-pass phrasing |
+| `reference/cleanup.md` | Fixing typos, mixed bullet styles, untagged code blocks |
+| `reference/examples.md` | Spoke-matched examples for situations not covered above |
+
+## Subdirectories
+
+| Directory | Purpose |
+|---|---|
+| `reference/` | One file per spoke; loaded on demand based on the routing table in `SKILL.md` |
+
+## Conventions
+
+- On first invocation, read `block-classification.md`, `research.md`, and `output-contract.md` before anything else.
+- The input arrives as the user's message body, a fenced block within it, or a file path argument.
+- Emit the result as a single fenced block (paste mode) or rewrite the file in place (file-path mode).
+- Load only the reference files the input situation matches — not all of them.

package/skills/structure-prompt/reference/CLAUDE.md

@@ -0,0 +1,28 @@
+# structure-prompt/reference
+
+One reference file per optimization spoke, loaded on demand by the routing table in `SKILL.md`.
+
+## Key files
+
+| File | Purpose |
+|---|---|
+| `block-classification.md` | How to classify each block in the input prompt (mission, metadata, framework, questions, output spec, data body). Read on every invocation. |
+| `research.md` | Steps to take when a spoke needs information not in the input. Read on every invocation. |
+| `output-contract.md` | How to emit the rewritten prompt (fenced paste mode or in-place file rewrite). Read on every invocation. |
+| `structure.md` | Re-ordering blocks and handling large content regions (≥500 chars, fenced code, diffs, transcripts). |
+| `persona.md` | Converting role assignments ("You are…", "Act as…") to task constraints. |
+| `per-category.md` | Enforcing per-category dispositions when the prompt names 2+ categories or criteria. |
+| `directives.md` | Rewriting performance directives ("be thorough", "think step by step"). |
+| `constraints.md` | Rewriting narrative directives ("try to", "make sure", "consider"). |
+| `instantiation.md` | Expanding placeholder tokens (`[REPO/ARTIFACT]`, `[N]`, etc.). |
+| `citation-depth.md` | Adding `file:line` citations to sub-bucket bullets that reference identifiers. |
+| `canonical-case.md` | Marking the ⭐ canonical sub-bucket when a framework has 5+ sub-buckets and none is marked. |
+| `adversarial-tuning.md` | Sharpening generic adversarial-pass phrasing. |
+| `cleanup.md` | Fixing typos, mixed bullet styles, untagged code blocks, trailing whitespace. |
+| `examples.md` | Spoke-matched examples for situations not covered by the named spokes above. |
+
+## Conventions
+
+- Read `block-classification.md`, `research.md`, and `output-contract.md` on every first invocation of a session.
+- For all other files: load only the one(s) that match the input situation — the `SKILL.md` routing table maps each situation to its spoke file.
+- Never load the full set; spoke files are designed for on-demand use to keep context lean.

package/skills/task-build/CLAUDE.md

@@ -0,0 +1,28 @@
+# task-build
+
+Gathers every open task in the current session and registers each one on the task list with `TaskCreate`.
+
+**Trigger:** `/task-build`, "build my task list", "capture these tasks", "add open tasks to the task list", "track these".
+
+## Purpose
+
+Collects outstanding work from the conversation, `$ARGUMENTS`, and any plan documents or `TodoWrite` items raised this session, then creates one task per open item — skipping anything already tracked or already complete.
+
+## Key files
+
+| File | Purpose |
+|---|---|
+| `SKILL.md` | The complete skill — four steps (read current list, find open tasks, create one task per item, report). No companion files. |
+
+## How the skill runs
+
+1. Calls `TaskList` to read what is already tracked — prevents duplicates.
+2. Scans `$ARGUMENTS`, the conversation, and any plan or checklist items for open, actionable work.
+3. Calls `TaskCreate` for each untracked item with a short imperative `subject`, a `description` of what done looks like, and an optional `activeForm` for the spinner.
+4. Reports how many tasks were added and how many were already tracked.
+
+## Conventions
+
+- This skill only records tasks — it does not start, assign, or complete them.
+- Use `TaskUpdate` to set status or owner after the list is built.
+- `disable-model-invocation: true` is not set; the skill uses model judgment to classify open vs. complete items.

package/skills/update/CLAUDE.md

@@ -0,0 +1,38 @@
+# update
+
+Fast-forwards a local git repository's `main` branch to a chosen remote's `main`.
+
+**Trigger:** `/update`, "update main", "fast-forward main", "sync main from origin", "pull latest main into <path>", "bring main up to date".
+
+## Purpose
+
+Advances the `main` ref in a safe, confirmed, fast-forward-only way. Never forces, never merges. Confirms the repo path and source remote before any write. Offers to switch the checkout to `main` after the ref moves, with a clean-tree safety check.
+
+## Key files
+
+| File | Purpose |
+|---|---|
+| `SKILL.md` | The complete skill — five phases, refusals, gotchas. Flat by design; no companion files. |
+
+## Five phases
+
+| Phase | Key action |
+|---|---|
+| 1 — Resolve path | `git -C "<path>" rev-parse --show-toplevel` |
+| 2 — Confirm path + remote | One `AskUserQuestion` listing remote/URL pairs; recommends `origin/main` first |
+| 3 — Fetch + fast-forward | Fetch, check ancestry with `merge-base --is-ancestor`, apply via `merge --ff-only` (on main) or `fetch main:main` (off main) |
+| 4 — Report | Old SHA → new SHA, checkout state, dirty tracked files |
+| 5 — Offer to land on disk | `AskUserQuestion` to switch checkout to `main` (only when tree is clean and `main` is not held by another worktree) |
+
+## Refusals (first match wins)
+
+- Path is not a git repository → stated error, stop.
+- Remote has no `main` → stated error, stop.
+- Local `main` has diverged (not a fast-forward) → stated error, stop. Use `/rebase` to reconcile.
+
+## Conventions
+
+- Every command uses `git -C "<path>"` — never `cd` into the repo.
+- Path confirmation is mandatory even when the path comes from the argument.
+- The skill never switches to any branch other than `main`, and only in Phase 5 with operator approval.
+- `origin` is not always the source of truth; the confirmed remote may be `upstream` or another name.

package/skills/verified-build/CLAUDE.md

@@ -0,0 +1,33 @@
+# verified-build
+
+Runs a code task through the two-phase verified workflow: scoped coder agents write the changes, then a fresh-context `code-verifier` agent re-derives and runs every check itself.
+
+**Trigger:** "verified build", "run this verified", "two-phase build", "build and verify", "verified implementation".
+
+## Purpose
+
+Ensures that `git commit`/`git push` open only after a clean, hook-minted verifier verdict bound to the live change surface. The `verified_commit_gate` hook blocks commits and pushes until a verdict covers the current branch diff.
+
+## Key files
+
+| File | Purpose |
+|---|---|
+| `SKILL.md` | The complete skill — workflow checklist, gotchas. No companion files. |
+
+## Workflow (copy-this checklist)
+
+- [ ] Record baselines (test command + exact failure set) before coders start
+- [ ] Scope assignments into file-disjoint tasks with named checks
+- [ ] Spawn one `clean-coder` (or Sonnet) agent per assignment; each consults `code-advisor` on decisions it cannot resolve
+- [ ] Settle the tree after coders finish (run formatters, stage nothing)
+- [ ] Spawn `code-verifier` (fresh context) with task texts, diff scope, and baselines
+- [ ] Repair only reported findings; re-spawn verifier after each repair
+- [ ] Land in one commit + push + draft PR as soon as verdict is clean
+
+## Conventions
+
+- Any file change after the verifier stops re-locks the gate — run formatters before spawning the verifier.
+- The verifier must end with a ` ```verdict ` fence; the `verifier_verdict_minter` hook mints the verdict from that fence.
+- The minter keys on agent type string `code-verifier` — the same prompt under another agent type mints nothing.
+- Docs/image-only diffs, docstring-only Python diffs, and pytest test files (`test_*.py`, `*_test.py`, `conftest.py`) are exempt from the gate automatically.
+- Record the test baseline before coders start; without it, new breakage hides inside old noise.

package/system-prompts/CLAUDE.md

@@ -0,0 +1,17 @@
+# system-prompts
+
+System prompt files installed into `~/.claude/system-prompts/` by `bin/install.mjs`. Claude Code loads these as the base persona and behavioral protocol for a session.
+
+## Files
+
+| File | Purpose |
+|---|---|
+| `software-engineer.xml` | Primary system prompt: defines the software engineering role, task-scope rules, output style, and the BDD `<behavior_protocol>` that rules in `rules/bdd.md` reference |
+
+## Format
+
+Files use XML with named sections (`<role>`, `<task_scope>`, `<output_style>`, `<behavior_protocol>`, etc.). Claude Code injects the full file into the system prompt slot at session start.
+
+## Adding a prompt
+
+Create a new `.xml` file and run `bin/install.mjs` to copy it to `~/.claude/system-prompts/`. Reference the new file in the relevant rule or skill by its installed path.