joycraft 0.5.19 → 0.5.20

package/dist/{chunk-YO3V7RJO.js → chunk-MEPNNJIE.js}

@@ -6,7 +6,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/specs/<feature-or-area>/bugfix-name.md`. Use the relevant feature name or area as the subdirectory (e.g., `auth`, `cli`, `parser`). Create the `docs/specs/<feature-or-area>/` directory if it doesn't exist.\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\nUse this template:\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:\n\n```\nBug fix spec is ready: docs/specs/<feature-or-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```\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-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 in `docs/briefs/`. If 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 worktrees)?"\n\nIterate until the user approves.\n\n## Step 5: Generate Atomic Specs\n\nFor each approved row, create `docs/specs/<feature-name>/spec-name.md`. Derive the feature-name from the brief filename (strip the date prefix and `.md` \u2014 e.g., `2026-04-06-token-discipline.md` \u2192 `token-discipline`). If no brief exists, use a user-provided or inferred feature name (slugified to kebab-case). Create the `docs/specs/<feature-name>/` directory if it doesn\'t exist.\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\nUse this structure:\n\n```markdown\n# [Verb + Object] \u2014 Atomic Spec\n\n> **Parent Brief:** `docs/briefs/YYYY-MM-DD-feature-name.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## 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 6: Recommend Execution Strategy\n\nBased on the dependency graph:\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\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/specs/\n- [N] can run in parallel, [N] are sequential\n- Estimated total: [N] sessions\n\nTo execute:\n- Sequential: Open a session, point Claude at each spec in order\n- Parallel: Use worktrees \u2014 one spec per worktree, merge when done\n- Each session should end with /joycraft-session-end to capture discoveries\n\nReady to start execution?\n```\n\n**Tip:** Run `/clear` before starting the next step. Your artifacts are saved to files \u2014 this conversation context is disposable.\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 in `docs/briefs/`, 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\nCreate `docs/designs/` directory if it doesn\'t exist. Write the design document to `docs/designs/YYYY-MM-DD-feature-name.md`.\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## Step 4: Present and STOP\n\nPresent the design document to the user. Say:\n\n```\nDesign discussion written to docs/designs/YYYY-MM-DD-feature-name.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 proceed to `/joycraft-decompose` or generate specs.** Wait for the human to review, answer open questions, and correct any wrong assumptions. The entire value of this skill is the pause \u2014 it forces a human checkpoint before mistakes propagate.\n\n## After Human Review\n\nOnce the human responds:\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- Only after explicit approval, tell the user: "Design approved. Run `/joycraft-decompose` with this brief to generate atomic specs."\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 `.joycraft-version`. If missing, 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/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/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\nUpdate `docs/joycraft-assessment.md` if it exists \u2014 set the Level 5 score to reflect the new setup.\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 `.joycraft-version`. If missing, 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/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/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, hand off to session-end\ninstructions: 28\n---\n\n# Implement Atomic Spec\n\nYou have one or more atomic spec paths to execute. Your job is to implement each spec using strict TDD \u2014 tests first, confirm they fail, then implement until green.\n\n## Step 1: Parse Arguments\n\nThe user should provide one or more spec paths (e.g., `docs/specs/my-feature/add-widget.md`).\n\nIf no spec path was provided, tell the user:\n\n> No spec path provided. Check `docs/specs/` for available specs, or provide a path like:\n> `/joycraft-implement docs/specs/feature-name/spec-name.md`\n\n## Step 2: Read and Understand the Spec\n\nFor each spec path:\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/specs/<feature-name>/` where the feature name is derived from the brief filename (strip the date prefix and `.md` \u2014 e.g., `2026-04-06-token-discipline.md` \u2192 `token-discipline`).\n- **Affected Files:** The spec's Affected Files table tells you which files to create or modify.\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: Multi-Spec Handling\n\nIf the user provided multiple specs:\n\n1. Execute specs in dependency order (check each spec's frontmatter for dependencies).\n2. After completing each spec, run the full test suite to ensure no regressions.\n3. **Between specs:** Tell the user:\n\n```\nSpec [name] complete. [N] specs remaining.\n```\n\n**Tip:** Run `/clear` before starting the next spec. Your artifacts are saved to files \u2014 this conversation context is disposable.\n\n## Step 6: Hand Off\n\nWhen all specs are implemented and passing:\n\n```\nImplementation complete:\n- Spec(s): [list spec names] \u2014 all Acceptance Criteria met\n- Tests: [N] written, all passing\n- Build: passing\n\nNext steps:\n- Run /joycraft-session-end to capture discoveries and wrap up\n```\n\n**Tip:** Run `/clear` before starting the next step. 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\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\nCreate a draft file at `docs/briefs/YYYY-MM-DD-topic-draft.md`. Create the `docs/briefs/` 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/briefs/YYYY-MM-DD-topic-draft.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```\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**Tip:** Run `/clear` before starting the next step. Your artifacts are saved to files \u2014 this conversation context is disposable.\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",
@@ -252,7 +252,7 @@ var CODEX_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\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/specs/<feature-or-area>/bugfix-name.md`. Use the relevant feature name or area as the subdirectory (e.g., `auth`, `cli`, `parser`). Create the `docs/specs/<feature-or-area>/` directory if it doesn't exist.\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\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/specs/<feature-or-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```\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 in `docs/briefs/`. If 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## Step 5: Generate Atomic Specs\n\nFor each approved row, create `docs/specs/<feature-name>/spec-name.md`. Derive the feature-name from the brief filename (strip the date prefix and `.md` \u2014 e.g., `2026-04-06-token-discipline.md` \u2192 `token-discipline`). If no brief exists, use a user-provided or inferred feature name (slugified to kebab-case). Create the `docs/specs/<feature-name>/` directory 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\nUse this structure:\n\n```markdown\n# [Verb + Object] \u2014 Atomic Spec\n\n> **Parent Brief:** `docs/briefs/YYYY-MM-DD-feature-name.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## 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 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\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/specs/\n- [N] can run in parallel, [N] are sequential\n- Estimated total: [N] sessions\n\nTo execute:\n- Sequential: Open a session, point at each spec in order\n- Parallel: One spec per branch, merge when done\n- Each session should end with $joycraft-session-end to capture discoveries\n\nReady to start execution?\n```\n\n**Tip:** Run `/new` before starting the next step. Your artifacts are saved to files \u2014 this conversation context is disposable.\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 in `docs/briefs/`, 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\nCreate `docs/designs/` directory if it doesn\'t exist. Write to `docs/designs/YYYY-MM-DD-feature-name.md`.\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## Step 4: Present and STOP\n\nPresent the design document. Say:\n```\nDesign discussion written to docs/designs/YYYY-MM-DD-feature-name.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-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 `.joycraft-version`. If missing, 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/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/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\nUpdate `docs/joycraft-assessment.md` if it exists -- set the Level 5 score to reflect the new setup.\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 `.joycraft-version`. If missing, 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/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/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 one or more atomic spec paths to execute. Your job is to implement each spec using strict TDD \u2014 tests first, confirm they fail, then implement until green.\n\n## Step 1: Parse Arguments\n\nThe user should provide one or more spec paths (e.g., `docs/specs/my-feature/add-widget.md`).\n\nIf no spec path was provided, tell the user:\n\n> No spec path provided. Check `docs/specs/` for available specs, or provide a path like:\n> `$joycraft-implement docs/specs/feature-name/spec-name.md`\n\n## Step 2: Read and Understand the Spec\n\nFor each spec path:\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/specs/<feature-name>/` where the feature name is derived from the brief filename (strip the date prefix and `.md` \u2014 e.g., `2026-04-06-token-discipline.md` \u2192 `token-discipline`).\n- **Affected Files:** The spec's Affected Files table tells you which files to create or modify.\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: Multi-Spec Handling\n\nIf the user provided multiple specs:\n\n1. Execute specs in dependency order (check each spec's frontmatter for dependencies).\n2. After completing each spec, run the full test suite to ensure no regressions.\n3. **Between specs:** Tell the user:\n\n```\nSpec [name] complete. [N] specs remaining.\n```\n\n**Tip:** Run `/new` before starting the next spec. Your artifacts are saved to files \u2014 this conversation context is disposable.\n\n## Step 6: Hand Off\n\nWhen all specs are implemented and passing:\n\n```\nImplementation complete:\n- Spec(s): [list spec names] \u2014 all Acceptance Criteria met\n- Tests: [N] written, all passing\n- Build: passing\n\nNext steps:\n- Run $joycraft-session-end to capture discoveries and wrap up\n```\n\n**Tip:** Run `/new` before starting the next step. 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/briefs/YYYY-MM-DD-topic-draft.md`. Create the `docs/briefs/` 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/briefs/YYYY-MM-DD-topic-draft.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```\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**Tip:** Run `/new` before starting the next step. Your artifacts are saved to files \u2014 this conversation context is disposable.\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",
@@ -269,4 +269,4 @@ export {
   TEMPLATES,
   CODEX_SKILLS
 };
-//# sourceMappingURL=chunk-YO3V7RJO.js.map
+//# sourceMappingURL=chunk-MEPNNJIE.js.map