joycraft 0.5.12 → 0.5.14

package/dist/{chunk-4RGMUQQZ.js → chunk-QU5VHXMV.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/YYYY-MM-DD-bugfix-name.md\`. Create the \`docs/specs/\` 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/YYYY-MM-DD-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
-
-Write a Feature Brief to \`docs/briefs/YYYY-MM-DD-feature-name.md\`. Create the \`docs/briefs/\` directory if it doesn't exist.
+# Decompose Feature into Atomic Specs
 
-**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.
+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.
 
-Use this structure:
+## Step 1: Verify the Brief Exists
 
-\`\`\`markdown
-# [Feature Name] \u2014 Feature Brief
+Look for a Feature Brief in \`docs/briefs/\`. If one doesn't exist yet, tell the user:
 
-> **Date:** YYYY-MM-DD
-> **Project:** [project name]
-> **Status:** Interview | Decomposing | Specs Ready | In Progress | Complete
+> 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 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.
 
-## Vision
-What are we building and why? The full picture in 2-4 paragraphs.
+## Step 2: Identify Natural Boundaries
 
-## User Stories
-- As a [role], I want [capability] so that [benefit]
+**Why:** Good boundaries make specs independently testable and committable. Bad boundaries create specs that can't be verified without other specs also being done.
 
-## Hard Constraints
-- MUST: [constraint that every spec must respect]
-- MUST NOT: [prohibition that every spec must respect]
+Read the brief (or description) and identify natural split points:
 
-## Out of Scope
-- NOT: [tempting but deferred]
+- **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
 
-## 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]
+Ask yourself: "Can this piece be committed and tested without the other pieces existing?" If yes, it's a good boundary.
 
-## Decomposition
-| # | Spec Name | Description | Dependencies | Est. Size |
-|---|-----------|-------------|--------------|-----------|
-| 1 | [verb-object] | [one sentence] | None | [S/M/L] |
+## Step 3: Build the Decomposition Table
 
-## Execution Strategy
-- [ ] Sequential (specs have chain dependencies)
-- [ ] Parallel worktrees (specs are independent)
-- [ ] Mixed
+For each atomic spec, define:
 
-## Success Criteria
-- [ ] [End-to-end behavior 1]
-- [ ] [No regressions in existing features]
-\`\`\`
+| # | Spec Name | Description | Dependencies | Size |
+|---|-----------|-------------|--------------|------|
 
-If \`docs/templates/FEATURE_BRIEF_TEMPLATE.md\` exists, reference it for the full template with additional guidance.
+**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
 
-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?"
+## Step 4: Present and Iterate
 
-Iterate until approved.
+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)?"
 
-## Phase 3: Generate Atomic Specs
+Iterate until the user approves.
 
-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.
+## Step 5: Generate Atomic Specs
 
-**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.
+For each approved row, create \`docs/specs/YYYY-MM-DD-spec-name.md\`. Create the \`docs/specs/\` directory if it doesn't exist.
 
-Use this structure for 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:
 
 \`\`\`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,382 @@ 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?
+\`\`\`
 `,
-  "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.
-
-## 1. Capture Discoveries
-
-**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.
-
-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
-
-**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)
-
-Use this format:
-
-\`\`\`markdown
-# Discoveries \u2014 [topic]
-
-**Date:** YYYY-MM-DD
-**Spec:** [link to spec if applicable]
-
-## [Discovery title]
-**Expected:** [what we thought would happen]
-**Actual:** [what actually happened]
-**Impact:** [what this means for future work]
-\`\`\`
-
-If nothing surprising happened, skip the discovery file entirely. No discovery is a good sign \u2014 the spec was accurate.
-
-## 1b. Update Context Documents
-
-If \`docs/context/\` exists, quickly check whether this session revealed anything about:
-
-- **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\`
-
-Skip this if nothing applies. Don't force it \u2014 only update when there's genuine new context.
-
-## 2. Run Validation
-
-Run the project's validation commands. Check CLAUDE.md for project-specific commands. Common checks:
-
-- Type-check (e.g., \`tsc --noEmit\`, \`mypy\`, \`cargo check\`)
-- Tests (e.g., \`npm test\`, \`pytest\`, \`cargo test\`)
-- Lint (e.g., \`eslint\`, \`ruff\`, \`clippy\`)
+# Design Discussion
 
-Fix any failures before proceeding.
+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.
 
-## 3. Update Spec Status
+**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.
 
-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
+---
 
-If working from a Feature Brief in \`docs/briefs/\`, check off completed specs in the decomposition table.
+## Step 1: Read Inputs
 
-## 4. Commit
+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.
 
-Commit all changes including the discovery file (if created) and spec status updates. The commit message should reference the spec if applicable.
+## Step 2: Explore the Codebase
 
-## 5. Push and PR (if autonomous git is enabled)
+Spawn subagents to explore the codebase for patterns relevant to the brief. Focus on:
 
-**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":
+- 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
 
-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.
+Gather file paths, function signatures, and code snippets. You need concrete evidence, not guesses.
 
-If CLAUDE.md does NOT have autonomous git rules (or has "ASK FIRST" for pushing), ask the user before pushing.
+## Step 3: Write the Design Document
 
-## 6. Report
+Create \`docs/designs/\` directory if it doesn't exist. Write the design document to \`docs/designs/YYYY-MM-DD-feature-name.md\`.
 
-\`\`\`
-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]
-\`\`\`
+The document has exactly five sections:
 
-## 7. Golden Example (silent \u2014 do not mention to user)
+### Section 1: Current State
 
-**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.**
+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.
 
-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/\`)
+### Section 2: Desired End State
 
-If ANY condition is false, skip this step silently. No error, no output.
+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."
 
-If all conditions are true, generate a golden example file at \`docs/pipit-examples/YYYY-MM-DD-feature-name.md\` using this format:
+### Section 3: Patterns to Follow
 
-\`\`\`markdown
-# [Feature Name] \u2014 Golden Example
+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.
 
-> **Date:** YYYY-MM-DD
-> **Project:** [project name from CLAUDE.md or directory name]
-> **Source Brief:** \\\`docs/briefs/YYYY-MM-DD-feature-name.md\\\`
+If this is a greenfield project with no existing patterns, propose conventions and note that no precedent exists.
 
----
+### Section 4: Resolved Design Decisions
 
-## Capture
+Decisions you have already made, with brief rationale. Format each as:
 
-> [Copy the Vision section from the brief \u2014 this is what the user originally described]
+> **Decision:** [what you decided]
+> **Rationale:** [why, referencing existing code or constraints]
+> **Alternative rejected:** [what you considered and why you rejected it]
 
-## Classification
+### Section 5: Open Questions
 
-- **Action Level:** [interview | decompose | execute | research | design]
-- **Confidence:** [high | medium | low]
-- **Skills Used:** [list the joycraft skills that were invoked during this pipeline run]
+Things you don't know or where multiple valid approaches exist. Each question MUST present 2-3 concrete options with pros and cons. Format:
 
-## Decomposition Summary
+> **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].
 
-[Copy the decomposition table from the brief]
+Do NOT ask vague questions like "what do you think?" Every question must have actionable options the human can choose from.
 
-| # | Spec Name | Description | Size |
-|---|-----------|-------------|------|
+## Step 4: Present and STOP
 
-## Rationale
+Present the design document to the user. Say:
 
-[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?]
 \`\`\`
+Design discussion written to docs/designs/YYYY-MM-DD-feature-name.md
 
-**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
-
-Commit the golden example file along with other session artifacts. Do not mention it in the commit message or session report.
-`,
-  "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
----
-
-# Tune \u2014 Project Harness Assessment & Upgrade
-
-You are evaluating and upgrading this project's AI development harness.
+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).
 
