joycraft 0.5.14 → 0.5.15

package/README.md

@@ -119,6 +119,10 @@ Tests are the mechanism to autonomy — every spec includes a test plan, and the
 
 A 2-3 minute risk interview generates safety boundaries, and you choose your git autonomy level. [Read the full guide →](docs/guides/tuning.md)
 
+### Token Discipline
+
+Joycraft produces file artifacts at every step, so your conversation context is disposable. Clear it between phases to reduce cost and improve output quality. [Read the full guide →](docs/guides/token-discipline.md)
+
 ### Level 5: The Autonomous Loop
 
 Level 5 is where specs go in and validated software comes out — four GitHub Actions workflows, a separate scenarios repo, and two AI agents that can never see each other's work. [Read the full guide →](docs/guides/level-5-autonomy.md)

package/dist/{chunk-QU5VHXMV.js → chunk-JXSFWGIN.js}

@@ -213,7 +213,7 @@ Ask: "Does this match? Comfortable with this approach?" If large/risky, suggest
 
 ## Phase 4: Spec the Fix
 
-Write a bug fix spec to \`docs/specs/YYYY-MM-DD-bugfix-name.md\`. Create the \`docs/specs/\` directory if it doesn't exist.
+Write a bug fix spec to \`docs/specs/<feature-or-area>/bugfix-name.md\`. Use the relevant feature name or area as the subdirectory (e.g., \`auth\`, \`cli\`, \`parser\`). Create the \`docs/specs/<feature-or-area>/\` directory if it doesn't exist.
 
 **Why:** Even bug fixes deserve a spec. It forces clarity on what "fixed" means, ensures test-first discipline, and creates a traceable record of the fix.
 
@@ -297,7 +297,7 @@ What changes will fix this? Be specific \u2014 describe the code change, not jus
 Tell the user:
 
 \`\`\`
-Bug fix spec is ready: docs/specs/YYYY-MM-DD-bugfix-name.md
+Bug fix spec is ready: docs/specs/<feature-or-area>/bugfix-name.md
 
 Summary:
 - Bug: [one sentence]
@@ -376,7 +376,7 @@ Iterate until the user approves.
 
 ## Step 5: Generate Atomic Specs
 
-For each approved row, create \`docs/specs/YYYY-MM-DD-spec-name.md\`. Create the \`docs/specs/\` directory if it doesn't exist.
+For each approved row, create \`docs/specs/<feature-name>/spec-name.md\`. Derive the feature-name from the brief filename (strip the date prefix and \`.md\` \u2014 e.g., \`2026-04-06-token-discipline.md\` \u2192 \`token-discipline\`). If no brief exists, use a user-provided or inferred feature name (slugified to kebab-case). Create the \`docs/specs/<feature-name>/\` directory if it doesn't exist.
 
 **Why:** Each spec must be self-contained \u2014 a fresh Claude session should be able to execute it without reading the Feature Brief. Copy relevant constraints and context into each spec.
 
@@ -466,6 +466,8 @@ To execute:
 
 Ready to start execution?
 \`\`\`
+
+**Tip:** Run \`/clear\` before starting the next step. Your artifacts are saved to files \u2014 this conversation context is disposable.
 `,
   "joycraft-design.md": `---
 name: joycraft-design
@@ -815,6 +817,8 @@ When you're ready to move forward:
 - **Mark everything as DRAFT.** The output is a starting point, not a commitment.
 - **Keep it short.** The draft brief should be 1-2 pages max. Capture the essence, not every detail.
 - **Multiple interviews are fine.** The user might run this several times as their thinking evolves. Each creates a new dated draft.
+
+**Tip:** Run \`/clear\` before starting the next step. Your artifacts are saved to files \u2014 this conversation context is disposable.
 `,
   "joycraft-lockdown.md": `---
 name: joycraft-lockdown
@@ -1036,7 +1040,7 @@ Iterate until approved.
 
 ## Phase 3: Generate Atomic Specs
 
-For each row in the decomposition table, create a self-contained spec file at \`docs/specs/YYYY-MM-DD-spec-name.md\`. Create the \`docs/specs/\` directory if it doesn't exist.
+For each row in the decomposition table, create a self-contained spec file at \`docs/specs/<feature-name>/spec-name.md\`. Derive the feature-name from the brief filename (strip the date prefix and \`.md\` \u2014 e.g., \`2026-04-06-token-discipline.md\` \u2192 \`token-discipline\`). Create the \`docs/specs/<feature-name>/\` directory if it doesn't exist.
 
 **Why:** Each spec must be understandable WITHOUT reading the Feature Brief. This prevents the "Curse of Instructions" \u2014 no spec should require holding the entire feature in context. Copy relevant context into each spec.
 
@@ -1126,6 +1130,105 @@ Ready to start?
 **Why:** A fresh session for execution produces better results. The interview session has too much context noise \u2014 a clean session with just the spec is more focused.
 
 You can also use \`/joycraft-decompose\` to re-decompose a brief if the breakdown needs adjustment, or run \`/joycraft-interview\` first for a lighter brainstorm before committing to the full workflow.
+
+**Tip:** Run \`/clear\` before starting the next step. Your artifacts are saved to files \u2014 this conversation context is disposable.
+`,
+  "joycraft-optimize.md": `---
+name: joycraft-optimize
+description: Audit your Claude Code or Codex session overhead \u2014 harness file sizes, plugins, MCP servers, hooks \u2014 and report actionable recommendations
+instructions: 20
+---
+
+# Optimize \u2014 Session Overhead Audit
+
+You are auditing the user's AI development session for token overhead. Produce a conversational diagnostic report \u2014 no files created.
+
+## Step 1: Detect Platform
+
+Check which platform is active:
+- **Claude Code:** Look for \`.claude/\` directory, \`CLAUDE.md\`
+- **Codex:** Look for \`.agents/\` directory, \`AGENTS.md\`
+
+If both exist, run both checks. If neither, default to Claude Code checks and note the uncertainty.
+
+## Step 2: Audit Harness Files
+
+### Claude Code Path
+
+1. **CLAUDE.md** \u2014 count lines. Threshold: \u2264200 lines.
+2. **Skill files** \u2014 glob \`.claude/skills/**/*.md\`. Count lines per file. Threshold: \u2264200 lines each.
+
+### Codex Path
+
+1. **AGENTS.md** \u2014 count lines. Threshold: \u2264200 lines.
+2. **Skill files** \u2014 glob \`.agents/skills/**/*.md\`. Count lines per file. Threshold: \u2264200 lines each.
+
+## Step 3: Audit Plugins & MCP Servers
+
+### Claude Code Path
+
+1. **Installed plugins** \u2014 read \`~/.claude/plugins/installed_plugins.json\`. List plugin names and versions. If not found, report "no plugins file found."
+2. **Enabled plugins** \u2014 read \`~/.claude/settings.json\`, check \`enabledPlugins\` array. Show enabled vs installed count.
+3. **MCP servers** \u2014 read \`~/.claude/settings.json\`, count entries under \`mcpServers\`. List server names.
+
+### Codex Path
+
+1. **Plugin config** \u2014 read \`~/.codex/config.toml\`. List any plugin toggles. Note: Codex syncs its curated plugin marketplace at startup \u2014 this is a boot cost even if you don't use them.
+2. **MCP servers** \u2014 check \`~/.codex/config.toml\` for MCP server entries. List server names.
+
+## Step 4: Audit Hooks (Claude Code Only)
+
+Read \`.claude/settings.json\` in the project directory. List all hook definitions under the \`hooks\` key \u2014 show the event name and command for each.
+
+For Codex: note "hook auditing not yet supported on Codex."
+
+## Step 5: Report
+
+Organize findings by category. Use pass/warn indicators:
+
+\`\`\`
+## Session Overhead Report
+
+### Harness Files
+- CLAUDE.md: [N] lines [PASS \u2264200 / WARN >200]
+- Skills: [N] files, [list any over 200 lines]
+
+### Plugins
+- Installed: [N] ([list names])
+- Enabled: [N] of [M] installed
+- [If 0: "No plugins \u2014 zero boot cost from plugins."]
+
+### MCP Servers
+- Count: [N] ([list names])
+- [If 0: "No MCP servers \u2014 zero boot cost from servers."]
+
+### Hooks
+- [N] hook definitions ([list event names])
+
+### Recommendations
+- [Specific, actionable items for anything over threshold]
+- [e.g., "CLAUDE.md is 312 lines \u2014 consider splitting reference sections into docs/"]
+- [e.g., "3 MCP servers load at boot \u2014 disable unused ones in settings.json"]
+\`\`\`
+
+## Step 6: Further Resources
+
+End with:
+
+> For deeper token optimization, see:
+> - [Nate B Jones's token optimization techniques](https://www.youtube.com/watch?v=bDcgHzCBgmQ)
+> - [OB1 repo](https://github.com/nate-b-j/OB1) \u2014 Heavy File Ingestion skill and stupid button prompt kit
+> - [Joycraft's token discipline guide](docs/guides/token-discipline.md)
+
+## Edge Cases
+
+| Scenario | Behavior |
+|----------|----------|
+| Config files don't exist | Report "not found" for that check, don't error |
+| No plugins installed | Report 0 plugins \u2014 this is good, say so |
+| CLAUDE.md/AGENTS.md exactly 200 lines | PASS \u2014 threshold is \u2264200 |
+| \`~/.claude/\` or \`~/.codex/\` not accessible | Skip user-level checks, note limitation |
+| Both platforms detected | Run both audits, report separately |
 `,
   "joycraft-research.md": `---
 name: joycraft-research
@@ -1305,7 +1408,7 @@ Fix any failures before proceeding.
 
 ## 3. Update Spec Status
 
-If working from an atomic spec in \`docs/specs/\`:
+If working from an atomic spec in \`docs/specs/\` (scan recursively \u2014 specs may be in subdirectories like \`docs/specs/<feature-name>/\`):
 - All acceptance criteria met \u2014 update status to \`Complete\`
 - Partially done \u2014 update status to \`In Progress\`, note what's left
 
@@ -1336,6 +1439,8 @@ Session complete.
 - PR: [opened #N / not yet \u2014 N specs remaining]
 - Next: [what the next session should tackle]
 \`\`\`
+
+**Tip:** Run \`/clear\` before starting the next step. Your artifacts are saved to files \u2014 this conversation context is disposable.
 `,
   "joycraft-tune.md": `---
 name: joycraft-tune
@@ -1362,7 +1467,7 @@ Read CLAUDE.md and explore the project. Score each with specific evidence:
 
 | Dimension | What to Check |
 |-----------|--------------|
-| Spec Quality | \`docs/specs/\` \u2014 structured? acceptance criteria? self-contained? |
+| Spec Quality | \`docs/specs/\` (scan recursively) \u2014 structured? acceptance criteria? self-contained? |
 | Spec Granularity | Can each spec be done in one session? |
 | Behavioral Boundaries | ALWAYS/ASK FIRST/NEVER sections (or equivalent rules under any heading) |
 | Skills & Hooks | \`.claude/skills/\` files, hooks config |
@@ -1406,6 +1511,8 @@ Show a tailored roadmap: Level 2-5 table, specific next steps based on actual ga
 - **Rules under non-standard headings:** Give credit for substance.
 - **Previous assessment exists:** Read it first. If nothing to upgrade, say so.
 - **Non-Joycraft content in CLAUDE.md:** Preserve as-is. Only append.
+
+**Tip:** Run \`/joycraft-optimize\` to audit your session's token overhead \u2014 plugins, MCP servers, and harness file sizes.
 `,
   "joycraft-verify.md": `---
 name: joycraft-verify
@@ -1421,9 +1528,9 @@ The user wants independent verification of an implementation. Your job is to fin
 
 ## Step 1: Find the Spec
 
-If the user provided a spec path (e.g., \`/joycraft-verify docs/specs/2026-03-26-add-widget.md\`), use that path directly.
+If the user provided a spec path (e.g., \`/joycraft-verify docs/specs/my-feature/add-widget.md\`), use that path directly.
 
-If no path was provided, scan \`docs/specs/\` for spec files. Pick the most recently modified \`.md\` file in that directory. If \`docs/specs/\` doesn't exist or is empty, tell the user:
+If no path was provided, scan \`docs/specs/\` recursively for spec files (they may be in subdirectories like \`docs/specs/<feature-name>/\`). Pick the most recently modified \`.md\` file. If \`docs/specs/\` doesn't exist or is empty, tell the user:
 
 > No specs found in \`docs/specs/\`. Please provide a spec path: \`/joycraft-verify path/to/spec.md\`
 
@@ -2868,7 +2975,7 @@ jobs:
       - name: Find changed specs
         id: changed
         run: |
-          FILES=$(git diff --name-only --diff-filter=AM HEAD~1 HEAD -- 'docs/specs/*.md')
+          FILES=$(git diff --name-only --diff-filter=AM HEAD~1 HEAD -- 'docs/specs/**/*.md')
           echo "files<<EOF" >> "$GITHUB_OUTPUT"
           echo "$FILES" >> "$GITHUB_OUTPUT"
           echo "EOF" >> "$GITHUB_OUTPUT"
@@ -3123,7 +3230,7 @@ Ask: "Does this match? Comfortable with this approach?" If large/risky, suggest
 
 ## Phase 4: Spec the Fix
 
-Write a bug fix spec to \`docs/specs/YYYY-MM-DD-bugfix-name.md\`. Create the \`docs/specs/\` directory if it doesn't exist.
+Write a bug fix spec to \`docs/specs/<feature-or-area>/bugfix-name.md\`. Use the relevant feature name or area as the subdirectory (e.g., \`auth\`, \`cli\`, \`parser\`). Create the \`docs/specs/<feature-or-area>/\` directory if it doesn't exist.
 
 **Why:** Even bug fixes deserve a spec. It forces clarity on what "fixed" means, ensures test-first discipline, and creates a traceable record of the fix.
 
@@ -3178,7 +3285,7 @@ What changes, where?
 ## Phase 5: Hand Off
 
 \`\`\`
-Bug fix spec is ready: docs/specs/YYYY-MM-DD-bugfix-name.md
+Bug fix spec is ready: docs/specs/<feature-or-area>/bugfix-name.md
 
 Summary:
 - Bug: [one sentence]
@@ -3254,7 +3361,7 @@ Iterate until the user approves.
 
 ## Step 5: Generate Atomic Specs
 
-For each approved row, create \`docs/specs/YYYY-MM-DD-spec-name.md\`. Create the \`docs/specs/\` directory if it doesn't exist.
+For each approved row, create \`docs/specs/<feature-name>/spec-name.md\`. Derive the feature-name from the brief filename (strip the date prefix and \`.md\` \u2014 e.g., \`2026-04-06-token-discipline.md\` \u2192 \`token-discipline\`). If no brief exists, use a user-provided or inferred feature name (slugified to kebab-case). Create the \`docs/specs/<feature-name>/\` directory if it doesn't exist.
 
 **Why:** Each spec must be self-contained \u2014 a fresh session should be able to execute it without reading the Feature Brief. Copy relevant constraints and context into each spec.
 
@@ -3344,6 +3451,8 @@ To execute:
 
 Ready to start execution?
 \`\`\`
+
+**Tip:** Run \`/new\` before starting the next step. Your artifacts are saved to files \u2014 this conversation context is disposable.
 `,
   "joycraft-design.md": `---
 name: joycraft-design
@@ -3671,6 +3780,8 @@ When you're ready to move forward:
 - **Mark everything as DRAFT.** The output is a starting point, not a commitment.
 - **Keep it short.** The draft brief should be 1-2 pages max. Capture the essence, not every detail.
 - **Multiple interviews are fine.** The user might run this several times as their thinking evolves. Each creates a new dated draft.
+
+**Tip:** Run \`/new\` before starting the next step. Your artifacts are saved to files \u2014 this conversation context is disposable.
 `,
   "joycraft-lockdown.md": `---
 name: joycraft-lockdown
@@ -3890,7 +4001,7 @@ Iterate until approved.
 
 ## Phase 3: Generate Atomic Specs
 
-For each row in the decomposition table, create a self-contained spec file at \`docs/specs/YYYY-MM-DD-spec-name.md\`. Create the \`docs/specs/\` directory if it doesn't exist.
+For each row in the decomposition table, create a self-contained spec file at \`docs/specs/<feature-name>/spec-name.md\`. Derive the feature-name from the brief filename (strip the date prefix and \`.md\` \u2014 e.g., \`2026-04-06-token-discipline.md\` \u2192 \`token-discipline\`). Create the \`docs/specs/<feature-name>/\` directory if it doesn't exist.
 
 **Why:** Each spec must be understandable WITHOUT reading the Feature Brief. This prevents the "Curse of Instructions" \u2014 no spec should require holding the entire feature in context. Copy relevant context into each spec.
 
@@ -3980,6 +4091,104 @@ Ready to start?
 **Why:** A fresh session for execution produces better results. The interview session has too much context noise \u2014 a clean session with just the spec is more focused.
 
 You can also use \`$joycraft-decompose\` to re-decompose a brief if the breakdown needs adjustment, or run \`$joycraft-interview\` first for a lighter brainstorm before committing to the full workflow.
+
+**Tip:** Run \`/new\` before starting the next step. Your artifacts are saved to files \u2014 this conversation context is disposable.
+`,
+  "joycraft-optimize.md": `---
+name: joycraft-optimize
+description: Audit your Claude Code or Codex session overhead \u2014 harness file sizes, plugins, MCP servers, hooks \u2014 and report actionable recommendations
+---
+
+# Optimize \u2014 Session Overhead Audit
+
+You are auditing the user's AI development session for token overhead. Produce a conversational diagnostic report \u2014 no files created.
+
+## Step 1: Detect Platform
+
+Check which platform is active:
+- **Claude Code:** Look for \`.claude/\` directory, \`CLAUDE.md\`
+- **Codex:** Look for \`.agents/\` directory, \`AGENTS.md\`
+
+If both exist, run both checks. If neither, default to Claude Code checks and note the uncertainty.
+
+## Step 2: Audit Harness Files
+
+### Claude Code Path
+
+1. **CLAUDE.md** \u2014 count lines. Threshold: \u2264200 lines.
+2. **Skill files** \u2014 glob \`.claude/skills/**/*.md\`. Count lines per file. Threshold: \u2264200 lines each.
+
+### Codex Path
+
+1. **AGENTS.md** \u2014 count lines. Threshold: \u2264200 lines.
+2. **Skill files** \u2014 glob \`.agents/skills/**/*.md\`. Count lines per file. Threshold: \u2264200 lines each.
+
+## Step 3: Audit Plugins & MCP Servers
+
+### Claude Code Path
+
+1. **Installed plugins** \u2014 read \`~/.claude/plugins/installed_plugins.json\`. List plugin names and versions. If not found, report "no plugins file found."
+2. **Enabled plugins** \u2014 read \`~/.claude/settings.json\`, check \`enabledPlugins\` array. Show enabled vs installed count.
+3. **MCP servers** \u2014 read \`~/.claude/settings.json\`, count entries under \`mcpServers\`. List server names.
+
+### Codex Path
+
+1. **Plugin config** \u2014 read \`~/.codex/config.toml\`. List any plugin toggles. Note: Codex syncs its curated plugin marketplace at startup \u2014 this is a boot cost even if you don't use them.
+2. **MCP servers** \u2014 check \`~/.codex/config.toml\` for MCP server entries. List server names.
+
+## Step 4: Audit Hooks (Claude Code Only)
+
+Read \`.claude/settings.json\` in the project directory. List all hook definitions under the \`hooks\` key \u2014 show the event name and command for each.
+
+For Codex: note "hook auditing not yet supported on Codex."
+
+## Step 5: Report
+
+Organize findings by category. Use pass/warn indicators:
+
+\`\`\`
+## Session Overhead Report
+
+### Harness Files
+- CLAUDE.md/AGENTS.md: [N] lines [PASS \u2264200 / WARN >200]
+- Skills: [N] files, [list any over 200 lines]
+
+### Plugins
+- Installed: [N] ([list names])
+- Enabled: [N] of [M] installed
+- [If 0: "No plugins \u2014 zero boot cost from plugins."]
+
+### MCP Servers
+- Count: [N] ([list names])
+- [If 0: "No MCP servers \u2014 zero boot cost from servers."]
+
+### Hooks
+- [N] hook definitions ([list event names])
+
+### Recommendations
+- [Specific, actionable items for anything over threshold]
+- [e.g., "AGENTS.md is 312 lines \u2014 consider splitting reference sections into docs/"]
+- [e.g., "3 MCP servers load at boot \u2014 disable unused ones in config"]
+\`\`\`
+
+## Step 6: Further Resources
+
+End with:
+
+> For deeper token optimization, see:
+> - [Nate B Jones's token optimization techniques](https://www.youtube.com/watch?v=bDcgHzCBgmQ)
+> - [OB1 repo](https://github.com/nate-b-j/OB1) \u2014 Heavy File Ingestion skill and stupid button prompt kit
+> - [Joycraft's token discipline guide](docs/guides/token-discipline.md)
+
+## Edge Cases
+
+| Scenario | Behavior |
+|----------|----------|
+| Config files don't exist | Report "not found" for that check, don't error |
+| No plugins installed | Report 0 plugins \u2014 this is good, say so |
+| CLAUDE.md/AGENTS.md exactly 200 lines | PASS \u2014 threshold is \u2264200 |
+| \`~/.claude/\` or \`~/.codex/\` not accessible | Skip user-level checks, note limitation |
+| Both platforms detected | Run both audits, report separately |
 `,
   "joycraft-research.md": `---
 name: joycraft-research
@@ -4123,7 +4332,7 @@ Fix any failures before proceeding.
 
 ## 3. Update Spec Status
 
-If working from an atomic spec in \`docs/specs/\`:
+If working from an atomic spec in \`docs/specs/\` (scan recursively \u2014 specs may be in subdirectories like \`docs/specs/<feature-name>/\`):
 - All acceptance criteria met \u2014 update status to \`Complete\`
 - Partially done \u2014 update status to \`In Progress\`, note what's left
 
@@ -4154,6 +4363,8 @@ Session complete.
 - PR: [opened #N / not yet \u2014 N specs remaining]
 - Next: [what the next session should tackle]
 \`\`\`
+
+**Tip:** Run \`/new\` before starting the next step. Your artifacts are saved to files \u2014 this conversation context is disposable.
 `,
   "joycraft-tune.md": `---
 name: joycraft-tune
@@ -4179,7 +4390,7 @@ Read CLAUDE.md and explore the project. Score each with specific evidence:
 
 | Dimension | What to Check |
 |-----------|--------------|
-| Spec Quality | \`docs/specs/\` \u2014 structured? acceptance criteria? self-contained? |
+| Spec Quality | \`docs/specs/\` (scan recursively) \u2014 structured? acceptance criteria? self-contained? |
 | Spec Granularity | Can each spec be done in one session? |
 | Behavioral Boundaries | ALWAYS/ASK FIRST/NEVER sections (or equivalent rules under any heading) |
 | Skills & Hooks | \`.agents/skills/\` files, hooks config |
@@ -4223,6 +4434,8 @@ Show a tailored roadmap: Level 2-5 table, specific next steps based on actual ga
 - **Rules under non-standard headings:** Give credit for substance.
 - **Previous assessment exists:** Read it first. If nothing to upgrade, say so.
 - **Non-Joycraft content in CLAUDE.md:** Preserve as-is. Only append.
+
+**Tip:** Run \`$joycraft-optimize\` to audit your session's token overhead \u2014 plugins, MCP servers, and harness file sizes.
 `,
   "joycraft-verify.md": `---
 name: joycraft-verify
@@ -4237,9 +4450,9 @@ The user wants independent verification of an implementation. Your job is to fin
 
 ## Step 1: Find the Spec
 
-If the user provided a spec path (e.g., \`$joycraft-verify docs/specs/2026-03-26-add-widget.md\`), use that path directly.
+If the user provided a spec path (e.g., \`$joycraft-verify docs/specs/my-feature/add-widget.md\`), use that path directly.
 
-If no path was provided, scan \`docs/specs/\` for spec files. Pick the most recently modified \`.md\` file in that directory. If \`docs/specs/\` doesn't exist or is empty, tell the user:
+If no path was provided, scan \`docs/specs/\` recursively for spec files (they may be in subdirectories like \`docs/specs/<feature-name>/\`). Pick the most recently modified \`.md\` file. If \`docs/specs/\` doesn't exist or is empty, tell the user:
 
 > No specs found in \`docs/specs/\`. Please provide a spec path: \`$joycraft-verify path/to/spec.md\`
 
@@ -4376,4 +4589,4 @@ export {
   TEMPLATES,
   CODEX_SKILLS
 };
-//# sourceMappingURL=chunk-QU5VHXMV.js.map
+//# sourceMappingURL=chunk-JXSFWGIN.js.map