joycraft 0.6.13 → 0.6.14

package/dist/{chunk-GM2T44P6.js → chunk-VCLRPD62.js}

@@ -7,7 +7,7 @@ var SKILLS = {
   "joycraft-bugfix.md": "---\nname: joycraft-bugfix\ndescription: Structured bug fix workflow \u2014 triage, diagnose, discuss with user, write a focused spec, hand off for implementation\ninstructions: 32\n---\n\n# Bug Fix Workflow\n\nYou are fixing a bug. Follow this process in order. Do not skip steps.\n\n**Guard clause:** If this is clearly a new feature, redirect to `/joycraft-new-feature` and stop.\n\n---\n\n## Phase 1: Triage\n\nEstablish what's broken. Gather: symptom, steps to reproduce, expected vs actual behavior, when it started, relevant logs/errors. If an error message or stack trace is provided, read the referenced files immediately. Try to reproduce if steps are given.\n\n**Done when:** You can describe the symptom in one sentence.\n\n---\n\n## Phase 2: Diagnose\n\nFind the root cause. Start from the error site and trace backward. Read source files \u2014 don't guess. Identify the specific line(s) and logic error. Check git blame if it's a recent regression.\n\n**Done when:** You can explain what's wrong, why, and where in 2-3 sentences.\n\n---\n\n## Phase 3: Discuss\n\nPresent findings to the user BEFORE writing any code or spec:\n1. **Symptom** \u2014 confirm it matches what they see\n2. **Root cause** \u2014 specific file(s) and line(s)\n3. **Proposed fix** \u2014 what changes, where\n4. **Risk** \u2014 side effects? scope?\n\nAsk: \"Does this match? Comfortable with this approach?\" If large/risky, suggest decomposing into multiple specs.\n\n**Done when:** User agrees with the diagnosis and fix direction.\n\n---\n\n## Phase 4: Spec the Fix\n\nWrite a bug fix spec to `docs/bugfixes/<area>/bugfix-name.md`. Use the relevant area as the subdirectory (e.g., `auth`, `cli`, `parser`). Lazy-create the `docs/bugfixes/<area>/` directory if it doesn't exist.\n\n(Bugfixes live under `docs/bugfixes/<area>/`, separate from `docs/features/<slug>/specs/`. Bugfixes are area-level, not feature-tied \u2014 multiple unrelated bugs accumulate in the same area folder over time, which is a fundamentally different folder shape from features.)\n\n**Area README:** When creating (or adding to) a `docs/bugfixes/<area>/` folder, also lazy-create/update a `docs/bugfixes/<area>/README.md` index \u2014 a one-line-per-bug table (`| Bug | Spec | Status | Date |`) so areas that accumulate many bugs stay navigable. Append a row for the new bugfix.\n\n**Why:** Even bug fixes deserve a spec. It forces clarity on what \"fixed\" means, ensures test-first discipline, and creates a traceable record of the fix.\n\nThe spec file MUST start with YAML frontmatter \u2014 the 4-field personal schema (the `area:` field carries the area name, used informally to indicate \"what folder this lives under\"):\n\n```yaml\n---\nstatus: active\nowner: <resolved name>\ncreated: YYYY-MM-DD\narea: <area>\n---\n```\n\n**Owner resolution:** look up the owner name in this order \u2014 (1) `git config user.name`, (2) value in your auto-memory `joycraft-owner.txt` if present, (3) ask the user once and persist.\n\nUse this template for the body:\n\n```markdown\n# Fix [Bug Description] \u2014 Bug Fix Spec\n\n> **Parent Brief:** none (bug fix)\n> **Issue/Error:** [error message, issue link, or symptom description]\n> **Status:** Ready\n> **Date:** YYYY-MM-DD\n> **Estimated scope:** [1 session / N files / ~N lines]\n\n---\n\n## Bug\n\nWhat is broken? Describe the symptom the user experiences.\n\n## Root Cause\n\nWhat is wrong in the code and why? Name the specific file(s) and line(s).\n\n## Fix\n\nWhat changes will fix this? Be specific \u2014 describe the code change, not just \"fix the bug.\"\n\n## Acceptance Criteria\n\n- [ ] [The bug no longer occurs \u2014 describe the correct behavior]\n- [ ] [No regressions in related functionality]\n- [ ] Build passes\n- [ ] Tests pass\n\n## Test Plan\n\n| Acceptance Criterion | Test | Type |\n|---------------------|------|------|\n| [Bug no longer occurs] | [Test that reproduces the bug, then verifies the fix] | [unit/integration/e2e] |\n| [No regressions] | [Existing tests still pass, or new regression test] | [unit/integration] |\n\n**Execution order:**\n1. Write a test that reproduces the bug \u2014 it should FAIL (red)\n2. Run the test to confirm it fails\n3. Apply the fix\n4. Run the test to confirm it passes (green)\n5. Run the full test suite to check for regressions\n\n**Smoke test:** [The bug reproduction test \u2014 fastest way to verify the fix works]\n\n**Before implementing, verify your test harness:**\n1. Run the reproduction test \u2014 it must FAIL (if it passes, you're not testing the actual bug)\n2. The test must exercise your actual code \u2014 not a reimplementation or mock\n3. Identify your smoke test \u2014 it must run in seconds, not minutes\n\n## Constraints\n\n- MUST: [any hard requirements for the fix]\n- MUST NOT: [any prohibitions \u2014 e.g., don't change the public API]\n\n## Affected Files\n\n| Action | File | What Changes |\n|--------|------|-------------|\n\n## Edge Cases\n\n| Scenario | Expected Behavior |\n|----------|------------------|\n```\n\n**For trivial bugs:** The spec will be short. That's fine \u2014 the structure is the point, not the length.\n\n**For large bugs that span multiple files/systems:** Consider whether this should be decomposed into multiple specs. If so, create a brief first using `/joycraft-new-feature`, then decompose. A bug fix spec should be implementable in a single session.\n\n---\n\n## Phase 5: Hand Off\n\nTell the user a one-line summary, then emit the canonical Handoff block.\n\n## Recommended Next Steps\n\nNext:\n```bash\n/joycraft-implement docs/bugfixes/<area>/bugfix-name.md\n```\nRun /clear first.\n\n**Why:** A fresh session for implementation produces better results. This diagnostic session has context noise from exploration \u2014 a clean session with just the spec is more focused.\n",
   "joycraft-collaborative-setup.md": '---\nname: joycraft-collaborative-setup\ndescription: Set up Joycraft for a team \u2014 scaffold per-area folders, owner conventions, and a team-facing CONTRIBUTING doc. Run once when adopting Joycraft on a multi-dev project.\n---\n\n# Collaborative Setup\n\nYou are setting up Joycraft for a team. Solo defaults stay solo; this skill adds the team-only ceremony \u2014 `docs/areas/` folders, area README/boundaries, and a thin team-facing CONTRIBUTING-joycraft doc.\n\nThis skill is **interactive** \u2014 ask the user, don\'t auto-detect.\n\n## When to run\n\nRun once when a team is adopting Joycraft on a multi-dev project. Solo users do **not** need this skill \u2014 solo defaults are fine without it.\n\n## Step 1: Confirm Team Context\n\nAsk the user:\n\n> "Setting up Joycraft for a team? (vs. solo work) If you\'re unsure, you can skip \u2014 solo defaults work fine and you can run this later."\n\nIf the user says "actually solo," bail before any writes:\n\n> "No problem. The solo workflow needs no extra setup. Run `/joycraft-new-feature` when you want to start a feature."\n\n## Step 2: Check for Flat Layout \u2014 Bail if Present\n\nBefore scaffolding team structure, check the project\'s docs/ for per-feature artifacts. Look for any of:\n\n- `docs/features/<slug>/brief.md`\n- `docs/features/<slug>/research.md`\n- `docs/features/<slug>/design.md`\n- Loose spec subdirectories that predate the per-feature layout (specs not under `docs/features/<slug>/specs/` or `docs/bugfixes/<area>/`)\n\nIf any **flat layout** artifacts exist, tell the user:\n\n> "I see flat-layout artifacts in your docs/ (briefs/research/designs). Run `npx joycraft upgrade` first \u2014 it will migrate them into `docs/features/<slug>/` automatically. Then re-run this skill."\n\nThen stop. Skills don\'t reliably shell out, so the CLI does the migration.\n\n## Step 3: Gather Areas + Owners (Interactive)\n\nAsk the user:\n\n> "How many areas does your team work in? (e.g., `auth`, `api`, `frontend`, `infra`) \u2014 pick names that match how your team thinks about ownership. You can also skip and just create the team CONTRIBUTING doc."\n\nFor each area name the user provides:\n1. Confirm the name (kebab-case).\n2. Ask: "Who owns this area? (a name, an email, or a team handle \u2014 used in the area README\'s frontmatter)"\n3. Ask (optional): "Are there NEVER or ASK FIRST rules specific to this area? If yes, list them; if no, skip."\n\nIf the user provides duplicate names, ask them to pick a different one. Track the area list in your working memory before writing anything.\n\nIf the user provides 0 areas, skip Step 4 and go straight to Step 5 (CONTRIBUTING doc only). Useful path for "we just want the team doc, no areas yet."\n\n## Step 4: Scaffold Each Area\n\nFor each confirmed area, lazy-create `docs/areas/<area-name>/` and write a `README.md` with the **shared frontmatter schema** (areas are shared docs, not personal):\n\n```yaml\n---\nlast_updated: YYYY-MM-DD\nlast_updated_by: <owner from step 3>\n---\n```\n\n**Owner resolution for `last_updated_by`:** look up the owner name in this order \u2014 (1) `git config user.name`, (2) value in your auto-memory `joycraft-owner.txt` if present, (3) ask the user once and persist. Use the user-provided owner from Step 3 if they specified one for this area.\n\nBody of `README.md`:\n\n```markdown\n# <area-name>\n\n> **Owner:** <name from Step 3>\n> **Status:** active\n\n## What this area covers\n\n(Filled in by the area owner)\n\n## Conventions\n\n(Area-specific patterns or constraints)\n\n## Onboarding\n\nWhen a new dev joins this area, they should:\n1. Read this README\n2. Read `boundaries.md` (if present)\n3. Read the codebase under <area-relevant paths>\n```\n\nIf the user provided NEVER / ASK FIRST rules for the area, also write `docs/areas/<area-name>/boundaries.md` with the shared frontmatter and those rules. If they didn\'t, skip the boundaries file \u2014 the root CLAUDE.md boundaries already cover the project-wide cases.\n\n**Idempotency:** if `docs/areas/<area-name>/README.md` already exists, ASK before overwriting (default: skip + inform).\n\n## Step 5: Write the Team CONTRIBUTING Doc\n\nLazy-create `docs/CONTRIBUTING-joycraft.md` (NOT the project\'s main `CONTRIBUTING.md` \u2014 keep them separate so neither stomps on the other).\n\nIf `docs/templates/CONTRIBUTING-joycraft-template.md` exists in the project (it should \u2014 bundled by `npx joycraft init`), use it as the starting point. If not, fall back to the inline template below.\n\nThe doc starts with shared frontmatter:\n\n```yaml\n---\nlast_updated: YYYY-MM-DD\nlast_updated_by: <resolved owner>\n---\n```\n\nBody (inline fallback template \u2014 short by design):\n\n```markdown\n# Joycraft on this project\n\nWe use [Joycraft](https://www.npmjs.com/package/joycraft) for AI-assisted development.\n\n## How our team uses it\n\n(Filled in during /joycraft-collaborative-setup \u2014 fill this in with your team\'s specific conventions.)\n\n## Conventions\n\n- Per-feature work goes under `docs/features/<slug>/`\n- Area-level work and ownership: see `docs/areas/`\n- For "what is Joycraft?", see the package README\n\n## Onboarding\n\nWhen a new dev joins:\n1. Run `npx joycraft init` (idempotent on already-set-up projects)\n2. Read `docs/areas/<your-area>/README.md` for context\n```\n\nIf `docs/CONTRIBUTING-joycraft.md` already exists, ASK before overwriting \u2014 offer overwrite / append / skip; default to skip.\n\n## Step 6: Trigger CLAUDE.md Update\n\nNow that `docs/areas/` exists, the next `npx joycraft upgrade` (or any future `npx joycraft init`) will pick it up and add the **Areas pointer** to CLAUDE.md automatically \u2014 that pointer tells Claude "when working on the X area, read docs/areas/X/README.md first."\n\nTell the user:\n\n> "Run `npx joycraft upgrade` to refresh CLAUDE.md with the Areas pointer (or `npx joycraft init` if you haven\'t initialized yet)."\n\nDon\'t try to shell out from inside the skill \u2014 let the user run the CLI deliberately.\n\n## Step 7: Hand Off\n\nSummarize what you wrote (paths to area READMEs, the CONTRIBUTING doc, any boundaries files), then emit the canonical Handoff block.\n\n## Recommended Next Steps\n\nNext:\n```bash\n/joycraft-new-feature\n```\nRun /clear first.\n\nInclude the path to `docs/CONTRIBUTING-joycraft.md` and any newly-created area READMEs in the summary above the Handoff block.\n\n## Notes\n\n- This skill does NOT migrate flat-layout artifacts on its own. That\'s `npx joycraft upgrade`\'s job \u2014 Step 2 directs the user to run it first.\n- Area names are user-provided. Don\'t auto-detect from `src/auth/`, `src/api/`, etc. \u2014 many projects have monorepo or non-conventional layouts and auto-detection produces noise.\n- If the user stops mid-way (Ctrl-C, abandons), whatever\'s been written stays. Re-running the skill is the recovery path; it\'s idempotent on existing area folders (asks before overwriting).\n',
   "joycraft-decompose.md": '---\nname: joycraft-decompose\ndescription: Break a feature brief into atomic specs \u2014 small, testable, independently executable units\ninstructions: 32\n---\n\n# Decompose Feature into Atomic Specs\n\nYou have a Feature Brief (or the user has described a feature). Your job is to decompose it into atomic specs that can be executed independently \u2014 one spec per session.\n\n## Step 1: Verify the Brief Exists\n\nLook for a Feature Brief at `docs/features/<slug>/brief.md`. If the user provided a brief path as an argument, use that. Otherwise, scan `docs/features/*/brief.md`.\n\n**Status filter when scanning neighbor briefs and specs:** read the YAML frontmatter at the top of each file. Treat each as **live** unless its `status:` is `done`, `deprecated`, or `superseded` \u2014 those three are the only states you **skip / ignore**. Every other state is live and must be considered. The status vocabulary is `todo \u2192 in-review \u2192 done` (see `docs/reference/spec-status-lifecycle.md`); both `todo` and `in-review` are live. An `in-review` spec is finished-but-unverified work that still constrains neighboring decomposition, so it stays in scope. Also ignore anything under `docs/archive/` entirely.\n\nIf no brief exists, tell the user:\n\n> No feature brief found. Run `/joycraft-new-feature` first to interview and create one, or describe the feature now and I\'ll work from your description.\n\nIf the user describes the feature inline, work from that description directly. You don\'t need a formal brief to decompose \u2014 but recommend creating one for complex features.\n\n## Step 2: Identify Natural Boundaries\n\n**Why:** Good boundaries make specs independently testable and committable. Bad boundaries create specs that can\'t be verified without other specs also being done.\n\nRead the brief (or description) and identify natural split points:\n\n- **Data layer changes** (schemas, types, migrations) \u2014 always a separate spec\n- **Pure functions / business logic** \u2014 separate from I/O\n- **UI components** \u2014 separate from data fetching\n- **API endpoints / route handlers** \u2014 separate from business logic\n- **Test infrastructure** (mocks, fixtures, helpers) \u2014 can be its own spec if substantial\n- **Configuration / environment** \u2014 separate from code changes\n\nAsk yourself: "Can this piece be committed and tested without the other pieces existing?" If yes, it\'s a good boundary.\n\n## Step 3: Build the Decomposition Table\n\nFor each atomic spec, define:\n\n| # | Spec Name | Description | Dependencies | Size |\n|---|-----------|-------------|--------------|------|\n\n**Rules:**\n- Each spec name is `verb-object` format (e.g., `add-terminal-detection`, `extract-prompt-module`)\n- Each description is ONE sentence \u2014 if you need two, the spec is too big\n- Dependencies reference other spec numbers \u2014 keep the dependency graph shallow\n- More than 2 dependencies on a single spec = it\'s too big, split further\n- Aim for 3-7 specs per feature. Fewer than 3 = probably not decomposed enough. More than 10 = the feature brief is too big\n\n## Step 4: Present and Iterate\n\nShow the decomposition table to the user. Ask:\n1. "Does this breakdown match how you think about this feature?"\n2. "Are there any specs that feel too big or too small?"\n3. "Should any of these run in parallel (separate worktrees)?"\n\nIterate until the user approves.\n\n## Execution Modes (assign a mode per spec)\n\nEvery spec carries an **execution mode** that controls how `joycraft-implement` wraps up after building it. Assign one to each spec \u2014 recommended by you, **approved by the human** (never silent).\n\n| Mode | Per-spec wrap-up | Context between specs | Best for |\n|------|------------------|-----------------------|----------|\n| `batch` | implement all, wrap once at the end (one `joycraft-session-end`) | shared (one conversation) | clusters of tiny specs |\n| `checkpoint` | `joycraft-spec-done` after each (commit + status bump), keep going | shared | medium specs wanting atomic commits without fresh context |\n| `isolated` | `joycraft-spec-done`, then a **fresh context**, then the next spec | fresh per spec | heavy specs that would pollute one context |\n\n**Project default.** Read the default mode from the project\'s `CLAUDE.md`: look for a line `**Default execution mode:** <mode>`. If that line is **absent, default to `batch`** (the safest: shared context, wrap once). Do not hard-fail when it\'s missing \u2014 just use `batch` and say so in your recommendation.\n\n**Size \u2192 mode heuristic** (a starting recommendation, not a rule):\n\n| Spec size | Recommended mode |\n|-----------|------------------|\n| XS / S | `batch`-eligible (fold into the batch) |\n| M | `checkpoint` |\n| L / XL | `isolated` |\n\nSize is your estimate from the spec\'s scope (files touched, surface area, risk). The heuristic is only a starting point: a tiny spec inside a risky feature may still warrant `isolated`, and only the human knows that \u2014 which is why the recommendation is **approved, not auto-applied**.\n\n**Surface the recommendation and get approval.** Before writing any spec files, present your per-spec mode recommendation and wait for the human\'s OK. Worked example:\n\n> Your project defaults to `batch` (no `**Default execution mode:**` line in CLAUDE.md, so I\'m using the safe default). Based on size, I recommend: specs 1, 2 \u2192 `batch`; spec 5 \u2192 `checkpoint`; specs 7, 8 \u2192 `isolated` (large/risky). OK, or adjust?\n\nIf the human overrides any recommendation, **honor their choice verbatim** in both the frontmatter and the queue. Record the approved mode in each spec\'s `mode:` frontmatter field (Step 5) and in each queue entry\'s `"mode"` field (Step 5a). A feature may mix modes across its specs \u2014 that\'s expected; note the mix in the README/wave plan. This applies even when there\'s no brief and the feature was described inline: still assign a mode to every spec, and the CLAUDE.md default applies the same way.\n\n## Step 5: Generate Atomic Specs\n\nFor each approved row, create `docs/features/<slug>/specs/<spec-name>.md`. The slug is the feature folder name (e.g., `2026-04-06-token-discipline`). Lazy-create `docs/features/<slug>/specs/` if it doesn\'t exist.\n\nIf no brief exists and the user described the feature inline, derive a kebab-case slug yourself: `YYYY-MM-DD-<short-name>`. Create the folder structure under `docs/features/<slug>/`.\n\n**Why:** Each spec must be self-contained \u2014 a fresh Claude session should be able to execute it without reading the Feature Brief. Copy relevant constraints and context into each spec.\n\nEach spec file MUST start with YAML frontmatter \u2014 the personal schema:\n\n```yaml\n---\nstatus: todo\nowner: <resolved name>\ncreated: YYYY-MM-DD\nfeature: <slug>\nmode: <approved mode \u2014 batch | checkpoint | isolated>\n---\n```\n\nNew specs always start at `status: todo` (the canonical first state \u2014 see `docs/reference/spec-status-lifecycle.md`). The `mode:` value is the human-approved execution mode from the Execution Modes step above.\n\n**Owner resolution:** look up the owner name in this order \u2014 (1) `git config user.name`, (2) value in your auto-memory `joycraft-owner.txt` if present, (3) ask the user once and persist.\n\nUse this structure for the body:\n\n```markdown\n# [Verb + Object] \u2014 Atomic Spec\n\n> **Parent Brief:** `docs/features/<slug>/brief.md` (or "standalone")\n> **Status:** Ready\n> **Date:** YYYY-MM-DD\n> **Estimated scope:** [1 session / N files / ~N lines]\n\n---\n\n## What\nOne paragraph \u2014 what changes when this spec is done?\n\n## Why\nOne sentence \u2014 what breaks or is missing without this?\n\n## External API Contract\n\n_Include this section ONLY when the spec touches a third-party SDK, package, or service API. Omit it entirely otherwise._\n\n**Package:** `<npm-package-name>`\n\n**Canonical sources:**\n- <link to docs>\n- <link to types>\n\n**Key API facts (validated against vX.Y.Z):**\n- <fact 1>\n- <fact 2>\n\n\n## Acceptance Criteria\n- [ ] [Observable behavior]\n- [ ] Build passes\n- [ ] Tests pass\n\n## Test Plan\n\n| Acceptance Criterion | Test | Type |\n|---------------------|------|------|\n| [Each AC above] | [What to call/assert] | [unit/integration/e2e] |\n\n**Execution order:**\n1. Write all tests above \u2014 they should fail against current/stubbed code\n2. Run tests to confirm they fail (red)\n3. Implement until all tests pass (green)\n\n**Smoke test:** [Identify the fastest test for iteration feedback]\n\n**Before implementing, verify your test harness:**\n1. Run all tests \u2014 they must FAIL (if they pass, you\'re testing the wrong thing)\n2. Each test calls your actual function/endpoint \u2014 not a reimplementation or the underlying library\n3. Identify your smoke test \u2014 it must run in seconds, not minutes, so you get fast feedback on each change\n\n## Constraints\n- MUST: [hard requirement]\n- MUST NOT: [hard prohibition]\n\n## Affected Files\n| Action | File | What Changes |\n|--------|------|-------------|\n\n## Approach\nStrategy, data flow, key decisions. Name one rejected alternative.\n\n## Edge Cases\n| Scenario | Expected Behavior |\n|----------|------------------|\n```\n\nIf `docs/templates/ATOMIC_SPEC_TEMPLATE.md` exists, reference it for the full template with additional guidance.\n\nFill in all sections \u2014 each spec must be self-contained (no "see the brief for context"). Copy relevant constraints from the Feature Brief into each spec. Write acceptance criteria specific to THIS spec, not the whole feature. Every acceptance criterion must have at least one corresponding test in the Test Plan. If the user provided test strategy info from the interview, use it to choose test types and frameworks. Include the test harness verification rules in every Test Plan.\n\n### Step 5a: Write the Spec Queue Manifest\n\nAfter all spec `.md` files are written, create `.joycraft-spec-queue.json` in the specs directory alongside the spec files and README. This manifest is the machine-readable, authoritative spec queue consumed by the Pi pipeline automation.\n\n```json\n{\n  "feature": "<slug>",\n  "specs": [\n    { "id": 1, "file": "<spec-name>.md", "depends_on": [], "status": "todo", "mode": "batch" },\n    { "id": 2, "file": "<spec-name>.md", "depends_on": [1], "status": "todo", "mode": "checkpoint" }\n  ]\n}\n```\n\nMap each row in your decomposition table to a spec entry:\n- `id`: sequential integer starting from 1 (matches the decomposition table\'s # column)\n- `file`: the spec filename relative to the specs directory\n- `depends_on`: array of spec ids this spec depends on (empty array `[]` for no dependencies)\n- `status`: always `"todo"` initially \u2014 the agent advances each spec to `"in-review"` via `joycraft-spec-done`, and `joycraft-session-end` graduates it to `"done"` (see `docs/reference/spec-status-lifecycle.md`)\n- `mode`: the human-approved execution mode for this spec (`batch` | `checkpoint` | `isolated`) \u2014 must match the spec file\'s `mode:` frontmatter\n\nValidate: every id referenced in `depends_on` must exist as an `id` in the specs array; the queue `status`/`mode` for each spec must match that spec file\'s frontmatter.\n\n## Step 6: Recommend Execution Strategy and Update Parent Brief\n\nBased on the dependency graph, group specs into execution waves:\n- **Independent specs** \u2014 "These can run in parallel worktrees"\n- **Sequential specs** \u2014 "Execute these in order: 1 -> 2 -> 4"\n- **Mixed** \u2014 "Start specs 1 and 3 in parallel. After 1 completes, start 2."\n\n**Mark each multi-spec wave\'s parallel-safety.** A wave is **parallel-safe** only when its specs\' Affected Files tables are disjoint \u2014 no file appears in two of the wave\'s specs. Overlapping files \u2192 mark the wave NOT parallel-safe and name the overlapping files. Dependency order says what *may* run together; parallel-safety says what *won\'t conflict* when it does \u2014 `joycraft-implement-feature` only parallelizes waves you mark safe.\n\n**Update the parent brief\'s Execution Strategy section** at `docs/features/<slug>/brief.md` with this wave plan, so the brief stays a useful one-stop reference for feature reviewers.\n\n## Step 7: Write the Feature-Folder README.md (Single Source of Truth for Implementers)\n\nAfter generating per-spec files, ALSO write a `README.md` at the spec folder root: `docs/features/<slug>/specs/README.md` (for feature work). For area-level bugfixes, the path is `docs/bugfixes/<area>/README.md`.\n\nThe README is the single source of truth for *implementers*. It contains a **spec table** (one row per spec with dependencies) and the execution wave plan. Use this template:\n\n```markdown\n# <Feature Name> \u2014 Feature Specs\n\n> **Parent Brief:** `docs/features/<slug>/brief.md`\n> **Design:** `docs/features/<slug>/design.md` (when present)\n> **Research:** `docs/features/<slug>/research.md` (when present)\n> **Status:** Decomposed YYYY-MM-DD, ready for implementation\n\n## What this feature does\n\n<one paragraph summary, derived from the brief>\n\n## Specs\n\n| # | Spec | Depends On | Mode | Notes |\n|---|------|-----------|------|-------|\n| 1 | [spec-name.md](spec-name.md) | \u2014 | batch | <one-line description> |\n| 2 | [other-spec.md](other-spec.md) | 1 | checkpoint | <one-line description> |\n\n## Execution waves\n\n- Wave 1: specs ... \u2014 parallel-safe (Affected Files disjoint) | NOT parallel-safe (overlap: <files>)\n- Wave 2 (after wave 1): specs ... \u2014 sequential\n\nParallel-safe = the wave\'s specs touch disjoint Affected Files, so they may run as\nconcurrent subagents/worktrees. Waves without the marker run sequentially.\n\n## How to use this file\n\nRun the whole queue with `/joycraft-implement-feature docs/features/<slug>/` \u2014 it executes the specs in wave order (fresh-context subagent per spec) and finishes with session-end. Or run one spec at a time with `/joycraft-implement <spec-path>`; the implement skill reads this README first so it understands the spec\'s position in the wave plan, and continues through the queue itself. Each spec is self-contained for the actual implementation; this README provides ordering context only.\n```\n\nThe brief and the README serve different audiences: the brief is for *feature reviewers* (vision, scope, decomposition decisions); the README is for *implementers* (what to run next, what depends on what).\n\n## Step 8: Hand Off\n\nTell the user a one-line summary, then emit the canonical Handoff block.\n\n## Recommended Next Steps\n\nNext:\n```bash\n/joycraft-implement-feature docs/features/<slug>/\n```\nRun /clear first.\n\nThat one command runs the whole queue \u2014 fresh-context subagent per spec, wrap-up and commit after each, session-end once at the end. To drive one spec at a time instead: `/joycraft-implement docs/features/<slug>/specs/<first-spec>.md` (it wraps up and continues through the queue itself).\n',
-  "joycraft-design.md": '---\nname: joycraft-design\ndescription: Design discussion before decomposition \u2014 produce a ~200-line design artifact for human review, catching wrong assumptions before they propagate into specs\n---\n\n# Design Discussion\n\nYou are producing a design discussion document for a feature. This sits between research and decomposition \u2014 it captures your understanding so the human can catch wrong assumptions before specs are written.\n\n**Guard clause:** If no brief path is provided and no brief exists at `docs/features/<slug>/brief.md`, say:\n"No feature brief found. Run `/joycraft-new-feature` first to create one, or provide the path to your brief."\nThen stop.\n\n---\n\n## Step 1: Read Inputs\n\nRead the feature brief at the path the user provides. If the user also provides a research document path, read that too. Research is optional \u2014 if none exists, note that you\'ll explore the codebase directly.\n\n## Step 2: Explore the Codebase\n\nSpawn subagents to explore the codebase for patterns relevant to the brief. Focus on:\n\n- Files and functions that will be touched or extended\n- Existing patterns this feature should follow (naming, data flow, error handling)\n- Similar features already implemented that serve as models\n- Boundaries and interfaces the feature must integrate with\n\nGather file paths, function signatures, and code snippets. You need concrete evidence, not guesses.\n\n## Step 3: Write the Design Document\n\nDerive the slug from the brief path (`docs/features/<slug>/brief.md`).\nLazy-create the folder `docs/features/<slug>/` if needed.\nWrite the design document to `docs/features/<slug>/design.md`.\n\nThe file MUST start with YAML frontmatter \u2014 the 4-field personal schema:\n\n```yaml\n---\nstatus: active\nowner: <resolved name>\ncreated: YYYY-MM-DD\nfeature: <slug>\n---\n```\n\n**Owner resolution:** look up the owner name in this order \u2014 (1) `git config user.name`, (2) value in your auto-memory `joycraft-owner.txt` if present, (3) ask the user once and persist.\n\nThe document has exactly five sections:\n\n### Section 1: Current State\n\nWhat exists today in the codebase that is relevant to this feature. Include file paths, function signatures, and data flows. Be specific \u2014 reference actual code, not abstractions. If no research doc was provided, note that and describe what you found through direct exploration.\n\n### Section 2: Desired End State\n\nWhat the codebase should look like when this feature is complete. Describe the change at a high level \u2014 new files, modified interfaces, new data flows. Do NOT include implementation steps. This is the "what," not the "how."\n\n### Section 3: Patterns to Follow\n\nExisting patterns in the codebase that this feature should match. Include short code snippets and `file:line` references. Show the pattern, don\'t just name it.\n\nIf this is a greenfield project with no existing patterns, propose conventions and note that no precedent exists.\n\n### Section 4: Resolved Design Decisions\n\nDecisions you have already made, with brief rationale. Format each as:\n\n> **Decision:** [what you decided]\n> **Rationale:** [why, referencing existing code or constraints]\n> **Alternative rejected:** [what you considered and why you rejected it]\n\n### Section 5: Open Questions\n\nThings you don\'t know or where multiple valid approaches exist. Each question MUST present 2-3 concrete options with pros and cons. Format:\n\n> **Q: [question]**\n> - **Option A:** [description] \u2014 Pro: [benefit]. Con: [cost].\n> - **Option B:** [description] \u2014 Pro: [benefit]. Con: [cost].\n> - **Option C (if applicable):** [description] \u2014 Pro: [benefit]. Con: [cost].\n\nDo NOT ask vague questions like "what do you think?" Every question must have actionable options the human can choose from.\n\n### Update the Feature Brief\n\nAfter writing the design document, update the parent brief with a back-reference:\n1. Read `docs/features/<slug>/brief.md`\n2. In the header blockquote (the `>` lines at the top), add or update:\n   `> **Design:** docs/features/<slug>/design.md`\n3. If a `> **Design:**` line already exists, replace it \u2014 do NOT add a duplicate\n4. Write the brief back\n\n## Step 4: Present and STOP \u2014 Pre-Approval Hold\n\nPresent the design document to the user. Say:\n\n```\nDesign discussion written to docs/features/<slug>/design.md\n\nPlease review the document above. Specifically:\n1. Are the patterns in Section 3 the right ones to follow, or should I use different ones?\n2. Do you agree with the resolved decisions in Section 4?\n3. Pick an option for each open question in Section 5 (or propose your own).\n\nReply with your feedback. I will NOT proceed to decomposition until you have reviewed and approved this design.\n```\n\n**CRITICAL: Do NOT emit the canonical Handoff block at this point.** The Handoff block emits ONLY after human approval (see "Step 5: Hand Off (Post-Approval Only)" below). The entire value of this skill is the pause \u2014 it forces a human checkpoint before mistakes propagate.\n\n## Offer to Capture Deferred Items to Backlog\n\nIf during the design discussion the user mentions deferred work \u2014 "let\'s not do X yet," "save Y for later" \u2014 ASK before writing:\n\n> "This looks like deferred work \u2014 want me to capture it to `docs/backlog/`?"\n\nOnly on user confirmation, write a backlog entry at `docs/backlog/YYYY-MM-DD-<short-name>.md` with backlog frontmatter:\n\n```yaml\n---\nstatus: backlog\nowner: <resolved name>\ncreated: YYYY-MM-DD\nsource: docs/features/<slug>/brief.md\n---\n```\n\n**Never auto-write to `docs/backlog/`.** Every backlog entry is user-confirmed.\n\n## Step 5: Hand Off (Post-Approval Only)\n\nOnce the human approves the design:\n- Update the design document with their corrections and chosen options\n- Move answered questions from "Open Questions" to "Resolved Design Decisions"\n- Present the updated document for final confirmation\n- Once the user gives explicit approval, AND ONLY THEN, emit the canonical Handoff block:\n\n## Recommended Next Steps\n\nNext:\n```bash\n/joycraft-decompose docs/features/<slug>/brief.md\n```\nRun /clear first.\n\nInclude any backlog paths produced as a side effect.\n',
+  "joycraft-design.md": '---\nname: joycraft-design\ndescription: Design discussion before decomposition \u2014 produce a ~200-line design artifact for human review, catching wrong assumptions before they propagate into specs\n---\n\n# Design Discussion\n\nYou are producing a design discussion document for a feature. This sits between research and decomposition \u2014 it captures your understanding so the human can catch wrong assumptions before specs are written.\n\n**Guard clause:** If no brief path is provided and no brief exists at `docs/features/<slug>/brief.md`, say:\n"No feature brief found. Run `/joycraft-new-feature` first to create one, or provide the path to your brief."\nThen stop.\n\n---\n\n## Step 1: Read Inputs\n\nRead the feature brief at the path the user provides. If the user also provides a research document path, read that too. Research is optional \u2014 if none exists, note that you\'ll explore the codebase directly.\n\n## Step 2: Explore the Codebase\n\nSpawn subagents to explore the codebase for patterns relevant to the brief. Focus on:\n\n- Files and functions that will be touched or extended\n- Existing patterns this feature should follow (naming, data flow, error handling)\n- Similar features already implemented that serve as models\n- Boundaries and interfaces the feature must integrate with\n\nGather file paths, function signatures, and code snippets. You need concrete evidence, not guesses.\n\n## Step 3: Write the Design Document\n\nDerive the slug from the brief path (`docs/features/<slug>/brief.md`).\nLazy-create the folder `docs/features/<slug>/` if needed.\nWrite the design document to `docs/features/<slug>/design.md`.\n\nThe file MUST start with YAML frontmatter \u2014 the 4-field personal schema:\n\n```yaml\n---\nstatus: active\nowner: <resolved name>\ncreated: YYYY-MM-DD\nfeature: <slug>\n---\n```\n\n**Owner resolution:** look up the owner name in this order \u2014 (1) `git config user.name`, (2) value in your auto-memory `joycraft-owner.txt` if present, (3) ask the user once and persist.\n\nThe document has exactly five sections:\n\n### Section 1: Current State\n\nWhat exists today in the codebase that is relevant to this feature. Include file paths, function signatures, and data flows. Be specific \u2014 reference actual code, not abstractions. If no research doc was provided, note that and describe what you found through direct exploration.\n\n### Section 2: Desired End State\n\nWhat the codebase should look like when this feature is complete. Describe the change at a high level \u2014 new files, modified interfaces, new data flows. Do NOT include implementation steps. This is the "what," not the "how."\n\n### Section 3: Patterns to Follow\n\nExisting patterns in the codebase that this feature should match. Include short code snippets and `file:line` references. Show the pattern, don\'t just name it.\n\nIf this is a greenfield project with no existing patterns, propose conventions and note that no precedent exists.\n\n### Section 4: Resolved Design Decisions\n\nDecisions you have already made, with brief rationale. Format each as:\n\n> **Decision:** [what you decided]\n> **Rationale:** [why, referencing existing code or constraints]\n> **Alternative rejected:** [what you considered and why you rejected it]\n\n### Section 5: Open Questions\n\nThings you don\'t know or where multiple valid approaches exist. Each question MUST present 2-3 concrete options with pros and cons. Format:\n\n> **Q: [question]**\n> - **Option A:** [description] \u2014 Pro: [benefit]. Con: [cost].\n> - **Option B:** [description] \u2014 Pro: [benefit]. Con: [cost].\n> - **Option C (if applicable):** [description] \u2014 Pro: [benefit]. Con: [cost].\n\nDo NOT ask vague questions like "what do you think?" Every question must have actionable options the human can choose from.\n\n### Update the Feature Brief\n\nAfter writing the design document, update the parent brief with a back-reference:\n1. Read `docs/features/<slug>/brief.md`\n2. In the header blockquote (the `>` lines at the top), add or update:\n   `> **Design:** docs/features/<slug>/design.md`\n3. If a `> **Design:**` line already exists, replace it \u2014 do NOT add a duplicate\n4. Write the brief back\n\n## Step 4: Reconcile Brief with Findings\n\nYou\'ve just written `docs/features/<slug>/design.md`. Before hand-off, the parent brief at `docs/features/<slug>/brief.md` may now disagree with what you discovered. Re-read it and check each of these sections:\n\n| Brief section | What to look for |\n|---|---|\n| Vision | Did your findings refine or contradict the framing? |\n| Hard Constraints | Are any constraints now obsolete, missing, or refined? |\n| Out of Scope | Did your findings push something in or out of scope? |\n| Decomposition | Are spec counts, names, or dependencies still accurate? |\n| Test Strategy | Do your findings change what or how to test? |\n| Success Criteria | Are the criteria still observable and still match the goal? |\n\n**For each section, choose one:**\n\n- **Edit in place** \u2014 small, mechanical updates: line-number corrections, clarifications, additions consistent with brief intent. No user approval needed.\n- **Diff + stop** \u2014 non-trivial changes: counts flipping, decomposition restructure, scope changes, contradiction with original brief intent. Present a diff of the proposed change, STOP, and wait for user approval before continuing.\n\nIf you make changes, note them at the bottom of `design.md` under a "Brief updates" subsection. If the brief is already in sync, note: "Reconciliation checked, no changes required." If no parent brief exists (feature was described inline), note that and skip this step.\n\n**Why this step exists:** the silent-drift gap. Without reconciliation, the brief and downstream artifacts diverge \u2014 and later decomposition is sized against the stale brief. This feature ("single-source-skills") hit exactly this: brief said "11 clean / 9 dirty" until the research re-audit forced a re-decomposition. Don\'t let it happen again.\n\n## Step 5: Present and STOP \u2014 Pre-Approval Hold\n\nPresent the design document to the user. Say:\n\n```\nDesign discussion written to docs/features/<slug>/design.md\n\nPlease review the document above. Specifically:\n1. Are the patterns in Section 3 the right ones to follow, or should I use different ones?\n2. Do you agree with the resolved decisions in Section 4?\n3. Pick an option for each open question in Section 5 (or propose your own).\n\nReply with your feedback. I will NOT proceed to decomposition until you have reviewed and approved this design.\n```\n\n**CRITICAL: Do NOT emit the canonical Handoff block at this point.** The Handoff block emits ONLY after human approval (see "Step 6: Hand Off (Post-Approval Only)" below). The entire value of this skill is the pause \u2014 it forces a human checkpoint before mistakes propagate.\n\n## Offer to Capture Deferred Items to Backlog\n\nIf during the design discussion the user mentions deferred work \u2014 "let\'s not do X yet," "save Y for later" \u2014 ASK before writing:\n\n> "This looks like deferred work \u2014 want me to capture it to `docs/backlog/`?"\n\nOnly on user confirmation, write a backlog entry at `docs/backlog/YYYY-MM-DD-<short-name>.md` with backlog frontmatter:\n\n```yaml\n---\nstatus: backlog\nowner: <resolved name>\ncreated: YYYY-MM-DD\nsource: docs/features/<slug>/brief.md\n---\n```\n\n**Never auto-write to `docs/backlog/`.** Every backlog entry is user-confirmed.\n\n## Step 6: Hand Off (Post-Approval Only)\n\nOnce the human approves the design:\n- Update the design document with their corrections and chosen options\n- Move answered questions from "Open Questions" to "Resolved Design Decisions"\n- Present the updated document for final confirmation\n- Once the user gives explicit approval, AND ONLY THEN, emit the canonical Handoff block:\n\n## Recommended Next Steps\n\nNext:\n```bash\n/joycraft-decompose docs/features/<slug>/brief.md\n```\nRun /clear first.\n\nInclude any backlog paths produced as a side effect.\n',
   "joycraft-gather-context.md": "---\nname: joycraft-gather-context\ndescription: First-run onboarding pass that populates the project context layer -- read what context already exists, then offer a gap-only interview and batch-write the missing fact rows and long-form reference docs\ninstructions: 40\n---\n\n# Gather Context\n\nThis is the first-run **read-then-offer** onboarding pass \u2014 the lowest-intervention way to populate the project's context layer. You read what context already exists, summarize coverage, offer a gap-only interview, and write everything in one reviewable batch at the end.\n\nThis skill is self-contained. It composes the same conventions the single-doc skills use, but everything you need is inlined below \u2014 do not call into or import another skill's logic.\n\n## Step 1: Read What Already Exists First\n\nThe user has invoked the first-run onboarding pass (e.g., `/joycraft-gather-context`). Before asking the user anything, scan the project's existing context. Default scan breadth is **README + `docs/` + CLAUDE.md only**:\n\n- The README(s) at the repo root and any obvious sub-package READMEs.\n- `docs/**` \u2014 existing design, architecture, or style docs.\n- `docs/context/*` \u2014 the flat operational fact-docs (production-map, dangerous-assumptions, decision-log, institutional-knowledge, troubleshooting) and `docs/context/reference/*` long-form docs.\n- The current CLAUDE.md content, including any `## Context Map` section.\n\nThen summarize for the user what context already exists and what's covered.\n\n**Do NOT auto-run a code-inference scan.** Reading the actual source to infer architecture costs significantly more tokens. Offer that deeper/full review ONLY if the user explicitly asks for it, and when you do, note clearly that it costs more tokens. The default pass never reads the codebase to infer context.\n\n## Step 2: Offer a Gap-Only Interview (Don't Force)\n\nFrom the summary, identify genuine gaps: no design-system doc? no production map? no decision log? Offer an **optional** interview that targets only those gaps. The user can decline any or all of it \u2014 offer, never force.\n\n**Per-doc skip guard (not all-or-nothing):** Never re-interview for a doc that already has real content. Skip each doc that's already populated individually, and interview only the empty or missing ones. If everything is already covered, say so and offer nothing.\n\n## Step 3: Route by Shape (Inline Test)\n\nFor each thing the user wants to capture, apply this minimal shape test inline \u2014 do not defer to another skill:\n\n- **\"Could this be one row in a table?\"** \u2192 it's an **operational fact**. Route it to one of the five flat fact-docs under `docs/context/`:\n  - `docs/context/production-map.md` \u2014 infrastructure, services, environments, URLs, credentials, safe/unsafe to touch.\n  - `docs/context/dangerous-assumptions.md` \u2014 false assumptions an agent might make.\n  - `docs/context/decision-log.md` \u2014 an architectural/tooling choice and why.\n  - `docs/context/institutional-knowledge.md` \u2014 team conventions, unwritten rules, ownership.\n  - `docs/context/troubleshooting.md` \u2014 when X happens, do Y.\n  Append it as a table row (or list item for institutional-knowledge), removing any italic example rows in that table first.\n\n- **\"Does explaining it take paragraphs?\"** \u2192 it's **long-form reference**. Scaffold `docs/context/reference/<slug>.md` from the matching template in `docs/templates/context/reference/` (`design-system`, `frontend-methodology`, `backend`, `testing`, or the generic `reference-doc` fallback), lazy-creating `docs/context/reference/` on first write.\n\nIf an item is ambiguous, apply the test literally: one row \u2192 fact bucket; paragraphs \u2192 reference doc.\n\n## Step 4: Batch-Write + One Final Confirm\n\nDo NOT write per-answer. Collect ALL of the user's gap answers across the whole interview first. Then, in ONE batch:\n\n1. Write all the fact rows into their fact-docs.\n2. Scaffold and write all the reference docs into `docs/context/reference/`.\n3. Add or update the `## Context Map` pointer rows in CLAUDE.md \u2014 one row per reference doc, in the form `| docs/context/reference/<slug>.md | <when to read it> |`. Create the `## Context Map` section (header + two-column table) if it doesn't exist; update an existing row in place rather than duplicating it.\n\nPresent the full set of intended changes and get ONE final confirm (\"do it in one go\") before writing. If the user aborts at the final confirm, write nothing \u2014 there are no partial writes in this batch model. The result is one clean, reviewable diff.\n\n## Step 5: Confirm and Hand Off\n\nReport the batch: which fact rows were added, which reference docs were scaffolded, and which Context Map rows were created or updated. Then end with the canonical Handoff block.\n\n## Recommended Next Steps\n\nNext:\n```bash\n/joycraft-session-end\n```\nRun /clear first.\n",
   "joycraft-implement-feature.md": "---\nname: joycraft-implement-feature\ndescription: Run a feature's entire spec queue from one invocation \u2014 fresh-context subagent per spec, fail-fast, session-end once at the end\ninstructions: 24\n---\n\n# Implement Feature (Whole-Queue Driver)\n\nOne invocation runs a feature's whole spec queue: `/joycraft-implement-feature docs/features/<slug>/`. You are the **driver** \u2014 you orchestrate; you do **not** implement specs in this conversation. Each spec runs in a **fresh-context subagent**: the subagent boundary is the context isolation, the in-session equivalent of Pi's process-per-spec loop. This is ordinary interactive use of your harness \u2014 one human invocation, no headless loop, no ToS/cost caveat.\n\n## Step 1: Load the Queue\n\n1. Resolve the specs directory: if the given path contains a `specs/` subdirectory, use it; otherwise use the path itself. Look for `.joycraft-spec-queue.json` there.\n2. **No queue** \u2192 stop:\n\n   > No spec queue found in [path]. Run `/joycraft-decompose` first \u2014 it writes the queue, the specs, and the wave plan.\n\n3. Read the sibling `README.md` (the wave plan written by `/joycraft-decompose`) \u2014 it tells you the intended order and which waves, if any, are marked **parallel-safe**.\n4. Report the plan before starting: feature slug, M specs, current statuses, the order you'll run them in.\n5. If **no `todo` specs remain**, skip to Step 4 and say why (everything is already `in-review`/`done`).\n\n## Step 2: The Loop \u2014 One Subagent per Spec\n\nRepeat until no `todo` specs remain:\n\n1. **Find the next ready spec**: the first `todo` whose `depends_on` are all `in-review`/`done`. Use `.pi/scripts/joycraft/joycraft-next-spec <specs-dir>` if installed, else read the queue JSON directly.\n2. **None ready but `todo` specs remain** \u2192 fail-fast (Step 3): report which specs are blocked and on what. Never run a spec whose dependencies are unmet.\n3. **Spawn one subagent** for the spec, with a prompt of this shape (fill in the concrete paths \u2014 the subagent starts with zero context):\n\n   > Implement exactly one atomic spec: `<spec-path>`.\n   > 1. Read `.claude/skills/joycraft-implement/SKILL.md` and follow it for this spec \u2014 strict TDD (write the Test Plan's tests first, confirm they fail, implement until green), every Acceptance Criterion met. IMPORTANT: skip that skill's \"continue the queue\" step \u2014 you own exactly this one spec.\n   > 2. Then perform the per-spec wrap-up defined in `.claude/skills/joycraft-spec-done/SKILL.md`: bump the spec to `in-review` in BOTH `.joycraft-spec-queue.json` and the spec file's `status:` frontmatter; write a 2-line discovery stub at `docs/discoveries/` ONLY if something contradicted the spec; commit as `spec: <spec-name>`. Do NOT push, do NOT open a PR, do NOT run session-end, do NOT touch other specs.\n   > 3. Reply with: tests written and passing (counts), each Acceptance Criterion's status, the commit hash, and the discovery stub path if any. If you could not get tests green, say so explicitly and DO NOT bump the status or commit a broken state.\n\n4. **Verify, don't trust**: when the subagent returns, confirm in the queue JSON that the spec is `in-review` and in `git log` that the `spec: <name>` commit exists. Both present \u2192 continue the loop. Either missing, or the subagent reported failure \u2192 fail-fast (Step 3).\n\n**Sequential by default.** Run a wave's specs in parallel ONLY when both hold: the README marks that wave **parallel-safe** (disjoint Affected Files), AND the user asked for parallelism. Never parallelize an unmarked wave \u2014 concurrent edits to shared files produce exactly the conflicts the wave plan exists to prevent.\n\n## Step 3: Fail-Fast\n\nWhen a spec fails (tests not green, wrap-up missing, subagent reports failure, or all remaining specs are blocked):\n\n- **Stop the loop.** Start no further specs.\n- Report: which spec failed and why, what reached `in-review`, what remains `todo`. Leave the queue exactly as it is \u2014 never mark anything to cover a failure.\n- Suggest the recovery path: investigate in a fresh conversation with `/joycraft-implement <failed-spec>`, then re-run `/joycraft-implement-feature` to finish the remainder.\n\n## Step 4: Finish \u2014 Session-End Once\n\nWhen no `todo` specs remain, run the once-per-feature finisher yourself, in this conversation: invoke `/joycraft-session-end` (or read and follow `.claude/skills/joycraft-session-end/SKILL.md`). It owns the gates the loop deliberately skipped: full validation (must pass before anything graduates `in-review \u2192 done`), discovery consolidation, and push/PR per the project's CLAUDE.md git autonomy rules.\n\n## Final Report\n\n```\nFeature run: <slug>\n- Specs completed: N of M (now in-review/done) \xB7 failures: [none | <spec> \u2014 <reason>]\n- Session-end: [ran \u2014 see its report | skipped: <reason>]\n- Discoveries: [n stubs consolidated | none]\n```\n",
   "joycraft-implement-level5.md": "---\nname: joycraft-implement-level5\ndescription: Set up Level 5 autonomous development \u2014 autofix loop, holdout scenario testing, and scenario evolution from specs\ninstructions: 35\n---\n\n# Implement Level 5 \u2014 Autonomous Development Loop\n\nYou are guiding the user through setting up Level 5: the autonomous feedback loop where specs go in, validated software comes out. This is a one-time setup that installs workflows, creates a scenarios repo, and configures the autofix loop.\n\n## Before You Begin\n\nCheck prerequisites:\n\n1. **Project must be initialized.** Look for `.claude/.joycraft/state.json` (older installs may still have a legacy `.joycraft-version` at the repo root). If neither exists, tell the user to run `npx joycraft init` first.\n2. **Project should be at Level 4.** Check `docs/joycraft-assessment.md` if it exists. If the project hasn't been assessed yet, suggest running `/joycraft-tune` first. But don't block \u2014 the user may know they're ready.\n3. **Git repo with GitHub remote.** This setup requires GitHub Actions. Check for `.git/` and a GitHub remote.\n\nIf prerequisites aren't met, explain what's needed and stop.\n\n## Step 1: Explain What Level 5 Means\n\nTell the user:\n\n> Level 5 is the autonomous loop. When you push specs, three things happen automatically:\n>\n> 1. **Scenario evolution** \u2014 A separate AI agent reads your specs and writes holdout tests in a private scenarios repo. These tests are invisible to your coding agent.\n> 2. **Autofix** \u2014 When CI fails on a PR, Claude Code automatically attempts a fix (up to 3 times).\n> 3. **Holdout validation** \u2014 When CI passes, your scenarios repo runs behavioral tests against the PR. Results post as PR comments.\n>\n> The key insight: your coding agent never sees the scenario tests. This prevents it from gaming the test suite \u2014 like a validation set in machine learning.\n\n## Step 2: Gather Configuration\n\nAsk these questions **one at a time**:\n\n### Question 1: Scenarios repo name\n\n> What should we call your scenarios repo? It'll be a private repo that holds your holdout tests.\n>\n> Default: `{current-repo-name}-scenarios`\n\nAccept the default or the user's choice.\n\n### Question 2: GitHub App\n\n> Level 5 needs a GitHub App to provide a separate identity for autofix pushes (this avoids GitHub's anti-recursion protection). Creating one takes about 2 minutes:\n>\n> 1. Go to https://github.com/settings/apps/new\n> 2. Give it a name (e.g., \"My Project Autofix\")\n> 3. Uncheck \"Webhook > Active\" (not needed)\n> 4. Under **Repository permissions**, set:\n>    - **Contents**: Read & Write\n>    - **Pull requests**: Read & Write\n>    - **Actions**: Read & Write\n> 5. Click **Create GitHub App**\n> 6. Note the **App ID** from the settings page\n> 7. Scroll to **Private keys** > click **Generate a private key** > save the `.pem` file\n> 8. Click **Install App** in the left sidebar > install it on your repo\n>\n> What's your App ID?\n\n## Step 3: Run init-autofix\n\nRun the CLI command with the gathered configuration:\n\n```bash\nnpx joycraft init-autofix --scenarios-repo {name} --app-id {id}\n```\n\nReview the output with the user. Confirm files were created.\n\n## Step 4: Walk Through Secret Configuration\n\nGuide the user step by step:\n\n### 4a: Add Secrets to Main Repo\n\n> You should already have the `.pem` file from when you created the app in Step 2.\n\n> Go to your repo's Settings > Secrets and variables > Actions, and add:\n> - `JOYCRAFT_APP_PRIVATE_KEY` \u2014 paste the contents of your `.pem` file\n> - `ANTHROPIC_API_KEY` \u2014 your Anthropic API key\n\n### 4b: Create the Scenarios Repo\n\n> Create the private scenarios repo:\n> ```bash\n> gh repo create {scenarios-repo-name} --private\n> ```\n>\n> Then copy the scenario templates into it:\n> ```bash\n> cp -r docs/templates/scenarios/* ../{scenarios-repo-name}/\n> cd ../{scenarios-repo-name}\n> git add -A && git commit -m \"init: scaffold scenarios repo from Joycraft\"\n> git push\n> ```\n\n### 4c: Add Secrets to Scenarios Repo\n\n> The scenarios repo also needs the App private key:\n> - `JOYCRAFT_APP_PRIVATE_KEY` \u2014 same `.pem` file as the main repo\n> - `ANTHROPIC_API_KEY` \u2014 same key (needed for scenario generation)\n\n## Step 5: Verify Setup\n\nHelp the user verify everything is wired correctly:\n\n1. **Check workflow files exist:** `ls .github/workflows/autofix.yml .github/workflows/scenarios-dispatch.yml .github/workflows/spec-dispatch.yml .github/workflows/scenarios-rerun.yml`\n2. **Check scenario templates were copied:** Verify the scenarios repo has `example-scenario.test.ts`, `workflows/run.yml`, `workflows/generate.yml`, `prompts/scenario-agent.md`\n3. **Check the App ID is correct** in the workflow files (not still a placeholder)\n\n## Step 6: Update CLAUDE.md\n\nIf the project's CLAUDE.md doesn't already have an \"External Validation\" section, add one:\n\n> ## External Validation\n>\n> This project uses holdout scenario tests in a separate private repo.\n>\n> ### NEVER\n> - Access, read, or reference the scenarios repo\n> - Mention scenario test names or contents\n> - Modify the scenarios dispatch workflow to leak test information\n>\n> The scenarios repo is deliberately invisible to you. This is the holdout guarantee.\n\n## Step 7: First Test (Optional)\n\nIf the user wants to test the loop:\n\n> Want to do a quick test? Here's how:\n>\n> 1. Write a simple spec in `docs/features/<slug>/specs/` and push to main \u2014 this triggers scenario generation\n> 2. Create a PR with a small change \u2014 when CI passes, scenarios will run\n> 3. Watch for the scenario test results as a PR comment\n>\n> Or deliberately break something in a PR to test the autofix loop.\n\n## Step 8: Summary\n\nPrint a summary of what was set up:\n\n> **Level 5 is live.** Here's what's running:\n>\n> | Trigger | What Happens |\n> |---------|-------------|\n> | Push specs to `docs/features/<slug>/specs/` | Scenario agent writes holdout tests |\n> | PR fails CI | Claude autofix attempts (up to 3x) |\n> | PR passes CI | Holdout scenarios run against PR |\n> | Scenarios update | Open PRs re-tested with latest scenarios |\n>\n> Your scenarios repo: `{name}`\n> Your coding agent cannot see those tests. The holdout wall is intact.\n\n**Important:** Tell the user:\n\n> **Before you can test the loop**, you need to merge this PR to main first. GitHub's `workflow_run` triggers only activate for workflows that exist on the default branch. Once merged, create a new PR with any small change \u2014 that's when you'll see Autofix, Scenarios Dispatch, and Spec Dispatch fire for the first time.\n\nUpdate `docs/joycraft-assessment.md` if it exists \u2014 set the Level 5 score to reflect the new setup.\n",
@@ -15,8 +15,8 @@ var SKILLS = {
   "joycraft-interview.md": '---\nname: joycraft-interview\ndescription: Brainstorm freely about what you want to build \u2014 yap, explore ideas, and get a structured summary you can use later\ninstructions: 18\n---\n\n# Interview \u2014 Idea Exploration\n\nYou are helping the user brainstorm and explore what they want to build. This is a lightweight, low-pressure conversation \u2014 not a formal spec process. Let them yap.\n\n## How to Run the Interview\n\n### 1. Open the Floor\n\nStart with something like:\n"What are you thinking about building? Just talk \u2014 I\'ll listen and ask questions as we go."\n\nLet the user talk freely. Do not interrupt their flow. Do not push toward structure yet.\n\n### 2. Ask Clarifying Questions\n\nAs they talk, weave in questions naturally \u2014 don\'t fire them all at once:\n\n- **What problem does this solve?** Who feels the pain today?\n- **What does "done" look like?** If this worked perfectly, what would a user see?\n- **What are the constraints?** Time, tech, team, budget \u2014 what boxes are we in?\n- **What\'s NOT in scope?** What\'s tempting but should be deferred?\n- **What are the edge cases?** What could go wrong? What\'s the weird input?\n- **What exists already?** Are we building on something or starting fresh?\n\n### 3. Play Back Understanding\n\nAfter the user has gotten their ideas out, reflect back:\n"So if I\'m hearing you right, you want to [summary]. The core problem is [X], and done looks like [Y]. Is that right?"\n\nLet them correct and refine. Iterate until they say "yes, that\'s it."\n\n### 4. Write a Draft Brief\n\nDerive a slug `YYYY-MM-DD-<topic>` (today\'s date + kebab-case topic \u2014 no `-draft` suffix).\nCreate a draft file at `docs/features/<slug>/brief.md`. Lazy-create `docs/features/<slug>/` if it doesn\'t exist.\n\nThe file MUST start with YAML frontmatter \u2014 the 4-field personal schema with `status: draft`:\n\n```yaml\n---\nstatus: draft\nowner: <resolved name>\ncreated: YYYY-MM-DD\nfeature: <slug>\n---\n```\n\n**Owner resolution:** look up the owner name in this order \u2014 (1) `git config user.name`, (2) value in your auto-memory `joycraft-owner.txt` if present, (3) ask the user once and persist. If you can\'t get a name, leave the field as `<resolved name>` and note it for the user.\n\nUse this format for the body:\n\n```markdown\n# [Topic] \u2014 Draft Brief\n\n> **Date:** YYYY-MM-DD\n> **Origin:** /joycraft-interview session\n\n---\n\n## The Idea\n[2-3 paragraphs capturing what the user described \u2014 their words, their framing]\n\n## Problem\n[What pain or gap this addresses]\n\n## What "Done" Looks Like\n[The user\'s description of success \u2014 observable outcomes]\n\n## Constraints\n- [constraint 1]\n- [constraint 2]\n\n## Open Questions\n- [things that came up but weren\'t resolved]\n- [decisions that need more thought]\n\n## Out of Scope (for now)\n- [things explicitly deferred \u2014 see also: deferred work goes to `docs/backlog/`]\n\n## Raw Notes\n[Any additional context, quotes, or tangents worth preserving]\n```\n\n### 5. Offer to Capture Deferred Items to Backlog\n\nIf during the conversation deferred work surfaces (a tangent, a "later" item, a "out-of-scope but tempting" idea), ASK the user:\n\n> "This looks like deferred work \u2014 want me to capture it to `docs/backlog/`?"\n\nOnly on user confirmation, write a backlog entry at `docs/backlog/YYYY-MM-DD-<short-name>.md` with backlog frontmatter:\n\n```yaml\n---\nstatus: backlog\nowner: <resolved name>\ncreated: YYYY-MM-DD\nsource: docs/features/<slug>/brief.md\n---\n```\n\n**Never auto-write to `docs/backlog/`.** Every backlog entry is user-confirmed.\n\n### 6. Hand Off\n\nAfter writing the draft (and any backlog entries), present the canonical Handoff block.\nInclude any backlog paths produced as a side effect.\n\n## Recommended Next Steps\n\nNext:\n```bash\n/joycraft-new-feature docs/features/<slug>/brief.md\n```\nRun /clear first.\n\nIf the idea sounds complex \u2014 touches many files, involves architectural decisions, or the user is working in an unfamiliar area \u2014 nudge them toward research and design (e.g., `/joycraft-research` then `/joycraft-design`). But present it as a recommendation, not a gate.\n\n## Guidelines\n\n- **This is NOT /joycraft-new-feature.** Do not push toward formal briefs, decomposition tables, or atomic specs. The point is exploration.\n- **Let the user lead.** Your job is to listen, clarify, and capture \u2014 not to structure or direct.\n- **Mark everything as DRAFT.** The output is a starting point, not a commitment.\n- **Keep it short.** The draft brief should be 1-2 pages max. Capture the essence, not every detail.\n- **Multiple interviews are fine.** The user might run this several times as their thinking evolves. Each creates a new dated draft.\n',
   "joycraft-lockdown.md": "---\nname: joycraft-lockdown\ndescription: Generate constrained execution boundaries for an implementation session -- NEVER rules and deny patterns to prevent agent overreach\ninstructions: 28\n---\n\n# Lockdown Mode\n\nThe user wants to constrain agent behavior for an implementation session. Your job is to interview them about what should be off-limits, then generate CLAUDE.md NEVER rules and `.claude/settings.json` deny patterns they can review and apply.\n\n## When Is Lockdown Useful?\n\nLockdown is most valuable for:\n- **Complex tech stacks** (hardware, firmware, multi-device) where agents can cause real damage\n- **Long-running autonomous sessions** where you won't be monitoring every action\n- **Production-adjacent work** where accidental network calls or package installs are risky\n\nFor simple feature work on a well-tested codebase, lockdown is usually overkill. Mention this context to the user so they can decide.\n\n## Step 1: Check for Tests\n\nBefore starting the interview, check if the project has test files or directories (look for `tests/`, `test/`, `__tests__/`, `spec/`, or files matching `*.test.*`, `*.spec.*`).\n\nIf no tests are found, tell the user:\n\n> Lockdown mode is most useful when you already have tests in place -- it prevents the agent from modifying them while constraining behavior to writing code and running tests. Consider running `/joycraft-new-feature` first to set up a test-driven workflow, then come back to lock it down.\n\nIf the user wants to proceed anyway, continue with the interview.\n\n## Step 2: Interview -- What to Lock Down\n\nAsk these three questions, one at a time. Wait for the user's response before proceeding to the next question.\n\n### Question 1: Read-Only Files\n\n> What test files or directories should be off-limits for editing? (e.g., `tests/`, `__tests__/`, `spec/`, specific test files)\n>\n> I'll generate NEVER rules to prevent editing these.\n\nIf the user isn't sure, suggest the test directories you found in Step 1.\n\n### Question 2: Allowed Commands\n\n> What commands should the agent be allowed to run? Defaults:\n> - Write and edit source code files\n> - Run the project's smoke test command\n> - Run the full test suite\n>\n> Any other commands to explicitly allow? Or should I restrict to just these?\n\n### Question 3: Denied Commands\n\n> What commands should be denied? Defaults:\n> - Package installs (`npm install`, `pip install`, `cargo add`, `go get`, etc.)\n> - Network tools (`curl`, `wget`, `ping`, `ssh`)\n> - Direct log file reading\n>\n> Any specific commands to add or remove from this list?\n\n**Edge case -- user wants to allow some network access:** If the user mentions API tests or specific endpoints that need network access, exclude those from the deny list and note the exception in the output.\n\n**Edge case -- user wants to lock down file writes:** If the user wants to prevent ALL file writes, warn them:\n\n> Denying all file writes would prevent the agent from doing any work. I recommend keeping source code writes allowed and only locking down test files, config files, or other sensitive directories.\n\n## Step 3: Generate Boundaries\n\nBased on the interview responses, generate output in this exact format:\n\n```\n## Lockdown boundaries generated\n\nReview these suggestions and add them to your project:\n\n### CLAUDE.md -- add to NEVER section:\n\n- Edit any file in `[user's test directories]`\n- Run `[denied package manager commands]`\n- Use `[denied network tools]`\n- Read log files directly -- interact with logs only through test assertions\n- [Any additional NEVER rules based on user responses]\n\n### .claude/settings.json -- suggested deny patterns:\n\nAdd these to the `permissions.deny` array:\n\n[\"[command1]\", \"[command2]\", \"[command3]\"]\n\n---\n\nCopy these into your project manually, or tell me to apply them now (I'll show you the exact changes for approval first).\n```\n\nAdjust the content based on the actual interview responses:\n- Only include deny patterns for commands the user confirmed should be denied\n- Only include NEVER rules for directories/files the user specified\n- If the user allowed certain network tools or package managers, exclude those\n\n## Recommended Permission Mode\n\nAfter generating the boundaries above, also recommend a Claude Code permission mode. Include this section in your output:\n\n```\n### Recommended Permission Mode\n\nYou don't need `--dangerously-skip-permissions`. Safer alternatives exist:\n\n| Your situation | Use | Why |\n|---|---|---|\n| Autonomous spec execution | `--permission-mode dontAsk` + allowlist above | Only pre-approved commands run |\n| Long session with some trust | `--permission-mode auto` | Safety classifier reviews each action |\n| Interactive development | `--permission-mode acceptEdits` | Auto-approves file edits, prompts for commands |\n\n**For lockdown mode, we recommend `--permission-mode dontAsk`** combined with the deny patterns above. This gives you full autonomy for allowed operations while blocking everything else -- no classifier overhead, no prompts, and no safety bypass.\n\n`--dangerously-skip-permissions` disables ALL safety checks. The modes above give you autonomy without removing the guardrails.\n```\n\n## Step 4: Offer to Apply\n\nIf the user asks you to apply the changes:\n\n1. **For CLAUDE.md:** Read the existing CLAUDE.md, find the Behavioral Boundaries section, and show the user the exact diff for the NEVER section. Ask for confirmation before writing.\n2. **For settings.json:** Read the existing `.claude/settings.json`, show the user what the `permissions.deny` array will look like after adding the new patterns. Ask for confirmation before writing.\n\n**Never auto-apply. Always show the exact changes and wait for explicit approval.**\n",
   "joycraft-new-feature.md": '---\nname: joycraft-new-feature\ndescription: Guided feature development \u2014 interview the user, produce a Feature Brief, then decompose into atomic specs\ninstructions: 35\n---\n\n# New Feature Workflow\n\nYou are starting a new feature. Follow this process in order. Do not skip steps.\n\n## Phase 0: Check for Existing Drafts and In-Flight Features\n\nBefore starting the interview, scan `docs/features/` for existing artifacts the user may want to continue from.\n\n**Skip this phase if:** the user provided a brief path as an argument (they already know what to work from).\n\n**Steps:**\n1. Check if `docs/features/` exists. If not, skip to Phase 1.\n2. List subdirectories. For each `docs/features/<slug>/brief.md`, read the YAML frontmatter at the top.\n3. **Filter by status:** treat each brief as `status: active` unless its frontmatter says otherwise. **Skip** any brief whose `status:` is `shipped`, `deprecated`, or `superseded`. Also skip anything under `docs/archive/` \u2014 those are out-of-scope for new feature work.\n4. Group what you find:\n   - **Drafts** (frontmatter `status: draft`) \u2014 likely from `/joycraft-interview`.\n   - **Active in-flight** (frontmatter `status: active`) \u2014 work the user already started.\n\n5. Present them:\n\n```\nI found existing artifacts in docs/features/:\n\nDrafts:\n- docs/features/<slug>/brief.md (drafted YYYY-MM-DD)\n\nActive features:\n- docs/features/<slug>/brief.md (started YYYY-MM-DD)\n\nWant me to:\n1. **Formalize** a draft into a full Feature Brief\n2. **Continue** an active feature\n3. **Start a new interview** from scratch\n```\n\n6. If user picks formalize/continue: read the full brief, extract context, and jump to Phase 2 with that context pre-filled.\n7. If user picks start fresh, or nothing found: proceed to Phase 1.\n\n## Phase 1: Interview\n\nInterview the user about what they want to build. Let them talk \u2014 your job is to listen, then sharpen.\n\n**Ask about:**\n- What problem does this solve? Who is affected?\n- What does "done" look like?\n- Hard constraints? (business rules, tech limitations, deadlines)\n- What is explicitly NOT in scope? (push hard on this)\n- Edge cases or error conditions?\n- What existing code/patterns should this follow?\n- Testing: existing setup? framework? smoke test budget? lockdown mode desired?\n\n**Interview technique:**\n- Let the user "yap" \u2014 don\'t interrupt their flow\n- Play back your understanding: "So if I\'m hearing you right..."\n- Push toward testable statements: "How would we verify that works?"\n\nKeep asking until you can fill out a Feature Brief.\n\n## Phase 2: Feature Brief\n\nDerive a slug `YYYY-MM-DD-<feature-name>` (today\'s date + kebab-case feature name).\nWrite the Feature Brief to `docs/features/<slug>/brief.md`. Lazy-create the folder if needed.\n\n**Slug derivation:** today\'s date in `YYYY-MM-DD` format, then `-`, then the feature name lower-cased and hyphen-separated. Example: a feature about "Token Discipline" started on 2026-04-06 \u2192 slug `2026-04-06-token-discipline` \u2192 folder `docs/features/2026-04-06-token-discipline/`.\n\n**Why:** The brief is the single source of truth for what we\'re building. It prevents scope creep and gives every spec a shared reference point.\n\nThe brief MUST start with YAML frontmatter \u2014 the 4-field personal schema:\n\n```yaml\n---\nstatus: active\nowner: <resolved name>\ncreated: YYYY-MM-DD\nfeature: <slug>\n---\n```\n\n**Owner resolution:** look up the owner name in this order \u2014 (1) `git config user.name`, (2) value in your auto-memory `joycraft-owner.txt` if present, (3) ask the user once and persist. If you can\'t get a name, leave the field as `<resolved name>` and note it for the user.\n\nIf the brief was formalized from an existing draft, parse the existing draft\'s frontmatter and update `status:` from `draft` to `active`. Never silently overwrite \u2014 if the draft already has body content, preserve it and append/refine rather than replacing.\n\nUse this structure for the body:\n\n```markdown\n# [Feature Name] \u2014 Feature Brief\n\n> **Date:** YYYY-MM-DD\n> **Project:** [project name]\n\n---\n\n## Vision\nWhat are we building and why? The full picture in 2-4 paragraphs.\n\n## User Stories\n- As a [role], I want [capability] so that [benefit]\n\n## Hard Constraints\n- MUST: [constraint that every spec must respect]\n- MUST NOT: [prohibition that every spec must respect]\n\n## Out of Scope\n- NOT: [tempting but deferred]\n\n## Test Strategy\n- **Existing setup:** [framework and tools, or "none yet"]\n- **User expertise:** [comfortable / learning / needs guidance]\n- **Test types:** [smoke, unit, integration, e2e, etc.]\n- **Smoke test budget:** [target time for fast-feedback tests]\n- **Lockdown mode:** [yes/no \u2014 constrain agent to code + tests only]\n\n## Decomposition\n| # | Spec Name | Description | Dependencies | Est. Size |\n|---|-----------|-------------|--------------|-----------|\n| 1 | [verb-object] | [one sentence] | None | [S/M/L] |\n\n## Execution Strategy\n- [ ] Sequential (specs have chain dependencies)\n- [ ] Parallel worktrees (specs are independent)\n- [ ] Mixed\n\n## Success Criteria\n- [ ] [End-to-end behavior 1]\n- [ ] [No regressions in existing features]\n```\n\nIf `docs/templates/FEATURE_BRIEF_TEMPLATE.md` exists, reference it for the full template with additional guidance.\n\nPresent the brief to the user. Focus review on:\n- "Does the decomposition match how you think about this?"\n- "Is anything in scope that shouldn\'t be?"\n- "Are the specs small enough? Can each be described in one sentence?"\n\nIterate until approved.\n\n## Phase 3: Generate Atomic Specs\n\nFor each row in the decomposition table, create a self-contained spec file at `docs/features/<slug>/specs/<spec-name>.md`. Lazy-create the `specs/` subfolder if it doesn\'t exist.\n\n**Why:** Each spec must be understandable WITHOUT reading the Feature Brief. This prevents the "Curse of Instructions" \u2014 no spec should require holding the entire feature in context. Copy relevant context into each spec.\n\nEach spec file MUST start with YAML frontmatter \u2014 the 4-field personal schema:\n\n```yaml\n---\nstatus: active\nowner: <resolved name>\ncreated: YYYY-MM-DD\nfeature: <slug>\n---\n```\n\nWhen listing existing in-flight features in Phase 0, ignore briefs whose `status:` is `shipped`, `deprecated`, or `superseded`. Also ignore anything under `docs/archive/`.\n\nIf `docs/backlog/` items surface during the interview as "deferred work" candidates, ask the user before writing \u2014 never auto-write to `docs/backlog/`.\n\nUse this structure for each spec body:\n\n```markdown\n# [Verb + Object] \u2014 Atomic Spec\n\n> **Parent Brief:** `docs/features/<slug>/brief.md`\n> **Status:** Ready\n> **Date:** YYYY-MM-DD\n> **Estimated scope:** [1 session / N files / ~N lines]\n\n---\n\n## What\nOne paragraph \u2014 what changes when this spec is done?\n\n## Why\nOne sentence \u2014 what breaks or is missing without this?\n\n## Acceptance Criteria\n- [ ] [Observable behavior]\n- [ ] Build passes\n- [ ] Tests pass\n\n## Test Plan\n\n| Acceptance Criterion | Test | Type |\n|---------------------|------|------|\n| [Each AC above] | [What to call/assert] | [unit/integration/e2e] |\n\n**Execution order:**\n1. Write all tests above \u2014 they should fail against current/stubbed code\n2. Run tests to confirm they fail (red)\n3. Implement until all tests pass (green)\n\n**Smoke test:** [Identify the fastest test for iteration feedback]\n\n**Before implementing, verify your test harness:**\n1. Run all tests \u2014 they must FAIL (if they pass, you\'re testing the wrong thing)\n2. Each test calls your actual function/endpoint \u2014 not a reimplementation or the underlying library\n3. Identify your smoke test \u2014 it must run in seconds, not minutes, so you get fast feedback on each change\n\n## Constraints\n- MUST: [hard requirement]\n- MUST NOT: [hard prohibition]\n\n## Affected Files\n| Action | File | What Changes |\n|--------|------|-------------|\n\n## Approach\nStrategy, data flow, key decisions. Name one rejected alternative.\n\n## Edge Cases\n| Scenario | Expected Behavior |\n|----------|------------------|\n```\n\nIf `docs/templates/ATOMIC_SPEC_TEMPLATE.md` exists, reference it for the full template with additional guidance.\n\n## Phase 3.5: Offer to Capture Deferred Items to Backlog\n\nIf during the interview deferred work surfaces (out-of-scope items, "later" features, tangents), ASK the user:\n\n> "This looks like deferred work \u2014 want me to capture it to `docs/backlog/`?"\n\nOnly on user confirmation, write a backlog entry at `docs/backlog/YYYY-MM-DD-<short-name>.md` with backlog frontmatter:\n\n```yaml\n---\nstatus: backlog\nowner: <resolved name>\ncreated: YYYY-MM-DD\nsource: docs/features/<slug>/brief.md\n---\n```\n\n**Never auto-write to `docs/backlog/`.** Every backlog entry is user-confirmed.\n\n## Phase 4: Hand Off for Execution\n\nBefore jumping to execution, consider whether research or design would catch wrong assumptions early:\n\n```\nFeature Brief and [N] atomic specs are ready.\n\nSpecs:\n1. [spec-name] \u2014 [one sentence] [S/M/L]\n2. [spec-name] \u2014 [one sentence] [S/M/L]\n...\n\nBefore executing, consider the complexity of this feature:\n\nCOMPLEX (5+ files, architectural decisions, unfamiliar area):\n  \u2192 /joycraft-research \u2014 gather codebase facts before committing to a design\n  \u2192 /joycraft-design \u2014 make architectural decisions explicit\n  \u2192 Then execute specs\n\nMEDIUM (clear scope but non-trivial):\n  \u2192 /joycraft-design \u2014 make key decisions explicit before building\n  \u2192 Then execute specs\n\nSIMPLE (scope is clear, < 5 files, well-understood area):\n  \u2192 Skip to execution\n\nRecommended execution:\n- [Parallel/Sequential/Mixed strategy]\n- Estimated: [N] sessions total\n\nTo execute: Start a fresh session per spec. Each session should:\n1. Read the spec\n2. Implement\n3. Run /joycraft-session-end to capture discoveries\n4. Commit and PR\n\nReady to start?\n```\n\nEnd with the canonical Handoff block. Include any backlog paths produced as a side effect.\n\n## Recommended Next Steps\n\nNext:\n```bash\n/joycraft-decompose docs/features/<slug>/brief.md\n```\nRun /clear first.\n\n**Why:** A fresh session for execution produces better results. The interview session has too much context noise \u2014 a clean session with just the spec is more focused. Research and design catch wrong assumptions before they propagate into specs \u2014 but skip them if the scope is clear and well-understood.\n\nYou can also use `/joycraft-decompose` to re-decompose a brief if the breakdown needs adjustment, or run `/joycraft-interview` first for a lighter brainstorm before committing to the full workflow.\n',
-  "joycraft-optimize.md": '---\nname: joycraft-optimize\ndescription: Audit your Claude Code or Codex session overhead \u2014 harness file sizes, plugins, MCP servers, hooks \u2014 and report actionable recommendations\ninstructions: 20\n---\n\n# Optimize \u2014 Session Overhead Audit\n\nYou are auditing the user\'s AI development session for token overhead. Produce a conversational diagnostic report \u2014 no files created.\n\n## Step 1: Detect Platform\n\nCheck which platform is active:\n- **Claude Code:** Look for `.claude/` directory, `CLAUDE.md`\n- **Codex:** Look for `.agents/` directory, `AGENTS.md`\n\nIf both exist, run both checks. If neither, default to Claude Code checks and note the uncertainty.\n\n## Step 2: Audit Harness Files\n\n### Claude Code Path\n\n1. **CLAUDE.md** \u2014 count lines. Threshold: \u2264200 lines.\n2. **Skill files** \u2014 glob `.claude/skills/**/*.md`. Count lines per file. Threshold: \u2264200 lines each.\n\n### Codex Path\n\n1. **AGENTS.md** \u2014 count lines. Threshold: \u2264200 lines.\n2. **Skill files** \u2014 glob `.agents/skills/**/*.md`. Count lines per file. Threshold: \u2264200 lines each.\n\n## Step 3: Audit Plugins & MCP Servers\n\n### Claude Code Path\n\n1. **Installed plugins** \u2014 read `~/.claude/plugins/installed_plugins.json`. List plugin names and versions. If not found, report "no plugins file found."\n2. **Enabled plugins** \u2014 read `~/.claude/settings.json`, check `enabledPlugins` array. Show enabled vs installed count.\n3. **MCP servers** \u2014 read `~/.claude/settings.json`, count entries under `mcpServers`. List server names.\n\n### Codex Path\n\n1. **Plugin config** \u2014 read `~/.codex/config.toml`. List any plugin toggles. Note: Codex syncs its curated plugin marketplace at startup \u2014 this is a boot cost even if you don\'t use them.\n2. **MCP servers** \u2014 check `~/.codex/config.toml` for MCP server entries. List server names.\n\n## Step 4: Audit Hooks (Claude Code Only)\n\nRead `.claude/settings.json` in the project directory. List all hook definitions under the `hooks` key \u2014 show the event name and command for each.\n\nFor Codex: note "hook auditing not yet supported on Codex."\n\n## Step 5: Report\n\nOrganize findings by category. Use pass/warn indicators:\n\n```\n## Session Overhead Report\n\n### Harness Files\n- CLAUDE.md: [N] lines [PASS \u2264200 / WARN >200]\n- Skills: [N] files, [list any over 200 lines]\n\n### Plugins\n- Installed: [N] ([list names])\n- Enabled: [N] of [M] installed\n- [If 0: "No plugins \u2014 zero boot cost from plugins."]\n\n### MCP Servers\n- Count: [N] ([list names])\n- [If 0: "No MCP servers \u2014 zero boot cost from servers."]\n\n### Hooks\n- [N] hook definitions ([list event names])\n\n### Recommendations\n- [Specific, actionable items for anything over threshold]\n- [e.g., "CLAUDE.md is 312 lines \u2014 consider splitting reference sections into docs/"]\n- [e.g., "3 MCP servers load at boot \u2014 disable unused ones in settings.json"]\n```\n\n## Step 6: Further Resources\n\nEnd with:\n\n> For deeper token optimization, see:\n> - [Nate B Jones\'s token optimization techniques](https://www.youtube.com/watch?v=bDcgHzCBgmQ)\n> - [OB1 repo](https://github.com/nate-b-j/OB1) \u2014 Heavy File Ingestion skill and stupid button prompt kit\n> - [Joycraft\'s token discipline guide](docs/guides/token-discipline.md)\n\n## Edge Cases\n\n| Scenario | Behavior |\n|----------|----------|\n| Config files don\'t exist | Report "not found" for that check, don\'t error |\n| No plugins installed | Report 0 plugins \u2014 this is good, say so |\n| CLAUDE.md/AGENTS.md exactly 200 lines | PASS \u2014 threshold is \u2264200 |\n| `~/.claude/` or `~/.codex/` not accessible | Skip user-level checks, note limitation |\n| Both platforms detected | Run both audits, report separately |\n',
-  "joycraft-research.md": '---\nname: joycraft-research\ndescription: Produce objective codebase research by isolating question generation from fact-gathering \u2014 subagent sees only questions, never the brief\n---\n\n# Research Codebase for a Feature\n\nYou are producing objective codebase research to inform a future spec or implementation. The key insight: the researching agent must never see the brief or ticket \u2014 only research questions. This prevents opinions from contaminating the facts.\n\n**Guard clause:** If the user doesn\'t provide a brief path or inline description, ask:\n"What feature or change are you researching? Provide a brief path (e.g., `docs/features/2026-03-30-my-feature/brief.md`) or describe it in a few sentences."\n\n## Scanning Prior Research (Status Filter)\n\nBefore generating fresh questions, scan `docs/features/*/research.md` for prior research on similar topics. Read the YAML frontmatter at the top of each file:\n\n- Treat each file as `status: active` unless its frontmatter explicitly says otherwise.\n- **Skip / ignore** any file whose `status:` is `shipped`, `deprecated`, or `superseded` \u2014 they are no longer load-bearing.\n- Also ignore anything under `docs/archive/` entirely \u2014 archived research is out-of-scope.\n\nFiles without frontmatter at all are treated as `status: active` (legacy artifacts).\n\n---\n\n## Phase 1: Generate Research Questions\n\nRead the brief file (if a path was provided) or use the user\'s inline description.\n\nIdentify which zones of the codebase are relevant to this feature. Then generate 5-10 research questions that are:\n\n- **Objective and fact-seeking** \u2014 "How does X work?" not "How should we build X?"\n- **Specific to the codebase** \u2014 reference concrete systems, files, or flows\n- **Answerable by reading code** \u2014 no questions about business strategy or user preferences\n\nGood examples:\n- "How does endpoint registration work in the current router?"\n- "What patterns exist for input validation across existing handlers?"\n- "Trace the data flow from API request to database write for entity X."\n- "What test infrastructure exists? Where are fixtures, mocks, and helpers?"\n- "What dependencies does module Y import, and what does its public API look like?"\n\nBad examples (do NOT generate these):\n- "What\'s the best way to implement this feature?" (opinion)\n- "Should we use library X or Y?" (recommendation)\n- "What would a good architecture look like?" (design, not research)\n\nDerive a slug `YYYY-MM-DD-<feature-name>`. Lazy-create the folder `docs/features/<slug>/`.\n\n**Output path:**\n- If a brief exists at `docs/features/<slug>/brief.md`, write to `docs/features/<slug>/research.md` (per-feature layout).\n- If no brief exists (inline description only), write to `docs/research/YYYY-MM-DD-feature-name.md` (flat layout).\nWrite the questions to a temporary file at `docs/features/<slug>/.questions-tmp.md`.\n\n**Do NOT include any content from the brief in this file \u2014 only the questions.**\n\n---\n\n## Phase 2: Spawn Research Subagent\n\nUse Claude Code\'s Agent tool to spawn a subagent. Pass ONLY the research questions \u2014 never the brief path, brief content, or feature description.\n\nBuild the subagent prompt by reading the questions file you just wrote, then use this template:\n\n```\nYou are researching a codebase to answer specific questions. You have NO context about why these questions are being asked \u2014 you are simply gathering facts.\n\nRULES \u2014 these are hard constraints:\n- Answer each question with FACTS ONLY: file paths, function signatures, data flows, patterns, dependencies\n- Do NOT recommend, suggest, or opine on anything\n- Do NOT speculate about what should be built or how\n- If a question cannot be answered (no relevant code exists), say "No existing code found for this"\n- Use the Read tool and Grep tool to explore the codebase thoroughly\n- Include code snippets only when they are essential evidence (e.g., a function signature, a config block)\n\nQUESTIONS:\n[INSERT_QUESTIONS_HERE]\n\nOUTPUT FORMAT \u2014 write your findings as a single markdown document using this structure:\n\n# Codebase Research\n\n**Date:** [today\'s date]\n**Questions answered:** [N/total]\n\n---\n\n## Q1: [question text]\n\n[Facts, file paths, function signatures, data flows. No opinions.]\n\n## Q2: [question text]\n\n[Facts, file paths, function signatures, data flows. No opinions.]\n\n[Continue for all questions]\n```\n\n## Phase 3: Write the Research Document\n\nTake the subagent\'s response and write it to `docs/features/<slug>/research.md`. The file MUST start with YAML frontmatter \u2014 the 4-field personal schema:\n\n```yaml\n---\nstatus: active\nowner: <resolved name>\ncreated: YYYY-MM-DD\nfeature: <slug>\n---\n```\n\n**Owner resolution:** look up the owner name in this order \u2014 (1) `git config user.name`, (2) value in your auto-memory `joycraft-owner.txt` if present, (3) ask the user once and persist.\n\nDelete the temporary questions file (`docs/features/<slug>/.questions-tmp.md`).\n\n### Update the Feature Brief\n\nAfter writing the research document, update the parent brief with a back-reference:\n1. Read `docs/features/<slug>/brief.md`\n2. In the header blockquote (the `>` lines at the top), add or update:\n   `> **Research:** docs/features/<slug>/research.md`\n3. If a `> **Research:**` line already exists, replace it \u2014 do NOT add a duplicate\n4. Write the brief back\n\nEnd with the canonical Handoff block.\n\n## Recommended Next Steps\n\nNext:\n```bash\n/joycraft-design docs/features/<slug>/research.md\n```\nRun /clear first.\n\nIf the scope is simple (< 5 files, well-understood area, no architectural decisions), instead hand off to `/joycraft-decompose docs/features/<slug>/brief.md` to skip design and break directly into atomic specs.\n\n## Edge Cases\n\n| Scenario | Behavior |\n|----------|----------|\n| No brief provided | Accept inline description, generate questions from that |\n| Codebase is empty or new | Research doc reports "no existing patterns found" per question |\n| User runs research twice for same feature | Overwrites previous research doc (same filename) |\n| Brief is very short (1-2 sentences) | Still generate questions \u2014 even simple features benefit from understanding existing patterns |\n| `docs/features/<slug>/` doesn\'t exist | Lazy-create it |\n',
+  "joycraft-optimize.md": '---\nname: joycraft-optimize\ndescription: Audit your Claude Code or Codex session overhead \u2014 harness file sizes, plugins, MCP servers, hooks \u2014 and report actionable recommendations\ninstructions: 20\n---\n\n# Optimize \u2014 Session Overhead Audit\n\nYou are auditing the user\'s AI development session for token overhead. Produce a conversational diagnostic report \u2014 no files created.\n\n## Step 1: Detect Platform\n\nCheck which platform is active:\n- **Claude Code:** Look for `.claude/` directory, `CLAUDE.md`\n- **Codex:** Look for `.agents/` directory, `AGENTS.md`\n\nIf both exist, run both checks. If neither, default to Claude Code checks and note the uncertainty.\n\n## Step 2: Audit Harness Files\n\n### Claude Code Path\n\n1. **CLAUDE.md** \u2014 count lines. Threshold: \u2264200 lines.\n2. **Skill files** \u2014 glob `.claude/skills/**/*.md`. Count lines per file. Threshold: \u2264200 lines each.\n\n### Codex Path\n\n1. **AGENTS.md** \u2014 count lines. Threshold: \u2264200 lines.\n2. **Skill files** \u2014 glob `.agents/skills/**/*.md`. Count lines per file. Threshold: \u2264200 lines each.\n\n## Step 3: Audit Plugins & MCP Servers\n\n### Claude Code Path\n\n1. **Installed plugins** \u2014 read `~/.claude/plugins/installed_plugins.json`. List plugin names and versions. If not found, report "no plugins file found."\n2. **Enabled plugins** \u2014 read `~/.claude/settings.json`, check `enabledPlugins` array. Show enabled vs installed count.\n3. **MCP servers** \u2014 read `~/.claude/settings.json`, count entries under `mcpServers`. List server names.\n\n### Codex Path\n\n1. **Plugin config** \u2014 read `~/.codex/config.toml`. List any plugin toggles. Note: Codex syncs its curated plugin marketplace at startup \u2014 this is a boot cost even if you don\'t use them.\n2. **MCP servers** \u2014 check `~/.codex/config.toml` for MCP server entries. List server names.\n\n## Step 4: Audit Hooks (Claude Code Only)\n\nRead `.claude/settings.json` in the project directory. List all hook definitions under the `hooks` key \u2014 show the event name and command for each.\n\nFor Codex: note "hook auditing not yet supported on Codex."\n\n## Step 5: Report\n\nOrganize findings by category. Use pass/warn indicators:\n\n```\n## Session Overhead Report\n\n### Harness Files\n- CLAUDE.md: [N] lines [PASS \u2264200 / WARN >200]\n- Skills: [N] files, [list any over 200 lines]\n\n### Plugins\n- Installed: [N] ([list names])\n- Enabled: [N] of [M] installed\n- [If 0: "No plugins \u2014 zero boot cost from plugins."]\n\n### MCP Servers\n- Count: [N] ([list names])\n- [If 0: "No MCP servers \u2014 zero boot cost from servers."]\n\n### Hooks\n- [N] hook definitions ([list event names])\n\n### Recommendations\n- [Specific, actionable items for anything over threshold]\n- [e.g., "CLAUDE.md is 312 lines \u2014 consider splitting reference sections into docs/"]\n- [e.g., "3 MCP servers load at boot \u2014 disable unused ones in settings.json"]\n```\n\n## Step 6: Further Resources\n\nEnd with:\n\n> For deeper token optimization, see:\n> - [Nate B Jones\'s token optimization techniques](https://www.youtube.com/watch?v=bDcgHzCBgmQ)\n> - [OB1 repo](https://github.com/nate-b-j/OB1) \u2014 Heavy File Ingestion skill and stupid button prompt kit\n> - [Joycraft\'s token discipline guide](docs/guides/token-discipline.md)\n\n## Edge Cases\n\n| Scenario | Behavior |\n|----------|----------|\n| Config files don\'t exist | Report "not found" for that check, don\'t error |\n| No plugins installed | Report 0 plugins \u2014 this is good, say so |\n| CLAUDE.md exactly 200 lines | PASS \u2014 threshold is \u2264200 |\n| `~/.claude/` or `~/.codex/` not accessible | Skip user-level checks, note limitation |\n| Both platforms detected | Run both audits, report separately |\n',
+  "joycraft-research.md": '---\nname: joycraft-research\ndescription: Produce objective codebase research by isolating question generation from fact-gathering \u2014 subagent sees only questions, never the brief\n---\n\n# Research Codebase for a Feature\n\nYou are producing objective codebase research to inform a future spec or implementation. The key insight: the researching agent must never see the brief or ticket \u2014 only research questions. This prevents opinions from contaminating the facts.\n\n**Guard clause:** If the user doesn\'t provide a brief path or inline description, ask:\n"What feature or change are you researching? Provide a brief path (e.g., `docs/features/2026-03-30-my-feature/brief.md`) or describe it in a few sentences."\n\n## Scanning Prior Research (Status Filter)\n\nBefore generating fresh questions, scan `docs/features/*/research.md` for prior research on similar topics. Read the YAML frontmatter at the top of each file:\n\n- Treat each file as `status: active` unless its frontmatter explicitly says otherwise.\n- **Skip / ignore** any file whose `status:` is `shipped`, `deprecated`, or `superseded` \u2014 they are no longer load-bearing.\n- Also ignore anything under `docs/archive/` entirely \u2014 archived research is out-of-scope.\n\nFiles without frontmatter at all are treated as `status: active` (legacy artifacts).\n\n---\n\n## Phase 1: Generate Research Questions\n\nRead the brief file (if a path was provided) or use the user\'s inline description.\n\nIdentify which zones of the codebase are relevant to this feature. Then generate 5-10 research questions that are:\n\n- **Objective and fact-seeking** \u2014 "How does X work?" not "How should we build X?"\n- **Specific to the codebase** \u2014 reference concrete systems, files, or flows\n- **Answerable by reading code** \u2014 no questions about business strategy or user preferences\n\nGood examples:\n- "How does endpoint registration work in the current router?"\n- "What patterns exist for input validation across existing handlers?"\n- "Trace the data flow from API request to database write for entity X."\n- "What test infrastructure exists? Where are fixtures, mocks, and helpers?"\n- "What dependencies does module Y import, and what does its public API look like?"\n\nBad examples (do NOT generate these):\n- "What\'s the best way to implement this feature?" (opinion)\n- "Should we use library X or Y?" (recommendation)\n- "What would a good architecture look like?" (design, not research)\n\nDerive a slug `YYYY-MM-DD-<feature-name>`. Lazy-create the folder `docs/features/<slug>/`.\n\n**Output path:**\n- If a brief exists at `docs/features/<slug>/brief.md`, write to `docs/features/<slug>/research.md` (per-feature layout).\n- If no brief exists (inline description only), write to `docs/research/YYYY-MM-DD-feature-name.md` (flat layout).\nWrite the questions to a temporary file at `docs/features/<slug>/.questions-tmp.md`.\n\n**Do NOT include any content from the brief in this file \u2014 only the questions.**\n\n---\n\n## Phase 2: Spawn Research Subagent\n\nUse Claude Code\'s Agent tool to spawn a subagent. Pass ONLY the research questions \u2014 never the brief path, brief content, or feature description.\n\nBuild the subagent prompt by reading the questions file you just wrote, then use this template:\n\n```\nYou are researching a codebase to answer specific questions. You have NO context about why these questions are being asked \u2014 you are simply gathering facts.\n\nRULES \u2014 these are hard constraints:\n- Answer each question with FACTS ONLY: file paths, function signatures, data flows, patterns, dependencies\n- Do NOT recommend, suggest, or opine on anything\n- Do NOT speculate about what should be built or how\n- If a question cannot be answered (no relevant code exists), say "No existing code found for this"\n- Use the Read tool and Grep tool to explore the codebase thoroughly\n- Include code snippets only when they are essential evidence (e.g., a function signature, a config block)\n\nQUESTIONS:\n[INSERT_QUESTIONS_HERE]\n\nOUTPUT FORMAT \u2014 write your findings as a single markdown document using this structure:\n\n# Codebase Research\n\n**Date:** [today\'s date]\n**Questions answered:** [N/total]\n\n---\n\n## Q1: [question text]\n\n[Facts, file paths, function signatures, data flows. No opinions.]\n\n## Q2: [question text]\n\n[Facts, file paths, function signatures, data flows. No opinions.]\n\n[Continue for all questions]\n```\n\n## Phase 3: Write the Research Document\n\nTake the subagent\'s response and write it to `docs/features/<slug>/research.md`. The file MUST start with YAML frontmatter \u2014 the 4-field personal schema:\n\n```yaml\n---\nstatus: active\nowner: <resolved name>\ncreated: YYYY-MM-DD\nfeature: <slug>\n---\n```\n\n**Owner resolution:** look up the owner name in this order \u2014 (1) `git config user.name`, (2) value in your auto-memory `joycraft-owner.txt` if present, (3) ask the user once and persist.\n\nDelete the temporary questions file (`docs/features/<slug>/.questions-tmp.md`).\n\n### Update the Feature Brief\n\nAfter writing the research document, update the parent brief with a back-reference:\n1. Read `docs/features/<slug>/brief.md`\n2. In the header blockquote (the `>` lines at the top), add or update:\n   `> **Research:** docs/features/<slug>/research.md`\n3. If a `> **Research:**` line already exists, replace it \u2014 do NOT add a duplicate\n4. Write the brief back\n\n## Phase 4: Reconcile Brief with Findings\n\nYou\'ve just written `docs/features/<slug>/research.md`. Before hand-off, the parent brief at `docs/features/<slug>/brief.md` may now disagree with what you discovered. Re-read it and check each of these sections:\n\n| Brief section | What to look for |\n|---|---|\n| Vision | Did your findings refine or contradict the framing? |\n| Hard Constraints | Are any constraints now obsolete, missing, or refined? |\n| Out of Scope | Did your findings push something in or out of scope? |\n| Decomposition | Are spec counts, names, or dependencies still accurate? |\n| Test Strategy | Do your findings change what or how to test? |\n| Success Criteria | Are the criteria still observable and still match the goal? |\n\n**For each section, choose one:**\n\n- **Edit in place** \u2014 small, mechanical updates: line-number corrections, clarifications, additions consistent with brief intent. No user approval needed.\n- **Diff + stop** \u2014 non-trivial changes: counts flipping, decomposition restructure, scope changes, contradiction with original brief intent. Present a diff of the proposed change, STOP, and wait for user approval before continuing.\n\nIf you make changes, note them at the bottom of `research.md` under a "Brief updates" subsection. If the brief is already in sync, note: "Reconciliation checked, no changes required." If no parent brief exists (feature was described inline), note that and skip this step.\n\n**Why this step exists:** the silent-drift gap. Without reconciliation, the brief and downstream artifacts diverge \u2014 and later decomposition is sized against the stale brief. This feature ("single-source-skills") hit exactly this: brief said "11 clean / 9 dirty" until the research re-audit forced a re-decomposition. Don\'t let it happen again.\n\nEnd with the canonical Handoff block.\n\n## Recommended Next Steps\n\nNext:\n```bash\n/joycraft-design docs/features/<slug>/research.md\n```\nRun /clear first.\n\nIf the scope is simple (< 5 files, well-understood area, no architectural decisions), instead hand off to `/joycraft-decompose docs/features/<slug>/brief.md` to skip design and break directly into atomic specs.\n\n## Edge Cases\n\n| Scenario | Behavior |\n|----------|----------|\n| No brief provided | Accept inline description, generate questions from that |\n| Codebase is empty or new | Research doc reports "no existing patterns found" per question |\n| User runs research twice for same feature | Overwrites previous research doc (same filename) |\n| Brief is very short (1-2 sentences) | Still generate questions \u2014 even simple features benefit from understanding existing patterns |\n| `docs/features/<slug>/` doesn\'t exist | Lazy-create it |\n',
   "joycraft-session-end.md": "---\nname: joycraft-session-end\ndescription: Wrap up a session \u2014 capture discoveries, verify, prepare for PR or next session\ninstructions: 22\n---\n\n# Session Wrap-Up \u2014 Feature Finisher\n\nThis is the **once-per-feature finisher** \u2014 the heavy bookend that runs **once**, when the feature's specs are done, not after every spec. It is the **only validation gate** in the loop and the single place that pushes and opens the PR.\n\n> **Two-tier wrap-up.** The light per-spec step is `joycraft-spec-done` (status bump `todo \u2192 in-review` + commit, no validation/push/PR \u2014 it runs after each spec). This skill is the heavy counterpart: full validation, consolidate the discovery stubs spec-done left behind, graduate every `in-review` spec to `done`, push, and open the PR. See `docs/reference/spec-status-lifecycle.md` for the `todo \u2192 in-review \u2192 done` lifecycle.\n\nComplete these steps in order.\n\n## 1. Consolidate Discoveries\n\n**Why:** Discoveries are the surprises \u2014 things that weren't in the spec or that contradicted expectations. They prevent future sessions from hitting the same walls.\n\nThis is the **consolidation** pass: `joycraft-spec-done` may have left terse 2-line discovery **stubs** during the feature (one per surprising spec). Curate and expand those stubs into proper discovery docs now, and capture anything else surprising from the feature as a whole. If any stubs exist at `docs/discoveries/`, consolidate them (merge related ones, expand each into the full format below); then create or update a discovery file at `docs/discoveries/YYYY-MM-DD-topic.md`. Lazy-create the `docs/discoveries/` directory if it doesn't exist.\n\n(Discoveries stay flat at `docs/discoveries/` rather than per-feature, since they often span features and are read serendipitously rather than via a known path.)\n\nThe discovery file MUST start with YAML frontmatter \u2014 the 4-field personal schema:\n\n```yaml\n---\nstatus: todo\nowner: <resolved name>\ncreated: YYYY-MM-DD\nfeature: <slug-of-related-feature>   # omit if not feature-tied\n---\n```\n\n**Owner resolution:** look up the owner name in this order \u2014 (1) `git config user.name`, (2) value in your auto-memory `joycraft-owner.txt` if present, (3) ask the user once and persist.\n\nOnly capture what's NOT obvious from the code or git diff:\n- \"We thought X but found Y\" \u2014 assumptions that were wrong\n- \"This API/library behaves differently than documented\" \u2014 external gotchas\n- \"This edge case needs handling in a future spec\" \u2014 deferred work with context\n- \"The approach in the spec didn't work because...\" \u2014 spec-vs-reality gaps\n- Key decisions made during implementation that aren't in the spec\n\n**Do NOT capture:**\n- Files changed (that's the diff)\n- What you set out to do (that's the spec)\n- Step-by-step narrative of the session (nobody re-reads these)\n\nUse this format:\n\n```markdown\n# Discoveries \u2014 [topic]\n\n**Date:** YYYY-MM-DD\n**Spec:** [link to spec if applicable]\n\n## [Discovery title]\n**Expected:** [what we thought would happen]\n**Actual:** [what actually happened]\n**Impact:** [what this means for future work]\n```\n\nIf nothing surprising happened, skip the discovery file entirely. No discovery is a good sign \u2014 the spec was accurate.\n\n## 1b. Update Context Documents\n\nIf `docs/context/` exists, quickly check whether this session revealed anything about:\n\n- **Production risks** \u2014 did you interact with or learn about production vs staging systems? \u2192 Update `docs/context/production-map.md`\n- **Wrong assumptions** \u2014 did the agent (or you) assume something that turned out to be false? \u2192 Update `docs/context/dangerous-assumptions.md`\n- **Key decisions** \u2014 did you make an architectural or tooling choice? \u2192 Add a row to `docs/context/decision-log.md`\n- **Unwritten rules** \u2014 did you discover a convention or constraint not documented anywhere? \u2192 Update `docs/context/institutional-knowledge.md`\n\nWhen you UPDATE a context doc, also bump (or add) its YAML frontmatter \u2014 the 2-field shared schema:\n\n```yaml\n---\nlast_updated: YYYY-MM-DD\nlast_updated_by: <resolved name>\n---\n```\n\nIf the file already has the frontmatter, update the `last_updated` and `last_updated_by` fields in place. If it doesn't, prepend a fresh block. Context docs are *shared* artifacts (no single owner) \u2014 the shared schema reflects that.\n\nSkip this if nothing applies. Don't force it \u2014 only update when there's genuine new context.\n\n## 2. Run Validation \u2014 the ONLY validation gate\n\nThis is **mandatory** and it is the **only** validation gate in the loop: `joycraft-spec-done` deliberately skips validation (it trusts implement's per-spec TDD), so this feature-level run is the single cross-spec safety net. Never skip it.\n\nRun the project's validation commands. Check CLAUDE.md for project-specific commands. Common checks:\n\n- Type-check (e.g., `tsc --noEmit`, `mypy`, `cargo check`)\n- Tests (e.g., `npm test`, `pytest`, `cargo test`)\n- Lint (e.g., `eslint`, `ruff`, `clippy`)\n\nFix any failures before proceeding. **If validation fails, stop \u2014 do NOT graduate specs to `done` and do NOT push.**\n\n## 3. Graduate Specs `in-review \u2192 done`\n\nThis step graduates the feature's finished specs to their terminal state. Because session-end runs once at the end, **multiple specs may be waiting** in `in-review` (one per spec the loop completed via `joycraft-spec-done`). Graduate **all** of them, in **both** systems (the queue JSON and the frontmatter must never disagree):\n\nFor each spec in `docs/features/<slug>/specs/` (or `docs/bugfixes/<area>/` for bugfixes \u2014 scan recursively) whose status is `in-review`:\n\n1. **Queue JSON** \u2014 `joycraft-mark-done <spec-id> --to done <specs-dir>` (the `--to done` graduation; find `<spec-id>` by matching the entry's `file`).\n2. **Frontmatter** \u2014 edit the spec file's YAML `status:` to `done`.\n\nRules:\n- Only graduate specs that are `in-review`. A spec still at `todo` was never started \u2014 **leave it `todo` and report it as remaining** (the feature isn't fully done; see the PR gate in step 5).\n- Never write `done` for work nothing has validated \u2014 this validation run (step 2) is what licenses the graduation. (Once `verify-in-loop` ships, an independent verify performs the `in-review \u2192 done` transition; until then, this step does.)\n- `done` means **verified**, not **merged**. A merged PR is a git fact, never a spec status \u2014 do not invent a `merged` status or any fourth state beyond `todo`/`in-review`/`done`.\n\nIf working from a Feature Brief at `docs/features/<slug>/brief.md`, also check off completed specs in the decomposition table.\n\n## 4. Commit\n\nCommit all changes including the discovery file (if created) and spec status updates. The commit message should reference the spec if applicable.\n\n## 5. Push and PR (if autonomous git is enabled)\n\n**Check CLAUDE.md for \"Git Autonomy\" in the Behavioral Boundaries section.** If it says \"STRICTLY ENFORCED\" or the ALWAYS section includes \"Push to feature branches immediately after every commit\":\n\n1. **Push immediately.** Run `git push origin <branch>` \u2014 do not ask, do not hesitate.\n2. **Open a PR if the feature is complete.** The feature is complete when every spec is `done` (none left at `todo`/`in-review`). Check the queue JSON / decomposition table \u2014 if all specs are `done`, run `gh pr create` with a summary of all completed specs. Do not ask first.\n3. **If specs remain (`todo`),** still push. The PR comes when the feature's last spec is graduated.\n\nIf CLAUDE.md does NOT have autonomous git rules (or has \"ASK FIRST\" for pushing), ask the user before pushing.\n\n## 6. Report and Hand Off\n\n```\nFeature complete.\n- Feature: [slug]\n- Specs graduated to done: [N] (remaining at todo: [N])\n- Build: [passing / failing]\n- Discoveries: [N consolidated / none]\n- Pushed: [yes / no \u2014 and why not]\n- PR: [opened #N / not yet \u2014 N specs remaining]\n- Next: [what comes after this feature]\n```\n\nEnd with the canonical Handoff block. Include any discovery and updated-context paths produced.\n\n## Recommended Next Steps\n\nNext:\n```bash\n/joycraft-implement docs/features/<slug>/specs/<next-spec>.md\n```\nRun /clear first.\n\nIf all specs in the feature are complete, hand off to a feature-level wrap-up instead (PR review, etc.) \u2014 the Handoff block is just the slash command for whatever the next move is.\n",
   "joycraft-setup.md": '---\nname: joycraft-setup\ndescription: Set up Joycraft and get started on this project -- the first-time entry point. Run this when you\'re configuring your project, onboarding, or asking "where do I begin?" / "how do I set this up?"\ninstructions: 6\n---\n\n# Setup \u2014 The First-Run Door\n\nThis is the obvious starting point for setting up Joycraft on this project. It does no work of its own \u2014 it routes you to the skill that does the real assessment and onboarding.\n\n**Run `/joycraft-tune`.**\n\n`/joycraft-tune` detects your project\'s current harness state, scores it, applies the upgrades it can, and on a first run kicks off the context-onboarding pass for you. That\'s the whole setup flow \u2014 this alias just exists so "set up", "get started", and "first time" lead you there.\n\nDo not re-implement assessment or scoring here; hand off to `/joycraft-tune`.\n',
   "joycraft-spec-done.md": "---\nname: joycraft-spec-done\ndescription: Lightweight per-spec wrap-up \u2014 bump status to in-review, terse discovery if surprised, commit. Run after each spec in checkpoint/isolated mode; no validation, no push, no PR.\n---\n\n# Spec Done (Lightweight Per-Spec Wrap-Up)\n\nYou just finished implementing **one** atomic spec. This is the fast handshake that runs **once per spec**, before context clears \u2014 the `todo \u2192 in-review` transition in the lifecycle (`docs/reference/spec-status-lifecycle.md`). It is deliberately tiny: it does exactly four things and nothing more.\n\n> **This is NOT session-end.** It does **not** run validation, push, or open a PR. It trusts the TDD you just did in `joycraft-implement`. The heavy once-per-feature wrap-up (full validation + consolidate discoveries + push + PR) is `joycraft-session-end`, which runs once at the end of the feature.\n>\n> **Usually you don't run this by hand:** `joycraft-implement` performs these four steps itself at the end of every checkpoint/isolated spec (and `joycraft-implement-feature` drives whole queues). This skill remains the canonical definition of the wrap-up \u2014 run it manually after ad-hoc work done outside the implement skill, or when an implement run was interrupted before wrapping up.\n\n## Step 1: Bump status to `in-review` \u2014 in BOTH systems\n\nA spec's status lives in two places that must never disagree (the desync this feature exists to kill): the **queue JSON** and the spec's **frontmatter**. Update both to `in-review`.\n\n1. **Queue JSON** \u2014 use the script, not a bespoke `sed`:\n   ```bash\n   joycraft-mark-done <spec-id> --to in-review <specs-dir>\n   ```\n   Find `<spec-id>` by reading `<specs-dir>/.joycraft-spec-queue.json` and matching the entry whose `file` is the spec you just implemented. `<specs-dir>` is the folder containing the spec (e.g. `docs/features/<slug>/specs`). If the spec isn't in the manifest, `joycraft-mark-done` exits non-zero with a clear error \u2014 **surface that error, don't silently skip the bump**.\n2. **Frontmatter** \u2014 edit the spec file's YAML `status:` field to `in-review`.\n\nDo **not** graduate to `done`. The agent never self-certifies \u2014 `done` is reached only by `joycraft-session-end` (or, later, an independent verify). `spec-done` only ever reaches `in-review`.\n\n## Step 2: Terse discovery stub \u2014 ONLY if something surprised you\n\nDid anything during implementation **contradict the spec** or surprise you (an assumption that was wrong, an external API that behaved differently, an edge case the spec missed)?\n\n- **No** \u2192 skip this step entirely. A spec that went as written needs no discovery. This is the common case.\n- **Yes** \u2192 write a **2-line stub** (not a full discovery doc) at `docs/discoveries/YYYY-MM-DD-topic.md`: one line on what contradicted the spec, one line pointing at the spec/file. `joycraft-session-end`'s consolidation pass later expands these stubs into proper discovery docs \u2014 keep it terse here.\n\n## Step 3: Commit\n\nCommit the spec's implementation changes plus the status edits (and the stub, if any) with the convention:\n\n```\nspec: <spec-name>\n```\n\nKeep scope disciplined \u2014 commit the spec's changes and its status edits, not unrelated working-tree noise.\n\n## Step 4: Stop\n\nThat's it. **No** validation re-run, **no** push, **no** PR \u2014 those belong to `joycraft-session-end` at feature end. Hand off and keep the loop moving.\n\n## Recommended Next Steps\n\nIf more specs remain in this feature (checkpoint/isolated mode), continue to the next one:\n\n```bash\n/joycraft-implement docs/features/<slug>/specs/<next-spec>.md\n```\n\nWhen the feature's last spec is done, run the feature finisher once:\n\n```bash\n/joycraft-session-end\n```\n",
@@ -438,48 +438,48 @@ describe("CLI: init command (example \u2014 replace with your real scenarios)",
   "workflows/spec-dispatch.yml": '# Spec Dispatch Workflow\n#\n# Triggered when specs are pushed to main (feature specs under\n# docs/features/<slug>/specs/, bugfix specs under docs/bugfixes/<area>/).\n# For each added or modified spec,\n# fires a `spec-pushed` repository_dispatch event to the scenarios repo so\n# that a scenario agent can triage the spec and write/update holdout tests.\n#\n# Prerequisites:\n#   - JOYCRAFT_APP_PRIVATE_KEY secret: GitHub App private key (.pem)\n#   - $JOYCRAFT_APP_ID is replaced with the actual App ID number at install time\n#   - $SCENARIOS_REPO is replaced with the actual scenarios repo name at install time\n\nname: Spec Dispatch\n\non:\n  push:\n    branches: [main]\n    paths:\n      - "docs/features/**/specs/**"\n      - "docs/bugfixes/**"\n\njobs:\n  dispatch:\n    name: Dispatch changed specs to scenarios repo\n    runs-on: ubuntu-latest\n\n    steps:\n      # \u2500\u2500 1. Check out with depth 2 to enable HEAD~1 diff \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n      - name: Checkout\n        uses: actions/checkout@v4\n        with:\n          fetch-depth: 2\n\n      # \u2500\u2500 2. Find added or modified spec files \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n      # --diff-filter=AM: Added or Modified only \u2014 ignore deletions.\n      - name: Find changed specs\n        id: changed\n        run: |\n          FILES=$(git diff --name-only --diff-filter=AM HEAD~1 HEAD -- \'docs/features/**/specs/**/*.md\' \'docs/bugfixes/**/*.md\')\n          echo "files<<EOF" >> "$GITHUB_OUTPUT"\n          echo "$FILES" >> "$GITHUB_OUTPUT"\n          echo "EOF" >> "$GITHUB_OUTPUT"\n          echo "Changed specs: $FILES"\n\n      # \u2500\u2500 3. Generate GitHub App token for cross-repo dispatch \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n      # Skipped if no specs changed (token unused, save the round-trip).\n      - name: Generate GitHub App token\n        id: app-token\n        if: steps.changed.outputs.files != \'\'\n        uses: actions/create-github-app-token@v1\n        with:\n          app-id: $JOYCRAFT_APP_ID\n          private-key: ${{ secrets.JOYCRAFT_APP_PRIVATE_KEY }}\n          repositories: $SCENARIOS_REPO\n\n      # \u2500\u2500 4. Dispatch each changed spec to the scenarios repo \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n      # Sends a `spec-pushed` event with the spec filename, full content,\n      # commit SHA, branch, and originating repo. The scenario agent uses\n      # this payload to triage and generate/update tests.\n      - name: Dispatch spec-pushed events\n        if: steps.changed.outputs.files != \'\'\n        env:\n          GH_TOKEN: ${{ steps.app-token.outputs.token }}\n        run: |\n          while IFS= read -r SPEC_FILE; do\n            [ -z "$SPEC_FILE" ] && continue\n\n            SPEC_FILENAME=$(basename "$SPEC_FILE")\n            SPEC_CONTENT=$(cat "$SPEC_FILE")\n\n            echo "Dispatching spec-pushed for $SPEC_FILENAME"\n\n            gh api repos/${{ github.repository_owner }}/$SCENARIOS_REPO/dispatches \\\n              -f event_type=spec-pushed \\\n              -f "client_payload[spec_filename]=$SPEC_FILENAME" \\\n              -f "client_payload[spec_content]=$SPEC_CONTENT" \\\n              -f "client_payload[commit_sha]=${{ github.sha }}" \\\n              -f "client_payload[branch]=${{ github.ref_name }}" \\\n              -f "client_payload[repo]=${{ github.repository }}"\n\n          done <<< "${{ steps.changed.outputs.files }}"\n'
 };
 var CODEX_SKILLS = {
-  "joycraft-add-context.md": '---\nname: joycraft-add-context\ndescription: Author one long-form reference doc -- a design system, frontend/backend methodology, testing conventions, or any other long-form reference doc -- scaffolding it from a template and wiring a pointer into the project boundary file\'s Context Map\n---\n\n# Add Context\n\nThe user wants to author ONE long-form reference doc \u2014 a design system, a frontend or backend methodology, testing conventions, or any other long-form reference for this project. Your job is to scaffold that doc from the matching template, fill in what the user has told you, write it immediately, and wire a pointer row into the project\'s `## Context Map`.\n\nThis is the single-doc primitive. Write-as-you-go is correct here: you scaffold and write ONE doc per invocation, immediately \u2014 not a batch.\n\nThis skill is self-contained. Everything you need is below; do not call into or import another skill\'s logic.\n\n## Step 1: Determine Topic and Slug\n\nFigure out what reference doc the user wants. If they named it (e.g., `$joycraft-add-context our design system`), use that. Otherwise ask: "What reference doc do you want to author?" \u2014 then wait.\n\nDerive a kebab-case `<slug>` from the topic (e.g., "our design system" \u2192 `design-system`, "payments service backend" \u2192 `payments-backend`).\n\n## Step 2: Pick the Matching Template\n\nChoose the bundled template in `docs/templates/context/reference/` that best fits the topic:\n\n| Topic | Template |\n|-------|----------|\n| Design system, tokens, components, visual language | `design-system.md` |\n| Frontend architecture, state, folder conventions, patterns | `frontend-methodology.md` |\n| Service boundaries, API conventions, data model, errors | `backend.md` |\n| Test pyramid, frameworks, fixtures, CI gates | `testing.md` |\n| Anything else not covered above | `reference-doc.md` (generic fallback) |\n\nIf the topic matches none of the four named templates, use the generic `reference-doc.md`.\n\n## Step 3: Scaffold the Doc to `docs/context/reference/<slug>.md`\n\n1. **Lazy-create `docs/context/reference/`** \u2014 create the directory only now, on first write. Do not create it preemptively in projects that never call this skill.\n2. Read the chosen template from `docs/templates/context/reference/`. If that template file isn\'t present in the project, fall back to a minimal skeleton: an `# H1` title, a `>` purpose blockquote, and one `##` section.\n3. Copy the template to `docs/context/reference/<slug>.md`, set the H1 to the real topic, and fill in whatever the user has already told you. Leave the rest of the template\'s deletable italic examples in place for the author to replace.\n4. **Write the doc immediately** \u2014 this single doc, this invocation. Do not defer or batch.\n\nIf `docs/context/reference/<slug>.md` already exists (the user is re-running for the same slug), update it in place rather than creating a duplicate.\n\n## Step 4: Add or Update the Context Map Pointer Row (Idempotent)\n\nRead the project\'s boundary file \u2014 CLAUDE.md and/or AGENTS.md, whichever the project uses \u2014 and maintain a pointer row for this doc in the `## Context Map` section. The row format is:\n\n```\n| docs/context/reference/<slug>.md | <when to read it> |\n```\n\nApply this idempotent logic exactly:\n\n1. **If a `## Context Map` section does not exist**, create it (place it after the project intro / Behavioral Boundaries area, before deep architecture). Add the header and a two-column table:\n\n   ```markdown\n   ## Context Map\n\n   | Doc | When to read it |\n   |-----|-----------------|\n   ```\n\n2. **If a row whose first cell is `docs/context/reference/<slug>.md` already exists**, update that row in place (refresh the "when to read it" cell). Do NOT add a second row for the same path.\n\n3. **Otherwise**, append one new row to the Context Map table.\n\nNever duplicate a row. The Context Map is a lightweight pointer index \u2014 one row per reference doc, nothing more.\n\n## Step 5: Confirm\n\nReport what you did:\n\n```\nScaffolded docs/context/reference/<slug>.md from the <template> template.\nContext Map row [added | updated]:\n  | docs/context/reference/<slug>.md | <when to read it> |\n\nFill in the doc\'s sections \u2014 the italic examples are placeholders to replace or delete.\n```\n',
-  "joycraft-add-fact.md": '---\nname: joycraft-add-fact\ndescription: Capture a project fact and route it to the correct context document -- production map, dangerous assumptions, decision log, institutional knowledge, or troubleshooting\n---\n\n# Add Fact\n\nThe user has a fact to capture. Your job is to classify it, route it to the correct context document, append it in the right format, and optionally add a boundary rule to CLAUDE.md or AGENTS.md.\n\n## Step 1: Get the Fact\n\nIf the user already provided the fact (e.g., `$joycraft-add-fact the staging DB resets every Sunday`), use it directly.\n\nIf not, ask: "What fact do you want to capture?" -- then wait for their response.\n\nIf the user provides multiple facts at once, process each one separately through all the steps below, then give a combined confirmation at the end.\n\n## Step 2: Classify the Fact\n\nRoute the fact to one of these 5 context documents based on its content:\n\n### `docs/context/production-map.md`\nThe fact is about **infrastructure, services, environments, URLs, endpoints, credentials, or what is safe/unsafe to touch**.\n- Signal words: "production", "staging", "endpoint", "URL", "database", "service", "deployed", "hosted", "credentials", "secret", "environment"\n- Examples: "The staging DB is at postgres://staging.example.com", "We use Vercel for the frontend and Railway for the API"\n\n### `docs/context/dangerous-assumptions.md`\nThe fact is about **something an AI agent might get wrong -- a false assumption that leads to bad outcomes**.\n- Signal words: "assumes", "might think", "but actually", "looks like X but is Y", "not what it seems", "trap", "gotcha"\n- Examples: "The `users` table looks like a test table but it\'s production", "Deleting a workspace doesn\'t delete the billing subscription"\n\n### `docs/context/decision-log.md`\nThe fact is about **an architectural or tooling choice and why it was made**.\n- Signal words: "decided", "chose", "because", "instead of", "we went with", "the reason we use", "trade-off"\n- Examples: "We chose SQLite over Postgres because this runs on embedded devices", "We use pnpm instead of npm for workspace support"\n\n### `docs/context/institutional-knowledge.md`\nThe fact is about **team conventions, unwritten rules, organizational context, or who owns what**.\n- Signal words: "convention", "rule", "always", "never", "team", "process", "review", "approval", "owns", "responsible"\n- Examples: "The design team reviews all color changes", "We never deploy on Fridays", "PR titles must start with the ticket number"\n\n### `docs/context/troubleshooting.md`\nThe fact is about **diagnostic knowledge -- when X happens, do Y (or don\'t do Z)**.\n- Signal words: "when", "fails", "error", "if you see", "stuck", "broken", "fix", "workaround", "before trying", "reboot", "restart", "reset"\n- Examples: "If Wi-Fi disconnects during flash, wait and retry -- don\'t switch networks", "When tests fail with ECONNREFUSED, check if Docker is running"\n\n### Ambiguous Facts\n\nIf the fact fits multiple categories, pick the **best fit** based on the primary intent. You will mention the alternative in your confirmation message so the user can correct you.\n\n## Step 3: Ensure the Target Document Exists\n\n1. If `docs/context/` does not exist, create the directory.\n2. If the target document does not exist, create it from the template structure. Check `docs/templates/` for the matching template. If no template exists, use this minimal structure:\n\nFor **production-map.md**:\n```markdown\n# Production Map\n\n> What\'s real, what\'s staging, what\'s safe to touch.\n\n## Services\n\n| Service | Environment | URL/Endpoint | Impact if Corrupted |\n|---------|-------------|-------------|-------------------|\n```\n\nFor **dangerous-assumptions.md**:\n```markdown\n# Dangerous Assumptions\n\n> Things the AI agent might assume that are wrong in this project.\n\n## Assumptions\n\n| Agent Might Assume | But Actually | Impact If Wrong |\n|-------------------|-------------|----------------|\n```\n\nFor **decision-log.md**:\n```markdown\n# Decision Log\n\n> Why choices were made, not just what was chosen.\n\n## Decisions\n\n| Date | Decision | Why | Alternatives Rejected | Revisit When |\n|------|----------|-----|----------------------|-------------|\n```\n\nFor **institutional-knowledge.md**:\n```markdown\n# Institutional Knowledge\n\n> Unwritten rules, team conventions, and organizational context.\n\n## Team Conventions\n\n- (none yet)\n```\n\nFor **troubleshooting.md**:\n```markdown\n# Troubleshooting\n\n> What to do when things go wrong for non-code reasons.\n\n## Common Failures\n\n| When This Happens | Do This | Don\'t Do This |\n|-------------------|---------|---------------|\n```\n\n## Step 4: Read the Target Document\n\nRead the target document to understand its current structure. Note:\n- Which section to append to\n- Whether it uses tables or lists\n- The column format if it\'s a table\n\n## Step 5: Append the Fact\n\nAdd the fact to the appropriate section of the target document. Match the existing format exactly:\n\n- **Table-based documents** (production-map, dangerous-assumptions, decision-log, troubleshooting): Add a new table row in the correct columns. Use today\'s date where a date column exists.\n- **List-based documents** (institutional-knowledge): Add a new list item (`- `) to the most appropriate section.\n\nRemove any italic example rows (rows where all cells start with `_`) before appending, so the document transitions from template to real content. Only remove examples from the specific table you are appending to.\n\n**Append only. Never modify or remove existing real content.**\n\n## Step 6: Evaluate Boundary Rule\n\nDecide whether the fact also warrants a rule in the project\'s boundary configuration (CLAUDE.md and/or AGENTS.md -- check which files the project uses and update accordingly):\n\n**Add a boundary rule if the fact:**\n- Describes something that should ALWAYS or NEVER be done\n- Could cause real damage if violated (data loss, broken deployments, security issues)\n- Is a hard constraint that applies across all work, not just a one-time note\n\n**Do NOT add a boundary rule if the fact is:**\n- Purely informational (e.g., "staging DB is at this URL")\n- A one-time decision that\'s already captured\n- A diagnostic tip rather than a prohibition\n\nIf a rule is warranted, read the project\'s boundary file(s) -- CLAUDE.md and/or AGENTS.md -- find the appropriate section (ALWAYS, ASK FIRST, or NEVER under Behavioral Boundaries), and append the rule. If no Behavioral Boundaries section exists, append one. Update whichever boundary files the project uses (some projects have CLAUDE.md, some have AGENTS.md, some have both).\n\n## Step 7: Confirm\n\nReport what you did in this format:\n\n```\nAdded to [document name]:\n  [summary of what was added]\n\n[If boundary file(s) were also updated:]\nAdded boundary rule to [CLAUDE.md / AGENTS.md / both]:\n  [ALWAYS/ASK FIRST/NEVER]: [rule text]\n\n[If the fact was ambiguous:]\nRouted to [chosen doc] -- move to [alternative doc] if this is more about [alternative category description].\n```\n',
-  "joycraft-bugfix.md": "---\nname: joycraft-bugfix\ndescription: Structured bug fix workflow \u2014 triage, diagnose, discuss with user, write a focused spec, hand off for implementation\n---\n\n# Bug Fix Workflow\n\nYou are fixing a bug. Follow this process in order. Do not skip steps.\n\n**Guard clause:** If this is clearly a new feature, redirect to `$joycraft-new-feature` and stop.\n\n---\n\n## Phase 1: Triage\n\nEstablish what's broken. Gather: symptom, steps to reproduce, expected vs actual behavior, when it started, relevant logs/errors. If an error message or stack trace is provided, read the referenced files immediately. Try to reproduce if steps are given.\n\n**Done when:** You can describe the symptom in one sentence.\n\n---\n\n## Phase 2: Diagnose\n\nFind the root cause. Start from the error site and trace backward. Search the codebase and read files \u2014 don't guess. Identify the specific line(s) and logic error. Check git blame if it's a recent regression.\n\n**Done when:** You can explain what's wrong, why, and where in 2-3 sentences.\n\n---\n\n## Phase 3: Discuss\n\nPresent findings to the user BEFORE writing any code or spec:\n1. **Symptom** \u2014 confirm it matches what they see\n2. **Root cause** \u2014 specific file(s) and line(s)\n3. **Proposed fix** \u2014 what changes, where\n4. **Risk** \u2014 side effects? scope?\n\nAsk: \"Does this match? Comfortable with this approach?\" If large/risky, suggest decomposing into multiple specs.\n\n**Done when:** User agrees with the diagnosis and fix direction.\n\n---\n\n## Phase 4: Spec the Fix\n\nWrite a bug fix spec to `docs/bugfixes/<area>/bugfix-name.md`. Use the relevant area as the subdirectory (e.g., `auth`, `cli`, `parser`). Lazy-create the `docs/bugfixes/<area>/` directory if it doesn't exist.\n\n(Bugfixes live under `docs/bugfixes/<area>/`, separate from `docs/features/<slug>/specs/`. Bugfixes are area-level, not feature-tied \u2014 multiple unrelated bugs accumulate in the same area folder over time, which is a fundamentally different folder shape from features.)\n\n**Area README:** When creating (or adding to) a `docs/bugfixes/<area>/` folder, also lazy-create/update a `docs/bugfixes/<area>/README.md` index \u2014 a one-line-per-bug table (`| Bug | Spec | Status | Date |`) so areas that accumulate many bugs stay navigable. Append a row for the new bugfix.\n\n**Why:** Even bug fixes deserve a spec. It forces clarity on what \"fixed\" means, ensures test-first discipline, and creates a traceable record of the fix.\n\nThe spec file MUST start with YAML frontmatter \u2014 the 4-field personal schema (the `area:` field carries the area name, used informally to indicate \"what folder this lives under\"):\n\n```yaml\n---\nstatus: active\nowner: <resolved name>\ncreated: YYYY-MM-DD\narea: <area>\n---\n```\n\n**Owner resolution:** look up the owner name in this order \u2014 (1) `git config user.name`, (2) value in your auto-memory `joycraft-owner.txt` if present, (3) ask the user once and persist.\n\nUse this structure:\n\n```markdown\n# [Bug Name] \u2014 Bug Fix Spec\n\n> **Status:** Ready\n> **Date:** YYYY-MM-DD\n> **Estimated scope:** [1 session / N files / ~N lines]\n\n---\n\n## Bug\nOne sentence \u2014 what's broken?\n\n## Root Cause\nWhat's actually wrong, in which file(s) and line(s)?\n\n## Fix\nWhat changes, where?\n\n## Acceptance Criteria\n- [ ] [Observable behavior that proves the fix works]\n- [ ] No regressions \u2014 existing tests still pass\n- [ ] Build passes\n\n## Test Plan\n1. Write a reproduction test that fails before the fix\n2. Apply the fix\n3. Reproduction test passes\n4. Full test suite passes\n\n## Constraints\n- MUST: [hard requirement]\n- MUST NOT: [hard prohibition]\n\n## Affected Files\n| Action | File | What Changes |\n|--------|------|-------------|\n\n## Edge Cases\n| Scenario | Expected Behavior |\n|----------|------------------|\n```\n\n**For large bugs that span multiple files/systems:** Consider whether this should be decomposed into multiple specs. If so, create a brief first using `$joycraft-new-feature`, then decompose.\n\n---\n\n## Phase 5: Hand Off\n\n```\nBug fix spec is ready: docs/bugfixes/<area>/bugfix-name.md\n\nSummary:\n- Bug: [one sentence]\n- Root cause: [one sentence]\n- Fix: [one sentence]\n- Estimated: 1 session\n\nTo execute: Start a fresh session and:\n1. Read the spec\n2. Write the reproduction test (must fail)\n3. Apply the fix (test must pass)\n4. Run full test suite\n5. Run $joycraft-session-end to capture discoveries\n6. Commit and PR\n\nReady to start?\n\nRun /clear before your next step \u2014 your artifacts are saved to files.\n```\n",
-  "joycraft-collaborative-setup.md": '---\nname: joycraft-collaborative-setup\ndescription: Set up Joycraft for a team \u2014 scaffold per-area folders, owner conventions, and a team-facing CONTRIBUTING doc. Run once when adopting Joycraft on a multi-dev project.\n---\n\n# Collaborative Setup\n\nYou are setting up Joycraft for a team. Solo defaults stay solo; this skill adds the team-only ceremony \u2014 `docs/areas/` folders, area README/boundaries, and a thin team-facing CONTRIBUTING-joycraft doc.\n\nThis skill is **interactive** \u2014 ask the user, don\'t auto-detect.\n\n## When to run\n\nRun once when a team is adopting Joycraft on a multi-dev project. Solo users do **not** need this skill \u2014 solo defaults are fine without it.\n\n## Step 1: Confirm Team Context\n\nAsk the user:\n\n> "Setting up Joycraft for a team? (vs. solo work) If you\'re unsure, you can skip \u2014 solo defaults work fine and you can run this later."\n\nIf the user says "actually solo," bail before any writes:\n\n> "No problem. The solo workflow needs no extra setup. Run `$joycraft-new-feature` when you want to start a feature."\n\n## Step 2: Check for Flat Layout \u2014 Bail if Present\n\nBefore scaffolding team structure, check the project\'s docs/ for per-feature artifacts. Look for any of:\n\n- `docs/features/<slug>/brief.md`\n- `docs/features/<slug>/research.md`\n- `docs/features/<slug>/design.md`\n- Loose spec subdirectories that predate the per-feature layout (specs not under `docs/features/<slug>/specs/` or `docs/bugfixes/<area>/`)\n\nIf any **flat layout** artifacts exist, tell the user:\n\n> "I see flat-layout artifacts in your docs/ (briefs/research/designs). Run `npx joycraft upgrade` first \u2014 it will migrate them into `docs/features/<slug>/` automatically. Then re-run this skill."\n\nThen stop. Skills don\'t reliably shell out, so the CLI does the migration.\n\n## Step 3: Gather Areas + Owners (Interactive)\n\nAsk the user:\n\n> "How many areas does your team work in? (e.g., `auth`, `api`, `frontend`, `infra`) \u2014 pick names that match how your team thinks about ownership. You can also skip and just create the team CONTRIBUTING doc."\n\nFor each area name the user provides:\n1. Confirm the name (kebab-case).\n2. Ask: "Who owns this area? (a name, an email, or a team handle \u2014 used in the area README\'s frontmatter)"\n3. Ask (optional): "Are there NEVER or ASK FIRST rules specific to this area? If yes, list them; if no, skip."\n\nIf the user provides duplicate names, ask them to pick a different one. Track the area list in your working memory before writing anything.\n\nIf the user provides 0 areas, skip Step 4 and go straight to Step 5 (CONTRIBUTING doc only). Useful path for "we just want the team doc, no areas yet."\n\n## Step 4: Scaffold Each Area\n\nFor each confirmed area, lazy-create `docs/areas/<area-name>/` and write a `README.md` with the **shared frontmatter schema** (areas are shared docs, not personal):\n\n```yaml\n---\nlast_updated: YYYY-MM-DD\nlast_updated_by: <owner from step 3>\n---\n```\n\n**Owner resolution for `last_updated_by`:** look up the owner name in this order \u2014 (1) `git config user.name`, (2) value in your auto-memory `joycraft-owner.txt` if present, (3) ask the user once and persist. Use the user-provided owner from Step 3 if they specified one for this area.\n\nBody of `README.md`:\n\n```markdown\n# <area-name>\n\n> **Owner:** <name from Step 3>\n> **Status:** active\n\n## What this area covers\n\n(Filled in by the area owner)\n\n## Conventions\n\n(Area-specific patterns or constraints)\n\n## Onboarding\n\nWhen a new dev joins this area, they should:\n1. Read this README\n2. Read `boundaries.md` (if present)\n3. Read the codebase under <area-relevant paths>\n```\n\nIf the user provided NEVER / ASK FIRST rules for the area, also write `docs/areas/<area-name>/boundaries.md` with the shared frontmatter and those rules. If they didn\'t, skip the boundaries file \u2014 the root CLAUDE.md boundaries already cover the project-wide cases.\n\n**Idempotency:** if `docs/areas/<area-name>/README.md` already exists, ASK before overwriting (default: skip + inform).\n\n## Step 5: Write the Team CONTRIBUTING Doc\n\nLazy-create `docs/CONTRIBUTING-joycraft.md` (NOT the project\'s main `CONTRIBUTING.md` \u2014 keep them separate so neither stomps on the other).\n\nIf `docs/templates/CONTRIBUTING-joycraft-template.md` exists in the project (it should \u2014 bundled by `npx joycraft init`), use it as the starting point. If not, fall back to the inline template below.\n\nThe doc starts with shared frontmatter:\n\n```yaml\n---\nlast_updated: YYYY-MM-DD\nlast_updated_by: <resolved owner>\n---\n```\n\nBody (inline fallback template \u2014 short by design):\n\n```markdown\n# Joycraft on this project\n\nWe use [Joycraft](https://www.npmjs.com/package/joycraft) for AI-assisted development.\n\n## How our team uses it\n\n(Filled in during $joycraft-collaborative-setup \u2014 fill this in with your team\'s specific conventions.)\n\n## Conventions\n\n- Per-feature work goes under `docs/features/<slug>/`\n- Area-level work and ownership: see `docs/areas/`\n- For "what is Joycraft?", see the package README\n\n## Onboarding\n\nWhen a new dev joins:\n1. Run `npx joycraft init` (idempotent on already-set-up projects)\n2. Read `docs/areas/<your-area>/README.md` for context\n```\n\nIf `docs/CONTRIBUTING-joycraft.md` already exists, ASK before overwriting \u2014 offer overwrite / append / skip; default to skip.\n\n## Step 6: Trigger CLAUDE.md Update\n\nNow that `docs/areas/` exists, the next `npx joycraft upgrade` (or any future `npx joycraft init`) will pick it up and add the **Areas pointer** to CLAUDE.md automatically \u2014 that pointer tells Claude "when working on the X area, read docs/areas/X/README.md first."\n\nTell the user:\n\n> "Run `npx joycraft upgrade` to refresh CLAUDE.md with the Areas pointer (or `npx joycraft init` if you haven\'t initialized yet)."\n\nDon\'t try to shell out from inside the skill \u2014 let the user run the CLI deliberately.\n\n## Step 7: Hand Off\n\nSummarize what you wrote (paths to area READMEs, the CONTRIBUTING doc, any boundaries files), then emit the canonical Handoff block.\n\n## Recommended Next Steps\n\nNext:\n```bash\n$joycraft-new-feature\n```\nRun /clear first.\n\nInclude the path to `docs/CONTRIBUTING-joycraft.md` and any newly-created area READMEs in the summary above the Handoff block.\n\n## Notes\n\n- This skill does NOT migrate flat-layout artifacts on its own. That\'s `npx joycraft upgrade`\'s job \u2014 Step 2 directs the user to run it first.\n- Area names are user-provided. Don\'t auto-detect from `src/auth/`, `src/api/`, etc. \u2014 many projects have monorepo or non-conventional layouts and auto-detection produces noise.\n- If the user stops mid-way (Ctrl-C, abandons), whatever\'s been written stays. Re-running the skill is the recovery path; it\'s idempotent on existing area folders (asks before overwriting).\n',
-  "joycraft-decompose.md": '---\nname: joycraft-decompose\ndescription: Break a feature brief into atomic specs \u2014 small, testable, independently executable units\n---\n\n# Decompose Feature into Atomic Specs\n\nYou have a Feature Brief (or the user has described a feature). Your job is to decompose it into atomic specs that can be executed independently \u2014 one spec per session.\n\n## Step 1: Verify the Brief Exists\n\nLook for a Feature Brief at `docs/features/<slug>/brief.md`. If the user provided a brief path as an argument, use that. Otherwise, scan `docs/features/*/brief.md`.\n\n**Status filter when scanning neighbor briefs and specs:** read the YAML frontmatter at the top of each file. Treat each as **live** unless its `status:` is `done`, `deprecated`, or `superseded` \u2014 those three are the only states you **skip / ignore**. Every other state is live and must be considered. The status vocabulary is `todo \u2192 in-review \u2192 done` (see `docs/reference/spec-status-lifecycle.md`); both `todo` and `in-review` are live. An `in-review` spec is finished-but-unverified work that still constrains neighboring decomposition, so it stays in scope. Also ignore anything under `docs/archive/` entirely.\n\nIf one doesn\'t exist yet, tell the user:\n\n> No feature brief found. Run `$joycraft-new-feature` first to interview and create one, or describe the feature now and I\'ll work from your description.\n\nIf the user describes the feature inline, work from that description directly. You don\'t need a formal brief to decompose \u2014 but recommend creating one for complex features.\n\n## Step 2: Identify Natural Boundaries\n\n**Why:** Good boundaries make specs independently testable and committable. Bad boundaries create specs that can\'t be verified without other specs also being done.\n\nRead the brief (or description) and identify natural split points:\n\n- **Data layer changes** (schemas, types, migrations) \u2014 always a separate spec\n- **Pure functions / business logic** \u2014 separate from I/O\n- **UI components** \u2014 separate from data fetching\n- **API endpoints / route handlers** \u2014 separate from business logic\n- **Test infrastructure** (mocks, fixtures, helpers) \u2014 can be its own spec if substantial\n- **Configuration / environment** \u2014 separate from code changes\n\nAsk yourself: "Can this piece be committed and tested without the other pieces existing?" If yes, it\'s a good boundary.\n\n## Step 3: Build the Decomposition Table\n\nFor each atomic spec, define:\n\n| # | Spec Name | Description | Dependencies | Size |\n|---|-----------|-------------|--------------|------|\n\n**Rules:**\n- Each spec name is `verb-object` format (e.g., `add-terminal-detection`, `extract-prompt-module`)\n- Each description is ONE sentence \u2014 if you need two, the spec is too big\n- Dependencies reference other spec numbers \u2014 keep the dependency graph shallow\n- More than 2 dependencies on a single spec = it\'s too big, split further\n- Aim for 3-7 specs per feature. Fewer than 3 = probably not decomposed enough. More than 10 = the feature brief is too big\n\n## Step 4: Present and Iterate\n\nShow the decomposition table to the user. Ask:\n1. "Does this breakdown match how you think about this feature?"\n2. "Are there any specs that feel too big or too small?"\n3. "Should any of these run in parallel (separate branches)?"\n\nIterate until the user approves.\n\n## Execution Modes (assign a mode per spec)\n\nEvery spec carries an **execution mode** that controls how `$joycraft-implement` wraps up after building it. Assign one to each spec \u2014 recommended by you, **approved by the human** (never silent).\n\n| Mode | Per-spec wrap-up | Context between specs | Best for |\n|------|------------------|-----------------------|----------|\n| `batch` | implement all, wrap once at the end (one `$joycraft-session-end`) | shared (one conversation) | clusters of tiny specs |\n| `checkpoint` | `$joycraft-spec-done` after each (commit + status bump), keep going | shared | medium specs wanting atomic commits without fresh context |\n| `isolated` | `$joycraft-spec-done`, then a **fresh context**, then the next spec | fresh per spec | heavy specs that would pollute one context |\n\n**Project default.** Read the default mode from the project\'s `CLAUDE.md`: look for a line `**Default execution mode:** <mode>`. If that line is **absent, default to `batch`** (the safest: shared context, wrap once). Do not hard-fail when it\'s missing \u2014 just use `batch` and say so in your recommendation.\n\n**Size \u2192 mode heuristic** (a starting recommendation, not a rule):\n\n| Spec size | Recommended mode |\n|-----------|------------------|\n| XS / S | `batch`-eligible (fold into the batch) |\n| M | `checkpoint` |\n| L / XL | `isolated` |\n\nSize is your estimate from the spec\'s scope (files touched, surface area, risk). The heuristic is only a starting point: a tiny spec inside a risky feature may still warrant `isolated`, and only the human knows that \u2014 which is why the recommendation is **approved, not auto-applied**.\n\n**Surface the recommendation and get approval.** Before writing any spec files, present your per-spec mode recommendation and wait for the human\'s OK. Worked example:\n\n> Your project defaults to `batch` (no `**Default execution mode:**` line in CLAUDE.md, so I\'m using the safe default). Based on size, I recommend: specs 1, 2 \u2192 `batch`; spec 5 \u2192 `checkpoint`; specs 7, 8 \u2192 `isolated` (large/risky). OK, or adjust?\n\nIf the human overrides any recommendation, **honor their choice verbatim** in both the frontmatter and the queue. Record the approved mode in each spec\'s `mode:` frontmatter field (Step 5) and in each queue entry\'s `"mode"` field (Step 5a). A feature may mix modes across its specs \u2014 that\'s expected. This applies even when there\'s no brief and the feature was described inline: still assign a mode to every spec, and the CLAUDE.md default applies the same way.\n\n## Step 5: Generate Atomic Specs\n\nFor each approved row, create `docs/features/<slug>/specs/<spec-name>.md`. The slug is the feature folder name (e.g., `2026-04-06-token-discipline`). If no brief exists and the user described the feature inline, derive a kebab-case slug yourself: `YYYY-MM-DD-<short-name>`. Lazy-create `docs/features/<slug>/specs/` if it doesn\'t exist.\n\n**Why:** Each spec must be self-contained \u2014 a fresh session should be able to execute it without reading the Feature Brief. Copy relevant constraints and context into each spec.\n\nEach spec file MUST start with YAML frontmatter:\n\n```yaml\n---\nstatus: todo\nowner: <resolved name>\ncreated: YYYY-MM-DD\nfeature: <slug>\nmode: <approved mode \u2014 batch | checkpoint | isolated>\n---\n```\n\nNew specs always start at `status: todo` (the canonical first state \u2014 see `docs/reference/spec-status-lifecycle.md`). The `mode:` value is the human-approved execution mode from the Execution Modes step above.\n\nUse this structure for the body:\n\n```markdown\n# [Verb + Object] \u2014 Atomic Spec\n\n> **Parent Brief:** `docs/features/<slug>/brief.md` (or "standalone")\n> **Status:** Ready\n> **Date:** YYYY-MM-DD\n> **Estimated scope:** [1 session / N files / ~N lines]\n\n---\n\n## What\nOne paragraph \u2014 what changes when this spec is done?\n\n## Why\nOne sentence \u2014 what breaks or is missing without this?\n\n## External API Contract\n\n_Include this section ONLY when the spec touches a third-party SDK, package, or service API. Omit it entirely otherwise._\n\n**Package:** `<npm-package-name>`\n\n**Canonical sources:**\n- <link to docs>\n- <link to types>\n\n**Key API facts (validated against vX.Y.Z):**\n- <fact 1>\n- <fact 2>\n\n\n## Acceptance Criteria\n- [ ] [Observable behavior]\n- [ ] Build passes\n- [ ] Tests pass\n\n## Test Plan\n\n| Acceptance Criterion | Test | Type |\n|---------------------|------|------|\n| [Each AC above] | [What to call/assert] | [unit/integration/e2e] |\n\n**Execution order:**\n1. Write all tests above \u2014 they should fail against current/stubbed code\n2. Run tests to confirm they fail (red)\n3. Implement until all tests pass (green)\n\n**Smoke test:** [Identify the fastest test for iteration feedback]\n\n**Before implementing, verify your test harness:**\n1. Run all tests \u2014 they must FAIL (if they pass, you\'re testing the wrong thing)\n2. Each test calls your actual function/endpoint \u2014 not a reimplementation or the underlying library\n3. Identify your smoke test \u2014 it must run in seconds, not minutes, so you get fast feedback on each change\n\n## Constraints\n- MUST: [hard requirement]\n- MUST NOT: [hard prohibition]\n\n## Affected Files\n| Action | File | What Changes |\n|--------|------|-------------|\n\n## Approach\nStrategy, data flow, key decisions. Name one rejected alternative.\n\n## Edge Cases\n| Scenario | Expected Behavior |\n|----------|------------------|\n```\n\nIf `docs/templates/ATOMIC_SPEC_TEMPLATE.md` exists, reference it for the full template with additional guidance.\n\nFill in all sections \u2014 each spec must be self-contained (no "see the brief for context"). Copy relevant constraints from the Feature Brief into each spec. Write acceptance criteria specific to THIS spec, not the whole feature. Every acceptance criterion must have at least one corresponding test in the Test Plan. If the user provided test strategy info from the interview, use it to choose test types and frameworks. Include the test harness verification rules in every Test Plan.\n\n### Step 5a: Write the Spec Queue Manifest\n\nAfter all spec `.md` files are written, create `.joycraft-spec-queue.json` in the specs directory alongside the spec files and README. This manifest is the machine-readable, authoritative spec queue consumed by the Pi pipeline automation.\n\n```json\n{\n  "feature": "<slug>",\n  "specs": [\n    { "id": 1, "file": "<spec-name>.md", "depends_on": [], "status": "todo", "mode": "batch" },\n    { "id": 2, "file": "<spec-name>.md", "depends_on": [1], "status": "todo", "mode": "checkpoint" }\n  ]\n}\n```\n\nMap each row in your decomposition table to a spec entry:\n- `id`: sequential integer starting from 1 (matches the decomposition table\'s # column)\n- `file`: the spec filename relative to the specs directory\n- `depends_on`: array of spec ids this spec depends on (empty array `[]` for no dependencies)\n- `status`: always `"todo"` initially \u2014 the agent advances each spec to `"in-review"` via `$joycraft-spec-done`, and `$joycraft-session-end` graduates it to `"done"` (see `docs/reference/spec-status-lifecycle.md`)\n- `mode`: the human-approved execution mode for this spec (`batch` | `checkpoint` | `isolated`) \u2014 must match the spec file\'s `mode:` frontmatter\n\nValidate: every id referenced in `depends_on` must exist as an `id` in the specs array; the queue `status`/`mode` for each spec must match that spec file\'s frontmatter.\n\n## Step 6: Recommend Execution Strategy\n\nBased on the dependency graph:\n- **Independent specs** \u2014 "These can run in parallel branches"\n- **Sequential specs** \u2014 "Execute these in order: 1 -> 2 -> 4"\n- **Mixed** \u2014 "Start specs 1 and 3 in parallel. After 1 completes, start 2."\n\n**Mark each multi-spec wave\'s parallel-safety**: a wave is parallel-safe only when its specs\' Affected Files tables are disjoint; overlapping files \u2192 NOT parallel-safe, name the overlap. Record the markers in the wave plan.\n\nUpdate the Feature Brief\'s Execution Strategy section with the plan (if a brief exists).\n\n## Step 7: Hand Off\n\nTell the user:\n```\nDecomposition complete:\n- [N] atomic specs created in docs/features/<slug>/specs/\n- [N] can run in parallel, [N] are sequential\n- Estimated total: [N] sessions\n\nTo execute:\n- Whole queue: $joycraft-implement-feature docs/features/<slug>/ \u2014 runs the specs\n  in wave order with per-spec wrap-up and commits, session-end once at the end\n- One at a time: $joycraft-implement docs/features/<slug>/specs/<first-spec>.md \u2014\n  it wraps up and continues through the queue itself\n- Parallel branches: one spec per branch, merge when done (only for waves marked\n  parallel-safe)\n\nReady to start execution?\n\nRun /clear before your next step \u2014 your artifacts are saved to files.\n```\n',
-  "joycraft-design.md": '---\nname: joycraft-design\ndescription: Design discussion before decomposition \u2014 produce a ~200-line design artifact for human review, catching wrong assumptions before they propagate into specs\n---\n\n# Design Discussion\n\nYou are producing a design discussion document for a feature. This sits between research and decomposition \u2014 it captures your understanding so the human can catch wrong assumptions before specs are written.\n\n**Guard clause:** If no brief path is provided and no brief exists at `docs/features/<slug>/brief.md`, say:\n"No feature brief found. Run `$joycraft-new-feature` first to create one, or provide the path to your brief."\nThen stop.\n\n---\n\n## Step 1: Read Inputs\n\nRead the feature brief at the path the user provides. If the user also provides a research document path, read that too.\n\n## Step 2: Explore the Codebase\n\nSpawn concurrent subagent threads to explore the codebase for patterns relevant to the brief. Focus on:\n\n- Files and functions that will be touched or extended\n- Existing patterns this feature should follow\n- Similar features already implemented that serve as models\n- Boundaries and interfaces the feature must integrate with\n\nEach subagent should search the codebase and read files to gather file paths, function signatures, and code snippets.\n\n## Step 3: Write the Design Document\n\nWrite to `docs/features/<slug>/design.md`. Lazy-create `docs/features/<slug>/` if it doesn\'t exist.\n\nThe document has exactly five sections:\n\n### Section 1: Current State\nWhat exists today in the codebase. Include file paths, function signatures, data flows. Be specific.\n\n### Section 2: Desired End State\nWhat the codebase should look like when this feature is complete.\n\n### Section 3: Patterns to Follow\nExisting patterns in the codebase that this feature should match. Include code snippets and `file:line` references.\n\n### Section 4: Resolved Design Decisions\nDecisions made with rationale. Format: Decision, Rationale, Alternative rejected.\n\n### Section 5: Open Questions\nThings where multiple valid approaches exist. Each question MUST present 2-3 concrete options with pros and cons.\n\n### Update the Feature Brief\n\nAfter writing the design document, update the parent brief with a back-reference:\n1. Read `docs/features/<slug>/brief.md`\n2. In the header blockquote (the `>` lines at the top), add or update:\n   `> **Design:** docs/features/<slug>/design.md`\n3. If a `> **Design:**` line already exists, replace it \u2014 do NOT add a duplicate\n4. Write the brief back\n\n## Step 4: Present and STOP\n\nPresent the design document. Say:\n```\nDesign discussion written to docs/features/<slug>/design.md\n\nPlease review. Specifically:\n1. Are the patterns in Section 3 right?\n2. Do you agree with the resolved decisions?\n3. Pick an option for each open question.\n\nReply with your feedback. I will NOT proceed to decomposition until you have reviewed and approved.\n```\n\n**CRITICAL: Do NOT proceed to `$joycraft-decompose` or generate specs.** Wait for human review.\n\n## After Human Review\n\n- Update the design document with corrections\n- Move answered questions to Resolved Design Decisions\n- Present for final confirmation\n- Only after explicit approval: "Design approved. Run `$joycraft-decompose` with this brief to generate atomic specs."\n',
-  "joycraft-gather-context.md": "---\nname: joycraft-gather-context\ndescription: First-run onboarding pass that populates the project context layer -- read what context already exists, then offer a gap-only interview and batch-write the missing fact rows and long-form reference docs\n---\n\n# Gather Context\n\nThis is the first-run **read-then-offer** onboarding pass \u2014 the lowest-intervention way to populate the project's context layer. You read what context already exists, summarize coverage, offer a gap-only interview, and write everything in one reviewable batch at the end.\n\nThis skill is self-contained. It composes the same conventions the single-doc skills use, but everything you need is inlined below \u2014 do not call into or import another skill's logic.\n\n## Step 1: Read What Already Exists First\n\nThe user has invoked the first-run onboarding pass (e.g., `$joycraft-gather-context`). Before asking the user anything, scan the project's existing context. Default scan breadth is **README + `docs/` + the project boundary file only**:\n\n- The README(s) at the repo root and any obvious sub-package READMEs.\n- `docs/**` \u2014 existing design, architecture, or style docs.\n- `docs/context/*` \u2014 the flat operational fact-docs (production-map, dangerous-assumptions, decision-log, institutional-knowledge, troubleshooting) and `docs/context/reference/*` long-form docs.\n- The current boundary-file content \u2014 CLAUDE.md and/or AGENTS.md, whichever the project uses \u2014 including any `## Context Map` section.\n\nThen summarize for the user what context already exists and what's covered.\n\n**Do NOT auto-run a code-inference scan.** Reading the actual source to infer architecture costs significantly more tokens. Offer that deeper/full review ONLY if the user explicitly asks for it, and when you do, note clearly that it costs more tokens. The default pass never reads the codebase to infer context.\n\n## Step 2: Offer a Gap-Only Interview (Don't Force)\n\nFrom the summary, identify genuine gaps: no design-system doc? no production map? no decision log? Offer an **optional** interview that targets only those gaps. The user can decline any or all of it \u2014 offer, never force.\n\n**Per-doc skip guard (not all-or-nothing):** Never re-interview for a doc that already has real content. Skip each doc that's already populated individually, and interview only the empty or missing ones. If everything is already covered, say so and offer nothing.\n\n## Step 3: Route by Shape (Inline Test)\n\nFor each thing the user wants to capture, apply this minimal shape test inline \u2014 do not defer to another skill:\n\n- **\"Could this be one row in a table?\"** \u2192 it's an **operational fact**. Route it to one of the five flat fact-docs under `docs/context/`:\n  - `docs/context/production-map.md` \u2014 infrastructure, services, environments, URLs, credentials, safe/unsafe to touch.\n  - `docs/context/dangerous-assumptions.md` \u2014 false assumptions an agent might make.\n  - `docs/context/decision-log.md` \u2014 an architectural/tooling choice and why.\n  - `docs/context/institutional-knowledge.md` \u2014 team conventions, unwritten rules, ownership.\n  - `docs/context/troubleshooting.md` \u2014 when X happens, do Y.\n  Append it as a table row (or list item for institutional-knowledge), removing any italic example rows in that table first.\n\n- **\"Does explaining it take paragraphs?\"** \u2192 it's **long-form reference**. Scaffold `docs/context/reference/<slug>.md` from the matching template in `docs/templates/context/reference/` (`design-system`, `frontend-methodology`, `backend`, `testing`, or the generic `reference-doc` fallback), lazy-creating `docs/context/reference/` on first write.\n\nIf an item is ambiguous, apply the test literally: one row \u2192 fact bucket; paragraphs \u2192 reference doc.\n\n## Step 4: Batch-Write + One Final Confirm\n\nDo NOT write per-answer. Collect ALL of the user's gap answers across the whole interview first. Then, in ONE batch:\n\n1. Write all the fact rows into their fact-docs.\n2. Scaffold and write all the reference docs into `docs/context/reference/`.\n3. Add or update the `## Context Map` pointer rows in the project boundary file (CLAUDE.md and/or AGENTS.md) \u2014 one row per reference doc, in the form `| docs/context/reference/<slug>.md | <when to read it> |`. Create the `## Context Map` section (header + two-column table) if it doesn't exist; update an existing row in place rather than duplicating it.\n\nPresent the full set of intended changes and get ONE final confirm (\"do it in one go\") before writing. If the user aborts at the final confirm, write nothing \u2014 there are no partial writes in this batch model. The result is one clean, reviewable diff.\n\n## Step 5: Confirm\n\nReport the batch: which fact rows were added, which reference docs were scaffolded, and which Context Map rows were created or updated.\n",
-  "joycraft-implement-feature.md": "---\nname: joycraft-implement-feature\ndescription: Run a feature's entire spec queue from one invocation \u2014 sequential chain with per-spec wrap-up, fail-fast, session-end once at the end\n---\n\n# Implement Feature (Whole-Queue Driver)\n\nOne invocation runs a feature's whole spec queue: `$joycraft-implement-feature docs/features/<slug>/`. You drive the queue **sequentially in this conversation** \u2014 Codex has no subagent boundary to give each spec a fresh context, so the chain shares context and compensates with disciplined per-spec wrap-ups. This is ordinary interactive use \u2014 one human invocation, no headless loop, no ToS/cost caveat.\n\n> **Context honesty:** for queues of heavy `isolated`-mode specs, a shared-context chain is the wrong tool \u2014 true per-spec isolation comes from Pi's `joycraft-implement-loop` (fresh process per spec) or guided-manual (`/new` + re-invoke per spec). Say so up front when you see a queue dominated by `isolated` specs, then proceed only if the user confirms.\n\n## Step 1: Load the Queue\n\n1. Resolve the specs directory: if the given path contains a `specs/` subdirectory, use it; otherwise use the path itself. Look for `.joycraft-spec-queue.json` there.\n2. **No queue** \u2192 stop:\n\n   > No spec queue found in [path]. Run `$joycraft-decompose` first \u2014 it writes the queue, the specs, and the wave plan.\n\n3. Read the sibling `README.md` (the wave plan) for the intended order. Waves marked parallel-safe still run sequentially here \u2014 parallelism needs isolation this harness chain doesn't have.\n4. Report the plan before starting: feature slug, M specs, current statuses, the order you'll run them in. If the queue is dominated by `isolated` specs, surface the context-honesty note above and get a confirmation.\n5. If **no `todo` specs remain**, skip to Step 4 and say why.\n\n## Step 2: The Chain \u2014 One Spec at a Time\n\nRepeat until no `todo` specs remain:\n\n1. **Find the next ready spec**: the first `todo` whose `depends_on` are all `in-review`/`done` (read the queue JSON).\n2. **None ready but `todo` specs remain** \u2192 fail-fast (Step 3): report which specs are blocked and on what.\n3. **Execute the spec** by following `.agents/skills/joycraft-implement/SKILL.md` end to end \u2014 strict TDD (failing tests first, implement until green, every Acceptance Criterion met), then its per-spec wrap-up: bump to `in-review` in BOTH the queue JSON and the spec's frontmatter, terse discovery stub only if surprised, commit `spec: <spec-name>`. (Treat `isolated` specs the user approved into this chain as `checkpoint`.)\n4. **Verify before advancing**: queue shows `in-review`, `git log` shows the `spec:` commit, tests green. Anything off \u2192 fail-fast (Step 3).\n5. Report one line \u2014 `Spec complete: <name> (spec N of M)` \u2014 and continue.\n\n## Step 3: Fail-Fast\n\nWhen a spec fails (tests not green, or all remaining specs are blocked):\n\n- **Stop the chain.** Start no further specs.\n- Report: which spec failed and why, what reached `in-review`, what remains `todo`. Leave the queue exactly as it is \u2014 never mark anything to cover a failure.\n- Suggest the recovery path: fix in a fresh conversation (`/new`, then `$joycraft-implement <failed-spec>`), then re-run `$joycraft-implement-feature` for the remainder.\n\n## Step 4: Finish \u2014 Session-End Once\n\nWhen no `todo` specs remain, run the once-per-feature finisher yourself: read and follow `.agents/skills/joycraft-session-end/SKILL.md`. It owns the gates the chain deliberately skipped: full validation (must pass before anything graduates `in-review \u2192 done`), discovery consolidation, and push/PR per the project's AGENTS.md/CLAUDE.md git autonomy rules.\n\n## Final Report\n\n```\nFeature run: <slug>\n- Specs completed: N of M (now in-review/done) \xB7 failures: [none | <spec> \u2014 <reason>]\n- Session-end: [ran \u2014 see its report | skipped: <reason>]\n- Discoveries: [n stubs consolidated | none]\n```\n",
-  "joycraft-implement-level5.md": "---\nname: joycraft-implement-level5\ndescription: Set up Level 5 autonomous development \u2014 autofix loop, holdout scenario testing, and scenario evolution from specs\n---\n\n# Implement Level 5 \u2014 Autonomous Development Loop\n\nYou are guiding the user through setting up Level 5: the autonomous feedback loop where specs go in, validated software comes out. This is a one-time setup that installs workflows, creates a scenarios repo, and configures the autofix loop.\n\n## Before You Begin\n\nCheck prerequisites:\n\n1. **Project must be initialized.** Search for `.claude/.joycraft/state.json` (older installs may still have a legacy `.joycraft-version` at the repo root). If neither exists, tell the user to run `npx joycraft init` first.\n2. **Project should be at Level 4.** Read `docs/joycraft-assessment.md` if it exists. If the project hasn't been assessed yet, suggest running `$joycraft-tune` first. But don't block -- the user may know they're ready.\n3. **Git repo with GitHub remote.** This setup requires GitHub Actions. Check for `.git/` and a GitHub remote.\n\nIf prerequisites aren't met, explain what's needed and stop.\n\n## Step 1: Explain What Level 5 Means\n\nTell the user:\n\n> Level 5 is the autonomous loop. When you push specs, three things happen automatically:\n>\n> 1. **Scenario evolution** -- An AI agent reads your specs and writes holdout tests in a private scenarios repo. These tests are invisible to your coding agent.\n> 2. **Autofix** -- When CI fails on a PR, the agent automatically attempts a fix (up to 3 times).\n> 3. **Holdout validation** -- When CI passes, your scenarios repo runs behavioral tests against the PR. Results post as PR comments.\n>\n> The key insight: your coding agent never sees the scenario tests. This prevents it from gaming the test suite -- like a validation set in machine learning.\n\n## Step 2: Gather Configuration\n\nAsk these questions **one at a time**:\n\n### Question 1: Scenarios repo name\n\n> What should we call your scenarios repo? It'll be a private repo that holds your holdout tests.\n>\n> Default: `{current-repo-name}-scenarios`\n\nAccept the default or the user's choice.\n\n### Question 2: GitHub App\n\n> Level 5 needs a GitHub App to provide a separate identity for autofix pushes (this avoids GitHub's anti-recursion protection). Creating one takes about 2 minutes:\n>\n> 1. Go to https://github.com/settings/apps/new\n> 2. Give it a name (e.g., \"My Project Autofix\")\n> 3. Uncheck \"Webhook > Active\" (not needed)\n> 4. Under **Repository permissions**, set:\n>    - **Contents**: Read & Write\n>    - **Pull requests**: Read & Write\n>    - **Actions**: Read & Write\n> 5. Click **Create GitHub App**\n> 6. Note the **App ID** from the settings page\n> 7. Scroll to **Private keys** > click **Generate a private key** > save the `.pem` file\n> 8. Click **Install App** in the left sidebar > install it on your repo\n>\n> What's your App ID?\n\n## Step 3: Run init-autofix\n\nRun the CLI command with the gathered configuration:\n\n```bash\nnpx joycraft init-autofix --scenarios-repo {name} --app-id {id}\n```\n\nReview the output with the user. Confirm files were created.\n\n## Step 4: Walk Through Secret Configuration\n\nGuide the user step by step:\n\n### 4a: Add Secrets to Main Repo\n\n> You should already have the `.pem` file from when you created the app in Step 2.\n\n> Go to your repo's Settings > Secrets and variables > Actions, and add:\n> - `JOYCRAFT_APP_PRIVATE_KEY` -- paste the contents of your `.pem` file\n> - `ANTHROPIC_API_KEY` -- your Anthropic API key (or the appropriate AI provider key for your setup)\n\n### 4b: Create the Scenarios Repo\n\n> Create the private scenarios repo:\n> ```bash\n> gh repo create {scenarios-repo-name} --private\n> ```\n>\n> Then copy the scenario templates into it:\n> ```bash\n> cp -r docs/templates/scenarios/* ../{scenarios-repo-name}/\n> cd ../{scenarios-repo-name}\n> git add -A && git commit -m \"init: scaffold scenarios repo from Joycraft\"\n> git push\n> ```\n\n### 4c: Add Secrets to Scenarios Repo\n\n> The scenarios repo also needs the App private key:\n> - `JOYCRAFT_APP_PRIVATE_KEY` -- same `.pem` file as the main repo\n> - `ANTHROPIC_API_KEY` -- same key (needed for scenario generation)\n\n## Step 5: Verify Setup\n\nHelp the user verify everything is wired correctly:\n\n1. **Check workflow files exist:** `ls .github/workflows/autofix.yml .github/workflows/scenarios-dispatch.yml .github/workflows/spec-dispatch.yml .github/workflows/scenarios-rerun.yml`\n2. **Check scenario templates were copied:** Verify the scenarios repo has `example-scenario.test.ts`, `workflows/run.yml`, `workflows/generate.yml`, `prompts/scenario-agent.md`\n3. **Check the App ID is correct** in the workflow files (not still a placeholder)\n\n## Step 6: Update AGENTS.md\n\nIf the project's AGENTS.md doesn't already have an \"External Validation\" section, add one:\n\n> ## External Validation\n>\n> This project uses holdout scenario tests in a separate private repo.\n>\n> ### NEVER\n> - Access, read, or reference the scenarios repo\n> - Mention scenario test names or contents\n> - Modify the scenarios dispatch workflow to leak test information\n>\n> The scenarios repo is deliberately invisible to you. This is the holdout guarantee.\n\n## Step 7: First Test (Optional)\n\nIf the user wants to test the loop:\n\n> Want to do a quick test? Here's how:\n>\n> 1. Write a simple spec in `docs/features/<slug>/specs/` and push to main -- this triggers scenario generation\n> 2. Create a PR with a small change -- when CI passes, scenarios will run\n> 3. Watch for the scenario test results as a PR comment\n>\n> Or deliberately break something in a PR to test the autofix loop.\n\n## Step 8: Summary\n\nPrint a summary of what was set up:\n\n> **Level 5 is live.** Here's what's running:\n>\n> | Trigger | What Happens |\n> |---------|-------------|\n> | Push specs to `docs/features/<slug>/specs/` | Scenario agent writes holdout tests |\n> | PR fails CI | Autofix agent attempts a fix (up to 3x) |\n> | PR passes CI | Holdout scenarios run against PR |\n> | Scenarios update | Open PRs re-tested with latest scenarios |\n>\n> Your scenarios repo: `{name}`\n> Your coding agent cannot see those tests. The holdout wall is intact.\n\n**Important:** Tell the user:\n\n> **Before you can test the loop**, you need to merge this PR to main first. GitHub's `workflow_run` triggers only activate for workflows that exist on the default branch. Once merged, create a new PR with any small change -- that's when you'll see Autofix, Scenarios Dispatch, and Spec Dispatch fire for the first time.\n\nUpdate `docs/joycraft-assessment.md` if it exists -- set the Level 5 score to reflect the new setup.\n",
-  "joycraft-implement.md": "---\nname: joycraft-implement\ndescription: Execute atomic specs with TDD \u2014 read spec, write failing tests, implement until green, hand off to session-end\n---\n\n# Implement Atomic Spec\n\nYou have exactly one atomic spec file to execute. Your job is to implement it using strict TDD \u2014 tests first, confirm they fail, then implement until green.\n\n## Step 1: Parse Arguments\n\nThe user MUST provide a path. No path = stop immediately.\n\n**If no path was provided:**\n\n> No spec path provided. Provide a spec file or a feature directory:\n> `$joycraft-implement docs/features/<slug>/specs/spec-name.md`\n> or `$joycraft-implement docs/features/<slug>/`\n\n**If the path is a directory** (ends with `/` or does not end with `.md`):\n\nLook for `specs/.joycraft-spec-queue.json` inside that directory. Read it. Find the **first `todo` spec whose dependencies are satisfied** (a dependency is satisfied once it is `in-review` or `done`; see `docs/reference/spec-status-lifecycle.md`). This matches what `joycraft-next-spec` serves. That single spec file is your target. Do NOT read any other specs.\n\n> Using spec queue: found [spec-file-name] as the next active spec.\n\nIf the directory has no queue or no active specs:\n\n> No active specs found in [directory].\n\n**If the path is a file** ending in `.md`:\n\nUse it directly as the spec to implement.\n\n## Step 2: Read and Understand the Spec\n\n1. **Read the spec file.** The spec is your execution contract \u2014 the Acceptance Criteria and Test Plan define \"done.\"\n2. **Check the spec's Status field.** If it says \"Complete,\" warn the user and ask if they want to re-implement or skip.\n3. **Read the Acceptance Criteria** \u2014 these are your success conditions.\n4. **Read the Test Plan** \u2014 this tells you exactly what tests to write and in what order.\n5. **Read the Constraints** \u2014 these are hard boundaries you must not violate.\n\n### Finding Additional Context\n\nSpecs are designed to be self-contained, but if you need more context:\n\n- **Parent brief:** Linked in the spec's frontmatter (`> **Parent Brief:**` line). Read it for broader feature context.\n- **Related specs:** Live in the same directory. The spec directory convention is `docs/features/<slug>/specs/` where the slug is the feature folder name (e.g., `2026-04-06-token-discipline`). Bugfix specs live under `docs/bugfixes/<area>/`.\n- **Affected Files:** The spec's Affected Files table tells you which files to create or modify.\n\n\n### Before writing code against an external API:\n\n\u26A0\uFE0F If the spec references a third-party SDK or package, read its official documentation and type definitions FIRST. Never write a `declare module` stub for a package that actually exists \u2014 use the real package as a devDependency instead. The stub will make typecheck pass but the code will fail at runtime.\n\n## Step 3: Execute the TDD Cycle\n\n**This is not optional. Write tests FIRST.**\n\n### 3a. Write Tests (Red Phase)\n\nUsing the spec's Test Plan:\n\n1. Write ALL tests listed in the Test Plan. Each Acceptance Criterion must have at least one test.\n2. Tests should call the actual function/endpoint \u2014 not a reimplementation or mock of the underlying library.\n3. Run the tests. **They MUST fail.** If any test passes immediately:\n   - Flag it \u2014 either the test isn't testing the right thing, or the code already exists.\n   - Investigate before proceeding. A test that passes before implementation is a test that proves nothing.\n\n### 3b. Implement (Green Phase)\n\n1. Follow the spec's Approach section for implementation strategy.\n2. Implement the minimum code needed to make tests pass.\n3. Run tests after each meaningful change \u2014 use the spec's Smoke Test for fast feedback.\n4. Continue until ALL tests pass.\n\n### 3c. Verify Acceptance Criteria\n\nWalk through every Acceptance Criterion in the spec:\n\n- [ ] Is each one met?\n- [ ] Does the build pass?\n- [ ] Do all tests pass?\n\nIf any criterion is not met, keep implementing. Do not move on until all criteria are green.\n\n## Step 4: Handle Edge Cases\n\nCheck the spec's Edge Cases table. For each scenario:\n\n- Verify the expected behavior is handled.\n- If the spec says \"warn the user\" or \"prompt,\" make sure that path works.\n\n## Step 5: Wrap Up and Continue (mode-aware \u2014 do the wrap-up yourself)\n\nWhen the spec is implemented and all its tests pass, wrap up and advance according to the spec's **execution mode**. Read the `mode:` field from the spec's frontmatter (written by `$joycraft-decompose`). If the spec has **no `mode:` field**, default to **`batch`** (back-compat with pre-mode specs). If the value is unrecognized, treat it as `batch` and note the unrecognized value.\n\n**You perform the wrap-up. You find the next spec. Do not stop to tell the human to run `$joycraft-spec-done` or to paste the next file path \u2014 those hand-backs carry zero information and break the feature's momentum.**\n\n### 5a. Per-spec wrap-up\n\n| Spec `mode:` | Wrap-up you perform now |\n|--------------|------------------------|\n| **batch** | **Status bump only**: set the spec to `in-review` in both systems (see below). No commit, no discovery stub \u2014 batch wraps once at feature end. (The bump is required: the queue treats a dependency as satisfied at `in-review`, so without it dependent specs would look blocked.) |\n| **checkpoint** / **isolated** | The full `joycraft-spec-done` wrap-up, performed by you (canonical definition: `.agents/skills/joycraft-spec-done/SKILL.md`): **(1)** bump status to `in-review` in both systems, **(2)** terse 2-line discovery stub at `docs/discoveries/YYYY-MM-DD-topic.md` ONLY if something contradicted the spec \u2014 usually skip, **(3)** commit `spec: <spec-name>` (implementation + status edits + stub, nothing unrelated), **(4)** no validation re-run, no push, no PR \u2014 those belong to `joycraft-session-end`. |\n\n**Both systems** means: the queue JSON (`joycraft-mark-done <spec-id> --to in-review <specs-dir>` if `.pi/scripts/joycraft/` is installed, else edit `.joycraft-spec-queue.json` directly) AND the spec file's `status:` frontmatter. Never `done` \u2014 the agent doesn't self-certify (`docs/reference/spec-status-lifecycle.md`).\n\n### 5b. Continue the queue (batch and checkpoint)\n\nRe-read `.joycraft-spec-queue.json` in the spec's directory and find the next `todo` spec whose dependencies are all `in-review`/`done` (same rule as Step 1). Then:\n\n- **Next ready spec exists** \u2192 announce one line \u2014 `Continuing: <next-spec> (spec N of M)` \u2014 and go back to Step 2 with it, in this same conversation.\n- **Remaining `todo` specs are all blocked** \u2192 stop and report which specs are blocked and on what.\n- **No `todo` specs remain** \u2192 this was the feature's last spec; go to 5d.\n- **No queue** (you were invoked with a bare spec file outside a queue) \u2192 report the spec complete and stop; there is nothing to continue from.\n\n### 5c. isolated \u2014 fresh context per spec\n\nA conversation cannot clear its own context, so after the wrap-up the fresh context comes from outside:\n\n- **Guided-manual:** tell the human to clear context (`/new`), then re-invoke `$joycraft-implement <next-spec>`. (Always fine, no ToS/cost surprise.)\n- **Sequential fallback:** `$joycraft-implement-feature docs/features/<slug>/` chains the remaining specs in this conversation \u2014 momentum without isolation; fine for small remainders.\n- **Pi:** the `joycraft-implement-loop` driver automates true isolation \u2014 a fresh `pi -p` process per spec.\n- **Headless (`claude -p` / `codex exec` loop):** opt-in only. **Surface the caveat, don't bury it:** unattended headless loops draw metered, full-rate API usage and carry a ToS posture the user must **knowingly opt into** (Anthropic meters `claude -p` from a separate full-rate pool; routing subscription OAuth through third-party harnesses is prohibited). The responsible default is Pi (BYO API key / open weights). Do not silently auto-run a subscription-backed headless loop.\n\n### 5d. Feature's last spec (any mode)\n\nRun the once-per-feature finisher yourself: read and follow `.agents/skills/joycraft-session-end/SKILL.md`. It carries its own gates \u2014 validation is mandatory and must pass before specs graduate `in-review \u2192 done`, and push/PR honor the project's AGENTS.md/CLAUDE.md git autonomy rules \u2014 so running it automatically is safe.\n\n### Report\n\nAfter each spec's wrap-up, report tersely before continuing:\n\n```\nSpec complete: [spec name] \xB7 mode: [mode] \xB7 tests: [N] passing \xB7 [wrapped up + committed | status bumped (batch)]\n[Continuing: <next-spec> (spec N of M) | Feature complete \u2014 running session-end | Blocked: <specs + reasons>]\n```\n\n**Tip:** In `isolated` mode your artifacts are saved to files \u2014 the conversation context is disposable; `/new` between specs keeps each one sharp.\n",
-  "joycraft-interview.md": "---\nname: joycraft-interview\ndescription: Brainstorm freely about what you want to build \u2014 yap, explore ideas, and get a structured summary you can use later\n---\n\n# Interview \u2014 Idea Exploration\n\nYou are helping the user brainstorm and explore what they want to build. This is a lightweight, low-pressure conversation \u2014 not a formal spec process. Let them yap.\n\n## How to Run the Interview\n\n### 1. Open the Floor\n\nStart with something like:\n\"What are you thinking about building? Just talk \u2014 I'll listen and ask questions as we go.\"\n\nLet the user talk freely. Do not interrupt their flow. Do not push toward structure yet.\n\n### 2. Ask Clarifying Questions\n\nAs they talk, weave in questions naturally \u2014 don't fire them all at once:\n\n- **What problem does this solve?** Who feels the pain today?\n- **What does \"done\" look like?** If this worked perfectly, what would a user see?\n- **What are the constraints?** Time, tech, team, budget \u2014 what boxes are we in?\n- **What's NOT in scope?** What's tempting but should be deferred?\n- **What are the edge cases?** What could go wrong? What's the weird input?\n- **What exists already?** Are we building on something or starting fresh?\n\n### 3. Play Back Understanding\n\nAfter the user has gotten their ideas out, reflect back:\n\"So if I'm hearing you right, you want to [summary]. The core problem is [X], and done looks like [Y]. Is that right?\"\n\nLet them correct and refine. Iterate until they say \"yes, that's it.\"\n\n### 4. Write a Draft Brief\n\nCreate a draft file at `docs/features/<slug>/brief.md`. Create the `docs/features/<slug>/` directory if it doesn't exist.\n\nUse this format:\n\n```markdown\n# [Topic] \u2014 Draft Brief\n\n> **Date:** YYYY-MM-DD\n> **Status:** DRAFT\n> **Origin:** $joycraft-interview session\n\n---\n\n## The Idea\n[2-3 paragraphs capturing what the user described \u2014 their words, their framing]\n\n## Problem\n[What pain or gap this addresses]\n\n## What \"Done\" Looks Like\n[The user's description of success \u2014 observable outcomes]\n\n## Constraints\n- [constraint 1]\n- [constraint 2]\n\n## Open Questions\n- [things that came up but weren't resolved]\n- [decisions that need more thought]\n\n## Out of Scope (for now)\n- [things explicitly deferred]\n\n## Raw Notes\n[Any additional context, quotes, or tangents worth preserving]\n```\n\n### 5. Hand Off\n\nAfter writing the draft, tell the user:\n\n```\nDraft brief saved to docs/features/<slug>/brief.md\n\nWhen you're ready to move forward, pick the path that fits the complexity:\n\nCOMPLEX (5+ files, architectural decisions, unfamiliar area):\n  $joycraft-new-feature \u2192 $joycraft-research \u2192 $joycraft-design \u2192 $joycraft-decompose\n\nMEDIUM (clear scope but non-trivial):\n  $joycraft-new-feature \u2192 $joycraft-design \u2192 $joycraft-decompose\n\nSIMPLE (scope is clear, < 5 files, well-understood area):\n  $joycraft-new-feature \u2192 $joycraft-decompose\n\nNot sure yet? Just keep brainstorming \u2014 run $joycraft-interview again anytime.\n\nRun /clear before your next step \u2014 your artifacts are saved to files.\n```\n\nIf the idea sounds complex \u2014 touches many files, involves architectural decisions, or the user is working in an unfamiliar area \u2014 nudge them toward research and design. But present it as a recommendation, not a gate.\n\n## Guidelines\n\n- **This is NOT $joycraft-new-feature.** Do not push toward formal briefs, decomposition tables, or atomic specs. The point is exploration.\n- **Let the user lead.** Your job is to listen, clarify, and capture \u2014 not to structure or direct.\n- **Mark everything as DRAFT.** The output is a starting point, not a commitment.\n- **Keep it short.** The draft brief should be 1-2 pages max. Capture the essence, not every detail.\n- **Multiple interviews are fine.** The user might run this several times as their thinking evolves. Each creates a new dated draft.\n",
+  "joycraft-add-context.md": '---\nname: joycraft-add-context\ndescription: Author one long-form reference doc -- a design system, frontend/backend methodology, testing conventions, or any other long-form reference doc -- scaffolding it from a template and wiring a pointer into AGENTS.md\'s Context Map\n---\n\n# Add Context\n\nThe user wants to author ONE long-form reference doc \u2014 a design system, a frontend or backend methodology, testing conventions, or any other long-form reference for this project. Your job is to scaffold that doc from the matching template, fill in what the user has told you, write it immediately, and wire a pointer row into AGENTS.md\'s `## Context Map`.\n\nThis is the single-doc primitive. Write-as-you-go is correct here: you scaffold and write ONE doc per invocation, immediately \u2014 not a batch.\n\nThis skill is self-contained. Everything you need is below; do not call into or import another skill\'s logic.\n\n## Step 1: Determine Topic and Slug\n\nFigure out what reference doc the user wants. If they named it (e.g., `$joycraft-add-context our design system`), use that. Otherwise ask: "What reference doc do you want to author?" \u2014 then wait.\n\nDerive a kebab-case `<slug>` from the topic (e.g., "our design system" \u2192 `design-system`, "payments service backend" \u2192 `payments-backend`).\n\n## Step 2: Pick the Matching Template\n\nChoose the bundled template in `docs/templates/context/reference/` that best fits the topic:\n\n| Topic | Template |\n|-------|----------|\n| Design system, tokens, components, visual language | `design-system.md` |\n| Frontend architecture, state, folder conventions, patterns | `frontend-methodology.md` |\n| Service boundaries, API conventions, data model, errors | `backend.md` |\n| Test pyramid, frameworks, fixtures, CI gates | `testing.md` |\n| Anything else not covered above | `reference-doc.md` (generic fallback) |\n\nIf the topic matches none of the four named templates, use the generic `reference-doc.md`.\n\n## Step 3: Scaffold the Doc to `docs/context/reference/<slug>.md`\n\n1. **Lazy-create `docs/context/reference/`** \u2014 create the directory only now, on first write. Do not create it preemptively in projects that never call this skill.\n2. Read the chosen template from `docs/templates/context/reference/`. If that template file isn\'t present in the project, fall back to a minimal skeleton: an `# H1` title, a `>` purpose blockquote, and one `##` section.\n3. Copy the template to `docs/context/reference/<slug>.md`, set the H1 to the real topic, and fill in whatever the user has already told you. Leave the rest of the template\'s deletable italic examples in place for the author to replace.\n4. **Write the doc immediately** \u2014 this single doc, this invocation. Do not defer or batch.\n\nIf `docs/context/reference/<slug>.md` already exists (the user is re-running for the same slug), update it in place rather than creating a duplicate.\n\n## Step 4: Add or Update the Context Map Pointer Row (Idempotent)\n\nRead AGENTS.md and maintain a pointer row for this doc in the `## Context Map` section. The row format is:\n\n```\n| docs/context/reference/<slug>.md | <when to read it> |\n```\n\nApply this idempotent logic exactly:\n\n1. **If a `## Context Map` section does not exist**, create it (place it after the project intro / Behavioral Boundaries area, before deep architecture). Add the header and a two-column table:\n\n   ```markdown\n   ## Context Map\n\n   | Doc | When to read it |\n   |-----|-----------------|\n   ```\n\n2. **If a row whose first cell is `docs/context/reference/<slug>.md` already exists**, update that row in place (refresh the "when to read it" cell). Do NOT add a second row for the same path.\n\n3. **Otherwise**, append one new row to the Context Map table.\n\nNever duplicate a row. The Context Map is a lightweight pointer index \u2014 one row per reference doc, nothing more.\n\n## Step 5: Confirm\n\nReport what you did:\n\n```\nScaffolded docs/context/reference/<slug>.md from the <template> template.\nContext Map row [added | updated]:\n  | docs/context/reference/<slug>.md | <when to read it> |\n\nFill in the doc\'s sections \u2014 the italic examples are placeholders to replace or delete.\n```\n\nThen end with the canonical Handoff block. After authoring a context doc, the next move is usually back to the work at hand; for a first-run onboarding sweep of several docs, point the user at the gather pass.\n\n## Recommended Next Steps\n\nNext:\n```bash\n$joycraft-session-end\n```\nRun run `/clear` in the CLI, or press Cmd+N (Ctrl+N on Windows/Linux) for a new thread in the desktop/IDE app first.\n',
+  "joycraft-add-fact.md": '---\nname: joycraft-add-fact\ndescription: Capture a project fact and route it to the correct context document -- production map, dangerous assumptions, decision log, institutional knowledge, or troubleshooting\n---\n\n# Add Fact\n\nThe user has a fact to capture. Your job is to classify it, route it to the correct context document, append it in the right format, and optionally add a AGENTS.md boundary rule.\n\n## Step 1: Get the Fact\n\nIf the user already provided the fact (e.g., `$joycraft-add-fact the staging DB resets every Sunday`), use it directly.\n\nIf not, ask: "What fact do you want to capture?" -- then wait for their response.\n\nIf the user provides multiple facts at once, process each one separately through all the steps below, then give a combined confirmation at the end.\n\n## Step 2: Classify the Fact\n\nRoute the fact to one of these 5 context documents based on its content:\n\n### `docs/context/production-map.md`\nThe fact is about **infrastructure, services, environments, URLs, endpoints, credentials, or what is safe/unsafe to touch**.\n- Signal words: "production", "staging", "endpoint", "URL", "database", "service", "deployed", "hosted", "credentials", "secret", "environment"\n- Examples: "The staging DB is at postgres://staging.example.com", "We use Vercel for the frontend and Railway for the API"\n\n### `docs/context/dangerous-assumptions.md`\nThe fact is about **something an AI agent might get wrong -- a false assumption that leads to bad outcomes**.\n- Signal words: "assumes", "might think", "but actually", "looks like X but is Y", "not what it seems", "trap", "gotcha"\n- Examples: "The `users` table looks like a test table but it\'s production", "Deleting a workspace doesn\'t delete the billing subscription"\n\n### `docs/context/decision-log.md`\nThe fact is about **an architectural or tooling choice and why it was made**.\n- Signal words: "decided", "chose", "because", "instead of", "we went with", "the reason we use", "trade-off"\n- Examples: "We chose SQLite over Postgres because this runs on embedded devices", "We use pnpm instead of npm for workspace support"\n\n### `docs/context/institutional-knowledge.md`\nThe fact is about **team conventions, unwritten rules, organizational context, or who owns what**.\n- Signal words: "convention", "rule", "always", "never", "team", "process", "review", "approval", "owns", "responsible"\n- Examples: "The design team reviews all color changes", "We never deploy on Fridays", "PR titles must start with the ticket number"\n\n### `docs/context/troubleshooting.md`\nThe fact is about **diagnostic knowledge -- when X happens, do Y (or don\'t do Z)**.\n- Signal words: "when", "fails", "error", "if you see", "stuck", "broken", "fix", "workaround", "before trying", "reboot", "restart", "reset"\n- Examples: "If Wi-Fi disconnects during flash, wait and retry -- don\'t switch networks", "When tests fail with ECONNREFUSED, check if Docker is running"\n\n### Ambiguous Facts\n\nIf the fact fits multiple categories, pick the **best fit** based on the primary intent. You will mention the alternative in your confirmation message so the user can correct you.\n\n## Step 3: Ensure the Target Document Exists\n\n1. If `docs/context/` does not exist, create the directory.\n2. If the target document does not exist, create it from the template structure. Check `docs/templates/` for the matching template. If no template exists, use this minimal structure:\n\nFor **production-map.md**:\n```markdown\n# Production Map\n\n> What\'s real, what\'s staging, what\'s safe to touch.\n\n## Services\n\n| Service | Environment | URL/Endpoint | Impact if Corrupted |\n|---------|-------------|-------------|-------------------|\n```\n\nFor **dangerous-assumptions.md**:\n```markdown\n# Dangerous Assumptions\n\n> Things the AI agent might assume that are wrong in this project.\n\n## Assumptions\n\n| Agent Might Assume | But Actually | Impact If Wrong |\n|-------------------|-------------|----------------|\n```\n\nFor **decision-log.md**:\n```markdown\n# Decision Log\n\n> Why choices were made, not just what was chosen.\n\n## Decisions\n\n| Date | Decision | Why | Alternatives Rejected | Revisit When |\n|------|----------|-----|----------------------|-------------|\n```\n\nFor **institutional-knowledge.md**:\n```markdown\n# Institutional Knowledge\n\n> Unwritten rules, team conventions, and organizational context.\n\n## Team Conventions\n\n- (none yet)\n```\n\nFor **troubleshooting.md**:\n```markdown\n# Troubleshooting\n\n> What to do when things go wrong for non-code reasons.\n\n## Common Failures\n\n| When This Happens | Do This | Don\'t Do This |\n|-------------------|---------|---------------|\n```\n\n## Step 4: Read the Target Document\n\nRead the target document to understand its current structure. Note:\n- Which section to append to\n- Whether it uses tables or lists\n- The column format if it\'s a table\n\n## Step 5: Append the Fact\n\nAdd the fact to the appropriate section of the target document. Match the existing format exactly:\n\n- **Table-based documents** (production-map, dangerous-assumptions, decision-log, troubleshooting): Add a new table row in the correct columns. Use today\'s date where a date column exists.\n- **List-based documents** (institutional-knowledge): Add a new list item (`- `) to the most appropriate section.\n\nRemove any italic example rows (rows where all cells start with `_`) before appending, so the document transitions from template to real content. Only remove examples from the specific table you are appending to.\n\n**Append only. Never modify or remove existing real content.**\n\n## Step 5b: Update Shared Frontmatter\n\nContext docs are *shared* artifacts (no single owner). After appending, update (or add) YAML frontmatter \u2014 the 2-field shared schema:\n\n```yaml\n---\nlast_updated: YYYY-MM-DD\nlast_updated_by: <resolved name>\n---\n```\n\nIf the file already has a frontmatter block, update the `last_updated` and `last_updated_by` fields in place. If it doesn\'t, prepend a fresh block ABOVE the existing `# Heading`.\n\n**Owner resolution:** look up the owner name in this order \u2014 (1) `git config user.name`, (2) value in your auto-memory `joycraft-owner.txt` if present, (3) ask the user once and persist.\n\n## Step 6: Evaluate AGENTS.md Boundary Rule\n\nDecide whether the fact also warrants a rule in AGENTS.md\'s behavioral boundaries:\n\n**Add a AGENTS.md rule if the fact:**\n- Describes something that should ALWAYS or NEVER be done\n- Could cause real damage if violated (data loss, broken deployments, security issues)\n- Is a hard constraint that applies across all work, not just a one-time note\n\n**Do NOT add a AGENTS.md rule if the fact is:**\n- Purely informational (e.g., "staging DB is at this URL")\n- A one-time decision that\'s already captured\n- A diagnostic tip rather than a prohibition\n\nIf a rule is warranted, read AGENTS.md, find the appropriate section (ALWAYS, ASK FIRST, or NEVER under Behavioral Boundaries), and append the rule. If no Behavioral Boundaries section exists, append one.\n\n## Step 7: Confirm and Hand Off\n\nReport what you did in this format:\n\n```\nAdded to [document name]:\n  [summary of what was added]\n\n[If AGENTS.md was also updated:]\nAdded AGENTS.md rule:\n  [ALWAYS/ASK FIRST/NEVER]: [rule text]\n\n[If the fact was ambiguous:]\nRouted to [chosen doc] -- move to [alternative doc] if this is more about [alternative category description].\n```\n\nEnd with the canonical Handoff block. For most facts, the next move is back to whatever the user was doing \u2014 the Handoff block degrades to just a slash command pointing them home.\n\n## Recommended Next Steps\n\nNext:\n```bash\n$joycraft-session-end\n```\nRun run `/clear` in the CLI, or press Cmd+N (Ctrl+N on Windows/Linux) for a new thread in the desktop/IDE app first.\n',
+  "joycraft-bugfix.md": "---\nname: joycraft-bugfix\ndescription: Structured bug fix workflow \u2014 triage, diagnose, discuss with user, write a focused spec, hand off for implementation\n---\n\n# Bug Fix Workflow\n\nYou are fixing a bug. Follow this process in order. Do not skip steps.\n\n**Guard clause:** If this is clearly a new feature, redirect to `$joycraft-new-feature` and stop.\n\n---\n\n## Phase 1: Triage\n\nEstablish what's broken. Gather: symptom, steps to reproduce, expected vs actual behavior, when it started, relevant logs/errors. If an error message or stack trace is provided, read the referenced files immediately. Try to reproduce if steps are given.\n\n**Done when:** You can describe the symptom in one sentence.\n\n---\n\n## Phase 2: Diagnose\n\nFind the root cause. Start from the error site and trace backward. Read source files \u2014 don't guess. Identify the specific line(s) and logic error. Check git blame if it's a recent regression.\n\n**Done when:** You can explain what's wrong, why, and where in 2-3 sentences.\n\n---\n\n## Phase 3: Discuss\n\nPresent findings to the user BEFORE writing any code or spec:\n1. **Symptom** \u2014 confirm it matches what they see\n2. **Root cause** \u2014 specific file(s) and line(s)\n3. **Proposed fix** \u2014 what changes, where\n4. **Risk** \u2014 side effects? scope?\n\nAsk: \"Does this match? Comfortable with this approach?\" If large/risky, suggest decomposing into multiple specs.\n\n**Done when:** User agrees with the diagnosis and fix direction.\n\n---\n\n## Phase 4: Spec the Fix\n\nWrite a bug fix spec to `docs/bugfixes/<area>/bugfix-name.md`. Use the relevant area as the subdirectory (e.g., `auth`, `cli`, `parser`). Lazy-create the `docs/bugfixes/<area>/` directory if it doesn't exist.\n\n(Bugfixes live under `docs/bugfixes/<area>/`, separate from `docs/features/<slug>/specs/`. Bugfixes are area-level, not feature-tied \u2014 multiple unrelated bugs accumulate in the same area folder over time, which is a fundamentally different folder shape from features.)\n\n**Area README:** When creating (or adding to) a `docs/bugfixes/<area>/` folder, also lazy-create/update a `docs/bugfixes/<area>/README.md` index \u2014 a one-line-per-bug table (`| Bug | Spec | Status | Date |`) so areas that accumulate many bugs stay navigable. Append a row for the new bugfix.\n\n**Why:** Even bug fixes deserve a spec. It forces clarity on what \"fixed\" means, ensures test-first discipline, and creates a traceable record of the fix.\n\nThe spec file MUST start with YAML frontmatter \u2014 the 4-field personal schema (the `area:` field carries the area name, used informally to indicate \"what folder this lives under\"):\n\n```yaml\n---\nstatus: active\nowner: <resolved name>\ncreated: YYYY-MM-DD\narea: <area>\n---\n```\n\n**Owner resolution:** look up the owner name in this order \u2014 (1) `git config user.name`, (2) value in your auto-memory `joycraft-owner.txt` if present, (3) ask the user once and persist.\n\nUse this template for the body:\n\n```markdown\n# Fix [Bug Description] \u2014 Bug Fix Spec\n\n> **Parent Brief:** none (bug fix)\n> **Issue/Error:** [error message, issue link, or symptom description]\n> **Status:** Ready\n> **Date:** YYYY-MM-DD\n> **Estimated scope:** [1 session / N files / ~N lines]\n\n---\n\n## Bug\n\nWhat is broken? Describe the symptom the user experiences.\n\n## Root Cause\n\nWhat is wrong in the code and why? Name the specific file(s) and line(s).\n\n## Fix\n\nWhat changes will fix this? Be specific \u2014 describe the code change, not just \"fix the bug.\"\n\n## Acceptance Criteria\n\n- [ ] [The bug no longer occurs \u2014 describe the correct behavior]\n- [ ] [No regressions in related functionality]\n- [ ] Build passes\n- [ ] Tests pass\n\n## Test Plan\n\n| Acceptance Criterion | Test | Type |\n|---------------------|------|------|\n| [Bug no longer occurs] | [Test that reproduces the bug, then verifies the fix] | [unit/integration/e2e] |\n| [No regressions] | [Existing tests still pass, or new regression test] | [unit/integration] |\n\n**Execution order:**\n1. Write a test that reproduces the bug \u2014 it should FAIL (red)\n2. Run the test to confirm it fails\n3. Apply the fix\n4. Run the test to confirm it passes (green)\n5. Run the full test suite to check for regressions\n\n**Smoke test:** [The bug reproduction test \u2014 fastest way to verify the fix works]\n\n**Before implementing, verify your test harness:**\n1. Run the reproduction test \u2014 it must FAIL (if it passes, you're not testing the actual bug)\n2. The test must exercise your actual code \u2014 not a reimplementation or mock\n3. Identify your smoke test \u2014 it must run in seconds, not minutes\n\n## Constraints\n\n- MUST: [any hard requirements for the fix]\n- MUST NOT: [any prohibitions \u2014 e.g., don't change the public API]\n\n## Affected Files\n\n| Action | File | What Changes |\n|--------|------|-------------|\n\n## Edge Cases\n\n| Scenario | Expected Behavior |\n|----------|------------------|\n```\n\n**For trivial bugs:** The spec will be short. That's fine \u2014 the structure is the point, not the length.\n\n**For large bugs that span multiple files/systems:** Consider whether this should be decomposed into multiple specs. If so, create a brief first using `$joycraft-new-feature`, then decompose. A bug fix spec should be implementable in a single session.\n\n---\n\n## Phase 5: Hand Off\n\nTell the user a one-line summary, then emit the canonical Handoff block.\n\n## Recommended Next Steps\n\nNext:\n```bash\n$joycraft-implement docs/bugfixes/<area>/bugfix-name.md\n```\nRun run `/clear` in the CLI, or press Cmd+N (Ctrl+N on Windows/Linux) for a new thread in the desktop/IDE app first.\n\n**Why:** A fresh session for implementation produces better results. This diagnostic session has context noise from exploration \u2014 a clean session with just the spec is more focused.\n",
+  "joycraft-collaborative-setup.md": '---\nname: joycraft-collaborative-setup\ndescription: Set up Joycraft for a team \u2014 scaffold per-area folders, owner conventions, and a team-facing CONTRIBUTING doc. Run once when adopting Joycraft on a multi-dev project.\n---\n\n# Collaborative Setup\n\nYou are setting up Joycraft for a team. Solo defaults stay solo; this skill adds the team-only ceremony \u2014 `docs/areas/` folders, area README/boundaries, and a thin team-facing CONTRIBUTING-joycraft doc.\n\nThis skill is **interactive** \u2014 ask the user, don\'t auto-detect.\n\n## When to run\n\nRun once when a team is adopting Joycraft on a multi-dev project. Solo users do **not** need this skill \u2014 solo defaults are fine without it.\n\n## Step 1: Confirm Team Context\n\nAsk the user:\n\n> "Setting up Joycraft for a team? (vs. solo work) If you\'re unsure, you can skip \u2014 solo defaults work fine and you can run this later."\n\nIf the user says "actually solo," bail before any writes:\n\n> "No problem. The solo workflow needs no extra setup. Run `$joycraft-new-feature` when you want to start a feature."\n\n## Step 2: Check for Flat Layout \u2014 Bail if Present\n\nBefore scaffolding team structure, check the project\'s docs/ for per-feature artifacts. Look for any of:\n\n- `docs/features/<slug>/brief.md`\n- `docs/features/<slug>/research.md`\n- `docs/features/<slug>/design.md`\n- Loose spec subdirectories that predate the per-feature layout (specs not under `docs/features/<slug>/specs/` or `docs/bugfixes/<area>/`)\n\nIf any **flat layout** artifacts exist, tell the user:\n\n> "I see flat-layout artifacts in your docs/ (briefs/research/designs). Run `npx joycraft upgrade` first \u2014 it will migrate them into `docs/features/<slug>/` automatically. Then re-run this skill."\n\nThen stop. Skills don\'t reliably shell out, so the CLI does the migration.\n\n## Step 3: Gather Areas + Owners (Interactive)\n\nAsk the user:\n\n> "How many areas does your team work in? (e.g., `auth`, `api`, `frontend`, `infra`) \u2014 pick names that match how your team thinks about ownership. You can also skip and just create the team CONTRIBUTING doc."\n\nFor each area name the user provides:\n1. Confirm the name (kebab-case).\n2. Ask: "Who owns this area? (a name, an email, or a team handle \u2014 used in the area README\'s frontmatter)"\n3. Ask (optional): "Are there NEVER or ASK FIRST rules specific to this area? If yes, list them; if no, skip."\n\nIf the user provides duplicate names, ask them to pick a different one. Track the area list in your working memory before writing anything.\n\nIf the user provides 0 areas, skip Step 4 and go straight to Step 5 (CONTRIBUTING doc only). Useful path for "we just want the team doc, no areas yet."\n\n## Step 4: Scaffold Each Area\n\nFor each confirmed area, lazy-create `docs/areas/<area-name>/` and write a `README.md` with the **shared frontmatter schema** (areas are shared docs, not personal):\n\n```yaml\n---\nlast_updated: YYYY-MM-DD\nlast_updated_by: <owner from step 3>\n---\n```\n\n**Owner resolution for `last_updated_by`:** look up the owner name in this order \u2014 (1) `git config user.name`, (2) value in your auto-memory `joycraft-owner.txt` if present, (3) ask the user once and persist. Use the user-provided owner from Step 3 if they specified one for this area.\n\nBody of `README.md`:\n\n```markdown\n# <area-name>\n\n> **Owner:** <name from Step 3>\n> **Status:** active\n\n## What this area covers\n\n(Filled in by the area owner)\n\n## Conventions\n\n(Area-specific patterns or constraints)\n\n## Onboarding\n\nWhen a new dev joins this area, they should:\n1. Read this README\n2. Read `boundaries.md` (if present)\n3. Read the codebase under <area-relevant paths>\n```\n\nIf the user provided NEVER / ASK FIRST rules for the area, also write `docs/areas/<area-name>/boundaries.md` with the shared frontmatter and those rules. If they didn\'t, skip the boundaries file \u2014 the root AGENTS.md boundaries already cover the project-wide cases.\n\n**Idempotency:** if `docs/areas/<area-name>/README.md` already exists, ASK before overwriting (default: skip + inform).\n\n## Step 5: Write the Team CONTRIBUTING Doc\n\nLazy-create `docs/CONTRIBUTING-joycraft.md` (NOT the project\'s main `CONTRIBUTING.md` \u2014 keep them separate so neither stomps on the other).\n\nIf `docs/templates/CONTRIBUTING-joycraft-template.md` exists in the project (it should \u2014 bundled by `npx joycraft init`), use it as the starting point. If not, fall back to the inline template below.\n\nThe doc starts with shared frontmatter:\n\n```yaml\n---\nlast_updated: YYYY-MM-DD\nlast_updated_by: <resolved owner>\n---\n```\n\nBody (inline fallback template \u2014 short by design):\n\n```markdown\n# Joycraft on this project\n\nWe use [Joycraft](https://www.npmjs.com/package/joycraft) for AI-assisted development.\n\n## How our team uses it\n\n(Filled in during $joycraft-collaborative-setup \u2014 fill this in with your team\'s specific conventions.)\n\n## Conventions\n\n- Per-feature work goes under `docs/features/<slug>/`\n- Area-level work and ownership: see `docs/areas/`\n- For "what is Joycraft?", see the package README\n\n## Onboarding\n\nWhen a new dev joins:\n1. Run `npx joycraft init` (idempotent on already-set-up projects)\n2. Read `docs/areas/<your-area>/README.md` for context\n```\n\nIf `docs/CONTRIBUTING-joycraft.md` already exists, ASK before overwriting \u2014 offer overwrite / append / skip; default to skip.\n\n## Step 6: Trigger AGENTS.md Update\n\nNow that `docs/areas/` exists, the next `npx joycraft upgrade` (or any future `npx joycraft init`) will pick it up and add the **Areas pointer** to AGENTS.md automatically \u2014 that pointer tells the agent "when working on the X area, read docs/areas/X/README.md first."\n\nTell the user:\n\n> "Run `npx joycraft upgrade` to refresh AGENTS.md with the Areas pointer (or `npx joycraft init` if you haven\'t initialized yet)."\n\nDon\'t try to shell out from inside the skill \u2014 let the user run the CLI deliberately.\n\n## Step 7: Hand Off\n\nSummarize what you wrote (paths to area READMEs, the CONTRIBUTING doc, any boundaries files), then emit the canonical Handoff block.\n\n## Recommended Next Steps\n\nNext:\n```bash\n$joycraft-new-feature\n```\nRun /clear first.\n\nInclude the path to `docs/CONTRIBUTING-joycraft.md` and any newly-created area READMEs in the summary above the Handoff block.\n\n## Notes\n\n- This skill does NOT migrate flat-layout artifacts on its own. That\'s `npx joycraft upgrade`\'s job \u2014 Step 2 directs the user to run it first.\n- Area names are user-provided. Don\'t auto-detect from `src/auth/`, `src/api/`, etc. \u2014 many projects have monorepo or non-conventional layouts and auto-detection produces noise.\n- If the user stops mid-way (Ctrl-C, abandons), whatever\'s been written stays. Re-running the skill is the recovery path; it\'s idempotent on existing area folders (asks before overwriting).\n',
+  "joycraft-decompose.md": '---\nname: joycraft-decompose\ndescription: Break a feature brief into atomic specs \u2014 small, testable, independently executable units\n---\n\n# Decompose Feature into Atomic Specs\n\nYou have a Feature Brief (or the user has described a feature). Your job is to decompose it into atomic specs that can be executed independently \u2014 one spec per session.\n\n## Step 1: Verify the Brief Exists\n\nLook for a Feature Brief at `docs/features/<slug>/brief.md`. If the user provided a brief path as an argument, use that. Otherwise, scan `docs/features/*/brief.md`.\n\n**Status filter when scanning neighbor briefs and specs:** read the YAML frontmatter at the top of each file. Treat each as **live** unless its `status:` is `done`, `deprecated`, or `superseded` \u2014 those three are the only states you **skip / ignore**. Every other state is live and must be considered. The status vocabulary is `todo \u2192 in-review \u2192 done` (see `docs/reference/spec-status-lifecycle.md`); both `todo` and `in-review` are live. An `in-review` spec is finished-but-unverified work that still constrains neighboring decomposition, so it stays in scope. Also ignore anything under `docs/archive/` entirely.\n\nIf no brief exists, tell the user:\n\n> No feature brief found. Run `$joycraft-new-feature` first to interview and create one, or describe the feature now and I\'ll work from your description.\n\nIf the user describes the feature inline, work from that description directly. You don\'t need a formal brief to decompose \u2014 but recommend creating one for complex features.\n\n## Step 2: Identify Natural Boundaries\n\n**Why:** Good boundaries make specs independently testable and committable. Bad boundaries create specs that can\'t be verified without other specs also being done.\n\nRead the brief (or description) and identify natural split points:\n\n- **Data layer changes** (schemas, types, migrations) \u2014 always a separate spec\n- **Pure functions / business logic** \u2014 separate from I/O\n- **UI components** \u2014 separate from data fetching\n- **API endpoints / route handlers** \u2014 separate from business logic\n- **Test infrastructure** (mocks, fixtures, helpers) \u2014 can be its own spec if substantial\n- **Configuration / environment** \u2014 separate from code changes\n\nAsk yourself: "Can this piece be committed and tested without the other pieces existing?" If yes, it\'s a good boundary.\n\n## Step 3: Build the Decomposition Table\n\nFor each atomic spec, define:\n\n| # | Spec Name | Description | Dependencies | Size |\n|---|-----------|-------------|--------------|------|\n\n**Rules:**\n- Each spec name is `verb-object` format (e.g., `add-terminal-detection`, `extract-prompt-module`)\n- Each description is ONE sentence \u2014 if you need two, the spec is too big\n- Dependencies reference other spec numbers \u2014 keep the dependency graph shallow\n- More than 2 dependencies on a single spec = it\'s too big, split further\n- Aim for 3-7 specs per feature. Fewer than 3 = probably not decomposed enough. More than 10 = the feature brief is too big\n\n## Step 4: Present and Iterate\n\nShow the decomposition table to the user. Ask:\n1. "Does this breakdown match how you think about this feature?"\n2. "Are there any specs that feel too big or too small?"\n3. "Should any of these run in parallel (separate worktrees)?"\n\nIterate until the user approves.\n\n## Execution Modes (assign a mode per spec)\n\nEvery spec carries an **execution mode** that controls how `joycraft-implement` wraps up after building it. Assign one to each spec \u2014 recommended by you, **approved by the human** (never silent).\n\n| Mode | Per-spec wrap-up | Context between specs | Best for |\n|------|------------------|-----------------------|----------|\n| `batch` | implement all, wrap once at the end (one `joycraft-session-end`) | shared (one conversation) | clusters of tiny specs |\n| `checkpoint` | `joycraft-spec-done` after each (commit + status bump), keep going | shared | medium specs wanting atomic commits without fresh context |\n| `isolated` | `joycraft-spec-done`, then a **fresh context**, then the next spec | fresh per spec | heavy specs that would pollute one context |\n\n**Project default.** Read the default mode from the project\'s `AGENTS.md`: look for a line `**Default execution mode:** <mode>`. If that line is **absent, default to `batch`** (the safest: shared context, wrap once). Do not hard-fail when it\'s missing \u2014 just use `batch` and say so in your recommendation.\n\n**Size \u2192 mode heuristic** (a starting recommendation, not a rule):\n\n| Spec size | Recommended mode |\n|-----------|------------------|\n| XS / S | `batch`-eligible (fold into the batch) |\n| M | `checkpoint` |\n| L / XL | `isolated` |\n\nSize is your estimate from the spec\'s scope (files touched, surface area, risk). The heuristic is only a starting point: a tiny spec inside a risky feature may still warrant `isolated`, and only the human knows that \u2014 which is why the recommendation is **approved, not auto-applied**.\n\n**Surface the recommendation and get approval.** Before writing any spec files, present your per-spec mode recommendation and wait for the human\'s OK. Worked example:\n\n> Your project defaults to `batch` (no `**Default execution mode:**` line in AGENTS.md, so I\'m using the safe default). Based on size, I recommend: specs 1, 2 \u2192 `batch`; spec 5 \u2192 `checkpoint`; specs 7, 8 \u2192 `isolated` (large/risky). OK, or adjust?\n\nIf the human overrides any recommendation, **honor their choice verbatim** in both the frontmatter and the queue. Record the approved mode in each spec\'s `mode:` frontmatter field (Step 5) and in each queue entry\'s `"mode"` field (Step 5a). A feature may mix modes across its specs \u2014 that\'s expected; note the mix in the README/wave plan. This applies even when there\'s no brief and the feature was described inline: still assign a mode to every spec, and the AGENTS.md default applies the same way.\n\n## Step 5: Generate Atomic Specs\n\nFor each approved row, create `docs/features/<slug>/specs/<spec-name>.md`. The slug is the feature folder name (e.g., `2026-04-06-token-discipline`). Lazy-create `docs/features/<slug>/specs/` if it doesn\'t exist.\n\nIf no brief exists and the user described the feature inline, derive a kebab-case slug yourself: `YYYY-MM-DD-<short-name>`. Create the folder structure under `docs/features/<slug>/`.\n\n**Why:** Each spec must be self-contained \u2014 a fresh Claude session should be able to execute it without reading the Feature Brief. Copy relevant constraints and context into each spec.\n\nEach spec file MUST start with YAML frontmatter \u2014 the personal schema:\n\n```yaml\n---\nstatus: todo\nowner: <resolved name>\ncreated: YYYY-MM-DD\nfeature: <slug>\nmode: <approved mode \u2014 batch | checkpoint | isolated>\n---\n```\n\nNew specs always start at `status: todo` (the canonical first state \u2014 see `docs/reference/spec-status-lifecycle.md`). The `mode:` value is the human-approved execution mode from the Execution Modes step above.\n\n**Owner resolution:** look up the owner name in this order \u2014 (1) `git config user.name`, (2) value in your auto-memory `joycraft-owner.txt` if present, (3) ask the user once and persist.\n\nUse this structure for the body:\n\n```markdown\n# [Verb + Object] \u2014 Atomic Spec\n\n> **Parent Brief:** `docs/features/<slug>/brief.md` (or "standalone")\n> **Status:** Ready\n> **Date:** YYYY-MM-DD\n> **Estimated scope:** [1 session / N files / ~N lines]\n\n---\n\n## What\nOne paragraph \u2014 what changes when this spec is done?\n\n## Why\nOne sentence \u2014 what breaks or is missing without this?\n\n## External API Contract\n\n_Include this section ONLY when the spec touches a third-party SDK, package, or service API. Omit it entirely otherwise._\n\n**Package:** `<npm-package-name>`\n\n**Canonical sources:**\n- <link to docs>\n- <link to types>\n\n**Key API facts (validated against vX.Y.Z):**\n- <fact 1>\n- <fact 2>\n\n\n## Acceptance Criteria\n- [ ] [Observable behavior]\n- [ ] Build passes\n- [ ] Tests pass\n\n## Test Plan\n\n| Acceptance Criterion | Test | Type |\n|---------------------|------|------|\n| [Each AC above] | [What to call/assert] | [unit/integration/e2e] |\n\n**Execution order:**\n1. Write all tests above \u2014 they should fail against current/stubbed code\n2. Run tests to confirm they fail (red)\n3. Implement until all tests pass (green)\n\n**Smoke test:** [Identify the fastest test for iteration feedback]\n\n**Before implementing, verify your test harness:**\n1. Run all tests \u2014 they must FAIL (if they pass, you\'re testing the wrong thing)\n2. Each test calls your actual function/endpoint \u2014 not a reimplementation or the underlying library\n3. Identify your smoke test \u2014 it must run in seconds, not minutes, so you get fast feedback on each change\n\n## Constraints\n- MUST: [hard requirement]\n- MUST NOT: [hard prohibition]\n\n## Affected Files\n| Action | File | What Changes |\n|--------|------|-------------|\n\n## Approach\nStrategy, data flow, key decisions. Name one rejected alternative.\n\n## Edge Cases\n| Scenario | Expected Behavior |\n|----------|------------------|\n```\n\nIf `docs/templates/ATOMIC_SPEC_TEMPLATE.md` exists, reference it for the full template with additional guidance.\n\nFill in all sections \u2014 each spec must be self-contained (no "see the brief for context"). Copy relevant constraints from the Feature Brief into each spec. Write acceptance criteria specific to THIS spec, not the whole feature. Every acceptance criterion must have at least one corresponding test in the Test Plan. If the user provided test strategy info from the interview, use it to choose test types and frameworks. Include the test harness verification rules in every Test Plan.\n\n### Step 5a: Write the Spec Queue Manifest\n\nAfter all spec `.md` files are written, create `.joycraft-spec-queue.json` in the specs directory alongside the spec files and README. This manifest is the machine-readable, authoritative spec queue consumed by the Pi pipeline automation.\n\n```json\n{\n  "feature": "<slug>",\n  "specs": [\n    { "id": 1, "file": "<spec-name>.md", "depends_on": [], "status": "todo", "mode": "batch" },\n    { "id": 2, "file": "<spec-name>.md", "depends_on": [1], "status": "todo", "mode": "checkpoint" }\n  ]\n}\n```\n\nMap each row in your decomposition table to a spec entry:\n- `id`: sequential integer starting from 1 (matches the decomposition table\'s # column)\n- `file`: the spec filename relative to the specs directory\n- `depends_on`: array of spec ids this spec depends on (empty array `[]` for no dependencies)\n- `status`: always `"todo"` initially \u2014 the agent advances each spec to `"in-review"` via `joycraft-spec-done`, and `joycraft-session-end` graduates it to `"done"` (see `docs/reference/spec-status-lifecycle.md`)\n- `mode`: the human-approved execution mode for this spec (`batch` | `checkpoint` | `isolated`) \u2014 must match the spec file\'s `mode:` frontmatter\n\nValidate: every id referenced in `depends_on` must exist as an `id` in the specs array; the queue `status`/`mode` for each spec must match that spec file\'s frontmatter.\n\n## Step 6: Recommend Execution Strategy and Update Parent Brief\n\nBased on the dependency graph, group specs into execution waves:\n- **Independent specs** \u2014 "These can run in parallel worktrees"\n- **Sequential specs** \u2014 "Execute these in order: 1 -> 2 -> 4"\n- **Mixed** \u2014 "Start specs 1 and 3 in parallel. After 1 completes, start 2."\n\n**Mark each multi-spec wave\'s parallel-safety.** A wave is **parallel-safe** only when its specs\' Affected Files tables are disjoint \u2014 no file appears in two of the wave\'s specs. Overlapping files \u2192 mark the wave NOT parallel-safe and name the overlapping files. Dependency order says what *may* run together; parallel-safety says what *won\'t conflict* when it does \u2014 `joycraft-implement-feature` only parallelizes waves you mark safe.\n\n**Update the parent brief\'s Execution Strategy section** at `docs/features/<slug>/brief.md` with this wave plan, so the brief stays a useful one-stop reference for feature reviewers.\n\n## Step 7: Write the Feature-Folder README.md (Single Source of Truth for Implementers)\n\nAfter generating per-spec files, ALSO write a `README.md` at the spec folder root: `docs/features/<slug>/specs/README.md` (for feature work). For area-level bugfixes, the path is `docs/bugfixes/<area>/README.md`.\n\nThe README is the single source of truth for *implementers*. It contains a **spec table** (one row per spec with dependencies) and the execution wave plan. Use this template:\n\n```markdown\n# <Feature Name> \u2014 Feature Specs\n\n> **Parent Brief:** `docs/features/<slug>/brief.md`\n> **Design:** `docs/features/<slug>/design.md` (when present)\n> **Research:** `docs/features/<slug>/research.md` (when present)\n> **Status:** Decomposed YYYY-MM-DD, ready for implementation\n\n## What this feature does\n\n<one paragraph summary, derived from the brief>\n\n## Specs\n\n| # | Spec | Depends On | Mode | Notes |\n|---|------|-----------|------|-------|\n| 1 | [spec-name.md](spec-name.md) | \u2014 | batch | <one-line description> |\n| 2 | [other-spec.md](other-spec.md) | 1 | checkpoint | <one-line description> |\n\n## Execution waves\n\n- Wave 1: specs ... \u2014 parallel-safe (Affected Files disjoint) | NOT parallel-safe (overlap: <files>)\n- Wave 2 (after wave 1): specs ... \u2014 sequential\n\nParallel-safe = the wave\'s specs touch disjoint Affected Files, so they may run as\nconcurrent subagents/worktrees. Waves without the marker run sequentially.\n\n## How to use this file\n\nRun the whole queue with `$joycraft-implement-feature docs/features/<slug>/` \u2014 it executes the specs in wave order (fresh-context subagent per spec) and finishes with session-end. Or run one spec at a time with `$joycraft-implement <spec-path>`; the implement skill reads this README first so it understands the spec\'s position in the wave plan, and continues through the queue itself. Each spec is self-contained for the actual implementation; this README provides ordering context only.\n```\n\nThe brief and the README serve different audiences: the brief is for *feature reviewers* (vision, scope, decomposition decisions); the README is for *implementers* (what to run next, what depends on what).\n\n## Step 8: Hand Off\n\nTell the user a one-line summary, then emit the canonical Handoff block.\n\n## Recommended Next Steps\n\nNext:\n```bash\n$joycraft-implement-feature docs/features/<slug>/\n```\nRun run `/clear` in the CLI, or press Cmd+N (Ctrl+N on Windows/Linux) for a new thread in the desktop/IDE app first.\n\nThat one command runs the whole queue \u2014 fresh-context subagent per spec, wrap-up and commit after each, session-end once at the end. To drive one spec at a time instead: `$joycraft-implement docs/features/<slug>/specs/<first-spec>.md` (it wraps up and continues through the queue itself).\n',
+  "joycraft-design.md": '---\nname: joycraft-design\ndescription: Design discussion before decomposition \u2014 produce a ~200-line design artifact for human review, catching wrong assumptions before they propagate into specs\n---\n\n# Design Discussion\n\nYou are producing a design discussion document for a feature. This sits between research and decomposition \u2014 it captures your understanding so the human can catch wrong assumptions before specs are written.\n\n**Guard clause:** If no brief path is provided and no brief exists at `docs/features/<slug>/brief.md`, say:\n"No feature brief found. Run `$joycraft-new-feature` first to create one, or provide the path to your brief."\nThen stop.\n\n---\n\n## Step 1: Read Inputs\n\nRead the feature brief at the path the user provides. If the user also provides a research document path, read that too. Research is optional \u2014 if none exists, note that you\'ll explore the codebase directly.\n\n## Step 2: Explore the Codebase\n\nSpawn subagents to explore the codebase for patterns relevant to the brief. Focus on:\n\n- Files and functions that will be touched or extended\n- Existing patterns this feature should follow (naming, data flow, error handling)\n- Similar features already implemented that serve as models\n- Boundaries and interfaces the feature must integrate with\n\nGather file paths, function signatures, and code snippets. You need concrete evidence, not guesses.\n\n## Step 3: Write the Design Document\n\nDerive the slug from the brief path (`docs/features/<slug>/brief.md`).\nLazy-create the folder `docs/features/<slug>/` if needed.\nWrite the design document to `docs/features/<slug>/design.md`.\n\nThe file MUST start with YAML frontmatter \u2014 the 4-field personal schema:\n\n```yaml\n---\nstatus: active\nowner: <resolved name>\ncreated: YYYY-MM-DD\nfeature: <slug>\n---\n```\n\n**Owner resolution:** look up the owner name in this order \u2014 (1) `git config user.name`, (2) value in your auto-memory `joycraft-owner.txt` if present, (3) ask the user once and persist.\n\nThe document has exactly five sections:\n\n### Section 1: Current State\n\nWhat exists today in the codebase that is relevant to this feature. Include file paths, function signatures, and data flows. Be specific \u2014 reference actual code, not abstractions. If no research doc was provided, note that and describe what you found through direct exploration.\n\n### Section 2: Desired End State\n\nWhat the codebase should look like when this feature is complete. Describe the change at a high level \u2014 new files, modified interfaces, new data flows. Do NOT include implementation steps. This is the "what," not the "how."\n\n### Section 3: Patterns to Follow\n\nExisting patterns in the codebase that this feature should match. Include short code snippets and `file:line` references. Show the pattern, don\'t just name it.\n\nIf this is a greenfield project with no existing patterns, propose conventions and note that no precedent exists.\n\n### Section 4: Resolved Design Decisions\n\nDecisions you have already made, with brief rationale. Format each as:\n\n> **Decision:** [what you decided]\n> **Rationale:** [why, referencing existing code or constraints]\n> **Alternative rejected:** [what you considered and why you rejected it]\n\n### Section 5: Open Questions\n\nThings you don\'t know or where multiple valid approaches exist. Each question MUST present 2-3 concrete options with pros and cons. Format:\n\n> **Q: [question]**\n> - **Option A:** [description] \u2014 Pro: [benefit]. Con: [cost].\n> - **Option B:** [description] \u2014 Pro: [benefit]. Con: [cost].\n> - **Option C (if applicable):** [description] \u2014 Pro: [benefit]. Con: [cost].\n\nDo NOT ask vague questions like "what do you think?" Every question must have actionable options the human can choose from.\n\n### Update the Feature Brief\n\nAfter writing the design document, update the parent brief with a back-reference:\n1. Read `docs/features/<slug>/brief.md`\n2. In the header blockquote (the `>` lines at the top), add or update:\n   `> **Design:** docs/features/<slug>/design.md`\n3. If a `> **Design:**` line already exists, replace it \u2014 do NOT add a duplicate\n4. Write the brief back\n\n## Step 4: Reconcile Brief with Findings\n\nYou\'ve just written `docs/features/<slug>/design.md`. Before hand-off, the parent brief at `docs/features/<slug>/brief.md` may now disagree with what you discovered. Re-read it and check each of these sections:\n\n| Brief section | What to look for |\n|---|---|\n| Vision | Did your findings refine or contradict the framing? |\n| Hard Constraints | Are any constraints now obsolete, missing, or refined? |\n| Out of Scope | Did your findings push something in or out of scope? |\n| Decomposition | Are spec counts, names, or dependencies still accurate? |\n| Test Strategy | Do your findings change what or how to test? |\n| Success Criteria | Are the criteria still observable and still match the goal? |\n\n**For each section, choose one:**\n\n- **Edit in place** \u2014 small, mechanical updates: line-number corrections, clarifications, additions consistent with brief intent. No user approval needed.\n- **Diff + stop** \u2014 non-trivial changes: counts flipping, decomposition restructure, scope changes, contradiction with original brief intent. Present a diff of the proposed change, STOP, and wait for user approval before continuing.\n\nIf you make changes, note them at the bottom of `design.md` under a "Brief updates" subsection. If the brief is already in sync, note: "Reconciliation checked, no changes required." If no parent brief exists (feature was described inline), note that and skip this step.\n\n**Why this step exists:** the silent-drift gap. Without reconciliation, the brief and downstream artifacts diverge \u2014 and later decomposition is sized against the stale brief. This feature ("single-source-skills") hit exactly this: brief said "11 clean / 9 dirty" until the research re-audit forced a re-decomposition. Don\'t let it happen again.\n\n## Step 5: Present and STOP \u2014 Pre-Approval Hold\n\nPresent the design document to the user. Say:\n\n```\nDesign discussion written to docs/features/<slug>/design.md\n\nPlease review the document above. Specifically:\n1. Are the patterns in Section 3 the right ones to follow, or should I use different ones?\n2. Do you agree with the resolved decisions in Section 4?\n3. Pick an option for each open question in Section 5 (or propose your own).\n\nReply with your feedback. I will NOT proceed to decomposition until you have reviewed and approved this design.\n```\n\n**CRITICAL: Do NOT emit the canonical Handoff block at this point.** The Handoff block emits ONLY after human approval (see "Step 6: Hand Off (Post-Approval Only)" below). The entire value of this skill is the pause \u2014 it forces a human checkpoint before mistakes propagate.\n\n## Offer to Capture Deferred Items to Backlog\n\nIf during the design discussion the user mentions deferred work \u2014 "let\'s not do X yet," "save Y for later" \u2014 ASK before writing:\n\n> "This looks like deferred work \u2014 want me to capture it to `docs/backlog/`?"\n\nOnly on user confirmation, write a backlog entry at `docs/backlog/YYYY-MM-DD-<short-name>.md` with backlog frontmatter:\n\n```yaml\n---\nstatus: backlog\nowner: <resolved name>\ncreated: YYYY-MM-DD\nsource: docs/features/<slug>/brief.md\n---\n```\n\n**Never auto-write to `docs/backlog/`.** Every backlog entry is user-confirmed.\n\n## Step 6: Hand Off (Post-Approval Only)\n\nOnce the human approves the design:\n- Update the design document with their corrections and chosen options\n- Move answered questions from "Open Questions" to "Resolved Design Decisions"\n- Present the updated document for final confirmation\n- Once the user gives explicit approval, AND ONLY THEN, emit the canonical Handoff block:\n\n## Recommended Next Steps\n\nNext:\n```bash\n$joycraft-decompose docs/features/<slug>/brief.md\n```\nRun run `/clear` in the CLI, or press Cmd+N (Ctrl+N on Windows/Linux) for a new thread in the desktop/IDE app first.\n\nInclude any backlog paths produced as a side effect.\n',
+  "joycraft-gather-context.md": "---\nname: joycraft-gather-context\ndescription: First-run onboarding pass that populates the project context layer -- read what context already exists, then offer a gap-only interview and batch-write the missing fact rows and long-form reference docs\n---\n\n# Gather Context\n\nThis is the first-run **read-then-offer** onboarding pass \u2014 the lowest-intervention way to populate the project's context layer. You read what context already exists, summarize coverage, offer a gap-only interview, and write everything in one reviewable batch at the end.\n\nThis skill is self-contained. It composes the same conventions the single-doc skills use, but everything you need is inlined below \u2014 do not call into or import another skill's logic.\n\n## Step 1: Read What Already Exists First\n\nThe user has invoked the first-run onboarding pass (e.g., `$joycraft-gather-context`). Before asking the user anything, scan the project's existing context. Default scan breadth is **README + `docs/` + AGENTS.md only**:\n\n- The README(s) at the repo root and any obvious sub-package READMEs.\n- `docs/**` \u2014 existing design, architecture, or style docs.\n- `docs/context/*` \u2014 the flat operational fact-docs (production-map, dangerous-assumptions, decision-log, institutional-knowledge, troubleshooting) and `docs/context/reference/*` long-form docs.\n- The current AGENTS.md content, including any `## Context Map` section.\n\nThen summarize for the user what context already exists and what's covered.\n\n**Do NOT auto-run a code-inference scan.** Reading the actual source to infer architecture costs significantly more tokens. Offer that deeper/full review ONLY if the user explicitly asks for it, and when you do, note clearly that it costs more tokens. The default pass never reads the codebase to infer context.\n\n## Step 2: Offer a Gap-Only Interview (Don't Force)\n\nFrom the summary, identify genuine gaps: no design-system doc? no production map? no decision log? Offer an **optional** interview that targets only those gaps. The user can decline any or all of it \u2014 offer, never force.\n\n**Per-doc skip guard (not all-or-nothing):** Never re-interview for a doc that already has real content. Skip each doc that's already populated individually, and interview only the empty or missing ones. If everything is already covered, say so and offer nothing.\n\n## Step 3: Route by Shape (Inline Test)\n\nFor each thing the user wants to capture, apply this minimal shape test inline \u2014 do not defer to another skill:\n\n- **\"Could this be one row in a table?\"** \u2192 it's an **operational fact**. Route it to one of the five flat fact-docs under `docs/context/`:\n  - `docs/context/production-map.md` \u2014 infrastructure, services, environments, URLs, credentials, safe/unsafe to touch.\n  - `docs/context/dangerous-assumptions.md` \u2014 false assumptions an agent might make.\n  - `docs/context/decision-log.md` \u2014 an architectural/tooling choice and why.\n  - `docs/context/institutional-knowledge.md` \u2014 team conventions, unwritten rules, ownership.\n  - `docs/context/troubleshooting.md` \u2014 when X happens, do Y.\n  Append it as a table row (or list item for institutional-knowledge), removing any italic example rows in that table first.\n\n- **\"Does explaining it take paragraphs?\"** \u2192 it's **long-form reference**. Scaffold `docs/context/reference/<slug>.md` from the matching template in `docs/templates/context/reference/` (`design-system`, `frontend-methodology`, `backend`, `testing`, or the generic `reference-doc` fallback), lazy-creating `docs/context/reference/` on first write.\n\nIf an item is ambiguous, apply the test literally: one row \u2192 fact bucket; paragraphs \u2192 reference doc.\n\n## Step 4: Batch-Write + One Final Confirm\n\nDo NOT write per-answer. Collect ALL of the user's gap answers across the whole interview first. Then, in ONE batch:\n\n1. Write all the fact rows into their fact-docs.\n2. Scaffold and write all the reference docs into `docs/context/reference/`.\n3. Add or update the `## Context Map` pointer rows in AGENTS.md \u2014 one row per reference doc, in the form `| docs/context/reference/<slug>.md | <when to read it> |`. Create the `## Context Map` section (header + two-column table) if it doesn't exist; update an existing row in place rather than duplicating it.\n\nPresent the full set of intended changes and get ONE final confirm (\"do it in one go\") before writing. If the user aborts at the final confirm, write nothing \u2014 there are no partial writes in this batch model. The result is one clean, reviewable diff.\n\n## Step 5: Confirm and Hand Off\n\nReport the batch: which fact rows were added, which reference docs were scaffolded, and which Context Map rows were created or updated. Then end with the canonical Handoff block.\n\n## Recommended Next Steps\n\nNext:\n```bash\n$joycraft-session-end\n```\nRun run `/clear` in the CLI, or press Cmd+N (Ctrl+N on Windows/Linux) for a new thread in the desktop/IDE app first.\n",
+  "joycraft-implement-feature.md": "---\nname: joycraft-implement-feature\ndescription: Run a feature's entire spec queue from one invocation \u2014 sequential chain with per-spec wrap-up, fail-fast, session-end once at the end\n---\n\n# Implement Feature (Whole-Queue Driver)\n\nOne invocation runs a feature's whole spec queue: `$joycraft-implement-feature docs/features/<slug>/`. You drive the queue **sequentially in this conversation** \u2014 Codex has no subagent boundary to give each spec a fresh context, so the chain shares context and compensates with disciplined per-spec wrap-ups. This is ordinary interactive use \u2014 one human invocation, no headless loop, no ToS/cost caveat.\n\n> **Context honesty:** for queues of heavy `isolated`-mode specs, a shared-context chain is the wrong tool \u2014 true per-spec isolation comes from Pi's `joycraft-implement-loop` (fresh process per spec) or guided-manual (`/new` + re-invoke per spec). Say so up front when you see a queue dominated by `isolated` specs, then proceed only if the user confirms.\n\n## Step 1: Load the Queue\n\n1. Resolve the specs directory: if the given path contains a `specs/` subdirectory, use it; otherwise use the path itself. Look for `.joycraft-spec-queue.json` there.\n2. **No queue** \u2192 stop:\n\n   > No spec queue found in [path]. Run `$joycraft-decompose` first \u2014 it writes the queue, the specs, and the wave plan.\n\n3. Read the sibling `README.md` (the wave plan) for the intended order. Waves marked parallel-safe still run sequentially here \u2014 parallelism needs isolation this harness chain doesn't have.\n4. Report the plan before starting: feature slug, M specs, current statuses, the order you'll run them in. If the queue is dominated by `isolated` specs, surface the context-honesty note above and get a confirmation.\n5. If **no `todo` specs remain**, skip to Step 4 and say why.\n\n## Step 2: The Chain \u2014 One Spec at a Time\n\nRepeat until no `todo` specs remain:\n\n1. **Find the next ready spec**: the first `todo` whose `depends_on` are all `in-review`/`done` (read the queue JSON).\n2. **None ready but `todo` specs remain** \u2192 fail-fast (Step 3): report which specs are blocked and on what.\n3. **Execute the spec** by following `.agents/skills/joycraft-implement/SKILL.md` end to end \u2014 strict TDD (failing tests first, implement until green, every Acceptance Criterion met), then its per-spec wrap-up: bump to `in-review` in BOTH the queue JSON and the spec's frontmatter, terse discovery stub only if surprised, commit `spec: <spec-name>`. (Treat `isolated` specs the user approved into this chain as `checkpoint`.)\n4. **Verify before advancing**: queue shows `in-review`, `git log` shows the `spec:` commit, tests green. Anything off \u2192 fail-fast (Step 3).\n5. Report one line \u2014 `Spec complete: <name> (spec N of M)` \u2014 and continue.\n\n## Step 3: Fail-Fast\n\nWhen a spec fails (tests not green, or all remaining specs are blocked):\n\n- **Stop the chain.** Start no further specs.\n- Report: which spec failed and why, what reached `in-review`, what remains `todo`. Leave the queue exactly as it is \u2014 never mark anything to cover a failure.\n- Suggest the recovery path: fix in a fresh conversation (`/new`, then `$joycraft-implement <failed-spec>`), then re-run `$joycraft-implement-feature` for the remainder.\n\n## Step 4: Finish \u2014 Session-End Once\n\nWhen no `todo` specs remain, run the once-per-feature finisher yourself: read and follow `.agents/skills/joycraft-session-end/SKILL.md`. It owns the gates the chain deliberately skipped: full validation (must pass before anything graduates `in-review \u2192 done`), discovery consolidation, and push/PR per the project's AGENTS.md git autonomy rules.\n\n## Final Report\n\n```\nFeature run: <slug>\n- Specs completed: N of M (now in-review/done) \xB7 failures: [none | <spec> \u2014 <reason>]\n- Session-end: [ran \u2014 see its report | skipped: <reason>]\n- Discoveries: [n stubs consolidated | none]\n```\n",
+  "joycraft-implement-level5.md": "---\nname: joycraft-implement-level5\ndescription: Set up Level 5 autonomous development \u2014 autofix loop, holdout scenario testing, and scenario evolution from specs\n---\n\n# Implement Level 5 \u2014 Autonomous Development Loop\n\nYou are guiding the user through setting up Level 5: the autonomous feedback loop where specs go in, validated software comes out. This is a one-time setup that installs workflows, creates a scenarios repo, and configures the autofix loop.\n\n## Before You Begin\n\nCheck prerequisites:\n\n1. **Project must be initialized.** Look for `.claude/.joycraft/state.json` (older installs may still have a legacy `.joycraft-version` at the repo root). If neither exists, tell the user to run `npx joycraft init` first.\n2. **Project should be at Level 4.** Check `docs$joycraft-assessment.md` if it exists. If the project hasn't been assessed yet, suggest running `$joycraft-tune` first. But don't block \u2014 the user may know they're ready.\n3. **Git repo with GitHub remote.** This setup requires GitHub Actions. Check for `.git/` and a GitHub remote.\n\nIf prerequisites aren't met, explain what's needed and stop.\n\n## Step 1: Explain What Level 5 Means\n\nTell the user:\n\n> Level 5 is the autonomous loop. When you push specs, three things happen automatically:\n>\n> 1. **Scenario evolution** \u2014 A separate AI agent reads your specs and writes holdout tests in a private scenarios repo. These tests are invisible to your coding agent.\n> 2. **Autofix** \u2014 When CI fails on a PR, Claude Code automatically attempts a fix (up to 3 times).\n> 3. **Holdout validation** \u2014 When CI passes, your scenarios repo runs behavioral tests against the PR. Results post as PR comments.\n>\n> The key insight: your coding agent never sees the scenario tests. This prevents it from gaming the test suite \u2014 like a validation set in machine learning.\n\n## Step 2: Gather Configuration\n\nAsk these questions **one at a time**:\n\n### Question 1: Scenarios repo name\n\n> What should we call your scenarios repo? It'll be a private repo that holds your holdout tests.\n>\n> Default: `{current-repo-name}-scenarios`\n\nAccept the default or the user's choice.\n\n### Question 2: GitHub App\n\n> Level 5 needs a GitHub App to provide a separate identity for autofix pushes (this avoids GitHub's anti-recursion protection). Creating one takes about 2 minutes:\n>\n> 1. Go to https://github.com/settings/apps/new\n> 2. Give it a name (e.g., \"My Project Autofix\")\n> 3. Uncheck \"Webhook > Active\" (not needed)\n> 4. Under **Repository permissions**, set:\n>    - **Contents**: Read & Write\n>    - **Pull requests**: Read & Write\n>    - **Actions**: Read & Write\n> 5. Click **Create GitHub App**\n> 6. Note the **App ID** from the settings page\n> 7. Scroll to **Private keys** > click **Generate a private key** > save the `.pem` file\n> 8. Click **Install App** in the left sidebar > install it on your repo\n>\n> What's your App ID?\n\n## Step 3: Run init-autofix\n\nRun the CLI command with the gathered configuration:\n\n```bash\nnpx joycraft init-autofix --scenarios-repo {name} --app-id {id}\n```\n\nReview the output with the user. Confirm files were created.\n\n## Step 4: Walk Through Secret Configuration\n\nGuide the user step by step:\n\n### 4a: Add Secrets to Main Repo\n\n> You should already have the `.pem` file from when you created the app in Step 2.\n\n> Go to your repo's Settings > Secrets and variables > Actions, and add:\n> - `JOYCRAFT_APP_PRIVATE_KEY` \u2014 paste the contents of your `.pem` file\n> - `ANTHROPIC_API_KEY` \u2014 your Anthropic API key\n\n### 4b: Create the Scenarios Repo\n\n> Create the private scenarios repo:\n> ```bash\n> gh repo create {scenarios-repo-name} --private\n> ```\n>\n> Then copy the scenario templates into it:\n> ```bash\n> cp -r docs/templates/scenarios/* ../{scenarios-repo-name}/\n> cd ../{scenarios-repo-name}\n> git add -A && git commit -m \"init: scaffold scenarios repo from Joycraft\"\n> git push\n> ```\n\n### 4c: Add Secrets to Scenarios Repo\n\n> The scenarios repo also needs the App private key:\n> - `JOYCRAFT_APP_PRIVATE_KEY` \u2014 same `.pem` file as the main repo\n> - `ANTHROPIC_API_KEY` \u2014 same key (needed for scenario generation)\n\n## Step 5: Verify Setup\n\nHelp the user verify everything is wired correctly:\n\n1. **Check workflow files exist:** `ls .github/workflows/autofix.yml .github/workflows/scenarios-dispatch.yml .github/workflows/spec-dispatch.yml .github/workflows/scenarios-rerun.yml`\n2. **Check scenario templates were copied:** Verify the scenarios repo has `example-scenario.test.ts`, `workflows/run.yml`, `workflows/generate.yml`, `prompts/scenario-agent.md`\n3. **Check the App ID is correct** in the workflow files (not still a placeholder)\n\n## Step 6: Update AGENTS.md\n\nIf the project's AGENTS.md doesn't already have an \"External Validation\" section, add one:\n\n> ## External Validation\n>\n> This project uses holdout scenario tests in a separate private repo.\n>\n> ### NEVER\n> - Access, read, or reference the scenarios repo\n> - Mention scenario test names or contents\n> - Modify the scenarios dispatch workflow to leak test information\n>\n> The scenarios repo is deliberately invisible to you. This is the holdout guarantee.\n\n## Step 7: First Test (Optional)\n\nIf the user wants to test the loop:\n\n> Want to do a quick test? Here's how:\n>\n> 1. Write a simple spec in `docs/features/<slug>/specs/` and push to main \u2014 this triggers scenario generation\n> 2. Create a PR with a small change \u2014 when CI passes, scenarios will run\n> 3. Watch for the scenario test results as a PR comment\n>\n> Or deliberately break something in a PR to test the autofix loop.\n\n## Step 8: Summary\n\nPrint a summary of what was set up:\n\n> **Level 5 is live.** Here's what's running:\n>\n> | Trigger | What Happens |\n> |---------|-------------|\n> | Push specs to `docs/features/<slug>/specs/` | Scenario agent writes holdout tests |\n> | PR fails CI | Claude autofix attempts (up to 3x) |\n> | PR passes CI | Holdout scenarios run against PR |\n> | Scenarios update | Open PRs re-tested with latest scenarios |\n>\n> Your scenarios repo: `{name}`\n> Your coding agent cannot see those tests. The holdout wall is intact.\n\n**Important:** Tell the user:\n\n> **Before you can test the loop**, you need to merge this PR to main first. GitHub's `workflow_run` triggers only activate for workflows that exist on the default branch. Once merged, create a new PR with any small change \u2014 that's when you'll see Autofix, Scenarios Dispatch, and Spec Dispatch fire for the first time.\n\nUpdate `docs$joycraft-assessment.md` if it exists \u2014 set the Level 5 score to reflect the new setup.\n",
+  "joycraft-implement.md": "---\nname: joycraft-implement\ndescription: Execute atomic specs with TDD \u2014 read spec, write failing tests, implement until green, wrap up and continue the queue\n---\n\n# Implement Atomic Spec\n\nYou have exactly one atomic spec file to execute. Your job is to implement it using strict TDD \u2014 tests first, confirm they fail, then implement until green.\n\n## Step 1: Parse Arguments\n\nThe user MUST provide a path. No path = stop immediately.\n\n**If no path was provided:**\n\n> No spec path provided. Provide a spec file or a feature directory:\n> `$joycraft-implement docs/features/<slug>/specs/spec-name.md`\n> or `$joycraft-implement docs/features/<slug>/`\n\n**If the path is a directory** (ends with `/` or does not end with `.md`):\n\nLook for `specs/.joycraft-spec-queue.json` inside that directory. Read it. Find the **first `todo` spec whose dependencies are satisfied** (a dependency is satisfied once it is `in-review` or `done`). This matches what `joycraft-next-spec` serves. That single spec file is your target. Do NOT read any other specs.\n\n> Using spec queue: found [spec-file-name] as the next spec.\n\nIf the directory has no queue or no `todo` specs:\n\n> No remaining specs found in [directory].\n\n**If the path is a file** ending in `.md`:\n\nUse it directly as the spec to implement.\n\n## Step 2: Read the Sibling README.md FIRST (if present)\n\nBefore reading the spec itself, check for a sibling `README.md` in the same folder as the spec \u2014 i.e., `<spec-path>/../README.md`. This file is the wave-plan + spec-table that `$joycraft-decompose` writes per feature.\n\n- **If present:** Read the README first. It tells you the spec's position in the wave plan, its dependencies, and which sibling specs (in the same folder) need to be done before this one.\n- **If absent:** That's fine \u2014 proceed normally. The convention is forward-only and many legacy spec folders pre-date it.\n\n### Warn on Unmet Dependencies\n\nIf the README shows that this spec depends on other specs in the same folder, check whether those dependencies are satisfied. A dependency is satisfied once its frontmatter `status:` is `in-review` or `done` (see `docs/reference/spec-status-lifecycle.md`) \u2014 a checkpoint chain progresses on `in-review` without waiting for session-end to graduate it to `done`. A dependency still at `todo` is unmet.\n\nIf any dependency is **not** complete, tell the user:\n\n> \"This spec lists unmet dependencies in the sibling README.md: [list]. Proceed anyway, or stop?\"\n\nWait for confirmation before continuing. The user might be deliberately running out of order (a hotfix, an exploration, etc.) \u2014 your job is to surface the warning, not to gate.\n\n## Step 3: Read and Understand the Spec\n\n1. **Read the spec file.** The spec is your execution contract \u2014 the Acceptance Criteria and Test Plan define \"done.\"\n2. **Check the spec's Status field.** If it says \"Complete,\" warn the user and ask if they want to re-implement or skip.\n3. **Read the Acceptance Criteria** \u2014 these are your success conditions.\n4. **Read the Test Plan** \u2014 this tells you exactly what tests to write and in what order.\n5. **Read the Constraints** \u2014 these are hard boundaries you must not violate.\n\n### Finding Additional Context\n\nSpecs are designed to be self-contained, but if you need more context:\n\n- **Parent brief:** Linked in the spec's body (`> **Parent Brief:**` line). The new convention is `docs/features/<slug>/brief.md`. Read it for broader feature context.\n- **Related specs:** Live in the same directory (typically `docs/features/<slug>/specs/`). The sibling `README.md` (read in Step 2 above) is the index.\n- **Affected Files:** The spec's Affected Files table tells you which files to create or modify.\n\n\n### Before writing code against an external API:\n\n\u26A0\uFE0F If the spec references a third-party SDK or package, read its official documentation and type definitions FIRST. Never write a `declare module` stub for a package that actually exists \u2014 use the real package as a devDependency instead. The stub will make typecheck pass but the code will fail at runtime.\n\n## Step 4: Execute the TDD Cycle\n\n**This is not optional. Write tests FIRST.**\n\n### 3a. Write Tests (Red Phase)\n\nUsing the spec's Test Plan:\n\n1. Write ALL tests listed in the Test Plan. Each Acceptance Criterion must have at least one test.\n2. Tests should call the actual function/endpoint \u2014 not a reimplementation or mock of the underlying library.\n3. Run the tests. **They MUST fail.** If any test passes immediately:\n   - Flag it \u2014 either the test isn't testing the right thing, or the code already exists.\n   - Investigate before proceeding. A test that passes before implementation is a test that proves nothing.\n\n### 3b. Implement (Green Phase)\n\n1. Follow the spec's Approach section for implementation strategy.\n2. Implement the minimum code needed to make tests pass.\n3. Run tests after each meaningful change \u2014 use the spec's Smoke Test for fast feedback.\n4. Continue until ALL tests pass.\n\n### 3c. Verify Acceptance Criteria\n\nWalk through every Acceptance Criterion in the spec:\n\n- [ ] Is each one met?\n- [ ] Does the build pass?\n- [ ] Do all tests pass?\n\nIf any criterion is not met, keep implementing. Do not move on until all criteria are green.\n\n## Step 5: Handle Edge Cases\n\nCheck the spec's Edge Cases table. For each scenario:\n\n- Verify the expected behavior is handled.\n- If the spec says \"warn the user\" or \"prompt,\" make sure that path works.\n\n## Step 6: Wrap Up and Continue (mode-aware \u2014 do the wrap-up yourself)\n\nWhen the spec is implemented and all its tests pass, wrap up and advance according to the spec's **execution mode**. Read the `mode:` field from the spec's frontmatter (written by `joycraft-decompose`). If the spec has **no `mode:` field**, default to **`batch`** (back-compat with pre-mode specs). If the value is unrecognized, treat it as `batch` and note the unrecognized value.\n\n**You perform the wrap-up. You find the next spec. Do not stop to tell the human to run `$joycraft-spec-done` or to paste the next file path \u2014 those hand-backs carry zero information and break the feature's momentum.**\n\n### 6a. Per-spec wrap-up\n\n| Spec `mode:` | Wrap-up you perform now |\n|--------------|------------------------|\n| **batch** | **Status bump only**: set the spec to `in-review` in both systems (see below). No commit, no discovery stub \u2014 batch wraps once at feature end. (The bump is required: the queue treats a dependency as satisfied at `in-review`, so without it dependent specs would look blocked.) |\n| **checkpoint** / **isolated** | The full `joycraft-spec-done` wrap-up, performed by you (canonical definition: `.agents/skills/joycraft-spec-done/SKILL.md`): **(1)** bump status to `in-review` in both systems, **(2)** terse 2-line discovery stub at `docs/discoveries/YYYY-MM-DD-topic.md` ONLY if something contradicted the spec \u2014 usually skip, **(3)** commit `spec: <spec-name>` (implementation + status edits + stub, nothing unrelated), **(4)** no validation re-run, no push, no PR \u2014 those belong to `joycraft-session-end`. |\n\n**Both systems** means: the queue JSON (`joycraft-mark-done <spec-id> --to in-review <specs-dir>` if `.pi/scripts/joycraft/` is installed, else edit `.joycraft-spec-queue.json` directly) AND the spec file's `status:` frontmatter. Never `done` \u2014 the agent doesn't self-certify (`docs/reference/spec-status-lifecycle.md`).\n\n### 6b. Continue the queue (batch and checkpoint)\n\nRe-read `.joycraft-spec-queue.json` in the spec's directory and find the next `todo` spec whose dependencies are all `in-review`/`done` (same rule as Step 1). Then:\n\n- **Next ready spec exists** \u2192 announce one line \u2014 `Continuing: <next-spec> (spec N of M)` \u2014 and go back to Step 2 with it, in this same conversation.\n- **Remaining `todo` specs are all blocked** \u2192 stop and report which specs are blocked and on what.\n- **No `todo` specs remain** \u2192 this was the feature's last spec; go to 6d.\n- **No queue** (you were invoked with a bare spec file outside a queue) \u2192 report the spec complete and stop; there is nothing to continue from.\n\n### 6c. isolated \u2014 fresh context per spec\n\nA conversation cannot clear its own context, so after the wrap-up the fresh context comes from outside:\n\n- **Driver (recommended):** `$joycraft-implement-feature docs/features/<slug>/` runs the remaining queue with a fresh-context subagent per spec \u2014 in-session, interactive, no headless loop.\n- **Guided-manual:** tell the human to run `run `/clear` in the CLI, or press Cmd+N (Ctrl+N on Windows/Linux) for a new thread in the desktop/IDE app`, then re-invoke `$joycraft-implement <next-spec>`. (Always fine, no ToS/cost surprise.)\n- **Pi:** the `joycraft-implement-loop` driver automates it \u2014 a fresh `pi -p` process per spec. Nothing for you to do beyond the wrap-up; the loop advances.\n- **Headless (`claude -p` / `codex exec` loop):** opt-in only. **Surface the caveat, don't bury it:** unattended headless loops draw metered, full-rate API usage and carry a ToS posture the user must **knowingly opt into** (Anthropic meters `claude -p` from a separate full-rate pool; routing subscription OAuth through third-party harnesses is prohibited). The responsible default is Pi (BYO API key / open weights). Do not silently auto-run a subscription-backed headless loop.\n\n### 6d. Feature's last spec (any mode)\n\nRun the once-per-feature finisher yourself: invoke `$joycraft-session-end` (or read and follow `.agents/skills/joycraft-session-end/SKILL.md`). It carries its own gates \u2014 validation is mandatory and must pass before specs graduate `in-review \u2192 done`, and push/PR honor the project's AGENTS.md git autonomy rules \u2014 so running it automatically is safe.\n\n### Report\n\nAfter each spec's wrap-up, report tersely before continuing:\n\n```\nSpec complete: [spec name] \xB7 mode: [mode] \xB7 tests: [N] passing \xB7 [wrapped up + committed | status bumped (batch)]\n[Continuing: <next-spec> (spec N of M) | Feature complete \u2014 running session-end | Blocked: <specs + reasons>]\n```\n",
+  "joycraft-interview.md": '---\nname: joycraft-interview\ndescription: Brainstorm freely about what you want to build \u2014 yap, explore ideas, and get a structured summary you can use later\n---\n\n# Interview \u2014 Idea Exploration\n\nYou are helping the user brainstorm and explore what they want to build. This is a lightweight, low-pressure conversation \u2014 not a formal spec process. Let them yap.\n\n## How to Run the Interview\n\n### 1. Open the Floor\n\nStart with something like:\n"What are you thinking about building? Just talk \u2014 I\'ll listen and ask questions as we go."\n\nLet the user talk freely. Do not interrupt their flow. Do not push toward structure yet.\n\n### 2. Ask Clarifying Questions\n\nAs they talk, weave in questions naturally \u2014 don\'t fire them all at once:\n\n- **What problem does this solve?** Who feels the pain today?\n- **What does "done" look like?** If this worked perfectly, what would a user see?\n- **What are the constraints?** Time, tech, team, budget \u2014 what boxes are we in?\n- **What\'s NOT in scope?** What\'s tempting but should be deferred?\n- **What are the edge cases?** What could go wrong? What\'s the weird input?\n- **What exists already?** Are we building on something or starting fresh?\n\n### 3. Play Back Understanding\n\nAfter the user has gotten their ideas out, reflect back:\n"So if I\'m hearing you right, you want to [summary]. The core problem is [X], and done looks like [Y]. Is that right?"\n\nLet them correct and refine. Iterate until they say "yes, that\'s it."\n\n### 4. Write a Draft Brief\n\nDerive a slug `YYYY-MM-DD-<topic>` (today\'s date + kebab-case topic \u2014 no `-draft` suffix).\nCreate a draft file at `docs/features/<slug>/brief.md`. Lazy-create `docs/features/<slug>/` if it doesn\'t exist.\n\nThe file MUST start with YAML frontmatter \u2014 the 4-field personal schema with `status: draft`:\n\n```yaml\n---\nstatus: draft\nowner: <resolved name>\ncreated: YYYY-MM-DD\nfeature: <slug>\n---\n```\n\n**Owner resolution:** look up the owner name in this order \u2014 (1) `git config user.name`, (2) value in your auto-memory `joycraft-owner.txt` if present, (3) ask the user once and persist. If you can\'t get a name, leave the field as `<resolved name>` and note it for the user.\n\nUse this format for the body:\n\n```markdown\n# [Topic] \u2014 Draft Brief\n\n> **Date:** YYYY-MM-DD\n> **Origin:** $joycraft-interview session\n\n---\n\n## The Idea\n[2-3 paragraphs capturing what the user described \u2014 their words, their framing]\n\n## Problem\n[What pain or gap this addresses]\n\n## What "Done" Looks Like\n[The user\'s description of success \u2014 observable outcomes]\n\n## Constraints\n- [constraint 1]\n- [constraint 2]\n\n## Open Questions\n- [things that came up but weren\'t resolved]\n- [decisions that need more thought]\n\n## Out of Scope (for now)\n- [things explicitly deferred \u2014 see also: deferred work goes to `docs/backlog/`]\n\n## Raw Notes\n[Any additional context, quotes, or tangents worth preserving]\n```\n\n### 5. Offer to Capture Deferred Items to Backlog\n\nIf during the conversation deferred work surfaces (a tangent, a "later" item, a "out-of-scope but tempting" idea), ASK the user:\n\n> "This looks like deferred work \u2014 want me to capture it to `docs/backlog/`?"\n\nOnly on user confirmation, write a backlog entry at `docs/backlog/YYYY-MM-DD-<short-name>.md` with backlog frontmatter:\n\n```yaml\n---\nstatus: backlog\nowner: <resolved name>\ncreated: YYYY-MM-DD\nsource: docs/features/<slug>/brief.md\n---\n```\n\n**Never auto-write to `docs/backlog/`.** Every backlog entry is user-confirmed.\n\n### 6. Hand Off\n\nAfter writing the draft (and any backlog entries), present the canonical Handoff block.\nInclude any backlog paths produced as a side effect.\n\n## Recommended Next Steps\n\nNext:\n```bash\n$joycraft-new-feature docs/features/<slug>/brief.md\n```\nRun run `/clear` in the CLI, or press Cmd+N (Ctrl+N on Windows/Linux) for a new thread in the desktop/IDE app first.\n\nIf the idea sounds complex \u2014 touches many files, involves architectural decisions, or the user is working in an unfamiliar area \u2014 nudge them toward research and design (e.g., `$joycraft-research` then `$joycraft-design`). But present it as a recommendation, not a gate.\n\n## Guidelines\n\n- **This is NOT $joycraft-new-feature.** Do not push toward formal briefs, decomposition tables, or atomic specs. The point is exploration.\n- **Let the user lead.** Your job is to listen, clarify, and capture \u2014 not to structure or direct.\n- **Mark everything as DRAFT.** The output is a starting point, not a commitment.\n- **Keep it short.** The draft brief should be 1-2 pages max. Capture the essence, not every detail.\n- **Multiple interviews are fine.** The user might run this several times as their thinking evolves. Each creates a new dated draft.\n',
   "joycraft-lockdown.md": "---\nname: joycraft-lockdown\ndescription: Generate constrained execution boundaries for an implementation session -- NEVER rules and deny patterns to prevent agent overreach\n---\n\n# Lockdown Mode\n\nThe user wants to constrain agent behavior for an implementation session. Your job is to interview them about what should be off-limits, then generate AGENTS.md NEVER rules and Codex configuration deny patterns they can review and apply.\n\n## When Is Lockdown Useful?\n\nLockdown is most valuable for:\n- **Complex tech stacks** (hardware, firmware, multi-device) where agents can cause real damage\n- **Long-running autonomous sessions** where you won't be monitoring every action\n- **Production-adjacent work** where accidental network calls or package installs are risky\n\nFor simple feature work on a well-tested codebase, lockdown is usually overkill. Mention this context to the user so they can decide.\n\n## Step 1: Check for Tests\n\nBefore starting the interview, search the codebase for test files or directories (look for `tests/`, `test/`, `__tests__/`, `spec/`, or files matching `*.test.*`, `*.spec.*`).\n\nIf no tests are found, tell the user:\n\n> Lockdown mode is most useful when you already have tests in place -- it prevents the agent from modifying them while constraining behavior to writing code and running tests. Consider running `$joycraft-new-feature` first to set up a test-driven workflow, then come back to lock it down.\n\nIf the user wants to proceed anyway, continue with the interview.\n\n## Step 2: Interview -- What to Lock Down\n\nAsk these three questions, one at a time. Wait for the user's response before proceeding to the next question.\n\n### Question 1: Read-Only Files\n\n> What test files or directories should be off-limits for editing? (e.g., `tests/`, `__tests__/`, `spec/`, specific test files)\n>\n> I'll generate NEVER rules to prevent editing these.\n\nIf the user isn't sure, suggest the test directories you found in Step 1.\n\n### Question 2: Allowed Commands\n\n> What commands should the agent be allowed to run? Defaults:\n> - Write and edit source code files\n> - Run the project's smoke test command\n> - Run the full test suite\n>\n> Any other commands to explicitly allow? Or should I restrict to just these?\n\n### Question 3: Denied Commands\n\n> What commands should be denied? Defaults:\n> - Package installs (`npm install`, `pip install`, `cargo add`, `go get`, etc.)\n> - Network tools (`curl`, `wget`, `ping`, `ssh`)\n> - Direct log file reading\n>\n> Any specific commands to add or remove from this list?\n\n**Edge case -- user wants to allow some network access:** If the user mentions API tests or specific endpoints that need network access, exclude those from the deny list and note the exception in the output.\n\n**Edge case -- user wants to lock down file writes:** If the user wants to prevent ALL file writes, warn them:\n\n> Denying all file writes would prevent the agent from doing any work. I recommend keeping source code writes allowed and only locking down test files, config files, or other sensitive directories.\n\n## Step 3: Generate Boundaries\n\nBased on the interview responses, generate output in this exact format:\n\n```\n## Lockdown boundaries generated\n\nReview these suggestions and add them to your project:\n\n### AGENTS.md -- add to NEVER section:\n\n- Edit any file in `[user's test directories]`\n- Run `[denied package manager commands]`\n- Use `[denied network tools]`\n- Read log files directly -- interact with logs only through test assertions\n- [Any additional NEVER rules based on user responses]\n\n### Codex configuration -- suggested deny patterns:\n\nAdd these to your Codex sandbox configuration to restrict command execution:\n\n[\"[command1]\", \"[command2]\", \"[command3]\"]\n\n---\n\nCopy these into your project manually, or tell me to apply them now (I'll show you the exact changes for approval first).\n```\n\nAdjust the content based on the actual interview responses:\n- Only include deny patterns for commands the user confirmed should be denied\n- Only include NEVER rules for directories/files the user specified\n- If the user allowed certain network tools or package managers, exclude those\n\n## Recommended Execution Model\n\nAfter generating the boundaries above, also recommend a Codex execution configuration. Include this section in your output:\n\n```\n### Recommended Execution Configuration\n\nCodex runs in a sandboxed environment by default. To maximize safety during lockdown:\n\n| Your situation | Configuration | Why |\n|---|---|---|\n| Autonomous spec execution | Sandbox with deny patterns above | Only pre-approved commands run |\n| Long session with some trust | Default sandbox | Network-disabled sandbox prevents external access |\n| Interactive development | Default with manual review | Review outputs before applying |\n\n**For lockdown mode, we recommend the default sandboxed execution** combined with the deny patterns above. Codex's sandbox already disables network access by default -- the deny patterns add file-level and command-level restrictions on top.\n\nIf you need network access for specific commands (e.g., API tests), configure explicit network allowances in your Codex setup rather than disabling the sandbox entirely.\n```\n\n## Step 4: Offer to Apply\n\nIf the user asks you to apply the changes:\n\n1. **For AGENTS.md:** Read the existing AGENTS.md, find the Behavioral Boundaries section, and show the user the exact diff for the NEVER section. Ask for confirmation before writing.\n2. **For Codex configuration:** Show the user what the deny patterns will look like after adding the new restrictions. Ask for confirmation before writing.\n\n**Never auto-apply. Always show the exact changes and wait for explicit approval.**\n",
-  "joycraft-new-feature.md": '---\nname: joycraft-new-feature\ndescription: Guided feature development \u2014 interview the user, produce a Feature Brief, then decompose into atomic specs\n---\n\n# New Feature Workflow\n\nYou are starting a new feature. Follow this process in order. Do not skip steps.\n\n## Phase 0: Check for Existing Drafts\n\nBefore starting the interview, check if the user has already drafted a brief.\n\n**Skip this phase if:** the user provided a brief path as an argument (they already know what to work from).\n\n**Steps:**\n1. Check if `docs/features/` exists. If not, skip to Phase 1.\n2. List subdirectories. For each `docs/features/<slug>/brief.md`, read the YAML frontmatter at the top.\n3. **Filter by status:** treat each brief as `status: active` unless its frontmatter says otherwise. **Skip** any brief whose `status:` is `shipped`, `deprecated`, or `superseded`. Also skip anything under `docs/archive/` \u2014 those are out-of-scope for new feature work.\n4. Group what you find:\n   - **Drafts** (frontmatter `status: draft`) \u2014 likely from `$joycraft-interview`.\n   - **Active in-flight** (frontmatter `status: active`) \u2014 work the user already started.\n\n5. Present them:\n\n```\nI found existing artifacts in docs/features/:\n\nDrafts:\n- docs/features/<slug>/brief.md (drafted YYYY-MM-DD)\n\nActive features:\n- docs/features/<slug>/brief.md (started YYYY-MM-DD)\n\nWant me to:\n1. **Formalize** a draft into a full Feature Brief\n2. **Continue** an active feature\n3. **Start a new interview** from scratch\n```\n\n6. If user picks formalize/continue: read the full brief, extract context, and jump to Phase 2 with that context pre-filled.\n7. If user picks start fresh, or nothing found: proceed to Phase 1.\n\n## Phase 1: Interview\n\nInterview the user about what they want to build. Let them talk \u2014 your job is to listen, then sharpen.\n\n**Ask about:**\n- What problem does this solve? Who is affected?\n- What does "done" look like?\n- Hard constraints? (business rules, tech limitations, deadlines)\n- What is explicitly NOT in scope? (push hard on this)\n- Edge cases or error conditions?\n- What existing code/patterns should this follow?\n- Testing: existing setup? framework? smoke test budget? lockdown mode desired?\n\n**Interview technique:**\n- Let the user "yap" \u2014 don\'t interrupt their flow\n- Play back your understanding: "So if I\'m hearing you right..."\n- Push toward testable statements: "How would we verify that works?"\n\nKeep asking until you can fill out a Feature Brief.\n\n## Phase 2: Feature Brief\n\nDerive a slug `YYYY-MM-DD-<feature-name>` (today\'s date + kebab-case feature name).\nWrite the Feature Brief to `docs/features/<slug>/brief.md`. Lazy-create the folder if needed.\n\n**Slug derivation:** today\'s date in `YYYY-MM-DD` format, then `-`, then the feature name lower-cased and hyphen-separated. Example: a feature about "Token Discipline" started on 2026-04-06 \u2192 slug `2026-04-06-token-discipline` \u2192 folder `docs/features/2026-04-06-token-discipline/`.\n\n**Why:** The brief is the single source of truth for what we\'re building. It prevents scope creep and gives every spec a shared reference point.\n\nUse this structure:\n\n```markdown\n# [Feature Name] \u2014 Feature Brief\n\n> **Date:** YYYY-MM-DD\n> **Project:** [project name]\n> **Status:** Interview | Decomposing | Specs Ready | In Progress | Complete\n\n---\n\n## Vision\nWhat are we building and why? The full picture in 2-4 paragraphs.\n\n## User Stories\n- As a [role], I want [capability] so that [benefit]\n\n## Hard Constraints\n- MUST: [constraint that every spec must respect]\n- MUST NOT: [prohibition that every spec must respect]\n\n## Out of Scope\n- NOT: [tempting but deferred]\n\n## Test Strategy\n- **Existing setup:** [framework and tools, or "none yet"]\n- **User expertise:** [comfortable / learning / needs guidance]\n- **Test types:** [smoke, unit, integration, e2e, etc.]\n- **Smoke test budget:** [target time for fast-feedback tests]\n- **Lockdown mode:** [yes/no \u2014 constrain agent to code + tests only]\n\n## Decomposition\n| # | Spec Name | Description | Dependencies | Est. Size |\n|---|-----------|-------------|--------------|-----------|\n| 1 | [verb-object] | [one sentence] | None | [S/M/L] |\n\n## Execution Strategy\n- [ ] Sequential (specs have chain dependencies)\n- [ ] Parallel (specs are independent)\n- [ ] Mixed\n\n## Success Criteria\n- [ ] [End-to-end behavior 1]\n- [ ] [No regressions in existing features]\n```\n\nIf `docs/templates/FEATURE_BRIEF_TEMPLATE.md` exists, reference it for the full template with additional guidance.\n\nPresent the brief to the user. Focus review on:\n- "Does the decomposition match how you think about this?"\n- "Is anything in scope that shouldn\'t be?"\n- "Are the specs small enough? Can each be described in one sentence?"\n\nIterate until approved.\n\n## Phase 3: Generate Atomic Specs\n\nFor each row in the decomposition table, create a self-contained spec file at `docs/features/<slug>/specs/<spec-name>.md`. Lazy-create the `specs/` subfolder if it doesn\'t exist.\n\n**Why:** Each spec must be understandable WITHOUT reading the Feature Brief. This prevents the "Curse of Instructions" \u2014 no spec should require holding the entire feature in context. Copy relevant context into each spec.\n\nUse this structure for each spec:\n\n```markdown\n# [Verb + Object] \u2014 Atomic Spec\n\n> **Parent Brief:** `docs/features/<slug>/brief.md`\n> **Status:** Ready\n> **Date:** YYYY-MM-DD\n> **Estimated scope:** [1 session / N files / ~N lines]\n\n---\n\n## What\nOne paragraph \u2014 what changes when this spec is done?\n\n## Why\nOne sentence \u2014 what breaks or is missing without this?\n\n## Acceptance Criteria\n- [ ] [Observable behavior]\n- [ ] Build passes\n- [ ] Tests pass\n\n## Test Plan\n\n| Acceptance Criterion | Test | Type |\n|---------------------|------|------|\n| [Each AC above] | [What to call/assert] | [unit/integration/e2e] |\n\n**Execution order:**\n1. Write all tests above \u2014 they should fail against current/stubbed code\n2. Run tests to confirm they fail (red)\n3. Implement until all tests pass (green)\n\n**Smoke test:** [Identify the fastest test for iteration feedback]\n\n**Before implementing, verify your test harness:**\n1. Run all tests \u2014 they must FAIL (if they pass, you\'re testing the wrong thing)\n2. Each test calls your actual function/endpoint \u2014 not a reimplementation or the underlying library\n3. Identify your smoke test \u2014 it must run in seconds, not minutes, so you get fast feedback on each change\n\n## Constraints\n- MUST: [hard requirement]\n- MUST NOT: [hard prohibition]\n\n## Affected Files\n| Action | File | What Changes |\n|--------|------|-------------|\n\n## Approach\nStrategy, data flow, key decisions. Name one rejected alternative.\n\n## Edge Cases\n| Scenario | Expected Behavior |\n|----------|------------------|\n```\n\nIf `docs/templates/ATOMIC_SPEC_TEMPLATE.md` exists, reference it for the full template with additional guidance.\n\n## Phase 4: Hand Off for Execution\n\nBefore jumping to execution, consider whether research or design would catch wrong assumptions early:\n\n```\nFeature Brief and [N] atomic specs are ready.\n\nSpecs:\n1. [spec-name] \u2014 [one sentence] [S/M/L]\n2. [spec-name] \u2014 [one sentence] [S/M/L]\n...\n\nBefore executing, consider the complexity of this feature:\n\nCOMPLEX (5+ files, architectural decisions, unfamiliar area):\n  \u2192 $joycraft-research \u2014 gather codebase facts before committing to a design\n  \u2192 $joycraft-design \u2014 make architectural decisions explicit\n  \u2192 Then execute specs\n\nMEDIUM (clear scope but non-trivial):\n  \u2192 $joycraft-design \u2014 make key decisions explicit before building\n  \u2192 Then execute specs\n\nSIMPLE (scope is clear, < 5 files, well-understood area):\n  \u2192 Skip to execution\n\nRecommended execution:\n- [Parallel/Sequential/Mixed strategy]\n- Estimated: [N] sessions total\n\nTo execute: Start a fresh session per spec. Each session should:\n1. Read the spec\n2. Implement\n3. Run $joycraft-session-end to capture discoveries\n4. Commit and PR\n\nReady to start?\n\nRun /clear before your next step \u2014 your artifacts are saved to files.\n```\n\n**Why:** A fresh session for execution produces better results. The interview session has too much context noise \u2014 a clean session with just the spec is more focused. Research and design catch wrong assumptions before they propagate into specs \u2014 but skip them if the scope is clear and well-understood.\n\nYou can also use `$joycraft-decompose` to re-decompose a brief if the breakdown needs adjustment, or run `$joycraft-interview` first for a lighter brainstorm before committing to the full workflow.\n',
-  "joycraft-optimize.md": '---\nname: joycraft-optimize\ndescription: Audit your Claude Code or Codex session overhead \u2014 harness file sizes, plugins, MCP servers, hooks \u2014 and report actionable recommendations\n---\n\n# Optimize \u2014 Session Overhead Audit\n\nYou are auditing the user\'s AI development session for token overhead. Produce a conversational diagnostic report \u2014 no files created.\n\n## Step 1: Detect Platform\n\nCheck which platform is active:\n- **Claude Code:** Look for `.claude/` directory, `CLAUDE.md`\n- **Codex:** Look for `.agents/` directory, `AGENTS.md`\n\nIf both exist, run both checks. If neither, default to Claude Code checks and note the uncertainty.\n\n## Step 2: Audit Harness Files\n\n### Claude Code Path\n\n1. **CLAUDE.md** \u2014 count lines. Threshold: \u2264200 lines.\n2. **Skill files** \u2014 glob `.claude/skills/**/*.md`. Count lines per file. Threshold: \u2264200 lines each.\n\n### Codex Path\n\n1. **AGENTS.md** \u2014 count lines. Threshold: \u2264200 lines.\n2. **Skill files** \u2014 glob `.agents/skills/**/*.md`. Count lines per file. Threshold: \u2264200 lines each.\n\n## Step 3: Audit Plugins & MCP Servers\n\n### Claude Code Path\n\n1. **Installed plugins** \u2014 read `~/.claude/plugins/installed_plugins.json`. List plugin names and versions. If not found, report "no plugins file found."\n2. **Enabled plugins** \u2014 read `~/.claude/settings.json`, check `enabledPlugins` array. Show enabled vs installed count.\n3. **MCP servers** \u2014 read `~/.claude/settings.json`, count entries under `mcpServers`. List server names.\n\n### Codex Path\n\n1. **Plugin config** \u2014 read `~/.codex/config.toml`. List any plugin toggles. Note: Codex syncs its curated plugin marketplace at startup \u2014 this is a boot cost even if you don\'t use them.\n2. **MCP servers** \u2014 check `~/.codex/config.toml` for MCP server entries. List server names.\n\n## Step 4: Audit Hooks (Claude Code Only)\n\nRead `.claude/settings.json` in the project directory. List all hook definitions under the `hooks` key \u2014 show the event name and command for each.\n\nFor Codex: note "hook auditing not yet supported on Codex."\n\n## Step 5: Report\n\nOrganize findings by category. Use pass/warn indicators:\n\n```\n## Session Overhead Report\n\n### Harness Files\n- CLAUDE.md/AGENTS.md: [N] lines [PASS \u2264200 / WARN >200]\n- Skills: [N] files, [list any over 200 lines]\n\n### Plugins\n- Installed: [N] ([list names])\n- Enabled: [N] of [M] installed\n- [If 0: "No plugins \u2014 zero boot cost from plugins."]\n\n### MCP Servers\n- Count: [N] ([list names])\n- [If 0: "No MCP servers \u2014 zero boot cost from servers."]\n\n### Hooks\n- [N] hook definitions ([list event names])\n\n### Recommendations\n- [Specific, actionable items for anything over threshold]\n- [e.g., "AGENTS.md is 312 lines \u2014 consider splitting reference sections into docs/"]\n- [e.g., "3 MCP servers load at boot \u2014 disable unused ones in config"]\n```\n\n## Step 6: Further Resources\n\nEnd with:\n\n> For deeper token optimization, see:\n> - [Nate B Jones\'s token optimization techniques](https://www.youtube.com/watch?v=bDcgHzCBgmQ)\n> - [OB1 repo](https://github.com/nate-b-j/OB1) \u2014 Heavy File Ingestion skill and stupid button prompt kit\n> - [Joycraft\'s token discipline guide](docs/guides/token-discipline.md)\n\n## Edge Cases\n\n| Scenario | Behavior |\n|----------|----------|\n| Config files don\'t exist | Report "not found" for that check, don\'t error |\n| No plugins installed | Report 0 plugins \u2014 this is good, say so |\n| CLAUDE.md/AGENTS.md exactly 200 lines | PASS \u2014 threshold is \u2264200 |\n| `~/.claude/` or `~/.codex/` not accessible | Skip user-level checks, note limitation |\n| Both platforms detected | Run both audits, report separately |\n',
-  "joycraft-research.md": '---\nname: joycraft-research\ndescription: Produce objective codebase research by isolating question generation from fact-gathering \u2014 subagent sees only questions, never the brief\n---\n\n# Research Codebase for a Feature\n\nYou are producing objective codebase research to inform a future spec or implementation. The key insight: the researching agent must never see the brief or ticket \u2014 only research questions. This prevents opinions from contaminating the facts.\n\n**Guard clause:** If the user doesn\'t provide a brief path or inline description, ask:\n"What feature or change are you researching? Provide a brief path or describe it."\n\n---\n\n## Phase 1: Generate Research Questions\n\nRead the brief and identify which zones of the codebase are relevant. Generate 5-10 research questions that are:\n- **Objective and fact-seeking** \u2014 "How does X work?" not "How should we build X?"\n- **Specific to the codebase**\n- **Answerable by reading code**\n\n**Output path:**\n- If a brief exists at `docs/features/<slug>/brief.md`, write to `docs/features/<slug>/research.md` (per-feature layout).\n- If no brief exists (inline description only), write to `docs/research/YYYY-MM-DD-feature-name.md` (flat layout).\n\nWrite the questions to `docs/features/<slug>/.questions-tmp.md`. **Do NOT include any content from the brief.**\n\n---\n\n## Phase 2: Spawn Research Subagent\n\nSpawn a subagent to perform the research. Pass ONLY the research questions \u2014 never the brief.\n\nSubagent prompt:\n```\nYou are researching a codebase to answer specific questions. You have NO context about why these questions are being asked.\n\nRULES:\n- Answer each question with FACTS ONLY: file paths, function signatures, data flows, patterns, dependencies\n- Do NOT recommend, suggest, or opine\n- Do NOT speculate about what should be built\n- If a question cannot be answered, say "No existing code found for this"\n- Search the codebase and read files thoroughly\n- Include code snippets only when essential evidence\n\nQUESTIONS:\n[INSERT_QUESTIONS_HERE]\n\nOUTPUT FORMAT:\n\n# Codebase Research\n\n**Date:** [today]\n**Questions answered:** [N/total]\n\n---\n\n## Q1: [question]\n[Facts only]\n\n## Q2: [question]\n[Facts only]\n```\n\n## Phase 3: Write the Research Document\n\nWrite the subagent\'s response to `docs/features/<slug>/research.md`. Delete the temporary questions file.\n\n### Update the Feature Brief\n\nAfter writing the research document, update the parent brief with a back-reference:\n1. Read `docs/features/<slug>/brief.md`\n2. In the header blockquote (the `>` lines at the top), add or update:\n   `> **Research:** docs/features/<slug>/research.md`\n3. If a `> **Research:**` line already exists, replace it \u2014 do NOT add a duplicate\n4. Write the brief back\n\nPresent:\n```\nResearch complete: docs/features/<slug>/research.md\n\nThis document contains objective facts \u2014 no opinions or recommendations.\n\nRecommended next step:\n- $joycraft-design \u2014 translate research findings into architectural decisions before building\n\nIf the scope is simple (< 5 files, well-understood area, no architectural decisions):\n- $joycraft-decompose \u2014 skip design and break directly into atomic specs\n\nOther options:\n- $joycraft-new-feature \u2014 formalize into a full Feature Brief first\n- Read the research and add corrections manually\n```\n',
-  "joycraft-session-end.md": "---\nname: joycraft-session-end\ndescription: Wrap up a session \u2014 capture discoveries, verify, prepare for PR or next session\n---\n\n# Session Wrap-Up \u2014 Feature Finisher\n\nThis is the **once-per-feature finisher** \u2014 the heavy bookend that runs **once**, when the feature's specs are done, not after every spec. It is the **only validation gate** in the loop and the single place that pushes and opens the PR.\n\n> **Two-tier wrap-up.** The light per-spec step is `$joycraft-spec-done` (status bump `todo \u2192 in-review` + commit, no validation/push/PR \u2014 it runs after each spec). This skill is the heavy counterpart: full validation, consolidate the discovery stubs spec-done left behind, graduate every `in-review` spec to `done`, push, and open the PR. See `docs/reference/spec-status-lifecycle.md` for the `todo \u2192 in-review \u2192 done` lifecycle.\n\nComplete these steps in order.\n\n## 1. Consolidate Discoveries\n\n**Why:** Discoveries are the surprises \u2014 things that weren't in the spec or that contradicted expectations. They prevent future sessions from hitting the same walls.\n\nThis is the **consolidation** pass: `$joycraft-spec-done` may have left terse 2-line discovery **stubs** during the feature (one per surprising spec). Curate and expand those stubs into proper discovery docs now, and capture anything else surprising from the feature as a whole. If any stubs exist at `docs/discoveries/`, consolidate them (merge related ones, expand each into the full format below); then create or update a discovery file at `docs/discoveries/YYYY-MM-DD-topic.md`. Create the `docs/discoveries/` directory if it doesn't exist.\n\nOnly capture what's NOT obvious from the code or git diff:\n- \"We thought X but found Y\" \u2014 assumptions that were wrong\n- \"This API/library behaves differently than documented\" \u2014 external gotchas\n- \"This edge case needs handling in a future spec\" \u2014 deferred work with context\n- \"The approach in the spec didn't work because...\" \u2014 spec-vs-reality gaps\n- Key decisions made during implementation that aren't in the spec\n\n**Do NOT capture:**\n- Files changed (that's the diff)\n- What you set out to do (that's the spec)\n- Step-by-step narrative of the session (nobody re-reads these)\n\nUse this format:\n\n```markdown\n# Discoveries \u2014 [topic]\n\n**Date:** YYYY-MM-DD\n**Spec:** [link to spec if applicable]\n\n## [Discovery title]\n**Expected:** [what we thought would happen]\n**Actual:** [what actually happened]\n**Impact:** [what this means for future work]\n```\n\nIf nothing surprising happened (no stubs, no surprises), skip the discovery file entirely. No discovery is a good sign \u2014 the spec was accurate.\n\n## 1b. Update Context Documents\n\nIf `docs/context/` exists, quickly check whether this session revealed anything about:\n\n- **Production risks** \u2014 did you interact with or learn about production vs staging systems? Update `docs/context/production-map.md`\n- **Wrong assumptions** \u2014 did you assume something that turned out to be false? Update `docs/context/dangerous-assumptions.md`\n- **Key decisions** \u2014 did you make an architectural or tooling choice? Add a row to `docs/context/decision-log.md`\n- **Unwritten rules** \u2014 did you discover a convention or constraint not documented anywhere? Update `docs/context/institutional-knowledge.md`\n\nSkip this if nothing applies. Don't force it \u2014 only update when there's genuine new context.\n\n## 2. Run Validation \u2014 the ONLY validation gate\n\nThis is **mandatory** and it is the **only** validation gate in the loop: `$joycraft-spec-done` deliberately skips validation (it trusts implement's per-spec TDD), so this feature-level run is the single cross-spec safety net. Never skip it.\n\nRun the project's validation commands. Check CLAUDE.md or AGENTS.md for project-specific commands. Common checks:\n\n- Type-check (e.g., `tsc --noEmit`, `mypy`, `cargo check`)\n- Tests (e.g., `npm test`, `pytest`, `cargo test`)\n- Lint (e.g., `eslint`, `ruff`, `clippy`)\n\nFix any failures before proceeding. **If validation fails, stop \u2014 do NOT graduate specs to `done` and do NOT push.**\n\n## 3. Graduate Specs `in-review \u2192 done`\n\nThis step graduates the feature's finished specs to their terminal state. Because session-end runs once at the end, **multiple specs may be waiting** in `in-review` (one per spec the loop completed via `$joycraft-spec-done`). Graduate **all** of them, in **both** systems (the queue JSON and the frontmatter must never disagree):\n\nFor each spec in `docs/features/<slug>/specs/` (or `docs/bugfixes/<area>/` for bugfixes \u2014 scan recursively) whose status is `in-review`:\n\n1. **Queue JSON** \u2014 `joycraft-mark-done <spec-id> --to done <specs-dir>` (the `--to done` graduation; find `<spec-id>` by matching the entry's `file`).\n2. **Frontmatter** \u2014 edit the spec file's YAML `status:` to `done`.\n\nRules:\n- Only graduate specs that are `in-review`. A spec still at `todo` was never started \u2014 **leave it `todo` and report it as remaining** (the feature isn't fully done; see the PR gate in step 5).\n- Never write `done` for work nothing has validated \u2014 this validation run (step 2) is what licenses the graduation. (Once `verify-in-loop` ships, an independent verify performs the `in-review \u2192 done` transition; until then, this step does.)\n- `done` means **verified**, not **merged**. A merged PR is a git fact, never a spec status \u2014 do not invent a `merged` status or any fourth state beyond `todo`/`in-review`/`done`.\n\nIf working from a Feature Brief at `docs/features/<slug>/brief.md`, also check off completed specs in the decomposition table.\n\n## 4. Commit\n\nCommit all changes including the discovery file (if created) and spec status updates. The commit message should reference the spec if applicable.\n\n## 5. Push and PR (if autonomous git is enabled)\n\n**Check CLAUDE.md or AGENTS.md for \"Git Autonomy\" in the Behavioral Boundaries section.** If it says \"STRICTLY ENFORCED\" or the ALWAYS section includes \"Push to feature branches immediately after every commit\":\n\n1. **Push immediately.** Run `git push origin <branch>` \u2014 do not ask, do not hesitate.\n2. **Open a PR if the feature is complete.** The feature is complete when every spec is `done` (none left at `todo`/`in-review`). Check the queue JSON / decomposition table \u2014 if all specs are `done`, run `gh pr create` with a summary of all completed specs. Do not ask first.\n3. **If specs remain (`todo`),** still push. The PR comes when the feature's last spec is graduated.\n\nIf CLAUDE.md or AGENTS.md does NOT have autonomous git rules (or has \"ASK FIRST\" for pushing), ask the user before pushing.\n\n## 6. Report\n\n```\nFeature complete.\n- Feature: [slug]\n- Specs graduated to done: [N] (remaining at todo: [N])\n- Build: [passing / failing]\n- Discoveries: [N consolidated / none]\n- Pushed: [yes / no \u2014 and why not]\n- PR: [opened #N / not yet \u2014 N specs remaining]\n- Next: [what comes after this feature]\n\nRun /clear before your next step \u2014 your artifacts are saved to files.\n```\n",
+  "joycraft-new-feature.md": '---\nname: joycraft-new-feature\ndescription: Guided feature development \u2014 interview the user, produce a Feature Brief, then decompose into atomic specs\n---\n\n# New Feature Workflow\n\nYou are starting a new feature. Follow this process in order. Do not skip steps.\n\n## Phase 0: Check for Existing Drafts and In-Flight Features\n\nBefore starting the interview, scan `docs/features/` for existing artifacts the user may want to continue from.\n\n**Skip this phase if:** the user provided a brief path as an argument (they already know what to work from).\n\n**Steps:**\n1. Check if `docs/features/` exists. If not, skip to Phase 1.\n2. List subdirectories. For each `docs/features/<slug>/brief.md`, read the YAML frontmatter at the top.\n3. **Filter by status:** treat each brief as `status: active` unless its frontmatter says otherwise. **Skip** any brief whose `status:` is `shipped`, `deprecated`, or `superseded`. Also skip anything under `docs/archive/` \u2014 those are out-of-scope for new feature work.\n4. Group what you find:\n   - **Drafts** (frontmatter `status: draft`) \u2014 likely from `$joycraft-interview`.\n   - **Active in-flight** (frontmatter `status: active`) \u2014 work the user already started.\n\n5. Present them:\n\n```\nI found existing artifacts in docs/features/:\n\nDrafts:\n- docs/features/<slug>/brief.md (drafted YYYY-MM-DD)\n\nActive features:\n- docs/features/<slug>/brief.md (started YYYY-MM-DD)\n\nWant me to:\n1. **Formalize** a draft into a full Feature Brief\n2. **Continue** an active feature\n3. **Start a new interview** from scratch\n```\n\n6. If user picks formalize/continue: read the full brief, extract context, and jump to Phase 2 with that context pre-filled.\n7. If user picks start fresh, or nothing found: proceed to Phase 1.\n\n## Phase 1: Interview\n\nInterview the user about what they want to build. Let them talk \u2014 your job is to listen, then sharpen.\n\n**Ask about:**\n- What problem does this solve? Who is affected?\n- What does "done" look like?\n- Hard constraints? (business rules, tech limitations, deadlines)\n- What is explicitly NOT in scope? (push hard on this)\n- Edge cases or error conditions?\n- What existing code/patterns should this follow?\n- Testing: existing setup? framework? smoke test budget? lockdown mode desired?\n\n**Interview technique:**\n- Let the user "yap" \u2014 don\'t interrupt their flow\n- Play back your understanding: "So if I\'m hearing you right..."\n- Push toward testable statements: "How would we verify that works?"\n\nKeep asking until you can fill out a Feature Brief.\n\n## Phase 2: Feature Brief\n\nDerive a slug `YYYY-MM-DD-<feature-name>` (today\'s date + kebab-case feature name).\nWrite the Feature Brief to `docs/features/<slug>/brief.md`. Lazy-create the folder if needed.\n\n**Slug derivation:** today\'s date in `YYYY-MM-DD` format, then `-`, then the feature name lower-cased and hyphen-separated. Example: a feature about "Token Discipline" started on 2026-04-06 \u2192 slug `2026-04-06-token-discipline` \u2192 folder `docs/features/2026-04-06-token-discipline/`.\n\n**Why:** The brief is the single source of truth for what we\'re building. It prevents scope creep and gives every spec a shared reference point.\n\nThe brief MUST start with YAML frontmatter \u2014 the 4-field personal schema:\n\n```yaml\n---\nstatus: active\nowner: <resolved name>\ncreated: YYYY-MM-DD\nfeature: <slug>\n---\n```\n\n**Owner resolution:** look up the owner name in this order \u2014 (1) `git config user.name`, (2) value in your auto-memory `joycraft-owner.txt` if present, (3) ask the user once and persist. If you can\'t get a name, leave the field as `<resolved name>` and note it for the user.\n\nIf the brief was formalized from an existing draft, parse the existing draft\'s frontmatter and update `status:` from `draft` to `active`. Never silently overwrite \u2014 if the draft already has body content, preserve it and append/refine rather than replacing.\n\nUse this structure for the body:\n\n```markdown\n# [Feature Name] \u2014 Feature Brief\n\n> **Date:** YYYY-MM-DD\n> **Project:** [project name]\n\n---\n\n## Vision\nWhat are we building and why? The full picture in 2-4 paragraphs.\n\n## User Stories\n- As a [role], I want [capability] so that [benefit]\n\n## Hard Constraints\n- MUST: [constraint that every spec must respect]\n- MUST NOT: [prohibition that every spec must respect]\n\n## Out of Scope\n- NOT: [tempting but deferred]\n\n## Test Strategy\n- **Existing setup:** [framework and tools, or "none yet"]\n- **User expertise:** [comfortable / learning / needs guidance]\n- **Test types:** [smoke, unit, integration, e2e, etc.]\n- **Smoke test budget:** [target time for fast-feedback tests]\n- **Lockdown mode:** [yes/no \u2014 constrain agent to code + tests only]\n\n## Decomposition\n| # | Spec Name | Description | Dependencies | Est. Size |\n|---|-----------|-------------|--------------|-----------|\n| 1 | [verb-object] | [one sentence] | None | [S/M/L] |\n\n## Execution Strategy\n- [ ] Sequential (specs have chain dependencies)\n- [ ] Parallel worktrees (specs are independent)\n- [ ] Mixed\n\n## Success Criteria\n- [ ] [End-to-end behavior 1]\n- [ ] [No regressions in existing features]\n```\n\nIf `docs/templates/FEATURE_BRIEF_TEMPLATE.md` exists, reference it for the full template with additional guidance.\n\nPresent the brief to the user. Focus review on:\n- "Does the decomposition match how you think about this?"\n- "Is anything in scope that shouldn\'t be?"\n- "Are the specs small enough? Can each be described in one sentence?"\n\nIterate until approved.\n\n## Phase 3: Generate Atomic Specs\n\nFor each row in the decomposition table, create a self-contained spec file at `docs/features/<slug>/specs/<spec-name>.md`. Lazy-create the `specs/` subfolder if it doesn\'t exist.\n\n**Why:** Each spec must be understandable WITHOUT reading the Feature Brief. This prevents the "Curse of Instructions" \u2014 no spec should require holding the entire feature in context. Copy relevant context into each spec.\n\nEach spec file MUST start with YAML frontmatter \u2014 the 4-field personal schema:\n\n```yaml\n---\nstatus: active\nowner: <resolved name>\ncreated: YYYY-MM-DD\nfeature: <slug>\n---\n```\n\nWhen listing existing in-flight features in Phase 0, ignore briefs whose `status:` is `shipped`, `deprecated`, or `superseded`. Also ignore anything under `docs/archive/`.\n\nIf `docs/backlog/` items surface during the interview as "deferred work" candidates, ask the user before writing \u2014 never auto-write to `docs/backlog/`.\n\nUse this structure for each spec body:\n\n```markdown\n# [Verb + Object] \u2014 Atomic Spec\n\n> **Parent Brief:** `docs/features/<slug>/brief.md`\n> **Status:** Ready\n> **Date:** YYYY-MM-DD\n> **Estimated scope:** [1 session / N files / ~N lines]\n\n---\n\n## What\nOne paragraph \u2014 what changes when this spec is done?\n\n## Why\nOne sentence \u2014 what breaks or is missing without this?\n\n## Acceptance Criteria\n- [ ] [Observable behavior]\n- [ ] Build passes\n- [ ] Tests pass\n\n## Test Plan\n\n| Acceptance Criterion | Test | Type |\n|---------------------|------|------|\n| [Each AC above] | [What to call/assert] | [unit/integration/e2e] |\n\n**Execution order:**\n1. Write all tests above \u2014 they should fail against current/stubbed code\n2. Run tests to confirm they fail (red)\n3. Implement until all tests pass (green)\n\n**Smoke test:** [Identify the fastest test for iteration feedback]\n\n**Before implementing, verify your test harness:**\n1. Run all tests \u2014 they must FAIL (if they pass, you\'re testing the wrong thing)\n2. Each test calls your actual function/endpoint \u2014 not a reimplementation or the underlying library\n3. Identify your smoke test \u2014 it must run in seconds, not minutes, so you get fast feedback on each change\n\n## Constraints\n- MUST: [hard requirement]\n- MUST NOT: [hard prohibition]\n\n## Affected Files\n| Action | File | What Changes |\n|--------|------|-------------|\n\n## Approach\nStrategy, data flow, key decisions. Name one rejected alternative.\n\n## Edge Cases\n| Scenario | Expected Behavior |\n|----------|------------------|\n```\n\nIf `docs/templates/ATOMIC_SPEC_TEMPLATE.md` exists, reference it for the full template with additional guidance.\n\n## Phase 3.5: Offer to Capture Deferred Items to Backlog\n\nIf during the interview deferred work surfaces (out-of-scope items, "later" features, tangents), ASK the user:\n\n> "This looks like deferred work \u2014 want me to capture it to `docs/backlog/`?"\n\nOnly on user confirmation, write a backlog entry at `docs/backlog/YYYY-MM-DD-<short-name>.md` with backlog frontmatter:\n\n```yaml\n---\nstatus: backlog\nowner: <resolved name>\ncreated: YYYY-MM-DD\nsource: docs/features/<slug>/brief.md\n---\n```\n\n**Never auto-write to `docs/backlog/`.** Every backlog entry is user-confirmed.\n\n## Phase 4: Hand Off for Execution\n\nBefore jumping to execution, consider whether research or design would catch wrong assumptions early:\n\n```\nFeature Brief and [N] atomic specs are ready.\n\nSpecs:\n1. [spec-name] \u2014 [one sentence] [S/M/L]\n2. [spec-name] \u2014 [one sentence] [S/M/L]\n...\n\nBefore executing, consider the complexity of this feature:\n\nCOMPLEX (5+ files, architectural decisions, unfamiliar area):\n  \u2192 $joycraft-research \u2014 gather codebase facts before committing to a design\n  \u2192 $joycraft-design \u2014 make architectural decisions explicit\n  \u2192 Then execute specs\n\nMEDIUM (clear scope but non-trivial):\n  \u2192 $joycraft-design \u2014 make key decisions explicit before building\n  \u2192 Then execute specs\n\nSIMPLE (scope is clear, < 5 files, well-understood area):\n  \u2192 Skip to execution\n\nRecommended execution:\n- [Parallel/Sequential/Mixed strategy]\n- Estimated: [N] sessions total\n\nTo execute: Start a fresh session per spec. Each session should:\n1. Read the spec\n2. Implement\n3. Run $joycraft-session-end to capture discoveries\n4. Commit and PR\n\nReady to start?\n```\n\nEnd with the canonical Handoff block. Include any backlog paths produced as a side effect.\n\n## Recommended Next Steps\n\nNext:\n```bash\n$joycraft-decompose docs/features/<slug>/brief.md\n```\nRun run `/clear` in the CLI, or press Cmd+N (Ctrl+N on Windows/Linux) for a new thread in the desktop/IDE app first.\n\n**Why:** A fresh session for execution produces better results. The interview session has too much context noise \u2014 a clean session with just the spec is more focused. Research and design catch wrong assumptions before they propagate into specs \u2014 but skip them if the scope is clear and well-understood.\n\nYou can also use `$joycraft-decompose` to re-decompose a brief if the breakdown needs adjustment, or run `$joycraft-interview` first for a lighter brainstorm before committing to the full workflow.\n',
+  "joycraft-optimize.md": '---\nname: joycraft-optimize\ndescription: Audit your Claude Code or Codex session overhead \u2014 harness file sizes, plugins, MCP servers, hooks \u2014 and report actionable recommendations\n---\n\n# Optimize \u2014 Session Overhead Audit\n\nYou are auditing the user\'s AI development session for token overhead. Produce a conversational diagnostic report \u2014 no files created.\n\n## Step 1: Detect Platform\n\nCheck which platform is active:\n- **Claude Code:** Look for `.claude/` directory, `AGENTS.md`\n- **Codex:** Look for `.agents/` directory, `AGENTS.md`\n\nIf both exist, run both checks. If neither, default to Claude Code checks and note the uncertainty.\n\n## Step 2: Audit Harness Files\n\n### Claude Code Path\n\n1. **AGENTS.md** \u2014 count lines. Threshold: \u2264200 lines.\n2. **Skill files** \u2014 glob `.agents/skills/**/*.md`. Count lines per file. Threshold: \u2264200 lines each.\n\n### Codex Path\n\n1. **AGENTS.md** \u2014 count lines. Threshold: \u2264200 lines.\n2. **Skill files** \u2014 glob `.agents/skills/**/*.md`. Count lines per file. Threshold: \u2264200 lines each.\n\n## Step 3: Audit Plugins & MCP Servers\n\n### Claude Code Path\n\n1. **Installed plugins** \u2014 read `~/.claude/plugins/installed_plugins.json`. List plugin names and versions. If not found, report "no plugins file found."\n2. **Enabled plugins** \u2014 read `~/.claude/settings.json`, check `enabledPlugins` array. Show enabled vs installed count.\n3. **MCP servers** \u2014 read `~/.claude/settings.json`, count entries under `mcpServers`. List server names.\n\n### Codex Path\n\n1. **Plugin config** \u2014 read `~/.codex/config.toml`. List any plugin toggles. Note: Codex syncs its curated plugin marketplace at startup \u2014 this is a boot cost even if you don\'t use them.\n2. **MCP servers** \u2014 check `~/.codex/config.toml` for MCP server entries. List server names.\n\n## Step 4: Audit Hooks (Claude Code Only)\n\nRead `.claude/settings.json` in the project directory. List all hook definitions under the `hooks` key \u2014 show the event name and command for each.\n\nFor Codex: note "hook auditing not yet supported on Codex."\n\n## Step 5: Report\n\nOrganize findings by category. Use pass/warn indicators:\n\n```\n## Session Overhead Report\n\n### Harness Files\n- AGENTS.md: [N] lines [PASS \u2264200 / WARN >200]\n- Skills: [N] files, [list any over 200 lines]\n\n### Plugins\n- Installed: [N] ([list names])\n- Enabled: [N] of [M] installed\n- [If 0: "No plugins \u2014 zero boot cost from plugins."]\n\n### MCP Servers\n- Count: [N] ([list names])\n- [If 0: "No MCP servers \u2014 zero boot cost from servers."]\n\n### Hooks\n- [N] hook definitions ([list event names])\n\n### Recommendations\n- [Specific, actionable items for anything over threshold]\n- [e.g., "AGENTS.md is 312 lines \u2014 consider splitting reference sections into docs/"]\n- [e.g., "3 MCP servers load at boot \u2014 disable unused ones in settings.json"]\n```\n\n## Step 6: Further Resources\n\nEnd with:\n\n> For deeper token optimization, see:\n> - [Nate B Jones\'s token optimization techniques](https://www.youtube.com/watch?v=bDcgHzCBgmQ)\n> - [OB1 repo](https://github.com/nate-b-j/OB1) \u2014 Heavy File Ingestion skill and stupid button prompt kit\n> - [Joycraft\'s token discipline guide](docs/guides/token-discipline.md)\n\n## Edge Cases\n\n| Scenario | Behavior |\n|----------|----------|\n| Config files don\'t exist | Report "not found" for that check, don\'t error |\n| No plugins installed | Report 0 plugins \u2014 this is good, say so |\n| AGENTS.md exactly 200 lines | PASS \u2014 threshold is \u2264200 |\n| `~/.claude/` or `~/.codex/` not accessible | Skip user-level checks, note limitation |\n| Both platforms detected | Run both audits, report separately |\n',
+  "joycraft-research.md": '---\nname: joycraft-research\ndescription: Produce objective codebase research by isolating question generation from fact-gathering \u2014 subagent sees only questions, never the brief\n---\n\n# Research Codebase for a Feature\n\nYou are producing objective codebase research to inform a future spec or implementation. The key insight: the researching agent must never see the brief or ticket \u2014 only research questions. This prevents opinions from contaminating the facts.\n\n**Guard clause:** If the user doesn\'t provide a brief path or inline description, ask:\n"What feature or change are you researching? Provide a brief path or describe it."\n\n---\n\n## Phase 1: Generate Research Questions\n\nRead the brief and identify which zones of the codebase are relevant. Generate 5-10 research questions that are:\n- **Objective and fact-seeking** \u2014 "How does X work?" not "How should we build X?"\n- **Specific to the codebase**\n- **Answerable by reading code**\n\n**Output path:**\n- If a brief exists at `docs/features/<slug>/brief.md`, write to `docs/features/<slug>/research.md` (per-feature layout).\n- If no brief exists (inline description only), write to `docs/research/YYYY-MM-DD-feature-name.md` (flat layout).\n\nWrite the questions to `docs/features/<slug>/.questions-tmp.md`. **Do NOT include any content from the brief.**\n\n---\n\n## Phase 2: Spawn Research Subagent\n\nSpawn a subagent to perform the research. Pass ONLY the research questions \u2014 never the brief.\n\nSubagent prompt:\n```\nYou are researching a codebase to answer specific questions. You have NO context about why these questions are being asked.\n\nRULES:\n- Answer each question with FACTS ONLY: file paths, function signatures, data flows, patterns, dependencies\n- Do NOT recommend, suggest, or opine\n- Do NOT speculate about what should be built\n- If a question cannot be answered, say "No existing code found for this"\n- Search the codebase and read files thoroughly\n- Include code snippets only when essential evidence\n\nQUESTIONS:\n[INSERT_QUESTIONS_HERE]\n\nOUTPUT FORMAT:\n\n# Codebase Research\n\n**Date:** [today]\n**Questions answered:** [N/total]\n\n---\n\n## Q1: [question]\n[Facts only]\n\n## Q2: [question]\n[Facts only]\n```\n\n## Phase 3: Write the Research Document\n\nWrite the subagent\'s response to `docs/features/<slug>/research.md`. Delete the temporary questions file.\n\n### Update the Feature Brief\n\nAfter writing the research document, update the parent brief with a back-reference:\n1. Read `docs/features/<slug>/brief.md`\n2. In the header blockquote (the `>` lines at the top), add or update:\n   `> **Research:** docs/features/<slug>/research.md`\n3. If a `> **Research:**` line already exists, replace it \u2014 do NOT add a duplicate\n4. Write the brief back\n\nPresent:\n```\nResearch complete: docs/features/<slug>/research.md\n\nThis document contains objective facts \u2014 no opinions or recommendations.\n\nRecommended next step:\n- $joycraft-design \u2014 translate research findings into architectural decisions before building\n\nIf the scope is simple (< 5 files, well-understood area, no architectural decisions):\n- $joycraft-decompose \u2014 skip design and break directly into atomic specs\n\nOther options:\n- $joycraft-new-feature \u2014 formalize into a full Feature Brief first\n- Read the research and add corrections manually\n```\n\n## Phase 4: Reconcile Brief with Findings\n\nYou\'ve just written `docs/features/<slug>/research.md`. Before hand-off, the parent brief at `docs/features/<slug>/brief.md` may now disagree with what you discovered. Re-read it and check each of these sections:\n\n| Brief section | What to look for |\n|---|---|\n| Vision | Did your findings refine or contradict the framing? |\n| Hard Constraints | Are any constraints now obsolete, missing, or refined? |\n| Out of Scope | Did your findings push something in or out of scope? |\n| Decomposition | Are spec counts, names, or dependencies still accurate? |\n| Test Strategy | Do your findings change what or how to test? |\n| Success Criteria | Are the criteria still observable and still match the goal? |\n\n**For each section, choose one:**\n\n- **Edit in place** \u2014 small, mechanical updates: line-number corrections, clarifications, additions consistent with brief intent. No user approval needed.\n- **Diff + stop** \u2014 non-trivial changes: counts flipping, decomposition restructure, scope changes, contradiction with original brief intent. Present a diff of the proposed change, STOP, and wait for user approval before continuing.\n\nIf you make changes, note them at the bottom of `research.md` under a "Brief updates" subsection. If the brief is already in sync, note: "Reconciliation checked, no changes required." If no parent brief exists (feature was described inline), note that and skip this step.\n\n**Why this step exists:** the silent-drift gap. Without reconciliation, the brief and downstream artifacts diverge \u2014 and later decomposition is sized against the stale brief. This feature ("single-source-skills") hit exactly this: brief said "11 clean / 9 dirty" until the research re-audit forced a re-decomposition. Don\'t let it happen again.\n',
+  "joycraft-session-end.md": "---\nname: joycraft-session-end\ndescription: Wrap up a session \u2014 capture discoveries, verify, prepare for PR or next session\n---\n\n# Session Wrap-Up \u2014 Feature Finisher\n\nThis is the **once-per-feature finisher** \u2014 the heavy bookend that runs **once**, when the feature's specs are done, not after every spec. It is the **only validation gate** in the loop and the single place that pushes and opens the PR.\n\n> **Two-tier wrap-up.** The light per-spec step is `joycraft-spec-done` (status bump `todo \u2192 in-review` + commit, no validation/push/PR \u2014 it runs after each spec). This skill is the heavy counterpart: full validation, consolidate the discovery stubs spec-done left behind, graduate every `in-review` spec to `done`, push, and open the PR. See `docs/reference/spec-status-lifecycle.md` for the `todo \u2192 in-review \u2192 done` lifecycle.\n\nComplete these steps in order.\n\n## 1. Consolidate Discoveries\n\n**Why:** Discoveries are the surprises \u2014 things that weren't in the spec or that contradicted expectations. They prevent future sessions from hitting the same walls.\n\nThis is the **consolidation** pass: `joycraft-spec-done` may have left terse 2-line discovery **stubs** during the feature (one per surprising spec). Curate and expand those stubs into proper discovery docs now, and capture anything else surprising from the feature as a whole. If any stubs exist at `docs/discoveries/`, consolidate them (merge related ones, expand each into the full format below); then create or update a discovery file at `docs/discoveries/YYYY-MM-DD-topic.md`. Lazy-create the `docs/discoveries/` directory if it doesn't exist.\n\n(Discoveries stay flat at `docs/discoveries/` rather than per-feature, since they often span features and are read serendipitously rather than via a known path.)\n\nThe discovery file MUST start with YAML frontmatter \u2014 the 4-field personal schema:\n\n```yaml\n---\nstatus: todo\nowner: <resolved name>\ncreated: YYYY-MM-DD\nfeature: <slug-of-related-feature>   # omit if not feature-tied\n---\n```\n\n**Owner resolution:** look up the owner name in this order \u2014 (1) `git config user.name`, (2) value in your auto-memory `joycraft-owner.txt` if present, (3) ask the user once and persist.\n\nOnly capture what's NOT obvious from the code or git diff:\n- \"We thought X but found Y\" \u2014 assumptions that were wrong\n- \"This API/library behaves differently than documented\" \u2014 external gotchas\n- \"This edge case needs handling in a future spec\" \u2014 deferred work with context\n- \"The approach in the spec didn't work because...\" \u2014 spec-vs-reality gaps\n- Key decisions made during implementation that aren't in the spec\n\n**Do NOT capture:**\n- Files changed (that's the diff)\n- What you set out to do (that's the spec)\n- Step-by-step narrative of the session (nobody re-reads these)\n\nUse this format:\n\n```markdown\n# Discoveries \u2014 [topic]\n\n**Date:** YYYY-MM-DD\n**Spec:** [link to spec if applicable]\n\n## [Discovery title]\n**Expected:** [what we thought would happen]\n**Actual:** [what actually happened]\n**Impact:** [what this means for future work]\n```\n\nIf nothing surprising happened, skip the discovery file entirely. No discovery is a good sign \u2014 the spec was accurate.\n\n## 1b. Update Context Documents\n\nIf `docs/context/` exists, quickly check whether this session revealed anything about:\n\n- **Production risks** \u2014 did you interact with or learn about production vs staging systems? \u2192 Update `docs/context/production-map.md`\n- **Wrong assumptions** \u2014 did the agent (or you) assume something that turned out to be false? \u2192 Update `docs/context/dangerous-assumptions.md`\n- **Key decisions** \u2014 did you make an architectural or tooling choice? \u2192 Add a row to `docs/context/decision-log.md`\n- **Unwritten rules** \u2014 did you discover a convention or constraint not documented anywhere? \u2192 Update `docs/context/institutional-knowledge.md`\n\nWhen you UPDATE a context doc, also bump (or add) its YAML frontmatter \u2014 the 2-field shared schema:\n\n```yaml\n---\nlast_updated: YYYY-MM-DD\nlast_updated_by: <resolved name>\n---\n```\n\nIf the file already has the frontmatter, update the `last_updated` and `last_updated_by` fields in place. If it doesn't, prepend a fresh block. Context docs are *shared* artifacts (no single owner) \u2014 the shared schema reflects that.\n\nSkip this if nothing applies. Don't force it \u2014 only update when there's genuine new context.\n\n## 2. Run Validation \u2014 the ONLY validation gate\n\nThis is **mandatory** and it is the **only** validation gate in the loop: `joycraft-spec-done` deliberately skips validation (it trusts implement's per-spec TDD), so this feature-level run is the single cross-spec safety net. Never skip it.\n\nRun the project's validation commands. Check AGENTS.md for project-specific commands. Common checks:\n\n- Type-check (e.g., `tsc --noEmit`, `mypy`, `cargo check`)\n- Tests (e.g., `npm test`, `pytest`, `cargo test`)\n- Lint (e.g., `eslint`, `ruff`, `clippy`)\n\nFix any failures before proceeding. **If validation fails, stop \u2014 do NOT graduate specs to `done` and do NOT push.**\n\n## 3. Graduate Specs `in-review \u2192 done`\n\nThis step graduates the feature's finished specs to their terminal state. Because session-end runs once at the end, **multiple specs may be waiting** in `in-review` (one per spec the loop completed via `joycraft-spec-done`). Graduate **all** of them, in **both** systems (the queue JSON and the frontmatter must never disagree):\n\nFor each spec in `docs/features/<slug>/specs/` (or `docs/bugfixes/<area>/` for bugfixes \u2014 scan recursively) whose status is `in-review`:\n\n1. **Queue JSON** \u2014 `joycraft-mark-done <spec-id> --to done <specs-dir>` (the `--to done` graduation; find `<spec-id>` by matching the entry's `file`).\n2. **Frontmatter** \u2014 edit the spec file's YAML `status:` to `done`.\n\nRules:\n- Only graduate specs that are `in-review`. A spec still at `todo` was never started \u2014 **leave it `todo` and report it as remaining** (the feature isn't fully done; see the PR gate in step 5).\n- Never write `done` for work nothing has validated \u2014 this validation run (step 2) is what licenses the graduation. (Once `verify-in-loop` ships, an independent verify performs the `in-review \u2192 done` transition; until then, this step does.)\n- `done` means **verified**, not **merged**. A merged PR is a git fact, never a spec status \u2014 do not invent a `merged` status or any fourth state beyond `todo`/`in-review`/`done`.\n\nIf working from a Feature Brief at `docs/features/<slug>/brief.md`, also check off completed specs in the decomposition table.\n\n## 4. Commit\n\nCommit all changes including the discovery file (if created) and spec status updates. The commit message should reference the spec if applicable.\n\n## 5. Push and PR (if autonomous git is enabled)\n\n**Check AGENTS.md for \"Git Autonomy\" in the Behavioral Boundaries section.** If it says \"STRICTLY ENFORCED\" or the ALWAYS section includes \"Push to feature branches immediately after every commit\":\n\n1. **Push immediately.** Run `git push origin <branch>` \u2014 do not ask, do not hesitate.\n2. **Open a PR if the feature is complete.** The feature is complete when every spec is `done` (none left at `todo`/`in-review`). Check the queue JSON / decomposition table \u2014 if all specs are `done`, run `gh pr create` with a summary of all completed specs. Do not ask first.\n3. **If specs remain (`todo`),** still push. The PR comes when the feature's last spec is graduated.\n\nIf AGENTS.md does NOT have autonomous git rules (or has \"ASK FIRST\" for pushing), ask the user before pushing.\n\n## 6. Report and Hand Off\n\n```\nFeature complete.\n- Feature: [slug]\n- Specs graduated to done: [N] (remaining at todo: [N])\n- Build: [passing / failing]\n- Discoveries: [N consolidated / none]\n- Pushed: [yes / no \u2014 and why not]\n- PR: [opened #N / not yet \u2014 N specs remaining]\n- Next: [what comes after this feature]\n```\n\nEnd with the canonical Handoff block. Include any discovery and updated-context paths produced.\n\n## Recommended Next Steps\n\nNext:\n```bash\n$joycraft-implement docs/features/<slug>/specs/<next-spec>.md\n```\nRun run `/clear` in the CLI, or press Cmd+N (Ctrl+N on Windows/Linux) for a new thread in the desktop/IDE app first.\n\nIf all specs in the feature are complete, hand off to a feature-level wrap-up instead (PR review, etc.) \u2014 the Handoff block is just the slash command for whatever the next move is.\n",
   "joycraft-setup.md": '---\nname: joycraft-setup\ndescription: Set up Joycraft and get started on this project -- the first-time entry point. Run this when you\'re configuring your project, onboarding, or asking "where do I begin?" / "how do I set this up?"\n---\n\n# Setup \u2014 The First-Run Door\n\nThis is the obvious starting point for setting up Joycraft on this project. It does no work of its own \u2014 it routes you to the skill that does the real assessment and onboarding.\n\n**Run `$joycraft-tune`.**\n\n`$joycraft-tune` detects your project\'s current harness state, scores it, applies the upgrades it can, and on a first run kicks off the context-onboarding pass for you. That\'s the whole setup flow \u2014 this alias just exists so "set up", "get started", and "first time" lead you there.\n\nDo not re-implement assessment or scoring here; hand off to `$joycraft-tune`.\n',
-  "joycraft-spec-done.md": "---\nname: joycraft-spec-done\ndescription: Lightweight per-spec wrap-up \u2014 bump status to in-review, terse discovery if surprised, commit. Run after each spec in checkpoint/isolated mode; no validation, no push, no PR.\n---\n\n# Spec Done (Lightweight Per-Spec Wrap-Up)\n\nYou just finished implementing **one** atomic spec. This is the fast handshake that runs **once per spec**, before context clears \u2014 the `todo \u2192 in-review` transition in the lifecycle (`docs/reference/spec-status-lifecycle.md`). It is deliberately tiny: it does exactly four things and nothing more.\n\n> **This is NOT session-end.** It does **not** run validation, push, or open a PR. It trusts the TDD you just did in `$joycraft-implement`. The heavy once-per-feature wrap-up (full validation + consolidate discoveries + push + PR) is `$joycraft-session-end`, which runs once at the end of the feature.\n>\n> **Usually you don't run this by hand:** `$joycraft-implement` performs these four steps itself at the end of every checkpoint/isolated spec (and `$joycraft-implement-feature` drives whole queues). This skill remains the canonical definition of the wrap-up \u2014 run it manually after ad-hoc work done outside the implement skill, or when an implement run was interrupted before wrapping up.\n\n## Step 1: Bump status to `in-review` \u2014 in BOTH systems\n\nA spec's status lives in two places that must never disagree (the desync this feature exists to kill): the **queue JSON** and the spec's **frontmatter**. Update both to `in-review`.\n\n1. **Queue JSON** \u2014 use the script, not a bespoke `sed`:\n   ```bash\n   joycraft-mark-done <spec-id> --to in-review <specs-dir>\n   ```\n   Find `<spec-id>` by reading `<specs-dir>/.joycraft-spec-queue.json` and matching the entry whose `file` is the spec you just implemented. `<specs-dir>` is the folder containing the spec (e.g. `docs/features/<slug>/specs`). If the spec isn't in the manifest, `joycraft-mark-done` exits non-zero with a clear error \u2014 **surface that error, don't silently skip the bump**.\n2. **Frontmatter** \u2014 edit the spec file's YAML `status:` field to `in-review`.\n\nDo **not** graduate to `done`. The agent never self-certifies \u2014 `done` is reached only by `$joycraft-session-end` (or, later, an independent verify). `spec-done` only ever reaches `in-review`.\n\n## Step 2: Terse discovery stub \u2014 ONLY if something surprised you\n\nDid anything during implementation **contradict the spec** or surprise you (an assumption that was wrong, an external API that behaved differently, an edge case the spec missed)?\n\n- **No** \u2192 skip this step entirely. A spec that went as written needs no discovery. This is the common case.\n- **Yes** \u2192 write a **2-line stub** (not a full discovery doc) at `docs/discoveries/YYYY-MM-DD-topic.md`: one line on what contradicted the spec, one line pointing at the spec/file. `$joycraft-session-end`'s consolidation pass later expands these stubs into proper discovery docs \u2014 keep it terse here.\n\n## Step 3: Commit\n\nCommit the spec's implementation changes plus the status edits (and the stub, if any) with the convention:\n\n```\nspec: <spec-name>\n```\n\nKeep scope disciplined \u2014 commit the spec's changes and its status edits, not unrelated working-tree noise.\n\n## Step 4: Stop\n\nThat's it. **No** validation re-run, **no** push, **no** PR \u2014 those belong to `$joycraft-session-end` at feature end. Hand off and keep the loop moving.\n\n## Recommended Next Steps\n\nIf more specs remain in this feature (checkpoint/isolated mode), continue to the next one:\n\n```\n$joycraft-implement docs/features/<slug>/specs/<next-spec>.md\n```\n\nWhen the feature's last spec is done, run the feature finisher once:\n\n```\n$joycraft-session-end\n```\n\nRun /clear before your next step \u2014 your artifacts are saved to files.\n",
-  "joycraft-tune.md": "---\nname: joycraft-tune\ndescription: Assess and upgrade your project's AI development harness \u2014 score 7 dimensions, apply fixes, show path to Level 5\n---\n\n# Tune \u2014 Project Harness Assessment & Upgrade\n\nYou are evaluating and upgrading this project's AI development harness.\n\n## Step 1: Detect Harness State\n\nSearch the codebase for: CLAUDE.md (with meaningful content), `docs/features/<slug>/` (briefs + specs), `docs/bugfixes/<area>/`, `docs/discoveries/`, `docs/context/*.md` fact-docs, `docs/context/reference/` long-form docs, `.agents/skills/`, and test configuration.\n\n## Step 2: Route\n\n- **No harness** (no CLAUDE.md or just a README): Recommend `npx joycraft init` and stop.\n- **Harness exists**: Continue to assessment.\n\n## Step 3: Assess \u2014 Score 7 Dimensions (1-5 scale)\n\nRead CLAUDE.md and explore the project. Score each with specific evidence:\n\n| Dimension | What to Check |\n|-----------|--------------|\n| Spec Quality | `docs/features/<slug>/specs/` (scan recursively; also `docs/bugfixes/<area>/`) \u2014 structured? acceptance criteria? self-contained? |\n| Spec Granularity | Can each spec be done in one session? |\n| Behavioral Boundaries | ALWAYS/ASK FIRST/NEVER sections (or equivalent rules under any heading) |\n| Skills & Hooks | `.agents/skills/` files, hooks config |\n| Documentation | `docs/` structure, templates, referenced from CLAUDE.md. Reward a lean + pointered CLAUDE.md. **Flag a CLAUDE.md exceeding ~200 lines** \u2014 recommend extracting long sections into `docs/context/reference/` and replacing them with a `## Context Map` pointer table. This is advisory only; tune never auto-edits CLAUDE.md. |\n| Knowledge Capture | `docs/discoveries/`, `docs/context/*.md` fact-docs, `docs/context/reference/` long-form docs \u2014 existence AND real content |\n| Testing & Validation | Test framework, CI pipeline, validation commands in CLAUDE.md |\n\nScore 1 = absent, 3 = partially there, 5 = comprehensive. Give credit for substance over format.\n\n## Step 4: Write Assessment\n\nWrite to `docs/joycraft-assessment.md` AND display it. Include: scores table, detailed findings (evidence + gap + recommendation per dimension), and an upgrade plan (up to 5 actions ordered by impact).\n\n## Step 5: Apply Upgrades\n\nApply using three tiers \u2014 do NOT ask per-item permission:\n\n**Tier 1 (silent):** Create missing dirs, install missing skills, copy missing templates, create AGENTS.md.\n\n**Before Tier 2, ask about git autonomy:** Cautious (ask before push/PR) or Autonomous (push + PR without asking)?\n\n**First-run context onboarding:** On a first run (the context layer is empty or absent), invoke `$joycraft-gather-context` for the read-then-offer onboarding pass \u2014 it owns reading existing docs, offering a gap-only interview, and populating `docs/context/` (fact-docs and `docs/context/reference/`). Do NOT run a separate risk interview here; gather is the onboarding path. On a recurring run of an already-populated project, skip this \u2014 gather is the first-run path, not forced every time.\n\nFrom git-autonomy and gather, generate: CLAUDE.md boundary rules, deny patterns configuration. Also recommend a permission mode (`auto` for most; `dontAsk` + allowlist for high-risk).\n\n**Tier 2 (show diff):** Add missing CLAUDE.md sections (Boundaries, Workflow, Key Files). Draft from real codebase content. Append only \u2014 never reformat existing content.\n\n**Tier 3 (confirm first):** Rewriting existing sections, overwriting customized files, suggesting test framework installs.\n\nAfter applying, append to `docs/joycraft-history.md` and show a consolidated upgrade results table.\n\n## Step 6: Show Path to Level 5\n\nShow a tailored roadmap: Level 2-5 table, specific next steps based on actual gaps, and the Level 5 north star (spec queue, autofix, holdout scenarios, self-improving harness).\n\n**Tip:** Run `$joycraft-optimize` to audit your session's token overhead \u2014 plugins, MCP servers, and harness file sizes.\n\n## Edge Cases\n\n- **CLAUDE.md is just a README:** Treat as no harness.\n- **Non-Joycraft skills:** Acknowledge, don't replace.\n- **Rules under non-standard headings:** Give credit for substance.\n- **Previous assessment exists:** Read it first. If nothing to upgrade, say so.\n- **Non-Joycraft content in CLAUDE.md:** Preserve as-is. Only append.\n",
-  "joycraft-verify.md": '---\nname: joycraft-verify\ndescription: Spawn an independent verifier subagent to check an implementation against its spec -- read-only, no code edits, structured pass/fail verdict\n---\n\n# Verify Implementation Against Spec\n\nThe user wants independent verification of an implementation. Your job is to find the relevant spec, extract its acceptance criteria and test plan, then spawn a separate verifier subagent that checks each criterion and produces a structured verdict.\n\n**Why a separate subagent?** Research found that agents reliably skew positive when grading their own work. Separating the agent doing the work from the agent judging it consistently outperforms self-evaluation. The verifier gets a clean context window with no implementation bias.\n\n## Step 1: Find the Spec\n\nIf the user provided a spec path (e.g., `$joycraft-verify docs/features/<slug>/specs/add-widget.md`), use that path directly.\n\nIf no path was provided, scan `docs/features/*/specs/` recursively for spec files (and `docs/bugfixes/<area>/` for bugfixes). Pick the most recently modified `.md` file. If no specs exist, tell the user:\n\n> No specs found under `docs/features/*/specs/` or `docs/bugfixes/`. Please provide a spec path: `$joycraft-verify path/to/spec.md`\n\n## Step 2: Read and Parse the Spec\n\nRead the spec file and extract:\n\n1. **Spec name** -- from the H1 title\n2. **Acceptance Criteria** -- the checklist under the `## Acceptance Criteria` section\n3. **Test Plan** -- the table under the `## Test Plan` section, including any test commands\n4. **Constraints** -- the `## Constraints` section if present\n\nIf the spec has no Acceptance Criteria section, tell the user:\n\n> This spec doesn\'t have an Acceptance Criteria section. Verification needs criteria to check against. Add acceptance criteria to the spec and try again.\n\nIf the spec has no Test Plan section, note this but proceed -- the verifier can still check criteria by reading code and running any available project tests.\n\n## Step 3: Identify Test Commands\n\nLook for test commands in these locations (in priority order):\n\n1. The spec\'s Test Plan section (look for commands in backticks or "Type" column entries like "unit", "integration", "e2e", "build")\n2. The project\'s CLAUDE.md or AGENTS.md (look for test/build commands in the Development Workflow section)\n3. Common defaults based on the project type:\n   - Node.js: `npm test` or `pnpm test --run`\n   - Python: `pytest`\n   - Rust: `cargo test`\n   - Go: `go test ./...`\n\nBuild a list of specific commands the verifier should run.\n\n## Step 4: Spawn the Verifier Subagent\n\nSpawn a concurrent subagent thread with the following prompt. Replace the placeholders with the actual content extracted in Steps 2-3.\n\n**Important:** The subagent must be given read-only constraints. It may search the codebase, read files, and run the specified test/build commands, but it must NOT edit or create any files.\n\n```\nYou are a QA verifier. Your job is to independently verify an implementation against its spec. You have NO context about how the implementation was done -- you are checking it fresh.\n\nRULES -- these are hard constraints, not suggestions:\n- You may search the codebase and read any file\n- You may RUN these specific test/build commands: [TEST_COMMANDS]\n- You may NOT edit, create, or delete any files\n- You may NOT run commands that modify state (no git commit, no npm install, no file writes)\n- You may NOT install packages or access the network\n- Report what you OBSERVE, not what you expect or hope\n\nSPEC NAME: [SPEC_NAME]\n\nACCEPTANCE CRITERIA:\n[ACCEPTANCE_CRITERIA]\n\nTEST PLAN:\n[TEST_PLAN]\n\nCONSTRAINTS:\n[CONSTRAINTS_OR_NONE]\n\nYOUR TASK:\nFor each acceptance criterion, determine if it PASSES or FAILS based on evidence:\n\n1. Run the test commands listed above. Record the output.\n2. For each acceptance criterion:\n   a. Check if there is a corresponding test and whether it passes\n   b. If no test exists, read the relevant source files to verify the criterion is met\n   c. If the criterion cannot be verified by reading code or running tests, mark it MANUAL CHECK NEEDED\n3. For criteria about build/test passing, actually run the commands and report results.\n\nOUTPUT FORMAT -- you MUST use this exact format:\n\nVERIFICATION REPORT\n\n| # | Criterion | Verdict | Evidence |\n|---|-----------|---------|----------|\n| 1 | [criterion text] | PASS/FAIL/MANUAL CHECK NEEDED | [what you observed] |\n| 2 | [criterion text] | PASS/FAIL/MANUAL CHECK NEEDED | [what you observed] |\n[continue for all criteria]\n\nSUMMARY: X/Y criteria passed. [Z failures need attention. / All criteria verified.]\n\nIf any test commands fail to run (missing dependencies, wrong command, etc.), report the error as evidence for a FAIL verdict on the relevant criterion.\n```\n\n## Step 5: Format and Present the Verdict\n\nTake the subagent\'s response and present it to the user in this format:\n\n```\n## Verification Report -- [Spec Name]\n\n| # | Criterion | Verdict | Evidence |\n|---|-----------|---------|----------|\n| 1 | ... | PASS | ... |\n| 2 | ... | FAIL | ... |\n\n**Overall: X/Y criteria passed.**\n\n[If all passed:]\nAll criteria verified. Ready to commit and open a PR.\n\n[If any failed:]\nN failures need attention. Review the evidence above and fix before proceeding.\n\n[If any MANUAL CHECK NEEDED:]\nN criteria need manual verification -- they can\'t be checked by reading code or running tests alone.\n```\n\n## Step 6: Suggest Next Steps\n\nBased on the verdict:\n\n- **All PASS:** Suggest committing and opening a PR, or running `$joycraft-session-end` to capture discoveries.\n- **Some FAIL:** List the failed criteria and suggest the user fix them, then run `$joycraft-verify` again.\n- **MANUAL CHECK NEEDED items:** Explain what needs human eyes and why automation couldn\'t verify it.\n\n**Do NOT offer to fix failures yourself.** The verifier reports; the human (or implementation agent in a separate turn) decides what to do. This separation is the whole point.\n\n## Edge Cases\n\n| Scenario | Behavior |\n|----------|----------|\n| Spec has no Test Plan | Warn that verification is weaker without a test plan, but proceed by checking criteria through code reading and any available project-level tests |\n| All tests pass but a criterion is not testable | Mark as MANUAL CHECK NEEDED with explanation |\n| Subagent can\'t run tests (missing deps) | Report the error as FAIL evidence |\n| No specs found and no path given | Tell user to provide a spec path or create a spec first |\n| Spec status is "Complete" | Still run verification -- "Complete" means the implementer thinks it\'s done, verification confirms |\n'
+  "joycraft-spec-done.md": "---\nname: joycraft-spec-done\ndescription: Lightweight per-spec wrap-up \u2014 bump status to in-review, terse discovery if surprised, commit. Run after each spec in checkpoint/isolated mode; no validation, no push, no PR.\n---\n\n# Spec Done (Lightweight Per-Spec Wrap-Up)\n\nYou just finished implementing **one** atomic spec. This is the fast handshake that runs **once per spec**, before context clears \u2014 the `todo \u2192 in-review` transition in the lifecycle (`docs/reference/spec-status-lifecycle.md`). It is deliberately tiny: it does exactly four things and nothing more.\n\n> **This is NOT session-end.** It does **not** run validation, push, or open a PR. It trusts the TDD you just did in `joycraft-implement`. The heavy once-per-feature wrap-up (full validation + consolidate discoveries + push + PR) is `joycraft-session-end`, which runs once at the end of the feature.\n>\n> **Usually you don't run this by hand:** `joycraft-implement` performs these four steps itself at the end of every checkpoint/isolated spec (and `joycraft-implement-feature` drives whole queues). This skill remains the canonical definition of the wrap-up \u2014 run it manually after ad-hoc work done outside the implement skill, or when an implement run was interrupted before wrapping up.\n\n## Step 1: Bump status to `in-review` \u2014 in BOTH systems\n\nA spec's status lives in two places that must never disagree (the desync this feature exists to kill): the **queue JSON** and the spec's **frontmatter**. Update both to `in-review`.\n\n1. **Queue JSON** \u2014 use the script, not a bespoke `sed`:\n   ```bash\n   joycraft-mark-done <spec-id> --to in-review <specs-dir>\n   ```\n   Find `<spec-id>` by reading `<specs-dir>/.joycraft-spec-queue.json` and matching the entry whose `file` is the spec you just implemented. `<specs-dir>` is the folder containing the spec (e.g. `docs/features/<slug>/specs`). If the spec isn't in the manifest, `joycraft-mark-done` exits non-zero with a clear error \u2014 **surface that error, don't silently skip the bump**.\n2. **Frontmatter** \u2014 edit the spec file's YAML `status:` field to `in-review`.\n\nDo **not** graduate to `done`. The agent never self-certifies \u2014 `done` is reached only by `joycraft-session-end` (or, later, an independent verify). `spec-done` only ever reaches `in-review`.\n\n## Step 2: Terse discovery stub \u2014 ONLY if something surprised you\n\nDid anything during implementation **contradict the spec** or surprise you (an assumption that was wrong, an external API that behaved differently, an edge case the spec missed)?\n\n- **No** \u2192 skip this step entirely. A spec that went as written needs no discovery. This is the common case.\n- **Yes** \u2192 write a **2-line stub** (not a full discovery doc) at `docs/discoveries/YYYY-MM-DD-topic.md`: one line on what contradicted the spec, one line pointing at the spec/file. `joycraft-session-end`'s consolidation pass later expands these stubs into proper discovery docs \u2014 keep it terse here.\n\n## Step 3: Commit\n\nCommit the spec's implementation changes plus the status edits (and the stub, if any) with the convention:\n\n```\nspec: <spec-name>\n```\n\nKeep scope disciplined \u2014 commit the spec's changes and its status edits, not unrelated working-tree noise.\n\n## Step 4: Stop\n\nThat's it. **No** validation re-run, **no** push, **no** PR \u2014 those belong to `joycraft-session-end` at feature end. Hand off and keep the loop moving.\n\n## Recommended Next Steps\n\nIf more specs remain in this feature (checkpoint/isolated mode), continue to the next one:\n\n```bash\n$joycraft-implement docs/features/<slug>/specs/<next-spec>.md\n```\n\nWhen the feature's last spec is done, run the feature finisher once:\n\n```bash\n$joycraft-session-end\n```\n",
+  "joycraft-tune.md": "---\nname: joycraft-tune\ndescription: Assess and upgrade your project's AI development harness \u2014 score 7 dimensions, apply fixes, show path to Level 5\n---\n\n# Tune \u2014 Project Harness Assessment & Upgrade\n\nYou are evaluating and upgrading this project's AI development harness.\n\n## Step 1: Detect Harness State\n\nCheck for: AGENTS.md (with meaningful content), `docs/features/<slug>/` (briefs + specs), `docs/bugfixes/<area>/`, `docs/discoveries/`, `docs/context/*.md` fact-docs, `docs/context/reference/` long-form docs, `.agents/skills/`, and test configuration.\n\n## Step 2: Route\n\n- **No harness** (no AGENTS.md or just a README): Recommend `npx joycraft init` and stop.\n- **Harness exists**: Continue to assessment.\n\n## Step 3: Assess \u2014 Score 7 Dimensions (1-5 scale)\n\nRead AGENTS.md and explore the project. Score each with specific evidence:\n\n| Dimension | What to Check |\n|-----------|--------------|\n| Spec Quality | `docs/features/<slug>/specs/` (scan recursively; also `docs/bugfixes/<area>/`) \u2014 structured? acceptance criteria? self-contained? |\n| Spec Granularity | Can each spec be done in one session? |\n| Behavioral Boundaries | ALWAYS/ASK FIRST/NEVER sections (or equivalent rules under any heading) |\n| Skills & Hooks | `.agents/skills/` files, hooks config |\n| Documentation | `docs/` structure, templates, referenced from AGENTS.md. Reward a lean + pointered AGENTS.md. **Flag a AGENTS.md exceeding ~200 lines** \u2014 recommend extracting long sections into `docs/context/reference/` and replacing them with a `## Context Map` pointer table. This is advisory only; tune never auto-edits AGENTS.md. |\n| Knowledge Capture | `docs/discoveries/`, `docs/context/*.md` fact-docs, `docs/context/reference/` long-form docs \u2014 existence AND real content |\n| Testing & Validation | Test framework, CI pipeline, validation commands in AGENTS.md |\n\nScore 1 = absent, 3 = partially there, 5 = comprehensive. Give credit for substance over format.\n\n## Step 4: Write Assessment\n\nWrite to `docs$joycraft-assessment.md` AND display it. Include: scores table, detailed findings (evidence + gap + recommendation per dimension), and an upgrade plan (up to 5 actions ordered by impact).\n\n## Step 5: Apply Upgrades\n\nApply using three tiers \u2014 do NOT ask per-item permission:\n\n**Tier 1 (silent):** Create missing dirs, install missing skills, copy missing templates, create AGENTS.md.\n\n**Before Tier 2, ask about git autonomy:** Cautious (ask before push/PR) or Autonomous (push + PR without asking)?\n\n**First-run context onboarding:** On a first run (the context layer is empty or absent), invoke `$joycraft-gather-context` for the read-then-offer onboarding pass \u2014 it owns reading existing docs, offering a gap-only interview, and populating `docs/context/` (fact-docs and `docs/context/reference/`). Do NOT run a separate risk interview here; gather is the onboarding path. On a recurring run of an already-populated project, skip this \u2014 gather is the first-run path, not forced every time.\n\nFrom git-autonomy and gather, generate: AGENTS.md boundary rules, `.claude/settings.json` deny patterns. Also recommend a permission mode (`auto` for most; `dontAsk` + allowlist for high-risk).\n\n**Tier 2 (show diff):** Add missing AGENTS.md sections (Boundaries, Workflow, Key Files). Draft from real codebase content. Append only \u2014 never reformat existing content.\n\n**Tier 3 (confirm first):** Rewriting existing sections, overwriting customized files, suggesting test framework installs.\n\nAfter applying, append to `docs$joycraft-history.md` and show a consolidated upgrade results table.\n\n## Step 6: Show Path to Level 5\n\nShow a tailored roadmap: Level 2-5 table, specific next steps based on actual gaps, and the Level 5 north star (spec queue, autofix, holdout scenarios, self-improving harness).\n\n**Tip:** Run `$joycraft-optimize` to audit your session's token overhead \u2014 plugins, MCP servers, and harness file sizes.\n\n## Edge Cases\n\n- **AGENTS.md is just a README:** Treat as no harness.\n- **Non-Joycraft skills:** Acknowledge, don't replace.\n- **Rules under non-standard headings:** Give credit for substance.\n- **Previous assessment exists:** Read it first. If nothing to upgrade, say so.\n- **Non-Joycraft content in AGENTS.md:** Preserve as-is. Only append.\n",
+  "joycraft-verify.md": '---\nname: joycraft-verify\ndescription: Spawn an independent verifier subagent to check an implementation against its spec -- read-only, no code edits, structured pass/fail verdict\n---\n\n# Verify Implementation Against Spec\n\nThe user wants independent verification of an implementation. Your job is to find the relevant spec, extract its acceptance criteria and test plan, then spawn a separate verifier subagent that checks each criterion and produces a structured verdict.\n\n**Why a separate subagent?** Research found that agents reliably skew positive when grading their own work. Separating the agent doing the work from the agent judging it consistently outperforms self-evaluation. The verifier gets a clean context window with no implementation bias.\n\n## Step 1: Find the Spec\n\nIf the user provided a spec path (e.g., `$joycraft-verify docs/features/<slug>/specs/add-widget.md`), use that path directly.\n\nIf no path was provided, scan `docs/features/*/specs/` recursively for spec files (and `docs/bugfixes/<area>/` for bugfixes). Pick the most recently modified `.md` file. If no specs exist, tell the user:\n\n> No specs found under `docs/features/*/specs/` or `docs/bugfixes/`. Please provide a spec path: `$joycraft-verify path/to/spec.md`\n\n## Step 2: Read and Parse the Spec\n\nRead the spec file and extract:\n\n1. **Spec name** -- from the H1 title\n2. **Acceptance Criteria** -- the checklist under the `## Acceptance Criteria` section\n3. **Test Plan** -- the table under the `## Test Plan` section, including any test commands\n4. **Constraints** -- the `## Constraints` section if present\n\nIf the spec has no Acceptance Criteria section, tell the user:\n\n> This spec doesn\'t have an Acceptance Criteria section. Verification needs criteria to check against. Add acceptance criteria to the spec and try again.\n\nIf the spec has no Test Plan section, note this but proceed -- the verifier can still check criteria by reading code and running any available project tests.\n\n## Step 3: Identify Test Commands\n\nLook for test commands in these locations (in priority order):\n\n1. The spec\'s Test Plan section (look for commands in backticks or "Type" column entries like "unit", "integration", "e2e", "build")\n2. The project\'s AGENTS.md (look for test/build commands in the Development Workflow section)\n3. Common defaults based on the project type:\n   - Node.js: `npm test` or `pnpm test --run`\n   - Python: `pytest`\n   - Rust: `cargo test`\n   - Go: `go test ./...`\n\nBuild a list of specific commands the verifier should run.\n\n## Step 4: Spawn the Verifier Subagent\n\nSpawn a concurrent subagent thread with the following prompt. Replace the placeholders with the actual content extracted in Steps 2-3.\n\n**Important:** The subagent must be given read-only constraints. It may search the codebase, read files, and run the specified test/build commands, but it must NOT edit or create any files.\n\n```\nYou are a QA verifier. Your job is to independently verify an implementation against its spec. You have NO context about how the implementation was done -- you are checking it fresh.\n\nRULES -- these are hard constraints, not suggestions:\n- You may search the codebase and read any file\n- You may RUN these specific test/build commands: [TEST_COMMANDS]\n- You may NOT edit, create, or delete any files\n- You may NOT run commands that modify state (no git commit, no npm install, no file writes)\n- You may NOT install packages or access the network\n- Report what you OBSERVE, not what you expect or hope\n\nSPEC NAME: [SPEC_NAME]\n\nACCEPTANCE CRITERIA:\n[ACCEPTANCE_CRITERIA]\n\nTEST PLAN:\n[TEST_PLAN]\n\nCONSTRAINTS:\n[CONSTRAINTS_OR_NONE]\n\nYOUR TASK:\nFor each acceptance criterion, determine if it PASSES or FAILS based on evidence:\n\n1. Run the test commands listed above. Record the output.\n2. For each acceptance criterion:\n   a. Check if there is a corresponding test and whether it passes\n   b. If no test exists, read the relevant source files to verify the criterion is met\n   c. If the criterion cannot be verified by reading code or running tests, mark it MANUAL CHECK NEEDED\n3. For criteria about build/test passing, actually run the commands and report results.\n\nOUTPUT FORMAT -- you MUST use this exact format:\n\nVERIFICATION REPORT\n\n| # | Criterion | Verdict | Evidence |\n|---|-----------|---------|----------|\n| 1 | [criterion text] | PASS/FAIL/MANUAL CHECK NEEDED | [what you observed] |\n| 2 | [criterion text] | PASS/FAIL/MANUAL CHECK NEEDED | [what you observed] |\n[continue for all criteria]\n\nSUMMARY: X/Y criteria passed. [Z failures need attention. / All criteria verified.]\n\nIf any test commands fail to run (missing dependencies, wrong command, etc.), report the error as evidence for a FAIL verdict on the relevant criterion.\n```\n\n## Step 5: Format and Present the Verdict\n\nTake the subagent\'s response and present it to the user in this format:\n\n```\n## Verification Report -- [Spec Name]\n\n| # | Criterion | Verdict | Evidence |\n|---|-----------|---------|----------|\n| 1 | ... | PASS | ... |\n| 2 | ... | FAIL | ... |\n\n**Overall: X/Y criteria passed.**\n\n[If all passed:]\nAll criteria verified. Ready to commit and open a PR.\n\n[If any failed:]\nN failures need attention. Review the evidence above and fix before proceeding.\n\n[If any MANUAL CHECK NEEDED:]\nN criteria need manual verification -- they can\'t be checked by reading code or running tests alone.\n```\n\n## Step 6: Suggest Next Steps\n\nBased on the verdict:\n\n- **All PASS:** Suggest committing and opening a PR, or running `$joycraft-session-end` to capture discoveries.\n- **Some FAIL:** List the failed criteria and suggest the user fix them, then run `$joycraft-verify` again.\n- **MANUAL CHECK NEEDED items:** Explain what needs human eyes and why automation couldn\'t verify it.\n\n**Do NOT offer to fix failures yourself.** The verifier reports; the human (or implementation agent in a separate turn) decides what to do. This separation is the whole point.\n\n## Edge Cases\n\n| Scenario | Behavior |\n|----------|----------|\n| Spec has no Test Plan | Warn that verification is weaker without a test plan, but proceed by checking criteria through code reading and any available project-level tests |\n| All tests pass but a criterion is not testable | Mark as MANUAL CHECK NEEDED with explanation |\n| Subagent can\'t run tests (missing deps) | Report the error as FAIL evidence |\n| No specs found and no path given | Tell user to provide a spec path or create a spec first |\n| Spec status is "Complete" | Still run verification -- "Complete" means the implementer thinks it\'s done, verification confirms |\n'
 };
 var PI_SKILLS = {
-  "joycraft-add-context.md": '---\nname: joycraft-add-context\ndescription: Author one long-form reference doc -- a design system, frontend/backend methodology, testing conventions, or any other long-form reference doc -- scaffolding it from a template and wiring a pointer into the project boundary file\'s Context Map\n---\n\n# Add Context\n\nThe user wants to author ONE long-form reference doc \u2014 a design system, a frontend or backend methodology, testing conventions, or any other long-form reference for this project. Your job is to scaffold that doc from the matching template, fill in what the user has told you, write it immediately, and wire a pointer row into the project\'s `## Context Map`.\n\nThis is the single-doc primitive. Write-as-you-go is correct here: you scaffold and write ONE doc per invocation, immediately \u2014 not a batch.\n\nThis skill is self-contained. Everything you need is below; do not call into or import another skill\'s logic.\n\n## Step 1: Determine Topic and Slug\n\nFigure out what reference doc the user wants. If they named it (e.g., `/skill:joycraft-add-context our design system`), use that. Otherwise ask: "What reference doc do you want to author?" \u2014 then wait.\n\nDerive a kebab-case `<slug>` from the topic (e.g., "our design system" \u2192 `design-system`, "payments service backend" \u2192 `payments-backend`).\n\n## Step 2: Pick the Matching Template\n\nChoose the bundled template in `docs/templates/context/reference/` that best fits the topic:\n\n| Topic | Template |\n|-------|----------|\n| Design system, tokens, components, visual language | `design-system.md` |\n| Frontend architecture, state, folder conventions, patterns | `frontend-methodology.md` |\n| Service boundaries, API conventions, data model, errors | `backend.md` |\n| Test pyramid, frameworks, fixtures, CI gates | `testing.md` |\n| Anything else not covered above | `reference-doc.md` (generic fallback) |\n\nIf the topic matches none of the four named templates, use the generic `reference-doc.md`.\n\n## Step 3: Scaffold the Doc to `docs/context/reference/<slug>.md`\n\n1. **Lazy-create `docs/context/reference/`** \u2014 create the directory only now, on first write. Do not create it preemptively in projects that never call this skill.\n2. Read the chosen template from `docs/templates/context/reference/`. If that template file isn\'t present in the project, fall back to a minimal skeleton: an `# H1` title, a `>` purpose blockquote, and one `##` section.\n3. Copy the template to `docs/context/reference/<slug>.md`, set the H1 to the real topic, and fill in whatever the user has already told you. Leave the rest of the template\'s deletable italic examples in place for the author to replace.\n4. **Write the doc immediately** \u2014 this single doc, this invocation. Do not defer or batch.\n\nIf `docs/context/reference/<slug>.md` already exists (the user is re-running for the same slug), update it in place rather than creating a duplicate.\n\n## Step 4: Add or Update the Context Map Pointer Row (Idempotent)\n\nRead the project\'s boundary file \u2014 CLAUDE.md and/or AGENTS.md, whichever the project uses \u2014 and maintain a pointer row for this doc in the `## Context Map` section. The row format is:\n\n```\n| docs/context/reference/<slug>.md | <when to read it> |\n```\n\nApply this idempotent logic exactly:\n\n1. **If a `## Context Map` section does not exist**, create it (place it after the project intro / Behavioral Boundaries area, before deep architecture). Add the header and a two-column table:\n\n   ```markdown\n   ## Context Map\n\n   | Doc | When to read it |\n   |-----|-----------------|\n   ```\n\n2. **If a row whose first cell is `docs/context/reference/<slug>.md` already exists**, update that row in place (refresh the "when to read it" cell). Do NOT add a second row for the same path.\n\n3. **Otherwise**, append one new row to the Context Map table.\n\nNever duplicate a row. The Context Map is a lightweight pointer index \u2014 one row per reference doc, nothing more.\n\n## Step 5: Confirm\n\nReport what you did:\n\n```\nScaffolded docs/context/reference/<slug>.md from the <template> template.\nContext Map row [added | updated]:\n  | docs/context/reference/<slug>.md | <when to read it> |\n\nFill in the doc\'s sections \u2014 the italic examples are placeholders to replace or delete.\n```\n',
-  "joycraft-add-fact.md": '---\nname: joycraft-add-fact\ndescription: Capture a project fact and route it to the correct context document -- production map, dangerous assumptions, decision log, institutional knowledge, or troubleshooting\n---\n\n# Add Fact\n\nThe user has a fact to capture. Your job is to classify it, route it to the correct context document, append it in the right format, and optionally add a boundary rule to CLAUDE.md or AGENTS.md.\n\n## Step 1: Get the Fact\n\nIf the user already provided the fact (e.g., `/skill:joycraft-add-fact the staging DB resets every Sunday`), use it directly.\n\nIf not, ask: "What fact do you want to capture?" -- then wait for their response.\n\nIf the user provides multiple facts at once, process each one separately through all the steps below, then give a combined confirmation at the end.\n\n## Step 2: Classify the Fact\n\nRoute the fact to one of these 5 context documents based on its content:\n\n### `docs/context/production-map.md`\nThe fact is about **infrastructure, services, environments, URLs, endpoints, credentials, or what is safe/unsafe to touch**.\n- Signal words: "production", "staging", "endpoint", "URL", "database", "service", "deployed", "hosted", "credentials", "secret", "environment"\n- Examples: "The staging DB is at postgres://staging.example.com", "We use Vercel for the frontend and Railway for the API"\n\n### `docs/context/dangerous-assumptions.md`\nThe fact is about **something an AI agent might get wrong -- a false assumption that leads to bad outcomes**.\n- Signal words: "assumes", "might think", "but actually", "looks like X but is Y", "not what it seems", "trap", "gotcha"\n- Examples: "The `users` table looks like a test table but it\'s production", "Deleting a workspace doesn\'t delete the billing subscription"\n\n### `docs/context/decision-log.md`\nThe fact is about **an architectural or tooling choice and why it was made**.\n- Signal words: "decided", "chose", "because", "instead of", "we went with", "the reason we use", "trade-off"\n- Examples: "We chose SQLite over Postgres because this runs on embedded devices", "We use pnpm instead of npm for workspace support"\n\n### `docs/context/institutional-knowledge.md`\nThe fact is about **team conventions, unwritten rules, organizational context, or who owns what**.\n- Signal words: "convention", "rule", "always", "never", "team", "process", "review", "approval", "owns", "responsible"\n- Examples: "The design team reviews all color changes", "We never deploy on Fridays", "PR titles must start with the ticket number"\n\n### `docs/context/troubleshooting.md`\nThe fact is about **diagnostic knowledge -- when X happens, do Y (or don\'t do Z)**.\n- Signal words: "when", "fails", "error", "if you see", "stuck", "broken", "fix", "workaround", "before trying", "reboot", "restart", "reset"\n- Examples: "If Wi-Fi disconnects during flash, wait and retry -- don\'t switch networks", "When tests fail with ECONNREFUSED, check if Docker is running"\n\n### Ambiguous Facts\n\nIf the fact fits multiple categories, pick the **best fit** based on the primary intent. You will mention the alternative in your confirmation message so the user can correct you.\n\n## Step 3: Ensure the Target Document Exists\n\n1. If `docs/context/` does not exist, create the directory.\n2. If the target document does not exist, create it from the template structure. Check `docs/templates/` for the matching template. If no template exists, use this minimal structure:\n\nFor **production-map.md**:\n```markdown\n# Production Map\n\n> What\'s real, what\'s staging, what\'s safe to touch.\n\n## Services\n\n| Service | Environment | URL/Endpoint | Impact if Corrupted |\n|---------|-------------|-------------|-------------------|\n```\n\nFor **dangerous-assumptions.md**:\n```markdown\n# Dangerous Assumptions\n\n> Things the AI agent might assume that are wrong in this project.\n\n## Assumptions\n\n| Agent Might Assume | But Actually | Impact If Wrong |\n|-------------------|-------------|----------------|\n```\n\nFor **decision-log.md**:\n```markdown\n# Decision Log\n\n> Why choices were made, not just what was chosen.\n\n## Decisions\n\n| Date | Decision | Why | Alternatives Rejected | Revisit When |\n|------|----------|-----|----------------------|-------------|\n```\n\nFor **institutional-knowledge.md**:\n```markdown\n# Institutional Knowledge\n\n> Unwritten rules, team conventions, and organizational context.\n\n## Team Conventions\n\n- (none yet)\n```\n\nFor **troubleshooting.md**:\n```markdown\n# Troubleshooting\n\n> What to do when things go wrong for non-code reasons.\n\n## Common Failures\n\n| When This Happens | Do This | Don\'t Do This |\n|-------------------|---------|---------------|\n```\n\n## Step 4: Read the Target Document\n\nRead the target document to understand its current structure. Note:\n- Which section to append to\n- Whether it uses tables or lists\n- The column format if it\'s a table\n\n## Step 5: Append the Fact\n\nAdd the fact to the appropriate section of the target document. Match the existing format exactly:\n\n- **Table-based documents** (production-map, dangerous-assumptions, decision-log, troubleshooting): Add a new table row in the correct columns. Use today\'s date where a date column exists.\n- **List-based documents** (institutional-knowledge): Add a new list item (`- `) to the most appropriate section.\n\nRemove any italic example rows (rows where all cells start with `_`) before appending, so the document transitions from template to real content. Only remove examples from the specific table you are appending to.\n\n**Append only. Never modify or remove existing real content.**\n\n## Step 6: Evaluate Boundary Rule\n\nDecide whether the fact also warrants a rule in the project\'s boundary configuration (CLAUDE.md and/or AGENTS.md -- check which files the project uses and update accordingly):\n\n**Add a boundary rule if the fact:**\n- Describes something that should ALWAYS or NEVER be done\n- Could cause real damage if violated (data loss, broken deployments, security issues)\n- Is a hard constraint that applies across all work, not just a one-time note\n\n**Do NOT add a boundary rule if the fact is:**\n- Purely informational (e.g., "staging DB is at this URL")\n- A one-time decision that\'s already captured\n- A diagnostic tip rather than a prohibition\n\nIf a rule is warranted, read the project\'s boundary file(s) -- CLAUDE.md and/or AGENTS.md -- find the appropriate section (ALWAYS, ASK FIRST, or NEVER under Behavioral Boundaries), and append the rule. If no Behavioral Boundaries section exists, append one. Update whichever boundary files the project uses (some projects have CLAUDE.md, some have AGENTS.md, some have both).\n\n## Step 7: Confirm\n\nReport what you did in this format:\n\n```\nAdded to [document name]:\n  [summary of what was added]\n\n[If boundary file(s) were also updated:]\nAdded boundary rule to [CLAUDE.md / AGENTS.md / both]:\n  [ALWAYS/ASK FIRST/NEVER]: [rule text]\n\n[If the fact was ambiguous:]\nRouted to [chosen doc] -- move to [alternative doc] if this is more about [alternative category description].\n```\n',
-  "joycraft-bugfix.md": "---\nname: joycraft-bugfix\ndescription: Structured bug fix workflow \u2014 triage, diagnose, discuss with user, write a focused spec, hand off for implementation\n---\n\n# Bug Fix Workflow\n\nYou are fixing a bug. Follow this process in order. Do not skip steps.\n\n**Guard clause:** If this is clearly a new feature, redirect to `/skill:joycraft-new-feature` and stop.\n\n---\n\n## Phase 1: Triage\n\nEstablish what's broken. Gather: symptom, steps to reproduce, expected vs actual behavior, when it started, relevant logs/errors. If an error message or stack trace is provided, read the referenced files immediately. Try to reproduce if steps are given.\n\n**Done when:** You can describe the symptom in one sentence.\n\n---\n\n## Phase 2: Diagnose\n\nFind the root cause. Start from the error site and trace backward. Search the codebase and read files \u2014 don't guess. Identify the specific line(s) and logic error. Check git blame if it's a recent regression.\n\n**Done when:** You can explain what's wrong, why, and where in 2-3 sentences.\n\n---\n\n## Phase 3: Discuss\n\nPresent findings to the user BEFORE writing any code or spec:\n1. **Symptom** \u2014 confirm it matches what they see\n2. **Root cause** \u2014 specific file(s) and line(s)\n3. **Proposed fix** \u2014 what changes, where\n4. **Risk** \u2014 side effects? scope?\n\nAsk: \"Does this match? Comfortable with this approach?\" If large/risky, suggest decomposing into multiple specs.\n\n**Done when:** User agrees with the diagnosis and fix direction.\n\n---\n\n## Phase 4: Spec the Fix\n\nWrite a bug fix spec to `docs/bugfixes/<area>/bugfix-name.md`. Use the relevant area as the subdirectory (e.g., `auth`, `cli`, `parser`). Lazy-create the `docs/bugfixes/<area>/` directory if it doesn't exist.\n\n(Bugfixes live under `docs/bugfixes/<area>/`, separate from `docs/features/<slug>/specs/`. Bugfixes are area-level, not feature-tied \u2014 multiple unrelated bugs accumulate in the same area folder over time, which is a fundamentally different folder shape from features.)\n\n**Area README:** When creating (or adding to) a `docs/bugfixes/<area>/` folder, also lazy-create/update a `docs/bugfixes/<area>/README.md` index \u2014 a one-line-per-bug table (`| Bug | Spec | Status | Date |`) so areas that accumulate many bugs stay navigable. Append a row for the new bugfix.\n\n**Why:** Even bug fixes deserve a spec. It forces clarity on what \"fixed\" means, ensures test-first discipline, and creates a traceable record of the fix.\n\nThe spec file MUST start with YAML frontmatter \u2014 the 4-field personal schema (the `area:` field carries the area name, used informally to indicate \"what folder this lives under\"):\n\n```yaml\n---\nstatus: active\nowner: <resolved name>\ncreated: YYYY-MM-DD\narea: <area>\n---\n```\n\n**Owner resolution:** look up the owner name in this order \u2014 (1) `git config user.name`, (2) value in your auto-memory `joycraft-owner.txt` if present, (3) ask the user once and persist.\n\nUse this structure:\n\n```markdown\n# [Bug Name] \u2014 Bug Fix Spec\n\n> **Status:** Ready\n> **Date:** YYYY-MM-DD\n> **Estimated scope:** [1 session / N files / ~N lines]\n\n---\n\n## Bug\nOne sentence \u2014 what's broken?\n\n## Root Cause\nWhat's actually wrong, in which file(s) and line(s)?\n\n## Fix\nWhat changes, where?\n\n## Acceptance Criteria\n- [ ] [Observable behavior that proves the fix works]\n- [ ] No regressions \u2014 existing tests still pass\n- [ ] Build passes\n\n## Test Plan\n1. Write a reproduction test that fails before the fix\n2. Apply the fix\n3. Reproduction test passes\n4. Full test suite passes\n\n## Constraints\n- MUST: [hard requirement]\n- MUST NOT: [hard prohibition]\n\n## Affected Files\n| Action | File | What Changes |\n|--------|------|-------------|\n\n## Edge Cases\n| Scenario | Expected Behavior |\n|----------|------------------|\n```\n\n**For large bugs that span multiple files/systems:** Consider whether this should be decomposed into multiple specs. If so, create a brief first using `/skill:joycraft-new-feature`, then decompose.\n\n---\n\n## Phase 5: Hand Off\n\n```\nBug fix spec is ready: docs/bugfixes/<area>/bugfix-name.md\n\nSummary:\n- Bug: [one sentence]\n- Root cause: [one sentence]\n- Fix: [one sentence]\n- Estimated: 1 session\n\nTo execute: Start a fresh session and:\n1. Read the spec\n2. Write the reproduction test (must fail)\n3. Apply the fix (test must pass)\n4. Run full test suite\n5. Run /skill:joycraft-session-end to capture discoveries\n6. Commit and PR\n\nReady to start?\n\nRun /new before your next step \u2014 your artifacts are saved to files.\n```\n",
-  "joycraft-collaborative-setup.md": '---\nname: joycraft-collaborative-setup\ndescription: Set up Joycraft for a team \u2014 scaffold per-area folders, owner conventions, and a team-facing CONTRIBUTING doc. Run once when adopting Joycraft on a multi-dev project.\n---\n\n# Collaborative Setup\n\nYou are setting up Joycraft for a team. Solo defaults stay solo; this skill adds the team-only ceremony \u2014 `docs/areas/` folders, area README/boundaries, and a thin team-facing CONTRIBUTING-joycraft doc.\n\nThis skill is **interactive** \u2014 ask the user, don\'t auto-detect.\n\n## When to run\n\nRun once when a team is adopting Joycraft on a multi-dev project. Solo users do **not** need this skill \u2014 solo defaults are fine without it.\n\n## Step 1: Confirm Team Context\n\nAsk the user:\n\n> "Setting up Joycraft for a team? (vs. solo work) If you\'re unsure, you can skip \u2014 solo defaults work fine and you can run this later."\n\nIf the user says "actually solo," bail before any writes:\n\n> "No problem. The solo workflow needs no extra setup. Run `/skill:joycraft-new-feature` when you want to start a feature."\n\n## Step 2: Check for Flat Layout \u2014 Bail if Present\n\nBefore scaffolding team structure, check the project\'s docs/ for per-feature artifacts. Look for any of:\n\n- `docs/features/<slug>/brief.md`\n- `docs/features/<slug>/research.md`\n- `docs/features/<slug>/design.md`\n- Loose spec subdirectories that predate the per-feature layout (specs not under `docs/features/<slug>/specs/` or `docs/bugfixes/<area>/`)\n\nIf any **flat layout** artifacts exist, tell the user:\n\n> "I see flat-layout artifacts in your docs/ (briefs/research/designs). Run `npx joycraft upgrade` first \u2014 it will migrate them into `docs/features/<slug>/` automatically. Then re-run this skill."\n\nThen stop. Skills don\'t reliably shell out, so the CLI does the migration.\n\n## Step 3: Gather Areas + Owners (Interactive)\n\nAsk the user:\n\n> "How many areas does your team work in? (e.g., `auth`, `api`, `frontend`, `infra`) \u2014 pick names that match how your team thinks about ownership. You can also skip and just create the team CONTRIBUTING doc."\n\nFor each area name the user provides:\n1. Confirm the name (kebab-case).\n2. Ask: "Who owns this area? (a name, an email, or a team handle \u2014 used in the area README\'s frontmatter)"\n3. Ask (optional): "Are there NEVER or ASK FIRST rules specific to this area? If yes, list them; if no, skip."\n\nIf the user provides duplicate names, ask them to pick a different one. Track the area list in your working memory before writing anything.\n\nIf the user provides 0 areas, skip Step 4 and go straight to Step 5 (CONTRIBUTING doc only). Useful path for "we just want the team doc, no areas yet."\n\n## Step 4: Scaffold Each Area\n\nFor each confirmed area, lazy-create `docs/areas/<area-name>/` and write a `README.md` with the **shared frontmatter schema** (areas are shared docs, not personal):\n\n```yaml\n---\nlast_updated: YYYY-MM-DD\nlast_updated_by: <owner from step 3>\n---\n```\n\n**Owner resolution for `last_updated_by`:** look up the owner name in this order \u2014 (1) `git config user.name`, (2) value in your auto-memory `joycraft-owner.txt` if present, (3) ask the user once and persist. Use the user-provided owner from Step 3 if they specified one for this area.\n\nBody of `README.md`:\n\n```markdown\n# <area-name>\n\n> **Owner:** <name from Step 3>\n> **Status:** active\n\n## What this area covers\n\n(Filled in by the area owner)\n\n## Conventions\n\n(Area-specific patterns or constraints)\n\n## Onboarding\n\nWhen a new dev joins this area, they should:\n1. Read this README\n2. Read `boundaries.md` (if present)\n3. Read the codebase under <area-relevant paths>\n```\n\nIf the user provided NEVER / ASK FIRST rules for the area, also write `docs/areas/<area-name>/boundaries.md` with the shared frontmatter and those rules. If they didn\'t, skip the boundaries file \u2014 the root CLAUDE.md boundaries already cover the project-wide cases.\n\n**Idempotency:** if `docs/areas/<area-name>/README.md` already exists, ASK before overwriting (default: skip + inform).\n\n## Step 5: Write the Team CONTRIBUTING Doc\n\nLazy-create `docs/CONTRIBUTING-joycraft.md` (NOT the project\'s main `CONTRIBUTING.md` \u2014 keep them separate so neither stomps on the other).\n\nIf `docs/templates/CONTRIBUTING-joycraft-template.md` exists in the project (it should \u2014 bundled by `npx joycraft init`), use it as the starting point. If not, fall back to the inline template below.\n\nThe doc starts with shared frontmatter:\n\n```yaml\n---\nlast_updated: YYYY-MM-DD\nlast_updated_by: <resolved owner>\n---\n```\n\nBody (inline fallback template \u2014 short by design):\n\n```markdown\n# Joycraft on this project\n\nWe use [Joycraft](https://www.npmjs.com/package/joycraft) for AI-assisted development.\n\n## How our team uses it\n\n(Filled in during /skill:joycraft-collaborative-setup \u2014 fill this in with your team\'s specific conventions.)\n\n## Conventions\n\n- Per-feature work goes under `docs/features/<slug>/`\n- Area-level work and ownership: see `docs/areas/`\n- For "what is Joycraft?", see the package README\n\n## Onboarding\n\nWhen a new dev joins:\n1. Run `npx joycraft init` (idempotent on already-set-up projects)\n2. Read `docs/areas/<your-area>/README.md` for context\n```\n\nIf `docs/CONTRIBUTING-joycraft.md` already exists, ASK before overwriting \u2014 offer overwrite / append / skip; default to skip.\n\n## Step 6: Trigger CLAUDE.md Update\n\nNow that `docs/areas/` exists, the next `npx joycraft upgrade` (or any future `npx joycraft init`) will pick it up and add the **Areas pointer** to CLAUDE.md automatically \u2014 that pointer tells Claude "when working on the X area, read docs/areas/X/README.md first."\n\nTell the user:\n\n> "Run `npx joycraft upgrade` to refresh CLAUDE.md with the Areas pointer (or `npx joycraft init` if you haven\'t initialized yet)."\n\nDon\'t try to shell out from inside the skill \u2014 let the user run the CLI deliberately.\n\n## Step 7: Hand Off\n\nSummarize what you wrote (paths to area READMEs, the CONTRIBUTING doc, any boundaries files), then emit the canonical Handoff block.\n\n## Recommended Next Steps\n\nNext:\n```bash\n/skill:joycraft-new-feature\n```\nRun /new first.\n\nInclude the path to `docs/CONTRIBUTING-joycraft.md` and any newly-created area READMEs in the summary above the Handoff block.\n\n## Notes\n\n- This skill does NOT migrate flat-layout artifacts on its own. That\'s `npx joycraft upgrade`\'s job \u2014 Step 2 directs the user to run it first.\n- Area names are user-provided. Don\'t auto-detect from `src/auth/`, `src/api/`, etc. \u2014 many projects have monorepo or non-conventional layouts and auto-detection produces noise.\n- If the user stops mid-way (Ctrl-C, abandons), whatever\'s been written stays. Re-running the skill is the recovery path; it\'s idempotent on existing area folders (asks before overwriting).\n',
-  "joycraft-decompose.md": '---\nname: joycraft-decompose\ndescription: Break a feature brief into atomic specs \u2014 small, testable, independently executable units\n---\n\n# Decompose Feature into Atomic Specs\n\nYou have a Feature Brief (or the user has described a feature). Your job is to decompose it into atomic specs that can be executed independently \u2014 one spec per session.\n\n## Step 1: Verify the Brief Exists\n\nLook for a Feature Brief at `docs/features/<slug>/brief.md`. If the user provided a brief path as an argument, use that. Otherwise, scan `docs/features/*/brief.md`.\n\n**Status filter when scanning neighbor briefs and specs:** read the YAML frontmatter at the top of each file. Treat each as **live** unless its `status:` is `done`, `deprecated`, or `superseded` \u2014 those three are the only states you **skip / ignore**. Every other state is live and must be considered. The status vocabulary is `todo \u2192 in-review \u2192 done` (see `docs/reference/spec-status-lifecycle.md`); both `todo` and `in-review` are live. An `in-review` spec is finished-but-unverified work that still constrains neighboring decomposition, so it stays in scope. Also ignore anything under `docs/archive/` entirely.\n\nIf one doesn\'t exist yet, tell the user:\n\n> No feature brief found. Run `/skill:joycraft-new-feature` first to interview and create one, or describe the feature now and I\'ll work from your description.\n\nIf the user describes the feature inline, work from that description directly. You don\'t need a formal brief to decompose \u2014 but recommend creating one for complex features.\n\n## Step 2: Identify Natural Boundaries\n\n**Why:** Good boundaries make specs independently testable and committable. Bad boundaries create specs that can\'t be verified without other specs also being done.\n\nRead the brief (or description) and identify natural split points:\n\n- **Data layer changes** (schemas, types, migrations) \u2014 always a separate spec\n- **Pure functions / business logic** \u2014 separate from I/O\n- **UI components** \u2014 separate from data fetching\n- **API endpoints / route handlers** \u2014 separate from business logic\n- **Test infrastructure** (mocks, fixtures, helpers) \u2014 can be its own spec if substantial\n- **Configuration / environment** \u2014 separate from code changes\n\nAsk yourself: "Can this piece be committed and tested without the other pieces existing?" If yes, it\'s a good boundary.\n\n## Step 3: Build the Decomposition Table\n\nFor each atomic spec, define:\n\n| # | Spec Name | Description | Dependencies | Size |\n|---|-----------|-------------|--------------|------|\n\n**Rules:**\n- Each spec name is `verb-object` format (e.g., `add-terminal-detection`, `extract-prompt-module`)\n- Each description is ONE sentence \u2014 if you need two, the spec is too big\n- Dependencies reference other spec numbers \u2014 keep the dependency graph shallow\n- More than 2 dependencies on a single spec = it\'s too big, split further\n- Aim for 3-7 specs per feature. Fewer than 3 = probably not decomposed enough. More than 10 = the feature brief is too big\n\n## Step 4: Present and Iterate\n\nShow the decomposition table to the user. Ask:\n1. "Does this breakdown match how you think about this feature?"\n2. "Are there any specs that feel too big or too small?"\n3. "Should any of these run in parallel (separate branches)?"\n\nIterate until the user approves.\n\n## Execution Modes (assign a mode per spec)\n\nEvery spec carries an **execution mode** that controls how implementation wraps up after building it. Assign one to each spec \u2014 recommended by you, **approved by the human** (never silent).\n\n| Mode | Per-spec wrap-up | Context between specs | Best for |\n|------|------------------|-----------------------|----------|\n| `batch` | implement all, wrap once at the end (one `/skill:joycraft-session-end`) | shared (one conversation) | clusters of tiny specs |\n| `checkpoint` | `/skill:joycraft-spec-done` after each (commit + status bump), keep going | shared | medium specs wanting atomic commits without fresh context |\n| `isolated` | `/skill:joycraft-spec-done`, then a **fresh context**, then the next spec \u2014 on Pi this is the single-shot `pi -p` loop (one fresh process per spec) | fresh per spec | heavy specs that would pollute one context |\n\n**Project default.** Read the default mode from the project\'s `CLAUDE.md`: look for a line `**Default execution mode:** <mode>`. If that line is **absent, default to `batch`** (the safest: shared context, wrap once). Do not hard-fail when it\'s missing \u2014 just use `batch` and say so in your recommendation.\n\n**Size \u2192 mode heuristic** (a starting recommendation, not a rule):\n\n| Spec size | Recommended mode |\n|-----------|------------------|\n| XS / S | `batch`-eligible (fold into the batch) |\n| M | `checkpoint` |\n| L / XL | `isolated` |\n\nSize is your estimate from the spec\'s scope (files touched, surface area, risk). The heuristic is only a starting point: a tiny spec inside a risky feature may still warrant `isolated`, and only the human knows that \u2014 which is why the recommendation is **approved, not auto-applied**.\n\n**Surface the recommendation and get approval.** Before writing any spec files, present your per-spec mode recommendation and wait for the human\'s OK. Worked example:\n\n> Your project defaults to `batch` (no `**Default execution mode:**` line in CLAUDE.md, so I\'m using the safe default). Based on size, I recommend: specs 1, 2 \u2192 `batch`; spec 5 \u2192 `checkpoint`; specs 7, 8 \u2192 `isolated` (large/risky). OK, or adjust?\n\nIf the human overrides any recommendation, **honor their choice verbatim** in both the frontmatter and the queue. Record the approved mode in each spec\'s `mode:` frontmatter field (Step 5) and in each queue entry\'s `"mode"` field (Step 5a). A feature may mix modes across its specs \u2014 that\'s expected. This applies even when there\'s no brief and the feature was described inline: still assign a mode to every spec, and the CLAUDE.md default applies the same way.\n\n## Step 5: Generate Atomic Specs\n\nFor each approved row, create `docs/features/<slug>/specs/<spec-name>.md`. The slug is the feature folder name (e.g., `2026-04-06-token-discipline`). If no brief exists and the user described the feature inline, derive a kebab-case slug yourself: `YYYY-MM-DD-<short-name>`. Lazy-create `docs/features/<slug>/specs/` if it doesn\'t exist.\n\n**Why:** Each spec must be self-contained \u2014 a fresh session should be able to execute it without reading the Feature Brief. Copy relevant constraints and context into each spec.\n\nEach spec file MUST start with YAML frontmatter:\n\n```yaml\n---\nstatus: todo\nowner: <resolved name>\ncreated: YYYY-MM-DD\nfeature: <slug>\nmode: <approved mode \u2014 batch | checkpoint | isolated>\n---\n```\n\nNew specs always start at `status: todo` (the canonical first state \u2014 see `docs/reference/spec-status-lifecycle.md`). The `mode:` value is the human-approved execution mode from the Execution Modes step above.\n\nUse this structure for the body:\n\n```markdown\n# [Verb + Object] \u2014 Atomic Spec\n\n> **Parent Brief:** `docs/features/<slug>/brief.md` (or "standalone")\n> **Status:** Ready\n> **Date:** YYYY-MM-DD\n> **Estimated scope:** [1 session / N files / ~N lines]\n\n---\n\n## What\nOne paragraph \u2014 what changes when this spec is done?\n\n## Why\nOne sentence \u2014 what breaks or is missing without this?\n\n## External API Contract\n\n_Include this section ONLY when the spec touches a third-party SDK, package, or service API. Omit it entirely otherwise._\n\n**Package:** `<npm-package-name>`\n\n**Canonical sources:**\n- <link to docs>\n- <link to types>\n\n**Key API facts (validated against vX.Y.Z):**\n- <fact 1>\n- <fact 2>\n\n\n## Acceptance Criteria\n- [ ] [Observable behavior]\n- [ ] Build passes\n- [ ] Tests pass\n\n## Test Plan\n\n| Acceptance Criterion | Test | Type |\n|---------------------|------|------|\n| [Each AC above] | [What to call/assert] | [unit/integration/e2e] |\n\n**Execution order:**\n1. Write all tests above \u2014 they should fail against current/stubbed code\n2. Run tests to confirm they fail (red)\n3. Implement until all tests pass (green)\n\n**Smoke test:** [Identify the fastest test for iteration feedback]\n\n**Before implementing, verify your test harness:**\n1. Run all tests \u2014 they must FAIL (if they pass, you\'re testing the wrong thing)\n2. Each test calls your actual function/endpoint \u2014 not a reimplementation or the underlying library\n3. Identify your smoke test \u2014 it must run in seconds, not minutes, so you get fast feedback on each change\n\n## Constraints\n- MUST: [hard requirement]\n- MUST NOT: [hard prohibition]\n\n## Affected Files\n| Action | File | What Changes |\n|--------|------|-------------|\n\n## Approach\nStrategy, data flow, key decisions. Name one rejected alternative.\n\n## Edge Cases\n| Scenario | Expected Behavior |\n|----------|------------------|\n```\n\nIf `docs/templates/ATOMIC_SPEC_TEMPLATE.md` exists, reference it for the full template with additional guidance.\n\nFill in all sections \u2014 each spec must be self-contained (no "see the brief for context"). Copy relevant constraints from the Feature Brief into each spec. Write acceptance criteria specific to THIS spec, not the whole feature. Every acceptance criterion must have at least one corresponding test in the Test Plan. If the user provided test strategy info from the interview, use it to choose test types and frameworks. Include the test harness verification rules in every Test Plan.\n\n### Step 5a: Write the Spec Queue Manifest\n\nAfter all spec `.md` files are written, create `.joycraft-spec-queue.json` in the specs directory alongside the spec files and README. This manifest is the machine-readable, authoritative spec queue consumed by the Pi pipeline automation.\n\n```json\n{\n  "feature": "<slug>",\n  "specs": [\n    { "id": 1, "file": "<spec-name>.md", "depends_on": [], "status": "todo", "mode": "batch" },\n    { "id": 2, "file": "<spec-name>.md", "depends_on": [1], "status": "todo", "mode": "checkpoint" }\n  ]\n}\n```\n\nMap each row in your decomposition table to a spec entry:\n- `id`: sequential integer starting from 1 (matches the decomposition table\'s # column)\n- `file`: the spec filename relative to the specs directory\n- `depends_on`: array of spec ids this spec depends on (empty array `[]` for no dependencies)\n- `status`: always `"todo"` initially \u2014 the agent advances each spec to `"in-review"` via `/skill:joycraft-spec-done`, and `/skill:joycraft-session-end` graduates it to `"done"` (see `docs/reference/spec-status-lifecycle.md`)\n- `mode`: the human-approved execution mode for this spec (`batch` | `checkpoint` | `isolated`) \u2014 must match the spec file\'s `mode:` frontmatter\n\nValidate: every id referenced in `depends_on` must exist as an `id` in the specs array; the queue `status`/`mode` for each spec must match that spec file\'s frontmatter.\n\n## Step 6: Recommend Execution Strategy\n\nBased on the dependency graph:\n- **Independent specs** \u2014 "These can run in parallel branches"\n- **Sequential specs** \u2014 "Execute these in order: 1 -> 2 -> 4"\n- **Mixed** \u2014 "Start specs 1 and 3 in parallel. After 1 completes, start 2."\n\n**Mark each multi-spec wave\'s parallel-safety**: a wave is parallel-safe only when its specs\' Affected Files tables are disjoint; overlapping files \u2192 NOT parallel-safe, name the overlap. Record the markers in the wave plan.\n\nUpdate the Feature Brief\'s Execution Strategy section with the plan (if a brief exists).\n\n## Step 7: Hand Off\n\nTell the user:\n```\nDecomposition complete:\n- [N] atomic specs created in docs/features/<slug>/specs/\n- [N] can run in parallel, [N] are sequential\n- Estimated total: [N] sessions\n\nTo execute:\n- Whole queue: /skill:joycraft-implement-feature docs/features/<slug>/ \u2014 checks the\n  queue and runs the joycraft-implement-loop driver (fresh pi -p process per spec)\n- One at a time: /skill:joycraft-implement docs/features/<slug>/specs/<first-spec>.md \u2014\n  it wraps up and continues through the queue itself\n\nReady to start execution?\n\nPi \u2014 autonomous (isolated specs): one command runs the whole queue headless \u2014\n  joycraft-implement-loop docs/features/<slug>/specs\nIt loops next-spec \u2192 implement \u2192 spec-done in a fresh `pi -p` process per spec\n(the process boundary IS the context isolation), then runs session-end once. You\ndon\'t hand-choreograph sessions \u2014 the loop advances itself. If the user wants\nthis run for them, invoke that command via the shell rather than implementing\ninline or spawning a subagent (neither gives the verified process-boundary\nisolation). ToS/cost note: the loop is for Pi with a BYO API key or open weights.\nPi \u2014 interactive (step-by-step): run /skill:joycraft-implement docs/features/<slug>/specs,\nthen /new between specs \u2014 your artifacts are saved to files.\nClaude Code / Codex: Run /clear before your next step \u2014 your artifacts are saved to files.\n```\n',
-  "joycraft-design.md": '---\nname: joycraft-design\ndescription: Design discussion before decomposition \u2014 produce a ~200-line design artifact for human review, catching wrong assumptions before they propagate into specs\n---\n\n# Design Discussion\n\nYou are producing a design discussion document for a feature. This sits between research and decomposition \u2014 it captures your understanding so the human can catch wrong assumptions before specs are written.\n\n**Guard clause:** If no brief path is provided and no brief exists at `docs/features/<slug>/brief.md`, say:\n"No feature brief found. Run `/skill:joycraft-new-feature` first to create one, or provide the path to your brief."\nThen stop.\n\n---\n\n## Step 1: Read Inputs\n\nRead the feature brief at the path the user provides. If the user also provides a research document path, read that too.\n\n## Step 2: Explore the Codebase\n\nSpawn concurrent subagent threads to explore the codebase for patterns relevant to the brief. Focus on:\n\n- Files and functions that will be touched or extended\n- Existing patterns this feature should follow\n- Similar features already implemented that serve as models\n- Boundaries and interfaces the feature must integrate with\n\nEach subagent should search the codebase and read files to gather file paths, function signatures, and code snippets.\n\n## Step 3: Write the Design Document\n\nWrite to `docs/features/<slug>/design.md`. Lazy-create `docs/features/<slug>/` if it doesn\'t exist.\n\nThe document has exactly five sections:\n\n### Section 1: Current State\nWhat exists today in the codebase. Include file paths, function signatures, data flows. Be specific.\n\n### Section 2: Desired End State\nWhat the codebase should look like when this feature is complete.\n\n### Section 3: Patterns to Follow\nExisting patterns in the codebase that this feature should match. Include code snippets and `file:line` references.\n\n### Section 4: Resolved Design Decisions\nDecisions made with rationale. Format: Decision, Rationale, Alternative rejected.\n\n### Section 5: Open Questions\nThings where multiple valid approaches exist. Each question MUST present 2-3 concrete options with pros and cons.\n\n### Update the Feature Brief\n\nAfter writing the design document, update the parent brief with a back-reference:\n1. Read `docs/features/<slug>/brief.md`\n2. In the header blockquote (the `>` lines at the top), add or update:\n   `> **Design:** docs/features/<slug>/design.md`\n3. If a `> **Design:**` line already exists, replace it \u2014 do NOT add a duplicate\n4. Write the brief back\n\n## Step 4: Present and STOP\n\nPresent the design document. Say:\n```\nDesign discussion written to docs/features/<slug>/design.md\n\nPlease review. Specifically:\n1. Are the patterns in Section 3 right?\n2. Do you agree with the resolved decisions?\n3. Pick an option for each open question.\n\nReply with your feedback. I will NOT proceed to decomposition until you have reviewed and approved.\n```\n\n**CRITICAL: Do NOT proceed to `/skill:joycraft-decompose` or generate specs.** Wait for human review.\n\n## After Human Review\n\n- Update the design document with corrections\n- Move answered questions to Resolved Design Decisions\n- Present for final confirmation\n- Only after explicit approval: "Design approved. Run `/skill:joycraft-decompose` with this brief to generate atomic specs."\n',
-  "joycraft-gather-context.md": "---\nname: joycraft-gather-context\ndescription: First-run onboarding pass that populates the project context layer -- read what context already exists, then offer a gap-only interview and batch-write the missing fact rows and long-form reference docs\n---\n\n# Gather Context\n\nThis is the first-run **read-then-offer** onboarding pass \u2014 the lowest-intervention way to populate the project's context layer. You read what context already exists, summarize coverage, offer a gap-only interview, and write everything in one reviewable batch at the end.\n\nThis skill is self-contained. It composes the same conventions the single-doc skills use, but everything you need is inlined below \u2014 do not call into or import another skill's logic.\n\n## Step 1: Read What Already Exists First\n\nThe user has invoked the first-run onboarding pass (e.g., `/skill:joycraft-gather-context`). Before asking the user anything, scan the project's existing context. Default scan breadth is **README + `docs/` + the project boundary file only**:\n\n- The README(s) at the repo root and any obvious sub-package READMEs.\n- `docs/**` \u2014 existing design, architecture, or style docs.\n- `docs/context/*` \u2014 the flat operational fact-docs (production-map, dangerous-assumptions, decision-log, institutional-knowledge, troubleshooting) and `docs/context/reference/*` long-form docs.\n- The current boundary-file content \u2014 CLAUDE.md and/or AGENTS.md, whichever the project uses \u2014 including any `## Context Map` section.\n\nThen summarize for the user what context already exists and what's covered.\n\n**Do NOT auto-run a code-inference scan.** Reading the actual source to infer architecture costs significantly more tokens. Offer that deeper/full review ONLY if the user explicitly asks for it, and when you do, note clearly that it costs more tokens. The default pass never reads the codebase to infer context.\n\n## Step 2: Offer a Gap-Only Interview (Don't Force)\n\nFrom the summary, identify genuine gaps: no design-system doc? no production map? no decision log? Offer an **optional** interview that targets only those gaps. The user can decline any or all of it \u2014 offer, never force.\n\n**Per-doc skip guard (not all-or-nothing):** Never re-interview for a doc that already has real content. Skip each doc that's already populated individually, and interview only the empty or missing ones. If everything is already covered, say so and offer nothing.\n\n## Step 3: Route by Shape (Inline Test)\n\nFor each thing the user wants to capture, apply this minimal shape test inline \u2014 do not defer to another skill:\n\n- **\"Could this be one row in a table?\"** \u2192 it's an **operational fact**. Route it to one of the five flat fact-docs under `docs/context/`:\n  - `docs/context/production-map.md` \u2014 infrastructure, services, environments, URLs, credentials, safe/unsafe to touch.\n  - `docs/context/dangerous-assumptions.md` \u2014 false assumptions an agent might make.\n  - `docs/context/decision-log.md` \u2014 an architectural/tooling choice and why.\n  - `docs/context/institutional-knowledge.md` \u2014 team conventions, unwritten rules, ownership.\n  - `docs/context/troubleshooting.md` \u2014 when X happens, do Y.\n  Append it as a table row (or list item for institutional-knowledge), removing any italic example rows in that table first.\n\n- **\"Does explaining it take paragraphs?\"** \u2192 it's **long-form reference**. Scaffold `docs/context/reference/<slug>.md` from the matching template in `docs/templates/context/reference/` (`design-system`, `frontend-methodology`, `backend`, `testing`, or the generic `reference-doc` fallback), lazy-creating `docs/context/reference/` on first write.\n\nIf an item is ambiguous, apply the test literally: one row \u2192 fact bucket; paragraphs \u2192 reference doc.\n\n## Step 4: Batch-Write + One Final Confirm\n\nDo NOT write per-answer. Collect ALL of the user's gap answers across the whole interview first. Then, in ONE batch:\n\n1. Write all the fact rows into their fact-docs.\n2. Scaffold and write all the reference docs into `docs/context/reference/`.\n3. Add or update the `## Context Map` pointer rows in the project boundary file (CLAUDE.md and/or AGENTS.md) \u2014 one row per reference doc, in the form `| docs/context/reference/<slug>.md | <when to read it> |`. Create the `## Context Map` section (header + two-column table) if it doesn't exist; update an existing row in place rather than duplicating it.\n\nPresent the full set of intended changes and get ONE final confirm (\"do it in one go\") before writing. If the user aborts at the final confirm, write nothing \u2014 there are no partial writes in this batch model. The result is one clean, reviewable diff.\n\n## Step 5: Confirm\n\nReport the batch: which fact rows were added, which reference docs were scaffolded, and which Context Map rows were created or updated.\n",
-  "joycraft-implement-feature.md": "---\nname: joycraft-implement-feature\ndescription: Run a feature's entire spec queue from one invocation \u2014 delegates to the joycraft-implement-loop driver (fresh pi -p process per spec)\n---\n\n# Implement Feature (Whole-Queue Driver)\n\nOne invocation runs a feature's whole spec queue: `/skill:joycraft-implement-feature docs/features/<slug>/`. On Pi the driver already exists as a script \u2014 `.pi/scripts/joycraft/joycraft-implement-loop` \u2014 and the process boundary it creates (a fresh `pi -p` per spec) is the verified context isolation. **Your job is to point the loop at the right queue and run it, not to reimplement it.**\n\n## Step 1: Load the Queue\n\n1. Resolve the specs directory: if the given path contains a `specs/` subdirectory, use it; otherwise use the path itself. Look for `.joycraft-spec-queue.json` there.\n2. **No queue** \u2192 stop:\n\n   > No spec queue found in [path]. Run `/skill:joycraft-decompose` first \u2014 it writes the queue, the specs, and the wave plan.\n\n3. Read the sibling `README.md` (the wave plan) and report the plan: feature slug, M specs, current statuses, the order the loop will serve them in (`joycraft-next-spec` order: first `todo` whose `depends_on` are all `in-review`/`done`).\n4. If **no `todo` specs remain**, report that and suggest `/skill:joycraft-session-end` if the feature was never finished; do not run the loop.\n\n## Step 2: Run the Loop\n\nInvoke the driver via the shell, pointing at the specs dir:\n\n```\njoycraft-implement-loop docs/features/<slug>/specs\n```\n\nWhat it does (so you can narrate it, not reimplement it): `joycraft-next-spec` \u2192 fresh `pi -p \"/skill:joycraft-implement <spec>\"` \u2192 fresh `pi -p \"/skill:joycraft-spec-done <spec>\"` \u2192 repeat; **fail-fast** (exits non-zero naming the failing spec, queue left intact); runs `joycraft-session-end` exactly once when the queue is exhausted.\n\nNotes:\n- The driver spawns `pi -p` subprocesses; nesting it under an already-running Pi session is sound by design but not yet smoke-tested end-to-end \u2014 if the nested `pi -p` misbehaves, fall back to telling the human to run the command above in a separate terminal.\n- **ToS/cost:** this path is for Pi with a BYO API key or open-weight model \u2014 do not route a subscription OAuth through it.\n\n## Step 3: Report\n\nRelay the loop's outcome:\n\n- **Success** \u2192 which specs ran, and session-end's own report (validation, graduation `in-review \u2192 done`, push/PR per CLAUDE.md autonomy).\n- **Failure** \u2192 which spec failed (the loop names it), what reached `in-review`, what remains `todo`. Suggest fixing in a fresh session (`/skill:joycraft-implement <failed-spec>`), then re-running the loop for the remainder \u2014 it picks up where it stopped.\n",
-  "joycraft-implement-level5.md": "---\nname: joycraft-implement-level5\ndescription: Set up Level 5 autonomous development \u2014 autofix loop, holdout scenario testing, and scenario evolution from specs\n---\n\n# Implement Level 5 \u2014 Autonomous Development Loop\n\nYou are guiding the user through setting up Level 5: the autonomous feedback loop where specs go in, validated software comes out. This is a one-time setup that installs workflows, creates a scenarios repo, and configures the autofix loop.\n\n## Before You Begin\n\nCheck prerequisites:\n\n1. **Project must be initialized.** Search for `.claude/.joycraft/state.json` (older installs may still have a legacy `.joycraft-version` at the repo root). If neither exists, tell the user to run `npx joycraft init` first.\n2. **Project should be at Level 4.** Read `docs/joycraft-assessment.md` if it exists. If the project hasn't been assessed yet, suggest running `/skill:joycraft-tune` first. But don't block -- the user may know they're ready.\n3. **Git repo with GitHub remote.** This setup requires GitHub Actions. Check for `.git/` and a GitHub remote.\n\nIf prerequisites aren't met, explain what's needed and stop.\n\n## Step 1: Explain What Level 5 Means\n\nTell the user:\n\n> Level 5 is the autonomous loop. When you push specs, three things happen automatically:\n>\n> 1. **Scenario evolution** -- An AI agent reads your specs and writes holdout tests in a private scenarios repo. These tests are invisible to your coding agent.\n> 2. **Autofix** -- When CI fails on a PR, the agent automatically attempts a fix (up to 3 times).\n> 3. **Holdout validation** -- When CI passes, your scenarios repo runs behavioral tests against the PR. Results post as PR comments.\n>\n> The key insight: your coding agent never sees the scenario tests. This prevents it from gaming the test suite -- like a validation set in machine learning.\n\n## Step 2: Gather Configuration\n\nAsk these questions **one at a time**:\n\n### Question 1: Scenarios repo name\n\n> What should we call your scenarios repo? It'll be a private repo that holds your holdout tests.\n>\n> Default: `{current-repo-name}-scenarios`\n\nAccept the default or the user's choice.\n\n### Question 2: GitHub App\n\n> Level 5 needs a GitHub App to provide a separate identity for autofix pushes (this avoids GitHub's anti-recursion protection). Creating one takes about 2 minutes:\n>\n> 1. Go to https://github.com/settings/apps/new\n> 2. Give it a name (e.g., \"My Project Autofix\")\n> 3. Uncheck \"Webhook > Active\" (not needed)\n> 4. Under **Repository permissions**, set:\n>    - **Contents**: Read & Write\n>    - **Pull requests**: Read & Write\n>    - **Actions**: Read & Write\n> 5. Click **Create GitHub App**\n> 6. Note the **App ID** from the settings page\n> 7. Scroll to **Private keys** > click **Generate a private key** > save the `.pem` file\n> 8. Click **Install App** in the left sidebar > install it on your repo\n>\n> What's your App ID?\n\n## Step 3: Run init-autofix\n\nRun the CLI command with the gathered configuration:\n\n```bash\nnpx joycraft init-autofix --scenarios-repo {name} --app-id {id}\n```\n\nReview the output with the user. Confirm files were created.\n\n## Step 4: Walk Through Secret Configuration\n\nGuide the user step by step:\n\n### 4a: Add Secrets to Main Repo\n\n> You should already have the `.pem` file from when you created the app in Step 2.\n\n> Go to your repo's Settings > Secrets and variables > Actions, and add:\n> - `JOYCRAFT_APP_PRIVATE_KEY` -- paste the contents of your `.pem` file\n> - `ANTHROPIC_API_KEY` -- your Anthropic API key (or the appropriate AI provider key for your setup)\n\n### 4b: Create the Scenarios Repo\n\n> Create the private scenarios repo:\n> ```bash\n> gh repo create {scenarios-repo-name} --private\n> ```\n>\n> Then copy the scenario templates into it:\n> ```bash\n> cp -r docs/templates/scenarios/* ../{scenarios-repo-name}/\n> cd ../{scenarios-repo-name}\n> git add -A && git commit -m \"init: scaffold scenarios repo from Joycraft\"\n> git push\n> ```\n\n### 4c: Add Secrets to Scenarios Repo\n\n> The scenarios repo also needs the App private key:\n> - `JOYCRAFT_APP_PRIVATE_KEY` -- same `.pem` file as the main repo\n> - `ANTHROPIC_API_KEY` -- same key (needed for scenario generation)\n\n## Step 5: Verify Setup\n\nHelp the user verify everything is wired correctly:\n\n1. **Check workflow files exist:** `ls .github/workflows/autofix.yml .github/workflows/scenarios-dispatch.yml .github/workflows/spec-dispatch.yml .github/workflows/scenarios-rerun.yml`\n2. **Check scenario templates were copied:** Verify the scenarios repo has `example-scenario.test.ts`, `workflows/run.yml`, `workflows/generate.yml`, `prompts/scenario-agent.md`\n3. **Check the App ID is correct** in the workflow files (not still a placeholder)\n\n## Step 6: Update AGENTS.md\n\nIf the project's AGENTS.md doesn't already have an \"External Validation\" section, add one:\n\n> ## External Validation\n>\n> This project uses holdout scenario tests in a separate private repo.\n>\n> ### NEVER\n> - Access, read, or reference the scenarios repo\n> - Mention scenario test names or contents\n> - Modify the scenarios dispatch workflow to leak test information\n>\n> The scenarios repo is deliberately invisible to you. This is the holdout guarantee.\n\n## Step 7: First Test (Optional)\n\nIf the user wants to test the loop:\n\n> Want to do a quick test? Here's how:\n>\n> 1. Write a simple spec in `docs/features/<slug>/specs/` and push to main -- this triggers scenario generation\n> 2. Create a PR with a small change -- when CI passes, scenarios will run\n> 3. Watch for the scenario test results as a PR comment\n>\n> Or deliberately break something in a PR to test the autofix loop.\n\n## Step 8: Summary\n\nPrint a summary of what was set up:\n\n> **Level 5 is live.** Here's what's running:\n>\n> | Trigger | What Happens |\n> |---------|-------------|\n> | Push specs to `docs/features/<slug>/specs/` | Scenario agent writes holdout tests |\n> | PR fails CI | Autofix agent attempts a fix (up to 3x) |\n> | PR passes CI | Holdout scenarios run against PR |\n> | Scenarios update | Open PRs re-tested with latest scenarios |\n>\n> Your scenarios repo: `{name}`\n> Your coding agent cannot see those tests. The holdout wall is intact.\n\n**Important:** Tell the user:\n\n> **Before you can test the loop**, you need to merge this PR to main first. GitHub's `workflow_run` triggers only activate for workflows that exist on the default branch. Once merged, create a new PR with any small change -- that's when you'll see Autofix, Scenarios Dispatch, and Spec Dispatch fire for the first time.\n\nUpdate `docs/joycraft-assessment.md` if it exists -- set the Level 5 score to reflect the new setup.\n",
-  "joycraft-implement.md": "---\nname: joycraft-implement\ndescription: Execute atomic specs with TDD \u2014 read spec, write failing tests, implement until green, hand off to session-end\n---\n\n# Implement Atomic Spec\n\nYou have exactly one atomic spec file to execute. Your job is to implement it using strict TDD \u2014 tests first, confirm they fail, then implement until green.\n\n## Step 1: Parse Arguments\n\nThe user MUST provide a path. No path = stop immediately.\n\n**If no path was provided:**\n\n> No spec path provided. Provide a spec file or a feature directory:\n> `/skill:joycraft-implement docs/features/<slug>/specs/spec-name.md`\n> or `/skill:joycraft-implement docs/features/<slug>/`\n\n**If the path is a directory** (ends with `/` or does not end with `.md`):\n\nLook for `specs/.joycraft-spec-queue.json` inside that directory. Read it. Find the **first `todo` spec whose dependencies are satisfied** (a dependency is satisfied once it is `in-review` or `done`; see `docs/reference/spec-status-lifecycle.md`). This matches what `joycraft-next-spec` serves. That single spec file is your target. Do NOT read any other specs.\n\n> Using spec queue: found [spec-file-name] as the next active spec.\n\nIf the directory has no queue or no active specs:\n\n> No active specs found in [directory].\n\n**If the path is a file** ending in `.md`:\n\nUse it directly as the spec to implement.\n\n## Step 2: Read and Understand the Spec\n\n1. **Read the spec file.** The spec is your execution contract \u2014 the Acceptance Criteria and Test Plan define \"done.\"\n2. **Check the spec's Status field.** If it says \"Complete,\" warn the user and ask if they want to re-implement or skip.\n3. **Read the Acceptance Criteria** \u2014 these are your success conditions.\n4. **Read the Test Plan** \u2014 this tells you exactly what tests to write and in what order.\n5. **Read the Constraints** \u2014 these are hard boundaries you must not violate.\n\n### Finding Additional Context\n\nSpecs are designed to be self-contained, but if you need more context:\n\n- **Parent brief:** Linked in the spec's frontmatter (`> **Parent Brief:**` line). Read it for broader feature context.\n- **Related specs:** Live in the same directory. The spec directory convention is `docs/features/<slug>/specs/` where the slug is the feature folder name (e.g., `2026-04-06-token-discipline`). Bugfix specs live under `docs/bugfixes/<area>/`.\n- **Affected Files:** The spec's Affected Files table tells you which files to create or modify.\n\n\n### Before writing code against an external API:\n\n\u26A0\uFE0F If the spec references a third-party SDK or package, read its official documentation and type definitions FIRST. Never write a `declare module` stub for a package that actually exists \u2014 use the real package as a devDependency instead. The stub will make typecheck pass but the code will fail at runtime.\n\n## Step 3: Execute the TDD Cycle\n\n**This is not optional. Write tests FIRST.**\n\n### 3a. Write Tests (Red Phase)\n\nUsing the spec's Test Plan:\n\n1. Write ALL tests listed in the Test Plan. Each Acceptance Criterion must have at least one test.\n2. Tests should call the actual function/endpoint \u2014 not a reimplementation or mock of the underlying library.\n3. Run the tests. **They MUST fail.** If any test passes immediately:\n   - Flag it \u2014 either the test isn't testing the right thing, or the code already exists.\n   - Investigate before proceeding. A test that passes before implementation is a test that proves nothing.\n\n### 3b. Implement (Green Phase)\n\n1. Follow the spec's Approach section for implementation strategy.\n2. Implement the minimum code needed to make tests pass.\n3. Run tests after each meaningful change \u2014 use the spec's Smoke Test for fast feedback.\n4. Continue until ALL tests pass.\n\n### 3c. Verify Acceptance Criteria\n\nWalk through every Acceptance Criterion in the spec:\n\n- [ ] Is each one met?\n- [ ] Does the build pass?\n- [ ] Do all tests pass?\n\nIf any criterion is not met, keep implementing. Do not move on until all criteria are green.\n\n## Step 4: Handle Edge Cases\n\nCheck the spec's Edge Cases table. For each scenario:\n\n- Verify the expected behavior is handled.\n- If the spec says \"warn the user\" or \"prompt,\" make sure that path works.\n\n## Step 5: Wrap Up and Continue (mode-aware \u2014 do the wrap-up yourself)\n\n**Loop-iteration check FIRST.** If this process is one iteration of the `joycraft-implement-loop` driver (you were launched by `pi -p` with a single spec path), STOP after the implementation report \u2014 do **not** wrap up and do **not** continue. The loop runs `/skill:joycraft-spec-done` as its own fresh `pi -p` step and advances the queue itself; wrapping up here would double-run it.\n\nOtherwise (interactive session), wrap up and advance according to the spec's **execution mode**. Read the `mode:` field from the spec's frontmatter (written by `/skill:joycraft-decompose`). If the spec has **no `mode:` field**, default to **`batch`** (back-compat with pre-mode specs). If the value is unrecognized, treat it as `batch` and note the unrecognized value.\n\n**You perform the wrap-up. You find the next spec. Do not stop to tell the human to run `/skill:joycraft-spec-done` or to paste the next file path \u2014 those hand-backs carry zero information and break the feature's momentum.**\n\n### 5a. Per-spec wrap-up\n\n| Spec `mode:` | Wrap-up you perform now |\n|--------------|------------------------|\n| **batch** | **Status bump only**: set the spec to `in-review` in both systems (see below). No commit, no discovery stub \u2014 batch wraps once at feature end. (The bump is required: the queue treats a dependency as satisfied at `in-review`, so without it dependent specs would look blocked.) |\n| **checkpoint** / **isolated** | The full `joycraft-spec-done` wrap-up, performed by you (canonical definition: `.pi/skills/joycraft-spec-done/SKILL.md`): **(1)** bump status to `in-review` in both systems, **(2)** terse 2-line discovery stub at `docs/discoveries/YYYY-MM-DD-topic.md` ONLY if something contradicted the spec \u2014 usually skip, **(3)** commit `spec: <spec-name>` (implementation + status edits + stub, nothing unrelated), **(4)** no validation re-run, no push, no PR \u2014 those belong to `joycraft-session-end`. |\n\n**Both systems** means: the queue JSON (`joycraft-mark-done <spec-id> --to in-review <specs-dir>`) AND the spec file's `status:` frontmatter. Never `done` \u2014 the agent doesn't self-certify (`docs/reference/spec-status-lifecycle.md`).\n\n### 5b. Continue the queue (batch and checkpoint)\n\nRe-read `.joycraft-spec-queue.json` in the spec's directory (or run `joycraft-next-spec <specs-dir>`) and find the next `todo` spec whose dependencies are all `in-review`/`done`. Then:\n\n- **Next ready spec exists** \u2192 announce one line \u2014 `Continuing: <next-spec> (spec N of M)` \u2014 and go back to Step 2 with it, in this same conversation.\n- **Remaining `todo` specs are all blocked** \u2192 stop and report which specs are blocked and on what.\n- **No `todo` specs remain** \u2192 this was the feature's last spec; go to 5d.\n- **No queue** (you were invoked with a bare spec file outside a queue) \u2192 report the spec complete and stop; there is nothing to continue from.\n\n### 5c. isolated \u2014 fresh context per spec\n\nA conversation cannot clear its own context. On Pi the autonomous path is the loop driver \u2014 after this spec's wrap-up, **invoke it via the shell**, pointing at the feature's specs dir:\n\n```\njoycraft-implement-loop docs/features/<slug>/specs\n```\n\nThat one command runs the remaining queue headless (fresh `pi -p` process per spec \u2014 the process boundary IS the context isolation) and finishes with session-end. Do **not** implement isolated specs inline in this conversation and do **not** spawn a subagent \u2014 neither gives the verified process-boundary isolation. (Note: the driver spawns `pi -p` subprocesses; nesting it under an already-running Pi session is sound by design but not yet smoke-tested end-to-end \u2014 if the nested `pi -p` misbehaves, fall back to telling the human to run the command in a separate terminal.) ToS/cost note: this path is for Pi with a BYO API key or open weights \u2014 do not route a subscription OAuth through it.\n\nFor step-by-step control instead, tell the human to run `/new`, then re-invoke `/skill:joycraft-implement <next-spec>` \u2014 the guided-manual path.\n\n### 5d. Feature's last spec (any mode)\n\nRun the once-per-feature finisher yourself: read and follow `.pi/skills/joycraft-session-end/SKILL.md`. It carries its own gates \u2014 validation is mandatory and must pass before specs graduate `in-review \u2192 done`, and push/PR honor the project's CLAUDE.md git autonomy rules \u2014 so running it automatically is safe. (When the loop driver ran the queue, it already runs session-end once \u2014 the loop-iteration check above keeps you from doubling it.)\n\n### Report\n\nAfter each spec's wrap-up, report tersely before continuing:\n\n```\nSpec complete: [spec name] \xB7 mode: [mode] \xB7 tests: [N] passing \xB7 [wrapped up + committed | status bumped (batch)]\n[Continuing: <next-spec> (spec N of M) | Feature complete \u2014 running session-end | Blocked: <specs + reasons>]\n```\n\n**Tip:** Your artifacts are saved to files \u2014 this conversation context is disposable.\n",
-  "joycraft-interview.md": "---\nname: joycraft-interview\ndescription: Brainstorm freely about what you want to build \u2014 yap, explore ideas, and get a structured summary you can use later\n---\n\n# Interview \u2014 Idea Exploration\n\nYou are helping the user brainstorm and explore what they want to build. This is a lightweight, low-pressure conversation \u2014 not a formal spec process. Let them yap.\n\n## How to Run the Interview\n\n### 1. Open the Floor\n\nStart with something like:\n\"What are you thinking about building? Just talk \u2014 I'll listen and ask questions as we go.\"\n\nLet the user talk freely. Do not interrupt their flow. Do not push toward structure yet.\n\n### 2. Ask Clarifying Questions\n\nAs they talk, weave in questions naturally \u2014 don't fire them all at once:\n\n- **What problem does this solve?** Who feels the pain today?\n- **What does \"done\" look like?** If this worked perfectly, what would a user see?\n- **What are the constraints?** Time, tech, team, budget \u2014 what boxes are we in?\n- **What's NOT in scope?** What's tempting but should be deferred?\n- **What are the edge cases?** What could go wrong? What's the weird input?\n- **What exists already?** Are we building on something or starting fresh?\n\n### 3. Play Back Understanding\n\nAfter the user has gotten their ideas out, reflect back:\n\"So if I'm hearing you right, you want to [summary]. The core problem is [X], and done looks like [Y]. Is that right?\"\n\nLet them correct and refine. Iterate until they say \"yes, that's it.\"\n\n### 4. Write a Draft Brief\n\nCreate a draft file at `docs/features/<slug>/brief.md`. Create the `docs/features/<slug>/` directory if it doesn't exist.\n\nUse this format:\n\n```markdown\n# [Topic] \u2014 Draft Brief\n\n> **Date:** YYYY-MM-DD\n> **Status:** DRAFT\n> **Origin:** /skill:joycraft-interview session\n\n---\n\n## The Idea\n[2-3 paragraphs capturing what the user described \u2014 their words, their framing]\n\n## Problem\n[What pain or gap this addresses]\n\n## What \"Done\" Looks Like\n[The user's description of success \u2014 observable outcomes]\n\n## Constraints\n- [constraint 1]\n- [constraint 2]\n\n## Open Questions\n- [things that came up but weren't resolved]\n- [decisions that need more thought]\n\n## Out of Scope (for now)\n- [things explicitly deferred]\n\n## Raw Notes\n[Any additional context, quotes, or tangents worth preserving]\n```\n\n### 5. Hand Off\n\nAfter writing the draft, tell the user:\n\n```\nDraft brief saved to docs/features/<slug>/brief.md\n\nWhen you're ready to move forward, pick the path that fits the complexity:\n\nCOMPLEX (5+ files, architectural decisions, unfamiliar area):\n  /skill:joycraft-new-feature \u2192 /skill:joycraft-research \u2192 /skill:joycraft-design \u2192 /skill:joycraft-decompose\n\nMEDIUM (clear scope but non-trivial):\n  /skill:joycraft-new-feature \u2192 /skill:joycraft-design \u2192 /skill:joycraft-decompose\n\nSIMPLE (scope is clear, < 5 files, well-understood area):\n  /skill:joycraft-new-feature \u2192 /skill:joycraft-decompose\n\nNot sure yet? Just keep brainstorming \u2014 run /skill:joycraft-interview again anytime.\n\nRun /new before your next step \u2014 your artifacts are saved to files.\n```\n\nIf the idea sounds complex \u2014 touches many files, involves architectural decisions, or the user is working in an unfamiliar area \u2014 nudge them toward research and design. But present it as a recommendation, not a gate.\n\n## Guidelines\n\n- **This is NOT /skill:joycraft-new-feature.** Do not push toward formal briefs, decomposition tables, or atomic specs. The point is exploration.\n- **Let the user lead.** Your job is to listen, clarify, and capture \u2014 not to structure or direct.\n- **Mark everything as DRAFT.** The output is a starting point, not a commitment.\n- **Keep it short.** The draft brief should be 1-2 pages max. Capture the essence, not every detail.\n- **Multiple interviews are fine.** The user might run this several times as their thinking evolves. Each creates a new dated draft.\n",
+  "joycraft-add-context.md": '---\nname: joycraft-add-context\ndescription: Author one long-form reference doc -- a design system, frontend/backend methodology, testing conventions, or any other long-form reference doc -- scaffolding it from a template and wiring a pointer into AGENTS.md\'s Context Map\n---\n\n# Add Context\n\nThe user wants to author ONE long-form reference doc \u2014 a design system, a frontend or backend methodology, testing conventions, or any other long-form reference for this project. Your job is to scaffold that doc from the matching template, fill in what the user has told you, write it immediately, and wire a pointer row into AGENTS.md\'s `## Context Map`.\n\nThis is the single-doc primitive. Write-as-you-go is correct here: you scaffold and write ONE doc per invocation, immediately \u2014 not a batch.\n\nThis skill is self-contained. Everything you need is below; do not call into or import another skill\'s logic.\n\n## Step 1: Determine Topic and Slug\n\nFigure out what reference doc the user wants. If they named it (e.g., `/skill:joycraft-add-context our design system`), use that. Otherwise ask: "What reference doc do you want to author?" \u2014 then wait.\n\nDerive a kebab-case `<slug>` from the topic (e.g., "our design system" \u2192 `design-system`, "payments service backend" \u2192 `payments-backend`).\n\n## Step 2: Pick the Matching Template\n\nChoose the bundled template in `docs/templates/context/reference/` that best fits the topic:\n\n| Topic | Template |\n|-------|----------|\n| Design system, tokens, components, visual language | `design-system.md` |\n| Frontend architecture, state, folder conventions, patterns | `frontend-methodology.md` |\n| Service boundaries, API conventions, data model, errors | `backend.md` |\n| Test pyramid, frameworks, fixtures, CI gates | `testing.md` |\n| Anything else not covered above | `reference-doc.md` (generic fallback) |\n\nIf the topic matches none of the four named templates, use the generic `reference-doc.md`.\n\n## Step 3: Scaffold the Doc to `docs/context/reference/<slug>.md`\n\n1. **Lazy-create `docs/context/reference/`** \u2014 create the directory only now, on first write. Do not create it preemptively in projects that never call this skill.\n2. Read the chosen template from `docs/templates/context/reference/`. If that template file isn\'t present in the project, fall back to a minimal skeleton: an `# H1` title, a `>` purpose blockquote, and one `##` section.\n3. Copy the template to `docs/context/reference/<slug>.md`, set the H1 to the real topic, and fill in whatever the user has already told you. Leave the rest of the template\'s deletable italic examples in place for the author to replace.\n4. **Write the doc immediately** \u2014 this single doc, this invocation. Do not defer or batch.\n\nIf `docs/context/reference/<slug>.md` already exists (the user is re-running for the same slug), update it in place rather than creating a duplicate.\n\n## Step 4: Add or Update the Context Map Pointer Row (Idempotent)\n\nRead AGENTS.md and maintain a pointer row for this doc in the `## Context Map` section. The row format is:\n\n```\n| docs/context/reference/<slug>.md | <when to read it> |\n```\n\nApply this idempotent logic exactly:\n\n1. **If a `## Context Map` section does not exist**, create it (place it after the project intro / Behavioral Boundaries area, before deep architecture). Add the header and a two-column table:\n\n   ```markdown\n   ## Context Map\n\n   | Doc | When to read it |\n   |-----|-----------------|\n   ```\n\n2. **If a row whose first cell is `docs/context/reference/<slug>.md` already exists**, update that row in place (refresh the "when to read it" cell). Do NOT add a second row for the same path.\n\n3. **Otherwise**, append one new row to the Context Map table.\n\nNever duplicate a row. The Context Map is a lightweight pointer index \u2014 one row per reference doc, nothing more.\n\n## Step 5: Confirm\n\nReport what you did:\n\n```\nScaffolded docs/context/reference/<slug>.md from the <template> template.\nContext Map row [added | updated]:\n  | docs/context/reference/<slug>.md | <when to read it> |\n\nFill in the doc\'s sections \u2014 the italic examples are placeholders to replace or delete.\n```\n\nThen end with the canonical Handoff block. After authoring a context doc, the next move is usually back to the work at hand; for a first-run onboarding sweep of several docs, point the user at the gather pass.\n\n## Recommended Next Steps\n\nNext:\n```bash\n/skill:joycraft-session-end\n```\nRun /new first.\n',
+  "joycraft-add-fact.md": '---\nname: joycraft-add-fact\ndescription: Capture a project fact and route it to the correct context document -- production map, dangerous assumptions, decision log, institutional knowledge, or troubleshooting\n---\n\n# Add Fact\n\nThe user has a fact to capture. Your job is to classify it, route it to the correct context document, append it in the right format, and optionally add a AGENTS.md boundary rule.\n\n## Step 1: Get the Fact\n\nIf the user already provided the fact (e.g., `/skill:joycraft-add-fact the staging DB resets every Sunday`), use it directly.\n\nIf not, ask: "What fact do you want to capture?" -- then wait for their response.\n\nIf the user provides multiple facts at once, process each one separately through all the steps below, then give a combined confirmation at the end.\n\n## Step 2: Classify the Fact\n\nRoute the fact to one of these 5 context documents based on its content:\n\n### `docs/context/production-map.md`\nThe fact is about **infrastructure, services, environments, URLs, endpoints, credentials, or what is safe/unsafe to touch**.\n- Signal words: "production", "staging", "endpoint", "URL", "database", "service", "deployed", "hosted", "credentials", "secret", "environment"\n- Examples: "The staging DB is at postgres://staging.example.com", "We use Vercel for the frontend and Railway for the API"\n\n### `docs/context/dangerous-assumptions.md`\nThe fact is about **something an AI agent might get wrong -- a false assumption that leads to bad outcomes**.\n- Signal words: "assumes", "might think", "but actually", "looks like X but is Y", "not what it seems", "trap", "gotcha"\n- Examples: "The `users` table looks like a test table but it\'s production", "Deleting a workspace doesn\'t delete the billing subscription"\n\n### `docs/context/decision-log.md`\nThe fact is about **an architectural or tooling choice and why it was made**.\n- Signal words: "decided", "chose", "because", "instead of", "we went with", "the reason we use", "trade-off"\n- Examples: "We chose SQLite over Postgres because this runs on embedded devices", "We use pnpm instead of npm for workspace support"\n\n### `docs/context/institutional-knowledge.md`\nThe fact is about **team conventions, unwritten rules, organizational context, or who owns what**.\n- Signal words: "convention", "rule", "always", "never", "team", "process", "review", "approval", "owns", "responsible"\n- Examples: "The design team reviews all color changes", "We never deploy on Fridays", "PR titles must start with the ticket number"\n\n### `docs/context/troubleshooting.md`\nThe fact is about **diagnostic knowledge -- when X happens, do Y (or don\'t do Z)**.\n- Signal words: "when", "fails", "error", "if you see", "stuck", "broken", "fix", "workaround", "before trying", "reboot", "restart", "reset"\n- Examples: "If Wi-Fi disconnects during flash, wait and retry -- don\'t switch networks", "When tests fail with ECONNREFUSED, check if Docker is running"\n\n### Ambiguous Facts\n\nIf the fact fits multiple categories, pick the **best fit** based on the primary intent. You will mention the alternative in your confirmation message so the user can correct you.\n\n## Step 3: Ensure the Target Document Exists\n\n1. If `docs/context/` does not exist, create the directory.\n2. If the target document does not exist, create it from the template structure. Check `docs/templates/` for the matching template. If no template exists, use this minimal structure:\n\nFor **production-map.md**:\n```markdown\n# Production Map\n\n> What\'s real, what\'s staging, what\'s safe to touch.\n\n## Services\n\n| Service | Environment | URL/Endpoint | Impact if Corrupted |\n|---------|-------------|-------------|-------------------|\n```\n\nFor **dangerous-assumptions.md**:\n```markdown\n# Dangerous Assumptions\n\n> Things the AI agent might assume that are wrong in this project.\n\n## Assumptions\n\n| Agent Might Assume | But Actually | Impact If Wrong |\n|-------------------|-------------|----------------|\n```\n\nFor **decision-log.md**:\n```markdown\n# Decision Log\n\n> Why choices were made, not just what was chosen.\n\n## Decisions\n\n| Date | Decision | Why | Alternatives Rejected | Revisit When |\n|------|----------|-----|----------------------|-------------|\n```\n\nFor **institutional-knowledge.md**:\n```markdown\n# Institutional Knowledge\n\n> Unwritten rules, team conventions, and organizational context.\n\n## Team Conventions\n\n- (none yet)\n```\n\nFor **troubleshooting.md**:\n```markdown\n# Troubleshooting\n\n> What to do when things go wrong for non-code reasons.\n\n## Common Failures\n\n| When This Happens | Do This | Don\'t Do This |\n|-------------------|---------|---------------|\n```\n\n## Step 4: Read the Target Document\n\nRead the target document to understand its current structure. Note:\n- Which section to append to\n- Whether it uses tables or lists\n- The column format if it\'s a table\n\n## Step 5: Append the Fact\n\nAdd the fact to the appropriate section of the target document. Match the existing format exactly:\n\n- **Table-based documents** (production-map, dangerous-assumptions, decision-log, troubleshooting): Add a new table row in the correct columns. Use today\'s date where a date column exists.\n- **List-based documents** (institutional-knowledge): Add a new list item (`- `) to the most appropriate section.\n\nRemove any italic example rows (rows where all cells start with `_`) before appending, so the document transitions from template to real content. Only remove examples from the specific table you are appending to.\n\n**Append only. Never modify or remove existing real content.**\n\n## Step 5b: Update Shared Frontmatter\n\nContext docs are *shared* artifacts (no single owner). After appending, update (or add) YAML frontmatter \u2014 the 2-field shared schema:\n\n```yaml\n---\nlast_updated: YYYY-MM-DD\nlast_updated_by: <resolved name>\n---\n```\n\nIf the file already has a frontmatter block, update the `last_updated` and `last_updated_by` fields in place. If it doesn\'t, prepend a fresh block ABOVE the existing `# Heading`.\n\n**Owner resolution:** look up the owner name in this order \u2014 (1) `git config user.name`, (2) value in your auto-memory `joycraft-owner.txt` if present, (3) ask the user once and persist.\n\n## Step 6: Evaluate AGENTS.md Boundary Rule\n\nDecide whether the fact also warrants a rule in AGENTS.md\'s behavioral boundaries:\n\n**Add a AGENTS.md rule if the fact:**\n- Describes something that should ALWAYS or NEVER be done\n- Could cause real damage if violated (data loss, broken deployments, security issues)\n- Is a hard constraint that applies across all work, not just a one-time note\n\n**Do NOT add a AGENTS.md rule if the fact is:**\n- Purely informational (e.g., "staging DB is at this URL")\n- A one-time decision that\'s already captured\n- A diagnostic tip rather than a prohibition\n\nIf a rule is warranted, read AGENTS.md, find the appropriate section (ALWAYS, ASK FIRST, or NEVER under Behavioral Boundaries), and append the rule. If no Behavioral Boundaries section exists, append one.\n\n## Step 7: Confirm and Hand Off\n\nReport what you did in this format:\n\n```\nAdded to [document name]:\n  [summary of what was added]\n\n[If AGENTS.md was also updated:]\nAdded AGENTS.md rule:\n  [ALWAYS/ASK FIRST/NEVER]: [rule text]\n\n[If the fact was ambiguous:]\nRouted to [chosen doc] -- move to [alternative doc] if this is more about [alternative category description].\n```\n\nEnd with the canonical Handoff block. For most facts, the next move is back to whatever the user was doing \u2014 the Handoff block degrades to just a slash command pointing them home.\n\n## Recommended Next Steps\n\nNext:\n```bash\n/skill:joycraft-session-end\n```\nRun /new first.\n',
+  "joycraft-bugfix.md": "---\nname: joycraft-bugfix\ndescription: Structured bug fix workflow \u2014 triage, diagnose, discuss with user, write a focused spec, hand off for implementation\n---\n\n# Bug Fix Workflow\n\nYou are fixing a bug. Follow this process in order. Do not skip steps.\n\n**Guard clause:** If this is clearly a new feature, redirect to `/skill:joycraft-new-feature` and stop.\n\n---\n\n## Phase 1: Triage\n\nEstablish what's broken. Gather: symptom, steps to reproduce, expected vs actual behavior, when it started, relevant logs/errors. If an error message or stack trace is provided, read the referenced files immediately. Try to reproduce if steps are given.\n\n**Done when:** You can describe the symptom in one sentence.\n\n---\n\n## Phase 2: Diagnose\n\nFind the root cause. Start from the error site and trace backward. Read source files \u2014 don't guess. Identify the specific line(s) and logic error. Check git blame if it's a recent regression.\n\n**Done when:** You can explain what's wrong, why, and where in 2-3 sentences.\n\n---\n\n## Phase 3: Discuss\n\nPresent findings to the user BEFORE writing any code or spec:\n1. **Symptom** \u2014 confirm it matches what they see\n2. **Root cause** \u2014 specific file(s) and line(s)\n3. **Proposed fix** \u2014 what changes, where\n4. **Risk** \u2014 side effects? scope?\n\nAsk: \"Does this match? Comfortable with this approach?\" If large/risky, suggest decomposing into multiple specs.\n\n**Done when:** User agrees with the diagnosis and fix direction.\n\n---\n\n## Phase 4: Spec the Fix\n\nWrite a bug fix spec to `docs/bugfixes/<area>/bugfix-name.md`. Use the relevant area as the subdirectory (e.g., `auth`, `cli`, `parser`). Lazy-create the `docs/bugfixes/<area>/` directory if it doesn't exist.\n\n(Bugfixes live under `docs/bugfixes/<area>/`, separate from `docs/features/<slug>/specs/`. Bugfixes are area-level, not feature-tied \u2014 multiple unrelated bugs accumulate in the same area folder over time, which is a fundamentally different folder shape from features.)\n\n**Area README:** When creating (or adding to) a `docs/bugfixes/<area>/` folder, also lazy-create/update a `docs/bugfixes/<area>/README.md` index \u2014 a one-line-per-bug table (`| Bug | Spec | Status | Date |`) so areas that accumulate many bugs stay navigable. Append a row for the new bugfix.\n\n**Why:** Even bug fixes deserve a spec. It forces clarity on what \"fixed\" means, ensures test-first discipline, and creates a traceable record of the fix.\n\nThe spec file MUST start with YAML frontmatter \u2014 the 4-field personal schema (the `area:` field carries the area name, used informally to indicate \"what folder this lives under\"):\n\n```yaml\n---\nstatus: active\nowner: <resolved name>\ncreated: YYYY-MM-DD\narea: <area>\n---\n```\n\n**Owner resolution:** look up the owner name in this order \u2014 (1) `git config user.name`, (2) value in your auto-memory `joycraft-owner.txt` if present, (3) ask the user once and persist.\n\nUse this template for the body:\n\n```markdown\n# Fix [Bug Description] \u2014 Bug Fix Spec\n\n> **Parent Brief:** none (bug fix)\n> **Issue/Error:** [error message, issue link, or symptom description]\n> **Status:** Ready\n> **Date:** YYYY-MM-DD\n> **Estimated scope:** [1 session / N files / ~N lines]\n\n---\n\n## Bug\n\nWhat is broken? Describe the symptom the user experiences.\n\n## Root Cause\n\nWhat is wrong in the code and why? Name the specific file(s) and line(s).\n\n## Fix\n\nWhat changes will fix this? Be specific \u2014 describe the code change, not just \"fix the bug.\"\n\n## Acceptance Criteria\n\n- [ ] [The bug no longer occurs \u2014 describe the correct behavior]\n- [ ] [No regressions in related functionality]\n- [ ] Build passes\n- [ ] Tests pass\n\n## Test Plan\n\n| Acceptance Criterion | Test | Type |\n|---------------------|------|------|\n| [Bug no longer occurs] | [Test that reproduces the bug, then verifies the fix] | [unit/integration/e2e] |\n| [No regressions] | [Existing tests still pass, or new regression test] | [unit/integration] |\n\n**Execution order:**\n1. Write a test that reproduces the bug \u2014 it should FAIL (red)\n2. Run the test to confirm it fails\n3. Apply the fix\n4. Run the test to confirm it passes (green)\n5. Run the full test suite to check for regressions\n\n**Smoke test:** [The bug reproduction test \u2014 fastest way to verify the fix works]\n\n**Before implementing, verify your test harness:**\n1. Run the reproduction test \u2014 it must FAIL (if it passes, you're not testing the actual bug)\n2. The test must exercise your actual code \u2014 not a reimplementation or mock\n3. Identify your smoke test \u2014 it must run in seconds, not minutes\n\n## Constraints\n\n- MUST: [any hard requirements for the fix]\n- MUST NOT: [any prohibitions \u2014 e.g., don't change the public API]\n\n## Affected Files\n\n| Action | File | What Changes |\n|--------|------|-------------|\n\n## Edge Cases\n\n| Scenario | Expected Behavior |\n|----------|------------------|\n```\n\n**For trivial bugs:** The spec will be short. That's fine \u2014 the structure is the point, not the length.\n\n**For large bugs that span multiple files/systems:** Consider whether this should be decomposed into multiple specs. If so, create a brief first using `/skill:joycraft-new-feature`, then decompose. A bug fix spec should be implementable in a single session.\n\n---\n\n## Phase 5: Hand Off\n\nTell the user a one-line summary, then emit the canonical Handoff block.\n\n## Recommended Next Steps\n\nNext:\n```bash\n/skill:joycraft-implement docs/bugfixes/<area>/bugfix-name.md\n```\nRun /new first.\n\n**Why:** A fresh session for implementation produces better results. This diagnostic session has context noise from exploration \u2014 a clean session with just the spec is more focused.\n",
+  "joycraft-collaborative-setup.md": '---\nname: joycraft-collaborative-setup\ndescription: Set up Joycraft for a team \u2014 scaffold per-area folders, owner conventions, and a team-facing CONTRIBUTING doc. Run once when adopting Joycraft on a multi-dev project.\n---\n\n# Collaborative Setup\n\nYou are setting up Joycraft for a team. Solo defaults stay solo; this skill adds the team-only ceremony \u2014 `docs/areas/` folders, area README/boundaries, and a thin team-facing CONTRIBUTING-joycraft doc.\n\nThis skill is **interactive** \u2014 ask the user, don\'t auto-detect.\n\n## When to run\n\nRun once when a team is adopting Joycraft on a multi-dev project. Solo users do **not** need this skill \u2014 solo defaults are fine without it.\n\n## Step 1: Confirm Team Context\n\nAsk the user:\n\n> "Setting up Joycraft for a team? (vs. solo work) If you\'re unsure, you can skip \u2014 solo defaults work fine and you can run this later."\n\nIf the user says "actually solo," bail before any writes:\n\n> "No problem. The solo workflow needs no extra setup. Run `/skill:joycraft-new-feature` when you want to start a feature."\n\n## Step 2: Check for Flat Layout \u2014 Bail if Present\n\nBefore scaffolding team structure, check the project\'s docs/ for per-feature artifacts. Look for any of:\n\n- `docs/features/<slug>/brief.md`\n- `docs/features/<slug>/research.md`\n- `docs/features/<slug>/design.md`\n- Loose spec subdirectories that predate the per-feature layout (specs not under `docs/features/<slug>/specs/` or `docs/bugfixes/<area>/`)\n\nIf any **flat layout** artifacts exist, tell the user:\n\n> "I see flat-layout artifacts in your docs/ (briefs/research/designs). Run `npx joycraft upgrade` first \u2014 it will migrate them into `docs/features/<slug>/` automatically. Then re-run this skill."\n\nThen stop. Skills don\'t reliably shell out, so the CLI does the migration.\n\n## Step 3: Gather Areas + Owners (Interactive)\n\nAsk the user:\n\n> "How many areas does your team work in? (e.g., `auth`, `api`, `frontend`, `infra`) \u2014 pick names that match how your team thinks about ownership. You can also skip and just create the team CONTRIBUTING doc."\n\nFor each area name the user provides:\n1. Confirm the name (kebab-case).\n2. Ask: "Who owns this area? (a name, an email, or a team handle \u2014 used in the area README\'s frontmatter)"\n3. Ask (optional): "Are there NEVER or ASK FIRST rules specific to this area? If yes, list them; if no, skip."\n\nIf the user provides duplicate names, ask them to pick a different one. Track the area list in your working memory before writing anything.\n\nIf the user provides 0 areas, skip Step 4 and go straight to Step 5 (CONTRIBUTING doc only). Useful path for "we just want the team doc, no areas yet."\n\n## Step 4: Scaffold Each Area\n\nFor each confirmed area, lazy-create `docs/areas/<area-name>/` and write a `README.md` with the **shared frontmatter schema** (areas are shared docs, not personal):\n\n```yaml\n---\nlast_updated: YYYY-MM-DD\nlast_updated_by: <owner from step 3>\n---\n```\n\n**Owner resolution for `last_updated_by`:** look up the owner name in this order \u2014 (1) `git config user.name`, (2) value in your auto-memory `joycraft-owner.txt` if present, (3) ask the user once and persist. Use the user-provided owner from Step 3 if they specified one for this area.\n\nBody of `README.md`:\n\n```markdown\n# <area-name>\n\n> **Owner:** <name from Step 3>\n> **Status:** active\n\n## What this area covers\n\n(Filled in by the area owner)\n\n## Conventions\n\n(Area-specific patterns or constraints)\n\n## Onboarding\n\nWhen a new dev joins this area, they should:\n1. Read this README\n2. Read `boundaries.md` (if present)\n3. Read the codebase under <area-relevant paths>\n```\n\nIf the user provided NEVER / ASK FIRST rules for the area, also write `docs/areas/<area-name>/boundaries.md` with the shared frontmatter and those rules. If they didn\'t, skip the boundaries file \u2014 the root AGENTS.md boundaries already cover the project-wide cases.\n\n**Idempotency:** if `docs/areas/<area-name>/README.md` already exists, ASK before overwriting (default: skip + inform).\n\n## Step 5: Write the Team CONTRIBUTING Doc\n\nLazy-create `docs/CONTRIBUTING-joycraft.md` (NOT the project\'s main `CONTRIBUTING.md` \u2014 keep them separate so neither stomps on the other).\n\nIf `docs/templates/CONTRIBUTING-joycraft-template.md` exists in the project (it should \u2014 bundled by `npx joycraft init`), use it as the starting point. If not, fall back to the inline template below.\n\nThe doc starts with shared frontmatter:\n\n```yaml\n---\nlast_updated: YYYY-MM-DD\nlast_updated_by: <resolved owner>\n---\n```\n\nBody (inline fallback template \u2014 short by design):\n\n```markdown\n# Joycraft on this project\n\nWe use [Joycraft](https://www.npmjs.com/package/joycraft) for AI-assisted development.\n\n## How our team uses it\n\n(Filled in during /skill:joycraft-collaborative-setup \u2014 fill this in with your team\'s specific conventions.)\n\n## Conventions\n\n- Per-feature work goes under `docs/features/<slug>/`\n- Area-level work and ownership: see `docs/areas/`\n- For "what is Joycraft?", see the package README\n\n## Onboarding\n\nWhen a new dev joins:\n1. Run `npx joycraft init` (idempotent on already-set-up projects)\n2. Read `docs/areas/<your-area>/README.md` for context\n```\n\nIf `docs/CONTRIBUTING-joycraft.md` already exists, ASK before overwriting \u2014 offer overwrite / append / skip; default to skip.\n\n## Step 6: Trigger AGENTS.md Update\n\nNow that `docs/areas/` exists, the next `npx joycraft upgrade` (or any future `npx joycraft init`) will pick it up and add the **Areas pointer** to AGENTS.md automatically \u2014 that pointer tells the agent "when working on the X area, read docs/areas/X/README.md first."\n\nTell the user:\n\n> "Run `npx joycraft upgrade` to refresh AGENTS.md with the Areas pointer (or `npx joycraft init` if you haven\'t initialized yet)."\n\nDon\'t try to shell out from inside the skill \u2014 let the user run the CLI deliberately.\n\n## Step 7: Hand Off\n\nSummarize what you wrote (paths to area READMEs, the CONTRIBUTING doc, any boundaries files), then emit the canonical Handoff block.\n\n## Recommended Next Steps\n\nNext:\n```bash\n/skill:joycraft-new-feature\n```\nRun /new first.\n\nInclude the path to `docs/CONTRIBUTING-joycraft.md` and any newly-created area READMEs in the summary above the Handoff block.\n\n## Notes\n\n- This skill does NOT migrate flat-layout artifacts on its own. That\'s `npx joycraft upgrade`\'s job \u2014 Step 2 directs the user to run it first.\n- Area names are user-provided. Don\'t auto-detect from `src/auth/`, `src/api/`, etc. \u2014 many projects have monorepo or non-conventional layouts and auto-detection produces noise.\n- If the user stops mid-way (Ctrl-C, abandons), whatever\'s been written stays. Re-running the skill is the recovery path; it\'s idempotent on existing area folders (asks before overwriting).\n',
+  "joycraft-decompose.md": '---\nname: joycraft-decompose\ndescription: Break a feature brief into atomic specs \u2014 small, testable, independently executable units\n---\n\n# Decompose Feature into Atomic Specs\n\nYou have a Feature Brief (or the user has described a feature). Your job is to decompose it into atomic specs that can be executed independently \u2014 one spec per session.\n\n## Step 1: Verify the Brief Exists\n\nLook for a Feature Brief at `docs/features/<slug>/brief.md`. If the user provided a brief path as an argument, use that. Otherwise, scan `docs/features/*/brief.md`.\n\n**Status filter when scanning neighbor briefs and specs:** read the YAML frontmatter at the top of each file. Treat each as **live** unless its `status:` is `done`, `deprecated`, or `superseded` \u2014 those three are the only states you **skip / ignore**. Every other state is live and must be considered. The status vocabulary is `todo \u2192 in-review \u2192 done` (see `docs/reference/spec-status-lifecycle.md`); both `todo` and `in-review` are live. An `in-review` spec is finished-but-unverified work that still constrains neighboring decomposition, so it stays in scope. Also ignore anything under `docs/archive/` entirely.\n\nIf no brief exists, tell the user:\n\n> No feature brief found. Run `/skill:joycraft-new-feature` first to interview and create one, or describe the feature now and I\'ll work from your description.\n\nIf the user describes the feature inline, work from that description directly. You don\'t need a formal brief to decompose \u2014 but recommend creating one for complex features.\n\n## Step 2: Identify Natural Boundaries\n\n**Why:** Good boundaries make specs independently testable and committable. Bad boundaries create specs that can\'t be verified without other specs also being done.\n\nRead the brief (or description) and identify natural split points:\n\n- **Data layer changes** (schemas, types, migrations) \u2014 always a separate spec\n- **Pure functions / business logic** \u2014 separate from I/O\n- **UI components** \u2014 separate from data fetching\n- **API endpoints / route handlers** \u2014 separate from business logic\n- **Test infrastructure** (mocks, fixtures, helpers) \u2014 can be its own spec if substantial\n- **Configuration / environment** \u2014 separate from code changes\n\nAsk yourself: "Can this piece be committed and tested without the other pieces existing?" If yes, it\'s a good boundary.\n\n## Step 3: Build the Decomposition Table\n\nFor each atomic spec, define:\n\n| # | Spec Name | Description | Dependencies | Size |\n|---|-----------|-------------|--------------|------|\n\n**Rules:**\n- Each spec name is `verb-object` format (e.g., `add-terminal-detection`, `extract-prompt-module`)\n- Each description is ONE sentence \u2014 if you need two, the spec is too big\n- Dependencies reference other spec numbers \u2014 keep the dependency graph shallow\n- More than 2 dependencies on a single spec = it\'s too big, split further\n- Aim for 3-7 specs per feature. Fewer than 3 = probably not decomposed enough. More than 10 = the feature brief is too big\n\n## Step 4: Present and Iterate\n\nShow the decomposition table to the user. Ask:\n1. "Does this breakdown match how you think about this feature?"\n2. "Are there any specs that feel too big or too small?"\n3. "Should any of these run in parallel (separate worktrees)?"\n\nIterate until the user approves.\n\n## Execution Modes (assign a mode per spec)\n\nEvery spec carries an **execution mode** that controls how `joycraft-implement` wraps up after building it. Assign one to each spec \u2014 recommended by you, **approved by the human** (never silent).\n\n| Mode | Per-spec wrap-up | Context between specs | Best for |\n|------|------------------|-----------------------|----------|\n| `batch` | implement all, wrap once at the end (one `joycraft-session-end`) | shared (one conversation) | clusters of tiny specs |\n| `checkpoint` | `joycraft-spec-done` after each (commit + status bump), keep going | shared | medium specs wanting atomic commits without fresh context |\n| `isolated` | `joycraft-spec-done`, then a **fresh context**, then the next spec | fresh per spec | heavy specs that would pollute one context |\n\n**Project default.** Read the default mode from the project\'s `AGENTS.md`: look for a line `**Default execution mode:** <mode>`. If that line is **absent, default to `batch`** (the safest: shared context, wrap once). Do not hard-fail when it\'s missing \u2014 just use `batch` and say so in your recommendation.\n\n**Size \u2192 mode heuristic** (a starting recommendation, not a rule):\n\n| Spec size | Recommended mode |\n|-----------|------------------|\n| XS / S | `batch`-eligible (fold into the batch) |\n| M | `checkpoint` |\n| L / XL | `isolated` |\n\nSize is your estimate from the spec\'s scope (files touched, surface area, risk). The heuristic is only a starting point: a tiny spec inside a risky feature may still warrant `isolated`, and only the human knows that \u2014 which is why the recommendation is **approved, not auto-applied**.\n\n**Surface the recommendation and get approval.** Before writing any spec files, present your per-spec mode recommendation and wait for the human\'s OK. Worked example:\n\n> Your project defaults to `batch` (no `**Default execution mode:**` line in AGENTS.md, so I\'m using the safe default). Based on size, I recommend: specs 1, 2 \u2192 `batch`; spec 5 \u2192 `checkpoint`; specs 7, 8 \u2192 `isolated` (large/risky). OK, or adjust?\n\nIf the human overrides any recommendation, **honor their choice verbatim** in both the frontmatter and the queue. Record the approved mode in each spec\'s `mode:` frontmatter field (Step 5) and in each queue entry\'s `"mode"` field (Step 5a). A feature may mix modes across its specs \u2014 that\'s expected; note the mix in the README/wave plan. This applies even when there\'s no brief and the feature was described inline: still assign a mode to every spec, and the AGENTS.md default applies the same way.\n\n## Step 5: Generate Atomic Specs\n\nFor each approved row, create `docs/features/<slug>/specs/<spec-name>.md`. The slug is the feature folder name (e.g., `2026-04-06-token-discipline`). Lazy-create `docs/features/<slug>/specs/` if it doesn\'t exist.\n\nIf no brief exists and the user described the feature inline, derive a kebab-case slug yourself: `YYYY-MM-DD-<short-name>`. Create the folder structure under `docs/features/<slug>/`.\n\n**Why:** Each spec must be self-contained \u2014 a fresh Claude session should be able to execute it without reading the Feature Brief. Copy relevant constraints and context into each spec.\n\nEach spec file MUST start with YAML frontmatter \u2014 the personal schema:\n\n```yaml\n---\nstatus: todo\nowner: <resolved name>\ncreated: YYYY-MM-DD\nfeature: <slug>\nmode: <approved mode \u2014 batch | checkpoint | isolated>\n---\n```\n\nNew specs always start at `status: todo` (the canonical first state \u2014 see `docs/reference/spec-status-lifecycle.md`). The `mode:` value is the human-approved execution mode from the Execution Modes step above.\n\n**Owner resolution:** look up the owner name in this order \u2014 (1) `git config user.name`, (2) value in your auto-memory `joycraft-owner.txt` if present, (3) ask the user once and persist.\n\nUse this structure for the body:\n\n```markdown\n# [Verb + Object] \u2014 Atomic Spec\n\n> **Parent Brief:** `docs/features/<slug>/brief.md` (or "standalone")\n> **Status:** Ready\n> **Date:** YYYY-MM-DD\n> **Estimated scope:** [1 session / N files / ~N lines]\n\n---\n\n## What\nOne paragraph \u2014 what changes when this spec is done?\n\n## Why\nOne sentence \u2014 what breaks or is missing without this?\n\n## External API Contract\n\n_Include this section ONLY when the spec touches a third-party SDK, package, or service API. Omit it entirely otherwise._\n\n**Package:** `<npm-package-name>`\n\n**Canonical sources:**\n- <link to docs>\n- <link to types>\n\n**Key API facts (validated against vX.Y.Z):**\n- <fact 1>\n- <fact 2>\n\n\n## Acceptance Criteria\n- [ ] [Observable behavior]\n- [ ] Build passes\n- [ ] Tests pass\n\n## Test Plan\n\n| Acceptance Criterion | Test | Type |\n|---------------------|------|------|\n| [Each AC above] | [What to call/assert] | [unit/integration/e2e] |\n\n**Execution order:**\n1. Write all tests above \u2014 they should fail against current/stubbed code\n2. Run tests to confirm they fail (red)\n3. Implement until all tests pass (green)\n\n**Smoke test:** [Identify the fastest test for iteration feedback]\n\n**Before implementing, verify your test harness:**\n1. Run all tests \u2014 they must FAIL (if they pass, you\'re testing the wrong thing)\n2. Each test calls your actual function/endpoint \u2014 not a reimplementation or the underlying library\n3. Identify your smoke test \u2014 it must run in seconds, not minutes, so you get fast feedback on each change\n\n## Constraints\n- MUST: [hard requirement]\n- MUST NOT: [hard prohibition]\n\n## Affected Files\n| Action | File | What Changes |\n|--------|------|-------------|\n\n## Approach\nStrategy, data flow, key decisions. Name one rejected alternative.\n\n## Edge Cases\n| Scenario | Expected Behavior |\n|----------|------------------|\n```\n\nIf `docs/templates/ATOMIC_SPEC_TEMPLATE.md` exists, reference it for the full template with additional guidance.\n\nFill in all sections \u2014 each spec must be self-contained (no "see the brief for context"). Copy relevant constraints from the Feature Brief into each spec. Write acceptance criteria specific to THIS spec, not the whole feature. Every acceptance criterion must have at least one corresponding test in the Test Plan. If the user provided test strategy info from the interview, use it to choose test types and frameworks. Include the test harness verification rules in every Test Plan.\n\n### Step 5a: Write the Spec Queue Manifest\n\nAfter all spec `.md` files are written, create `.joycraft-spec-queue.json` in the specs directory alongside the spec files and README. This manifest is the machine-readable, authoritative spec queue consumed by the Pi pipeline automation.\n\n```json\n{\n  "feature": "<slug>",\n  "specs": [\n    { "id": 1, "file": "<spec-name>.md", "depends_on": [], "status": "todo", "mode": "batch" },\n    { "id": 2, "file": "<spec-name>.md", "depends_on": [1], "status": "todo", "mode": "checkpoint" }\n  ]\n}\n```\n\nMap each row in your decomposition table to a spec entry:\n- `id`: sequential integer starting from 1 (matches the decomposition table\'s # column)\n- `file`: the spec filename relative to the specs directory\n- `depends_on`: array of spec ids this spec depends on (empty array `[]` for no dependencies)\n- `status`: always `"todo"` initially \u2014 the agent advances each spec to `"in-review"` via `joycraft-spec-done`, and `joycraft-session-end` graduates it to `"done"` (see `docs/reference/spec-status-lifecycle.md`)\n- `mode`: the human-approved execution mode for this spec (`batch` | `checkpoint` | `isolated`) \u2014 must match the spec file\'s `mode:` frontmatter\n\nValidate: every id referenced in `depends_on` must exist as an `id` in the specs array; the queue `status`/`mode` for each spec must match that spec file\'s frontmatter.\n\n## Step 6: Recommend Execution Strategy and Update Parent Brief\n\nBased on the dependency graph, group specs into execution waves:\n- **Independent specs** \u2014 "These can run in parallel worktrees"\n- **Sequential specs** \u2014 "Execute these in order: 1 -> 2 -> 4"\n- **Mixed** \u2014 "Start specs 1 and 3 in parallel. After 1 completes, start 2."\n\n**Mark each multi-spec wave\'s parallel-safety.** A wave is **parallel-safe** only when its specs\' Affected Files tables are disjoint \u2014 no file appears in two of the wave\'s specs. Overlapping files \u2192 mark the wave NOT parallel-safe and name the overlapping files. Dependency order says what *may* run together; parallel-safety says what *won\'t conflict* when it does \u2014 `joycraft-implement-feature` only parallelizes waves you mark safe.\n\n**Update the parent brief\'s Execution Strategy section** at `docs/features/<slug>/brief.md` with this wave plan, so the brief stays a useful one-stop reference for feature reviewers.\n\n## Step 7: Hand Off\n\nTell the user:\n```\nDecomposition complete:\n- [N] atomic specs created in docs/features/<slug>/specs/\n- [N] can run in parallel, [N] are sequential\n- Estimated total: [N] sessions\n\nTo execute:\n- Whole queue: /skill:joycraft-implement-feature docs/features/<slug>/ \u2014 checks the\n  queue and runs the joycraft-implement-loop driver (fresh pi -p process per spec)\n- One at a time: /skill:joycraft-implement docs/features/<slug>/specs/<first-spec>.md \u2014\n  it wraps up and continues through the queue itself\n\nReady to start execution?\n\nPi \u2014 autonomous (isolated specs): one command runs the whole queue headless \u2014\n  joycraft-implement-loop docs/features/<slug>/specs\nIt loops next-spec \u2192 implement \u2192 spec-done in a fresh `pi -p` process per spec\n(the process boundary IS the context isolation), then runs session-end once. You\ndon\'t hand-choreograph sessions \u2014 the loop advances itself. If the user wants\nthis run for them, invoke that command via the shell rather than implementing\ninline or spawning a subagent (neither gives the verified process-boundary\nisolation). ToS/cost note: the loop is for Pi with a BYO API key or open weights.\nPi \u2014 interactive (step-by-step): run /skill:joycraft-implement docs/features/<slug>/specs,\nthen /new between specs \u2014 your artifacts are saved to files.\nClaude Code / Codex: Run /clear before your next step \u2014 your artifacts are saved to files.\n```\n',
+  "joycraft-design.md": '---\nname: joycraft-design\ndescription: Design discussion before decomposition \u2014 produce a ~200-line design artifact for human review, catching wrong assumptions before they propagate into specs\n---\n\n# Design Discussion\n\nYou are producing a design discussion document for a feature. This sits between research and decomposition \u2014 it captures your understanding so the human can catch wrong assumptions before specs are written.\n\n**Guard clause:** If no brief path is provided and no brief exists at `docs/features/<slug>/brief.md`, say:\n"No feature brief found. Run `/skill:joycraft-new-feature` first to create one, or provide the path to your brief."\nThen stop.\n\n---\n\n## Step 1: Read Inputs\n\nRead the feature brief at the path the user provides. If the user also provides a research document path, read that too. Research is optional \u2014 if none exists, note that you\'ll explore the codebase directly.\n\n## Step 2: Explore the Codebase\n\nSpawn subagents to explore the codebase for patterns relevant to the brief. Focus on:\n\n- Files and functions that will be touched or extended\n- Existing patterns this feature should follow (naming, data flow, error handling)\n- Similar features already implemented that serve as models\n- Boundaries and interfaces the feature must integrate with\n\nGather file paths, function signatures, and code snippets. You need concrete evidence, not guesses.\n\n## Step 3: Write the Design Document\n\nDerive the slug from the brief path (`docs/features/<slug>/brief.md`).\nLazy-create the folder `docs/features/<slug>/` if needed.\nWrite the design document to `docs/features/<slug>/design.md`.\n\nThe file MUST start with YAML frontmatter \u2014 the 4-field personal schema:\n\n```yaml\n---\nstatus: active\nowner: <resolved name>\ncreated: YYYY-MM-DD\nfeature: <slug>\n---\n```\n\n**Owner resolution:** look up the owner name in this order \u2014 (1) `git config user.name`, (2) value in your auto-memory `joycraft-owner.txt` if present, (3) ask the user once and persist.\n\nThe document has exactly five sections:\n\n### Section 1: Current State\n\nWhat exists today in the codebase that is relevant to this feature. Include file paths, function signatures, and data flows. Be specific \u2014 reference actual code, not abstractions. If no research doc was provided, note that and describe what you found through direct exploration.\n\n### Section 2: Desired End State\n\nWhat the codebase should look like when this feature is complete. Describe the change at a high level \u2014 new files, modified interfaces, new data flows. Do NOT include implementation steps. This is the "what," not the "how."\n\n### Section 3: Patterns to Follow\n\nExisting patterns in the codebase that this feature should match. Include short code snippets and `file:line` references. Show the pattern, don\'t just name it.\n\nIf this is a greenfield project with no existing patterns, propose conventions and note that no precedent exists.\n\n### Section 4: Resolved Design Decisions\n\nDecisions you have already made, with brief rationale. Format each as:\n\n> **Decision:** [what you decided]\n> **Rationale:** [why, referencing existing code or constraints]\n> **Alternative rejected:** [what you considered and why you rejected it]\n\n### Section 5: Open Questions\n\nThings you don\'t know or where multiple valid approaches exist. Each question MUST present 2-3 concrete options with pros and cons. Format:\n\n> **Q: [question]**\n> - **Option A:** [description] \u2014 Pro: [benefit]. Con: [cost].\n> - **Option B:** [description] \u2014 Pro: [benefit]. Con: [cost].\n> - **Option C (if applicable):** [description] \u2014 Pro: [benefit]. Con: [cost].\n\nDo NOT ask vague questions like "what do you think?" Every question must have actionable options the human can choose from.\n\n### Update the Feature Brief\n\nAfter writing the design document, update the parent brief with a back-reference:\n1. Read `docs/features/<slug>/brief.md`\n2. In the header blockquote (the `>` lines at the top), add or update:\n   `> **Design:** docs/features/<slug>/design.md`\n3. If a `> **Design:**` line already exists, replace it \u2014 do NOT add a duplicate\n4. Write the brief back\n\n## Step 4: Reconcile Brief with Findings\n\nYou\'ve just written `docs/features/<slug>/design.md`. Before hand-off, the parent brief at `docs/features/<slug>/brief.md` may now disagree with what you discovered. Re-read it and check each of these sections:\n\n| Brief section | What to look for |\n|---|---|\n| Vision | Did your findings refine or contradict the framing? |\n| Hard Constraints | Are any constraints now obsolete, missing, or refined? |\n| Out of Scope | Did your findings push something in or out of scope? |\n| Decomposition | Are spec counts, names, or dependencies still accurate? |\n| Test Strategy | Do your findings change what or how to test? |\n| Success Criteria | Are the criteria still observable and still match the goal? |\n\n**For each section, choose one:**\n\n- **Edit in place** \u2014 small, mechanical updates: line-number corrections, clarifications, additions consistent with brief intent. No user approval needed.\n- **Diff + stop** \u2014 non-trivial changes: counts flipping, decomposition restructure, scope changes, contradiction with original brief intent. Present a diff of the proposed change, STOP, and wait for user approval before continuing.\n\nIf you make changes, note them at the bottom of `design.md` under a "Brief updates" subsection. If the brief is already in sync, note: "Reconciliation checked, no changes required." If no parent brief exists (feature was described inline), note that and skip this step.\n\n**Why this step exists:** the silent-drift gap. Without reconciliation, the brief and downstream artifacts diverge \u2014 and later decomposition is sized against the stale brief. This feature ("single-source-skills") hit exactly this: brief said "11 clean / 9 dirty" until the research re-audit forced a re-decomposition. Don\'t let it happen again.\n\n## Step 5: Present and STOP \u2014 Pre-Approval Hold\n\nPresent the design document to the user. Say:\n\n```\nDesign discussion written to docs/features/<slug>/design.md\n\nPlease review the document above. Specifically:\n1. Are the patterns in Section 3 the right ones to follow, or should I use different ones?\n2. Do you agree with the resolved decisions in Section 4?\n3. Pick an option for each open question in Section 5 (or propose your own).\n\nReply with your feedback. I will NOT proceed to decomposition until you have reviewed and approved this design.\n```\n\n**CRITICAL: Do NOT emit the canonical Handoff block at this point.** The Handoff block emits ONLY after human approval (see "Step 6: Hand Off (Post-Approval Only)" below). The entire value of this skill is the pause \u2014 it forces a human checkpoint before mistakes propagate.\n\n## Offer to Capture Deferred Items to Backlog\n\nIf during the design discussion the user mentions deferred work \u2014 "let\'s not do X yet," "save Y for later" \u2014 ASK before writing:\n\n> "This looks like deferred work \u2014 want me to capture it to `docs/backlog/`?"\n\nOnly on user confirmation, write a backlog entry at `docs/backlog/YYYY-MM-DD-<short-name>.md` with backlog frontmatter:\n\n```yaml\n---\nstatus: backlog\nowner: <resolved name>\ncreated: YYYY-MM-DD\nsource: docs/features/<slug>/brief.md\n---\n```\n\n**Never auto-write to `docs/backlog/`.** Every backlog entry is user-confirmed.\n\n## Step 6: Hand Off (Post-Approval Only)\n\nOnce the human approves the design:\n- Update the design document with their corrections and chosen options\n- Move answered questions from "Open Questions" to "Resolved Design Decisions"\n- Present the updated document for final confirmation\n- Once the user gives explicit approval, AND ONLY THEN, emit the canonical Handoff block:\n\n## Recommended Next Steps\n\nNext:\n```bash\n/skill:joycraft-decompose docs/features/<slug>/brief.md\n```\nRun /new first.\n\nInclude any backlog paths produced as a side effect.\n',
+  "joycraft-gather-context.md": "---\nname: joycraft-gather-context\ndescription: First-run onboarding pass that populates the project context layer -- read what context already exists, then offer a gap-only interview and batch-write the missing fact rows and long-form reference docs\n---\n\n# Gather Context\n\nThis is the first-run **read-then-offer** onboarding pass \u2014 the lowest-intervention way to populate the project's context layer. You read what context already exists, summarize coverage, offer a gap-only interview, and write everything in one reviewable batch at the end.\n\nThis skill is self-contained. It composes the same conventions the single-doc skills use, but everything you need is inlined below \u2014 do not call into or import another skill's logic.\n\n## Step 1: Read What Already Exists First\n\nThe user has invoked the first-run onboarding pass (e.g., `/skill:joycraft-gather-context`). Before asking the user anything, scan the project's existing context. Default scan breadth is **README + `docs/` + AGENTS.md only**:\n\n- The README(s) at the repo root and any obvious sub-package READMEs.\n- `docs/**` \u2014 existing design, architecture, or style docs.\n- `docs/context/*` \u2014 the flat operational fact-docs (production-map, dangerous-assumptions, decision-log, institutional-knowledge, troubleshooting) and `docs/context/reference/*` long-form docs.\n- The current AGENTS.md content, including any `## Context Map` section.\n\nThen summarize for the user what context already exists and what's covered.\n\n**Do NOT auto-run a code-inference scan.** Reading the actual source to infer architecture costs significantly more tokens. Offer that deeper/full review ONLY if the user explicitly asks for it, and when you do, note clearly that it costs more tokens. The default pass never reads the codebase to infer context.\n\n## Step 2: Offer a Gap-Only Interview (Don't Force)\n\nFrom the summary, identify genuine gaps: no design-system doc? no production map? no decision log? Offer an **optional** interview that targets only those gaps. The user can decline any or all of it \u2014 offer, never force.\n\n**Per-doc skip guard (not all-or-nothing):** Never re-interview for a doc that already has real content. Skip each doc that's already populated individually, and interview only the empty or missing ones. If everything is already covered, say so and offer nothing.\n\n## Step 3: Route by Shape (Inline Test)\n\nFor each thing the user wants to capture, apply this minimal shape test inline \u2014 do not defer to another skill:\n\n- **\"Could this be one row in a table?\"** \u2192 it's an **operational fact**. Route it to one of the five flat fact-docs under `docs/context/`:\n  - `docs/context/production-map.md` \u2014 infrastructure, services, environments, URLs, credentials, safe/unsafe to touch.\n  - `docs/context/dangerous-assumptions.md` \u2014 false assumptions an agent might make.\n  - `docs/context/decision-log.md` \u2014 an architectural/tooling choice and why.\n  - `docs/context/institutional-knowledge.md` \u2014 team conventions, unwritten rules, ownership.\n  - `docs/context/troubleshooting.md` \u2014 when X happens, do Y.\n  Append it as a table row (or list item for institutional-knowledge), removing any italic example rows in that table first.\n\n- **\"Does explaining it take paragraphs?\"** \u2192 it's **long-form reference**. Scaffold `docs/context/reference/<slug>.md` from the matching template in `docs/templates/context/reference/` (`design-system`, `frontend-methodology`, `backend`, `testing`, or the generic `reference-doc` fallback), lazy-creating `docs/context/reference/` on first write.\n\nIf an item is ambiguous, apply the test literally: one row \u2192 fact bucket; paragraphs \u2192 reference doc.\n\n## Step 4: Batch-Write + One Final Confirm\n\nDo NOT write per-answer. Collect ALL of the user's gap answers across the whole interview first. Then, in ONE batch:\n\n1. Write all the fact rows into their fact-docs.\n2. Scaffold and write all the reference docs into `docs/context/reference/`.\n3. Add or update the `## Context Map` pointer rows in AGENTS.md \u2014 one row per reference doc, in the form `| docs/context/reference/<slug>.md | <when to read it> |`. Create the `## Context Map` section (header + two-column table) if it doesn't exist; update an existing row in place rather than duplicating it.\n\nPresent the full set of intended changes and get ONE final confirm (\"do it in one go\") before writing. If the user aborts at the final confirm, write nothing \u2014 there are no partial writes in this batch model. The result is one clean, reviewable diff.\n\n## Step 5: Confirm and Hand Off\n\nReport the batch: which fact rows were added, which reference docs were scaffolded, and which Context Map rows were created or updated. Then end with the canonical Handoff block.\n\n## Recommended Next Steps\n\nNext:\n```bash\n/skill:joycraft-session-end\n```\nRun /new first.\n",
+  "joycraft-implement-feature.md": "---\nname: joycraft-implement-feature\ndescription: Run a feature's entire spec queue from one invocation \u2014 delegates to the joycraft-implement-loop driver (fresh pi -p process per spec)\n---\n\n# Implement Feature (Whole-Queue Driver)\n\nOne invocation runs a feature's whole spec queue: `/skill:joycraft-implement-feature docs/features/<slug>/`. On Pi the driver already exists as a script \u2014 `.pi/scripts/joycraft/joycraft-implement-loop` \u2014 and the process boundary it creates (a fresh `pi -p` per spec) is the verified context isolation. **Your job is to point the loop at the right queue and run it, not to reimplement it.**\n\n## Step 1: Load the Queue\n\n1. Resolve the specs directory: if the given path contains a `specs/` subdirectory, use it; otherwise use the path itself. Look for `.joycraft-spec-queue.json` there.\n2. **No queue** \u2192 stop:\n\n   > No spec queue found in [path]. Run `/skill:joycraft-decompose` first \u2014 it writes the queue, the specs, and the wave plan.\n\n3. Read the sibling `README.md` (the wave plan) and report the plan: feature slug, M specs, current statuses, the order the loop will serve them in (`joycraft-next-spec` order: first `todo` whose `depends_on` are all `in-review`/`done`).\n4. If **no `todo` specs remain**, report that and suggest `/skill:joycraft-session-end` if the feature was never finished; do not run the loop.\n\n## Step 2: Run the Loop\n\nInvoke the driver via the shell, pointing at the specs dir:\n\n```\njoycraft-implement-loop docs/features/<slug>/specs\n```\n\nWhat it does (so you can narrate it, not reimplement it): `joycraft-next-spec` \u2192 fresh `pi -p \"/skill:joycraft-implement <spec>\"` \u2192 fresh `pi -p \"/skill:joycraft-spec-done <spec>\"` \u2192 repeat; **fail-fast** (exits non-zero naming the failing spec, queue left intact); runs `joycraft-session-end` exactly once when the queue is exhausted.\n\nNotes:\n- The driver spawns `pi -p` subprocesses; nesting it under an already-running Pi session is sound by design but not yet smoke-tested end-to-end \u2014 if the nested `pi -p` misbehaves, fall back to telling the human to run the command above in a separate terminal.\n- **ToS/cost:** this path is for Pi with a BYO API key or open-weight model \u2014 do not route a subscription OAuth through it.\n\n## Step 3: Report\n\nRelay the loop's outcome:\n\n- **Success** \u2192 which specs ran, and session-end's own report (validation, graduation `in-review \u2192 done`, push/PR per AGENTS.md autonomy).\n- **Failure** \u2192 which spec failed (the loop names it), what reached `in-review`, what remains `todo`. Suggest fixing in a fresh session (`/skill:joycraft-implement <failed-spec>`), then re-running the loop for the remainder \u2014 it picks up where it stopped.\n",
+  "joycraft-implement-level5.md": "---\nname: joycraft-implement-level5\ndescription: Set up Level 5 autonomous development \u2014 autofix loop, holdout scenario testing, and scenario evolution from specs\n---\n\n# Implement Level 5 \u2014 Autonomous Development Loop\n\nYou are guiding the user through setting up Level 5: the autonomous feedback loop where specs go in, validated software comes out. This is a one-time setup that installs workflows, creates a scenarios repo, and configures the autofix loop.\n\n## Before You Begin\n\nCheck prerequisites:\n\n1. **Project must be initialized.** Look for `.claude/.joycraft/state.json` (older installs may still have a legacy `.joycraft-version` at the repo root). If neither exists, tell the user to run `npx joycraft init` first.\n2. **Project should be at Level 4.** Check `docs/skill:joycraft-assessment.md` if it exists. If the project hasn't been assessed yet, suggest running `/skill:joycraft-tune` first. But don't block \u2014 the user may know they're ready.\n3. **Git repo with GitHub remote.** This setup requires GitHub Actions. Check for `.git/` and a GitHub remote.\n\nIf prerequisites aren't met, explain what's needed and stop.\n\n## Step 1: Explain What Level 5 Means\n\nTell the user:\n\n> Level 5 is the autonomous loop. When you push specs, three things happen automatically:\n>\n> 1. **Scenario evolution** \u2014 A separate AI agent reads your specs and writes holdout tests in a private scenarios repo. These tests are invisible to your coding agent.\n> 2. **Autofix** \u2014 When CI fails on a PR, Claude Code automatically attempts a fix (up to 3 times).\n> 3. **Holdout validation** \u2014 When CI passes, your scenarios repo runs behavioral tests against the PR. Results post as PR comments.\n>\n> The key insight: your coding agent never sees the scenario tests. This prevents it from gaming the test suite \u2014 like a validation set in machine learning.\n\n## Step 2: Gather Configuration\n\nAsk these questions **one at a time**:\n\n### Question 1: Scenarios repo name\n\n> What should we call your scenarios repo? It'll be a private repo that holds your holdout tests.\n>\n> Default: `{current-repo-name}-scenarios`\n\nAccept the default or the user's choice.\n\n### Question 2: GitHub App\n\n> Level 5 needs a GitHub App to provide a separate identity for autofix pushes (this avoids GitHub's anti-recursion protection). Creating one takes about 2 minutes:\n>\n> 1. Go to https://github.com/settings/apps/new\n> 2. Give it a name (e.g., \"My Project Autofix\")\n> 3. Uncheck \"Webhook > Active\" (not needed)\n> 4. Under **Repository permissions**, set:\n>    - **Contents**: Read & Write\n>    - **Pull requests**: Read & Write\n>    - **Actions**: Read & Write\n> 5. Click **Create GitHub App**\n> 6. Note the **App ID** from the settings page\n> 7. Scroll to **Private keys** > click **Generate a private key** > save the `.pem` file\n> 8. Click **Install App** in the left sidebar > install it on your repo\n>\n> What's your App ID?\n\n## Step 3: Run init-autofix\n\nRun the CLI command with the gathered configuration:\n\n```bash\nnpx joycraft init-autofix --scenarios-repo {name} --app-id {id}\n```\n\nReview the output with the user. Confirm files were created.\n\n## Step 4: Walk Through Secret Configuration\n\nGuide the user step by step:\n\n### 4a: Add Secrets to Main Repo\n\n> You should already have the `.pem` file from when you created the app in Step 2.\n\n> Go to your repo's Settings > Secrets and variables > Actions, and add:\n> - `JOYCRAFT_APP_PRIVATE_KEY` \u2014 paste the contents of your `.pem` file\n> - `ANTHROPIC_API_KEY` \u2014 your Anthropic API key\n\n### 4b: Create the Scenarios Repo\n\n> Create the private scenarios repo:\n> ```bash\n> gh repo create {scenarios-repo-name} --private\n> ```\n>\n> Then copy the scenario templates into it:\n> ```bash\n> cp -r docs/templates/scenarios/* ../{scenarios-repo-name}/\n> cd ../{scenarios-repo-name}\n> git add -A && git commit -m \"init: scaffold scenarios repo from Joycraft\"\n> git push\n> ```\n\n### 4c: Add Secrets to Scenarios Repo\n\n> The scenarios repo also needs the App private key:\n> - `JOYCRAFT_APP_PRIVATE_KEY` \u2014 same `.pem` file as the main repo\n> - `ANTHROPIC_API_KEY` \u2014 same key (needed for scenario generation)\n\n## Step 5: Verify Setup\n\nHelp the user verify everything is wired correctly:\n\n1. **Check workflow files exist:** `ls .github/workflows/autofix.yml .github/workflows/scenarios-dispatch.yml .github/workflows/spec-dispatch.yml .github/workflows/scenarios-rerun.yml`\n2. **Check scenario templates were copied:** Verify the scenarios repo has `example-scenario.test.ts`, `workflows/run.yml`, `workflows/generate.yml`, `prompts/scenario-agent.md`\n3. **Check the App ID is correct** in the workflow files (not still a placeholder)\n\n## Step 6: Update AGENTS.md\n\nIf the project's AGENTS.md doesn't already have an \"External Validation\" section, add one:\n\n> ## External Validation\n>\n> This project uses holdout scenario tests in a separate private repo.\n>\n> ### NEVER\n> - Access, read, or reference the scenarios repo\n> - Mention scenario test names or contents\n> - Modify the scenarios dispatch workflow to leak test information\n>\n> The scenarios repo is deliberately invisible to you. This is the holdout guarantee.\n\n## Step 7: First Test (Optional)\n\nIf the user wants to test the loop:\n\n> Want to do a quick test? Here's how:\n>\n> 1. Write a simple spec in `docs/features/<slug>/specs/` and push to main \u2014 this triggers scenario generation\n> 2. Create a PR with a small change \u2014 when CI passes, scenarios will run\n> 3. Watch for the scenario test results as a PR comment\n>\n> Or deliberately break something in a PR to test the autofix loop.\n\n## Step 8: Summary\n\nPrint a summary of what was set up:\n\n> **Level 5 is live.** Here's what's running:\n>\n> | Trigger | What Happens |\n> |---------|-------------|\n> | Push specs to `docs/features/<slug>/specs/` | Scenario agent writes holdout tests |\n> | PR fails CI | Claude autofix attempts (up to 3x) |\n> | PR passes CI | Holdout scenarios run against PR |\n> | Scenarios update | Open PRs re-tested with latest scenarios |\n>\n> Your scenarios repo: `{name}`\n> Your coding agent cannot see those tests. The holdout wall is intact.\n\n**Important:** Tell the user:\n\n> **Before you can test the loop**, you need to merge this PR to main first. GitHub's `workflow_run` triggers only activate for workflows that exist on the default branch. Once merged, create a new PR with any small change \u2014 that's when you'll see Autofix, Scenarios Dispatch, and Spec Dispatch fire for the first time.\n\nUpdate `docs/skill:joycraft-assessment.md` if it exists \u2014 set the Level 5 score to reflect the new setup.\n",
+  "joycraft-implement.md": "---\nname: joycraft-implement\ndescription: Execute atomic specs with TDD \u2014 read spec, write failing tests, implement until green, wrap up and continue the queue\n---\n\n# Implement Atomic Spec\n\nYou have exactly one atomic spec file to execute. Your job is to implement it using strict TDD \u2014 tests first, confirm they fail, then implement until green.\n\n## Step 1: Parse Arguments\n\nThe user MUST provide a path. No path = stop immediately.\n\n**If no path was provided:**\n\n> No spec path provided. Provide a spec file or a feature directory:\n> `/skill:joycraft-implement docs/features/<slug>/specs/spec-name.md`\n> or `/skill:joycraft-implement docs/features/<slug>/`\n\n**If the path is a directory** (ends with `/` or does not end with `.md`):\n\nLook for `specs/.joycraft-spec-queue.json` inside that directory. Read it. Find the **first `todo` spec whose dependencies are satisfied** (a dependency is satisfied once it is `in-review` or `done`). This matches what `joycraft-next-spec` serves. That single spec file is your target. Do NOT read any other specs.\n\n> Using spec queue: found [spec-file-name] as the next spec.\n\nIf the directory has no queue or no `todo` specs:\n\n> No remaining specs found in [directory].\n\n**If the path is a file** ending in `.md`:\n\nUse it directly as the spec to implement.\n\n## Step 2: Read the Sibling README.md FIRST (if present)\n\nBefore reading the spec itself, check for a sibling `README.md` in the same folder as the spec \u2014 i.e., `<spec-path>/../README.md`. This file is the wave-plan + spec-table that `/skill:joycraft-decompose` writes per feature.\n\n- **If present:** Read the README first. It tells you the spec's position in the wave plan, its dependencies, and which sibling specs (in the same folder) need to be done before this one.\n- **If absent:** That's fine \u2014 proceed normally. The convention is forward-only and many legacy spec folders pre-date it.\n\n### Warn on Unmet Dependencies\n\nIf the README shows that this spec depends on other specs in the same folder, check whether those dependencies are satisfied. A dependency is satisfied once its frontmatter `status:` is `in-review` or `done` (see `docs/reference/spec-status-lifecycle.md`) \u2014 a checkpoint chain progresses on `in-review` without waiting for session-end to graduate it to `done`. A dependency still at `todo` is unmet.\n\nIf any dependency is **not** complete, tell the user:\n\n> \"This spec lists unmet dependencies in the sibling README.md: [list]. Proceed anyway, or stop?\"\n\nWait for confirmation before continuing. The user might be deliberately running out of order (a hotfix, an exploration, etc.) \u2014 your job is to surface the warning, not to gate.\n\n## Step 3: Read and Understand the Spec\n\n1. **Read the spec file.** The spec is your execution contract \u2014 the Acceptance Criteria and Test Plan define \"done.\"\n2. **Check the spec's Status field.** If it says \"Complete,\" warn the user and ask if they want to re-implement or skip.\n3. **Read the Acceptance Criteria** \u2014 these are your success conditions.\n4. **Read the Test Plan** \u2014 this tells you exactly what tests to write and in what order.\n5. **Read the Constraints** \u2014 these are hard boundaries you must not violate.\n\n### Finding Additional Context\n\nSpecs are designed to be self-contained, but if you need more context:\n\n- **Parent brief:** Linked in the spec's body (`> **Parent Brief:**` line). The new convention is `docs/features/<slug>/brief.md`. Read it for broader feature context.\n- **Related specs:** Live in the same directory (typically `docs/features/<slug>/specs/`). The sibling `README.md` (read in Step 2 above) is the index.\n- **Affected Files:** The spec's Affected Files table tells you which files to create or modify.\n\n\n### Before writing code against an external API:\n\n\u26A0\uFE0F If the spec references a third-party SDK or package, read its official documentation and type definitions FIRST. Never write a `declare module` stub for a package that actually exists \u2014 use the real package as a devDependency instead. The stub will make typecheck pass but the code will fail at runtime.\n\n## Step 4: Execute the TDD Cycle\n\n**This is not optional. Write tests FIRST.**\n\n### 3a. Write Tests (Red Phase)\n\nUsing the spec's Test Plan:\n\n1. Write ALL tests listed in the Test Plan. Each Acceptance Criterion must have at least one test.\n2. Tests should call the actual function/endpoint \u2014 not a reimplementation or mock of the underlying library.\n3. Run the tests. **They MUST fail.** If any test passes immediately:\n   - Flag it \u2014 either the test isn't testing the right thing, or the code already exists.\n   - Investigate before proceeding. A test that passes before implementation is a test that proves nothing.\n\n### 3b. Implement (Green Phase)\n\n1. Follow the spec's Approach section for implementation strategy.\n2. Implement the minimum code needed to make tests pass.\n3. Run tests after each meaningful change \u2014 use the spec's Smoke Test for fast feedback.\n4. Continue until ALL tests pass.\n\n### 3c. Verify Acceptance Criteria\n\nWalk through every Acceptance Criterion in the spec:\n\n- [ ] Is each one met?\n- [ ] Does the build pass?\n- [ ] Do all tests pass?\n\nIf any criterion is not met, keep implementing. Do not move on until all criteria are green.\n\n## Step 5: Handle Edge Cases\n\nCheck the spec's Edge Cases table. For each scenario:\n\n- Verify the expected behavior is handled.\n- If the spec says \"warn the user\" or \"prompt,\" make sure that path works.\n\n## Step 6: Wrap Up and Continue (mode-aware \u2014 do the wrap-up yourself)\n\n**Loop-iteration check FIRST.** If this process is one iteration of the `joycraft-implement-loop` driver (you were launched by `pi -p` with a single spec path), STOP after the implementation report \u2014 do **not** wrap up and do **not** continue. The loop runs `/skill:joycraft-spec-done` as its own fresh `pi -p` step and advances the queue itself; wrapping up here would double-run it.\n\nOtherwise (interactive session), when the spec is implemented and all its tests pass, wrap up and advance according to the spec's **execution mode**. Read the `mode:` field from the spec's frontmatter (written by `joycraft-decompose`). If the spec has **no `mode:` field**, default to **`batch`** (back-compat with pre-mode specs). If the value is unrecognized, treat it as `batch` and note the unrecognized value.\n\n**You perform the wrap-up. You find the next spec. Do not stop to tell the human to run `/skill:joycraft-spec-done` or to paste the next file path \u2014 those hand-backs carry zero information and break the feature's momentum.**\n\n### 6a. Per-spec wrap-up\n\n| Spec `mode:` | Wrap-up you perform now |\n|--------------|------------------------|\n| **batch** | **Status bump only**: set the spec to `in-review` in both systems (see below). No commit, no discovery stub \u2014 batch wraps once at feature end. (The bump is required: the queue treats a dependency as satisfied at `in-review`, so without it dependent specs would look blocked.) |\n| **checkpoint** / **isolated** | The full `joycraft-spec-done` wrap-up, performed by you (canonical definition: `.pi/skills/joycraft-spec-done/SKILL.md`): **(1)** bump status to `in-review` in both systems, **(2)** terse 2-line discovery stub at `docs/discoveries/YYYY-MM-DD-topic.md` ONLY if something contradicted the spec \u2014 usually skip, **(3)** commit `spec: <spec-name>` (implementation + status edits + stub, nothing unrelated), **(4)** no validation re-run, no push, no PR \u2014 those belong to `joycraft-session-end`. |\n\n**Both systems** means: the queue JSON (`joycraft-mark-done <spec-id> --to in-review <specs-dir>` if `.pi/scripts/joycraft/` is installed, else edit `.joycraft-spec-queue.json` directly) AND the spec file's `status:` frontmatter. Never `done` \u2014 the agent doesn't self-certify (`docs/reference/spec-status-lifecycle.md`).\n\n### 6b. Continue the queue (batch and checkpoint)\n\nRe-read `.joycraft-spec-queue.json` in the spec's directory and find the next `todo` spec whose dependencies are all `in-review`/`done` (same rule as Step 1). Then:\n\n- **Next ready spec exists** \u2192 announce one line \u2014 `Continuing: <next-spec> (spec N of M)` \u2014 and go back to Step 2 with it, in this same conversation.\n- **Remaining `todo` specs are all blocked** \u2192 stop and report which specs are blocked and on what.\n- **No `todo` specs remain** \u2192 this was the feature's last spec; go to 6d.\n- **No queue** (you were invoked with a bare spec file outside a queue) \u2192 report the spec complete and stop; there is nothing to continue from.\n\n### 6c. isolated \u2014 fresh context per spec\n\nA conversation cannot clear its own context, so after the wrap-up the fresh context comes from outside:\n\n- **Driver (recommended):** `/skill:joycraft-implement-feature docs/features/<slug>/` runs the remaining queue with a fresh-context subagent per spec \u2014 in-session, interactive, no headless loop.\n- **Guided-manual:** tell the human to run `/new`, then re-invoke `/skill:joycraft-implement <next-spec>`. (Always fine, no ToS/cost surprise.)\n- **Pi:** the `joycraft-implement-loop` driver automates it \u2014 a fresh `pi -p` process per spec. Nothing for you to do beyond the wrap-up; the loop advances.\n- **Headless (`claude -p` / `codex exec` loop):** opt-in only. **Surface the caveat, don't bury it:** unattended headless loops draw metered, full-rate API usage and carry a ToS posture the user must **knowingly opt into** (Anthropic meters `claude -p` from a separate full-rate pool; routing subscription OAuth through third-party harnesses is prohibited). The responsible default is Pi (BYO API key / open weights). Do not silently auto-run a subscription-backed headless loop.\n\n### 6d. Feature's last spec (any mode)\n\nRun the once-per-feature finisher yourself: invoke `/skill:joycraft-session-end` (or read and follow `.pi/skills/joycraft-session-end/SKILL.md`). It carries its own gates \u2014 validation is mandatory and must pass before specs graduate `in-review \u2192 done`, and push/PR honor the project's AGENTS.md git autonomy rules \u2014 so running it automatically is safe.\n\n### Report\n\nAfter each spec's wrap-up, report tersely before continuing:\n\n```\nSpec complete: [spec name] \xB7 mode: [mode] \xB7 tests: [N] passing \xB7 [wrapped up + committed | status bumped (batch)]\n[Continuing: <next-spec> (spec N of M) | Feature complete \u2014 running session-end | Blocked: <specs + reasons>]\n```\n",
+  "joycraft-interview.md": '---\nname: joycraft-interview\ndescription: Brainstorm freely about what you want to build \u2014 yap, explore ideas, and get a structured summary you can use later\n---\n\n# Interview \u2014 Idea Exploration\n\nYou are helping the user brainstorm and explore what they want to build. This is a lightweight, low-pressure conversation \u2014 not a formal spec process. Let them yap.\n\n## How to Run the Interview\n\n### 1. Open the Floor\n\nStart with something like:\n"What are you thinking about building? Just talk \u2014 I\'ll listen and ask questions as we go."\n\nLet the user talk freely. Do not interrupt their flow. Do not push toward structure yet.\n\n### 2. Ask Clarifying Questions\n\nAs they talk, weave in questions naturally \u2014 don\'t fire them all at once:\n\n- **What problem does this solve?** Who feels the pain today?\n- **What does "done" look like?** If this worked perfectly, what would a user see?\n- **What are the constraints?** Time, tech, team, budget \u2014 what boxes are we in?\n- **What\'s NOT in scope?** What\'s tempting but should be deferred?\n- **What are the edge cases?** What could go wrong? What\'s the weird input?\n- **What exists already?** Are we building on something or starting fresh?\n\n### 3. Play Back Understanding\n\nAfter the user has gotten their ideas out, reflect back:\n"So if I\'m hearing you right, you want to [summary]. The core problem is [X], and done looks like [Y]. Is that right?"\n\nLet them correct and refine. Iterate until they say "yes, that\'s it."\n\n### 4. Write a Draft Brief\n\nDerive a slug `YYYY-MM-DD-<topic>` (today\'s date + kebab-case topic \u2014 no `-draft` suffix).\nCreate a draft file at `docs/features/<slug>/brief.md`. Lazy-create `docs/features/<slug>/` if it doesn\'t exist.\n\nThe file MUST start with YAML frontmatter \u2014 the 4-field personal schema with `status: draft`:\n\n```yaml\n---\nstatus: draft\nowner: <resolved name>\ncreated: YYYY-MM-DD\nfeature: <slug>\n---\n```\n\n**Owner resolution:** look up the owner name in this order \u2014 (1) `git config user.name`, (2) value in your auto-memory `joycraft-owner.txt` if present, (3) ask the user once and persist. If you can\'t get a name, leave the field as `<resolved name>` and note it for the user.\n\nUse this format for the body:\n\n```markdown\n# [Topic] \u2014 Draft Brief\n\n> **Date:** YYYY-MM-DD\n> **Origin:** /skill:joycraft-interview session\n\n---\n\n## The Idea\n[2-3 paragraphs capturing what the user described \u2014 their words, their framing]\n\n## Problem\n[What pain or gap this addresses]\n\n## What "Done" Looks Like\n[The user\'s description of success \u2014 observable outcomes]\n\n## Constraints\n- [constraint 1]\n- [constraint 2]\n\n## Open Questions\n- [things that came up but weren\'t resolved]\n- [decisions that need more thought]\n\n## Out of Scope (for now)\n- [things explicitly deferred \u2014 see also: deferred work goes to `docs/backlog/`]\n\n## Raw Notes\n[Any additional context, quotes, or tangents worth preserving]\n```\n\n### 5. Offer to Capture Deferred Items to Backlog\n\nIf during the conversation deferred work surfaces (a tangent, a "later" item, a "out-of-scope but tempting" idea), ASK the user:\n\n> "This looks like deferred work \u2014 want me to capture it to `docs/backlog/`?"\n\nOnly on user confirmation, write a backlog entry at `docs/backlog/YYYY-MM-DD-<short-name>.md` with backlog frontmatter:\n\n```yaml\n---\nstatus: backlog\nowner: <resolved name>\ncreated: YYYY-MM-DD\nsource: docs/features/<slug>/brief.md\n---\n```\n\n**Never auto-write to `docs/backlog/`.** Every backlog entry is user-confirmed.\n\n### 6. Hand Off\n\nAfter writing the draft (and any backlog entries), present the canonical Handoff block.\nInclude any backlog paths produced as a side effect.\n\n## Recommended Next Steps\n\nNext:\n```bash\n/skill:joycraft-new-feature docs/features/<slug>/brief.md\n```\nRun /new first.\n\nIf the idea sounds complex \u2014 touches many files, involves architectural decisions, or the user is working in an unfamiliar area \u2014 nudge them toward research and design (e.g., `/skill:joycraft-research` then `/skill:joycraft-design`). But present it as a recommendation, not a gate.\n\n## Guidelines\n\n- **This is NOT /skill:joycraft-new-feature.** Do not push toward formal briefs, decomposition tables, or atomic specs. The point is exploration.\n- **Let the user lead.** Your job is to listen, clarify, and capture \u2014 not to structure or direct.\n- **Mark everything as DRAFT.** The output is a starting point, not a commitment.\n- **Keep it short.** The draft brief should be 1-2 pages max. Capture the essence, not every detail.\n- **Multiple interviews are fine.** The user might run this several times as their thinking evolves. Each creates a new dated draft.\n',
   "joycraft-lockdown.md": "---\nname: joycraft-lockdown\ndescription: Generate constrained execution boundaries for an implementation session -- NEVER rules and deny patterns to prevent agent overreach\n---\n\n# Lockdown Mode\n\nThe user wants to constrain agent behavior for an implementation session. Your job is to interview them about what should be off-limits, then generate AGENTS.md NEVER rules and Codex configuration deny patterns they can review and apply.\n\n## When Is Lockdown Useful?\n\nLockdown is most valuable for:\n- **Complex tech stacks** (hardware, firmware, multi-device) where agents can cause real damage\n- **Long-running autonomous sessions** where you won't be monitoring every action\n- **Production-adjacent work** where accidental network calls or package installs are risky\n\nFor simple feature work on a well-tested codebase, lockdown is usually overkill. Mention this context to the user so they can decide.\n\n## Step 1: Check for Tests\n\nBefore starting the interview, search the codebase for test files or directories (look for `tests/`, `test/`, `__tests__/`, `spec/`, or files matching `*.test.*`, `*.spec.*`).\n\nIf no tests are found, tell the user:\n\n> Lockdown mode is most useful when you already have tests in place -- it prevents the agent from modifying them while constraining behavior to writing code and running tests. Consider running `/skill:joycraft-new-feature` first to set up a test-driven workflow, then come back to lock it down.\n\nIf the user wants to proceed anyway, continue with the interview.\n\n## Step 2: Interview -- What to Lock Down\n\nAsk these three questions, one at a time. Wait for the user's response before proceeding to the next question.\n\n### Question 1: Read-Only Files\n\n> What test files or directories should be off-limits for editing? (e.g., `tests/`, `__tests__/`, `spec/`, specific test files)\n>\n> I'll generate NEVER rules to prevent editing these.\n\nIf the user isn't sure, suggest the test directories you found in Step 1.\n\n### Question 2: Allowed Commands\n\n> What commands should the agent be allowed to run? Defaults:\n> - Write and edit source code files\n> - Run the project's smoke test command\n> - Run the full test suite\n>\n> Any other commands to explicitly allow? Or should I restrict to just these?\n\n### Question 3: Denied Commands\n\n> What commands should be denied? Defaults:\n> - Package installs (`npm install`, `pip install`, `cargo add`, `go get`, etc.)\n> - Network tools (`curl`, `wget`, `ping`, `ssh`)\n> - Direct log file reading\n>\n> Any specific commands to add or remove from this list?\n\n**Edge case -- user wants to allow some network access:** If the user mentions API tests or specific endpoints that need network access, exclude those from the deny list and note the exception in the output.\n\n**Edge case -- user wants to lock down file writes:** If the user wants to prevent ALL file writes, warn them:\n\n> Denying all file writes would prevent the agent from doing any work. I recommend keeping source code writes allowed and only locking down test files, config files, or other sensitive directories.\n\n## Step 3: Generate Boundaries\n\nBased on the interview responses, generate output in this exact format:\n\n```\n## Lockdown boundaries generated\n\nReview these suggestions and add them to your project:\n\n### AGENTS.md -- add to NEVER section:\n\n- Edit any file in `[user's test directories]`\n- Run `[denied package manager commands]`\n- Use `[denied network tools]`\n- Read log files directly -- interact with logs only through test assertions\n- [Any additional NEVER rules based on user responses]\n\n### Codex configuration -- suggested deny patterns:\n\nAdd these to your Codex sandbox configuration to restrict command execution:\n\n[\"[command1]\", \"[command2]\", \"[command3]\"]\n\n---\n\nCopy these into your project manually, or tell me to apply them now (I'll show you the exact changes for approval first).\n```\n\nAdjust the content based on the actual interview responses:\n- Only include deny patterns for commands the user confirmed should be denied\n- Only include NEVER rules for directories/files the user specified\n- If the user allowed certain network tools or package managers, exclude those\n\n## Recommended Execution Model\n\nAfter generating the boundaries above, also recommend a Codex execution configuration. Include this section in your output:\n\n```\n### Recommended Execution Configuration\n\nCodex runs in a sandboxed environment by default. To maximize safety during lockdown:\n\n| Your situation | Configuration | Why |\n|---|---|---|\n| Autonomous spec execution | Sandbox with deny patterns above | Only pre-approved commands run |\n| Long session with some trust | Default sandbox | Network-disabled sandbox prevents external access |\n| Interactive development | Default with manual review | Review outputs before applying |\n\n**For lockdown mode, we recommend the default sandboxed execution** combined with the deny patterns above. Codex's sandbox already disables network access by default -- the deny patterns add file-level and command-level restrictions on top.\n\nIf you need network access for specific commands (e.g., API tests), configure explicit network allowances in your Codex setup rather than disabling the sandbox entirely.\n```\n\n## Step 4: Offer to Apply\n\nIf the user asks you to apply the changes:\n\n1. **For AGENTS.md:** Read the existing AGENTS.md, find the Behavioral Boundaries section, and show the user the exact diff for the NEVER section. Ask for confirmation before writing.\n2. **For Codex configuration:** Show the user what the deny patterns will look like after adding the new restrictions. Ask for confirmation before writing.\n\n**Never auto-apply. Always show the exact changes and wait for explicit approval.**\n",
-  "joycraft-new-feature.md": '---\nname: joycraft-new-feature\ndescription: Guided feature development \u2014 interview the user, produce a Feature Brief, then decompose into atomic specs\n---\n\n# New Feature Workflow\n\nYou are starting a new feature. Follow this process in order. Do not skip steps.\n\n## Phase 0: Check for Existing Drafts\n\nBefore starting the interview, check if the user has already drafted a brief.\n\n**Skip this phase if:** the user provided a brief path as an argument (they already know what to work from).\n\n**Steps:**\n1. Check if `docs/features/` exists. If not, skip to Phase 1.\n2. List subdirectories. For each `docs/features/<slug>/brief.md`, read the YAML frontmatter at the top.\n3. **Filter by status:** treat each brief as `status: active` unless its frontmatter says otherwise. **Skip** any brief whose `status:` is `shipped`, `deprecated`, or `superseded`. Also skip anything under `docs/archive/` \u2014 those are out-of-scope for new feature work.\n4. Group what you find:\n   - **Drafts** (frontmatter `status: draft`) \u2014 likely from `/skill:joycraft-interview`.\n   - **Active in-flight** (frontmatter `status: active`) \u2014 work the user already started.\n\n5. Present them:\n\n```\nI found existing artifacts in docs/features/:\n\nDrafts:\n- docs/features/<slug>/brief.md (drafted YYYY-MM-DD)\n\nActive features:\n- docs/features/<slug>/brief.md (started YYYY-MM-DD)\n\nWant me to:\n1. **Formalize** a draft into a full Feature Brief\n2. **Continue** an active feature\n3. **Start a new interview** from scratch\n```\n\n6. If user picks formalize/continue: read the full brief, extract context, and jump to Phase 2 with that context pre-filled.\n7. If user picks start fresh, or nothing found: proceed to Phase 1.\n\n## Phase 1: Interview\n\nInterview the user about what they want to build. Let them talk \u2014 your job is to listen, then sharpen.\n\n**Ask about:**\n- What problem does this solve? Who is affected?\n- What does "done" look like?\n- Hard constraints? (business rules, tech limitations, deadlines)\n- What is explicitly NOT in scope? (push hard on this)\n- Edge cases or error conditions?\n- What existing code/patterns should this follow?\n- Testing: existing setup? framework? smoke test budget? lockdown mode desired?\n\n**Interview technique:**\n- Let the user "yap" \u2014 don\'t interrupt their flow\n- Play back your understanding: "So if I\'m hearing you right..."\n- Push toward testable statements: "How would we verify that works?"\n\nKeep asking until you can fill out a Feature Brief.\n\n## Phase 2: Feature Brief\n\nDerive a slug `YYYY-MM-DD-<feature-name>` (today\'s date + kebab-case feature name).\nWrite the Feature Brief to `docs/features/<slug>/brief.md`. Lazy-create the folder if needed.\n\n**Slug derivation:** today\'s date in `YYYY-MM-DD` format, then `-`, then the feature name lower-cased and hyphen-separated. Example: a feature about "Token Discipline" started on 2026-04-06 \u2192 slug `2026-04-06-token-discipline` \u2192 folder `docs/features/2026-04-06-token-discipline/`.\n\n**Why:** The brief is the single source of truth for what we\'re building. It prevents scope creep and gives every spec a shared reference point.\n\nUse this structure:\n\n```markdown\n# [Feature Name] \u2014 Feature Brief\n\n> **Date:** YYYY-MM-DD\n> **Project:** [project name]\n> **Status:** Interview | Decomposing | Specs Ready | In Progress | Complete\n\n---\n\n## Vision\nWhat are we building and why? The full picture in 2-4 paragraphs.\n\n## User Stories\n- As a [role], I want [capability] so that [benefit]\n\n## Hard Constraints\n- MUST: [constraint that every spec must respect]\n- MUST NOT: [prohibition that every spec must respect]\n\n## Out of Scope\n- NOT: [tempting but deferred]\n\n## Test Strategy\n- **Existing setup:** [framework and tools, or "none yet"]\n- **User expertise:** [comfortable / learning / needs guidance]\n- **Test types:** [smoke, unit, integration, e2e, etc.]\n- **Smoke test budget:** [target time for fast-feedback tests]\n- **Lockdown mode:** [yes/no \u2014 constrain agent to code + tests only]\n\n## Decomposition\n| # | Spec Name | Description | Dependencies | Est. Size |\n|---|-----------|-------------|--------------|-----------|\n| 1 | [verb-object] | [one sentence] | None | [S/M/L] |\n\n## Execution Strategy\n- [ ] Sequential (specs have chain dependencies)\n- [ ] Parallel (specs are independent)\n- [ ] Mixed\n\n## Success Criteria\n- [ ] [End-to-end behavior 1]\n- [ ] [No regressions in existing features]\n```\n\nIf `docs/templates/FEATURE_BRIEF_TEMPLATE.md` exists, reference it for the full template with additional guidance.\n\nPresent the brief to the user. Focus review on:\n- "Does the decomposition match how you think about this?"\n- "Is anything in scope that shouldn\'t be?"\n- "Are the specs small enough? Can each be described in one sentence?"\n\nIterate until approved.\n\n## Phase 3: Generate Atomic Specs\n\nFor each row in the decomposition table, create a self-contained spec file at `docs/features/<slug>/specs/<spec-name>.md`. Lazy-create the `specs/` subfolder if it doesn\'t exist.\n\n**Why:** Each spec must be understandable WITHOUT reading the Feature Brief. This prevents the "Curse of Instructions" \u2014 no spec should require holding the entire feature in context. Copy relevant context into each spec.\n\nUse this structure for each spec:\n\n```markdown\n# [Verb + Object] \u2014 Atomic Spec\n\n> **Parent Brief:** `docs/features/<slug>/brief.md`\n> **Status:** Ready\n> **Date:** YYYY-MM-DD\n> **Estimated scope:** [1 session / N files / ~N lines]\n\n---\n\n## What\nOne paragraph \u2014 what changes when this spec is done?\n\n## Why\nOne sentence \u2014 what breaks or is missing without this?\n\n## Acceptance Criteria\n- [ ] [Observable behavior]\n- [ ] Build passes\n- [ ] Tests pass\n\n## Test Plan\n\n| Acceptance Criterion | Test | Type |\n|---------------------|------|------|\n| [Each AC above] | [What to call/assert] | [unit/integration/e2e] |\n\n**Execution order:**\n1. Write all tests above \u2014 they should fail against current/stubbed code\n2. Run tests to confirm they fail (red)\n3. Implement until all tests pass (green)\n\n**Smoke test:** [Identify the fastest test for iteration feedback]\n\n**Before implementing, verify your test harness:**\n1. Run all tests \u2014 they must FAIL (if they pass, you\'re testing the wrong thing)\n2. Each test calls your actual function/endpoint \u2014 not a reimplementation or the underlying library\n3. Identify your smoke test \u2014 it must run in seconds, not minutes, so you get fast feedback on each change\n\n## Constraints\n- MUST: [hard requirement]\n- MUST NOT: [hard prohibition]\n\n## Affected Files\n| Action | File | What Changes |\n|--------|------|-------------|\n\n## Approach\nStrategy, data flow, key decisions. Name one rejected alternative.\n\n## Edge Cases\n| Scenario | Expected Behavior |\n|----------|------------------|\n```\n\nIf `docs/templates/ATOMIC_SPEC_TEMPLATE.md` exists, reference it for the full template with additional guidance.\n\n## Phase 4: Hand Off for Execution\n\nBefore jumping to execution, consider whether research or design would catch wrong assumptions early:\n\n```\nFeature Brief and [N] atomic specs are ready.\n\nSpecs:\n1. [spec-name] \u2014 [one sentence] [S/M/L]\n2. [spec-name] \u2014 [one sentence] [S/M/L]\n...\n\nBefore executing, consider the complexity of this feature:\n\nCOMPLEX (5+ files, architectural decisions, unfamiliar area):\n  \u2192 /skill:joycraft-research \u2014 gather codebase facts before committing to a design\n  \u2192 /skill:joycraft-design \u2014 make architectural decisions explicit\n  \u2192 Then execute specs\n\nMEDIUM (clear scope but non-trivial):\n  \u2192 /skill:joycraft-design \u2014 make key decisions explicit before building\n  \u2192 Then execute specs\n\nSIMPLE (scope is clear, < 5 files, well-understood area):\n  \u2192 Skip to execution\n\nRecommended execution:\n- [Parallel/Sequential/Mixed strategy]\n- Estimated: [N] sessions total\n\nTo execute: Start a fresh session per spec. Each session should:\n1. Read the spec\n2. Implement\n3. Run /skill:joycraft-session-end to capture discoveries\n4. Commit and PR\n\nReady to start?\n\nRun /new before your next step \u2014 your artifacts are saved to files.\n```\n\n**Why:** A fresh session for execution produces better results. The interview session has too much context noise \u2014 a clean session with just the spec is more focused. Research and design catch wrong assumptions before they propagate into specs \u2014 but skip them if the scope is clear and well-understood.\n\nYou can also use `/skill:joycraft-decompose` to re-decompose a brief if the breakdown needs adjustment, or run `/skill:joycraft-interview` first for a lighter brainstorm before committing to the full workflow.\n',
-  "joycraft-optimize.md": '---\nname: joycraft-optimize\ndescription: Audit your Claude Code or Codex session overhead \u2014 harness file sizes, plugins, MCP servers, hooks \u2014 and report actionable recommendations\n---\n\n# Optimize \u2014 Session Overhead Audit\n\nYou are auditing the user\'s AI development session for token overhead. Produce a conversational diagnostic report \u2014 no files created.\n\n## Step 1: Detect Platform\n\nCheck which platform is active:\n- **Claude Code:** Look for `.claude/` directory, `CLAUDE.md`\n- **Codex:** Look for `.agents/` directory, `AGENTS.md`\n\nIf both exist, run both checks. If neither, default to Claude Code checks and note the uncertainty.\n\n## Step 2: Audit Harness Files\n\n### Claude Code Path\n\n1. **CLAUDE.md** \u2014 count lines. Threshold: \u2264200 lines.\n2. **Skill files** \u2014 glob `.claude/skills/**/*.md`. Count lines per file. Threshold: \u2264200 lines each.\n\n### Codex Path\n\n1. **AGENTS.md** \u2014 count lines. Threshold: \u2264200 lines.\n2. **Skill files** \u2014 glob `.agents/skills/**/*.md`. Count lines per file. Threshold: \u2264200 lines each.\n\n## Step 3: Audit Plugins & MCP Servers\n\n### Claude Code Path\n\n1. **Installed plugins** \u2014 read `~/.claude/plugins/installed_plugins.json`. List plugin names and versions. If not found, report "no plugins file found."\n2. **Enabled plugins** \u2014 read `~/.claude/settings.json`, check `enabledPlugins` array. Show enabled vs installed count.\n3. **MCP servers** \u2014 read `~/.claude/settings.json`, count entries under `mcpServers`. List server names.\n\n### Codex Path\n\n1. **Plugin config** \u2014 read `~/.codex/config.toml`. List any plugin toggles. Note: Codex syncs its curated plugin marketplace at startup \u2014 this is a boot cost even if you don\'t use them.\n2. **MCP servers** \u2014 check `~/.codex/config.toml` for MCP server entries. List server names.\n\n## Step 4: Audit Hooks (Claude Code Only)\n\nRead `.claude/settings.json` in the project directory. List all hook definitions under the `hooks` key \u2014 show the event name and command for each.\n\nFor Codex: note "hook auditing not yet supported on Codex."\n\n## Step 5: Report\n\nOrganize findings by category. Use pass/warn indicators:\n\n```\n## Session Overhead Report\n\n### Harness Files\n- CLAUDE.md/AGENTS.md: [N] lines [PASS \u2264200 / WARN >200]\n- Skills: [N] files, [list any over 200 lines]\n\n### Plugins\n- Installed: [N] ([list names])\n- Enabled: [N] of [M] installed\n- [If 0: "No plugins \u2014 zero boot cost from plugins."]\n\n### MCP Servers\n- Count: [N] ([list names])\n- [If 0: "No MCP servers \u2014 zero boot cost from servers."]\n\n### Hooks\n- [N] hook definitions ([list event names])\n\n### Recommendations\n- [Specific, actionable items for anything over threshold]\n- [e.g., "AGENTS.md is 312 lines \u2014 consider splitting reference sections into docs/"]\n- [e.g., "3 MCP servers load at boot \u2014 disable unused ones in config"]\n```\n\n## Step 6: Further Resources\n\nEnd with:\n\n> For deeper token optimization, see:\n> - [Nate B Jones\'s token optimization techniques](https://www.youtube.com/watch?v=bDcgHzCBgmQ)\n> - [OB1 repo](https://github.com/nate-b-j/OB1) \u2014 Heavy File Ingestion skill and stupid button prompt kit\n> - [Joycraft\'s token discipline guide](docs/guides/token-discipline.md)\n\n## Edge Cases\n\n| Scenario | Behavior |\n|----------|----------|\n| Config files don\'t exist | Report "not found" for that check, don\'t error |\n| No plugins installed | Report 0 plugins \u2014 this is good, say so |\n| CLAUDE.md/AGENTS.md exactly 200 lines | PASS \u2014 threshold is \u2264200 |\n| `~/.claude/` or `~/.codex/` not accessible | Skip user-level checks, note limitation |\n| Both platforms detected | Run both audits, report separately |\n',
-  "joycraft-research.md": '---\nname: joycraft-research\ndescription: Produce objective codebase research by isolating question generation from fact-gathering \u2014 subagent sees only questions, never the brief\n---\n\n# Research Codebase for a Feature\n\nYou are producing objective codebase research to inform a future spec or implementation. The key insight: the researching agent must never see the brief or ticket \u2014 only research questions. This prevents opinions from contaminating the facts.\n\n**Guard clause:** If the user doesn\'t provide a brief path or inline description, ask:\n"What feature or change are you researching? Provide a brief path or describe it."\n\n---\n\n## Phase 1: Generate Research Questions\n\nRead the brief and identify which zones of the codebase are relevant. Generate 5-10 research questions that are:\n- **Objective and fact-seeking** \u2014 "How does X work?" not "How should we build X?"\n- **Specific to the codebase**\n- **Answerable by reading code**\n\n**Output path:**\n- If a brief exists at `docs/features/<slug>/brief.md`, write to `docs/features/<slug>/research.md` (per-feature layout).\n- If no brief exists (inline description only), write to `docs/research/YYYY-MM-DD-feature-name.md` (flat layout).\n\nWrite the questions to `docs/features/<slug>/.questions-tmp.md`. **Do NOT include any content from the brief.**\n\n---\n\n## Phase 2: Deploy Research Subagent\n\nUse the `subagent` tool with agent `joycraft-researcher` to perform the research. Pass ONLY the research questions \u2014 never the brief. Build the prompt from the questions file you just wrote.\n\nSubagent prompt:\n```\nYou are researching a codebase to answer specific questions. You have NO context about why these questions are being asked.\n\nRULES:\n- Answer each question with FACTS ONLY: file paths, function signatures, data flows, patterns, dependencies\n- Do NOT recommend, suggest, or opine\n- Do NOT speculate about what should be built\n- If a question cannot be answered, say "No existing code found for this"\n- Search the codebase and read files thoroughly\n- Include code snippets only when essential evidence\n\nQUESTIONS:\n[INSERT_QUESTIONS_HERE]\n\nOUTPUT FORMAT:\n\n# Codebase Research\n\n**Date:** [today]\n**Questions answered:** [N/total]\n\n---\n\n## Q1: [question]\n[Facts only]\n\n## Q2: [question]\n[Facts only]\n```\n\n## Phase 3: Write the Research Document\n\nWrite the subagent\'s response to `docs/features/<slug>/research.md`. Delete the temporary questions file.\n\n### Update the Feature Brief\n\nAfter writing the research document, update the parent brief with a back-reference:\n1. Read `docs/features/<slug>/brief.md`\n2. In the header blockquote (the `>` lines at the top), add or update:\n   `> **Research:** docs/features/<slug>/research.md`\n3. If a `> **Research:**` line already exists, replace it \u2014 do NOT add a duplicate\n4. Write the brief back\n\nPresent:\n```\nResearch complete: docs/features/<slug>/research.md\n\nThis document contains objective facts \u2014 no opinions or recommendations.\n\nRecommended next step:\n- /skill:joycraft-design \u2014 translate research findings into architectural decisions before building\n\nIf the scope is simple (< 5 files, well-understood area, no architectural decisions):\n- /skill:joycraft-decompose \u2014 skip design and break directly into atomic specs\n\nOther options:\n- /skill:joycraft-new-feature \u2014 formalize into a full Feature Brief first\n- Read the research and add corrections manually\n```\n',
-  "joycraft-session-end.md": "---\nname: joycraft-session-end\ndescription: Wrap up a session \u2014 capture discoveries, verify, prepare for PR or next session\n---\n\n# Session Wrap-Up \u2014 Feature Finisher\n\nThis is the **once-per-feature finisher** \u2014 the heavy bookend that runs **once**, when the feature's specs are done, not after every spec. It is the **only validation gate** in the loop and the single place that pushes and opens the PR.\n\n> **Two-tier wrap-up.** The light per-spec step is `/skill:joycraft-spec-done` (status bump `todo \u2192 in-review` + commit, no validation/push/PR \u2014 it runs after each spec). This skill is the heavy counterpart: full validation, consolidate the discovery stubs spec-done left behind, graduate every `in-review` spec to `done`, push, and open the PR. See `docs/reference/spec-status-lifecycle.md` for the `todo \u2192 in-review \u2192 done` lifecycle.\n\nComplete these steps in order.\n\n## 1. Consolidate Discoveries\n\n**Why:** Discoveries are the surprises \u2014 things that weren't in the spec or that contradicted expectations. They prevent future sessions from hitting the same walls.\n\nThis is the **consolidation** pass: `/skill:joycraft-spec-done` may have left terse 2-line discovery **stubs** during the feature (one per surprising spec). Curate and expand those stubs into proper discovery docs now, and capture anything else surprising from the feature as a whole. If any stubs exist at `docs/discoveries/`, consolidate them (merge related ones, expand each into the full format below); then create or update a discovery file at `docs/discoveries/YYYY-MM-DD-topic.md`. Create the `docs/discoveries/` directory if it doesn't exist.\n\nOnly capture what's NOT obvious from the code or git diff:\n- \"We thought X but found Y\" \u2014 assumptions that were wrong\n- \"This API/library behaves differently than documented\" \u2014 external gotchas\n- \"This edge case needs handling in a future spec\" \u2014 deferred work with context\n- \"The approach in the spec didn't work because...\" \u2014 spec-vs-reality gaps\n- Key decisions made during implementation that aren't in the spec\n\n**Do NOT capture:**\n- Files changed (that's the diff)\n- What you set out to do (that's the spec)\n- Step-by-step narrative of the session (nobody re-reads these)\n\nUse this format:\n\n```markdown\n# Discoveries \u2014 [topic]\n\n**Date:** YYYY-MM-DD\n**Spec:** [link to spec if applicable]\n\n## [Discovery title]\n**Expected:** [what we thought would happen]\n**Actual:** [what actually happened]\n**Impact:** [what this means for future work]\n```\n\nIf nothing surprising happened (no stubs, no surprises), skip the discovery file entirely. No discovery is a good sign \u2014 the spec was accurate.\n\n## 1b. Update Context Documents\n\nIf `docs/context/` exists, quickly check whether this session revealed anything about:\n\n- **Production risks** \u2014 did you interact with or learn about production vs staging systems? Update `docs/context/production-map.md`\n- **Wrong assumptions** \u2014 did you assume something that turned out to be false? Update `docs/context/dangerous-assumptions.md`\n- **Key decisions** \u2014 did you make an architectural or tooling choice? Add a row to `docs/context/decision-log.md`\n- **Unwritten rules** \u2014 did you discover a convention or constraint not documented anywhere? Update `docs/context/institutional-knowledge.md`\n\nSkip this if nothing applies. Don't force it \u2014 only update when there's genuine new context.\n\n## 2. Run Validation \u2014 the ONLY validation gate\n\nThis is **mandatory** and it is the **only** validation gate in the loop: `/skill:joycraft-spec-done` deliberately skips validation (it trusts implement's per-spec TDD), so this feature-level run is the single cross-spec safety net. Never skip it.\n\nRun the project's validation commands. Check CLAUDE.md or AGENTS.md for project-specific commands. Common checks:\n\n- Type-check (e.g., `tsc --noEmit`, `mypy`, `cargo check`)\n- Tests (e.g., `npm test`, `pytest`, `cargo test`)\n- Lint (e.g., `eslint`, `ruff`, `clippy`)\n\nFix any failures before proceeding. **If validation fails, stop \u2014 do NOT graduate specs to `done` and do NOT push.**\n\n## 3. Graduate Specs `in-review \u2192 done`\n\nThis step graduates the feature's finished specs to their terminal state. Because session-end runs once at the end, **multiple specs may be waiting** in `in-review` (one per spec the loop completed via `/skill:joycraft-spec-done`). Graduate **all** of them, in **both** systems (the queue JSON and the frontmatter must never disagree):\n\nFor each spec in `docs/features/<slug>/specs/` (or `docs/bugfixes/<area>/` for bugfixes \u2014 scan recursively) whose status is `in-review`:\n\n1. **Queue JSON** \u2014 `joycraft-mark-done <spec-id> --to done <specs-dir>` (the `--to done` graduation; find `<spec-id>` by matching the entry's `file`).\n2. **Frontmatter** \u2014 edit the spec file's YAML `status:` to `done`.\n\nRules:\n- Only graduate specs that are `in-review`. A spec still at `todo` was never started \u2014 **leave it `todo` and report it as remaining** (the feature isn't fully done; see the PR gate in step 5).\n- Never write `done` for work nothing has validated \u2014 this validation run (step 2) is what licenses the graduation. (Once `verify-in-loop` ships, an independent verify performs the `in-review \u2192 done` transition; until then, this step does.)\n- `done` means **verified**, not **merged**. A merged PR is a git fact, never a spec status \u2014 do not invent a `merged` status or any fourth state beyond `todo`/`in-review`/`done`.\n\nIf working from a Feature Brief at `docs/features/<slug>/brief.md`, also check off completed specs in the decomposition table.\n\n## 4. Commit\n\nCommit all changes including the discovery file (if created) and spec status updates. The commit message should reference the spec if applicable.\n\n## 5. Push and PR (if autonomous git is enabled)\n\n**Check CLAUDE.md or AGENTS.md for \"Git Autonomy\" in the Behavioral Boundaries section.** If it says \"STRICTLY ENFORCED\" or the ALWAYS section includes \"Push to feature branches immediately after every commit\":\n\n1. **Push immediately.** Run `git push origin <branch>` \u2014 do not ask, do not hesitate.\n2. **Open a PR if the feature is complete.** The feature is complete when every spec is `done` (none left at `todo`/`in-review`). Check the queue JSON / decomposition table \u2014 if all specs are `done`, run `gh pr create` with a summary of all completed specs. Do not ask first.\n3. **If specs remain (`todo`),** still push. The PR comes when the feature's last spec is graduated.\n\nIf CLAUDE.md or AGENTS.md does NOT have autonomous git rules (or has \"ASK FIRST\" for pushing), ask the user before pushing.\n\n## 6. Report\n\n```\nFeature complete.\n- Feature: [slug]\n- Specs graduated to done: [N] (remaining at todo: [N])\n- Build: [passing / failing]\n- Discoveries: [N consolidated / none]\n- Pushed: [yes / no \u2014 and why not]\n- PR: [opened #N / not yet \u2014 N specs remaining]\n- Next: [what comes after this feature]\n\nRun /new before your next step \u2014 your artifacts are saved to files.\n```\n",
+  "joycraft-new-feature.md": '---\nname: joycraft-new-feature\ndescription: Guided feature development \u2014 interview the user, produce a Feature Brief, then decompose into atomic specs\n---\n\n# New Feature Workflow\n\nYou are starting a new feature. Follow this process in order. Do not skip steps.\n\n## Phase 0: Check for Existing Drafts and In-Flight Features\n\nBefore starting the interview, scan `docs/features/` for existing artifacts the user may want to continue from.\n\n**Skip this phase if:** the user provided a brief path as an argument (they already know what to work from).\n\n**Steps:**\n1. Check if `docs/features/` exists. If not, skip to Phase 1.\n2. List subdirectories. For each `docs/features/<slug>/brief.md`, read the YAML frontmatter at the top.\n3. **Filter by status:** treat each brief as `status: active` unless its frontmatter says otherwise. **Skip** any brief whose `status:` is `shipped`, `deprecated`, or `superseded`. Also skip anything under `docs/archive/` \u2014 those are out-of-scope for new feature work.\n4. Group what you find:\n   - **Drafts** (frontmatter `status: draft`) \u2014 likely from `/skill:joycraft-interview`.\n   - **Active in-flight** (frontmatter `status: active`) \u2014 work the user already started.\n\n5. Present them:\n\n```\nI found existing artifacts in docs/features/:\n\nDrafts:\n- docs/features/<slug>/brief.md (drafted YYYY-MM-DD)\n\nActive features:\n- docs/features/<slug>/brief.md (started YYYY-MM-DD)\n\nWant me to:\n1. **Formalize** a draft into a full Feature Brief\n2. **Continue** an active feature\n3. **Start a new interview** from scratch\n```\n\n6. If user picks formalize/continue: read the full brief, extract context, and jump to Phase 2 with that context pre-filled.\n7. If user picks start fresh, or nothing found: proceed to Phase 1.\n\n## Phase 1: Interview\n\nInterview the user about what they want to build. Let them talk \u2014 your job is to listen, then sharpen.\n\n**Ask about:**\n- What problem does this solve? Who is affected?\n- What does "done" look like?\n- Hard constraints? (business rules, tech limitations, deadlines)\n- What is explicitly NOT in scope? (push hard on this)\n- Edge cases or error conditions?\n- What existing code/patterns should this follow?\n- Testing: existing setup? framework? smoke test budget? lockdown mode desired?\n\n**Interview technique:**\n- Let the user "yap" \u2014 don\'t interrupt their flow\n- Play back your understanding: "So if I\'m hearing you right..."\n- Push toward testable statements: "How would we verify that works?"\n\nKeep asking until you can fill out a Feature Brief.\n\n## Phase 2: Feature Brief\n\nDerive a slug `YYYY-MM-DD-<feature-name>` (today\'s date + kebab-case feature name).\nWrite the Feature Brief to `docs/features/<slug>/brief.md`. Lazy-create the folder if needed.\n\n**Slug derivation:** today\'s date in `YYYY-MM-DD` format, then `-`, then the feature name lower-cased and hyphen-separated. Example: a feature about "Token Discipline" started on 2026-04-06 \u2192 slug `2026-04-06-token-discipline` \u2192 folder `docs/features/2026-04-06-token-discipline/`.\n\n**Why:** The brief is the single source of truth for what we\'re building. It prevents scope creep and gives every spec a shared reference point.\n\nThe brief MUST start with YAML frontmatter \u2014 the 4-field personal schema:\n\n```yaml\n---\nstatus: active\nowner: <resolved name>\ncreated: YYYY-MM-DD\nfeature: <slug>\n---\n```\n\n**Owner resolution:** look up the owner name in this order \u2014 (1) `git config user.name`, (2) value in your auto-memory `joycraft-owner.txt` if present, (3) ask the user once and persist. If you can\'t get a name, leave the field as `<resolved name>` and note it for the user.\n\nIf the brief was formalized from an existing draft, parse the existing draft\'s frontmatter and update `status:` from `draft` to `active`. Never silently overwrite \u2014 if the draft already has body content, preserve it and append/refine rather than replacing.\n\nUse this structure for the body:\n\n```markdown\n# [Feature Name] \u2014 Feature Brief\n\n> **Date:** YYYY-MM-DD\n> **Project:** [project name]\n\n---\n\n## Vision\nWhat are we building and why? The full picture in 2-4 paragraphs.\n\n## User Stories\n- As a [role], I want [capability] so that [benefit]\n\n## Hard Constraints\n- MUST: [constraint that every spec must respect]\n- MUST NOT: [prohibition that every spec must respect]\n\n## Out of Scope\n- NOT: [tempting but deferred]\n\n## Test Strategy\n- **Existing setup:** [framework and tools, or "none yet"]\n- **User expertise:** [comfortable / learning / needs guidance]\n- **Test types:** [smoke, unit, integration, e2e, etc.]\n- **Smoke test budget:** [target time for fast-feedback tests]\n- **Lockdown mode:** [yes/no \u2014 constrain agent to code + tests only]\n\n## Decomposition\n| # | Spec Name | Description | Dependencies | Est. Size |\n|---|-----------|-------------|--------------|-----------|\n| 1 | [verb-object] | [one sentence] | None | [S/M/L] |\n\n## Execution Strategy\n- [ ] Sequential (specs have chain dependencies)\n- [ ] Parallel worktrees (specs are independent)\n- [ ] Mixed\n\n## Success Criteria\n- [ ] [End-to-end behavior 1]\n- [ ] [No regressions in existing features]\n```\n\nIf `docs/templates/FEATURE_BRIEF_TEMPLATE.md` exists, reference it for the full template with additional guidance.\n\nPresent the brief to the user. Focus review on:\n- "Does the decomposition match how you think about this?"\n- "Is anything in scope that shouldn\'t be?"\n- "Are the specs small enough? Can each be described in one sentence?"\n\nIterate until approved.\n\n## Phase 3: Generate Atomic Specs\n\nFor each row in the decomposition table, create a self-contained spec file at `docs/features/<slug>/specs/<spec-name>.md`. Lazy-create the `specs/` subfolder if it doesn\'t exist.\n\n**Why:** Each spec must be understandable WITHOUT reading the Feature Brief. This prevents the "Curse of Instructions" \u2014 no spec should require holding the entire feature in context. Copy relevant context into each spec.\n\nEach spec file MUST start with YAML frontmatter \u2014 the 4-field personal schema:\n\n```yaml\n---\nstatus: active\nowner: <resolved name>\ncreated: YYYY-MM-DD\nfeature: <slug>\n---\n```\n\nWhen listing existing in-flight features in Phase 0, ignore briefs whose `status:` is `shipped`, `deprecated`, or `superseded`. Also ignore anything under `docs/archive/`.\n\nIf `docs/backlog/` items surface during the interview as "deferred work" candidates, ask the user before writing \u2014 never auto-write to `docs/backlog/`.\n\nUse this structure for each spec body:\n\n```markdown\n# [Verb + Object] \u2014 Atomic Spec\n\n> **Parent Brief:** `docs/features/<slug>/brief.md`\n> **Status:** Ready\n> **Date:** YYYY-MM-DD\n> **Estimated scope:** [1 session / N files / ~N lines]\n\n---\n\n## What\nOne paragraph \u2014 what changes when this spec is done?\n\n## Why\nOne sentence \u2014 what breaks or is missing without this?\n\n## Acceptance Criteria\n- [ ] [Observable behavior]\n- [ ] Build passes\n- [ ] Tests pass\n\n## Test Plan\n\n| Acceptance Criterion | Test | Type |\n|---------------------|------|------|\n| [Each AC above] | [What to call/assert] | [unit/integration/e2e] |\n\n**Execution order:**\n1. Write all tests above \u2014 they should fail against current/stubbed code\n2. Run tests to confirm they fail (red)\n3. Implement until all tests pass (green)\n\n**Smoke test:** [Identify the fastest test for iteration feedback]\n\n**Before implementing, verify your test harness:**\n1. Run all tests \u2014 they must FAIL (if they pass, you\'re testing the wrong thing)\n2. Each test calls your actual function/endpoint \u2014 not a reimplementation or the underlying library\n3. Identify your smoke test \u2014 it must run in seconds, not minutes, so you get fast feedback on each change\n\n## Constraints\n- MUST: [hard requirement]\n- MUST NOT: [hard prohibition]\n\n## Affected Files\n| Action | File | What Changes |\n|--------|------|-------------|\n\n## Approach\nStrategy, data flow, key decisions. Name one rejected alternative.\n\n## Edge Cases\n| Scenario | Expected Behavior |\n|----------|------------------|\n```\n\nIf `docs/templates/ATOMIC_SPEC_TEMPLATE.md` exists, reference it for the full template with additional guidance.\n\n## Phase 3.5: Offer to Capture Deferred Items to Backlog\n\nIf during the interview deferred work surfaces (out-of-scope items, "later" features, tangents), ASK the user:\n\n> "This looks like deferred work \u2014 want me to capture it to `docs/backlog/`?"\n\nOnly on user confirmation, write a backlog entry at `docs/backlog/YYYY-MM-DD-<short-name>.md` with backlog frontmatter:\n\n```yaml\n---\nstatus: backlog\nowner: <resolved name>\ncreated: YYYY-MM-DD\nsource: docs/features/<slug>/brief.md\n---\n```\n\n**Never auto-write to `docs/backlog/`.** Every backlog entry is user-confirmed.\n\n## Phase 4: Hand Off for Execution\n\nBefore jumping to execution, consider whether research or design would catch wrong assumptions early:\n\n```\nFeature Brief and [N] atomic specs are ready.\n\nSpecs:\n1. [spec-name] \u2014 [one sentence] [S/M/L]\n2. [spec-name] \u2014 [one sentence] [S/M/L]\n...\n\nBefore executing, consider the complexity of this feature:\n\nCOMPLEX (5+ files, architectural decisions, unfamiliar area):\n  \u2192 /skill:joycraft-research \u2014 gather codebase facts before committing to a design\n  \u2192 /skill:joycraft-design \u2014 make architectural decisions explicit\n  \u2192 Then execute specs\n\nMEDIUM (clear scope but non-trivial):\n  \u2192 /skill:joycraft-design \u2014 make key decisions explicit before building\n  \u2192 Then execute specs\n\nSIMPLE (scope is clear, < 5 files, well-understood area):\n  \u2192 Skip to execution\n\nRecommended execution:\n- [Parallel/Sequential/Mixed strategy]\n- Estimated: [N] sessions total\n\nTo execute: Start a fresh session per spec. Each session should:\n1. Read the spec\n2. Implement\n3. Run /skill:joycraft-session-end to capture discoveries\n4. Commit and PR\n\nReady to start?\n```\n\nEnd with the canonical Handoff block. Include any backlog paths produced as a side effect.\n\n## Recommended Next Steps\n\nNext:\n```bash\n/skill:joycraft-decompose docs/features/<slug>/brief.md\n```\nRun /new first.\n\n**Why:** A fresh session for execution produces better results. The interview session has too much context noise \u2014 a clean session with just the spec is more focused. Research and design catch wrong assumptions before they propagate into specs \u2014 but skip them if the scope is clear and well-understood.\n\nYou can also use `/skill:joycraft-decompose` to re-decompose a brief if the breakdown needs adjustment, or run `/skill:joycraft-interview` first for a lighter brainstorm before committing to the full workflow.\n',
+  "joycraft-optimize.md": '---\nname: joycraft-optimize\ndescription: Audit your Claude Code or Codex session overhead \u2014 harness file sizes, plugins, MCP servers, hooks \u2014 and report actionable recommendations\n---\n\n# Optimize \u2014 Session Overhead Audit\n\nYou are auditing the user\'s AI development session for token overhead. Produce a conversational diagnostic report \u2014 no files created.\n\n## Step 1: Detect Platform\n\nCheck which platform is active:\n- **Claude Code:** Look for `.claude/` directory, `AGENTS.md`\n- **Codex:** Look for `.agents/` directory, `AGENTS.md`\n\nIf both exist, run both checks. If neither, default to Claude Code checks and note the uncertainty.\n\n## Step 2: Audit Harness Files\n\n### Claude Code Path\n\n1. **AGENTS.md** \u2014 count lines. Threshold: \u2264200 lines.\n2. **Skill files** \u2014 glob `.pi/skills/**/*.md`. Count lines per file. Threshold: \u2264200 lines each.\n\n### Codex Path\n\n1. **AGENTS.md** \u2014 count lines. Threshold: \u2264200 lines.\n2. **Skill files** \u2014 glob `.agents/skills/**/*.md`. Count lines per file. Threshold: \u2264200 lines each.\n\n## Step 3: Audit Plugins & MCP Servers\n\n### Claude Code Path\n\n1. **Installed plugins** \u2014 read `~/.claude/plugins/installed_plugins.json`. List plugin names and versions. If not found, report "no plugins file found."\n2. **Enabled plugins** \u2014 read `~/.claude/settings.json`, check `enabledPlugins` array. Show enabled vs installed count.\n3. **MCP servers** \u2014 read `~/.claude/settings.json`, count entries under `mcpServers`. List server names.\n\n### Codex Path\n\n1. **Plugin config** \u2014 read `~/.codex/config.toml`. List any plugin toggles. Note: Codex syncs its curated plugin marketplace at startup \u2014 this is a boot cost even if you don\'t use them.\n2. **MCP servers** \u2014 check `~/.codex/config.toml` for MCP server entries. List server names.\n\n## Step 4: Audit Hooks (Claude Code Only)\n\nRead `.claude/settings.json` in the project directory. List all hook definitions under the `hooks` key \u2014 show the event name and command for each.\n\nFor Codex: note "hook auditing not yet supported on Codex."\n\n## Step 5: Report\n\nOrganize findings by category. Use pass/warn indicators:\n\n```\n## Session Overhead Report\n\n### Harness Files\n- AGENTS.md: [N] lines [PASS \u2264200 / WARN >200]\n- Skills: [N] files, [list any over 200 lines]\n\n### Plugins\n- Installed: [N] ([list names])\n- Enabled: [N] of [M] installed\n- [If 0: "No plugins \u2014 zero boot cost from plugins."]\n\n### MCP Servers\n- Count: [N] ([list names])\n- [If 0: "No MCP servers \u2014 zero boot cost from servers."]\n\n### Hooks\n- [N] hook definitions ([list event names])\n\n### Recommendations\n- [Specific, actionable items for anything over threshold]\n- [e.g., "AGENTS.md is 312 lines \u2014 consider splitting reference sections into docs/"]\n- [e.g., "3 MCP servers load at boot \u2014 disable unused ones in settings.json"]\n```\n\n## Step 6: Further Resources\n\nEnd with:\n\n> For deeper token optimization, see:\n> - [Nate B Jones\'s token optimization techniques](https://www.youtube.com/watch?v=bDcgHzCBgmQ)\n> - [OB1 repo](https://github.com/nate-b-j/OB1) \u2014 Heavy File Ingestion skill and stupid button prompt kit\n> - [Joycraft\'s token discipline guide](docs/guides/token-discipline.md)\n\n## Edge Cases\n\n| Scenario | Behavior |\n|----------|----------|\n| Config files don\'t exist | Report "not found" for that check, don\'t error |\n| No plugins installed | Report 0 plugins \u2014 this is good, say so |\n| AGENTS.md exactly 200 lines | PASS \u2014 threshold is \u2264200 |\n| `~/.claude/` or `~/.codex/` not accessible | Skip user-level checks, note limitation |\n| Both platforms detected | Run both audits, report separately |\n',
+  "joycraft-research.md": '---\nname: joycraft-research\ndescription: Produce objective codebase research by isolating question generation from fact-gathering \u2014 subagent sees only questions, never the brief\n---\n\n# Research Codebase for a Feature\n\nYou are producing objective codebase research to inform a future spec or implementation. The key insight: the researching agent must never see the brief or ticket \u2014 only research questions. This prevents opinions from contaminating the facts.\n\n**Guard clause:** If the user doesn\'t provide a brief path or inline description, ask:\n"What feature or change are you researching? Provide a brief path or describe it."\n\n---\n\n## Phase 1: Generate Research Questions\n\nRead the brief and identify which zones of the codebase are relevant. Generate 5-10 research questions that are:\n- **Objective and fact-seeking** \u2014 "How does X work?" not "How should we build X?"\n- **Specific to the codebase**\n- **Answerable by reading code**\n\n**Output path:**\n- If a brief exists at `docs/features/<slug>/brief.md`, write to `docs/features/<slug>/research.md` (per-feature layout).\n- If no brief exists (inline description only), write to `docs/research/YYYY-MM-DD-feature-name.md` (flat layout).\n\nWrite the questions to `docs/features/<slug>/.questions-tmp.md`. **Do NOT include any content from the brief.**\n\n---\n\n## Phase 2: Deploy Research Subagent\n\nUse the `subagent` tool with agent `joycraft-researcher` to perform the research. Pass ONLY the research questions \u2014 never the brief. Build the prompt from the questions file you just wrote.\n\nSubagent prompt:\n```\nYou are researching a codebase to answer specific questions. You have NO context about why these questions are being asked.\n\nRULES:\n- Answer each question with FACTS ONLY: file paths, function signatures, data flows, patterns, dependencies\n- Do NOT recommend, suggest, or opine\n- Do NOT speculate about what should be built\n- If a question cannot be answered, say "No existing code found for this"\n- Search the codebase and read files thoroughly\n- Include code snippets only when essential evidence\n\nQUESTIONS:\n[INSERT_QUESTIONS_HERE]\n\nOUTPUT FORMAT:\n\n# Codebase Research\n\n**Date:** [today]\n**Questions answered:** [N/total]\n\n---\n\n## Q1: [question]\n[Facts only]\n\n## Q2: [question]\n[Facts only]\n```\n\n## Phase 3: Write the Research Document\n\nWrite the subagent\'s response to `docs/features/<slug>/research.md`. Delete the temporary questions file.\n\n### Update the Feature Brief\n\nAfter writing the research document, update the parent brief with a back-reference:\n1. Read `docs/features/<slug>/brief.md`\n2. In the header blockquote (the `>` lines at the top), add or update:\n   `> **Research:** docs/features/<slug>/research.md`\n3. If a `> **Research:**` line already exists, replace it \u2014 do NOT add a duplicate\n4. Write the brief back\n\nPresent:\n```\nResearch complete: docs/features/<slug>/research.md\n\nThis document contains objective facts \u2014 no opinions or recommendations.\n\nRecommended next step:\n- /skill:joycraft-design \u2014 translate research findings into architectural decisions before building\n\nIf the scope is simple (< 5 files, well-understood area, no architectural decisions):\n- /skill:joycraft-decompose \u2014 skip design and break directly into atomic specs\n\nOther options:\n- /skill:joycraft-new-feature \u2014 formalize into a full Feature Brief first\n- Read the research and add corrections manually\n```\n\n## Phase 4: Reconcile Brief with Findings\n\nYou\'ve just written `docs/features/<slug>/research.md`. Before hand-off, the parent brief at `docs/features/<slug>/brief.md` may now disagree with what you discovered. Re-read it and check each of these sections:\n\n| Brief section | What to look for |\n|---|---|\n| Vision | Did your findings refine or contradict the framing? |\n| Hard Constraints | Are any constraints now obsolete, missing, or refined? |\n| Out of Scope | Did your findings push something in or out of scope? |\n| Decomposition | Are spec counts, names, or dependencies still accurate? |\n| Test Strategy | Do your findings change what or how to test? |\n| Success Criteria | Are the criteria still observable and still match the goal? |\n\n**For each section, choose one:**\n\n- **Edit in place** \u2014 small, mechanical updates: line-number corrections, clarifications, additions consistent with brief intent. No user approval needed.\n- **Diff + stop** \u2014 non-trivial changes: counts flipping, decomposition restructure, scope changes, contradiction with original brief intent. Present a diff of the proposed change, STOP, and wait for user approval before continuing.\n\nIf you make changes, note them at the bottom of `research.md` under a "Brief updates" subsection. If the brief is already in sync, note: "Reconciliation checked, no changes required." If no parent brief exists (feature was described inline), note that and skip this step.\n\n**Why this step exists:** the silent-drift gap. Without reconciliation, the brief and downstream artifacts diverge \u2014 and later decomposition is sized against the stale brief. This feature ("single-source-skills") hit exactly this: brief said "11 clean / 9 dirty" until the research re-audit forced a re-decomposition. Don\'t let it happen again.\n',
+  "joycraft-session-end.md": "---\nname: joycraft-session-end\ndescription: Wrap up a session \u2014 capture discoveries, verify, prepare for PR or next session\n---\n\n# Session Wrap-Up \u2014 Feature Finisher\n\nThis is the **once-per-feature finisher** \u2014 the heavy bookend that runs **once**, when the feature's specs are done, not after every spec. It is the **only validation gate** in the loop and the single place that pushes and opens the PR.\n\n> **Two-tier wrap-up.** The light per-spec step is `joycraft-spec-done` (status bump `todo \u2192 in-review` + commit, no validation/push/PR \u2014 it runs after each spec). This skill is the heavy counterpart: full validation, consolidate the discovery stubs spec-done left behind, graduate every `in-review` spec to `done`, push, and open the PR. See `docs/reference/spec-status-lifecycle.md` for the `todo \u2192 in-review \u2192 done` lifecycle.\n\nComplete these steps in order.\n\n## 1. Consolidate Discoveries\n\n**Why:** Discoveries are the surprises \u2014 things that weren't in the spec or that contradicted expectations. They prevent future sessions from hitting the same walls.\n\nThis is the **consolidation** pass: `joycraft-spec-done` may have left terse 2-line discovery **stubs** during the feature (one per surprising spec). Curate and expand those stubs into proper discovery docs now, and capture anything else surprising from the feature as a whole. If any stubs exist at `docs/discoveries/`, consolidate them (merge related ones, expand each into the full format below); then create or update a discovery file at `docs/discoveries/YYYY-MM-DD-topic.md`. Lazy-create the `docs/discoveries/` directory if it doesn't exist.\n\n(Discoveries stay flat at `docs/discoveries/` rather than per-feature, since they often span features and are read serendipitously rather than via a known path.)\n\nThe discovery file MUST start with YAML frontmatter \u2014 the 4-field personal schema:\n\n```yaml\n---\nstatus: todo\nowner: <resolved name>\ncreated: YYYY-MM-DD\nfeature: <slug-of-related-feature>   # omit if not feature-tied\n---\n```\n\n**Owner resolution:** look up the owner name in this order \u2014 (1) `git config user.name`, (2) value in your auto-memory `joycraft-owner.txt` if present, (3) ask the user once and persist.\n\nOnly capture what's NOT obvious from the code or git diff:\n- \"We thought X but found Y\" \u2014 assumptions that were wrong\n- \"This API/library behaves differently than documented\" \u2014 external gotchas\n- \"This edge case needs handling in a future spec\" \u2014 deferred work with context\n- \"The approach in the spec didn't work because...\" \u2014 spec-vs-reality gaps\n- Key decisions made during implementation that aren't in the spec\n\n**Do NOT capture:**\n- Files changed (that's the diff)\n- What you set out to do (that's the spec)\n- Step-by-step narrative of the session (nobody re-reads these)\n\nUse this format:\n\n```markdown\n# Discoveries \u2014 [topic]\n\n**Date:** YYYY-MM-DD\n**Spec:** [link to spec if applicable]\n\n## [Discovery title]\n**Expected:** [what we thought would happen]\n**Actual:** [what actually happened]\n**Impact:** [what this means for future work]\n```\n\nIf nothing surprising happened, skip the discovery file entirely. No discovery is a good sign \u2014 the spec was accurate.\n\n## 1b. Update Context Documents\n\nIf `docs/context/` exists, quickly check whether this session revealed anything about:\n\n- **Production risks** \u2014 did you interact with or learn about production vs staging systems? \u2192 Update `docs/context/production-map.md`\n- **Wrong assumptions** \u2014 did the agent (or you) assume something that turned out to be false? \u2192 Update `docs/context/dangerous-assumptions.md`\n- **Key decisions** \u2014 did you make an architectural or tooling choice? \u2192 Add a row to `docs/context/decision-log.md`\n- **Unwritten rules** \u2014 did you discover a convention or constraint not documented anywhere? \u2192 Update `docs/context/institutional-knowledge.md`\n\nWhen you UPDATE a context doc, also bump (or add) its YAML frontmatter \u2014 the 2-field shared schema:\n\n```yaml\n---\nlast_updated: YYYY-MM-DD\nlast_updated_by: <resolved name>\n---\n```\n\nIf the file already has the frontmatter, update the `last_updated` and `last_updated_by` fields in place. If it doesn't, prepend a fresh block. Context docs are *shared* artifacts (no single owner) \u2014 the shared schema reflects that.\n\nSkip this if nothing applies. Don't force it \u2014 only update when there's genuine new context.\n\n## 2. Run Validation \u2014 the ONLY validation gate\n\nThis is **mandatory** and it is the **only** validation gate in the loop: `joycraft-spec-done` deliberately skips validation (it trusts implement's per-spec TDD), so this feature-level run is the single cross-spec safety net. Never skip it.\n\nRun the project's validation commands. Check AGENTS.md for project-specific commands. Common checks:\n\n- Type-check (e.g., `tsc --noEmit`, `mypy`, `cargo check`)\n- Tests (e.g., `npm test`, `pytest`, `cargo test`)\n- Lint (e.g., `eslint`, `ruff`, `clippy`)\n\nFix any failures before proceeding. **If validation fails, stop \u2014 do NOT graduate specs to `done` and do NOT push.**\n\n## 3. Graduate Specs `in-review \u2192 done`\n\nThis step graduates the feature's finished specs to their terminal state. Because session-end runs once at the end, **multiple specs may be waiting** in `in-review` (one per spec the loop completed via `joycraft-spec-done`). Graduate **all** of them, in **both** systems (the queue JSON and the frontmatter must never disagree):\n\nFor each spec in `docs/features/<slug>/specs/` (or `docs/bugfixes/<area>/` for bugfixes \u2014 scan recursively) whose status is `in-review`:\n\n1. **Queue JSON** \u2014 `joycraft-mark-done <spec-id> --to done <specs-dir>` (the `--to done` graduation; find `<spec-id>` by matching the entry's `file`).\n2. **Frontmatter** \u2014 edit the spec file's YAML `status:` to `done`.\n\nRules:\n- Only graduate specs that are `in-review`. A spec still at `todo` was never started \u2014 **leave it `todo` and report it as remaining** (the feature isn't fully done; see the PR gate in step 5).\n- Never write `done` for work nothing has validated \u2014 this validation run (step 2) is what licenses the graduation. (Once `verify-in-loop` ships, an independent verify performs the `in-review \u2192 done` transition; until then, this step does.)\n- `done` means **verified**, not **merged**. A merged PR is a git fact, never a spec status \u2014 do not invent a `merged` status or any fourth state beyond `todo`/`in-review`/`done`.\n\nIf working from a Feature Brief at `docs/features/<slug>/brief.md`, also check off completed specs in the decomposition table.\n\n## 4. Commit\n\nCommit all changes including the discovery file (if created) and spec status updates. The commit message should reference the spec if applicable.\n\n## 5. Push and PR (if autonomous git is enabled)\n\n**Check AGENTS.md for \"Git Autonomy\" in the Behavioral Boundaries section.** If it says \"STRICTLY ENFORCED\" or the ALWAYS section includes \"Push to feature branches immediately after every commit\":\n\n1. **Push immediately.** Run `git push origin <branch>` \u2014 do not ask, do not hesitate.\n2. **Open a PR if the feature is complete.** The feature is complete when every spec is `done` (none left at `todo`/`in-review`). Check the queue JSON / decomposition table \u2014 if all specs are `done`, run `gh pr create` with a summary of all completed specs. Do not ask first.\n3. **If specs remain (`todo`),** still push. The PR comes when the feature's last spec is graduated.\n\nIf AGENTS.md does NOT have autonomous git rules (or has \"ASK FIRST\" for pushing), ask the user before pushing.\n\n## 6. Report and Hand Off\n\n```\nFeature complete.\n- Feature: [slug]\n- Specs graduated to done: [N] (remaining at todo: [N])\n- Build: [passing / failing]\n- Discoveries: [N consolidated / none]\n- Pushed: [yes / no \u2014 and why not]\n- PR: [opened #N / not yet \u2014 N specs remaining]\n- Next: [what comes after this feature]\n```\n\nEnd with the canonical Handoff block. Include any discovery and updated-context paths produced.\n\n## Recommended Next Steps\n\nNext:\n```bash\n/skill:joycraft-implement docs/features/<slug>/specs/<next-spec>.md\n```\nRun /new first.\n\nIf all specs in the feature are complete, hand off to a feature-level wrap-up instead (PR review, etc.) \u2014 the Handoff block is just the slash command for whatever the next move is.\n",
   "joycraft-setup.md": '---\nname: joycraft-setup\ndescription: Set up Joycraft and get started on this project -- the first-time entry point. Run this when you\'re configuring your project, onboarding, or asking "where do I begin?" / "how do I set this up?"\n---\n\n# Setup \u2014 The First-Run Door\n\nThis is the obvious starting point for setting up Joycraft on this project. It does no work of its own \u2014 it routes you to the skill that does the real assessment and onboarding.\n\n**Run `/skill:joycraft-tune`.**\n\n`/skill:joycraft-tune` detects your project\'s current harness state, scores it, applies the upgrades it can, and on a first run kicks off the context-onboarding pass for you. That\'s the whole setup flow \u2014 this alias just exists so "set up", "get started", and "first time" lead you there.\n\nDo not re-implement assessment or scoring here; hand off to `/skill:joycraft-tune`.\n',
-  "joycraft-spec-done.md": "---\nname: joycraft-spec-done\ndescription: Lightweight per-spec wrap-up \u2014 bump status to in-review, terse discovery if surprised, commit. Run after each spec in checkpoint/isolated mode; no validation, no push, no PR.\n---\n\n# Spec Done (Lightweight Per-Spec Wrap-Up)\n\nYou just finished implementing **one** atomic spec. This is the fast handshake that runs **once per spec**, before context clears \u2014 the `todo \u2192 in-review` transition in the lifecycle (`docs/reference/spec-status-lifecycle.md`). It is deliberately tiny: it does exactly four things and nothing more.\n\n> **This is NOT session-end.** It does **not** run validation, push, or open a PR. It trusts the TDD you just did in `/skill:joycraft-implement`. The heavy once-per-feature wrap-up (full validation + consolidate discoveries + push + PR) is `/skill:joycraft-session-end`, which runs once at the end of the feature.\n>\n> **On the Pi isolated-mode loop** (`joycraft-implement-loop`), this same four-step logic runs as a fresh-process step after each implement \u2014 the loop calls spec-done between specs and session-end once at the end.\n>\n> **In interactive sessions you usually don't run this by hand:** `/skill:joycraft-implement` performs these four steps itself at the end of every checkpoint/isolated spec. This skill remains the canonical definition of the wrap-up (and the loop's own per-spec step) \u2014 run it manually after ad-hoc work done outside the implement skill, or when an implement run was interrupted before wrapping up.\n\n## Step 1: Bump status to `in-review` \u2014 in BOTH systems\n\nA spec's status lives in two places that must never disagree (the desync this feature exists to kill): the **queue JSON** and the spec's **frontmatter**. Update both to `in-review`.\n\n1. **Queue JSON** \u2014 use the script, not a bespoke `sed`:\n   ```bash\n   joycraft-mark-done <spec-id> --to in-review <specs-dir>\n   ```\n   Find `<spec-id>` by reading `<specs-dir>/.joycraft-spec-queue.json` and matching the entry whose `file` is the spec you just implemented. `<specs-dir>` is the folder containing the spec (e.g. `docs/features/<slug>/specs`). If the spec isn't in the manifest, `joycraft-mark-done` exits non-zero with a clear error \u2014 **surface that error, don't silently skip the bump**.\n2. **Frontmatter** \u2014 edit the spec file's YAML `status:` field to `in-review`.\n\nDo **not** graduate to `done`. The agent never self-certifies \u2014 `done` is reached only by `/skill:joycraft-session-end` (or, later, an independent verify). `spec-done` only ever reaches `in-review`.\n\n## Step 2: Terse discovery stub \u2014 ONLY if something surprised you\n\nDid anything during implementation **contradict the spec** or surprise you (an assumption that was wrong, an external API that behaved differently, an edge case the spec missed)?\n\n- **No** \u2192 skip this step entirely. A spec that went as written needs no discovery. This is the common case.\n- **Yes** \u2192 write a **2-line stub** (not a full discovery doc) at `docs/discoveries/YYYY-MM-DD-topic.md`: one line on what contradicted the spec, one line pointing at the spec/file. `/skill:joycraft-session-end`'s consolidation pass later expands these stubs into proper discovery docs \u2014 keep it terse here.\n\n## Step 3: Commit\n\nCommit the spec's implementation changes plus the status edits (and the stub, if any) with the convention:\n\n```\nspec: <spec-name>\n```\n\nKeep scope disciplined \u2014 commit the spec's changes and its status edits, not unrelated working-tree noise.\n\n## Step 4: Stop\n\nThat's it. **No** validation re-run, **no** push, **no** PR \u2014 those belong to `/skill:joycraft-session-end` at feature end. Hand off and keep the loop moving.\n\n## Recommended Next Steps\n\nIf more specs remain in this feature (checkpoint/isolated mode), continue to the next one:\n\n```\n/skill:joycraft-implement docs/features/<slug>/specs/<next-spec>.md\n```\n\nWhen the feature's last spec is done, run the feature finisher once:\n\n```\n/skill:joycraft-session-end\n```\n\nRun /new before your next step \u2014 your artifacts are saved to files.\n",
-  "joycraft-tune.md": "---\nname: joycraft-tune\ndescription: Assess and upgrade your project's AI development harness \u2014 score 7 dimensions, apply fixes, show path to Level 5\n---\n\n# Tune \u2014 Project Harness Assessment & Upgrade\n\nYou are evaluating and upgrading this project's AI development harness.\n\n## Step 1: Detect Harness State\n\nSearch the codebase for: CLAUDE.md (with meaningful content), `docs/features/<slug>/` (briefs + specs), `docs/bugfixes/<area>/`, `docs/discoveries/`, `docs/context/*.md` fact-docs, `docs/context/reference/` long-form docs, `.agents/skills/`, and test configuration.\n\n## Step 2: Route\n\n- **No harness** (no CLAUDE.md or just a README): Recommend `npx joycraft init` and stop.\n- **Harness exists**: Continue to assessment.\n\n## Step 3: Assess \u2014 Score 7 Dimensions (1-5 scale)\n\nRead CLAUDE.md and explore the project. Score each with specific evidence:\n\n| Dimension | What to Check |\n|-----------|--------------|\n| Spec Quality | `docs/features/<slug>/specs/` (scan recursively; also `docs/bugfixes/<area>/`) \u2014 structured? acceptance criteria? self-contained? |\n| Spec Granularity | Can each spec be done in one session? |\n| Behavioral Boundaries | ALWAYS/ASK FIRST/NEVER sections (or equivalent rules under any heading) |\n| Skills & Hooks | `.agents/skills/` files, hooks config |\n| Documentation | `docs/` structure, templates, referenced from CLAUDE.md. Reward a lean + pointered CLAUDE.md. **Flag a CLAUDE.md exceeding ~200 lines** \u2014 recommend extracting long sections into `docs/context/reference/` and replacing them with a `## Context Map` pointer table. This is advisory only; tune never auto-edits CLAUDE.md. |\n| Knowledge Capture | `docs/discoveries/`, `docs/context/*.md` fact-docs, `docs/context/reference/` long-form docs \u2014 existence AND real content |\n| Testing & Validation | Test framework, CI pipeline, validation commands in CLAUDE.md |\n\nScore 1 = absent, 3 = partially there, 5 = comprehensive. Give credit for substance over format.\n\n## Step 4: Write Assessment\n\nWrite to `docs/joycraft-assessment.md` AND display it. Include: scores table, detailed findings (evidence + gap + recommendation per dimension), and an upgrade plan (up to 5 actions ordered by impact).\n\n## Step 5: Apply Upgrades\n\nApply using three tiers \u2014 do NOT ask per-item permission:\n\n**Tier 1 (silent):** Create missing dirs, install missing skills, copy missing templates, create AGENTS.md.\n\n**Before Tier 2, ask about git autonomy:** Cautious (ask before push/PR) or Autonomous (push + PR without asking)?\n\n**First-run context onboarding:** On a first run (the context layer is empty or absent), invoke `/skill:joycraft-gather-context` for the read-then-offer onboarding pass \u2014 it owns reading existing docs, offering a gap-only interview, and populating `docs/context/` (fact-docs and `docs/context/reference/`). Do NOT run a separate risk interview here; gather is the onboarding path. On a recurring run of an already-populated project, skip this \u2014 gather is the first-run path, not forced every time.\n\nFrom git-autonomy and gather, generate: CLAUDE.md boundary rules, deny patterns configuration. Also recommend a permission mode (`auto` for most; `dontAsk` + allowlist for high-risk).\n\n**Tier 2 (show diff):** Add missing CLAUDE.md sections (Boundaries, Workflow, Key Files). Draft from real codebase content. Append only \u2014 never reformat existing content.\n\n**Tier 3 (confirm first):** Rewriting existing sections, overwriting customized files, suggesting test framework installs.\n\nAfter applying, append to `docs/joycraft-history.md` and show a consolidated upgrade results table.\n\n## Step 6: Show Path to Level 5\n\nShow a tailored roadmap: Level 2-5 table, specific next steps based on actual gaps, and the Level 5 north star (spec queue, autofix, holdout scenarios, self-improving harness).\n\n**Tip:** Run `/skill:joycraft-optimize` to audit your session's token overhead \u2014 plugins, MCP servers, and harness file sizes.\n\n## Edge Cases\n\n- **CLAUDE.md is just a README:** Treat as no harness.\n- **Non-Joycraft skills:** Acknowledge, don't replace.\n- **Rules under non-standard headings:** Give credit for substance.\n- **Previous assessment exists:** Read it first. If nothing to upgrade, say so.\n- **Non-Joycraft content in CLAUDE.md:** Preserve as-is. Only append.\n",
-  "joycraft-verify.md": '---\nname: joycraft-verify\ndescription: Spawn an independent verifier subagent to check an implementation against its spec -- read-only, no code edits, structured pass/fail verdict\n---\n\n# Verify Implementation Against Spec\n\nThe user wants independent verification of an implementation. Your job is to find the relevant spec, extract its acceptance criteria and test plan, then use the `subagent` tool with agent `joycraft-verifier` to check each criterion and produce a structured verdict.\n\n**Why a separate subagent?** Research found that agents reliably skew positive when grading their own work. Separating the agent doing the work from the agent judging it consistently outperforms self-evaluation. The verifier gets a clean context window with no implementation bias.\n\n## Step 1: Find the Spec\n\nIf the user provided a spec path (e.g., `/skill:joycraft-verify docs/features/<slug>/specs/add-widget.md`), use that path directly.\n\nIf no path was provided, scan `docs/features/*/specs/` recursively for spec files (and `docs/bugfixes/<area>/` for bugfixes). Pick the most recently modified `.md` file. If no specs exist, tell the user:\n\n> No specs found under `docs/features/*/specs/` or `docs/bugfixes/`. Please provide a spec path: `/skill:joycraft-verify path/to/spec.md`\n\n## Step 2: Read and Parse the Spec\n\nRead the spec file and extract:\n\n1. **Spec name** -- from the H1 title\n2. **Acceptance Criteria** -- the checklist under the `## Acceptance Criteria` section\n3. **Test Plan** -- the table under the `## Test Plan` section, including any test commands\n4. **Constraints** -- the `## Constraints` section if present\n\nIf the spec has no Acceptance Criteria section, tell the user:\n\n> This spec doesn\'t have an Acceptance Criteria section. Verification needs criteria to check against. Add acceptance criteria to the spec and try again.\n\nIf the spec has no Test Plan section, note this but proceed -- the verifier can still check criteria by reading code and running any available project tests.\n\n## Step 3: Identify Test Commands\n\nLook for test commands in these locations (in priority order):\n\n1. The spec\'s Test Plan section (look for commands in backticks or "Type" column entries like "unit", "integration", "e2e", "build")\n2. The project\'s CLAUDE.md or AGENTS.md (look for test/build commands in the Development Workflow section)\n3. Common defaults based on the project type:\n   - Node.js: `npm test` or `pnpm test --run`\n   - Python: `pytest`\n   - Rust: `cargo test`\n   - Go: `go test ./...`\n\nBuild a list of specific commands the verifier should run.\n\n## Step 4: Deploy the Verifier Subagent\n\nUse the `subagent` tool with agent `joycraft-verifier`. Pass the prompt below, replacing placeholders with the actual content extracted in Steps 2-3.\n\n```\nYou are a QA verifier. Your job is to independently verify an implementation against its spec. You have NO context about how the implementation was done -- you are checking it fresh.\n\nRULES -- these are hard constraints, not suggestions:\n- You may search the codebase and read any file\n- You may RUN these specific test/build commands: [TEST_COMMANDS]\n- You may NOT edit, create, or delete any files\n- You may NOT run commands that modify state (no git commit, no npm install, no file writes)\n- You may NOT install packages or access the network\n- Report what you OBSERVE, not what you expect or hope\n\nSPEC NAME: [SPEC_NAME]\n\nACCEPTANCE CRITERIA:\n[ACCEPTANCE_CRITERIA]\n\nTEST PLAN:\n[TEST_PLAN]\n\nCONSTRAINTS:\n[CONSTRAINTS_OR_NONE]\n\nYOUR TASK:\nFor each acceptance criterion, determine if it PASSES or FAILS based on evidence:\n\n1. Run the test commands listed above. Record the output.\n2. For each acceptance criterion:\n   a. Check if there is a corresponding test and whether it passes\n   b. If no test exists, read the relevant source files to verify the criterion is met\n   c. If the criterion cannot be verified by reading code or running tests, mark it MANUAL CHECK NEEDED\n3. For criteria about build/test passing, actually run the commands and report results.\n\nOUTPUT FORMAT -- you MUST use this exact format:\n\nVERIFICATION REPORT\n\n| # | Criterion | Verdict | Evidence |\n|---|-----------|---------|----------|\n| 1 | [criterion text] | PASS/FAIL/MANUAL CHECK NEEDED | [what you observed] |\n| 2 | [criterion text] | PASS/FAIL/MANUAL CHECK NEEDED | [what you observed] |\n[continue for all criteria]\n\nSUMMARY: X/Y criteria passed. [Z failures need attention. / All criteria verified.]\n\nIf any test commands fail to run (missing dependencies, wrong command, etc.), report the error as evidence for a FAIL verdict on the relevant criterion.\n```\n\n## Step 5: Format and Present the Verdict\n\nTake the subagent\'s response and present it to the user in this format:\n\n```\n## Verification Report -- [Spec Name]\n\n| # | Criterion | Verdict | Evidence |\n|---|-----------|---------|----------|\n| 1 | ... | PASS | ... |\n| 2 | ... | FAIL | ... |\n\n**Overall: X/Y criteria passed.**\n\n[If all passed:]\nAll criteria verified. Ready to commit and open a PR.\n\n[If any failed:]\nN failures need attention. Review the evidence above and fix before proceeding.\n\n[If any MANUAL CHECK NEEDED:]\nN criteria need manual verification -- they can\'t be checked by reading code or running tests alone.\n```\n\n## Step 6: Suggest Next Steps\n\nBased on the verdict:\n\n- **All PASS:** Suggest committing and opening a PR, or running `/skill:joycraft-session-end` to capture discoveries.\n- **Some FAIL:** List the failed criteria and suggest the user fix them, then run `/skill:joycraft-verify` again.\n- **MANUAL CHECK NEEDED items:** Explain what needs human eyes and why automation couldn\'t verify it.\n\n**Do NOT offer to fix failures yourself.** The verifier reports; the human (or implementation agent in a separate turn) decides what to do. This separation is the whole point.\n\n## Edge Cases\n\n| Scenario | Behavior |\n|----------|----------|\n| Spec has no Test Plan | Warn that verification is weaker without a test plan, but proceed by checking criteria through code reading and any available project-level tests |\n| All tests pass but a criterion is not testable | Mark as MANUAL CHECK NEEDED with explanation |\n| Subagent can\'t run tests (missing deps) | Report the error as FAIL evidence |\n| No specs found and no path given | Tell user to provide a spec path or create a spec first |\n| Spec status is "Complete" | Still run verification -- "Complete" means the implementer thinks it\'s done, verification confirms |\n'
+  "joycraft-spec-done.md": "---\nname: joycraft-spec-done\ndescription: Lightweight per-spec wrap-up \u2014 bump status to in-review, terse discovery if surprised, commit. Run after each spec in checkpoint/isolated mode; no validation, no push, no PR.\n---\n\n# Spec Done (Lightweight Per-Spec Wrap-Up)\n\nYou just finished implementing **one** atomic spec. This is the fast handshake that runs **once per spec**, before context clears \u2014 the `todo \u2192 in-review` transition in the lifecycle (`docs/reference/spec-status-lifecycle.md`). It is deliberately tiny: it does exactly four things and nothing more.\n\n> **This is NOT session-end.** It does **not** run validation, push, or open a PR. It trusts the TDD you just did in `joycraft-implement`. The heavy once-per-feature wrap-up (full validation + consolidate discoveries + push + PR) is `joycraft-session-end`, which runs once at the end of the feature.\n>\n> **On the Pi isolated-mode loop** (`joycraft-implement-loop`), this same four-step logic runs as a fresh-process step after each implement \u2014 the loop calls spec-done between specs and session-end once at the end.\n>\n> **Usually you don't run this by hand:** `joycraft-implement` performs these four steps itself at the end of every checkpoint/isolated spec (and `joycraft-implement-feature` drives whole queues). This skill remains the canonical definition of the wrap-up \u2014 run it manually after ad-hoc work done outside the implement skill, or when an implement run was interrupted before wrapping up.\n\n## Step 1: Bump status to `in-review` \u2014 in BOTH systems\n\nA spec's status lives in two places that must never disagree (the desync this feature exists to kill): the **queue JSON** and the spec's **frontmatter**. Update both to `in-review`.\n\n1. **Queue JSON** \u2014 use the script, not a bespoke `sed`:\n   ```bash\n   joycraft-mark-done <spec-id> --to in-review <specs-dir>\n   ```\n   Find `<spec-id>` by reading `<specs-dir>/.joycraft-spec-queue.json` and matching the entry whose `file` is the spec you just implemented. `<specs-dir>` is the folder containing the spec (e.g. `docs/features/<slug>/specs`). If the spec isn't in the manifest, `joycraft-mark-done` exits non-zero with a clear error \u2014 **surface that error, don't silently skip the bump**.\n2. **Frontmatter** \u2014 edit the spec file's YAML `status:` field to `in-review`.\n\nDo **not** graduate to `done`. The agent never self-certifies \u2014 `done` is reached only by `joycraft-session-end` (or, later, an independent verify). `spec-done` only ever reaches `in-review`.\n\n## Step 2: Terse discovery stub \u2014 ONLY if something surprised you\n\nDid anything during implementation **contradict the spec** or surprise you (an assumption that was wrong, an external API that behaved differently, an edge case the spec missed)?\n\n- **No** \u2192 skip this step entirely. A spec that went as written needs no discovery. This is the common case.\n- **Yes** \u2192 write a **2-line stub** (not a full discovery doc) at `docs/discoveries/YYYY-MM-DD-topic.md`: one line on what contradicted the spec, one line pointing at the spec/file. `joycraft-session-end`'s consolidation pass later expands these stubs into proper discovery docs \u2014 keep it terse here.\n\n## Step 3: Commit\n\nCommit the spec's implementation changes plus the status edits (and the stub, if any) with the convention:\n\n```\nspec: <spec-name>\n```\n\nKeep scope disciplined \u2014 commit the spec's changes and its status edits, not unrelated working-tree noise.\n\n## Step 4: Stop\n\nThat's it. **No** validation re-run, **no** push, **no** PR \u2014 those belong to `joycraft-session-end` at feature end. Hand off and keep the loop moving.\n\n## Recommended Next Steps\n\nIf more specs remain in this feature (checkpoint/isolated mode), continue to the next one:\n\n```bash\n/skill:joycraft-implement docs/features/<slug>/specs/<next-spec>.md\n```\n\nWhen the feature's last spec is done, run the feature finisher once:\n\n```bash\n/skill:joycraft-session-end\n```\n\nRun /new before your next step \u2014 your artifacts are saved to files.\n",
+  "joycraft-tune.md": "---\nname: joycraft-tune\ndescription: Assess and upgrade your project's AI development harness \u2014 score 7 dimensions, apply fixes, show path to Level 5\n---\n\n# Tune \u2014 Project Harness Assessment & Upgrade\n\nYou are evaluating and upgrading this project's AI development harness.\n\n## Step 1: Detect Harness State\n\nCheck for: AGENTS.md (with meaningful content), `docs/features/<slug>/` (briefs + specs), `docs/bugfixes/<area>/`, `docs/discoveries/`, `docs/context/*.md` fact-docs, `docs/context/reference/` long-form docs, `.pi/skills/`, and test configuration.\n\n## Step 2: Route\n\n- **No harness** (no AGENTS.md or just a README): Recommend `npx joycraft init` and stop.\n- **Harness exists**: Continue to assessment.\n\n## Step 3: Assess \u2014 Score 7 Dimensions (1-5 scale)\n\nRead AGENTS.md and explore the project. Score each with specific evidence:\n\n| Dimension | What to Check |\n|-----------|--------------|\n| Spec Quality | `docs/features/<slug>/specs/` (scan recursively; also `docs/bugfixes/<area>/`) \u2014 structured? acceptance criteria? self-contained? |\n| Spec Granularity | Can each spec be done in one session? |\n| Behavioral Boundaries | ALWAYS/ASK FIRST/NEVER sections (or equivalent rules under any heading) |\n| Skills & Hooks | `.pi/skills/` files, hooks config |\n| Documentation | `docs/` structure, templates, referenced from AGENTS.md. Reward a lean + pointered AGENTS.md. **Flag a AGENTS.md exceeding ~200 lines** \u2014 recommend extracting long sections into `docs/context/reference/` and replacing them with a `## Context Map` pointer table. This is advisory only; tune never auto-edits AGENTS.md. |\n| Knowledge Capture | `docs/discoveries/`, `docs/context/*.md` fact-docs, `docs/context/reference/` long-form docs \u2014 existence AND real content |\n| Testing & Validation | Test framework, CI pipeline, validation commands in AGENTS.md |\n\nScore 1 = absent, 3 = partially there, 5 = comprehensive. Give credit for substance over format.\n\n## Step 4: Write Assessment\n\nWrite to `docs/skill:joycraft-assessment.md` AND display it. Include: scores table, detailed findings (evidence + gap + recommendation per dimension), and an upgrade plan (up to 5 actions ordered by impact).\n\n## Step 5: Apply Upgrades\n\nApply using three tiers \u2014 do NOT ask per-item permission:\n\n**Tier 1 (silent):** Create missing dirs, install missing skills, copy missing templates, create AGENTS.md.\n\n**Before Tier 2, ask about git autonomy:** Cautious (ask before push/PR) or Autonomous (push + PR without asking)?\n\n**First-run context onboarding:** On a first run (the context layer is empty or absent), invoke `/skill:joycraft-gather-context` for the read-then-offer onboarding pass \u2014 it owns reading existing docs, offering a gap-only interview, and populating `docs/context/` (fact-docs and `docs/context/reference/`). Do NOT run a separate risk interview here; gather is the onboarding path. On a recurring run of an already-populated project, skip this \u2014 gather is the first-run path, not forced every time.\n\nFrom git-autonomy and gather, generate: AGENTS.md boundary rules, `.claude/settings.json` deny patterns. Also recommend a permission mode (`auto` for most; `dontAsk` + allowlist for high-risk).\n\n**Tier 2 (show diff):** Add missing AGENTS.md sections (Boundaries, Workflow, Key Files). Draft from real codebase content. Append only \u2014 never reformat existing content.\n\n**Tier 3 (confirm first):** Rewriting existing sections, overwriting customized files, suggesting test framework installs.\n\nAfter applying, append to `docs/skill:joycraft-history.md` and show a consolidated upgrade results table.\n\n## Step 6: Show Path to Level 5\n\nShow a tailored roadmap: Level 2-5 table, specific next steps based on actual gaps, and the Level 5 north star (spec queue, autofix, holdout scenarios, self-improving harness).\n\n**Tip:** Run `/skill:joycraft-optimize` to audit your session's token overhead \u2014 plugins, MCP servers, and harness file sizes.\n\n## Edge Cases\n\n- **AGENTS.md is just a README:** Treat as no harness.\n- **Non-Joycraft skills:** Acknowledge, don't replace.\n- **Rules under non-standard headings:** Give credit for substance.\n- **Previous assessment exists:** Read it first. If nothing to upgrade, say so.\n- **Non-Joycraft content in AGENTS.md:** Preserve as-is. Only append.\n",
+  "joycraft-verify.md": '---\nname: joycraft-verify\ndescription: Spawn an independent verifier subagent to check an implementation against its spec -- read-only, no code edits, structured pass/fail verdict\n---\n\n# Verify Implementation Against Spec\n\nThe user wants independent verification of an implementation. Your job is to find the relevant spec, extract its acceptance criteria and test plan, then use the `subagent` tool with agent `joycraft-verifier` to check each criterion and produce a structured verdict.\n\n**Why a separate subagent?** Research found that agents reliably skew positive when grading their own work. Separating the agent doing the work from the agent judging it consistently outperforms self-evaluation. The verifier gets a clean context window with no implementation bias.\n\n## Step 1: Find the Spec\n\nIf the user provided a spec path (e.g., `/skill:joycraft-verify docs/features/<slug>/specs/add-widget.md`), use that path directly.\n\nIf no path was provided, scan `docs/features/*/specs/` recursively for spec files (and `docs/bugfixes/<area>/` for bugfixes). Pick the most recently modified `.md` file. If no specs exist, tell the user:\n\n> No specs found under `docs/features/*/specs/` or `docs/bugfixes/`. Please provide a spec path: `/skill:joycraft-verify path/to/spec.md`\n\n## Step 2: Read and Parse the Spec\n\nRead the spec file and extract:\n\n1. **Spec name** -- from the H1 title\n2. **Acceptance Criteria** -- the checklist under the `## Acceptance Criteria` section\n3. **Test Plan** -- the table under the `## Test Plan` section, including any test commands\n4. **Constraints** -- the `## Constraints` section if present\n\nIf the spec has no Acceptance Criteria section, tell the user:\n\n> This spec doesn\'t have an Acceptance Criteria section. Verification needs criteria to check against. Add acceptance criteria to the spec and try again.\n\nIf the spec has no Test Plan section, note this but proceed -- the verifier can still check criteria by reading code and running any available project tests.\n\n## Step 3: Identify Test Commands\n\nLook for test commands in these locations (in priority order):\n\n1. The spec\'s Test Plan section (look for commands in backticks or "Type" column entries like "unit", "integration", "e2e", "build")\n2. The project\'s AGENTS.md (look for test/build commands in the Development Workflow section)\n3. Common defaults based on the project type:\n   - Node.js: `npm test` or `pnpm test --run`\n   - Python: `pytest`\n   - Rust: `cargo test`\n   - Go: `go test ./...`\n\nBuild a list of specific commands the verifier should run.\n\n## Step 4: Deploy the Verifier Subagent\n\nUse the `subagent` tool with agent `joycraft-verifier`. Pass the prompt below, replacing placeholders with the actual content extracted in Steps 2-3.\n\n```\nYou are a QA verifier. Your job is to independently verify an implementation against its spec. You have NO context about how the implementation was done -- you are checking it fresh.\n\nRULES -- these are hard constraints, not suggestions:\n- You may search the codebase and read any file\n- You may RUN these specific test/build commands: [TEST_COMMANDS]\n- You may NOT edit, create, or delete any files\n- You may NOT run commands that modify state (no git commit, no npm install, no file writes)\n- You may NOT install packages or access the network\n- Report what you OBSERVE, not what you expect or hope\n\nSPEC NAME: [SPEC_NAME]\n\nACCEPTANCE CRITERIA:\n[ACCEPTANCE_CRITERIA]\n\nTEST PLAN:\n[TEST_PLAN]\n\nCONSTRAINTS:\n[CONSTRAINTS_OR_NONE]\n\nYOUR TASK:\nFor each acceptance criterion, determine if it PASSES or FAILS based on evidence:\n\n1. Run the test commands listed above. Record the output.\n2. For each acceptance criterion:\n   a. Check if there is a corresponding test and whether it passes\n   b. If no test exists, read the relevant source files to verify the criterion is met\n   c. If the criterion cannot be verified by reading code or running tests, mark it MANUAL CHECK NEEDED\n3. For criteria about build/test passing, actually run the commands and report results.\n\nOUTPUT FORMAT -- you MUST use this exact format:\n\nVERIFICATION REPORT\n\n| # | Criterion | Verdict | Evidence |\n|---|-----------|---------|----------|\n| 1 | [criterion text] | PASS/FAIL/MANUAL CHECK NEEDED | [what you observed] |\n| 2 | [criterion text] | PASS/FAIL/MANUAL CHECK NEEDED | [what you observed] |\n[continue for all criteria]\n\nSUMMARY: X/Y criteria passed. [Z failures need attention. / All criteria verified.]\n\nIf any test commands fail to run (missing dependencies, wrong command, etc.), report the error as evidence for a FAIL verdict on the relevant criterion.\n```\n\n## Step 5: Format and Present the Verdict\n\nTake the subagent\'s response and present it to the user in this format:\n\n```\n## Verification Report -- [Spec Name]\n\n| # | Criterion | Verdict | Evidence |\n|---|-----------|---------|----------|\n| 1 | ... | PASS | ... |\n| 2 | ... | FAIL | ... |\n\n**Overall: X/Y criteria passed.**\n\n[If all passed:]\nAll criteria verified. Ready to commit and open a PR.\n\n[If any failed:]\nN failures need attention. Review the evidence above and fix before proceeding.\n\n[If any MANUAL CHECK NEEDED:]\nN criteria need manual verification -- they can\'t be checked by reading code or running tests alone.\n```\n\n## Step 6: Suggest Next Steps\n\nBased on the verdict:\n\n- **All PASS:** Suggest committing and opening a PR, or running `/skill:joycraft-session-end` to capture discoveries.\n- **Some FAIL:** List the failed criteria and suggest the user fix them, then run `/skill:joycraft-verify` again.\n- **MANUAL CHECK NEEDED items:** Explain what needs human eyes and why automation couldn\'t verify it.\n\n**Do NOT offer to fix failures yourself.** The verifier reports; the human (or implementation agent in a separate turn) decides what to do. This separation is the whole point.\n\n## Edge Cases\n\n| Scenario | Behavior |\n|----------|----------|\n| Spec has no Test Plan | Warn that verification is weaker without a test plan, but proceed by checking criteria through code reading and any available project-level tests |\n| All tests pass but a criterion is not testable | Mark as MANUAL CHECK NEEDED with explanation |\n| Subagent can\'t run tests (missing deps) | Report the error as FAIL evidence |\n| No specs found and no path given | Tell user to provide a spec path or create a spec first |\n| Spec status is "Complete" | Still run verification -- "Complete" means the implementer thinks it\'s done, verification confirms |\n'
 };
 var PI_SCRIPTS = {
   "README.md": "# Joycraft Pi Scripts\n\nBash scripts that form the tool belt for Joycraft's autonomous Pi pipeline.\n\n## Scripts\n\n| Script | Purpose |\n|--------|---------|\n| `joycraft-spec-status` | Read `.joycraft-spec-queue.json` and print a formatted status table (glyphs: `[ ]` todo, `[~]` in-review, `[\u2713]` done) |\n| `joycraft-mark-done` | Transition a spec's status in the queue: `joycraft-mark-done <id> --to <state>` where `<state>` is `todo`, `in-review`, or `done` (omitting `--to` defaults to `in-review`) |\n| `joycraft-next-spec` | Find the next `todo` spec whose dependencies are satisfied (`in-review`/`done`), respecting dependency order |\n| `joycraft-session-end` | Capture discoveries, run validation, and stage changes (the once-per-feature finisher) |\n| `joycraft-implement-loop` | Isolated-mode driver: run a whole feature's queue headlessly, one fresh `pi -p` process per spec |\n\nStatus vocabulary is defined canonically in `docs/reference/spec-status-lifecycle.md` (`todo \u2192 in-review \u2192 done`).\n\n## Usage\n\nAll scripts are designed to be called from the project root.\n\n```bash\n# Check status of all specs (3-glyph table)\n.pi/scripts/joycraft/joycraft-spec-status\n\n# Mark spec #3 in-review (spec-done), or graduate it to done (session-end)\n.pi/scripts/joycraft/joycraft-mark-done 3 --to in-review\n.pi/scripts/joycraft/joycraft-mark-done 3 --to done\n\n# Get path of next spec to implement\n.pi/scripts/joycraft/joycraft-next-spec docs/features/<slug>/specs\n\n# Run the isolated-mode loop over a feature's queue (fresh process per spec)\n.pi/scripts/joycraft/joycraft-implement-loop docs/features/<slug>/specs\n\n# End a feature (validate + stage)\n.pi/scripts/joycraft/joycraft-session-end add-pi-skills\n```\n\n`joycraft-implement-loop` reads the `pi` binary from `PI_BIN` (defaults to `pi`), so it can be tested with a stub and pointed at any Pi build. It is for Pi with a BYO API key or open-weight model \u2014 not a Claude/ChatGPT subscription OAuth (see the ToS note in the north star).\n\n## Dependency\n\nThese scripts parse `.joycraft-spec-queue.json` \u2014 a JSON manifest generated by the `joycraft-decompose` skill. They use only POSIX-compatible `grep` and `sed` (no `jq` dependency).\n\n## Pi Pipeline Flow\n\n```\njoycraft-implement-loop  (one fresh pi -p process per spec)\n  next-spec \u2192 implement \u2192 spec-done (todo\u2192in-review + commit) \u2192 repeat\n                                      \u2193\n                          queue exhausted \u2192 session-end (validate, graduate\n                                            in-review\u2192done, push, PR) once\n```\n",
@@ -675,4 +675,4 @@ export {
   PI_EXTENSIONS,
   PI_AGENTS
 };
-//# sourceMappingURL=chunk-GM2T44P6.js.map
+//# sourceMappingURL=chunk-VCLRPD62.js.map