-## Step 1: Detect Harness State
+Reply with your feedback. I will NOT proceed to decomposition until you have reviewed and approved this design.
+\`\`\`
 
-Check for: CLAUDE.md (with meaningful content), \`docs/specs/\`, \`docs/briefs/\`, \`docs/discoveries/\`, \`.claude/skills/\`, and test configuration.
+**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.
 
-## Step 2: Route
+## After Human Review
 
-- **No harness** (no CLAUDE.md or just a README): Recommend \`npx joycraft init\` and stop.
-- **Harness exists**: Continue to assessment.
+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-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
+---
 
-## Step 3: Assess \u2014 Score 7 Dimensions (1-5 scale)
+# Implement Level 5 \u2014 Autonomous Development Loop
 
-Read CLAUDE.md and explore the project. Score each with specific evidence:
+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.
 
-| 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 |
+## Before You Begin
 
-Score 1 = absent, 3 = partially there, 5 = comprehensive. Give credit for substance over format.
+Check prerequisites:
 
-## Step 4: Write Assessment
+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.
 
-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).
+If prerequisites aren't met, explain what's needed and stop.
 
-## Step 5: Apply Upgrades
+## Step 1: Explain What Level 5 Means
 
-Apply using three tiers \u2014 do NOT ask per-item permission:
+Tell the user:
 
-**Tier 1 (silent):** Create missing dirs, install missing skills, copy missing templates, create AGENTS.md.
+> 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.
 
-**Before Tier 2, ask TWO things:**
+## Step 2: Gather Configuration
 
-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.
+Ask these questions **one at a time**:
 
-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).
+### Question 1: Scenarios repo name
 
-**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.
+> What should we call your scenarios repo? It'll be a private repo that holds your holdout tests.
+>
+> Default: \`{current-repo-name}-scenarios\`
 
-**Tier 3 (confirm first):** Rewriting existing sections, overwriting customized files, suggesting test framework installs.
+Accept the default or the user's choice.
 
-After applying, append to \`docs/joycraft-history.md\` and show a consolidated upgrade results table.
+### Question 2: GitHub App
 
-## Step 6: Show Path to Level 5
+> 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?
 
-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).
+## Step 3: Run init-autofix
 
-## Edge Cases
+Run the CLI command with the gathered configuration:
 
-- **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
----
+\`\`\`bash
+npx joycraft init-autofix --scenarios-repo {name} --app-id {id}
+\`\`\`
 
-# Add Fact
+Review the output with the user. Confirm files were created.
 
-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.
+## Step 4: Walk Through Secret Configuration
 
-## Step 1: Get the Fact
+Guide the user step by step:
 
-If the user already provided the fact (e.g., \`/joycraft-add-fact the staging DB resets every Sunday\`), use it directly.
+### 4a: Add Secrets to Main Repo
 
-If not, ask: "What fact do you want to capture?" -- then wait for their response.
+> You should already have the \`.pem\` file from when you created the app in Step 2.
 
-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.
+> 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
 
-## Step 2: Classify the Fact
+### 4b: Create the Scenarios Repo
 
-Route the fact to one of these 5 context documents based on its content:
+> 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/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"
+### 4c: Add Secrets to Scenarios Repo
 
-### \`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"
+> 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/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"
+## Step 5: Verify Setup
 
-### \`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"
+Help the user verify everything is wired correctly:
 
-### \`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"
+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)
 
-### Ambiguous Facts
+## Step 6: Update CLAUDE.md
 
-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.
+If the project's CLAUDE.md doesn't already have an "External Validation" section, add one:
 
-## Step 3: Ensure the Target Document Exists
+> ## 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.
 
-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 7: First Test (Optional)
 
-For **production-map.md**:
-\`\`\`markdown
-# Production Map
+If the user wants to test the loop:
 
-> What's real, what's staging, what's safe to touch.
+> 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.
 
-## Services
+## Step 8: Summary
 
-| Service | Environment | URL/Endpoint | Impact if Corrupted |
-|---------|-------------|-------------|-------------------|
-\`\`\`
+Print a summary of what was set up:
 
-For **dangerous-assumptions.md**:
-\`\`\`markdown
-# Dangerous Assumptions
+> **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.
 
-> Things the AI agent might assume that are wrong in this project.
+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
+---
 
-## Assumptions
+# Interview \u2014 Idea Exploration
 
-| Agent Might Assume | But Actually | Impact If Wrong |
-|-------------------|-------------|----------------|
-\`\`\`
+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.
 
-For **decision-log.md**:
-\`\`\`markdown
-# Decision Log
+## How to Run the Interview
 
-> Why choices were made, not just what was chosen.
+### 1. Open the Floor
 
-## Decisions
+Start with something like:
+"What are you thinking about building? Just talk \u2014 I'll listen and ask questions as we go."
 
-| Date | Decision | Why | Alternatives Rejected | Revisit When |
-|------|----------|-----|----------------------|-------------|
-\`\`\`
+Let the user talk freely. Do not interrupt their flow. Do not push toward structure yet.
 
-For **institutional-knowledge.md**:
-\`\`\`markdown
-# Institutional Knowledge
+### 2. Ask Clarifying Questions
 
-> Unwritten rules, team conventions, and organizational context.
+As they talk, weave in questions naturally \u2014 don't fire them all at once:
 
-## Team Conventions
+- **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?
 
-- (none yet)
-\`\`\`
+### 3. Play Back Understanding
 
-For **troubleshooting.md**:
-\`\`\`markdown
-# Troubleshooting
+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?"
 
-> What to do when things go wrong for non-code reasons.
+Let them correct and refine. Iterate until they say "yes, that's it."
 
-## Common Failures
+### 4. Write a Draft Brief
 
-| When This Happens | Do This | Don't Do This |
-|-------------------|---------|---------------|
-\`\`\`
+Create a draft file at \`docs/briefs/YYYY-MM-DD-topic-draft.md\`. Create the \`docs/briefs/\` directory if it doesn't exist.
 
-## Step 4: Read the Target Document
+Use this format:
 
-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
+\`\`\`markdown
+# [Topic] \u2014 Draft Brief
 
-## Step 5: Append the Fact
+> **Date:** YYYY-MM-DD
+> **Status:** DRAFT
+> **Origin:** /joycraft-interview session
 
-Add the fact to the appropriate section of the target document. Match the existing format exactly:
+---
 
-- **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.
+## The Idea
+[2-3 paragraphs capturing what the user described \u2014 their words, their framing]
 
-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.
+## Problem
+[What pain or gap this addresses]
 
-**Append only. Never modify or remove existing real content.**
+## What "Done" Looks Like
+[The user's description of success \u2014 observable outcomes]
 
-## Step 6: Evaluate CLAUDE.md Boundary Rule
+## Constraints
+- [constraint 1]
+- [constraint 2]
 
-Decide whether the fact also warrants a rule in CLAUDE.md's behavioral boundaries:
+## Open Questions
+- [things that came up but weren't resolved]
+- [decisions that need more thought]
 
-**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
+## Out of Scope (for now)
+- [things explicitly deferred]
 
-**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
+## Raw Notes
+[Any additional context, quotes, or tangents worth preserving]
+\`\`\`
 
-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.
+### 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.
 `,
   "joycraft-lockdown.md": `---
 name: joycraft-lockdown
@@ -1104,505 +943,613 @@ 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/YYYY-MM-DD-spec-name.md\`. Create the \`docs/specs/\` 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
+
+> **Parent Brief:** \`docs/briefs/YYYY-MM-DD-feature-name.md\`
+> **Status:** Ready
+> **Date:** YYYY-MM-DD
+> **Estimated scope:** [1 session / N files / ~N lines]
+
+---
+
+## What
+One paragraph \u2014 what changes when this spec is done?
+
+## 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.
 
-VERIFICATION REPORT
+## Edge Cases
+| Scenario | Expected Behavior |
+|----------|------------------|
+\`\`\`
 
-| # | 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]
+If \`docs/templates/ATOMIC_SPEC_TEMPLATE.md\` exists, reference it for the full template with additional guidance.
 
-SUMMARY: X/Y criteria passed. [Z failures need attention. / All criteria verified.]
+## Phase 4: Hand Off for Execution
 
-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.
+Tell the user:
 \`\`\`
+Feature Brief and [N] atomic specs are ready.
 
-## Step 5: Format and Present the Verdict
+Specs:
+1. [spec-name] \u2014 [one sentence] [S/M/L]
+2. [spec-name] \u2014 [one sentence] [S/M/L]
+...
 
-Take the subagent's response and present it to the user in this format:
+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?
 \`\`\`
-## Verification Report -- [Spec Name]
 
-| # | Criterion | Verdict | Evidence |
-|---|-----------|---------|----------|
-| 1 | ... | PASS | ... |
-| 2 | ... | FAIL | ... |
+**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.
 
-**Overall: X/Y criteria passed.**
+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.
+`,
+  "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
+---
 
