joycraft 0.5.9 → 0.5.10

package/dist/{chunk-Y6GBN6R4.js → chunk-T62ZHD3N.js}

@@ -5,6 +5,7 @@ var SKILLS = {
   "joycraft-decompose.md": `---
 name: joycraft-decompose
 description: Break a feature brief into atomic specs \u2014 small, testable, independently executable units
+instructions: 32
 ---
 
 # Decompose Feature into Atomic Specs
@@ -153,6 +154,7 @@ Ready to start execution?
   "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
 ---
 
 # Implement Level 5 \u2014 Autonomous Development Loop
@@ -250,7 +252,7 @@ Guide the user step by step:
 
 ### 4c: Add Secrets to Scenarios Repo
 
-> The scenarios repo also needs the same secrets:
+> 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)
 
@@ -310,6 +312,7 @@ Update \`docs/joycraft-assessment.md\` if it exists \u2014 set the Level 5 score
   "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
@@ -406,6 +409,7 @@ When you're ready to move forward:
   "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
 ---
 
 # New Feature Workflow
@@ -416,24 +420,21 @@ You are starting a new feature. Follow this process in order. Do not skip steps.
 
 Interview the user about what they want to build. Let them talk \u2014 your job is to listen, then sharpen.
 
-**Why:** A thorough interview prevents wasted implementation time. Most failed features fail because the problem wasn't understood, not because the code was wrong.
-
 **Ask about:**
 - What problem does this solve? Who is affected?
-- What does "done" look like? How will a user know this works?
-- What are the hard constraints? (business rules, tech limitations, deadlines)
-- What is explicitly NOT in scope? (push hard on this \u2014 aggressive scoping is key)
-- Are there edge cases or error conditions we need to handle?
+- 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 of ideas
-- After they finish, play back your understanding: "So if I'm hearing you right..."
-- Ask clarifying questions that force specificity: "When you say 'handle errors,' what should the user see?"
+- 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. When ready, say:
-"I have enough context. Let me write the Feature Brief for your review."
+Keep asking until you can fill out a Feature Brief.
 
 ## Phase 2: Feature Brief
 
@@ -465,6 +466,13 @@ What are we building and why? The full picture in 2-4 paragraphs.
 ## Out of Scope
 - NOT: [tempting but deferred]
 
+## 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 |
 |---|-----------|-------------|--------------|-----------|
@@ -585,6 +593,7 @@ You can also use \`/joycraft-decompose\` to re-decompose a brief if the breakdow
   "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
 ---
 
 # Session Wrap-Up
@@ -683,387 +692,77 @@ Session complete.
   "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. Follow these steps in order.
+You are evaluating and upgrading this project's AI development harness.
 
 ## Step 1: Detect Harness State
 
-Check the following and note what exists:
-
-1. **CLAUDE.md** \u2014 Read it if it exists. Check whether it contains meaningful content (not just a project name or generic README).
-2. **Key directories** \u2014 Check for: \`docs/specs/\`, \`docs/briefs/\`, \`docs/discoveries/\`, \`docs/templates/\`, \`.claude/skills/\`
-3. **Boundary framework** \u2014 Look for \`Always\`, \`Ask First\`, and \`Never\` sections in CLAUDE.md (or similar behavioral constraints under any heading).
-4. **Skills infrastructure** \u2014 Check \`.claude/skills/\` for installed skill files.
-5. **Test configuration** \u2014 Look for test commands in package.json, pyproject.toml, Cargo.toml, Makefile, or CI config files.
-
-## Step 2: Route Based on State
-
-### If No Harness (no CLAUDE.md, or CLAUDE.md is just a README with no structured sections):
-
-Tell the user:
-- Their project has no AI development harness
-- Recommend running \`npx joycraft init\` to scaffold one
-- Briefly explain what it sets up: CLAUDE.md with boundaries, spec/brief templates, skills, documentation structure
-- **Stop here** \u2014 do not run the full assessment on a bare project
-
-### If Harness Exists (CLAUDE.md has structured content \u2014 boundaries, commands, architecture, or domain rules):
-
-Continue to Step 3 for the full assessment.
-
-## Step 3: Score 7 Dimensions
-
-Read CLAUDE.md thoroughly. Explore the project structure. Score each dimension on a 1-5 scale with specific evidence.
-
-### Dimension 1: Spec Quality
-
-Look in \`docs/specs/\` for specification files.
-
-| Score | Criteria |
-|-------|----------|
-| 1 | No specs directory or no spec files |
-| 2 | Specs exist but are informal notes or TODOs |
-| 3 | Specs have structure (sections, some criteria) but lack consistency |
-| 4 | Specs are structured with clear acceptance criteria and constraints |
-| 5 | Atomic specs: self-contained, acceptance criteria, constraints, edge cases, affected files |
-
-**Evidence:** Number of specs found, example of best/worst, whether acceptance criteria are present.
-
-### Dimension 2: Spec Granularity
-
-Can each spec be completed in a single coding session?
-
-| Score | Criteria |
-|-------|----------|
-| 1 | No specs |
-| 2 | Specs cover entire features or epics |
-| 3 | Specs are feature-sized (multi-session but bounded) |
-| 4 | Most specs are session-sized with clear scope |
-| 5 | All specs are atomic \u2014 one session, one concern, clear done state |
-
-### Dimension 3: Behavioral Boundaries
-
-Read CLAUDE.md for explicit behavioral constraints.
-
-| Score | Criteria |
-|-------|----------|
-| 1 | No CLAUDE.md or no behavioral guidance |
-| 2 | CLAUDE.md exists with general instructions but no structured boundaries |
-| 3 | Some boundaries exist but not organized as Always/Ask First/Never |
-| 4 | Always/Ask First/Never sections present with reasonable coverage |
-| 5 | Comprehensive boundaries covering code style, testing, deployment, dependencies, and dangerous operations |
-
-**Important:** Projects may have strong rules under different headings (e.g., "Critical Rules", "Constraints"). Give credit for substance over format \u2014 a project with clear, enforced rules scores higher than one with empty Always/Ask First/Never sections.
-
-### Dimension 4: Skills & Hooks
+Check for: CLAUDE.md (with meaningful content), \`docs/specs/\`, \`docs/briefs/\`, \`docs/discoveries/\`, \`.claude/skills/\`, and test configuration.
 
-Look in \`.claude/skills/\` for skill files. Check for hooks configuration.
+## Step 2: Route
 
-| Score | Criteria |
-|-------|----------|
-| 1 | No .claude/ directory |
-| 2 | .claude/ exists but empty or minimal |
-| 3 | A few skills installed, no hooks |
-| 4 | Multiple relevant skills, basic hooks |
-| 5 | Comprehensive skills covering workflow, hooks for validation |
+- **No harness** (no CLAUDE.md or just a README): Recommend \`npx joycraft init\` and stop.
+- **Harness exists**: Continue to assessment.
 
-### Dimension 5: Documentation
+## Step 3: Assess \u2014 Score 7 Dimensions (1-5 scale)
 
-Examine \`docs/\` directory structure and content.
+Read CLAUDE.md and explore the project. Score each with specific evidence:
 
-| Score | Criteria |
-|-------|----------|
-| 1 | No docs/ directory |
-| 2 | docs/ exists with ad-hoc files |
-| 3 | Some structure (subdirectories) but inconsistent |
-| 4 | Structured docs/ with templates and clear organization |
-| 5 | Full structure: briefs/, specs/, templates/, architecture docs, referenced from CLAUDE.md |
+| 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 |
 
-### Dimension 6: Knowledge Capture & Contextual Stewardship
-
-Look for discoveries, decisions, session notes, and context documents.
-
-| Score | Criteria |
-|-------|----------|
-| 1 | No knowledge capture mechanism |
-| 2 | Ad-hoc notes or a discoveries directory with no entries |
-| 3 | Discoveries directory with some entries, or context docs exist but empty |
-| 4 | Active discoveries + at least 2 context docs with content (production-map, dangerous-assumptions, decision-log, institutional-knowledge) |
-| 5 | Full contextual stewardship: discoveries with entries, all 4 context docs maintained, session-end workflow in active use |
-
-**Check for:** \`docs/discoveries/\`, \`docs/context/production-map.md\`, \`docs/context/dangerous-assumptions.md\`, \`docs/context/decision-log.md\`, \`docs/context/institutional-knowledge.md\`. Score based on both existence AND whether they have real content (not just templates).
-
-### Dimension 7: Testing & Validation
-
-Look for test config, CI setup, and validation commands.
-
-| Score | Criteria |
-|-------|----------|
-| 1 | No test configuration |
-| 2 | Test framework installed but few/no tests |
-| 3 | Tests exist with reasonable coverage |
-| 4 | Tests + CI pipeline configured |
-| 5 | Tests + CI + validation commands in CLAUDE.md + scenario tests |
+Score 1 = absent, 3 = partially there, 5 = comprehensive. Give credit for substance over format.
 
 ## Step 4: Write Assessment
 
-Write the assessment to \`docs/joycraft-assessment.md\` AND display it in the conversation. Use this format:
-
-\`\`\`markdown
-# Joycraft Assessment \u2014 [Project Name]
-
-**Date:** [today's date]
-**Overall Level:** [1-5, based on average score]
-
-## Scores
-
-| Dimension | Score | Summary |
-|-----------|-------|---------|
-| Spec Quality | X/5 | [one-line summary] |
-| Spec Granularity | X/5 | [one-line summary] |
-| Behavioral Boundaries | X/5 | [one-line summary] |
-| Skills & Hooks | X/5 | [one-line summary] |
-| Documentation | X/5 | [one-line summary] |
-| Knowledge Capture | X/5 | [one-line summary] |
-| Testing & Validation | X/5 | [one-line summary] |
-
-**Average:** X.X/5
-
-## Detailed Findings
-
-### [Dimension Name] \u2014 X/5
-**Evidence:** [specific files, paths, counts found]
-**Gap:** [what's missing]
-**Recommendation:** [specific action to improve]
-
-## Upgrade Plan
-
-To reach Level [current + 1], complete these steps:
-1. [Most impactful action] \u2014 addresses [dimension] (X -> Y)
-2. [Next action] \u2014 addresses [dimension] (X -> Y)
-[up to 5 actions, ordered by impact]
-\`\`\`
+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).
 
 ## Step 5: Apply Upgrades
 
-Immediately after presenting the assessment, apply upgrades using the three-tier model below. Do NOT ask for per-item permission \u2014 batch everything and show a consolidated report at the end.
-
-### Tier 1: Silent Apply (just do it)
-These are safe, additive operations. Apply them without asking:
-- Create missing directories (\`docs/specs/\`, \`docs/briefs/\`, \`docs/discoveries/\`, \`docs/templates/\`)
-- Install missing skills to \`.claude/skills/\`
-- Copy missing templates to \`docs/templates/\`
-- Create AGENTS.md if it doesn't exist
-
-### Git Autonomy Preference
-
-Before applying Behavioral Boundaries to CLAUDE.md, ask the user ONE question:
-
-> How autonomous should git operations be?
-> 1. **Cautious** \u2014 commits freely, asks before pushing or opening PRs *(good for learning the workflow)*
-> 2. **Autonomous** \u2014 commits, pushes to branches, and opens PRs without asking *(good for spec-driven development)*
-
-Based on their answer, use the appropriate git rules in the Behavioral Boundaries section:
+Apply using three tiers \u2014 do NOT ask per-item permission:
 
-**If Cautious (default):**
-\`\`\`
-### ASK FIRST
-- Pushing to remote
-- Creating or merging pull requests
-- Any destructive git operation (force-push, reset --hard, branch deletion)
-
-### NEVER
-- Push directly to main/master without approval
-- Amend commits that have been pushed
-\`\`\`
-
-**If Autonomous:**
-\`\`\`
-### ALWAYS \u2014 Git Autonomy (STRICTLY ENFORCED)
-
-> **This project uses fully autonomous git operations.** The user has explicitly
-> granted permission for all git operations below. Do NOT ask for confirmation.
-> Do NOT hesitate. Do NOT treat these as suggestions. These are standing orders
-> that override any default caution about pushing or creating PRs.
-
-- **Commit early and often** \u2014 after each logical unit of work, not just at session end
-- **Push to feature branches immediately after every commit** \u2014 do not batch pushes, do not wait, do not ask
-- **Open a PR when all specs in a feature are complete** \u2014 use gh pr create, do not ask first
-- **Use descriptive branch names:** feature/spec-name or fix/description
-- **After /joycraft-session-end:** push all commits and open a PR if the feature is complete
-
-### ASK FIRST
-- Merging PRs to main/master
-- Any destructive git operation (force-push, reset --hard, branch deletion)
-
-### NEVER
-- Push directly to main/master (always use feature branches + PR)
-- Amend commits that have been pushed to remote
-- Ask "should I push?" or "should I create a PR?" \u2014 the answer is always yes, just do it
-\`\`\`
-
-### Permission Mode Recommendation
-
-After the git autonomy question and before the risk interview, recommend a Claude Code permission mode based on what you've learned so far. Present this guidance:
-
-> **What permission mode should you use?**
->
-> | Your situation | Use | Why |
-> |---|---|---|
-> | Autonomous spec execution | \`--permission-mode dontAsk\` + allowlist | Only pre-approved commands run |
-> | Long session with some trust | \`--permission-mode auto\` | Safety classifier reviews each action |
-> | Interactive development | \`--permission-mode acceptEdits\` | Auto-approves file edits, prompts for commands |
->
-> You do NOT need \`--dangerously-skip-permissions\`. The modes above provide autonomy with safety.
-
-**If the user chose Autonomous git:** Recommend \`auto\` mode as a good default -- it provides autonomy while the safety classifier catches risky operations. Note that \`dontAsk\` is even more autonomous but requires a well-configured allowlist.
-
-**If the user chose Cautious git:** Recommend \`auto\` mode -- it matches their preference for safety with less manual intervention than the default.
-
-**If the risk interview reveals production databases, live APIs, or billing systems:** Upgrade the recommendation to \`dontAsk\` with a tight allowlist. Explain that \`dontAsk\` with explicit deny patterns is safer than \`auto\` for high-risk environments because it uses a deterministic allowlist rather than a classifier.
-
-This is informational only -- do not change the user's permission mode. Just tell them what to use when they launch Claude Code.
-
-### Risk Interview
-
-Before applying upgrades, ask 3-5 targeted questions to capture what's dangerous in this project. Skip this if \`docs/context/production-map.md\` or \`docs/context/dangerous-assumptions.md\` already exist (offer to update instead).
-
-**Question 1:** "What could this agent break that would ruin your day? Think: production databases, live APIs, billing systems, user data, infrastructure."
-
-From the answer, generate:
-- NEVER rules for CLAUDE.md (e.g., "NEVER connect to production DB at postgres://prod.example.com")
-- Deny patterns for .claude/settings.json (e.g., deny Bash commands containing production hostnames)
-
-**Question 2:** "What external services does this project connect to? Which are production vs. staging/dev?"
-
-From the answer, generate:
-- \`docs/context/production-map.md\` documenting what's real vs safe to touch
-- Include: service name, URL/endpoint, environment (prod/staging/dev), what happens if corrupted
-
-**Question 3:** "What are the unwritten rules a new developer would need months to learn about this project?"
-
-From the answer, generate:
-- Additions to CLAUDE.md boundaries (new ALWAYS/ASK FIRST/NEVER rules)
-- \`docs/context/dangerous-assumptions.md\` with "Agent might assume X, but actually Y"
-
-**Question 4 (optional):** "What happened last time something went wrong with an automated tool or deploy?"
+**Tier 1 (silent):** Create missing dirs, install missing skills, copy missing templates, create AGENTS.md.
 
-If the user has a story, capture the lesson as a specific NEVER rule and add to dangerous-assumptions.md.
+**Before Tier 2, ask TWO things:**
 
-**Question 5:** "Any files, directories, or commands that should be completely off-limits?"
+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.
 
-From the answer, generate deny rules for .claude/settings.json and add to NEVER section.
+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).
 
-**Rules for the interview:**
-- Ask questions ONE AT A TIME, not all at once
-- If the user says "nothing" or "skip", respect that and move on
-- Keep it to 2-3 minutes total \u2014 don't interrogate
-- Generate artifacts immediately after the interview, don't wait for all questions
-- This is the SECOND and LAST set of questions during /joycraft-tune (first is git autonomy)
+**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.
 
-### Tier 2: Apply and Show Diff (do it, then report)
-These modify important files but are additive (append-only). Apply them, then show what changed so the user can review. Git is the undo button.
-- Add missing sections to CLAUDE.md (Behavioral Boundaries, Development Workflow, Getting Started with Joycraft, Key Files, Common Gotchas)
-- Use the git autonomy preference from above when generating the Behavioral Boundaries section
-- Draft section content from the actual codebase \u2014 not generic placeholders. Read the project's real rules, real commands, real structure.
-- Only append \u2014 never modify or reformat existing content
+**Tier 3 (confirm first):** Rewriting existing sections, overwriting customized files, suggesting test framework installs.
 
-### Tier 3: Confirm First (ask before acting)
-These are potentially destructive or opinionated. Ask before proceeding:
-- Rewriting or reorganizing existing CLAUDE.md sections
-- Overwriting files the user has customized
-- Suggesting test framework installation or CI setup (present as recommendations, don't auto-install)
-
-### Reading a Previous Assessment
-
-If \`docs/joycraft-assessment.md\` already exists, read it first. If all recommendations have been applied, report "nothing to upgrade" and offer to re-assess.
-
-### After Applying
-
-Append a history entry to \`docs/joycraft-history.md\` (create if needed):
-\`\`\`
-| [date] | [new avg score] | [change from last] | [summary of what changed] |
-\`\`\`
-
-Then display a single consolidated report:
-
-\`\`\`markdown
-## Upgrade Results
-
-| Dimension              | Before | After | Change |
-|------------------------|--------|-------|--------|
-| Spec Quality           | X/5    | X/5   | +X     |
-| ...                    | ...    | ...   | ...    |
-
-**Previous Level:** X \u2014 **New Level:** X
-
-### What Changed
-- [list each change applied]
-
-### Remaining Gaps
-- [anything still below 3.5, with specific next action]
-\`\`\`
-
-Update \`docs/joycraft-assessment.md\` with the new scores and today's date.
+After applying, append to \`docs/joycraft-history.md\` and show a consolidated upgrade results table.
 
 ## Step 6: Show Path to Level 5
 
-After the upgrade report, always show the Level 5 roadmap tailored to the project's current state:
-
-\`\`\`markdown
-## Path to Level 5 \u2014 Autonomous Development
-
-You're at Level [X]. Here's what each level looks like:
-
-| Level | You | AI | Key Skill |
-|-------|-----|-----|-----------|
-| 2 | Guide direction | Multi-file changes | AI-native tooling |
-| 3 | Review diffs | Primary developer | Code review at scale |
-| 4 | Write specs, check tests | End-to-end development | Specification writing |
-| 5 | Define what + why | Specs in, software out | Systems design |
-
-### Your Next Steps Toward Level [X+1]:
-1. [Specific action based on current gaps \u2014 e.g., "Write your first atomic spec using /joycraft-new-feature"]
-2. [Next action \u2014 e.g., "Add vitest and write tests for your core logic"]
-3. [Next action \u2014 e.g., "Use /joycraft-session-end consistently to build your discoveries log"]
-
-### What Level 5 Looks Like (Your North Star):
-- A backlog of ready specs that agents pull from and execute autonomously
-- CI failures auto-generate fix specs \u2014 no human triage for regressions
-- Multi-agent execution with parallel worktrees, one spec per agent
-- External holdout scenarios (tests the agent can't see) prevent overfitting
-- CLAUDE.md evolves from discoveries \u2014 the harness improves itself
-
-### You'll Know You're at Level 5 When:
-- You describe a feature in one sentence and walk away
-- The system produces a PR with tests, docs, and discoveries \u2014 without further input
-- Failed CI runs generate their own fix specs
-- Your harness improves without you manually editing CLAUDE.md
-
-This is a significant journey. Most teams are at Level 2. Getting to Level 4 with Joycraft's workflow is achievable \u2014 Level 5 requires building validation infrastructure (scenario tests, spec queues, CI feedback loops) that goes beyond what Joycraft scaffolds today. But the harness you're building now is the foundation.
-\`\`\`
-
-Tailor the "Next Steps" section based on the project's actual gaps \u2014 don't show generic advice.
+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).
 
 ## Edge Cases
 
-- **Not a git repo:** Note this. Joycraft works best in a git repo.
-- **CLAUDE.md is just a README:** Treat as "no harness."
-- **Non-Joycraft skills already installed:** Acknowledge them. Do not replace \u2014 suggest additions.
-- **Monorepo:** Assess the root CLAUDE.md. Note if component-level CLAUDE.md files exist.
-- **Project has rules under non-standard headings:** Give credit. Suggest reformatting as Always/Ask First/Never but acknowledge the rules are there.
-- **Assessment file missing when upgrading:** Run the full assessment first, then offer to apply.
-- **Assessment is stale:** Warn and offer to re-assess before proceeding.
-- **All recommendations already applied:** Report "nothing to upgrade" and stop.
-- **User declines a recommendation:** Skip it, continue, include in "What Was Skipped."
-- **CLAUDE.md does not exist at all:** Create it with recommended sections, but ask the user first.
-- **Non-Joycraft content in CLAUDE.md:** Preserve exactly as-is. Only append or merge \u2014 never remove or reformat existing content.
+- **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
 ---
 
 # Add Fact
@@ -1090,7 +789,7 @@ The fact is about **infrastructure, services, environments, URLs, endpoints, cre
 ### \`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"
+- Examples: "The \`users\` table looks like a test table but it's production", "Deleting a workspace doesn't delete the billing subscription"
 
 ### \`docs/context/decision-log.md\`
 The fact is about **an architectural or tooling choice and why it was made**.
@@ -1228,6 +927,7 @@ Routed to [chosen doc] -- move to [alternative doc] if this is more about [alter
   "joycraft-lockdown.md": `---
 name: joycraft-lockdown
 description: Generate constrained execution boundaries for an implementation session -- NEVER rules and deny patterns to prevent agent overreach
+instructions: 28
 ---
 
 # Lockdown Mode
@@ -1300,15 +1000,15 @@ Review these suggestions and add them to your project:
 
 ### CLAUDE.md -- add to NEVER section:
 
-- Edit any file in \\\`[user's test directories]\\\`
-- Run \\\`[denied package manager commands]\\\`
-- Use \\\`[denied network tools]\\\`
+- Edit any file in \`[user's test directories]\`
+- Run \`[denied package manager commands]\`
+- Use \`[denied network tools]\`
 - Read log files directly -- interact with logs only through test assertions
 - [Any additional NEVER rules based on user responses]
 
 ### .claude/settings.json -- suggested deny patterns:
 
-Add these to the \\\`permissions.deny\\\` array:
+Add these to the \`permissions.deny\` array:
 
 ["[command1]", "[command2]", "[command3]"]
 
@@ -1329,17 +1029,17 @@ After generating the boundaries above, also recommend a Claude Code permission m
 \`\`\`
 ### Recommended Permission Mode
 
-You don't need \\\`--dangerously-skip-permissions\\\`. Safer alternatives exist:
+You don't need \`--dangerously-skip-permissions\`. Safer alternatives exist:
 
 | Your situation | Use | Why |
 |---|---|---|
-| Autonomous spec execution | \\\`--permission-mode dontAsk\\\` + allowlist above | Only pre-approved commands run |
-| Long session with some trust | \\\`--permission-mode auto\\\` | Safety classifier reviews each action |
-| Interactive development | \\\`--permission-mode acceptEdits\\\` | Auto-approves file edits, prompts for commands |
+| Autonomous spec execution | \`--permission-mode dontAsk\` + allowlist above | Only pre-approved commands run |
+| Long session with some trust | \`--permission-mode auto\` | Safety classifier reviews each action |
+| Interactive development | \`--permission-mode acceptEdits\` | Auto-approves file edits, prompts for commands |
 
-**For lockdown mode, we recommend \\\`--permission-mode dontAsk\\\`** combined with the deny patterns above. This gives you full autonomy for allowed operations while blocking everything else -- no classifier overhead, no prompts, and no safety bypass.
+**For lockdown mode, we recommend \`--permission-mode dontAsk\`** combined with the deny patterns above. This gives you full autonomy for allowed operations while blocking everything else -- no classifier overhead, no prompts, and no safety bypass.
 
-\\\`--dangerously-skip-permissions\\\` disables ALL safety checks. The modes above give you autonomy without removing the guardrails.
+\`--dangerously-skip-permissions\` disables ALL safety checks. The modes above give you autonomy without removing the guardrails.
 \`\`\`
 
 ## Step 4: Offer to Apply
@@ -1354,6 +1054,7 @@ If the user asks you to apply the changes:
   "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
 ---
 
 # Verify Implementation Against Spec
@@ -1497,70 +1198,44 @@ Based on the verdict:
   "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
 ---
 
 # Bug Fix Workflow
 
 You are fixing a bug. Follow this process in order. Do not skip steps.
 
-**Guard clause:** If the user's request is clearly a new feature \u2014 not a bug, error, or unexpected behavior \u2014 say:
-"This sounds like a new feature rather than a bug fix. Try \`/joycraft-new-feature\` for a guided feature workflow."
-Then stop.
+**Guard clause:** If this is clearly a new feature, redirect to \`/joycraft-new-feature\` and stop.
 
 ---
 
 ## Phase 1: Triage
 
-Establish what's broken. Your goal is to reproduce the bug or at minimum understand the symptom clearly.
-
-**Ask / gather:**
-- What is the symptom? (error message, unexpected behavior, crash, wrong output)
-- What are the steps to reproduce?
-- What is the expected behavior vs. actual behavior?
-- When did it start? (recent change, always been this way, intermittent)
-- Any relevant logs, screenshots, or error output?
+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.
 
-**Actions:**
-- If the user provides an error message or stack trace, read the referenced files immediately
-- If steps to reproduce are provided, try to reproduce the bug (run the failing command, test, or request)
-- If the bug is intermittent or hard to reproduce, gather more context: environment, OS, versions, config
-
-**Done when:** You can describe the symptom in one sentence and have either reproduced it or have enough context to diagnose without reproduction.
+**Done when:** You can describe the symptom in one sentence.
 
 ---
 
 ## Phase 2: Diagnose
 
-Find the root cause. Read code, trace the execution path, identify what's wrong and why.
-
-**Actions:**
-- Start from the error site (stack trace, failing test, broken UI) and trace backward
-- Read the relevant source files \u2014 don't guess based on file names alone
-- Identify the specific line(s), condition, or logic error causing the bug
-- Check git blame or recent commits if the bug was introduced by a recent change
-- Look for related bugs \u2014 is this a symptom of a deeper issue?
+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.
 
-**Done when:** You can explain the root cause in 2-3 sentences: what's wrong, why it's wrong, and where in the code it happens.
+**Done when:** You can explain what's wrong, why, and where in 2-3 sentences.
 
 ---
 
 ## Phase 3: Discuss
 
-Present your findings to the user. Do NOT start writing code or a spec yet.
+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?
 
-**Present:**
-1. **Symptom:** What the user sees (confirm your understanding matches theirs)
-2. **Root cause:** What's actually wrong in the code and why
-3. **Proposed fix:** What you think the fix is \u2014 be specific (which files, what changes)
-4. **Risk assessment:** What could go wrong with this fix? Any side effects?
-5. **Scope check:** Is this a simple fix or does it touch multiple systems?
+Ask: "Does this match? Comfortable with this approach?" If large/risky, suggest decomposing into multiple specs.
 
-**Ask:**
-- "Does this match what you're seeing?"
-- "Are you comfortable with this approach, or do you want to explore alternatives?"
-- If the fix is large or risky: "Should we decompose this into smaller specs?"
-
-**Done when:** The user agrees with the diagnosis and proposed fix direction.
+**Done when:** User agrees with the diagnosis and fix direction.
 
 ---
 
@@ -1670,6 +1345,211 @@ Ready to start?
 \`\`\`
 
 **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
+---
+
+# Design Discussion
+
+You are producing a design discussion document for a feature. This sits between research and decomposition \u2014 it captures your understanding so the human can catch wrong assumptions before specs are written.
+
+**Guard clause:** If no brief path is provided and no brief exists in \`docs/briefs/\`, say:
+"No feature brief found. Run \`/joycraft-new-feature\` first to create one, or provide the path to your brief."
+Then stop.
+
+---
+
+## Step 1: Read Inputs
+
+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.
+
+## Step 2: Explore the Codebase
+
+Spawn subagents to explore the codebase for patterns relevant to the brief. Focus on:
+
+- 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
+
+Gather file paths, function signatures, and code snippets. You need concrete evidence, not guesses.
+
+## Step 3: Write the Design Document
+
+Create \`docs/designs/\` directory if it doesn't exist. Write the design document to \`docs/designs/YYYY-MM-DD-feature-name.md\`.
+
+The document has exactly five sections:
+
+### Section 1: Current State
+
+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.
+
+### Section 2: Desired End State
+
+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."
+
+### Section 3: Patterns to Follow
+
+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.
+
+If this is a greenfield project with no existing patterns, propose conventions and note that no precedent exists.
+
+### Section 4: Resolved Design Decisions
+
+Decisions you have already made, with brief rationale. Format each as:
+
+> **Decision:** [what you decided]
+> **Rationale:** [why, referencing existing code or constraints]
+> **Alternative rejected:** [what you considered and why you rejected it]
+
+### Section 5: Open Questions
+
+Things you don't know or where multiple valid approaches exist. Each question MUST present 2-3 concrete options with pros and cons. Format:
+
+> **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].
+
+Do NOT ask vague questions like "what do you think?" Every question must have actionable options the human can choose from.
+
+## Step 4: Present and STOP
+
+Present the design document to the user. Say:
+
+\`\`\`
+Design discussion written to docs/designs/YYYY-MM-DD-feature-name.md
+
+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).
+
+Reply with your feedback. I will NOT proceed to decomposition until you have reviewed and approved this design.
+\`\`\`
+
+**CRITICAL: Do NOT proceed to \`/joycraft-decompose\` or generate specs.** Wait for the human to review, answer open questions, and correct any wrong assumptions. The entire value of this skill is the pause \u2014 it forces a human checkpoint before mistakes propagate.
+
+## After Human Review
+
+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
+---
+
+# Research Codebase for a Feature
+
+You are producing objective codebase research to inform a future spec or implementation. The key insight: the researching agent must never see the brief or ticket \u2014 only research questions. This prevents opinions from contaminating the facts.
+
+**Guard clause:** If the user doesn't provide a brief path or inline description, ask:
+"What feature or change are you researching? Provide a brief path (e.g., \`docs/briefs/2026-03-30-my-feature.md\`) or describe it in a few sentences."
+
+---
+
+## Phase 1: Generate Research Questions
+
+Read the brief file (if a path was provided) or use the user's inline description.
+
+Identify which zones of the codebase are relevant to this feature. Then generate 5-10 research questions that are:
+
+- **Objective and fact-seeking** \u2014 "How does X work?" not "How should we build X?"
+- **Specific to the codebase** \u2014 reference concrete systems, files, or flows
+- **Answerable by reading code** \u2014 no questions about business strategy or user preferences
+
+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?"
+
+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)
+
+Write the questions to a temporary file at \`docs/research/.questions-tmp.md\`. Create the \`docs/research/\` directory if it doesn't exist.
+
+**Do NOT include any content from the brief in this file \u2014 only the questions.**
+
+---
+
+## Phase 2: Spawn Research Subagent
+
+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.
+
+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.
+
+RULES \u2014 these are hard constraints:
+- Answer each question with FACTS ONLY: file paths, function signatures, data flows, patterns, dependencies
+- Do NOT recommend, suggest, or opine on anything
+- Do NOT speculate about what should be built or how
+- If a question cannot be answered (no relevant code exists), say "No existing code found for this"
+- Use the Read tool and Grep tool to explore the codebase thoroughly
+- Include code snippets only when they are essential evidence (e.g., a function signature, a config block)
+
+QUESTIONS:
+[INSERT_QUESTIONS_HERE]
+
+OUTPUT FORMAT \u2014 write your findings as a single markdown document using this structure:
+
+# Codebase Research
+
+**Date:** [today's date]
+**Questions answered:** [N/total]
+
+---
+
+## Q1: [question text]
+
+[Facts, file paths, function signatures, data flows. No opinions.]
+
+## Q2: [question text]
+
+[Facts, file paths, function signatures, data flows. No opinions.]
+
+[Continue for all questions]
+\`\`\`
+
+## Phase 3: Write the Research Document
+
+Take the subagent's response and write it to \`docs/research/YYYY-MM-DD-feature-name.md\`. Derive the feature name from the brief filename or the user's description (lowercase, hyphenated).
+
+Delete the temporary questions file (\`docs/research/.questions-tmp.md\`).
+
+Present the research document path to the user:
+
+\`\`\`
+Research complete: docs/research/YYYY-MM-DD-feature-name.md
+
+This document contains objective facts about your codebase \u2014 no opinions or recommendations.
+
+Next steps:
+- /joycraft-decompose \u2014 break the feature into atomic specs (research will inform the specs)
+- /joycraft-new-feature \u2014 formalize into a full Feature Brief first
+- Read the research and add any corrections or missing context manually
+\`\`\`
+
+## Edge Cases
+
+| Scenario | Behavior |
+|----------|----------|
+| No brief provided | Accept inline description, generate questions from that |
+| Codebase is empty or new | Research doc reports "no existing patterns found" per question |
+| User runs research twice for same feature | Overwrites previous research doc (same filename) |
+| Brief is very short (1-2 sentences) | Still generate questions \u2014 even simple features benefit from understanding existing patterns |
+| \`docs/research/\` doesn't exist | Create it |
 `
 };
 var TEMPLATES = {
@@ -3472,4 +3352,4 @@ export {
   SKILLS,
   TEMPLATES
 };
-//# sourceMappingURL=chunk-Y6GBN6R4.js.map
+//# sourceMappingURL=chunk-T62ZHD3N.js.map