joycraft 0.5.13 → 0.5.15

package/dist/{chunk-4RGMUQQZ.js → chunk-JXSFWGIN.js}

@@ -2,513 +2,390 @@
 
 // src/bundled-files.ts
 var SKILLS = {
-  "joycraft-decompose.md": `---
-name: joycraft-decompose
-description: Break a feature brief into atomic specs \u2014 small, testable, independently executable units
-instructions: 32
+  "joycraft-add-fact.md": `---
+name: joycraft-add-fact
+description: Capture a project fact and route it to the correct context document -- production map, dangerous assumptions, decision log, institutional knowledge, or troubleshooting
+instructions: 38
 ---
 
-# Decompose Feature into Atomic Specs
-
-You 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.
+# Add Fact
 
-## Step 1: Verify the Brief Exists
+The 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 CLAUDE.md boundary rule.
 
-Look for a Feature Brief in \`docs/briefs/\`. If one doesn't exist yet, tell the user:
+## Step 1: Get the Fact
 
-> 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.
+If the user already provided the fact (e.g., \`/joycraft-add-fact the staging DB resets every Sunday\`), use it directly.
 
-If 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.
+If not, ask: "What fact do you want to capture?" -- then wait for their response.
 
-## Step 2: Identify Natural Boundaries
+If the user provides multiple facts at once, process each one separately through all the steps below, then give a combined confirmation at the end.
 
-**Why:** Good boundaries make specs independently testable and committable. Bad boundaries create specs that can't be verified without other specs also being done.
+## Step 2: Classify the Fact
 
-Read the brief (or description) and identify natural split points:
+Route the fact to one of these 5 context documents based on its content:
 
-- **Data layer changes** (schemas, types, migrations) \u2014 always a separate spec
-- **Pure functions / business logic** \u2014 separate from I/O
-- **UI components** \u2014 separate from data fetching
-- **API endpoints / route handlers** \u2014 separate from business logic
-- **Test infrastructure** (mocks, fixtures, helpers) \u2014 can be its own spec if substantial
-- **Configuration / environment** \u2014 separate from code changes
+### \`docs/context/production-map.md\`
+The fact is about **infrastructure, services, environments, URLs, endpoints, credentials, or what is safe/unsafe to touch**.
+- Signal words: "production", "staging", "endpoint", "URL", "database", "service", "deployed", "hosted", "credentials", "secret", "environment"
+- Examples: "The staging DB is at postgres://staging.example.com", "We use Vercel for the frontend and Railway for the API"
 
-Ask yourself: "Can this piece be committed and tested without the other pieces existing?" If yes, it's a good boundary.
+### \`docs/context/dangerous-assumptions.md\`
+The fact is about **something an AI agent might get wrong -- a false assumption that leads to bad outcomes**.
+- Signal words: "assumes", "might think", "but actually", "looks like X but is Y", "not what it seems", "trap", "gotcha"
+- Examples: "The \`users\` table looks like a test table but it's production", "Deleting a workspace doesn't delete the billing subscription"
 
-## Step 3: Build the Decomposition Table
+### \`docs/context/decision-log.md\`
+The fact is about **an architectural or tooling choice and why it was made**.
+- Signal words: "decided", "chose", "because", "instead of", "we went with", "the reason we use", "trade-off"
+- Examples: "We chose SQLite over Postgres because this runs on embedded devices", "We use pnpm instead of npm for workspace support"
 
-For each atomic spec, define:
+### \`docs/context/institutional-knowledge.md\`
+The fact is about **team conventions, unwritten rules, organizational context, or who owns what**.
+- Signal words: "convention", "rule", "always", "never", "team", "process", "review", "approval", "owns", "responsible"
+- Examples: "The design team reviews all color changes", "We never deploy on Fridays", "PR titles must start with the ticket number"
 
-| # | Spec Name | Description | Dependencies | Size |
-|---|-----------|-------------|--------------|------|
+### \`docs/context/troubleshooting.md\`
+The fact is about **diagnostic knowledge -- when X happens, do Y (or don't do Z)**.
+- Signal words: "when", "fails", "error", "if you see", "stuck", "broken", "fix", "workaround", "before trying", "reboot", "restart", "reset"
+- Examples: "If Wi-Fi disconnects during flash, wait and retry -- don't switch networks", "When tests fail with ECONNREFUSED, check if Docker is running"
 
-**Rules:**
-- Each spec name is \`verb-object\` format (e.g., \`add-terminal-detection\`, \`extract-prompt-module\`)
-- Each description is ONE sentence \u2014 if you need two, the spec is too big
-- Dependencies reference other spec numbers \u2014 keep the dependency graph shallow
-- More than 2 dependencies on a single spec = it's too big, split further
-- Aim for 3-7 specs per feature. Fewer than 3 = probably not decomposed enough. More than 10 = the feature brief is too big
+### Ambiguous Facts
 
-## Step 4: Present and Iterate
+If 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.
 
-Show the decomposition table to the user. Ask:
-1. "Does this breakdown match how you think about this feature?"
-2. "Are there any specs that feel too big or too small?"
-3. "Should any of these run in parallel (separate worktrees)?"
+## Step 3: Ensure the Target Document Exists
 
-Iterate until the user approves.
+1. If \`docs/context/\` does not exist, create the directory.
+2. 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:
 
-## Step 5: Generate Atomic Specs
+For **production-map.md**:
+\`\`\`markdown
+# Production Map
 
-For each approved row, create \`docs/specs/YYYY-MM-DD-spec-name.md\`. Create the \`docs/specs/\` directory if it doesn't exist.
+> What's real, what's staging, what's safe to touch.
 
-**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.
+## Services
 
-Use this structure:
+| Service | Environment | URL/Endpoint | Impact if Corrupted |
+|---------|-------------|-------------|-------------------|
+\`\`\`
 
+For **dangerous-assumptions.md**:
 \`\`\`markdown
-# [Verb + Object] \u2014 Atomic Spec
+# Dangerous Assumptions
 
-> **Parent Brief:** \`docs/briefs/YYYY-MM-DD-feature-name.md\` (or "standalone")
-> **Status:** Ready
-> **Date:** YYYY-MM-DD
-> **Estimated scope:** [1 session / N files / ~N lines]
+> Things the AI agent might assume that are wrong in this project.
 
----
+## Assumptions
 
-## What
-One paragraph \u2014 what changes when this spec is done?
+| Agent Might Assume | But Actually | Impact If Wrong |
+|-------------------|-------------|----------------|
+\`\`\`
 
-## Why
-One sentence \u2014 what breaks or is missing without this?
+For **decision-log.md**:
+\`\`\`markdown
+# Decision Log
 
-## Acceptance Criteria
-- [ ] [Observable behavior]
-- [ ] Build passes
-- [ ] Tests pass
+> Why choices were made, not just what was chosen.
 
-## Test Plan
+## Decisions
 
-| Acceptance Criterion | Test | Type |
-|---------------------|------|------|
-| [Each AC above] | [What to call/assert] | [unit/integration/e2e] |
+| Date | Decision | Why | Alternatives Rejected | Revisit When |
+|------|----------|-----|----------------------|-------------|
+\`\`\`
 
-**Execution order:**
-1. Write all tests above \u2014 they should fail against current/stubbed code
-2. Run tests to confirm they fail (red)
-3. Implement until all tests pass (green)
+For **institutional-knowledge.md**:
+\`\`\`markdown
+# Institutional Knowledge
 
-**Smoke test:** [Identify the fastest test for iteration feedback]
+> Unwritten rules, team conventions, and organizational context.
 
-**Before implementing, verify your test harness:**
-1. Run all tests \u2014 they must FAIL (if they pass, you're testing the wrong thing)
-2. Each test calls your actual function/endpoint \u2014 not a reimplementation or the underlying library
-3. Identify your smoke test \u2014 it must run in seconds, not minutes, so you get fast feedback on each change
+## Team Conventions
 
-## Constraints
-- MUST: [hard requirement]
-- MUST NOT: [hard prohibition]
+- (none yet)
+\`\`\`
 
-## Affected Files
-| Action | File | What Changes |
-|--------|------|-------------|
+For **troubleshooting.md**:
+\`\`\`markdown
+# Troubleshooting
 
-## Approach
-Strategy, data flow, key decisions. Name one rejected alternative.
+> What to do when things go wrong for non-code reasons.
 
-## Edge Cases
-| Scenario | Expected Behavior |
-|----------|------------------|
+## Common Failures
+
+| When This Happens | Do This | Don't Do This |
+|-------------------|---------|---------------|
 \`\`\`
 
-If \`docs/templates/ATOMIC_SPEC_TEMPLATE.md\` exists, reference it for the full template with additional guidance.
+## Step 4: Read the Target Document
 
-Fill 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.
+Read the target document to understand its current structure. Note:
+- Which section to append to
+- Whether it uses tables or lists
+- The column format if it's a table
 
-## Step 6: Recommend Execution Strategy
+## Step 5: Append the Fact
 
-Based on the dependency graph:
-- **Independent specs** \u2014 "These can run in parallel worktrees"
-- **Sequential specs** \u2014 "Execute these in order: 1 -> 2 -> 4"
-- **Mixed** \u2014 "Start specs 1 and 3 in parallel. After 1 completes, start 2."
+Add the fact to the appropriate section of the target document. Match the existing format exactly:
 
-Update the Feature Brief's Execution Strategy section with the plan (if a brief exists).
+- **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.
+- **List-based documents** (institutional-knowledge): Add a new list item (\`- \`) to the most appropriate section.
 
-## Step 7: Hand Off
+Remove 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.
+
+**Append only. Never modify or remove existing real content.**
+
+## Step 6: Evaluate CLAUDE.md Boundary Rule
+
+Decide whether the fact also warrants a rule in CLAUDE.md's behavioral boundaries:
+
+**Add a CLAUDE.md rule if the fact:**
+- Describes something that should ALWAYS or NEVER be done
+- Could cause real damage if violated (data loss, broken deployments, security issues)
+- Is a hard constraint that applies across all work, not just a one-time note
+
+**Do NOT add a CLAUDE.md rule if the fact is:**
+- Purely informational (e.g., "staging DB is at this URL")
+- A one-time decision that's already captured
+- A diagnostic tip rather than a prohibition
+
+If a rule is warranted, read CLAUDE.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.
+
+## Step 7: Confirm
+
+Report what you did in this format:
 
-Tell the user:
 \`\`\`
-Decomposition complete:
-- [N] atomic specs created in docs/specs/
-- [N] can run in parallel, [N] are sequential
-- Estimated total: [N] sessions
+Added to [document name]:
+  [summary of what was added]
 
-To execute:
-- Sequential: Open a session, point Claude at each spec in order
-- Parallel: Use worktrees \u2014 one spec per worktree, merge when done
-- Each session should end with /joycraft-session-end to capture discoveries
+[If CLAUDE.md was also updated:]
+Added CLAUDE.md rule:
+  [ALWAYS/ASK FIRST/NEVER]: [rule text]
 
-Ready to start execution?
+[If the fact was ambiguous:]
+Routed to [chosen doc] -- move to [alternative doc] if this is more about [alternative category description].
 \`\`\`
 `,
-  "joycraft-implement-level5.md": `---
-name: joycraft-implement-level5
-description: Set up Level 5 autonomous development \u2014 autofix loop, holdout scenario testing, and scenario evolution from specs
-instructions: 35
+  "joycraft-bugfix.md": `---
+name: joycraft-bugfix
+description: Structured bug fix workflow \u2014 triage, diagnose, discuss with user, write a focused spec, hand off for implementation
+instructions: 32
 ---
 
-# Implement Level 5 \u2014 Autonomous Development Loop
+# Bug Fix Workflow
 
-You 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.
+You are fixing a bug. Follow this process in order. Do not skip steps.
 
-## Before You Begin
+**Guard clause:** If this is clearly a new feature, redirect to \`/joycraft-new-feature\` and stop.
 
-Check prerequisites:
+---
 
-1. **Project must be initialized.** Look for \`.joycraft-version\`. If missing, tell the user to run \`npx joycraft init\` first.
-2. **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.
-3. **Git repo with GitHub remote.** This setup requires GitHub Actions. Check for \`.git/\` and a GitHub remote.
+## Phase 1: Triage
 
-If prerequisites aren't met, explain what's needed and stop.
+Establish 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.
 
-## Step 1: Explain What Level 5 Means
+**Done when:** You can describe the symptom in one sentence.
 
-Tell the user:
+---
 
-> Level 5 is the autonomous loop. When you push specs, three things happen automatically:
->
-> 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.
-> 2. **Autofix** \u2014 When CI fails on a PR, Claude Code automatically attempts a fix (up to 3 times).
-> 3. **Holdout validation** \u2014 When CI passes, your scenarios repo runs behavioral tests against the PR. Results post as PR comments.
->
-> 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.
+## Phase 2: Diagnose
 
-## Step 2: Gather Configuration
+Find 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.
 
-Ask these questions **one at a time**:
+**Done when:** You can explain what's wrong, why, and where in 2-3 sentences.
 
-### Question 1: Scenarios repo name
+---
 
-> What should we call your scenarios repo? It'll be a private repo that holds your holdout tests.
->
-> Default: \`{current-repo-name}-scenarios\`
+## Phase 3: Discuss
 
-Accept the default or the user's choice.
-
-### Question 2: GitHub App
-
-> 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:
->
-> 1. Go to https://github.com/settings/apps/new
-> 2. Give it a name (e.g., "My Project Autofix")
-> 3. Uncheck "Webhook > Active" (not needed)
-> 4. Under **Repository permissions**, set:
->    - **Contents**: Read & Write
->    - **Pull requests**: Read & Write
->    - **Actions**: Read & Write
-> 5. Click **Create GitHub App**
-> 6. Note the **App ID** from the settings page
-> 7. Scroll to **Private keys** > click **Generate a private key** > save the \`.pem\` file
-> 8. Click **Install App** in the left sidebar > install it on your repo
->
-> What's your App ID?
-
-## Step 3: Run init-autofix
-
-Run the CLI command with the gathered configuration:
-
-\`\`\`bash
-npx joycraft init-autofix --scenarios-repo {name} --app-id {id}
-\`\`\`
-
-Review the output with the user. Confirm files were created.
-
-## Step 4: Walk Through Secret Configuration
-
-Guide the user step by step:
-
-### 4a: Add Secrets to Main Repo
-
-> You should already have the \`.pem\` file from when you created the app in Step 2.
-
-> Go to your repo's Settings > Secrets and variables > Actions, and add:
-> - \`JOYCRAFT_APP_PRIVATE_KEY\` \u2014 paste the contents of your \`.pem\` file
-> - \`ANTHROPIC_API_KEY\` \u2014 your Anthropic API key
-
-### 4b: Create the Scenarios Repo
-
-> Create the private scenarios repo:
-> \`\`\`bash
-> gh repo create {scenarios-repo-name} --private
-> \`\`\`
->
-> Then copy the scenario templates into it:
-> \`\`\`bash
-> cp -r docs/templates/scenarios/* ../{scenarios-repo-name}/
-> cd ../{scenarios-repo-name}
-> git add -A && git commit -m "init: scaffold scenarios repo from Joycraft"
-> git push
-> \`\`\`
-
-### 4c: Add Secrets to Scenarios Repo
-
-> The scenarios repo also needs the App private key:
-> - \`JOYCRAFT_APP_PRIVATE_KEY\` \u2014 same \`.pem\` file as the main repo
-> - \`ANTHROPIC_API_KEY\` \u2014 same key (needed for scenario generation)
-
-## Step 5: Verify Setup
-
-Help the user verify everything is wired correctly:
-
-1. **Check workflow files exist:** \`ls .github/workflows/autofix.yml .github/workflows/scenarios-dispatch.yml .github/workflows/spec-dispatch.yml .github/workflows/scenarios-rerun.yml\`
-2. **Check scenario templates were copied:** Verify the scenarios repo has \`example-scenario.test.ts\`, \`workflows/run.yml\`, \`workflows/generate.yml\`, \`prompts/scenario-agent.md\`
-3. **Check the App ID is correct** in the workflow files (not still a placeholder)
+Present findings to the user BEFORE writing any code or spec:
+1. **Symptom** \u2014 confirm it matches what they see
+2. **Root cause** \u2014 specific file(s) and line(s)
+3. **Proposed fix** \u2014 what changes, where
+4. **Risk** \u2014 side effects? scope?
 
-## Step 6: Update CLAUDE.md
+Ask: "Does this match? Comfortable with this approach?" If large/risky, suggest decomposing into multiple specs.
 
-If the project's CLAUDE.md doesn't already have an "External Validation" section, add one:
+**Done when:** User agrees with the diagnosis and fix direction.
 
-> ## External Validation
->
-> This project uses holdout scenario tests in a separate private repo.
->
-> ### NEVER
-> - Access, read, or reference the scenarios repo
-> - Mention scenario test names or contents
-> - Modify the scenarios dispatch workflow to leak test information
->
-> The scenarios repo is deliberately invisible to you. This is the holdout guarantee.
+---
 
-## Step 7: First Test (Optional)
+## Phase 4: Spec the Fix
 
-If the user wants to test the loop:
+Write 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.
 
-> Want to do a quick test? Here's how:
->
-> 1. Write a simple spec in \`docs/specs/\` and push to main \u2014 this triggers scenario generation
-> 2. Create a PR with a small change \u2014 when CI passes, scenarios will run
-> 3. Watch for the scenario test results as a PR comment
->
-> Or deliberately break something in a PR to test the autofix loop.
+**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.
 
-## Step 8: Summary
+Use this template:
 
-Print a summary of what was set up:
+\`\`\`markdown
+# Fix [Bug Description] \u2014 Bug Fix Spec
 
-> **Level 5 is live.** Here's what's running:
->
-> | Trigger | What Happens |
-> |---------|-------------|
-> | Push specs to \`docs/specs/\` | Scenario agent writes holdout tests |
-> | PR fails CI | Claude autofix attempts (up to 3x) |
-> | PR passes CI | Holdout scenarios run against PR |
-> | Scenarios update | Open PRs re-tested with latest scenarios |
->
-> Your scenarios repo: \`{name}\`
-> Your coding agent cannot see those tests. The holdout wall is intact.
+> **Parent Brief:** none (bug fix)
+> **Issue/Error:** [error message, issue link, or symptom description]
+> **Status:** Ready
+> **Date:** YYYY-MM-DD
+> **Estimated scope:** [1 session / N files / ~N lines]
 
-Update \`docs/joycraft-assessment.md\` if it exists \u2014 set the Level 5 score to reflect the new setup.
-`,
-  "joycraft-interview.md": `---
-name: joycraft-interview
-description: Brainstorm freely about what you want to build \u2014 yap, explore ideas, and get a structured summary you can use later
-instructions: 18
 ---
 
-# Interview \u2014 Idea Exploration
+## Bug
 
-You 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.
+What is broken? Describe the symptom the user experiences.
 
-## How to Run the Interview
+## Root Cause
 
-### 1. Open the Floor
+What is wrong in the code and why? Name the specific file(s) and line(s).
 
-Start with something like:
-"What are you thinking about building? Just talk \u2014 I'll listen and ask questions as we go."
+## Fix
 
-Let the user talk freely. Do not interrupt their flow. Do not push toward structure yet.
+What changes will fix this? Be specific \u2014 describe the code change, not just "fix the bug."
 
-### 2. Ask Clarifying Questions
+## Acceptance Criteria
 
-As they talk, weave in questions naturally \u2014 don't fire them all at once:
+- [ ] [The bug no longer occurs \u2014 describe the correct behavior]
+- [ ] [No regressions in related functionality]
+- [ ] Build passes
+- [ ] Tests pass
 
-- **What problem does this solve?** Who feels the pain today?
-- **What does "done" look like?** If this worked perfectly, what would a user see?
-- **What are the constraints?** Time, tech, team, budget \u2014 what boxes are we in?
-- **What's NOT in scope?** What's tempting but should be deferred?
-- **What are the edge cases?** What could go wrong? What's the weird input?
-- **What exists already?** Are we building on something or starting fresh?
+## Test Plan
 
-### 3. Play Back Understanding
+| Acceptance Criterion | Test | Type |
+|---------------------|------|------|
+| [Bug no longer occurs] | [Test that reproduces the bug, then verifies the fix] | [unit/integration/e2e] |
+| [No regressions] | [Existing tests still pass, or new regression test] | [unit/integration] |
 
-After the user has gotten their ideas out, reflect back:
-"So if I'm hearing you right, you want to [summary]. The core problem is [X], and done looks like [Y]. Is that right?"
+**Execution order:**
+1. Write a test that reproduces the bug \u2014 it should FAIL (red)
+2. Run the test to confirm it fails
+3. Apply the fix
+4. Run the test to confirm it passes (green)
+5. Run the full test suite to check for regressions
 
-Let them correct and refine. Iterate until they say "yes, that's it."
+**Smoke test:** [The bug reproduction test \u2014 fastest way to verify the fix works]
 
-### 4. Write a Draft Brief
+**Before implementing, verify your test harness:**
+1. Run the reproduction test \u2014 it must FAIL (if it passes, you're not testing the actual bug)
+2. The test must exercise your actual code \u2014 not a reimplementation or mock
+3. Identify your smoke test \u2014 it must run in seconds, not minutes
 
-Create a draft file at \`docs/briefs/YYYY-MM-DD-topic-draft.md\`. Create the \`docs/briefs/\` directory if it doesn't exist.
+## Constraints
 
-Use this format:
+- MUST: [any hard requirements for the fix]
+- MUST NOT: [any prohibitions \u2014 e.g., don't change the public API]
 
-\`\`\`markdown
-# [Topic] \u2014 Draft Brief
+## Affected Files
 
-> **Date:** YYYY-MM-DD
-> **Status:** DRAFT
-> **Origin:** /joycraft-interview session
+| Action | File | What Changes |
+|--------|------|-------------|
 
----
+## Edge Cases
 
-## The Idea
-[2-3 paragraphs capturing what the user described \u2014 their words, their framing]
+| Scenario | Expected Behavior |
+|----------|------------------|
+\`\`\`
 
-## Problem
-[What pain or gap this addresses]
+**For trivial bugs:** The spec will be short. That's fine \u2014 the structure is the point, not the length.
 
-## What "Done" Looks Like
-[The user's description of success \u2014 observable outcomes]
+**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.
 
-## Constraints
-- [constraint 1]
-- [constraint 2]
+---
 
-## Open Questions
-- [things that came up but weren't resolved]
-- [decisions that need more thought]
+## Phase 5: Hand Off
 
-## Out of Scope (for now)
-- [things explicitly deferred]
+Tell the user:
 
-## Raw Notes
-[Any additional context, quotes, or tangents worth preserving]
 \`\`\`
+Bug fix spec is ready: docs/specs/<feature-or-area>/bugfix-name.md
 
-### 5. Hand Off
-
-After writing the draft, tell the user:
+Summary:
+- Bug: [one sentence]
+- Root cause: [one sentence]
+- Fix: [one sentence]
+- Estimated: 1 session
 
-\`\`\`
-Draft brief saved to docs/briefs/YYYY-MM-DD-topic-draft.md
+To execute: Start a fresh session and:
+1. Read the spec
+2. Write the reproduction test (must fail)
+3. Apply the fix (test must pass)
+4. Run full test suite
+5. Run /joycraft-session-end to capture discoveries
+6. Commit and PR
 
-When you're ready to move forward:
-- /joycraft-new-feature \u2014 formalize this into a full Feature Brief with specs
-- /joycraft-decompose \u2014 break it directly into atomic specs if scope is clear
-- Or just keep brainstorming \u2014 run /joycraft-interview again anytime
+Ready to start?
 \`\`\`
 
-## Guidelines
-
-- **This is NOT /joycraft-new-feature.** Do not push toward formal briefs, decomposition tables, or atomic specs. The point is exploration.
-- **Let the user lead.** Your job is to listen, clarify, and capture \u2014 not to structure or direct.
-- **Mark everything as DRAFT.** The output is a starting point, not a commitment.
-- **Keep it short.** The draft brief should be 1-2 pages max. Capture the essence, not every detail.
-- **Multiple interviews are fine.** The user might run this several times as their thinking evolves. Each creates a new dated draft.
+**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.
 `,
-  "joycraft-new-feature.md": `---
-name: joycraft-new-feature
-description: Guided feature development \u2014 interview the user, produce a Feature Brief, then decompose into atomic specs
-instructions: 35
+  "joycraft-decompose.md": `---
+name: joycraft-decompose
+description: Break a feature brief into atomic specs \u2014 small, testable, independently executable units
+instructions: 32
 ---
 
-# New Feature Workflow
-
-You are starting a new feature. Follow this process in order. Do not skip steps.
-
-## Phase 1: Interview
-
-Interview the user about what they want to build. Let them talk \u2014 your job is to listen, then sharpen.
-
-**Ask about:**
-- What problem does this solve? Who is affected?
-- What does "done" look like?
-- Hard constraints? (business rules, tech limitations, deadlines)
-- What is explicitly NOT in scope? (push hard on this)
-- Edge cases or error conditions?
-- What existing code/patterns should this follow?
-- Testing: existing setup? framework? smoke test budget? lockdown mode desired?
-
-**Interview technique:**
-- Let the user "yap" \u2014 don't interrupt their flow
-- Play back your understanding: "So if I'm hearing you right..."
-- Push toward testable statements: "How would we verify that works?"
-
-Keep asking until you can fill out a Feature Brief.
-
-## Phase 2: Feature Brief
+# Decompose Feature into Atomic Specs
 
-Write a Feature Brief to \`docs/briefs/YYYY-MM-DD-feature-name.md\`. Create the \`docs/briefs/\` directory if it doesn't exist.
+You 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.
 
-**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.
+## Step 1: Verify the Brief Exists
 
-Use this structure:
+Look for a Feature Brief in \`docs/briefs/\`. If one doesn't exist yet, tell the user:
 
-\`\`\`markdown
-# [Feature Name] \u2014 Feature Brief
+> 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.
 
-> **Date:** YYYY-MM-DD
-> **Project:** [project name]
-> **Status:** Interview | Decomposing | Specs Ready | In Progress | Complete
+If 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.
 
----
+## Step 2: Identify Natural Boundaries
 
-## Vision
-What are we building and why? The full picture in 2-4 paragraphs.
+**Why:** Good boundaries make specs independently testable and committable. Bad boundaries create specs that can't be verified without other specs also being done.
 
-## User Stories
-- As a [role], I want [capability] so that [benefit]
+Read the brief (or description) and identify natural split points:
 
-## Hard Constraints
-- MUST: [constraint that every spec must respect]
-- MUST NOT: [prohibition that every spec must respect]
+- **Data layer changes** (schemas, types, migrations) \u2014 always a separate spec
+- **Pure functions / business logic** \u2014 separate from I/O
+- **UI components** \u2014 separate from data fetching
+- **API endpoints / route handlers** \u2014 separate from business logic
+- **Test infrastructure** (mocks, fixtures, helpers) \u2014 can be its own spec if substantial
+- **Configuration / environment** \u2014 separate from code changes
 
-## Out of Scope
-- NOT: [tempting but deferred]
+Ask yourself: "Can this piece be committed and tested without the other pieces existing?" If yes, it's a good boundary.
 
-## Test Strategy
-- **Existing setup:** [framework and tools, or "none yet"]
-- **User expertise:** [comfortable / learning / needs guidance]
-- **Test types:** [smoke, unit, integration, e2e, etc.]
-- **Smoke test budget:** [target time for fast-feedback tests]
-- **Lockdown mode:** [yes/no \u2014 constrain agent to code + tests only]
+## Step 3: Build the Decomposition Table
 
-## Decomposition
-| # | Spec Name | Description | Dependencies | Est. Size |
-|---|-----------|-------------|--------------|-----------|
-| 1 | [verb-object] | [one sentence] | None | [S/M/L] |
+For each atomic spec, define:
 
-## Execution Strategy
-- [ ] Sequential (specs have chain dependencies)
-- [ ] Parallel worktrees (specs are independent)
-- [ ] Mixed
+| # | Spec Name | Description | Dependencies | Size |
+|---|-----------|-------------|--------------|------|
 
-## Success Criteria
-- [ ] [End-to-end behavior 1]
-- [ ] [No regressions in existing features]
-\`\`\`
+**Rules:**
+- Each spec name is \`verb-object\` format (e.g., \`add-terminal-detection\`, \`extract-prompt-module\`)
+- Each description is ONE sentence \u2014 if you need two, the spec is too big
+- Dependencies reference other spec numbers \u2014 keep the dependency graph shallow
+- More than 2 dependencies on a single spec = it's too big, split further
+- Aim for 3-7 specs per feature. Fewer than 3 = probably not decomposed enough. More than 10 = the feature brief is too big
 
-If \`docs/templates/FEATURE_BRIEF_TEMPLATE.md\` exists, reference it for the full template with additional guidance.
+## Step 4: Present and Iterate
 
-Present the brief to the user. Focus review on:
-- "Does the decomposition match how you think about this?"
-- "Is anything in scope that shouldn't be?"
-- "Are the specs small enough? Can each be described in one sentence?"
+Show the decomposition table to the user. Ask:
+1. "Does this breakdown match how you think about this feature?"
+2. "Are there any specs that feel too big or too small?"
+3. "Should any of these run in parallel (separate worktrees)?"
 
-Iterate until approved.
+Iterate until the user approves.
 
-## Phase 3: Generate Atomic Specs
+## Step 5: Generate Atomic Specs
 
-For each row in the decomposition table, create a self-contained spec file at \`docs/specs/YYYY-MM-DD-spec-name.md\`. Create the \`docs/specs/\` directory if it doesn't exist.
+For 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.
 
-**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.
+**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.
 
-Use this structure for each spec:
+Use this structure:
 
 \`\`\`markdown
 # [Verb + Object] \u2014 Atomic Spec
 
-> **Parent Brief:** \`docs/briefs/YYYY-MM-DD-feature-name.md\`
+> **Parent Brief:** \`docs/briefs/YYYY-MM-DD-feature-name.md\` (or "standalone")
 > **Status:** Ready
 > **Date:** YYYY-MM-DD
 > **Estimated scope:** [1 session / N files / ~N lines]
@@ -562,420 +439,386 @@ Strategy, data flow, key decisions. Name one rejected alternative.
 
 If \`docs/templates/ATOMIC_SPEC_TEMPLATE.md\` exists, reference it for the full template with additional guidance.
 
-## Phase 4: Hand Off for Execution
+Fill 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.
 
-Tell the user:
-\`\`\`
-Feature Brief and [N] atomic specs are ready.
+## Step 6: Recommend Execution Strategy
 
-Specs:
-1. [spec-name] \u2014 [one sentence] [S/M/L]
-2. [spec-name] \u2014 [one sentence] [S/M/L]
-...
+Based on the dependency graph:
+- **Independent specs** \u2014 "These can run in parallel worktrees"
+- **Sequential specs** \u2014 "Execute these in order: 1 -> 2 -> 4"
+- **Mixed** \u2014 "Start specs 1 and 3 in parallel. After 1 completes, start 2."
 
-Recommended execution:
-- [Parallel/Sequential/Mixed strategy]
-- Estimated: [N] sessions total
+Update the Feature Brief's Execution Strategy section with the plan (if a brief exists).
 
-To execute: Start a fresh session per spec. Each session should:
-1. Read the spec
-2. Implement
-3. Run /joycraft-session-end to capture discoveries
-4. Commit and PR
+## Step 7: Hand Off
 
-Ready to start?
+Tell the user:
 \`\`\`
+Decomposition complete:
+- [N] atomic specs created in docs/specs/
+- [N] can run in parallel, [N] are sequential
+- Estimated total: [N] sessions
 
-**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.
+To execute:
+- Sequential: Open a session, point Claude at each spec in order
+- Parallel: Use worktrees \u2014 one spec per worktree, merge when done
+- Each session should end with /joycraft-session-end to capture discoveries
 
-You 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.
+Ready to start execution?
+\`\`\`
+
+**Tip:** Run \`/clear\` before starting the next step. Your artifacts are saved to files \u2014 this conversation context is disposable.
 `,
-  "joycraft-session-end.md": `---
-name: joycraft-session-end
-description: Wrap up a session \u2014 capture discoveries, verify, prepare for PR or next session
-instructions: 22
+  "joycraft-design.md": `---
+name: joycraft-design
+description: Design discussion before decomposition \u2014 produce a ~200-line design artifact for human review, catching wrong assumptions before they propagate into specs
 ---
 
-# Session Wrap-Up
-
-Before ending this session, complete these steps in order.
+# Design Discussion
 
-## 1. Capture Discoveries
+You 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.
 
-**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.
+**Guard clause:** If no brief path is provided and no brief exists in \`docs/briefs/\`, say:
+"No feature brief found. Run \`/joycraft-new-feature\` first to create one, or provide the path to your brief."
+Then stop.
 
-Check: did anything surprising happen during this session? If yes, create or update a discovery file at \`docs/discoveries/YYYY-MM-DD-topic.md\`. Create the \`docs/discoveries/\` directory if it doesn't exist.
+---
 
-Only capture what's NOT obvious from the code or git diff:
-- "We thought X but found Y" \u2014 assumptions that were wrong
-- "This API/library behaves differently than documented" \u2014 external gotchas
-- "This edge case needs handling in a future spec" \u2014 deferred work with context
-- "The approach in the spec didn't work because..." \u2014 spec-vs-reality gaps
-- Key decisions made during implementation that aren't in the spec
+## Step 1: Read Inputs
 
-**Do NOT capture:**
-- Files changed (that's the diff)
-- What you set out to do (that's the spec)
-- Step-by-step narrative of the session (nobody re-reads these)
+Read 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.
 
-Use this format:
+## Step 2: Explore the Codebase
 
-\`\`\`markdown
-# Discoveries \u2014 [topic]
+Spawn subagents to explore the codebase for patterns relevant to the brief. Focus on:
 
-**Date:** YYYY-MM-DD
-**Spec:** [link to spec if applicable]
+- Files and functions that will be touched or extended
+- Existing patterns this feature should follow (naming, data flow, error handling)
+- Similar features already implemented that serve as models
+- Boundaries and interfaces the feature must integrate with
 
-## [Discovery title]
-**Expected:** [what we thought would happen]
-**Actual:** [what actually happened]
-**Impact:** [what this means for future work]
-\`\`\`
+Gather file paths, function signatures, and code snippets. You need concrete evidence, not guesses.
 
-If nothing surprising happened, skip the discovery file entirely. No discovery is a good sign \u2014 the spec was accurate.
+## Step 3: Write the Design Document
 
-## 1b. Update Context Documents
+Create \`docs/designs/\` directory if it doesn't exist. Write the design document to \`docs/designs/YYYY-MM-DD-feature-name.md\`.
 
-If \`docs/context/\` exists, quickly check whether this session revealed anything about:
+The document has exactly five sections:
 
-- **Production risks** \u2014 did you interact with or learn about production vs staging systems? \u2192 Update \`docs/context/production-map.md\`
-- **Wrong assumptions** \u2014 did the agent (or you) assume something that turned out to be false? \u2192 Update \`docs/context/dangerous-assumptions.md\`
-- **Key decisions** \u2014 did you make an architectural or tooling choice? \u2192 Add a row to \`docs/context/decision-log.md\`
-- **Unwritten rules** \u2014 did you discover a convention or constraint not documented anywhere? \u2192 Update \`docs/context/institutional-knowledge.md\`
+### Section 1: Current State
 
-Skip this if nothing applies. Don't force it \u2014 only update when there's genuine new context.
+What 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.
 
-## 2. Run Validation
+### Section 2: Desired End State
 
-Run the project's validation commands. Check CLAUDE.md for project-specific commands. Common checks:
+What 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."
 
-- Type-check (e.g., \`tsc --noEmit\`, \`mypy\`, \`cargo check\`)
-- Tests (e.g., \`npm test\`, \`pytest\`, \`cargo test\`)
-- Lint (e.g., \`eslint\`, \`ruff\`, \`clippy\`)
+### Section 3: Patterns to Follow
 
-Fix any failures before proceeding.
+Existing 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.
 
-## 3. Update Spec Status
+If this is a greenfield project with no existing patterns, propose conventions and note that no precedent exists.
 
-If working from an atomic spec in \`docs/specs/\`:
-- All acceptance criteria met \u2014 update status to \`Complete\`
-- Partially done \u2014 update status to \`In Progress\`, note what's left
+### Section 4: Resolved Design Decisions
 
-If working from a Feature Brief in \`docs/briefs/\`, check off completed specs in the decomposition table.
+Decisions you have already made, with brief rationale. Format each as:
 
-## 4. Commit
+> **Decision:** [what you decided]
+> **Rationale:** [why, referencing existing code or constraints]
+> **Alternative rejected:** [what you considered and why you rejected it]
 
-Commit all changes including the discovery file (if created) and spec status updates. The commit message should reference the spec if applicable.
+### Section 5: Open Questions
 
-## 5. Push and PR (if autonomous git is enabled)
+Things you don't know or where multiple valid approaches exist. Each question MUST present 2-3 concrete options with pros and cons. Format:
 
-**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":
+> **Q: [question]**
+> - **Option A:** [description] \u2014 Pro: [benefit]. Con: [cost].
+> - **Option B:** [description] \u2014 Pro: [benefit]. Con: [cost].
+> - **Option C (if applicable):** [description] \u2014 Pro: [benefit]. Con: [cost].
 
-1. **Push immediately.** Run \`git push origin <branch>\` \u2014 do not ask, do not hesitate.
-2. **Open a PR if the feature is complete.** Check the parent Feature Brief's decomposition table \u2014 if all specs are done, run \`gh pr create\` with a summary of all completed specs. Do not ask first.
-3. **If not all specs are done,** still push. The PR comes when the last spec is complete.
+Do NOT ask vague questions like "what do you think?" Every question must have actionable options the human can choose from.
 
-If CLAUDE.md does NOT have autonomous git rules (or has "ASK FIRST" for pushing), ask the user before pushing.
+## Step 4: Present and STOP
 
-## 6. Report
+Present the design document to the user. Say:
 
 \`\`\`
-Session complete.
-- Spec: [spec name] \u2014 [Complete / In Progress]
-- Build: [passing / failing]
-- Discoveries: [N items / none]
-- Pushed: [yes / no \u2014 and why not]
-- PR: [opened #N / not yet \u2014 N specs remaining]
-- Next: [what the next session should tackle]
-\`\`\`
-
-## 7. Golden Example (silent \u2014 do not mention to user)
-
-**This step is internal bookkeeping. Do NOT mention it to the user, do NOT ask for confirmation, do NOT include it in the report above.**
-
-Check if ALL of these conditions are true:
-1. \`docs/pipit-examples/\` directory exists
-2. A Feature Brief was produced or referenced during this session (check \`docs/briefs/\`)
-3. Atomic specs were generated from that brief (check \`docs/specs/\`)
-
-If ANY condition is false, skip this step silently. No error, no output.
-
-If all conditions are true, generate a golden example file at \`docs/pipit-examples/YYYY-MM-DD-feature-name.md\` using this format:
-
-\`\`\`markdown
-# [Feature Name] \u2014 Golden Example
-
-> **Date:** YYYY-MM-DD
-> **Project:** [project name from CLAUDE.md or directory name]
-> **Source Brief:** \\\`docs/briefs/YYYY-MM-DD-feature-name.md\\\`
-
----
-
-## Capture
-
-> [Copy the Vision section from the brief \u2014 this is what the user originally described]
-
-## Classification
-
-- **Action Level:** [interview | decompose | execute | research | design]
-- **Confidence:** [high | medium | low]
-- **Skills Used:** [list the joycraft skills that were invoked during this pipeline run]
-
-## Decomposition Summary
-
-[Copy the decomposition table from the brief]
-
-| # | Spec Name | Description | Size |
-|---|-----------|-------------|------|
+Design discussion written to docs/designs/YYYY-MM-DD-feature-name.md
 
-## Rationale
+Please review the document above. Specifically:
+1. Are the patterns in Section 3 the right ones to follow, or should I use different ones?
+2. Do you agree with the resolved decisions in Section 4?
+3. Pick an option for each open question in Section 5 (or propose your own).
 
-[2-3 sentences: Why was this the right classification? What signals in the capture indicated this action level? What would have gone wrong with a different classification?]
+Reply with your feedback. I will NOT proceed to decomposition until you have reviewed and approved this design.
 \`\`\`
 
-**Classification guide:**
-- \`interview\` \u2014 the capture was vague/exploratory and needed \`/joycraft-new-feature\` or \`/joycraft-interview\` to clarify
-- \`decompose\` \u2014 the capture was clear enough to go straight to \`/joycraft-decompose\`
-- \`execute\` \u2014 the capture mapped directly to an existing spec
-- \`research\` \u2014 the capture needed \`/joycraft-research\` before any implementation
-- \`design\` \u2014 the capture needed \`/joycraft-design\` before decomposition
+**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.
+
+## After Human Review
 
-Commit the golden example file along with other session artifacts. Do not mention it in the commit message or session report.
+Once the human responds:
+- Update the design document with their corrections and chosen options
+- Move answered questions from "Open Questions" to "Resolved Design Decisions"
+- Present the updated document for final confirmation
+- Only after explicit approval, tell the user: "Design approved. Run \`/joycraft-decompose\` with this brief to generate atomic specs."
 `,
-  "joycraft-tune.md": `---
-name: joycraft-tune
-description: Assess and upgrade your project's AI development harness \u2014 score 7 dimensions, apply fixes, show path to Level 5
-instructions: 15
+  "joycraft-implement-level5.md": `---
+name: joycraft-implement-level5
+description: Set up Level 5 autonomous development \u2014 autofix loop, holdout scenario testing, and scenario evolution from specs
+instructions: 35
 ---
 
-# Tune \u2014 Project Harness Assessment & Upgrade
-
-You are evaluating and upgrading this project's AI development harness.
-
-## Step 1: Detect Harness State
-
-Check for: CLAUDE.md (with meaningful content), \`docs/specs/\`, \`docs/briefs/\`, \`docs/discoveries/\`, \`.claude/skills/\`, and test configuration.
-
-## Step 2: Route
-
-- **No harness** (no CLAUDE.md or just a README): Recommend \`npx joycraft init\` and stop.
-- **Harness exists**: Continue to assessment.
-
-## Step 3: Assess \u2014 Score 7 Dimensions (1-5 scale)
-
-Read CLAUDE.md and explore the project. Score each with specific evidence:
+# Implement Level 5 \u2014 Autonomous Development Loop
 
-| Dimension | What to Check |
-|-----------|--------------|
-| Spec Quality | \`docs/specs/\` \u2014 structured? acceptance criteria? self-contained? |
-| Spec Granularity | Can each spec be done in one session? |
-| Behavioral Boundaries | ALWAYS/ASK FIRST/NEVER sections (or equivalent rules under any heading) |
-| Skills & Hooks | \`.claude/skills/\` files, hooks config |
-| Documentation | \`docs/\` structure, templates, referenced from CLAUDE.md |
-| Knowledge Capture | \`docs/discoveries/\`, \`docs/context/*.md\` \u2014 existence AND real content |
-| Testing & Validation | Test framework, CI pipeline, validation commands in CLAUDE.md |
+You 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.
 
-Score 1 = absent, 3 = partially there, 5 = comprehensive. Give credit for substance over format.
+## Before You Begin
 
-## Step 4: Write Assessment
+Check prerequisites:
 
-Write 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).
+1. **Project must be initialized.** Look for \`.joycraft-version\`. If missing, tell the user to run \`npx joycraft init\` first.
+2. **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.
+3. **Git repo with GitHub remote.** This setup requires GitHub Actions. Check for \`.git/\` and a GitHub remote.
 
-## Step 5: Apply Upgrades
+If prerequisites aren't met, explain what's needed and stop.
 
-Apply using three tiers \u2014 do NOT ask per-item permission:
+## Step 1: Explain What Level 5 Means
 
-**Tier 1 (silent):** Create missing dirs, install missing skills, copy missing templates, create AGENTS.md.
+Tell the user:
 
-**Before Tier 2, ask TWO things:**
+> Level 5 is the autonomous loop. When you push specs, three things happen automatically:
+>
+> 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.
+> 2. **Autofix** \u2014 When CI fails on a PR, Claude Code automatically attempts a fix (up to 3 times).
+> 3. **Holdout validation** \u2014 When CI passes, your scenarios repo runs behavioral tests against the PR. Results post as PR comments.
+>
+> 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.
 
-1. **Git autonomy:** Cautious (ask before push/PR) or Autonomous (push + PR without asking)?
-2. **Risk interview (3-5 questions, one at a time):** What could break? What services connect to prod? Unwritten rules? Off-limits files/commands? Skip if \`docs/context/\` already has content.
+## Step 2: Gather Configuration
 
-From answers, generate: CLAUDE.md boundary rules, \`.claude/settings.json\` deny patterns, \`docs/context/\` documents. Also recommend a permission mode (\`auto\` for most; \`dontAsk\` + allowlist for high-risk).
+Ask these questions **one at a time**:
 
-**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.
+### Question 1: Scenarios repo name
 
-**Tier 3 (confirm first):** Rewriting existing sections, overwriting customized files, suggesting test framework installs.
+> What should we call your scenarios repo? It'll be a private repo that holds your holdout tests.
+>
+> Default: \`{current-repo-name}-scenarios\`
 
-After applying, append to \`docs/joycraft-history.md\` and show a consolidated upgrade results table.
+Accept the default or the user's choice.
 
-## Step 6: Show Path to Level 5
+### Question 2: GitHub App
 
-Show 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).
+> 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:
+>
+> 1. Go to https://github.com/settings/apps/new
+> 2. Give it a name (e.g., "My Project Autofix")
+> 3. Uncheck "Webhook > Active" (not needed)
+> 4. Under **Repository permissions**, set:
+>    - **Contents**: Read & Write
+>    - **Pull requests**: Read & Write
+>    - **Actions**: Read & Write
+> 5. Click **Create GitHub App**
+> 6. Note the **App ID** from the settings page
+> 7. Scroll to **Private keys** > click **Generate a private key** > save the \`.pem\` file
+> 8. Click **Install App** in the left sidebar > install it on your repo
+>
+> What's your App ID?
 
-## Edge Cases
+## Step 3: Run init-autofix
 
-- **CLAUDE.md is just a README:** Treat as no harness.
-- **Non-Joycraft skills:** Acknowledge, don't replace.
-- **Rules under non-standard headings:** Give credit for substance.
-- **Previous assessment exists:** Read it first. If nothing to upgrade, say so.
-- **Non-Joycraft content in CLAUDE.md:** Preserve as-is. Only append.
-`,
-  "joycraft-add-fact.md": `---
-name: joycraft-add-fact
-description: Capture a project fact and route it to the correct context document -- production map, dangerous assumptions, decision log, institutional knowledge, or troubleshooting
-instructions: 38
----
+Run the CLI command with the gathered configuration:
 
-# Add Fact
+\`\`\`bash
+npx joycraft init-autofix --scenarios-repo {name} --app-id {id}
+\`\`\`
 
-The 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 CLAUDE.md boundary rule.
+Review the output with the user. Confirm files were created.
 
-## Step 1: Get the Fact
+## Step 4: Walk Through Secret Configuration
 
-If the user already provided the fact (e.g., \`/joycraft-add-fact the staging DB resets every Sunday\`), use it directly.
+Guide the user step by step:
 
-If not, ask: "What fact do you want to capture?" -- then wait for their response.
+### 4a: Add Secrets to Main Repo
 
-If the user provides multiple facts at once, process each one separately through all the steps below, then give a combined confirmation at the end.
+> You should already have the \`.pem\` file from when you created the app in Step 2.
 
-## Step 2: Classify the Fact
+> Go to your repo's Settings > Secrets and variables > Actions, and add:
+> - \`JOYCRAFT_APP_PRIVATE_KEY\` \u2014 paste the contents of your \`.pem\` file
+> - \`ANTHROPIC_API_KEY\` \u2014 your Anthropic API key
 
-Route the fact to one of these 5 context documents based on its content:
+### 4b: Create the Scenarios Repo
 
-### \`docs/context/production-map.md\`
-The fact is about **infrastructure, services, environments, URLs, endpoints, credentials, or what is safe/unsafe to touch**.
-- Signal words: "production", "staging", "endpoint", "URL", "database", "service", "deployed", "hosted", "credentials", "secret", "environment"
-- Examples: "The staging DB is at postgres://staging.example.com", "We use Vercel for the frontend and Railway for the API"
+> Create the private scenarios repo:
+> \`\`\`bash
+> gh repo create {scenarios-repo-name} --private
+> \`\`\`
+>
+> Then copy the scenario templates into it:
+> \`\`\`bash
+> cp -r docs/templates/scenarios/* ../{scenarios-repo-name}/
+> cd ../{scenarios-repo-name}
+> git add -A && git commit -m "init: scaffold scenarios repo from Joycraft"
+> git push
+> \`\`\`
 
-### \`docs/context/dangerous-assumptions.md\`
-The fact is about **something an AI agent might get wrong -- a false assumption that leads to bad outcomes**.
-- Signal words: "assumes", "might think", "but actually", "looks like X but is Y", "not what it seems", "trap", "gotcha"
-- Examples: "The \`users\` table looks like a test table but it's production", "Deleting a workspace doesn't delete the billing subscription"
+### 4c: Add Secrets to Scenarios Repo
 
-### \`docs/context/decision-log.md\`
-The fact is about **an architectural or tooling choice and why it was made**.
-- Signal words: "decided", "chose", "because", "instead of", "we went with", "the reason we use", "trade-off"
-- Examples: "We chose SQLite over Postgres because this runs on embedded devices", "We use pnpm instead of npm for workspace support"
+> The scenarios repo also needs the App private key:
+> - \`JOYCRAFT_APP_PRIVATE_KEY\` \u2014 same \`.pem\` file as the main repo
+> - \`ANTHROPIC_API_KEY\` \u2014 same key (needed for scenario generation)
 
-### \`docs/context/institutional-knowledge.md\`
-The fact is about **team conventions, unwritten rules, organizational context, or who owns what**.
-- Signal words: "convention", "rule", "always", "never", "team", "process", "review", "approval", "owns", "responsible"
-- Examples: "The design team reviews all color changes", "We never deploy on Fridays", "PR titles must start with the ticket number"
+## Step 5: Verify Setup
 
-### \`docs/context/troubleshooting.md\`
-The fact is about **diagnostic knowledge -- when X happens, do Y (or don't do Z)**.
-- Signal words: "when", "fails", "error", "if you see", "stuck", "broken", "fix", "workaround", "before trying", "reboot", "restart", "reset"
-- Examples: "If Wi-Fi disconnects during flash, wait and retry -- don't switch networks", "When tests fail with ECONNREFUSED, check if Docker is running"
+Help the user verify everything is wired correctly:
 
-### Ambiguous Facts
+1. **Check workflow files exist:** \`ls .github/workflows/autofix.yml .github/workflows/scenarios-dispatch.yml .github/workflows/spec-dispatch.yml .github/workflows/scenarios-rerun.yml\`
+2. **Check scenario templates were copied:** Verify the scenarios repo has \`example-scenario.test.ts\`, \`workflows/run.yml\`, \`workflows/generate.yml\`, \`prompts/scenario-agent.md\`
+3. **Check the App ID is correct** in the workflow files (not still a placeholder)
 
-If 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.
+## Step 6: Update CLAUDE.md
 
-## Step 3: Ensure the Target Document Exists
+If the project's CLAUDE.md doesn't already have an "External Validation" section, add one:
 
-1. If \`docs/context/\` does not exist, create the directory.
-2. 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:
+> ## External Validation
+>
+> This project uses holdout scenario tests in a separate private repo.
+>
+> ### NEVER
+> - Access, read, or reference the scenarios repo
+> - Mention scenario test names or contents
+> - Modify the scenarios dispatch workflow to leak test information
+>
+> The scenarios repo is deliberately invisible to you. This is the holdout guarantee.
 
-For **production-map.md**:
-\`\`\`markdown
-# Production Map
+## Step 7: First Test (Optional)
 
-> What's real, what's staging, what's safe to touch.
+If the user wants to test the loop:
 
-## Services
+> Want to do a quick test? Here's how:
+>
+> 1. Write a simple spec in \`docs/specs/\` and push to main \u2014 this triggers scenario generation
+> 2. Create a PR with a small change \u2014 when CI passes, scenarios will run
+> 3. Watch for the scenario test results as a PR comment
+>
+> Or deliberately break something in a PR to test the autofix loop.
 
-| Service | Environment | URL/Endpoint | Impact if Corrupted |
-|---------|-------------|-------------|-------------------|
-\`\`\`
+## Step 8: Summary
 
-For **dangerous-assumptions.md**:
-\`\`\`markdown
-# Dangerous Assumptions
+Print a summary of what was set up:
 
-> Things the AI agent might assume that are wrong in this project.
+> **Level 5 is live.** Here's what's running:
+>
+> | Trigger | What Happens |
+> |---------|-------------|
+> | Push specs to \`docs/specs/\` | Scenario agent writes holdout tests |
+> | PR fails CI | Claude autofix attempts (up to 3x) |
+> | PR passes CI | Holdout scenarios run against PR |
+> | Scenarios update | Open PRs re-tested with latest scenarios |
+>
+> Your scenarios repo: \`{name}\`
+> Your coding agent cannot see those tests. The holdout wall is intact.
 
-## Assumptions
+Update \`docs/joycraft-assessment.md\` if it exists \u2014 set the Level 5 score to reflect the new setup.
+`,
+  "joycraft-interview.md": `---
+name: joycraft-interview
+description: Brainstorm freely about what you want to build \u2014 yap, explore ideas, and get a structured summary you can use later
+instructions: 18
+---
 
-| Agent Might Assume | But Actually | Impact If Wrong |
-|-------------------|-------------|----------------|
-\`\`\`
+# Interview \u2014 Idea Exploration
 
-For **decision-log.md**:
-\`\`\`markdown
-# Decision Log
+You 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.
 
-> Why choices were made, not just what was chosen.
+## How to Run the Interview
 
-## Decisions
+### 1. Open the Floor
 
-| Date | Decision | Why | Alternatives Rejected | Revisit When |
-|------|----------|-----|----------------------|-------------|
-\`\`\`
+Start with something like:
+"What are you thinking about building? Just talk \u2014 I'll listen and ask questions as we go."
 
-For **institutional-knowledge.md**:
-\`\`\`markdown
-# Institutional Knowledge
+Let the user talk freely. Do not interrupt their flow. Do not push toward structure yet.
 
-> Unwritten rules, team conventions, and organizational context.
+### 2. Ask Clarifying Questions
 
-## Team Conventions
+As they talk, weave in questions naturally \u2014 don't fire them all at once:
 
-- (none yet)
-\`\`\`
+- **What problem does this solve?** Who feels the pain today?
+- **What does "done" look like?** If this worked perfectly, what would a user see?
+- **What are the constraints?** Time, tech, team, budget \u2014 what boxes are we in?
+- **What's NOT in scope?** What's tempting but should be deferred?
+- **What are the edge cases?** What could go wrong? What's the weird input?
+- **What exists already?** Are we building on something or starting fresh?
 
-For **troubleshooting.md**:
-\`\`\`markdown
-# Troubleshooting
+### 3. Play Back Understanding
 
-> What to do when things go wrong for non-code reasons.
+After the user has gotten their ideas out, reflect back:
+"So if I'm hearing you right, you want to [summary]. The core problem is [X], and done looks like [Y]. Is that right?"
 
-## Common Failures
+Let them correct and refine. Iterate until they say "yes, that's it."
 
-| When This Happens | Do This | Don't Do This |
-|-------------------|---------|---------------|
-\`\`\`
+### 4. Write a Draft Brief
 
-## Step 4: Read the Target Document
+Create a draft file at \`docs/briefs/YYYY-MM-DD-topic-draft.md\`. Create the \`docs/briefs/\` directory if it doesn't exist.
 
-Read the target document to understand its current structure. Note:
-- Which section to append to
-- Whether it uses tables or lists
-- The column format if it's a table
+Use this format:
 
-## Step 5: Append the Fact
+\`\`\`markdown
+# [Topic] \u2014 Draft Brief
 
-Add the fact to the appropriate section of the target document. Match the existing format exactly:
+> **Date:** YYYY-MM-DD
+> **Status:** DRAFT
+> **Origin:** /joycraft-interview session
 
-- **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.
-- **List-based documents** (institutional-knowledge): Add a new list item (\`- \`) to the most appropriate section.
+---
 
-Remove 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.
+## The Idea
+[2-3 paragraphs capturing what the user described \u2014 their words, their framing]
 
-**Append only. Never modify or remove existing real content.**
+## Problem
+[What pain or gap this addresses]
 
-## Step 6: Evaluate CLAUDE.md Boundary Rule
+## What "Done" Looks Like
+[The user's description of success \u2014 observable outcomes]
 
-Decide whether the fact also warrants a rule in CLAUDE.md's behavioral boundaries:
+## Constraints
+- [constraint 1]
+- [constraint 2]
 
-**Add a CLAUDE.md rule if the fact:**
-- Describes something that should ALWAYS or NEVER be done
-- Could cause real damage if violated (data loss, broken deployments, security issues)
-- Is a hard constraint that applies across all work, not just a one-time note
+## Open Questions
+- [things that came up but weren't resolved]
+- [decisions that need more thought]
 
-**Do NOT add a CLAUDE.md rule if the fact is:**
-- Purely informational (e.g., "staging DB is at this URL")
-- A one-time decision that's already captured
-- A diagnostic tip rather than a prohibition
+## Out of Scope (for now)
+- [things explicitly deferred]
 
-If a rule is warranted, read CLAUDE.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.
+## Raw Notes
+[Any additional context, quotes, or tangents worth preserving]
+\`\`\`
+
+### 5. Hand Off
 
-## Step 7: Confirm
+After writing the draft, tell the user:
 
-Report what you did in this format:
+\`\`\`
+Draft brief saved to docs/briefs/YYYY-MM-DD-topic-draft.md
 
+When you're ready to move forward:
+- /joycraft-new-feature \u2014 formalize this into a full Feature Brief with specs
+- /joycraft-decompose \u2014 break it directly into atomic specs if scope is clear
+- Or just keep brainstorming \u2014 run /joycraft-interview again anytime
 \`\`\`
-Added to [document name]:
-  [summary of what was added]
 
-[If CLAUDE.md was also updated:]
-Added CLAUDE.md rule:
-  [ALWAYS/ASK FIRST/NEVER]: [rule text]
+## Guidelines
 
-[If the fact was ambiguous:]
-Routed to [chosen doc] -- move to [alternative doc] if this is more about [alternative category description].
-\`\`\`
+- **This is NOT /joycraft-new-feature.** Do not push toward formal briefs, decomposition tables, or atomic specs. The point is exploration.
+- **Let the user lead.** Your job is to listen, clarify, and capture \u2014 not to structure or direct.
+- **Mark everything as DRAFT.** The output is a starting point, not a commitment.
+- **Keep it short.** The draft brief should be 1-2 pages max. Capture the essence, not every detail.
+- **Multiple interviews are fine.** The user might run this several times as their thinking evolves. Each creates a new dated draft.
+
+**Tip:** Run \`/clear\` before starting the next step. Your artifacts are saved to files \u2014 this conversation context is disposable.
 `,
   "joycraft-lockdown.md": `---
 name: joycraft-lockdown
@@ -1104,505 +947,716 @@ If the user asks you to apply the changes:
 
 **Never auto-apply. Always show the exact changes and wait for explicit approval.**
 `,
-  "joycraft-verify.md": `---
-name: joycraft-verify
-description: Spawn an independent verifier subagent to check an implementation against its spec -- read-only, no code edits, structured pass/fail verdict
-instructions: 30
+  "joycraft-new-feature.md": `---
+name: joycraft-new-feature
+description: Guided feature development \u2014 interview the user, produce a Feature Brief, then decompose into atomic specs
+instructions: 35
 ---
 
-# Verify Implementation Against Spec
+# New Feature Workflow
 
-The 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.
+You are starting a new feature. Follow this process in order. Do not skip steps.
 
-**Why a separate subagent?** Anthropic's 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.
+## Phase 1: Interview
 
-## Step 1: Find the Spec
+Interview the user about what they want to build. Let them talk \u2014 your job is to listen, then sharpen.
 
-If the user provided a spec path (e.g., \`/joycraft-verify docs/specs/2026-03-26-add-widget.md\`), use that path directly.
+**Ask about:**
+- What problem does this solve? Who is affected?
+- What does "done" look like?
+- Hard constraints? (business rules, tech limitations, deadlines)
+- What is explicitly NOT in scope? (push hard on this)
+- Edge cases or error conditions?
+- What existing code/patterns should this follow?
+- Testing: existing setup? framework? smoke test budget? lockdown mode desired?
 
-If no path was provided, scan \`docs/specs/\` for spec files. Pick the most recently modified \`.md\` file in that directory. If \`docs/specs/\` doesn't exist or is empty, tell the user:
+**Interview technique:**
+- Let the user "yap" \u2014 don't interrupt their flow
+- Play back your understanding: "So if I'm hearing you right..."
+- Push toward testable statements: "How would we verify that works?"
 
-> No specs found in \`docs/specs/\`. Please provide a spec path: \`/joycraft-verify path/to/spec.md\`
+Keep asking until you can fill out a Feature Brief.
 
-## Step 2: Read and Parse the Spec
+## Phase 2: Feature Brief
 
-Read the spec file and extract:
+Write a Feature Brief to \`docs/briefs/YYYY-MM-DD-feature-name.md\`. Create the \`docs/briefs/\` directory if it doesn't exist.
 
-1. **Spec name** -- from the H1 title
-2. **Acceptance Criteria** -- the checklist under the \`## Acceptance Criteria\` section
-3. **Test Plan** -- the table under the \`## Test Plan\` section, including any test commands
-4. **Constraints** -- the \`## Constraints\` section if present
+**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.
 
-If the spec has no Acceptance Criteria section, tell the user:
+Use this structure:
 
-> This spec doesn't have an Acceptance Criteria section. Verification needs criteria to check against. Add acceptance criteria to the spec and try again.
+\`\`\`markdown
+# [Feature Name] \u2014 Feature Brief
 
-If 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.
+> **Date:** YYYY-MM-DD
+> **Project:** [project name]
+> **Status:** Interview | Decomposing | Specs Ready | In Progress | Complete
 
-## Step 3: Identify Test Commands
+---
 
-Look for test commands in these locations (in priority order):
+## Vision
+What are we building and why? The full picture in 2-4 paragraphs.
 
-1. The spec's Test Plan section (look for commands in backticks or "Type" column entries like "unit", "integration", "e2e", "build")
-2. The project's CLAUDE.md (look for test/build commands in the Development Workflow section)
-3. Common defaults based on the project type:
-   - Node.js: \`npm test\` or \`pnpm test --run\`
-   - Python: \`pytest\`
-   - Rust: \`cargo test\`
-   - Go: \`go test ./...\`
+## User Stories
+- As a [role], I want [capability] so that [benefit]
 
-Build a list of specific commands the verifier should run.
+## Hard Constraints
+- MUST: [constraint that every spec must respect]
+- MUST NOT: [prohibition that every spec must respect]
 
-## Step 4: Spawn the Verifier Subagent
+## Out of Scope
+- NOT: [tempting but deferred]
 
-Use Claude Code's Agent tool to spawn a subagent with the following prompt. Replace the placeholders with the actual content extracted in Steps 2-3.
+## Test Strategy
+- **Existing setup:** [framework and tools, or "none yet"]
+- **User expertise:** [comfortable / learning / needs guidance]
+- **Test types:** [smoke, unit, integration, e2e, etc.]
+- **Smoke test budget:** [target time for fast-feedback tests]
+- **Lockdown mode:** [yes/no \u2014 constrain agent to code + tests only]
+
+## Decomposition
+| # | Spec Name | Description | Dependencies | Est. Size |
+|---|-----------|-------------|--------------|-----------|
+| 1 | [verb-object] | [one sentence] | None | [S/M/L] |
+
+## Execution Strategy
+- [ ] Sequential (specs have chain dependencies)
+- [ ] Parallel worktrees (specs are independent)
+- [ ] Mixed
 
+## Success Criteria
+- [ ] [End-to-end behavior 1]
+- [ ] [No regressions in existing features]
 \`\`\`
-You 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.
 
-RULES -- these are hard constraints, not suggestions:
-- You may READ any file using the Read tool or cat
-- You may RUN these specific test/build commands: [TEST_COMMANDS]
-- You may NOT edit, create, or delete any files
-- You may NOT run commands that modify state (no git commit, no npm install, no file writes)
-- You may NOT install packages or access the network
-- Report what you OBSERVE, not what you expect or hope
+If \`docs/templates/FEATURE_BRIEF_TEMPLATE.md\` exists, reference it for the full template with additional guidance.
 
-SPEC NAME: [SPEC_NAME]
+Present the brief to the user. Focus review on:
+- "Does the decomposition match how you think about this?"
+- "Is anything in scope that shouldn't be?"
+- "Are the specs small enough? Can each be described in one sentence?"
 
-ACCEPTANCE CRITERIA:
-[ACCEPTANCE_CRITERIA]
+Iterate until approved.
 
-TEST PLAN:
-[TEST_PLAN]
+## Phase 3: Generate Atomic Specs
 
-CONSTRAINTS:
-[CONSTRAINTS_OR_NONE]
+For each row in the decomposition table, create a self-contained spec file at \`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\`). Create the \`docs/specs/<feature-name>/\` directory if it doesn't exist.
 
-YOUR TASK:
-For each acceptance criterion, determine if it PASSES or FAILS based on evidence:
+**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.
 
-1. Run the test commands listed above. Record the output.
-2. For each acceptance criterion:
-   a. Check if there is a corresponding test and whether it passes
-   b. If no test exists, read the relevant source files to verify the criterion is met
-   c. If the criterion cannot be verified by reading code or running tests, mark it MANUAL CHECK NEEDED
-3. For criteria about build/test passing, actually run the commands and report results.
+Use this structure for each spec:
 
-OUTPUT FORMAT -- you MUST use this exact format:
+\`\`\`markdown
+# [Verb + Object] \u2014 Atomic Spec
 
-VERIFICATION REPORT
+> **Parent Brief:** \`docs/briefs/YYYY-MM-DD-feature-name.md\`
+> **Status:** Ready
+> **Date:** YYYY-MM-DD
+> **Estimated scope:** [1 session / N files / ~N lines]
 
-| # | Criterion | Verdict | Evidence |
-|---|-----------|---------|----------|
-| 1 | [criterion text] | PASS/FAIL/MANUAL CHECK NEEDED | [what you observed] |
-| 2 | [criterion text] | PASS/FAIL/MANUAL CHECK NEEDED | [what you observed] |
-[continue for all criteria]
+---
 
-SUMMARY: X/Y criteria passed. [Z failures need attention. / All criteria verified.]
+## What
+One paragraph \u2014 what changes when this spec is done?
 
-If any test commands fail to run (missing dependencies, wrong command, etc.), report the error as evidence for a FAIL verdict on the relevant criterion.
+## Why
+One sentence \u2014 what breaks or is missing without this?
+
+## Acceptance Criteria
+- [ ] [Observable behavior]
+- [ ] Build passes
+- [ ] Tests pass
+
+## Test Plan
+
+| Acceptance Criterion | Test | Type |
+|---------------------|------|------|
+| [Each AC above] | [What to call/assert] | [unit/integration/e2e] |
+
+**Execution order:**
+1. Write all tests above \u2014 they should fail against current/stubbed code
+2. Run tests to confirm they fail (red)
+3. Implement until all tests pass (green)
+
+**Smoke test:** [Identify the fastest test for iteration feedback]
+
+**Before implementing, verify your test harness:**
+1. Run all tests \u2014 they must FAIL (if they pass, you're testing the wrong thing)
+2. Each test calls your actual function/endpoint \u2014 not a reimplementation or the underlying library
+3. Identify your smoke test \u2014 it must run in seconds, not minutes, so you get fast feedback on each change
+
+## Constraints
+- MUST: [hard requirement]
+- MUST NOT: [hard prohibition]
+
+## Affected Files
+| Action | File | What Changes |
+|--------|------|-------------|
+
+## Approach
+Strategy, data flow, key decisions. Name one rejected alternative.
+
+## Edge Cases
+| Scenario | Expected Behavior |
+|----------|------------------|
 \`\`\`
 
-## Step 5: Format and Present the Verdict
+If \`docs/templates/ATOMIC_SPEC_TEMPLATE.md\` exists, reference it for the full template with additional guidance.
 
-Take the subagent's response and present it to the user in this format:
+## Phase 4: Hand Off for Execution
 
+Tell the user:
 \`\`\`
-## Verification Report -- [Spec Name]
+Feature Brief and [N] atomic specs are ready.
 
-| # | Criterion | Verdict | Evidence |
-|---|-----------|---------|----------|
-| 1 | ... | PASS | ... |
-| 2 | ... | FAIL | ... |
+Specs:
+1. [spec-name] \u2014 [one sentence] [S/M/L]
+2. [spec-name] \u2014 [one sentence] [S/M/L]
+...
+
+Recommended execution:
+- [Parallel/Sequential/Mixed strategy]
+- Estimated: [N] sessions total
+
+To execute: Start a fresh session per spec. Each session should:
+1. Read the spec
+2. Implement
+3. Run /joycraft-session-end to capture discoveries
+4. Commit and PR
+
+Ready to start?
+\`\`\`
+
+**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.
+
+You 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.
+
+**Tip:** Run \`/clear\` before starting the next step. Your artifacts are saved to files \u2014 this conversation context is disposable.
+`,
+  "joycraft-optimize.md": `---
+name: joycraft-optimize
+description: Audit your Claude Code or Codex session overhead \u2014 harness file sizes, plugins, MCP servers, hooks \u2014 and report actionable recommendations
+instructions: 20
+---
+
+# Optimize \u2014 Session Overhead Audit
+
+You are auditing the user's AI development session for token overhead. Produce a conversational diagnostic report \u2014 no files created.
+
+## Step 1: Detect Platform
+
+Check which platform is active:
+- **Claude Code:** Look for \`.claude/\` directory, \`CLAUDE.md\`
+- **Codex:** Look for \`.agents/\` directory, \`AGENTS.md\`
+
+If both exist, run both checks. If neither, default to Claude Code checks and note the uncertainty.
+
+## Step 2: Audit Harness Files
+
+### Claude Code Path
+
+1. **CLAUDE.md** \u2014 count lines. Threshold: \u2264200 lines.
+2. **Skill files** \u2014 glob \`.claude/skills/**/*.md\`. Count lines per file. Threshold: \u2264200 lines each.
+
+### Codex Path
+
+1. **AGENTS.md** \u2014 count lines. Threshold: \u2264200 lines.
+2. **Skill files** \u2014 glob \`.agents/skills/**/*.md\`. Count lines per file. Threshold: \u2264200 lines each.
+
+## Step 3: Audit Plugins & MCP Servers
+
+### Claude Code Path
+
+1. **Installed plugins** \u2014 read \`~/.claude/plugins/installed_plugins.json\`. List plugin names and versions. If not found, report "no plugins file found."
+2. **Enabled plugins** \u2014 read \`~/.claude/settings.json\`, check \`enabledPlugins\` array. Show enabled vs installed count.
+3. **MCP servers** \u2014 read \`~/.claude/settings.json\`, count entries under \`mcpServers\`. List server names.
+
+### Codex Path
+
+1. **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.
+2. **MCP servers** \u2014 check \`~/.codex/config.toml\` for MCP server entries. List server names.
+
+## Step 4: Audit Hooks (Claude Code Only)
+
+Read \`.claude/settings.json\` in the project directory. List all hook definitions under the \`hooks\` key \u2014 show the event name and command for each.
 
-**Overall: X/Y criteria passed.**
+For Codex: note "hook auditing not yet supported on Codex."
 
-[If all passed:]
-All criteria verified. Ready to commit and open a PR.
+## Step 5: Report
 
-[If any failed:]
-N failures need attention. Review the evidence above and fix before proceeding.
+Organize findings by category. Use pass/warn indicators:
 
-[If any MANUAL CHECK NEEDED:]
-N criteria need manual verification -- they can't be checked by reading code or running tests alone.
 \`\`\`
+## Session Overhead Report
 
-## Step 6: Suggest Next Steps
+### Harness Files
+- CLAUDE.md: [N] lines [PASS \u2264200 / WARN >200]
+- Skills: [N] files, [list any over 200 lines]
 
-Based on the verdict:
+### Plugins
+- Installed: [N] ([list names])
+- Enabled: [N] of [M] installed
+- [If 0: "No plugins \u2014 zero boot cost from plugins."]
 
-- **All PASS:** Suggest committing and opening a PR, or running \`/joycraft-session-end\` to capture discoveries.
-- **Some FAIL:** List the failed criteria and suggest the user fix them, then run \`/joycraft-verify\` again.
-- **MANUAL CHECK NEEDED items:** Explain what needs human eyes and why automation couldn't verify it.
+### MCP Servers
+- Count: [N] ([list names])
+- [If 0: "No MCP servers \u2014 zero boot cost from servers."]
 
-**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.
+### Hooks
+- [N] hook definitions ([list event names])
+
+### Recommendations
+- [Specific, actionable items for anything over threshold]
+- [e.g., "CLAUDE.md is 312 lines \u2014 consider splitting reference sections into docs/"]
+- [e.g., "3 MCP servers load at boot \u2014 disable unused ones in settings.json"]
+\`\`\`
+
+## Step 6: Further Resources
+
+End with:
+
+> For deeper token optimization, see:
+> - [Nate B Jones's token optimization techniques](https://www.youtube.com/watch?v=bDcgHzCBgmQ)
+> - [OB1 repo](https://github.com/nate-b-j/OB1) \u2014 Heavy File Ingestion skill and stupid button prompt kit
+> - [Joycraft's token discipline guide](docs/guides/token-discipline.md)
 
 ## Edge Cases
 
 | Scenario | Behavior |
 |----------|----------|
-| 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 |
-| All tests pass but a criterion is not testable | Mark as MANUAL CHECK NEEDED with explanation |
-| Subagent can't run tests (missing deps) | Report the error as FAIL evidence |
-| No specs found and no path given | Tell user to provide a spec path or create a spec first |
-| Spec status is "Complete" | Still run verification -- "Complete" means the implementer thinks it's done, verification confirms |
+| Config files don't exist | Report "not found" for that check, don't error |
+| No plugins installed | Report 0 plugins \u2014 this is good, say so |
+| CLAUDE.md/AGENTS.md exactly 200 lines | PASS \u2014 threshold is \u2264200 |
+| \`~/.claude/\` or \`~/.codex/\` not accessible | Skip user-level checks, note limitation |
+| Both platforms detected | Run both audits, report separately |
 `,
-  "joycraft-bugfix.md": `---
-name: joycraft-bugfix
-description: Structured bug fix workflow \u2014 triage, diagnose, discuss with user, write a focused spec, hand off for implementation
-instructions: 32
+  "joycraft-research.md": `---
+name: joycraft-research
+description: Produce objective codebase research by isolating question generation from fact-gathering \u2014 subagent sees only questions, never the brief
 ---
 
-# Bug Fix Workflow
+# Research Codebase for a Feature
 
-You are fixing a bug. Follow this process in order. Do not skip steps.
+You 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.
 
-**Guard clause:** If this is clearly a new feature, redirect to \`/joycraft-new-feature\` and stop.
+**Guard clause:** If the user doesn't provide a brief path or inline description, ask:
+"What feature or change are you researching? Provide a brief path (e.g., \`docs/briefs/2026-03-30-my-feature.md\`) or describe it in a few sentences."
 
 ---
 
-## Phase 1: Triage
+## Phase 1: Generate Research Questions
 
-Establish 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.
+Read the brief file (if a path was provided) or use the user's inline description.
 
-**Done when:** You can describe the symptom in one sentence.
+Identify which zones of the codebase are relevant to this feature. Then generate 5-10 research questions that are:
 
----
+- **Objective and fact-seeking** \u2014 "How does X work?" not "How should we build X?"
+- **Specific to the codebase** \u2014 reference concrete systems, files, or flows
+- **Answerable by reading code** \u2014 no questions about business strategy or user preferences
 
-## Phase 2: Diagnose
+Good examples:
+- "How does endpoint registration work in the current router?"
+- "What patterns exist for input validation across existing handlers?"
+- "Trace the data flow from API request to database write for entity X."
+- "What test infrastructure exists? Where are fixtures, mocks, and helpers?"
+- "What dependencies does module Y import, and what does its public API look like?"
 
-Find 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.
+Bad examples (do NOT generate these):
+- "What's the best way to implement this feature?" (opinion)
+- "Should we use library X or Y?" (recommendation)
+- "What would a good architecture look like?" (design, not research)
 
-**Done when:** You can explain what's wrong, why, and where in 2-3 sentences.
+Write the questions to a temporary file at \`docs/research/.questions-tmp.md\`. Create the \`docs/research/\` directory if it doesn't exist.
+
+**Do NOT include any content from the brief in this file \u2014 only the questions.**
 
 ---
 
-## Phase 3: Discuss
+## Phase 2: Spawn Research Subagent
 
-Present findings to the user BEFORE writing any code or spec:
-1. **Symptom** \u2014 confirm it matches what they see
-2. **Root cause** \u2014 specific file(s) and line(s)
-3. **Proposed fix** \u2014 what changes, where
-4. **Risk** \u2014 side effects? scope?
+Use Claude Code's Agent tool to spawn a subagent. Pass ONLY the research questions \u2014 never the brief path, brief content, or feature description.
 
-Ask: "Does this match? Comfortable with this approach?" If large/risky, suggest decomposing into multiple specs.
+Build the subagent prompt by reading the questions file you just wrote, then use this template:
 
-**Done when:** User agrees with the diagnosis and fix direction.
+\`\`\`
+You 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.
+
+RULES \u2014 these are hard constraints:
+- Answer each question with FACTS ONLY: file paths, function signatures, data flows, patterns, dependencies
+- Do NOT recommend, suggest, or opine on anything
+- Do NOT speculate about what should be built or how
+- If a question cannot be answered (no relevant code exists), say "No existing code found for this"
+- Use the Read tool and Grep tool to explore the codebase thoroughly
+- Include code snippets only when they are essential evidence (e.g., a function signature, a config block)
+
+QUESTIONS:
+[INSERT_QUESTIONS_HERE]
+
+OUTPUT FORMAT \u2014 write your findings as a single markdown document using this structure:
+
+# Codebase Research
+
+**Date:** [today's date]
+**Questions answered:** [N/total]
 
 ---
 
-## Phase 4: Spec the Fix
+## Q1: [question text]
 
-Write a bug fix spec to \`docs/specs/YYYY-MM-DD-bugfix-name.md\`. Create the \`docs/specs/\` directory if it doesn't exist.
+[Facts, file paths, function signatures, data flows. No opinions.]
 
-**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.
+## Q2: [question text]
 
-Use this template:
+[Facts, file paths, function signatures, data flows. No opinions.]
 
-\`\`\`markdown
-# Fix [Bug Description] \u2014 Bug Fix Spec
+[Continue for all questions]
+\`\`\`
 
-> **Parent Brief:** none (bug fix)
-> **Issue/Error:** [error message, issue link, or symptom description]
-> **Status:** Ready
-> **Date:** YYYY-MM-DD
-> **Estimated scope:** [1 session / N files / ~N lines]
+## Phase 3: Write the Research Document
+
+Take the subagent's response and write it to \`docs/research/YYYY-MM-DD-feature-name.md\`. Derive the feature name from the brief filename or the user's description (lowercase, hyphenated).
+
+Delete the temporary questions file (\`docs/research/.questions-tmp.md\`).
+
+Present the research document path to the user:
+
+\`\`\`
+Research complete: docs/research/YYYY-MM-DD-feature-name.md
+
+This document contains objective facts about your codebase \u2014 no opinions or recommendations.
+
+Next steps:
+- /joycraft-decompose \u2014 break the feature into atomic specs (research will inform the specs)
+- /joycraft-new-feature \u2014 formalize into a full Feature Brief first
+- Read the research and add any corrections or missing context manually
+\`\`\`
 
+## Edge Cases
+
+| Scenario | Behavior |
+|----------|----------|
+| No brief provided | Accept inline description, generate questions from that |
+| Codebase is empty or new | Research doc reports "no existing patterns found" per question |
+| User runs research twice for same feature | Overwrites previous research doc (same filename) |
+| Brief is very short (1-2 sentences) | Still generate questions \u2014 even simple features benefit from understanding existing patterns |
+| \`docs/research/\` doesn't exist | Create it |
+`,
+  "joycraft-session-end.md": `---
+name: joycraft-session-end
+description: Wrap up a session \u2014 capture discoveries, verify, prepare for PR or next session
+instructions: 22
 ---
 
-## Bug
+# Session Wrap-Up
 
-What is broken? Describe the symptom the user experiences.
+Before ending this session, complete these steps in order.
 
-## Root Cause
+## 1. Capture Discoveries
 
-What is wrong in the code and why? Name the specific file(s) and line(s).
+**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.
 
-## Fix
+Check: did anything surprising happen during this session? If yes, create or update a discovery file at \`docs/discoveries/YYYY-MM-DD-topic.md\`. Create the \`docs/discoveries/\` directory if it doesn't exist.
 
-What changes will fix this? Be specific \u2014 describe the code change, not just "fix the bug."
+Only capture what's NOT obvious from the code or git diff:
+- "We thought X but found Y" \u2014 assumptions that were wrong
+- "This API/library behaves differently than documented" \u2014 external gotchas
+- "This edge case needs handling in a future spec" \u2014 deferred work with context
+- "The approach in the spec didn't work because..." \u2014 spec-vs-reality gaps
+- Key decisions made during implementation that aren't in the spec
 
-## Acceptance Criteria
+**Do NOT capture:**
+- Files changed (that's the diff)
+- What you set out to do (that's the spec)
+- Step-by-step narrative of the session (nobody re-reads these)
 
-- [ ] [The bug no longer occurs \u2014 describe the correct behavior]
-- [ ] [No regressions in related functionality]
-- [ ] Build passes
-- [ ] Tests pass
+Use this format:
 
-## Test Plan
+\`\`\`markdown
+# Discoveries \u2014 [topic]
 
-| Acceptance Criterion | Test | Type |
-|---------------------|------|------|
-| [Bug no longer occurs] | [Test that reproduces the bug, then verifies the fix] | [unit/integration/e2e] |
-| [No regressions] | [Existing tests still pass, or new regression test] | [unit/integration] |
+**Date:** YYYY-MM-DD
+**Spec:** [link to spec if applicable]
 
-**Execution order:**
-1. Write a test that reproduces the bug \u2014 it should FAIL (red)
-2. Run the test to confirm it fails
-3. Apply the fix
-4. Run the test to confirm it passes (green)
-5. Run the full test suite to check for regressions
+## [Discovery title]
+**Expected:** [what we thought would happen]
+**Actual:** [what actually happened]
+**Impact:** [what this means for future work]
+\`\`\`
 
-**Smoke test:** [The bug reproduction test \u2014 fastest way to verify the fix works]
+If nothing surprising happened, skip the discovery file entirely. No discovery is a good sign \u2014 the spec was accurate.
 
-**Before implementing, verify your test harness:**
-1. Run the reproduction test \u2014 it must FAIL (if it passes, you're not testing the actual bug)
-2. The test must exercise your actual code \u2014 not a reimplementation or mock
-3. Identify your smoke test \u2014 it must run in seconds, not minutes
+## 1b. Update Context Documents
 
-## Constraints
+If \`docs/context/\` exists, quickly check whether this session revealed anything about:
 
-- MUST: [any hard requirements for the fix]
-- MUST NOT: [any prohibitions \u2014 e.g., don't change the public API]
+- **Production risks** \u2014 did you interact with or learn about production vs staging systems? \u2192 Update \`docs/context/production-map.md\`
+- **Wrong assumptions** \u2014 did the agent (or you) assume something that turned out to be false? \u2192 Update \`docs/context/dangerous-assumptions.md\`
+- **Key decisions** \u2014 did you make an architectural or tooling choice? \u2192 Add a row to \`docs/context/decision-log.md\`
+- **Unwritten rules** \u2014 did you discover a convention or constraint not documented anywhere? \u2192 Update \`docs/context/institutional-knowledge.md\`
 
-## Affected Files
+Skip this if nothing applies. Don't force it \u2014 only update when there's genuine new context.
 
-| Action | File | What Changes |
-|--------|------|-------------|
+## 2. Run Validation
 
-## Edge Cases
+Run the project's validation commands. Check CLAUDE.md for project-specific commands. Common checks:
 
-| Scenario | Expected Behavior |
-|----------|------------------|
-\`\`\`
+- Type-check (e.g., \`tsc --noEmit\`, \`mypy\`, \`cargo check\`)
+- Tests (e.g., \`npm test\`, \`pytest\`, \`cargo test\`)
+- Lint (e.g., \`eslint\`, \`ruff\`, \`clippy\`)
 
-**For trivial bugs:** The spec will be short. That's fine \u2014 the structure is the point, not the length.
+Fix any failures before proceeding.
 
-**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.
+## 3. Update Spec Status
 
----
+If working from an atomic spec in \`docs/specs/\` (scan recursively \u2014 specs may be in subdirectories like \`docs/specs/<feature-name>/\`):
+- All acceptance criteria met \u2014 update status to \`Complete\`
+- Partially done \u2014 update status to \`In Progress\`, note what's left
 
-## Phase 5: Hand Off
+If working from a Feature Brief in \`docs/briefs/\`, check off completed specs in the decomposition table.
 
-Tell the user:
+## 4. Commit
 
-\`\`\`
-Bug fix spec is ready: docs/specs/YYYY-MM-DD-bugfix-name.md
+Commit all changes including the discovery file (if created) and spec status updates. The commit message should reference the spec if applicable.
 
-Summary:
-- Bug: [one sentence]
-- Root cause: [one sentence]
-- Fix: [one sentence]
-- Estimated: 1 session
+## 5. Push and PR (if autonomous git is enabled)
 
-To execute: Start a fresh session and:
-1. Read the spec
-2. Write the reproduction test (must fail)
-3. Apply the fix (test must pass)
-4. Run full test suite
-5. Run /joycraft-session-end to capture discoveries
-6. Commit and PR
+**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":
 
-Ready to start?
+1. **Push immediately.** Run \`git push origin <branch>\` \u2014 do not ask, do not hesitate.
+2. **Open a PR if the feature is complete.** Check the parent Feature Brief's decomposition table \u2014 if all specs are done, run \`gh pr create\` with a summary of all completed specs. Do not ask first.
+3. **If not all specs are done,** still push. The PR comes when the last spec is complete.
+
+If CLAUDE.md does NOT have autonomous git rules (or has "ASK FIRST" for pushing), ask the user before pushing.
+
+## 6. Report
+
+\`\`\`
+Session complete.
+- Spec: [spec name] \u2014 [Complete / In Progress]
+- Build: [passing / failing]
+- Discoveries: [N items / none]
+- Pushed: [yes / no \u2014 and why not]
+- PR: [opened #N / not yet \u2014 N specs remaining]
+- Next: [what the next session should tackle]
 \`\`\`
 
-**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.
+**Tip:** Run \`/clear\` before starting the next step. Your artifacts are saved to files \u2014 this conversation context is disposable.
 `,
-  "joycraft-design.md": `---
-name: joycraft-design
-description: Design discussion before decomposition \u2014 produce a ~200-line design artifact for human review, catching wrong assumptions before they propagate into specs
+  "joycraft-tune.md": `---
+name: joycraft-tune
+description: Assess and upgrade your project's AI development harness \u2014 score 7 dimensions, apply fixes, show path to Level 5
+instructions: 15
 ---
 
-# Design Discussion
-
-You 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.
-
-**Guard clause:** If no brief path is provided and no brief exists in \`docs/briefs/\`, say:
-"No feature brief found. Run \`/joycraft-new-feature\` first to create one, or provide the path to your brief."
-Then stop.
+# Tune \u2014 Project Harness Assessment & Upgrade
 
----
+You are evaluating and upgrading this project's AI development harness.
 
-## Step 1: Read Inputs
+## Step 1: Detect Harness State
 
-Read 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.
+Check for: CLAUDE.md (with meaningful content), \`docs/specs/\`, \`docs/briefs/\`, \`docs/discoveries/\`, \`.claude/skills/\`, and test configuration.
 
-## Step 2: Explore the Codebase
+## Step 2: Route
 
-Spawn subagents to explore the codebase for patterns relevant to the brief. Focus on:
+- **No harness** (no CLAUDE.md or just a README): Recommend \`npx joycraft init\` and stop.
+- **Harness exists**: Continue to assessment.
 
-- Files and functions that will be touched or extended
-- Existing patterns this feature should follow (naming, data flow, error handling)
-- Similar features already implemented that serve as models
-- Boundaries and interfaces the feature must integrate with
+## Step 3: Assess \u2014 Score 7 Dimensions (1-5 scale)
 
-Gather file paths, function signatures, and code snippets. You need concrete evidence, not guesses.
+Read CLAUDE.md and explore the project. Score each with specific evidence:
 
-## Step 3: Write the Design Document
+| Dimension | What to Check |
+|-----------|--------------|
+| Spec Quality | \`docs/specs/\` (scan recursively) \u2014 structured? acceptance criteria? self-contained? |
+| Spec Granularity | Can each spec be done in one session? |
+| Behavioral Boundaries | ALWAYS/ASK FIRST/NEVER sections (or equivalent rules under any heading) |
+| Skills & Hooks | \`.claude/skills/\` files, hooks config |
+| Documentation | \`docs/\` structure, templates, referenced from CLAUDE.md |
+| Knowledge Capture | \`docs/discoveries/\`, \`docs/context/*.md\` \u2014 existence AND real content |
+| Testing & Validation | Test framework, CI pipeline, validation commands in CLAUDE.md |
 
-Create \`docs/designs/\` directory if it doesn't exist. Write the design document to \`docs/designs/YYYY-MM-DD-feature-name.md\`.
+Score 1 = absent, 3 = partially there, 5 = comprehensive. Give credit for substance over format.
 
-The document has exactly five sections:
+## Step 4: Write Assessment
 
-### Section 1: Current State
+Write 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).
 
-What 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.
+## Step 5: Apply Upgrades
 
-### Section 2: Desired End State
+Apply using three tiers \u2014 do NOT ask per-item permission:
 
-What 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."
+**Tier 1 (silent):** Create missing dirs, install missing skills, copy missing templates, create AGENTS.md.
 
-### Section 3: Patterns to Follow
+**Before Tier 2, ask TWO things:**
 
-Existing 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.
+1. **Git autonomy:** Cautious (ask before push/PR) or Autonomous (push + PR without asking)?
+2. **Risk interview (3-5 questions, one at a time):** What could break? What services connect to prod? Unwritten rules? Off-limits files/commands? Skip if \`docs/context/\` already has content.
 
-If this is a greenfield project with no existing patterns, propose conventions and note that no precedent exists.
+From answers, generate: CLAUDE.md boundary rules, \`.claude/settings.json\` deny patterns, \`docs/context/\` documents. Also recommend a permission mode (\`auto\` for most; \`dontAsk\` + allowlist for high-risk).
 
-### Section 4: Resolved Design Decisions
+**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.
 
-Decisions you have already made, with brief rationale. Format each as:
+**Tier 3 (confirm first):** Rewriting existing sections, overwriting customized files, suggesting test framework installs.
 
-> **Decision:** [what you decided]
-> **Rationale:** [why, referencing existing code or constraints]
-> **Alternative rejected:** [what you considered and why you rejected it]
+After applying, append to \`docs/joycraft-history.md\` and show a consolidated upgrade results table.
 
-### Section 5: Open Questions
+## Step 6: Show Path to Level 5
 
-Things you don't know or where multiple valid approaches exist. Each question MUST present 2-3 concrete options with pros and cons. Format:
+Show 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).
 
-> **Q: [question]**
-> - **Option A:** [description] \u2014 Pro: [benefit]. Con: [cost].
-> - **Option B:** [description] \u2014 Pro: [benefit]. Con: [cost].
-> - **Option C (if applicable):** [description] \u2014 Pro: [benefit]. Con: [cost].
+## Edge Cases
 
-Do NOT ask vague questions like "what do you think?" Every question must have actionable options the human can choose from.
+- **CLAUDE.md is just a README:** Treat as no harness.
+- **Non-Joycraft skills:** Acknowledge, don't replace.
+- **Rules under non-standard headings:** Give credit for substance.
+- **Previous assessment exists:** Read it first. If nothing to upgrade, say so.
+- **Non-Joycraft content in CLAUDE.md:** Preserve as-is. Only append.
 
-## Step 4: Present and STOP
+**Tip:** Run \`/joycraft-optimize\` to audit your session's token overhead \u2014 plugins, MCP servers, and harness file sizes.
+`,
+  "joycraft-verify.md": `---
+name: joycraft-verify
+description: Spawn an independent verifier subagent to check an implementation against its spec -- read-only, no code edits, structured pass/fail verdict
+instructions: 30
+---
 
-Present the design document to the user. Say:
+# Verify Implementation Against Spec
 
-\`\`\`
-Design discussion written to docs/designs/YYYY-MM-DD-feature-name.md
+The 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.
 
-Please review the document above. Specifically:
-1. Are the patterns in Section 3 the right ones to follow, or should I use different ones?
-2. Do you agree with the resolved decisions in Section 4?
-3. Pick an option for each open question in Section 5 (or propose your own).
+**Why a separate subagent?** Anthropic's 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.
 
-Reply with your feedback. I will NOT proceed to decomposition until you have reviewed and approved this design.
-\`\`\`
+## Step 1: Find the Spec
 
-**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.
+If the user provided a spec path (e.g., \`/joycraft-verify docs/specs/my-feature/add-widget.md\`), use that path directly.
 
-## After Human Review
+If no path was provided, scan \`docs/specs/\` recursively for spec files (they may be in subdirectories like \`docs/specs/<feature-name>/\`). Pick the most recently modified \`.md\` file. If \`docs/specs/\` doesn't exist or is empty, tell the user:
 
-Once the human responds:
-- Update the design document with their corrections and chosen options
-- Move answered questions from "Open Questions" to "Resolved Design Decisions"
-- Present the updated document for final confirmation
-- Only after explicit approval, tell the user: "Design approved. Run \`/joycraft-decompose\` with this brief to generate atomic specs."
-`,
-  "joycraft-research.md": `---
-name: joycraft-research
-description: Produce objective codebase research by isolating question generation from fact-gathering \u2014 subagent sees only questions, never the brief
----
+> No specs found in \`docs/specs/\`. Please provide a spec path: \`/joycraft-verify path/to/spec.md\`
 
-# Research Codebase for a Feature
+## Step 2: Read and Parse the Spec
 
-You 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.
+Read the spec file and extract:
 
-**Guard clause:** If the user doesn't provide a brief path or inline description, ask:
-"What feature or change are you researching? Provide a brief path (e.g., \`docs/briefs/2026-03-30-my-feature.md\`) or describe it in a few sentences."
+1. **Spec name** -- from the H1 title
+2. **Acceptance Criteria** -- the checklist under the \`## Acceptance Criteria\` section
+3. **Test Plan** -- the table under the \`## Test Plan\` section, including any test commands
+4. **Constraints** -- the \`## Constraints\` section if present
 
----
+If the spec has no Acceptance Criteria section, tell the user:
 
-## Phase 1: Generate Research Questions
+> This spec doesn't have an Acceptance Criteria section. Verification needs criteria to check against. Add acceptance criteria to the spec and try again.
 
-Read the brief file (if a path was provided) or use the user's inline description.
+If 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.
 
-Identify which zones of the codebase are relevant to this feature. Then generate 5-10 research questions that are:
+## Step 3: Identify Test Commands
 
-- **Objective and fact-seeking** \u2014 "How does X work?" not "How should we build X?"
-- **Specific to the codebase** \u2014 reference concrete systems, files, or flows
-- **Answerable by reading code** \u2014 no questions about business strategy or user preferences
+Look for test commands in these locations (in priority order):
 
-Good examples:
-- "How does endpoint registration work in the current router?"
-- "What patterns exist for input validation across existing handlers?"
-- "Trace the data flow from API request to database write for entity X."
-- "What test infrastructure exists? Where are fixtures, mocks, and helpers?"
-- "What dependencies does module Y import, and what does its public API look like?"
+1. The spec's Test Plan section (look for commands in backticks or "Type" column entries like "unit", "integration", "e2e", "build")
+2. The project's CLAUDE.md (look for test/build commands in the Development Workflow section)
+3. Common defaults based on the project type:
+   - Node.js: \`npm test\` or \`pnpm test --run\`
+   - Python: \`pytest\`
+   - Rust: \`cargo test\`
+   - Go: \`go test ./...\`
 
-Bad examples (do NOT generate these):
-- "What's the best way to implement this feature?" (opinion)
-- "Should we use library X or Y?" (recommendation)
-- "What would a good architecture look like?" (design, not research)
+Build a list of specific commands the verifier should run.
 
-Write the questions to a temporary file at \`docs/research/.questions-tmp.md\`. Create the \`docs/research/\` directory if it doesn't exist.
+## Step 4: Spawn the Verifier Subagent
 
-**Do NOT include any content from the brief in this file \u2014 only the questions.**
+Use Claude Code's Agent tool to spawn a subagent with the following prompt. Replace the placeholders with the actual content extracted in Steps 2-3.
 
----
+\`\`\`
+You 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.
 
-## Phase 2: Spawn Research Subagent
+RULES -- these are hard constraints, not suggestions:
+- You may READ any file using the Read tool or cat
+- You may RUN these specific test/build commands: [TEST_COMMANDS]
+- You may NOT edit, create, or delete any files
+- You may NOT run commands that modify state (no git commit, no npm install, no file writes)
+- You may NOT install packages or access the network
+- Report what you OBSERVE, not what you expect or hope
 
-Use Claude Code's Agent tool to spawn a subagent. Pass ONLY the research questions \u2014 never the brief path, brief content, or feature description.
+SPEC NAME: [SPEC_NAME]
 
-Build the subagent prompt by reading the questions file you just wrote, then use this template:
+ACCEPTANCE CRITERIA:
+[ACCEPTANCE_CRITERIA]
 
-\`\`\`
-You 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.
+TEST PLAN:
+[TEST_PLAN]
 
-RULES \u2014 these are hard constraints:
-- Answer each question with FACTS ONLY: file paths, function signatures, data flows, patterns, dependencies
-- Do NOT recommend, suggest, or opine on anything
-- Do NOT speculate about what should be built or how
-- If a question cannot be answered (no relevant code exists), say "No existing code found for this"
-- Use the Read tool and Grep tool to explore the codebase thoroughly
-- Include code snippets only when they are essential evidence (e.g., a function signature, a config block)
+CONSTRAINTS:
+[CONSTRAINTS_OR_NONE]
 
-QUESTIONS:
-[INSERT_QUESTIONS_HERE]
+YOUR TASK:
+For each acceptance criterion, determine if it PASSES or FAILS based on evidence:
 
-OUTPUT FORMAT \u2014 write your findings as a single markdown document using this structure:
+1. Run the test commands listed above. Record the output.
+2. For each acceptance criterion:
+   a. Check if there is a corresponding test and whether it passes
+   b. If no test exists, read the relevant source files to verify the criterion is met
+   c. If the criterion cannot be verified by reading code or running tests, mark it MANUAL CHECK NEEDED
+3. For criteria about build/test passing, actually run the commands and report results.
 
-# Codebase Research
+OUTPUT FORMAT -- you MUST use this exact format:
 
-**Date:** [today's date]
-**Questions answered:** [N/total]
+VERIFICATION REPORT
 
----
+| # | Criterion | Verdict | Evidence |
+|---|-----------|---------|----------|
+| 1 | [criterion text] | PASS/FAIL/MANUAL CHECK NEEDED | [what you observed] |
+| 2 | [criterion text] | PASS/FAIL/MANUAL CHECK NEEDED | [what you observed] |
+[continue for all criteria]
 
-## Q1: [question text]
+SUMMARY: X/Y criteria passed. [Z failures need attention. / All criteria verified.]
 
-[Facts, file paths, function signatures, data flows. No opinions.]
+If any test commands fail to run (missing dependencies, wrong command, etc.), report the error as evidence for a FAIL verdict on the relevant criterion.
+\`\`\`
 
-## Q2: [question text]
+## Step 5: Format and Present the Verdict
 
-[Facts, file paths, function signatures, data flows. No opinions.]
+Take the subagent's response and present it to the user in this format:
 
-[Continue for all questions]
 \`\`\`
+## Verification Report -- [Spec Name]
 
-## Phase 3: Write the Research Document
+| # | Criterion | Verdict | Evidence |
+|---|-----------|---------|----------|
+| 1 | ... | PASS | ... |
+| 2 | ... | FAIL | ... |
 
-Take the subagent's response and write it to \`docs/research/YYYY-MM-DD-feature-name.md\`. Derive the feature name from the brief filename or the user's description (lowercase, hyphenated).
+**Overall: X/Y criteria passed.**
 
-Delete the temporary questions file (\`docs/research/.questions-tmp.md\`).
+[If all passed:]
+All criteria verified. Ready to commit and open a PR.
 
-Present the research document path to the user:
+[If any failed:]
+N failures need attention. Review the evidence above and fix before proceeding.
 
+[If any MANUAL CHECK NEEDED:]
+N criteria need manual verification -- they can't be checked by reading code or running tests alone.
 \`\`\`
-Research complete: docs/research/YYYY-MM-DD-feature-name.md
 
-This document contains objective facts about your codebase \u2014 no opinions or recommendations.
+## Step 6: Suggest Next Steps
 
-Next steps:
-- /joycraft-decompose \u2014 break the feature into atomic specs (research will inform the specs)
-- /joycraft-new-feature \u2014 formalize into a full Feature Brief first
-- Read the research and add any corrections or missing context manually
-\`\`\`
+Based on the verdict:
+
+- **All PASS:** Suggest committing and opening a PR, or running \`/joycraft-session-end\` to capture discoveries.
+- **Some FAIL:** List the failed criteria and suggest the user fix them, then run \`/joycraft-verify\` again.
+- **MANUAL CHECK NEEDED items:** Explain what needs human eyes and why automation couldn't verify it.
+
+**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.
 
 ## Edge Cases
 
 | Scenario | Behavior |
 |----------|----------|
-| No brief provided | Accept inline description, generate questions from that |
-| Codebase is empty or new | Research doc reports "no existing patterns found" per question |
-| User runs research twice for same feature | Overwrites previous research doc (same filename) |
-| Brief is very short (1-2 sentences) | Still generate questions \u2014 even simple features benefit from understanding existing patterns |
-| \`docs/research/\` doesn't exist | Create it |
+| 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 |
+| All tests pass but a criterion is not testable | Mark as MANUAL CHECK NEEDED with explanation |
+| Subagent can't run tests (missing deps) | Report the error as FAIL evidence |
+| No specs found and no path given | Tell user to provide a spec path or create a spec first |
+| Spec status is "Complete" | Still run verification -- "Complete" means the implementer thinks it's done, verification confirms |
 `
 };
 var TEMPLATES = {
@@ -1984,59 +2038,13 @@ is required, though you can add one via the GitHub Checks API if you prefer.
 
 ---
 
-## Testing by Stack Type
-
-The scenario agent selects the appropriate test format based on the project's
-testing backbone. Each backbone tests the same holdout principle \u2014 observable
-behavior only, no source imports \u2014 but uses different tools.
-
-### Web Apps (Playwright)
-
-For Next.js, Vite, Nuxt, Remix, and other web frameworks. Tests run against a
-dev server or preview URL using a headless browser.
-
-- **Template:** \`example-scenario-web.spec.ts\`
-- **Config:** \`playwright.config.ts\`
-- **Package:** \`package-web.json\` (use instead of \`package.json\` for web projects)
-- **Run:** \`npx playwright test\`
-
-### Mobile Apps (Maestro)
-
-For React Native, Flutter, and native iOS/Android. Tests are declarative YAML
-flows that interact with a running app on a simulator.
-
-- **Template:** \`example-scenario-mobile.yaml\`
-- **Login sub-flow:** \`example-scenario-mobile-login.yaml\`
-- **Setup guide:** \`README-mobile.md\`
-- **Run:** \`maestro test example-scenario-mobile.yaml\`
-
-### API Backends (HTTP)
-
-For Express, FastAPI, Django, and other API-only backends. Tests send HTTP
-requests using Node.js built-in \`fetch\`.
-
-- **Template:** \`example-scenario-api.test.ts\`
-- **Run:** \`npx vitest run\`
-
-### CLI Tools & Libraries (native)
-
-For CLI tools, npm packages, and non-UI projects. Tests invoke the built
-binary via \`spawnSync\` and assert on stdout/stderr.
-
-- **Template:** \`example-scenario.test.ts\`
-- **Run:** \`npx vitest run\`
-
----
-
 ## Adding scenarios
 
 ### Rules
 
-These rules apply to ALL backbones:
-
-1. **Behavioral, not structural.** Test what the app does from a user's
-   perspective. For web: navigate and assert on content. For CLI: run commands
-   and check output. For API: send requests and check responses.
+1. **Behavioral, not structural.** Test what the tool does, not how it is
+   built internally. Invoke the binary; assert on stdout, exit codes, and
+   filesystem state. Never import from \`../main-repo/src\`.
 
 2. **End-to-end.** Each test should represent something a real user would
    actually do. If you would not put it in a demo or docs example, reconsider
@@ -2046,8 +2054,9 @@ These rules apply to ALL backbones:
    see source code. Any \`import\` that reaches into \`../main-repo/src\` breaks
    the pattern.
 
-4. **Independent.** Each test must be able to run in isolation. No shared
-   mutable state between tests.
+4. **Independent.** Each test must be able to run in isolation. Use \`beforeEach\`
+   / \`afterEach\` to set up and tear down temp directories. Do not share mutable
+   state between tests.
 
 5. **Deterministic.** Avoid network calls, timestamps, or random values in
    assertions unless the feature under test genuinely involves them.
@@ -2056,25 +2065,31 @@ These rules apply to ALL backbones:
 
 \`\`\`
 $SCENARIOS_REPO/
-\u251C\u2500\u2500 example-scenario.test.ts           # CLI/binary scenario template
-\u251C\u2500\u2500 example-scenario-web.spec.ts       # Web app scenario template (Playwright)
-\u251C\u2500\u2500 example-scenario-api.test.ts       # API backend scenario template
-\u251C\u2500\u2500 example-scenario-mobile.yaml       # Mobile app scenario template (Maestro)
-\u251C\u2500\u2500 example-scenario-mobile-login.yaml # Reusable login sub-flow
-\u251C\u2500\u2500 playwright.config.ts               # Playwright config (web projects)
-\u251C\u2500\u2500 package.json                       # Default (vitest for CLI/API)
-\u251C\u2500\u2500 package-web.json                   # Alternative (Playwright for web)
-\u251C\u2500\u2500 README-mobile.md                   # Mobile testing setup guide
+\u251C\u2500\u2500 example-scenario.test.ts   # Starter file \u2014 replace with real scenarios
 \u251C\u2500\u2500 workflows/
-\u2502   \u251C\u2500\u2500 run.yml                        # CI workflow (do not rename)
-\u2502   \u2514\u2500\u2500 generate.yml                   # Scenario generation workflow
-\u251C\u2500\u2500 prompts/
-\u2502   \u2514\u2500\u2500 scenario-agent.md              # Scenario agent instructions
+\u2502   \u2514\u2500\u2500 run.yml                # CI workflow (do not rename)
+\u251C\u2500\u2500 package.json
 \u2514\u2500\u2500 README.md
 \`\`\`
 
-Use the template that matches your project's stack. Remove the ones you
-don't need.
+Add new \`.test.ts\` files at the top level or in subdirectories. Vitest will
+discover them automatically.
+
+### Example structure
+
+\`\`\`ts
+import { spawnSync } from "node:child_process";
+import { join } from "node:path";
+
+const CLI = join(__dirname, "..", "main-repo", "dist", "cli.js");
+
+it("init creates a CLAUDE.md file", () => {
+  const tmp = mkdtempSync(join(tmpdir(), "scenario-"));
+  const { status } = spawnSync("node", [CLI, "init", tmp], { encoding: "utf8" });
+  expect(status).toBe(0);
+  expect(existsSync(join(tmp, "CLAUDE.md"))).toBe(true);
+});
+\`\`\`
 
 ---
 
@@ -2086,7 +2101,6 @@ don't need.
 | Visible to agent | Yes | No |
 | What they test | Units, modules, logic | End-to-end behavior |
 | Import source code | Yes | Never |
-| Test method | Unit test framework | Depends on backbone (Playwright/Maestro/vitest/fetch) |
 | Run on every push | Yes | Yes (via dispatch) |
 | Purpose | Catch regressions fast | Validate real behavior |
 
@@ -2235,304 +2249,6 @@ describe("CLI: init command (example \u2014 replace with your real scenarios)",
   }
 }
 `,
-  "scenarios/package-web.json": `{
-  "name": "$SCENARIOS_REPO",
-  "version": "0.0.1",
-  "private": true,
-  "type": "module",
-  "scripts": {
-    "test": "playwright test"
-  },
-  "devDependencies": {
-    "@playwright/test": "^1.50.0"
-  }
-}
-`,
-  "scenarios/playwright.config.ts": `import { defineConfig } from '@playwright/test';
-
-/**
- * Playwright configuration for holdout scenario tests.
- *
- * BASE_URL can be set to test against a preview deployment URL
- * or defaults to http://localhost:3000 for local dev server testing.
- */
-export default defineConfig({
-  testDir: '.',
-  testMatch: '**/*.spec.ts',
-  timeout: 60_000,
-  retries: 0,
-  use: {
-    baseURL: process.env.BASE_URL || 'http://localhost:3000',
-    headless: true,
-    screenshot: 'only-on-failure',
-  },
-  projects: [
-    { name: 'chromium', use: { browserName: 'chromium' } },
-  ],
-});
-`,
-  "scenarios/example-scenario-web.spec.ts": `/**
- * Example Web Scenario Test (Playwright)
- *
- * This file is a template for scenario tests against web applications.
- * The holdout pattern applies: test the running app through its UI,
- * never import source code from the main repo.
- *
- * The main repo is available at ../main-repo and is already built.
- * Tests run against either:
- *   - A dev server started from ../main-repo (default)
- *   - A preview deployment URL (set BASE_URL env var)
- *
- * DO:
- *   - Navigate to pages, click elements, fill forms, assert on visible content
- *   - Use page.locator() with accessible selectors (role, text, test-id)
- *   - Keep each test fully independent
- *
- * DON'T:
- *   - Import from ../main-repo/src \u2014 that defeats the holdout
- *   - Test internal implementation details
- *   - Rely on specific CSS classes or DOM structure (use accessible selectors)
- */
-
-import { test, expect } from '@playwright/test';
-import { spawn, type ChildProcess } from 'node:child_process';
-import { join } from 'node:path';
-
-const MAIN_REPO = join(__dirname, '..', 'main-repo');
-let serverProcess: ChildProcess | undefined;
-
-/**
- * Wait for a URL to become reachable.
- */
-async function waitForServer(url: string, timeoutMs = 60_000): Promise<void> {
-  const start = Date.now();
-  while (Date.now() - start < timeoutMs) {
-    try {
-      const res = await fetch(url);
-      if (res.ok || res.status < 500) return;
-    } catch {
-      // Server not ready yet
-    }
-    await new Promise(r => setTimeout(r, 1000));
-  }
-  throw new Error(\`Server at \${url} did not become ready within \${timeoutMs}ms\`);
-}
-
-test.beforeAll(async () => {
-  // If BASE_URL is set, skip starting a dev server \u2014 test against the provided URL
-  if (process.env.BASE_URL) return;
-
-  serverProcess = spawn('npm', ['run', 'dev'], {
-    cwd: MAIN_REPO,
-    stdio: 'pipe',
-    env: { ...process.env, PORT: '3000' },
-  });
-
-  await waitForServer('http://localhost:3000');
-});
-
-test.afterAll(async () => {
-  if (serverProcess) {
-    serverProcess.kill('SIGTERM');
-    serverProcess = undefined;
-  }
-});
-
-// ---------------------------------------------------------------------------
-// Example scenarios \u2014 replace with real tests for your application
-// ---------------------------------------------------------------------------
-
-test.describe('Home page', () => {
-  test('loads successfully and shows main heading', async ({ page }) => {
-    await page.goto('/');
-    // Replace with your app's actual heading or key element
-    await expect(page.locator('h1')).toBeVisible();
-  });
-
-  test('navigates to a subpage', async ({ page }) => {
-    await page.goto('/');
-    // Replace with your app's actual navigation
-    // await page.click('text=About');
-    // await expect(page).toHaveURL(/\\/about/);
-    // await expect(page.locator('h1')).toContainText('About');
-  });
-});
-`,
-  "scenarios/example-scenario-api.test.ts": `/**
- * Example API Scenario Test
- *
- * This file is a template for scenario tests against API-only backends.
- * The holdout pattern applies: test the running server via HTTP requests,
- * never import route handlers or source code from the main repo.
- *
- * The main repo is available at ../main-repo and is already built.
- * Tests run against either:
- *   - A server started from ../main-repo (default)
- *   - A deployed URL (set BASE_URL env var)
- *
- * Uses Node.js built-in fetch \u2014 no additional HTTP client dependencies.
- *
- * DO:
- *   - Send HTTP requests to endpoints, assert on status codes and response bodies
- *   - Test realistic user actions (create, read, update, delete flows)
- *   - Keep each test fully independent
- *
- * DON'T:
- *   - Import from ../main-repo/src \u2014 that defeats the holdout
- *   - Use supertest or similar tools that import the app directly
- *   - Test internal implementation details
- */
-
-import { describe, it, expect, beforeAll, afterAll } from 'vitest';
-import { spawn, type ChildProcess } from 'node:child_process';
-import { join } from 'node:path';
-
-const MAIN_REPO = join(__dirname, '..', 'main-repo');
-const BASE_URL = process.env.BASE_URL || 'http://localhost:3000';
-let serverProcess: ChildProcess | undefined;
-
-/**
- * Wait for a URL to become reachable.
- */
-async function waitForServer(url: string, timeoutMs = 60_000): Promise<void> {
-  const start = Date.now();
-  while (Date.now() - start < timeoutMs) {
-    try {
-      const res = await fetch(url);
-      if (res.ok || res.status < 500) return;
-    } catch {
-      // Server not ready yet
-    }
-    await new Promise(r => setTimeout(r, 1000));
-  }
-  throw new Error(\`Server at \${url} did not become ready within \${timeoutMs}ms\`);
-}
-
-beforeAll(async () => {
-  // If BASE_URL is set externally, skip starting a server
-  if (process.env.BASE_URL) return;
-
-  serverProcess = spawn('npm', ['start'], {
-    cwd: MAIN_REPO,
-    stdio: 'pipe',
-    env: { ...process.env, PORT: '3000' },
-  });
-
-  await waitForServer(BASE_URL);
-}, 90_000);
-
-afterAll(() => {
-  if (serverProcess) {
-    serverProcess.kill('SIGTERM');
-    serverProcess = undefined;
-  }
-});
-
-// ---------------------------------------------------------------------------
-// Example scenarios \u2014 replace with real tests for your API
-// ---------------------------------------------------------------------------
-
-describe('API health', () => {
-  it('GET / returns a success status', async () => {
-    const res = await fetch(\`\${BASE_URL}/\`);
-    expect(res.status).toBeLessThan(500);
-  });
-});
-
-describe('API endpoints', () => {
-  it('GET /api/example returns JSON', async () => {
-    const res = await fetch(\`\${BASE_URL}/api/example\`);
-    // Replace with your actual endpoint
-    // expect(res.status).toBe(200);
-    // const body = await res.json();
-    // expect(body).toHaveProperty('data');
-  });
-
-  it('POST /api/example creates a resource', async () => {
-    // Replace with your actual endpoint and payload
-    // const res = await fetch(\\\`\\\${BASE_URL}/api/example\\\`, {
-    //   method: 'POST',
-    //   headers: { 'Content-Type': 'application/json' },
-    //   body: JSON.stringify({ name: 'test' }),
-    // });
-    // expect(res.status).toBe(201);
-    // const body = await res.json();
-    // expect(body).toHaveProperty('id');
-  });
-
-  it('returns 404 for unknown routes', async () => {
-    const res = await fetch(\`\${BASE_URL}/api/does-not-exist\`);
-    expect(res.status).toBe(404);
-  });
-});
-`,
-  "scenarios/example-scenario-mobile.yaml": `# Example Mobile Scenario Test (Maestro)
-#
-# This file is a template for scenario tests against mobile applications.
-# The holdout pattern applies: test the running app through its UI,
-# never reference source code from the main repo.
-#
-# Maestro tests are declarative YAML flows that interact with a running
-# app on a simulator/emulator. Install Maestro:
-#   curl -Ls "https://get.maestro.mobile.dev" | bash
-#
-# Run this flow:
-#   maestro test example-scenario-mobile.yaml
-#
-# DO:
-#   - Tap elements, fill inputs, assert on visible text
-#   - Use runFlow for reusable sub-flows (e.g., login)
-#   - Use assertWithAI for natural-language assertions
-#
-# DON'T:
-#   - Reference source code paths or internal identifiers
-#   - Depend on exact pixel positions (use text and accessibility labels)
-
-appId: com.example.myapp  # Replace with your app's bundle identifier
-name: "Core User Journey"
-tags:
-  - smoke
-  - holdout
----
-# Step 1: Launch the app
-- launchApp
-
-# Step 2: Login (using a reusable sub-flow)
-- runFlow: example-scenario-mobile-login.yaml
-
-# Step 3: Verify the main screen loaded
-- assertVisible: "Home"
-
-# Step 4: Navigate to a feature
-# - tapOn: "Settings"
-# - assertVisible: "Account"
-
-# Step 5: AI-powered assertion (natural language)
-# - assertWithAI: "The main dashboard is visible with navigation tabs at the bottom"
-
-# Step 6: Go back
-# - back
-# - assertVisible: "Home"
-`,
-  "scenarios/example-scenario-mobile-login.yaml": `# Reusable Login Sub-Flow (Maestro)
-#
-# This flow handles authentication. Other flows include it via:
-#   - runFlow: example-scenario-mobile-login.yaml
-#
-# Replace the selectors and credentials with your app's actual login flow.
-
-appId: com.example.myapp
-name: "Login"
----
-- assertVisible: "Sign In"
-- tapOn: "Email"
-- inputText: "test@example.com"
-- tapOn: "Password"
-- inputText: "testpassword123"
-- tapOn: "Log In"
-- assertVisible: "Home"  # Verify login succeeded
-`,
-  "scenarios/README-mobile.md": '# Mobile Scenario Testing with Maestro\n\nThis guide explains how to set up and run mobile holdout scenario tests using [Maestro](https://maestro.dev/).\n\n## Prerequisites\n\n- **Maestro CLI:** `curl -Ls "https://get.maestro.mobile.dev" | bash`\n- **Java 17+** (required by Maestro)\n- **Simulator/Emulator:**\n  - iOS: Xcode with iOS Simulator (macOS only)\n  - Android: Android Studio with an AVD configured\n\n> **Important:** Joycraft does not install Maestro or manage simulators. This is your responsibility.\n\n## Running Tests Locally\n\n```bash\n# Boot your simulator/emulator first, then:\nmaestro test example-scenario-mobile.yaml\n\n# Run all flows in a directory:\nmaestro test .maestro/\n```\n\n## Writing Flows\n\nMaestro flows are declarative YAML. Core commands:\n\n| Command | Purpose |\n|---------|--------|\n| `launchApp` | Start or restart the app |\n| `tapOn: "text"` | Tap an element by visible text or test ID |\n| `inputText: "value"` | Type into a focused field |\n| `assertVisible: "text"` | Assert an element is on screen |\n| `assertNotVisible: "text"` | Assert an element is NOT on screen |\n| `scroll` | Scroll down |\n| `back` | Press the back button |\n| `runFlow: file.yaml` | Run a reusable sub-flow |\n| `assertWithAI: "description"` | Natural-language assertion (AI-powered) |\n\n## CI Options\n\n### Option A: Maestro Cloud (paid, easiest)\n\nUpload your app binary and flows to Maestro Cloud. No simulator management.\n\n```yaml\n- uses: mobile-dev-inc/action-maestro-cloud@v2\n  with:\n    api-key: ${{ secrets.MAESTRO_API_KEY }}\n    app-file: app.apk  # or app.ipa\n    workspace: .\n```\n\n### Option B: Self-hosted emulator (free, more setup)\n\nSpin up an Android emulator on a Linux runner or iOS simulator on a macOS runner.\n\n> **Cost note:** macOS GitHub Actions runners are ~10x more expensive than Linux runners.\n\n## The Holdout Pattern\n\nThese tests live in the scenarios repo, separate from the main codebase. The scenario agent generates them from specs. They test observable behavior through the app\'s UI \u2014 never referencing source code or internal implementation.\n',
   "scenarios/prompts/scenario-agent.md": `You are a QA engineer working in a holdout test repository. You CANNOT access the main repository's source code. Your job is to write or update behavioral scenario tests based on specs that are pushed from the main repo.
 
 ## What You Have Access To
@@ -2540,23 +2256,7 @@ name: "Login"
 - This scenarios repository (test files, \`specs/\` mirror, \`package.json\`)
 - The incoming spec (provided below)
 - A list of existing test files and spec mirrors (provided below)
-- The main repo is available at \`../main-repo\` and is already built
-- The testing strategy for this project (provided below)
-
-## Testing Strategy
-
-This project uses the **$TESTING_BACKBONE** testing backbone.
-
-Select the correct test format based on the backbone:
-
-| Backbone | Tool | Test Format | File Extension | How to Test |
-|----------|------|-------------|---------------|-------------|
-| \`playwright\` | Playwright | Browser-based E2E | \`.spec.ts\` | Navigate pages, click elements, assert on visible content |
-| \`maestro\` | Maestro | YAML flows | \`.yaml\` | Tap elements, fill inputs, assert on screen state |
-| \`api\` | fetch (Node.js built-in) | HTTP requests | \`.test.ts\` | Send requests to endpoints, assert on responses |
-| \`native\` | vitest + spawnSync | CLI/binary invocation | \`.test.ts\` | Run commands, assert on stdout/stderr/exit codes |
-
-If the backbone is not provided or unrecognized, default to \`native\`.
+- The main repo is available at \`../main-repo\` and is already built \u2014 you can invoke its CLI or entry point via \`execSync\`/\`spawnSync\`, but you MUST NOT import from \`../main-repo/src\`
 
 ## Triage Decision Tree
 
@@ -2575,7 +2275,7 @@ If you SKIP, write a brief comment in the relevant test file (or a new one) expl
 - A new output format or file that gets generated
 - A new user-facing behavior that doesn't map to any existing test file
 
-Name the file after the feature area using the correct extension for the backbone.
+Name the file after the feature area: \`[feature-area].test.ts\`. One feature area per test file.
 
 ### UPDATE \u2014 Modify an existing test file if the spec:
 - Changes behavior that is already tested
@@ -2586,20 +2286,25 @@ Match to the most relevant existing test file by feature area.
 
 **If you are unsure whether a spec is user-facing, err on the side of writing a test.**
 
-## Test Writing Rules (All Backbones)
+## Test Writing Rules
+
+1. **Behavioral only.** Test observable output \u2014 stdout, stderr, exit codes, files created/modified on disk. Never test internal implementation details or import source modules.
+
+2. **Use \`execSync\` or \`spawnSync\`.** Invoke the built binary at \`../main-repo/dist/cli.js\` (or whatever the main repo's entry point is). Check \`../main-repo/package.json\` to find the correct entry point if unsure.
+
+3. **Use vitest.** Import \`describe\`, \`it\`, \`expect\` from \`vitest\`. Use \`beforeEach\`/\`afterEach\` for temp directory setup/teardown.
 
-1. **Behavioral only.** Test observable behavior \u2014 what a real user would see. Never test internal implementation details or import source modules.
-2. **Each test is fully independent.** No shared mutable state between tests.
-3. **Assert on realistic user actions.** Write tests that reflect what a real user would do.
-4. **Never import from the parent repo's source.** If you find yourself writing \`import { ... } from '../main-repo/src/...'\`, stop \u2014 that defeats the holdout.
+4. **Each test is fully independent.** No shared mutable state between tests. Each test that touches the filesystem gets its own temp directory via \`mkdtempSync\`.
 
-## Backbone: native (CLI/Binary)
+5. **Assert on realistic user actions.** Write tests that reflect what a real user would do \u2014 not what the implementation happens to do.
 
-Use when the project is a CLI tool, library, or has no web/mobile UI.
+6. **Never import from the parent repo's source.** If you find yourself writing \`import { ... } from '../main-repo/src/...'\`, stop \u2014 that defeats the holdout.
+
+## Test File Template
 
 \`\`\`typescript
-import { spawnSync } from 'node:child_process';
-import { mkdtempSync, rmSync } from 'node:fs';
+import { execSync, spawnSync } from 'node:child_process';
+import { existsSync, mkdtempSync, rmSync, readFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { describe, it, expect, beforeEach, afterEach } from 'vitest';
@@ -2612,122 +2317,39 @@ function runCLI(args: string[], cwd?: string) {
     cwd: cwd ?? process.cwd(),
     env: { ...process.env, NO_COLOR: '1' },
   });
-  return { stdout: result.stdout ?? '', stderr: result.stderr ?? '', status: result.status ?? 1 };
+  return {
+    stdout: result.stdout ?? '',
+    stderr: result.stderr ?? '',
+    status: result.status ?? 1,
+  };
 }
 
-describe('[feature area]', () => {
+describe('[feature area]: [behavior being tested]', () => {
   let tmpDir: string;
-  beforeEach(() => { tmpDir = mkdtempSync(join(tmpdir(), 'scenarios-')); });
-  afterEach(() => { rmSync(tmpDir, { recursive: true, force: true }); });
-
-  it('[observable behavior]', () => {
-    const { stdout, status } = runCLI(['command', 'args'], tmpDir);
-    expect(status).toBe(0);
-    expect(stdout).toContain('expected output');
-  });
-});
-\`\`\`
-
-## Backbone: playwright (Web Apps)
 
-Use when the project is a web application (Next.js, Vite, Nuxt, etc.).
-
-\`\`\`typescript
-import { test, expect } from '@playwright/test';
-
-// Tests run against BASE_URL (configured in playwright.config.ts)
-// The dev server is started automatically or BASE_URL points to a preview deploy
-
-test.describe('[feature area]', () => {
-  test('[observable behavior]', async ({ page }) => {
-    await page.goto('/');
-    await expect(page.locator('h1')).toBeVisible();
-  });
-
-  test('[user interaction]', async ({ page }) => {
-    await page.goto('/login');
-    await page.fill('[name="email"]', 'test@example.com');
-    await page.click('button[type="submit"]');
-    await expect(page).toHaveURL(/dashboard/);
+  beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), 'scenarios-'));
   });
-});
-\`\`\`
-
-## Backbone: api (API Backends)
-
-Use when the project is an API-only backend (Express, FastAPI, etc.).
-
-\`\`\`typescript
-import { describe, it, expect } from 'vitest';
-
-const BASE_URL = process.env.BASE_URL || 'http://localhost:3000';
 
-describe('[feature area]', () => {
-  it('[endpoint behavior]', async () => {
-    const res = await fetch(\\\`\\\${BASE_URL}/api/endpoint\\\`);
-    expect(res.status).toBe(200);
-    const body = await res.json();
-    expect(body).toHaveProperty('data');
+  afterEach(() => {
+    rmSync(tmpDir, { recursive: true, force: true });
   });
 
-  it('[error handling]', async () => {
-    const res = await fetch(\\\`\\\${BASE_URL}/api/not-found\\\`);
-    expect(res.status).toBe(404);
+  it('[specific observable behavior]', () => {
+    const { stdout, status } = runCLI(['command', 'args'], tmpDir);
+    expect(status).toBe(0);
+    expect(stdout).toContain('expected output');
   });
 });
 \`\`\`
 
-## Backbone: maestro (Mobile Apps)
-
-Use when the project is a mobile application (React Native, Flutter, native iOS/Android).
-
-\`\`\`yaml
-appId: com.example.myapp
-name: "[feature area]: [behavior being tested]"
-tags:
-  - holdout
----
-- launchApp
-- tapOn: "Sign In"
-- inputText: "test@example.com"
-- tapOn: "Submit"
-- assertVisible: "Welcome"
-# Use assertWithAI for complex visual assertions:
-# - assertWithAI: "The dashboard shows a list of recent items"
-\`\`\`
-
-## Graceful Degradation
-
-If the primary backbone tool is not available in this repo, fall back to the next deepest testable layer:
-
-| Layer | What's Tested | When to Use |
-|-------|-------------|-------------|
-| **Layer 4: UI** | Full user flows through browser/simulator | \`@playwright/test\` or Maestro is installed |
-| **Layer 3: API** | HTTP requests against running server | Server can be started from \`../main-repo\` |
-| **Layer 2: Logic** | Unit tests via test runner | Test runner (vitest/jest) is available |
-| **Layer 1: Static** | Build, typecheck, lint | Build toolchain is available |
-
-**Fallback rules:**
-- If backbone is \`playwright\` but \`@playwright/test\` is NOT in this repo's \`package.json\`: fall back to \`api\` (fetch-based HTTP tests)
-- If backbone is \`maestro\` but no simulator context is available: fall back to \`api\` if a server can be started, else \`native\`
-- If backbone is \`api\` but no server start script exists: fall back to \`native\`
-- \`native\` is always available as the floor
-
-Start each test file with a comment indicating the testing layer:
-\`// Testing Layer: [4|3|2|1] - [UI|API|Logic|Static]\`
-
-If you fell back from the intended backbone, note this in your commit message:
-\`scenarios: [action] for [spec] (layer: [N], reason: [why])\`
-
 ## Checklist Before Committing
 
 - [ ] Decision: SKIP / NEW / UPDATE (and why)
-- [ ] Correct backbone selected (or fallback justified)
 - [ ] Tests assert on observable behavior, not implementation
 - [ ] No imports from \`../main-repo/src\`
-- [ ] Each test is independent (own temp dir, own state)
-- [ ] File uses the correct extension for the backbone
-- [ ] Testing layer comment at top of file
+- [ ] Each test has its own temp directory if it touches the filesystem
+- [ ] File is named after the feature area, not the spec
 `,
   "scenarios/workflows/generate.yml": `# Scenario Generation Workflow
 #
@@ -2827,9 +2449,7 @@ jobs:
           ## Context
 
           Existing test files in this repo: \${{ steps.context.outputs.existing_tests }}
-          Existing spec mirrors: \${{ steps.context.outputs.existing_specs }}
-
-          Testing backbone: \${{ github.event.client_payload.testing_backbone || 'native' }}"
+          Existing spec mirrors: \${{ steps.context.outputs.existing_specs }}"
 
       # \u2500\u2500 7. Commit any changes the agent made \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
       - name: Commit scenario changes
@@ -3355,7 +2975,7 @@ jobs:
       - name: Find changed specs
         id: changed
         run: |
-          FILES=$(git diff --name-only --diff-filter=AM HEAD~1 HEAD -- 'docs/specs/*.md')
+          FILES=$(git diff --name-only --diff-filter=AM HEAD~1 HEAD -- 'docs/specs/**/*.md')
           echo "files<<EOF" >> "$GITHUB_OUTPUT"
           echo "$FILES" >> "$GITHUB_OUTPUT"
           echo "EOF" >> "$GITHUB_OUTPUT"
@@ -3398,48 +3018,6 @@ jobs:
               -f "client_payload[repo]=\${{ github.repository }}"
 
           done <<< "\${{ steps.changed.outputs.files }}"
-`,
-  "GOLDEN_EXAMPLE_TEMPLATE.md": `# [Feature Name] \u2014 Golden Example
-
-> **Date:** YYYY-MM-DD
-> **Project:** [project name]
-> **Source Brief:** \`docs/briefs/YYYY-MM-DD-feature-name.md\`
-
----
-
-## Capture
-
-The original user request or description that initiated this feature. Copied verbatim or lightly edited from the brief's Vision section.
-
-> [Paste the original capture text here \u2014 what the user said/typed that kicked off the pipeline]
-
-## Classification
-
-- **Action Level:** [interview | decompose | execute | research | design]
-- **Confidence:** [high | medium | low]
-- **Skills Used:** [comma-separated list of Joycraft skills invoked, e.g., joycraft-new-feature, joycraft-decompose]
-
-## Decomposition Summary
-
-The resulting spec breakdown from this capture:
-
-| # | Spec Name | Description | Size |
-|---|-----------|-------------|------|
-| 1 | [spec-name] | [one sentence] | [S/M/L] |
-
-## Rationale
-
-2-3 sentences explaining why this classification was correct for this capture. What signals in the capture text indicated this action level? What would have gone wrong with a different classification?
-
----
-
-## Template Usage Notes
-
-**This template is for Pipit golden examples.** Golden examples are auto-generated by Joycraft's session-end skill after a successful pipeline run. They provide few-shot examples that improve Pipit's level classifier over time.
-
-**Do not edit generated examples** unless the classification was wrong. If it was wrong, correct the Classification section \u2014 this teaches Pipit the right answer.
-
-**One example per pipeline run.** Each successful interview \u2192 brief \u2192 specs \u2192 execution cycle produces one golden example.
 `
 };
 var CODEX_SKILLS = {
@@ -3652,7 +3230,7 @@ Ask: "Does this match? Comfortable with this approach?" If large/risky, suggest
 
 ## Phase 4: Spec the Fix
 
-Write a bug fix spec to \`docs/specs/YYYY-MM-DD-bugfix-name.md\`. Create the \`docs/specs/\` directory if it doesn't exist.
+Write 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.
 
 **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.
 
@@ -3707,7 +3285,7 @@ What changes, where?
 ## Phase 5: Hand Off
 
 \`\`\`
-Bug fix spec is ready: docs/specs/YYYY-MM-DD-bugfix-name.md
+Bug fix spec is ready: docs/specs/<feature-or-area>/bugfix-name.md
 
 Summary:
 - Bug: [one sentence]
@@ -3783,7 +3361,7 @@ Iterate until the user approves.
 
 ## Step 5: Generate Atomic Specs
 
-For each approved row, create \`docs/specs/YYYY-MM-DD-spec-name.md\`. Create the \`docs/specs/\` directory if it doesn't exist.
+For 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.
 
 **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.
 
@@ -3873,6 +3451,8 @@ To execute:
 
 Ready to start execution?
 \`\`\`
+
+**Tip:** Run \`/new\` before starting the next step. Your artifacts are saved to files \u2014 this conversation context is disposable.
 `,
   "joycraft-design.md": `---
 name: joycraft-design
@@ -4200,6 +3780,8 @@ When you're ready to move forward:
 - **Mark everything as DRAFT.** The output is a starting point, not a commitment.
 - **Keep it short.** The draft brief should be 1-2 pages max. Capture the essence, not every detail.
 - **Multiple interviews are fine.** The user might run this several times as their thinking evolves. Each creates a new dated draft.
+
+**Tip:** Run \`/new\` before starting the next step. Your artifacts are saved to files \u2014 this conversation context is disposable.
 `,
   "joycraft-lockdown.md": `---
 name: joycraft-lockdown
@@ -4419,7 +4001,7 @@ Iterate until approved.
 
 ## Phase 3: Generate Atomic Specs
 
-For each row in the decomposition table, create a self-contained spec file at \`docs/specs/YYYY-MM-DD-spec-name.md\`. Create the \`docs/specs/\` directory if it doesn't exist.
+For each row in the decomposition table, create a self-contained spec file at \`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\`). Create the \`docs/specs/<feature-name>/\` directory if it doesn't exist.
 
 **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.
 
@@ -4509,6 +4091,104 @@ Ready to start?
 **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.
 
 You 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.
+
+**Tip:** Run \`/new\` before starting the next step. Your artifacts are saved to files \u2014 this conversation context is disposable.
+`,
+  "joycraft-optimize.md": `---
+name: joycraft-optimize
+description: Audit your Claude Code or Codex session overhead \u2014 harness file sizes, plugins, MCP servers, hooks \u2014 and report actionable recommendations
+---
+
+# Optimize \u2014 Session Overhead Audit
+
+You are auditing the user's AI development session for token overhead. Produce a conversational diagnostic report \u2014 no files created.
+
+## Step 1: Detect Platform
+
+Check which platform is active:
+- **Claude Code:** Look for \`.claude/\` directory, \`CLAUDE.md\`
+- **Codex:** Look for \`.agents/\` directory, \`AGENTS.md\`
+
+If both exist, run both checks. If neither, default to Claude Code checks and note the uncertainty.
+
+## Step 2: Audit Harness Files
+
+### Claude Code Path
+
+1. **CLAUDE.md** \u2014 count lines. Threshold: \u2264200 lines.
+2. **Skill files** \u2014 glob \`.claude/skills/**/*.md\`. Count lines per file. Threshold: \u2264200 lines each.
+
+### Codex Path
+
+1. **AGENTS.md** \u2014 count lines. Threshold: \u2264200 lines.
+2. **Skill files** \u2014 glob \`.agents/skills/**/*.md\`. Count lines per file. Threshold: \u2264200 lines each.
+
+## Step 3: Audit Plugins & MCP Servers
+
+### Claude Code Path
+
+1. **Installed plugins** \u2014 read \`~/.claude/plugins/installed_plugins.json\`. List plugin names and versions. If not found, report "no plugins file found."
+2. **Enabled plugins** \u2014 read \`~/.claude/settings.json\`, check \`enabledPlugins\` array. Show enabled vs installed count.
+3. **MCP servers** \u2014 read \`~/.claude/settings.json\`, count entries under \`mcpServers\`. List server names.
+
+### Codex Path
+
+1. **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.
+2. **MCP servers** \u2014 check \`~/.codex/config.toml\` for MCP server entries. List server names.
+
+## Step 4: Audit Hooks (Claude Code Only)
+
+Read \`.claude/settings.json\` in the project directory. List all hook definitions under the \`hooks\` key \u2014 show the event name and command for each.
+
+For Codex: note "hook auditing not yet supported on Codex."
+
+## Step 5: Report
+
+Organize findings by category. Use pass/warn indicators:
+
+\`\`\`
+## Session Overhead Report
+
+### Harness Files
+- CLAUDE.md/AGENTS.md: [N] lines [PASS \u2264200 / WARN >200]
+- Skills: [N] files, [list any over 200 lines]
+
+### Plugins
+- Installed: [N] ([list names])
+- Enabled: [N] of [M] installed
+- [If 0: "No plugins \u2014 zero boot cost from plugins."]
+
+### MCP Servers
+- Count: [N] ([list names])
+- [If 0: "No MCP servers \u2014 zero boot cost from servers."]
+
+### Hooks
+- [N] hook definitions ([list event names])
+
+### Recommendations
+- [Specific, actionable items for anything over threshold]
+- [e.g., "AGENTS.md is 312 lines \u2014 consider splitting reference sections into docs/"]
+- [e.g., "3 MCP servers load at boot \u2014 disable unused ones in config"]
+\`\`\`
+
+## Step 6: Further Resources
+
+End with:
+
+> For deeper token optimization, see:
+> - [Nate B Jones's token optimization techniques](https://www.youtube.com/watch?v=bDcgHzCBgmQ)
+> - [OB1 repo](https://github.com/nate-b-j/OB1) \u2014 Heavy File Ingestion skill and stupid button prompt kit
+> - [Joycraft's token discipline guide](docs/guides/token-discipline.md)
+
+## Edge Cases
+
+| Scenario | Behavior |
+|----------|----------|
+| Config files don't exist | Report "not found" for that check, don't error |
+| No plugins installed | Report 0 plugins \u2014 this is good, say so |
+| CLAUDE.md/AGENTS.md exactly 200 lines | PASS \u2014 threshold is \u2264200 |
+| \`~/.claude/\` or \`~/.codex/\` not accessible | Skip user-level checks, note limitation |
+| Both platforms detected | Run both audits, report separately |
 `,
   "joycraft-research.md": `---
 name: joycraft-research
@@ -4652,7 +4332,7 @@ Fix any failures before proceeding.
 
 ## 3. Update Spec Status
 
-If working from an atomic spec in \`docs/specs/\`:
+If working from an atomic spec in \`docs/specs/\` (scan recursively \u2014 specs may be in subdirectories like \`docs/specs/<feature-name>/\`):
 - All acceptance criteria met \u2014 update status to \`Complete\`
 - Partially done \u2014 update status to \`In Progress\`, note what's left
 
@@ -4683,6 +4363,8 @@ Session complete.
 - PR: [opened #N / not yet \u2014 N specs remaining]
 - Next: [what the next session should tackle]
 \`\`\`
+
+**Tip:** Run \`/new\` before starting the next step. Your artifacts are saved to files \u2014 this conversation context is disposable.
 `,
   "joycraft-tune.md": `---
 name: joycraft-tune
@@ -4708,7 +4390,7 @@ Read CLAUDE.md and explore the project. Score each with specific evidence:
 
 | Dimension | What to Check |
 |-----------|--------------|
-| Spec Quality | \`docs/specs/\` \u2014 structured? acceptance criteria? self-contained? |
+| Spec Quality | \`docs/specs/\` (scan recursively) \u2014 structured? acceptance criteria? self-contained? |
 | Spec Granularity | Can each spec be done in one session? |
 | Behavioral Boundaries | ALWAYS/ASK FIRST/NEVER sections (or equivalent rules under any heading) |
 | Skills & Hooks | \`.agents/skills/\` files, hooks config |
@@ -4752,6 +4434,8 @@ Show a tailored roadmap: Level 2-5 table, specific next steps based on actual ga
 - **Rules under non-standard headings:** Give credit for substance.
 - **Previous assessment exists:** Read it first. If nothing to upgrade, say so.
 - **Non-Joycraft content in CLAUDE.md:** Preserve as-is. Only append.
+
+**Tip:** Run \`$joycraft-optimize\` to audit your session's token overhead \u2014 plugins, MCP servers, and harness file sizes.
 `,
   "joycraft-verify.md": `---
 name: joycraft-verify
@@ -4766,9 +4450,9 @@ The user wants independent verification of an implementation. Your job is to fin
 
 ## Step 1: Find the Spec
 
-If the user provided a spec path (e.g., \`$joycraft-verify docs/specs/2026-03-26-add-widget.md\`), use that path directly.
+If the user provided a spec path (e.g., \`$joycraft-verify docs/specs/my-feature/add-widget.md\`), use that path directly.
 
-If no path was provided, scan \`docs/specs/\` for spec files. Pick the most recently modified \`.md\` file in that directory. If \`docs/specs/\` doesn't exist or is empty, tell the user:
+If no path was provided, scan \`docs/specs/\` recursively for spec files (they may be in subdirectories like \`docs/specs/<feature-name>/\`). Pick the most recently modified \`.md\` file. If \`docs/specs/\` doesn't exist or is empty, tell the user:
 
 > No specs found in \`docs/specs/\`. Please provide a spec path: \`$joycraft-verify path/to/spec.md\`
 
@@ -4905,4 +4589,4 @@ export {
   TEMPLATES,
   CODEX_SKILLS
 };
-//# sourceMappingURL=chunk-4RGMUQQZ.js.map
+//# sourceMappingURL=chunk-JXSFWGIN.js.map