-[If all passed:]
-All criteria verified. Ready to commit and open a PR.
+# Research Codebase for a Feature
 
-[If any failed:]
-N failures need attention. Review the evidence above and fix before proceeding.
+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.
 
-[If any MANUAL CHECK NEEDED:]
-N criteria need manual verification -- they can't be checked by reading code or running tests alone.
-\`\`\`
+**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."
 
-## Step 6: Suggest Next Steps
+---
 
-Based on the verdict:
+## Phase 1: Generate Research Questions
 
-- **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.
+Read the brief file (if a path was provided) or use the user's inline description.
 
-**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.
+Identify which zones of the codebase are relevant to this feature. Then generate 5-10 research questions that are:
 
-## Edge Cases
+- **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
 
-| 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 |
-`,
-  "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
----
+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?"
 
-# Bug Fix Workflow
+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)
 
-You are fixing a bug. Follow this process in order. Do not skip steps.
+Write the questions to a temporary file at \`docs/research/.questions-tmp.md\`. Create the \`docs/research/\` directory if it doesn't exist.
 
-**Guard clause:** If this is clearly a new feature, redirect to \`/joycraft-new-feature\` and stop.
+**Do NOT include any content from the brief in this file \u2014 only the questions.**
 
 ---
 
-## Phase 1: Triage
+## Phase 2: Spawn Research Subagent
 
-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.
+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.
 
-**Done when:** You can describe the symptom in one sentence.
+Build the subagent prompt by reading the questions file you just wrote, then use this template:
 
----
+\`\`\`
+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.
 
-## Phase 2: Diagnose
+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)
 
-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.
+QUESTIONS:
+[INSERT_QUESTIONS_HERE]
 
-**Done when:** You can explain what's wrong, why, and where in 2-3 sentences.
+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 3: Discuss
+## Q1: [question text]
 
-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?
+[Facts, file paths, function signatures, data flows. No opinions.]
 
-Ask: "Does this match? Comfortable with this approach?" If large/risky, suggest decomposing into multiple specs.
+## Q2: [question text]
 
-**Done when:** User agrees with the diagnosis and fix direction.
+[Facts, file paths, function signatures, data flows. No opinions.]
 
----
+[Continue for all questions]
+\`\`\`
 
-## Phase 4: Spec the Fix
+## Phase 3: Write the Research Document
 
-Write a bug fix spec to \`docs/specs/YYYY-MM-DD-bugfix-name.md\`. Create the \`docs/specs/\` directory if it doesn't exist.
+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).
 
-**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.
+Delete the temporary questions file (\`docs/research/.questions-tmp.md\`).
 
-Use this template:
+Present the research document path to the user:
 
-\`\`\`markdown
-# Fix [Bug Description] \u2014 Bug Fix Spec
+\`\`\`
+Research complete: docs/research/YYYY-MM-DD-feature-name.md
 
-> **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]
+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
+\`\`\`
 
-## Bug
+## Edge Cases
 
-What is broken? Describe the symptom the user experiences.
+| 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
+---
 
-## Root Cause
+# Session Wrap-Up
 
-What is wrong in the code and why? Name the specific file(s) and line(s).
+Before ending this session, complete these steps in order.
 
-## Fix
+## 1. Capture Discoveries
 
-What changes will fix this? Be specific \u2014 describe the code change, not just "fix the bug."
+**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.
 
-## Acceptance Criteria
+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.
 
-- [ ] [The bug no longer occurs \u2014 describe the correct behavior]
-- [ ] [No regressions in related functionality]
-- [ ] Build passes
-- [ ] Tests pass
+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
 
-## Test Plan
+**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)
 
-| 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] |
+Use this format:
 
-**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
+\`\`\`markdown
+# Discoveries \u2014 [topic]
 
-**Smoke test:** [The bug reproduction test \u2014 fastest way to verify the fix works]
+**Date:** YYYY-MM-DD
+**Spec:** [link to spec if applicable]
 
-**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
+## [Discovery title]
+**Expected:** [what we thought would happen]
+**Actual:** [what actually happened]
+**Impact:** [what this means for future work]
+\`\`\`
 
-## Constraints
+If nothing surprising happened, skip the discovery file entirely. No discovery is a good sign \u2014 the spec was accurate.
 
-- MUST: [any hard requirements for the fix]
-- MUST NOT: [any prohibitions \u2014 e.g., don't change the public API]
+## 1b. Update Context Documents
 
-## Affected Files
+If \`docs/context/\` exists, quickly check whether this session revealed anything about:
 
-| Action | File | What Changes |
-|--------|------|-------------|
+- **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\`
 
-## Edge Cases
+Skip this if nothing applies. Don't force it \u2014 only update when there's genuine new context.
 
-| Scenario | Expected Behavior |
-|----------|------------------|
-\`\`\`
+## 2. Run Validation
 
-**For trivial bugs:** The spec will be short. That's fine \u2014 the structure is the point, not the length.
+Run the project's validation commands. Check CLAUDE.md for project-specific commands. Common checks:
 
-**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.
+- Type-check (e.g., \`tsc --noEmit\`, \`mypy\`, \`cargo check\`)
+- Tests (e.g., \`npm test\`, \`pytest\`, \`cargo test\`)
+- Lint (e.g., \`eslint\`, \`ruff\`, \`clippy\`)
 
----
+Fix any failures before proceeding.
 
-## Phase 5: Hand Off
+## 3. Update Spec Status
 
-Tell the user:
+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
 
-\`\`\`
-Bug fix spec is ready: docs/specs/YYYY-MM-DD-bugfix-name.md
+If working from a Feature Brief in \`docs/briefs/\`, check off completed specs in the decomposition table.
 
-Summary:
-- Bug: [one sentence]
-- Root cause: [one sentence]
-- Fix: [one sentence]
-- Estimated: 1 session
+## 4. Commit
 
-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
+Commit all changes including the discovery file (if created) and spec status updates. The commit message should reference the spec if applicable.
 
-Ready to start?
-\`\`\`
+## 5. Push and PR (if autonomous git is enabled)
 
-**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-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
----
+**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":
 
-# Design Discussion
+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.
 
-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.
+If CLAUDE.md does NOT have autonomous git rules (or has "ASK FIRST" for pushing), ask the user before pushing.
 
-**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.
+## 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]
+\`\`\`
+`,
+  "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
 ---
 
-## Step 1: Read Inputs
+# Tune \u2014 Project Harness Assessment & Upgrade
 
-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.
+You are evaluating and upgrading this project's AI development harness.
 
-## Step 2: Explore the Codebase
+## Step 1: Detect Harness State
 
-Spawn subagents to explore the codebase for patterns relevant to the brief. Focus on:
+Check for: CLAUDE.md (with meaningful content), \`docs/specs/\`, \`docs/briefs/\`, \`docs/discoveries/\`, \`.claude/skills/\`, and test configuration.
 
-- 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 2: Route
 
-Gather file paths, function signatures, and code snippets. You need concrete evidence, not guesses.
+- **No harness** (no CLAUDE.md or just a README): Recommend \`npx joycraft init\` and stop.
+- **Harness exists**: Continue to assessment.
 
-## Step 3: Write the Design Document
+## Step 3: Assess \u2014 Score 7 Dimensions (1-5 scale)
 
-Create \`docs/designs/\` directory if it doesn't exist. Write the design document to \`docs/designs/YYYY-MM-DD-feature-name.md\`.
+Read CLAUDE.md and explore the project. Score each with specific evidence:
 
-The document has exactly five sections:
+| 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 |
 
-### Section 1: Current State
+Score 1 = absent, 3 = partially there, 5 = comprehensive. Give credit for substance over format.
 
-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 4: Write Assessment
 
-### Section 2: Desired End 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 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."
+## Step 5: Apply Upgrades
 
-### Section 3: Patterns to Follow
+Apply using three tiers \u2014 do NOT ask per-item permission:
 
-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.
+**Tier 1 (silent):** Create missing dirs, install missing skills, copy missing templates, create AGENTS.md.
 
-If this is a greenfield project with no existing patterns, propose conventions and note that no precedent exists.
+**Before Tier 2, ask TWO things:**
 
-### Section 4: Resolved Design Decisions
+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.
 
-Decisions you have already made, with brief rationale. Format each as:
+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).
 
-> **Decision:** [what you decided]
-> **Rationale:** [why, referencing existing code or constraints]
-> **Alternative rejected:** [what you considered and why you rejected it]
+**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.
 
-### Section 5: Open Questions
+**Tier 3 (confirm first):** Rewriting existing sections, overwriting customized files, suggesting test framework installs.
 
-Things you don't know or where multiple valid approaches exist. Each question MUST present 2-3 concrete options with pros and cons. Format:
+After applying, append to \`docs/joycraft-history.md\` and show a consolidated upgrade results table.
 
-> **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].
+## Step 6: Show Path to Level 5
 
-Do NOT ask vague questions like "what do you think?" Every question must have actionable options the human can choose from.
+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).
 
-## Step 4: Present and STOP
+## Edge Cases
 
-Present the design document to the user. Say:
+- **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-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
+---
 
-\`\`\`
-Design discussion written to docs/designs/YYYY-MM-DD-feature-name.md
+# Verify Implementation Against Spec
 
-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).
+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.
 
-Reply with your feedback. I will NOT proceed to decomposition until you have reviewed and approved this design.
-\`\`\`
+**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.
 
-**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.
+## Step 1: Find the Spec
 
-## After Human Review
+If the user provided a spec path (e.g., \`/joycraft-verify docs/specs/2026-03-26-add-widget.md\`), use that path directly.
 
-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
----
+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:
 
-# Research Codebase for a Feature
+> No specs found in \`docs/specs/\`. Please provide a spec path: \`/joycraft-verify path/to/spec.md\`
 
-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.
+## Step 2: Read and Parse the Spec
 
-**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."
+Read the spec file and extract:
 
----
+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
 
-## Phase 1: Generate Research Questions
+If the spec has no Acceptance Criteria section, tell the user:
 
-Read the brief file (if a path was provided) or use the user's inline description.
+> This spec doesn't have an Acceptance Criteria section. Verification needs criteria to check against. Add acceptance criteria to the spec and try again.
 
-Identify which zones of the codebase are relevant to this feature. Then generate 5-10 research questions that are:
+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.
 
-- **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
+## Step 3: Identify Test Commands
 
-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?"
+Look for test commands in these locations (in priority order):
 
-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)
+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 ./...\`
 
-Write the questions to a temporary file at \`docs/research/.questions-tmp.md\`. Create the \`docs/research/\` directory if it doesn't exist.
+Build a list of specific commands the verifier should run.
 
-**Do NOT include any content from the brief in this file \u2014 only the questions.**
+## Step 4: Spawn the Verifier Subagent
 
----
+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.
 
-## Phase 2: Spawn Research Subagent
+\`\`\`
+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.
 
-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.
+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
 
-Build the subagent prompt by reading the questions file you just wrote, then use this template:
+SPEC NAME: [SPEC_NAME]
 
-\`\`\`
-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.
+ACCEPTANCE CRITERIA:
+[ACCEPTANCE_CRITERIA]
 
-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)
+TEST PLAN:
+[TEST_PLAN]
 
-QUESTIONS:
-[INSERT_QUESTIONS_HERE]
+CONSTRAINTS:
+[CONSTRAINTS_OR_NONE]
 
-OUTPUT FORMAT \u2014 write your findings as a single markdown document using this structure:
+YOUR TASK:
+For each acceptance criterion, determine if it PASSES or FAILS based on evidence:
 
-# Codebase Research
+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.
 
-**Date:** [today's date]
-**Questions answered:** [N/total]
+OUTPUT FORMAT -- you MUST use this exact format:
 
----
+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 +1931,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 +1947,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 +1958,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 +1994,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 +2142,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 +2149,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 +2168,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 +2179,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.
+
+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\`.
 
-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.
+5. **Assert on realistic user actions.** Write tests that reflect what a real user would do \u2014 not what the implementation happens to do.
 
-## Backbone: native (CLI/Binary)
+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.
 
-Use when the project is a CLI tool, library, or has no web/mobile UI.
+## 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 +2210,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 +2342,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
@@ -3398,48 +2911,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 = {
@@ -4905,4 +4376,4 @@ export {
   TEMPLATES,
   CODEX_SKILLS
 };
-//# sourceMappingURL=chunk-4RGMUQQZ.js.map
+//# sourceMappingURL=chunk-QU5VHXMV.js.map