joycraft 0.6.16 → 0.6.17

package/README.md

@@ -91,6 +91,8 @@ npx joycraft init
 
 > Pick nothing at the harness prompt and `init` installs nothing — it tells you to re-run and choose at least one harness.
 
+**`init` only creates *missing* files.** It is safe to run on a project that already has Joycraft (or a hand-tuned `CLAUDE.md`): an existing `CLAUDE.md`, `AGENTS.md`, template, or skill file is **skipped, never regenerated** — your customizations are left untouched. Only `--force` overwrites existing files. The run summary lists what it skipped (`Skipped N file(s) (already exist, use --force to overwrite)`) so you can see exactly what was preserved. This makes `init` the right command to **fill in a private-profile clone**: a teammate who clones a `private` repo gets the committed `CLAUDE.md`/`AGENTS.md`/`docs/` but not the gitignored harness dirs — running `npx joycraft init` regenerates the missing skill files locally and leaves the committed files alone.
+
 ### Git tracking: shared vs private
 
 By default Joycraft assumes you want to **commit** the harness so your whole team

package/dist/{chunk-UEG5IO6Q.js → chunk-3JVMOJTA.js}

@@ -20,7 +20,7 @@ var SKILLS = {
   "joycraft-session-end.md": "---\nname: joycraft-session-end\ndescription: Wrap up a session \u2014 capture discoveries, verify, prepare for PR or next session\ninstructions: 22\n---\n\n# Session Wrap-Up \u2014 Feature Finisher\n\nThis is the **once-per-feature finisher** \u2014 the heavy bookend that runs **once**, when the feature's specs are done, not after every spec. It is the **only validation gate** in the loop and the single place that pushes and opens the PR.\n\n> **Two-tier wrap-up.** The light per-spec step is `joycraft-spec-done` (status bump `todo \u2192 in-review` + commit, no validation/push/PR \u2014 it runs after each spec). This skill is the heavy counterpart: full validation, consolidate the discovery stubs spec-done left behind, graduate every `in-review` spec to `done`, push, and open the PR. See `docs/reference/spec-status-lifecycle.md` for the `todo \u2192 in-review \u2192 done` lifecycle.\n\nComplete these steps in order.\n\n## 1. Consolidate Discoveries\n\n**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.\n\nThis is the **consolidation** pass: `joycraft-spec-done` may have left terse 2-line discovery **stubs** during the feature (one per surprising spec). Curate and expand those stubs into proper discovery docs now, and capture anything else surprising from the feature as a whole. If any stubs exist at `docs/discoveries/`, consolidate them (merge related ones, expand each into the full format below); then create or update a discovery file at `docs/discoveries/YYYY-MM-DD-topic.md`. Lazy-create the `docs/discoveries/` directory if it doesn't exist.\n\n(Discoveries stay flat at `docs/discoveries/` rather than per-feature, since they often span features and are read serendipitously rather than via a known path.)\n\nThe discovery file MUST start with YAML frontmatter \u2014 the 4-field personal schema:\n\n```yaml\n---\nstatus: todo\nowner: <resolved name>\ncreated: YYYY-MM-DD\nfeature: <slug-of-related-feature>   # omit if not feature-tied\n---\n```\n\n**Owner resolution:** look up the owner name in this order \u2014 (1) `git config user.name`, (2) value in your auto-memory `joycraft-owner.txt` if present, (3) ask the user once and persist.\n\nOnly capture what's NOT obvious from the code or git diff:\n- \"We thought X but found Y\" \u2014 assumptions that were wrong\n- \"This API/library behaves differently than documented\" \u2014 external gotchas\n- \"This edge case needs handling in a future spec\" \u2014 deferred work with context\n- \"The approach in the spec didn't work because...\" \u2014 spec-vs-reality gaps\n- Key decisions made during implementation that aren't in the spec\n\n**Do NOT capture:**\n- Files changed (that's the diff)\n- What you set out to do (that's the spec)\n- Step-by-step narrative of the session (nobody re-reads these)\n\nUse this format:\n\n```markdown\n# Discoveries \u2014 [topic]\n\n**Date:** YYYY-MM-DD\n**Spec:** [link to spec if applicable]\n\n## [Discovery title]\n**Expected:** [what we thought would happen]\n**Actual:** [what actually happened]\n**Impact:** [what this means for future work]\n```\n\nIf nothing surprising happened, skip the discovery file entirely. No discovery is a good sign \u2014 the spec was accurate.\n\n## 1b. Update Context Documents\n\nIf `docs/context/` exists, quickly check whether this session revealed anything about:\n\n- **Production risks** \u2014 did you interact with or learn about production vs staging systems? \u2192 Update `docs/context/production-map.md`\n- **Wrong assumptions** \u2014 did the agent (or you) assume something that turned out to be false? \u2192 Update `docs/context/dangerous-assumptions.md`\n- **Key decisions** \u2014 did you make an architectural or tooling choice? \u2192 Add a row to `docs/context/decision-log.md`\n- **Unwritten rules** \u2014 did you discover a convention or constraint not documented anywhere? \u2192 Update `docs/context/institutional-knowledge.md`\n\nWhen you UPDATE a context doc, also bump (or add) its YAML frontmatter \u2014 the 2-field shared schema:\n\n```yaml\n---\nlast_updated: YYYY-MM-DD\nlast_updated_by: <resolved name>\n---\n```\n\nIf the file already has the frontmatter, update the `last_updated` and `last_updated_by` fields in place. If it doesn't, prepend a fresh block. Context docs are *shared* artifacts (no single owner) \u2014 the shared schema reflects that.\n\nSkip this if nothing applies. Don't force it \u2014 only update when there's genuine new context.\n\n## 2. Run Validation \u2014 the ONLY validation gate\n\nThis is **mandatory** and it is the **only** validation gate in the loop: `joycraft-spec-done` deliberately skips validation (it trusts implement's per-spec TDD), so this feature-level run is the single cross-spec safety net. Never skip it.\n\nRun the project's validation commands. Check CLAUDE.md for project-specific commands. Common checks:\n\n- Type-check (e.g., `tsc --noEmit`, `mypy`, `cargo check`)\n- Tests (e.g., `npm test`, `pytest`, `cargo test`)\n- Lint (e.g., `eslint`, `ruff`, `clippy`)\n\nFix any failures before proceeding. **If validation fails, stop \u2014 do NOT graduate specs to `done` and do NOT push.**\n\n## 3. Graduate Specs `in-review \u2192 done`\n\nThis step graduates the feature's finished specs to their terminal state. Because session-end runs once at the end, **multiple specs may be waiting** in `in-review` (one per spec the loop completed via `joycraft-spec-done`). Graduate **all** of them, in **both** systems (the queue JSON and the frontmatter must never disagree):\n\nFor each spec in `docs/features/<slug>/specs/` (or `docs/bugfixes/<area>/` for bugfixes \u2014 scan recursively) whose status is `in-review`:\n\n1. **Queue JSON** \u2014 `joycraft-mark-done <spec-id> --to done <specs-dir>` (the `--to done` graduation; find `<spec-id>` by matching the entry's `file`).\n2. **Frontmatter** \u2014 edit the spec file's YAML `status:` to `done`.\n\nRules:\n- Only graduate specs that are `in-review`. A spec still at `todo` was never started \u2014 **leave it `todo` and report it as remaining** (the feature isn't fully done; see the PR gate in step 5).\n- Never write `done` for work nothing has validated \u2014 this validation run (step 2) is what licenses the graduation. (Once `verify-in-loop` ships, an independent verify performs the `in-review \u2192 done` transition; until then, this step does.)\n- `done` means **verified**, not **merged**. A merged PR is a git fact, never a spec status \u2014 do not invent a `merged` status or any fourth state beyond `todo`/`in-review`/`done`.\n\nIf working from a Feature Brief at `docs/features/<slug>/brief.md`, also check off completed specs in the decomposition table.\n\n## 4. Commit\n\nCommit all changes including the discovery file (if created) and spec status updates. The commit message should reference the spec if applicable.\n\n## 5. Push and PR (if autonomous git is enabled)\n\n**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\":\n\n1. **Push immediately.** Run `git push origin <branch>` \u2014 do not ask, do not hesitate.\n2. **Open a PR if the feature is complete.** The feature is complete when every spec is `done` (none left at `todo`/`in-review`). Check the queue JSON / decomposition table \u2014 if all specs are `done`, run `gh pr create` with a summary of all completed specs. Do not ask first.\n3. **If specs remain (`todo`),** still push. The PR comes when the feature's last spec is graduated.\n\nIf CLAUDE.md does NOT have autonomous git rules (or has \"ASK FIRST\" for pushing), ask the user before pushing.\n\n## 6. Report and Hand Off\n\n```\nFeature complete.\n- Feature: [slug]\n- Specs graduated to done: [N] (remaining at todo: [N])\n- Build: [passing / failing]\n- Discoveries: [N consolidated / none]\n- Pushed: [yes / no \u2014 and why not]\n- PR: [opened #N / not yet \u2014 N specs remaining]\n- Next: [what comes after this feature]\n```\n\nEnd with the canonical Handoff block. Include any discovery and updated-context paths produced.\n\n## Recommended Next Steps\n\nNext:\n```bash\n/joycraft-implement docs/features/<slug>/specs/<next-spec>.md\n```\nRun /clear first.\n\nIf all specs in the feature are complete, hand off to a feature-level wrap-up instead (PR review, etc.) \u2014 the Handoff block is just the slash command for whatever the next move is.\n",
   "joycraft-setup.md": '---\nname: joycraft-setup\ndescription: Set up Joycraft and get started on this project -- the first-time entry point. Run this when you\'re configuring your project, onboarding, or asking "where do I begin?" / "how do I set this up?"\ninstructions: 6\n---\n\n# Setup \u2014 The First-Run Door\n\nThis is the obvious starting point for setting up Joycraft on this project. It does no work of its own \u2014 it routes you to the skill that does the real assessment and onboarding.\n\n**Run `/joycraft-tune`.**\n\n`/joycraft-tune` detects your project\'s current harness state, scores it, applies the upgrades it can, and on a first run kicks off the context-onboarding pass for you. That\'s the whole setup flow \u2014 this alias just exists so "set up", "get started", and "first time" lead you there.\n\nDo not re-implement assessment or scoring here; hand off to `/joycraft-tune`.\n',
   "joycraft-spec-done.md": "---\nname: joycraft-spec-done\ndescription: Lightweight per-spec wrap-up \u2014 bump status to in-review, terse discovery if surprised, commit. Run after each spec in checkpoint/isolated mode; no validation, no push, no PR.\n---\n\n# Spec Done (Lightweight Per-Spec Wrap-Up)\n\nYou just finished implementing **one** atomic spec. This is the fast handshake that runs **once per spec**, before context clears \u2014 the `todo \u2192 in-review` transition in the lifecycle (`docs/reference/spec-status-lifecycle.md`). It is deliberately tiny: it does exactly four things and nothing more.\n\n> **This is NOT session-end.** It does **not** run validation, push, or open a PR. It trusts the TDD you just did in `joycraft-implement`. The heavy once-per-feature wrap-up (full validation + consolidate discoveries + push + PR) is `joycraft-session-end`, which runs once at the end of the feature.\n>\n> **Usually you don't run this by hand:** `joycraft-implement` performs these four steps itself at the end of every checkpoint/isolated spec (and `joycraft-implement-feature` drives whole queues). This skill remains the canonical definition of the wrap-up \u2014 run it manually after ad-hoc work done outside the implement skill, or when an implement run was interrupted before wrapping up.\n\n## Step 1: Bump status to `in-review` \u2014 in BOTH systems\n\nA spec's status lives in two places that must never disagree (the desync this feature exists to kill): the **queue JSON** and the spec's **frontmatter**. Update both to `in-review`.\n\n1. **Queue JSON** \u2014 use the script, not a bespoke `sed`:\n   ```bash\n   joycraft-mark-done <spec-id> --to in-review <specs-dir>\n   ```\n   Find `<spec-id>` by reading `<specs-dir>/.joycraft-spec-queue.json` and matching the entry whose `file` is the spec you just implemented. `<specs-dir>` is the folder containing the spec (e.g. `docs/features/<slug>/specs`). If the spec isn't in the manifest, `joycraft-mark-done` exits non-zero with a clear error \u2014 **surface that error, don't silently skip the bump**.\n2. **Frontmatter** \u2014 edit the spec file's YAML `status:` field to `in-review`.\n\nDo **not** graduate to `done`. The agent never self-certifies \u2014 `done` is reached only by `joycraft-session-end` (or, later, an independent verify). `spec-done` only ever reaches `in-review`.\n\n## Step 2: Terse discovery stub \u2014 ONLY if something surprised you\n\nDid anything during implementation **contradict the spec** or surprise you (an assumption that was wrong, an external API that behaved differently, an edge case the spec missed)?\n\n- **No** \u2192 skip this step entirely. A spec that went as written needs no discovery. This is the common case.\n- **Yes** \u2192 write a **2-line stub** (not a full discovery doc) at `docs/discoveries/YYYY-MM-DD-topic.md`: one line on what contradicted the spec, one line pointing at the spec/file. `joycraft-session-end`'s consolidation pass later expands these stubs into proper discovery docs \u2014 keep it terse here.\n\n## Step 3: Commit\n\nCommit the spec's implementation changes plus the status edits (and the stub, if any) with the convention:\n\n```\nspec: <spec-name>\n```\n\nKeep scope disciplined \u2014 commit the spec's changes and its status edits, not unrelated working-tree noise.\n\n## Step 4: Stop\n\nThat's it. **No** validation re-run, **no** push, **no** PR \u2014 those belong to `joycraft-session-end` at feature end. Hand off and keep the loop moving.\n\n## Recommended Next Steps\n\nIf more specs remain in this feature (checkpoint/isolated mode), continue to the next one:\n\n```bash\n/joycraft-implement docs/features/<slug>/specs/<next-spec>.md\n```\n\nWhen the feature's last spec is done, run the feature finisher once:\n\n```bash\n/joycraft-session-end\n```\n",
-  "joycraft-tune.md": "---\nname: joycraft-tune\ndescription: Assess and upgrade your project's AI development harness \u2014 score 7 dimensions, apply fixes, show path to Level 5\ninstructions: 15\n---\n\n# Tune \u2014 Project Harness Assessment & Upgrade\n\nYou are evaluating and upgrading this project's AI development harness.\n\n## Step 1: Detect Harness State\n\nCheck for: CLAUDE.md (with meaningful content), `docs/features/<slug>/` (briefs + specs), `docs/bugfixes/<area>/`, `docs/discoveries/`, `docs/context/*.md` fact-docs, `docs/context/reference/` long-form docs, `.claude/skills/`, and test configuration.\n\n## Step 2: Route\n\n- **No harness** (no CLAUDE.md or just a README): Recommend `npx joycraft init` and stop.\n- **Harness exists**: Continue to assessment.\n\n## Step 3: Assess \u2014 Score 7 Dimensions (1-5 scale)\n\nRead CLAUDE.md and explore the project. Score each with specific evidence:\n\n| Dimension | What to Check |\n|-----------|--------------|\n| Spec Quality | `docs/features/<slug>/specs/` (scan recursively; also `docs/bugfixes/<area>/`) \u2014 structured? acceptance criteria? self-contained? |\n| Spec Granularity | Can each spec be done in one session? |\n| Behavioral Boundaries | ALWAYS/ASK FIRST/NEVER sections (or equivalent rules under any heading) |\n| Skills & Hooks | `.claude/skills/` files, hooks config |\n| Documentation | `docs/` structure, templates, referenced from CLAUDE.md. Reward a lean + pointered CLAUDE.md. **Flag a CLAUDE.md exceeding ~200 lines** \u2014 recommend extracting long sections into `docs/context/reference/` and replacing them with a `## Context Map` pointer table. This is advisory only; tune never auto-edits CLAUDE.md. |\n| Knowledge Capture | `docs/discoveries/`, `docs/context/*.md` fact-docs, `docs/context/reference/` long-form docs \u2014 existence AND real content |\n| Testing & Validation | Test framework, CI pipeline, validation commands in CLAUDE.md |\n\nScore 1 = absent, 3 = partially there, 5 = comprehensive. Give credit for substance over format.\n\n## Step 4: Write Assessment\n\nWrite 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).\n\n## Step 5: Apply Upgrades\n\nApply using three tiers \u2014 do NOT ask per-item permission:\n\n**Tier 1 (silent):** Create missing dirs, install missing skills, copy missing templates, create AGENTS.md.\n\n**Private-profile note:** If `.gitignore` ignores the harness dirs (`.claude/`, `.agents/`, `.pi/` \u2014 the `private` profile), teammates who clone won't get the skill files. Ensure CLAUDE.md and AGENTS.md each carry a one-line note \u2014 append if absent, idempotent (match on the phrase \"After cloning, run\"): `> **Private setup:** The harness dirs (.claude/, .agents/, .pi/) are gitignored in this repo, so they aren't committed. After cloning, run \\`npx joycraft init\\` to regenerate the skill files locally.` Skip entirely under the `shared` profile.\n\n**Before Tier 2, ask about git autonomy:** Cautious (ask before push/PR) or Autonomous (push + PR without asking)?\n\n**First-run context onboarding:** On a first run (the context layer is empty or absent), invoke `/joycraft-gather-context` for the read-then-offer onboarding pass \u2014 it owns reading existing docs, offering a gap-only interview, and populating `docs/context/` (fact-docs and `docs/context/reference/`). Do NOT run a separate risk interview here; gather is the onboarding path. On a recurring run of an already-populated project, skip this \u2014 gather is the first-run path, not forced every time.\n\nFrom git-autonomy and gather, generate: CLAUDE.md boundary rules, `.claude/settings.json` deny patterns. Also recommend a permission mode (`auto` for most; `dontAsk` + allowlist for high-risk).\n\n**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.\n\n**Tier 3 (confirm first):** Rewriting existing sections, overwriting customized files, suggesting test framework installs.\n\nAfter applying, append to `docs/joycraft-history.md` and show a consolidated upgrade results table.\n\n## Step 6: Show Path to Level 5\n\nShow 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).\n\n**Tip:** Run `/joycraft-optimize` to audit your session's token overhead \u2014 plugins, MCP servers, and harness file sizes.\n\n## Edge Cases\n\n- **CLAUDE.md is just a README:** Treat as no harness.\n- **Non-Joycraft skills:** Acknowledge, don't replace.\n- **Rules under non-standard headings:** Give credit for substance.\n- **Previous assessment exists:** Read it first. If nothing to upgrade, say so.\n- **Non-Joycraft content in CLAUDE.md:** Preserve as-is. Only append.\n",
+  "joycraft-tune.md": "---\nname: joycraft-tune\ndescription: Assess and upgrade your project's AI development harness \u2014 score 7 dimensions, apply fixes, show path to Level 5\ninstructions: 15\n---\n\n# Tune \u2014 Project Harness Assessment & Upgrade\n\nYou are evaluating and upgrading this project's AI development harness.\n\n## Step 1: Detect Harness State\n\nCheck for: CLAUDE.md (with meaningful content), `docs/features/<slug>/` (briefs + specs), `docs/bugfixes/<area>/`, `docs/discoveries/`, `docs/context/*.md` fact-docs, `docs/context/reference/` long-form docs, `.claude/skills/`, and test configuration.\n\n## Step 2: Route\n\n- **No harness** (no CLAUDE.md or just a README): Recommend `npx joycraft init` and stop.\n- **Harness exists**: Continue to assessment.\n\n## Step 3: Assess \u2014 Score 7 Dimensions (1-5 scale)\n\nRead CLAUDE.md and explore the project. Score each with specific evidence:\n\n| Dimension | What to Check |\n|-----------|--------------|\n| Spec Quality | `docs/features/<slug>/specs/` (scan recursively; also `docs/bugfixes/<area>/`) \u2014 structured? acceptance criteria? self-contained? |\n| Spec Granularity | Can each spec be done in one session? |\n| Behavioral Boundaries | ALWAYS/ASK FIRST/NEVER sections (or equivalent rules under any heading) |\n| Skills & Hooks | `.claude/skills/` files, hooks config |\n| Documentation | `docs/` structure, templates, referenced from CLAUDE.md. Reward a lean + pointered CLAUDE.md. **Flag a CLAUDE.md exceeding ~200 lines** \u2014 recommend extracting long sections into `docs/context/reference/` and replacing them with a `## Context Map` pointer table. This is advisory only; tune never auto-edits CLAUDE.md. |\n| Knowledge Capture | `docs/discoveries/`, `docs/context/*.md` fact-docs, `docs/context/reference/` long-form docs \u2014 existence AND real content |\n| Testing & Validation | Test framework, CI pipeline, validation commands in CLAUDE.md |\n\nScore 1 = absent, 3 = partially there, 5 = comprehensive. Give credit for substance over format.\n\n## Step 4: Write Assessment\n\nWrite 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).\n\n## Step 5: Apply Upgrades\n\nApply using three tiers \u2014 do NOT ask per-item permission:\n\n**Tier 1 (silent):** Create missing dirs, install missing skills, copy missing templates, create AGENTS.md.\n\n**Private-profile note:** If `.gitignore` ignores the harness dirs (`.claude/`, `.agents/`, `.pi/` \u2014 the `private` profile), teammates who clone won't get the skill files. Ensure CLAUDE.md and AGENTS.md each carry a one-line note \u2014 append if absent, idempotent (match on the phrase \"After cloning, run\"): `> **Private setup:** The harness dirs (.claude/, .agents/, .pi/) are gitignored in this repo, so they aren't committed. After cloning, run \\`npx joycraft init\\` to regenerate the skill files locally \u2014 it only creates missing files and leaves your committed \\`CLAUDE.md\\`, \\`AGENTS.md\\`, and \\`docs/\\` untouched (use \\`--force\\` only if you deliberately want to regenerate them).` Skip entirely under the `shared` profile.\n\n**Already-tracked harness files (private profile):** If the project is on the `private` profile but `git ls-files` shows tracked files under `.claude/`, `.agents/`, or `.pi/`, those files were committed before the switch and the gitignore won't untrack them. Surface the copy-pasteable fix once, prominently, in your upgrade results \u2014 `git rm -r --cached .claude .agents .pi` \u2014 and note it's advisory (never run git yourself). Skip when no harness files are tracked, and skip entirely under `shared`.\n\n**Before Tier 2, ask about git autonomy:** Cautious (ask before push/PR) or Autonomous (push + PR without asking)?\n\n**First-run context onboarding:** On a first run (the context layer is empty or absent), invoke `/joycraft-gather-context` for the read-then-offer onboarding pass \u2014 it owns reading existing docs, offering a gap-only interview, and populating `docs/context/` (fact-docs and `docs/context/reference/`). Do NOT run a separate risk interview here; gather is the onboarding path. On a recurring run of an already-populated project, skip this \u2014 gather is the first-run path, not forced every time.\n\nFrom git-autonomy and gather, generate: CLAUDE.md boundary rules, `.claude/settings.json` deny patterns. Also recommend a permission mode (`auto` for most; `dontAsk` + allowlist for high-risk).\n\n**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.\n\n**Tier 3 (confirm first):** Rewriting existing sections, overwriting customized files, suggesting test framework installs.\n\nAfter applying, append to `docs/joycraft-history.md` and show a consolidated upgrade results table.\n\n## Step 6: Show Path to Level 5\n\nShow 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).\n\n**Tip:** Run `/joycraft-optimize` to audit your session's token overhead \u2014 plugins, MCP servers, and harness file sizes.\n\n## Edge Cases\n\n- **CLAUDE.md is just a README:** Treat as no harness.\n- **Non-Joycraft skills:** Acknowledge, don't replace.\n- **Rules under non-standard headings:** Give credit for substance.\n- **Previous assessment exists:** Read it first. If nothing to upgrade, say so.\n- **Non-Joycraft content in CLAUDE.md:** Preserve as-is. Only append.\n",
   "joycraft-verify.md": '---\nname: joycraft-verify\ndescription: Spawn an independent verifier subagent to check an implementation against its spec -- read-only, no code edits, structured pass/fail verdict\ninstructions: 30\n---\n\n# Verify Implementation Against Spec\n\nThe 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.\n\n**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.\n\n## Step 1: Find the Spec\n\nIf the user provided a spec path (e.g., `/joycraft-verify docs/features/<slug>/specs/add-widget.md`), use that path directly.\n\nIf no path was provided, scan `docs/features/*/specs/` recursively for spec files (and `docs/bugfixes/<area>/` for bugfixes). Pick the most recently modified `.md` file. If no specs exist, tell the user:\n\n> No specs found under `docs/features/*/specs/` or `docs/bugfixes/`. Please provide a spec path: `/joycraft-verify path/to/spec.md`\n\n## Step 2: Read and Parse the Spec\n\nRead the spec file and extract:\n\n1. **Spec name** -- from the H1 title\n2. **Acceptance Criteria** -- the checklist under the `## Acceptance Criteria` section\n3. **Test Plan** -- the table under the `## Test Plan` section, including any test commands\n4. **Constraints** -- the `## Constraints` section if present\n\nIf the spec has no Acceptance Criteria section, tell the user:\n\n> This spec doesn\'t have an Acceptance Criteria section. Verification needs criteria to check against. Add acceptance criteria to the spec and try again.\n\nIf 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.\n\n## Step 3: Identify Test Commands\n\nLook for test commands in these locations (in priority order):\n\n1. The spec\'s Test Plan section (look for commands in backticks or "Type" column entries like "unit", "integration", "e2e", "build")\n2. The project\'s CLAUDE.md (look for test/build commands in the Development Workflow section)\n3. Common defaults based on the project type:\n   - Node.js: `npm test` or `pnpm test --run`\n   - Python: `pytest`\n   - Rust: `cargo test`\n   - Go: `go test ./...`\n\nBuild a list of specific commands the verifier should run.\n\n## Step 4: Spawn the Verifier Subagent\n\nUse 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.\n\n```\nYou 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.\n\nRULES -- these are hard constraints, not suggestions:\n- You may READ any file using the Read tool or cat\n- You may RUN these specific test/build commands: [TEST_COMMANDS]\n- You may NOT edit, create, or delete any files\n- You may NOT run commands that modify state (no git commit, no npm install, no file writes)\n- You may NOT install packages or access the network\n- Report what you OBSERVE, not what you expect or hope\n\nSPEC NAME: [SPEC_NAME]\n\nACCEPTANCE CRITERIA:\n[ACCEPTANCE_CRITERIA]\n\nTEST PLAN:\n[TEST_PLAN]\n\nCONSTRAINTS:\n[CONSTRAINTS_OR_NONE]\n\nYOUR TASK:\nFor each acceptance criterion, determine if it PASSES or FAILS based on evidence:\n\n1. Run the test commands listed above. Record the output.\n2. For each acceptance criterion:\n   a. Check if there is a corresponding test and whether it passes\n   b. If no test exists, read the relevant source files to verify the criterion is met\n   c. If the criterion cannot be verified by reading code or running tests, mark it MANUAL CHECK NEEDED\n3. For criteria about build/test passing, actually run the commands and report results.\n\nOUTPUT FORMAT -- you MUST use this exact format:\n\nVERIFICATION REPORT\n\n| # | Criterion | Verdict | Evidence |\n|---|-----------|---------|----------|\n| 1 | [criterion text] | PASS/FAIL/MANUAL CHECK NEEDED | [what you observed] |\n| 2 | [criterion text] | PASS/FAIL/MANUAL CHECK NEEDED | [what you observed] |\n[continue for all criteria]\n\nSUMMARY: X/Y criteria passed. [Z failures need attention. / All criteria verified.]\n\nIf any test commands fail to run (missing dependencies, wrong command, etc.), report the error as evidence for a FAIL verdict on the relevant criterion.\n```\n\n## Step 5: Format and Present the Verdict\n\nTake the subagent\'s response and present it to the user in this format:\n\n```\n## Verification Report -- [Spec Name]\n\n| # | Criterion | Verdict | Evidence |\n|---|-----------|---------|----------|\n| 1 | ... | PASS | ... |\n| 2 | ... | FAIL | ... |\n\n**Overall: X/Y criteria passed.**\n\n[If all passed:]\nAll criteria verified. Ready to commit and open a PR.\n\n[If any failed:]\nN failures need attention. Review the evidence above and fix before proceeding.\n\n[If any MANUAL CHECK NEEDED:]\nN criteria need manual verification -- they can\'t be checked by reading code or running tests alone.\n```\n\n## Step 6: Suggest Next Steps\n\nBased on the verdict:\n\n- **All PASS:** Suggest committing and opening a PR, or running `/joycraft-session-end` to capture discoveries.\n- **Some FAIL:** List the failed criteria and suggest the user fix them, then run `/joycraft-verify` again.\n- **MANUAL CHECK NEEDED items:** Explain what needs human eyes and why automation couldn\'t verify it.\n\n**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.\n\n## Edge Cases\n\n| Scenario | Behavior |\n|----------|----------|\n| 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 |\n| All tests pass but a criterion is not testable | Mark as MANUAL CHECK NEEDED with explanation |\n| Subagent can\'t run tests (missing deps) | Report the error as FAIL evidence |\n| No specs found and no path given | Tell user to provide a spec path or create a spec first |\n| Spec status is "Complete" | Still run verification -- "Complete" means the implementer thinks it\'s done, verification confirms |\n'
 };
 var TEMPLATES = {
@@ -278,7 +278,7 @@ var CODEX_SKILLS = {
   "joycraft-session-end.md": "---\nname: joycraft-session-end\ndescription: Wrap up a session \u2014 capture discoveries, verify, prepare for PR or next session\n---\n\n# Session Wrap-Up \u2014 Feature Finisher\n\nThis is the **once-per-feature finisher** \u2014 the heavy bookend that runs **once**, when the feature's specs are done, not after every spec. It is the **only validation gate** in the loop and the single place that pushes and opens the PR.\n\n> **Two-tier wrap-up.** The light per-spec step is `joycraft-spec-done` (status bump `todo \u2192 in-review` + commit, no validation/push/PR \u2014 it runs after each spec). This skill is the heavy counterpart: full validation, consolidate the discovery stubs spec-done left behind, graduate every `in-review` spec to `done`, push, and open the PR. See `docs/reference/spec-status-lifecycle.md` for the `todo \u2192 in-review \u2192 done` lifecycle.\n\nComplete these steps in order.\n\n## 1. Consolidate Discoveries\n\n**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.\n\nThis is the **consolidation** pass: `joycraft-spec-done` may have left terse 2-line discovery **stubs** during the feature (one per surprising spec). Curate and expand those stubs into proper discovery docs now, and capture anything else surprising from the feature as a whole. If any stubs exist at `docs/discoveries/`, consolidate them (merge related ones, expand each into the full format below); then create or update a discovery file at `docs/discoveries/YYYY-MM-DD-topic.md`. Lazy-create the `docs/discoveries/` directory if it doesn't exist.\n\n(Discoveries stay flat at `docs/discoveries/` rather than per-feature, since they often span features and are read serendipitously rather than via a known path.)\n\nThe discovery file MUST start with YAML frontmatter \u2014 the 4-field personal schema:\n\n```yaml\n---\nstatus: todo\nowner: <resolved name>\ncreated: YYYY-MM-DD\nfeature: <slug-of-related-feature>   # omit if not feature-tied\n---\n```\n\n**Owner resolution:** look up the owner name in this order \u2014 (1) `git config user.name`, (2) value in your auto-memory `joycraft-owner.txt` if present, (3) ask the user once and persist.\n\nOnly capture what's NOT obvious from the code or git diff:\n- \"We thought X but found Y\" \u2014 assumptions that were wrong\n- \"This API/library behaves differently than documented\" \u2014 external gotchas\n- \"This edge case needs handling in a future spec\" \u2014 deferred work with context\n- \"The approach in the spec didn't work because...\" \u2014 spec-vs-reality gaps\n- Key decisions made during implementation that aren't in the spec\n\n**Do NOT capture:**\n- Files changed (that's the diff)\n- What you set out to do (that's the spec)\n- Step-by-step narrative of the session (nobody re-reads these)\n\nUse this format:\n\n```markdown\n# Discoveries \u2014 [topic]\n\n**Date:** YYYY-MM-DD\n**Spec:** [link to spec if applicable]\n\n## [Discovery title]\n**Expected:** [what we thought would happen]\n**Actual:** [what actually happened]\n**Impact:** [what this means for future work]\n```\n\nIf nothing surprising happened, skip the discovery file entirely. No discovery is a good sign \u2014 the spec was accurate.\n\n## 1b. Update Context Documents\n\nIf `docs/context/` exists, quickly check whether this session revealed anything about:\n\n- **Production risks** \u2014 did you interact with or learn about production vs staging systems? \u2192 Update `docs/context/production-map.md`\n- **Wrong assumptions** \u2014 did the agent (or you) assume something that turned out to be false? \u2192 Update `docs/context/dangerous-assumptions.md`\n- **Key decisions** \u2014 did you make an architectural or tooling choice? \u2192 Add a row to `docs/context/decision-log.md`\n- **Unwritten rules** \u2014 did you discover a convention or constraint not documented anywhere? \u2192 Update `docs/context/institutional-knowledge.md`\n\nWhen you UPDATE a context doc, also bump (or add) its YAML frontmatter \u2014 the 2-field shared schema:\n\n```yaml\n---\nlast_updated: YYYY-MM-DD\nlast_updated_by: <resolved name>\n---\n```\n\nIf the file already has the frontmatter, update the `last_updated` and `last_updated_by` fields in place. If it doesn't, prepend a fresh block. Context docs are *shared* artifacts (no single owner) \u2014 the shared schema reflects that.\n\nSkip this if nothing applies. Don't force it \u2014 only update when there's genuine new context.\n\n## 2. Run Validation \u2014 the ONLY validation gate\n\nThis is **mandatory** and it is the **only** validation gate in the loop: `joycraft-spec-done` deliberately skips validation (it trusts implement's per-spec TDD), so this feature-level run is the single cross-spec safety net. Never skip it.\n\nRun the project's validation commands. Check AGENTS.md for project-specific commands. Common checks:\n\n- Type-check (e.g., `tsc --noEmit`, `mypy`, `cargo check`)\n- Tests (e.g., `npm test`, `pytest`, `cargo test`)\n- Lint (e.g., `eslint`, `ruff`, `clippy`)\n\nFix any failures before proceeding. **If validation fails, stop \u2014 do NOT graduate specs to `done` and do NOT push.**\n\n## 3. Graduate Specs `in-review \u2192 done`\n\nThis step graduates the feature's finished specs to their terminal state. Because session-end runs once at the end, **multiple specs may be waiting** in `in-review` (one per spec the loop completed via `joycraft-spec-done`). Graduate **all** of them, in **both** systems (the queue JSON and the frontmatter must never disagree):\n\nFor each spec in `docs/features/<slug>/specs/` (or `docs/bugfixes/<area>/` for bugfixes \u2014 scan recursively) whose status is `in-review`:\n\n1. **Queue JSON** \u2014 `joycraft-mark-done <spec-id> --to done <specs-dir>` (the `--to done` graduation; find `<spec-id>` by matching the entry's `file`).\n2. **Frontmatter** \u2014 edit the spec file's YAML `status:` to `done`.\n\nRules:\n- Only graduate specs that are `in-review`. A spec still at `todo` was never started \u2014 **leave it `todo` and report it as remaining** (the feature isn't fully done; see the PR gate in step 5).\n- Never write `done` for work nothing has validated \u2014 this validation run (step 2) is what licenses the graduation. (Once `verify-in-loop` ships, an independent verify performs the `in-review \u2192 done` transition; until then, this step does.)\n- `done` means **verified**, not **merged**. A merged PR is a git fact, never a spec status \u2014 do not invent a `merged` status or any fourth state beyond `todo`/`in-review`/`done`.\n\nIf working from a Feature Brief at `docs/features/<slug>/brief.md`, also check off completed specs in the decomposition table.\n\n## 4. Commit\n\nCommit all changes including the discovery file (if created) and spec status updates. The commit message should reference the spec if applicable.\n\n## 5. Push and PR (if autonomous git is enabled)\n\n**Check AGENTS.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\":\n\n1. **Push immediately.** Run `git push origin <branch>` \u2014 do not ask, do not hesitate.\n2. **Open a PR if the feature is complete.** The feature is complete when every spec is `done` (none left at `todo`/`in-review`). Check the queue JSON / decomposition table \u2014 if all specs are `done`, run `gh pr create` with a summary of all completed specs. Do not ask first.\n3. **If specs remain (`todo`),** still push. The PR comes when the feature's last spec is graduated.\n\nIf AGENTS.md does NOT have autonomous git rules (or has \"ASK FIRST\" for pushing), ask the user before pushing.\n\n## 6. Report and Hand Off\n\n```\nFeature complete.\n- Feature: [slug]\n- Specs graduated to done: [N] (remaining at todo: [N])\n- Build: [passing / failing]\n- Discoveries: [N consolidated / none]\n- Pushed: [yes / no \u2014 and why not]\n- PR: [opened #N / not yet \u2014 N specs remaining]\n- Next: [what comes after this feature]\n```\n\nEnd with the canonical Handoff block. Include any discovery and updated-context paths produced.\n\n## Recommended Next Steps\n\nNext:\n```bash\n$joycraft-implement docs/features/<slug>/specs/<next-spec>.md\n```\nRun run `/clear` in the CLI, or press Cmd+N (Ctrl+N on Windows/Linux) for a new thread in the desktop/IDE app first.\n\nIf all specs in the feature are complete, hand off to a feature-level wrap-up instead (PR review, etc.) \u2014 the Handoff block is just the slash command for whatever the next move is.\n",
   "joycraft-setup.md": '---\nname: joycraft-setup\ndescription: Set up Joycraft and get started on this project -- the first-time entry point. Run this when you\'re configuring your project, onboarding, or asking "where do I begin?" / "how do I set this up?"\n---\n\n# Setup \u2014 The First-Run Door\n\nThis is the obvious starting point for setting up Joycraft on this project. It does no work of its own \u2014 it routes you to the skill that does the real assessment and onboarding.\n\n**Run `$joycraft-tune`.**\n\n`$joycraft-tune` detects your project\'s current harness state, scores it, applies the upgrades it can, and on a first run kicks off the context-onboarding pass for you. That\'s the whole setup flow \u2014 this alias just exists so "set up", "get started", and "first time" lead you there.\n\nDo not re-implement assessment or scoring here; hand off to `$joycraft-tune`.\n',
   "joycraft-spec-done.md": "---\nname: joycraft-spec-done\ndescription: Lightweight per-spec wrap-up \u2014 bump status to in-review, terse discovery if surprised, commit. Run after each spec in checkpoint/isolated mode; no validation, no push, no PR.\n---\n\n# Spec Done (Lightweight Per-Spec Wrap-Up)\n\nYou just finished implementing **one** atomic spec. This is the fast handshake that runs **once per spec**, before context clears \u2014 the `todo \u2192 in-review` transition in the lifecycle (`docs/reference/spec-status-lifecycle.md`). It is deliberately tiny: it does exactly four things and nothing more.\n\n> **This is NOT session-end.** It does **not** run validation, push, or open a PR. It trusts the TDD you just did in `joycraft-implement`. The heavy once-per-feature wrap-up (full validation + consolidate discoveries + push + PR) is `joycraft-session-end`, which runs once at the end of the feature.\n>\n> **Usually you don't run this by hand:** `joycraft-implement` performs these four steps itself at the end of every checkpoint/isolated spec (and `joycraft-implement-feature` drives whole queues). This skill remains the canonical definition of the wrap-up \u2014 run it manually after ad-hoc work done outside the implement skill, or when an implement run was interrupted before wrapping up.\n\n## Step 1: Bump status to `in-review` \u2014 in BOTH systems\n\nA spec's status lives in two places that must never disagree (the desync this feature exists to kill): the **queue JSON** and the spec's **frontmatter**. Update both to `in-review`.\n\n1. **Queue JSON** \u2014 use the script, not a bespoke `sed`:\n   ```bash\n   joycraft-mark-done <spec-id> --to in-review <specs-dir>\n   ```\n   Find `<spec-id>` by reading `<specs-dir>/.joycraft-spec-queue.json` and matching the entry whose `file` is the spec you just implemented. `<specs-dir>` is the folder containing the spec (e.g. `docs/features/<slug>/specs`). If the spec isn't in the manifest, `joycraft-mark-done` exits non-zero with a clear error \u2014 **surface that error, don't silently skip the bump**.\n2. **Frontmatter** \u2014 edit the spec file's YAML `status:` field to `in-review`.\n\nDo **not** graduate to `done`. The agent never self-certifies \u2014 `done` is reached only by `joycraft-session-end` (or, later, an independent verify). `spec-done` only ever reaches `in-review`.\n\n## Step 2: Terse discovery stub \u2014 ONLY if something surprised you\n\nDid anything during implementation **contradict the spec** or surprise you (an assumption that was wrong, an external API that behaved differently, an edge case the spec missed)?\n\n- **No** \u2192 skip this step entirely. A spec that went as written needs no discovery. This is the common case.\n- **Yes** \u2192 write a **2-line stub** (not a full discovery doc) at `docs/discoveries/YYYY-MM-DD-topic.md`: one line on what contradicted the spec, one line pointing at the spec/file. `joycraft-session-end`'s consolidation pass later expands these stubs into proper discovery docs \u2014 keep it terse here.\n\n## Step 3: Commit\n\nCommit the spec's implementation changes plus the status edits (and the stub, if any) with the convention:\n\n```\nspec: <spec-name>\n```\n\nKeep scope disciplined \u2014 commit the spec's changes and its status edits, not unrelated working-tree noise.\n\n## Step 4: Stop\n\nThat's it. **No** validation re-run, **no** push, **no** PR \u2014 those belong to `joycraft-session-end` at feature end. Hand off and keep the loop moving.\n\n## Recommended Next Steps\n\nIf more specs remain in this feature (checkpoint/isolated mode), continue to the next one:\n\n```bash\n$joycraft-implement docs/features/<slug>/specs/<next-spec>.md\n```\n\nWhen the feature's last spec is done, run the feature finisher once:\n\n```bash\n$joycraft-session-end\n```\n",
-  "joycraft-tune.md": "---\nname: joycraft-tune\ndescription: Assess and upgrade your project's AI development harness \u2014 score 7 dimensions, apply fixes, show path to Level 5\n---\n\n# Tune \u2014 Project Harness Assessment & Upgrade\n\nYou are evaluating and upgrading this project's AI development harness.\n\n## Step 1: Detect Harness State\n\nCheck for: AGENTS.md (with meaningful content), `docs/features/<slug>/` (briefs + specs), `docs/bugfixes/<area>/`, `docs/discoveries/`, `docs/context/*.md` fact-docs, `docs/context/reference/` long-form docs, `.agents/skills/`, and test configuration.\n\n## Step 2: Route\n\n- **No harness** (no AGENTS.md or just a README): Recommend `npx joycraft init` and stop.\n- **Harness exists**: Continue to assessment.\n\n## Step 3: Assess \u2014 Score 7 Dimensions (1-5 scale)\n\nRead AGENTS.md and explore the project. Score each with specific evidence:\n\n| Dimension | What to Check |\n|-----------|--------------|\n| Spec Quality | `docs/features/<slug>/specs/` (scan recursively; also `docs/bugfixes/<area>/`) \u2014 structured? acceptance criteria? self-contained? |\n| Spec Granularity | Can each spec be done in one session? |\n| Behavioral Boundaries | ALWAYS/ASK FIRST/NEVER sections (or equivalent rules under any heading) |\n| Skills & Hooks | `.agents/skills/` files, hooks config |\n| Documentation | `docs/` structure, templates, referenced from AGENTS.md. Reward a lean + pointered AGENTS.md. **Flag a AGENTS.md exceeding ~200 lines** \u2014 recommend extracting long sections into `docs/context/reference/` and replacing them with a `## Context Map` pointer table. This is advisory only; tune never auto-edits AGENTS.md. |\n| Knowledge Capture | `docs/discoveries/`, `docs/context/*.md` fact-docs, `docs/context/reference/` long-form docs \u2014 existence AND real content |\n| Testing & Validation | Test framework, CI pipeline, validation commands in AGENTS.md |\n\nScore 1 = absent, 3 = partially there, 5 = comprehensive. Give credit for substance over format.\n\n## Step 4: Write Assessment\n\nWrite 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).\n\n## Step 5: Apply Upgrades\n\nApply using three tiers \u2014 do NOT ask per-item permission:\n\n**Tier 1 (silent):** Create missing dirs, install missing skills, copy missing templates, create AGENTS.md.\n\n**Private-profile note:** If `.gitignore` ignores the harness dirs (`.claude/`, `.agents/`, `.pi/` \u2014 the `private` profile), teammates who clone won't get the skill files. Ensure CLAUDE.md and AGENTS.md each carry a one-line note \u2014 append if absent, idempotent (match on the phrase \"After cloning, run\"): `> **Private setup:** The harness dirs (.claude/, .agents/, .pi/) are gitignored in this repo, so they aren't committed. After cloning, run \\`npx joycraft init\\` to regenerate the skill files locally.` Skip entirely under the `shared` profile.\n\n**Before Tier 2, ask about git autonomy:** Cautious (ask before push/PR) or Autonomous (push + PR without asking)?\n\n**First-run context onboarding:** On a first run (the context layer is empty or absent), invoke `$joycraft-gather-context` for the read-then-offer onboarding pass \u2014 it owns reading existing docs, offering a gap-only interview, and populating `docs/context/` (fact-docs and `docs/context/reference/`). Do NOT run a separate risk interview here; gather is the onboarding path. On a recurring run of an already-populated project, skip this \u2014 gather is the first-run path, not forced every time.\n\nFrom git-autonomy and gather, generate: AGENTS.md boundary rules, `.claude/settings.json` deny patterns. Also recommend a permission mode (`auto` for most; `dontAsk` + allowlist for high-risk).\n\n**Tier 2 (show diff):** Add missing AGENTS.md sections (Boundaries, Workflow, Key Files). Draft from real codebase content. Append only \u2014 never reformat existing content.\n\n**Tier 3 (confirm first):** Rewriting existing sections, overwriting customized files, suggesting test framework installs.\n\nAfter applying, append to `docs$joycraft-history.md` and show a consolidated upgrade results table.\n\n## Step 6: Show Path to Level 5\n\nShow 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).\n\n**Tip:** Run `$joycraft-optimize` to audit your session's token overhead \u2014 plugins, MCP servers, and harness file sizes.\n\n## Edge Cases\n\n- **AGENTS.md is just a README:** Treat as no harness.\n- **Non-Joycraft skills:** Acknowledge, don't replace.\n- **Rules under non-standard headings:** Give credit for substance.\n- **Previous assessment exists:** Read it first. If nothing to upgrade, say so.\n- **Non-Joycraft content in AGENTS.md:** Preserve as-is. Only append.\n",
+  "joycraft-tune.md": "---\nname: joycraft-tune\ndescription: Assess and upgrade your project's AI development harness \u2014 score 7 dimensions, apply fixes, show path to Level 5\n---\n\n# Tune \u2014 Project Harness Assessment & Upgrade\n\nYou are evaluating and upgrading this project's AI development harness.\n\n## Step 1: Detect Harness State\n\nCheck for: AGENTS.md (with meaningful content), `docs/features/<slug>/` (briefs + specs), `docs/bugfixes/<area>/`, `docs/discoveries/`, `docs/context/*.md` fact-docs, `docs/context/reference/` long-form docs, `.agents/skills/`, and test configuration.\n\n## Step 2: Route\n\n- **No harness** (no AGENTS.md or just a README): Recommend `npx joycraft init` and stop.\n- **Harness exists**: Continue to assessment.\n\n## Step 3: Assess \u2014 Score 7 Dimensions (1-5 scale)\n\nRead AGENTS.md and explore the project. Score each with specific evidence:\n\n| Dimension | What to Check |\n|-----------|--------------|\n| Spec Quality | `docs/features/<slug>/specs/` (scan recursively; also `docs/bugfixes/<area>/`) \u2014 structured? acceptance criteria? self-contained? |\n| Spec Granularity | Can each spec be done in one session? |\n| Behavioral Boundaries | ALWAYS/ASK FIRST/NEVER sections (or equivalent rules under any heading) |\n| Skills & Hooks | `.agents/skills/` files, hooks config |\n| Documentation | `docs/` structure, templates, referenced from AGENTS.md. Reward a lean + pointered AGENTS.md. **Flag a AGENTS.md exceeding ~200 lines** \u2014 recommend extracting long sections into `docs/context/reference/` and replacing them with a `## Context Map` pointer table. This is advisory only; tune never auto-edits AGENTS.md. |\n| Knowledge Capture | `docs/discoveries/`, `docs/context/*.md` fact-docs, `docs/context/reference/` long-form docs \u2014 existence AND real content |\n| Testing & Validation | Test framework, CI pipeline, validation commands in AGENTS.md |\n\nScore 1 = absent, 3 = partially there, 5 = comprehensive. Give credit for substance over format.\n\n## Step 4: Write Assessment\n\nWrite 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).\n\n## Step 5: Apply Upgrades\n\nApply using three tiers \u2014 do NOT ask per-item permission:\n\n**Tier 1 (silent):** Create missing dirs, install missing skills, copy missing templates, create AGENTS.md.\n\n**Private-profile note:** If `.gitignore` ignores the harness dirs (`.claude/`, `.agents/`, `.pi/` \u2014 the `private` profile), teammates who clone won't get the skill files. Ensure CLAUDE.md and AGENTS.md each carry a one-line note \u2014 append if absent, idempotent (match on the phrase \"After cloning, run\"): `> **Private setup:** The harness dirs (.claude/, .agents/, .pi/) are gitignored in this repo, so they aren't committed. After cloning, run \\`npx joycraft init\\` to regenerate the skill files locally \u2014 it only creates missing files and leaves your committed \\`CLAUDE.md\\`, \\`AGENTS.md\\`, and \\`docs/\\` untouched (use \\`--force\\` only if you deliberately want to regenerate them).` Skip entirely under the `shared` profile.\n\n**Already-tracked harness files (private profile):** If the project is on the `private` profile but `git ls-files` shows tracked files under `.claude/`, `.agents/`, or `.pi/`, those files were committed before the switch and the gitignore won't untrack them. Surface the copy-pasteable fix once, prominently, in your upgrade results \u2014 `git rm -r --cached .claude .agents .pi` \u2014 and note it's advisory (never run git yourself). Skip when no harness files are tracked, and skip entirely under `shared`.\n\n**Before Tier 2, ask about git autonomy:** Cautious (ask before push/PR) or Autonomous (push + PR without asking)?\n\n**First-run context onboarding:** On a first run (the context layer is empty or absent), invoke `$joycraft-gather-context` for the read-then-offer onboarding pass \u2014 it owns reading existing docs, offering a gap-only interview, and populating `docs/context/` (fact-docs and `docs/context/reference/`). Do NOT run a separate risk interview here; gather is the onboarding path. On a recurring run of an already-populated project, skip this \u2014 gather is the first-run path, not forced every time.\n\nFrom git-autonomy and gather, generate: AGENTS.md boundary rules, `.claude/settings.json` deny patterns. Also recommend a permission mode (`auto` for most; `dontAsk` + allowlist for high-risk).\n\n**Tier 2 (show diff):** Add missing AGENTS.md sections (Boundaries, Workflow, Key Files). Draft from real codebase content. Append only \u2014 never reformat existing content.\n\n**Tier 3 (confirm first):** Rewriting existing sections, overwriting customized files, suggesting test framework installs.\n\nAfter applying, append to `docs$joycraft-history.md` and show a consolidated upgrade results table.\n\n## Step 6: Show Path to Level 5\n\nShow 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).\n\n**Tip:** Run `$joycraft-optimize` to audit your session's token overhead \u2014 plugins, MCP servers, and harness file sizes.\n\n## Edge Cases\n\n- **AGENTS.md is just a README:** Treat as no harness.\n- **Non-Joycraft skills:** Acknowledge, don't replace.\n- **Rules under non-standard headings:** Give credit for substance.\n- **Previous assessment exists:** Read it first. If nothing to upgrade, say so.\n- **Non-Joycraft content in AGENTS.md:** Preserve as-is. Only append.\n",
   "joycraft-verify.md": '---\nname: joycraft-verify\ndescription: Spawn an independent verifier subagent to check an implementation against its spec -- read-only, no code edits, structured pass/fail verdict\n---\n\n# Verify Implementation Against Spec\n\nThe 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.\n\n**Why a separate subagent?** 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.\n\n## Step 1: Find the Spec\n\nIf the user provided a spec path (e.g., `$joycraft-verify docs/features/<slug>/specs/add-widget.md`), use that path directly.\n\nIf no path was provided, scan `docs/features/*/specs/` recursively for spec files (and `docs/bugfixes/<area>/` for bugfixes). Pick the most recently modified `.md` file. If no specs exist, tell the user:\n\n> No specs found under `docs/features/*/specs/` or `docs/bugfixes/`. Please provide a spec path: `$joycraft-verify path/to/spec.md`\n\n## Step 2: Read and Parse the Spec\n\nRead the spec file and extract:\n\n1. **Spec name** -- from the H1 title\n2. **Acceptance Criteria** -- the checklist under the `## Acceptance Criteria` section\n3. **Test Plan** -- the table under the `## Test Plan` section, including any test commands\n4. **Constraints** -- the `## Constraints` section if present\n\nIf the spec has no Acceptance Criteria section, tell the user:\n\n> This spec doesn\'t have an Acceptance Criteria section. Verification needs criteria to check against. Add acceptance criteria to the spec and try again.\n\nIf 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.\n\n## Step 3: Identify Test Commands\n\nLook for test commands in these locations (in priority order):\n\n1. The spec\'s Test Plan section (look for commands in backticks or "Type" column entries like "unit", "integration", "e2e", "build")\n2. The project\'s AGENTS.md (look for test/build commands in the Development Workflow section)\n3. Common defaults based on the project type:\n   - Node.js: `npm test` or `pnpm test --run`\n   - Python: `pytest`\n   - Rust: `cargo test`\n   - Go: `go test ./...`\n\nBuild a list of specific commands the verifier should run.\n\n## Step 4: Spawn the Verifier Subagent\n\nSpawn a concurrent subagent thread with the following prompt. Replace the placeholders with the actual content extracted in Steps 2-3.\n\n**Important:** The subagent must be given read-only constraints. It may search the codebase, read files, and run the specified test/build commands, but it must NOT edit or create any files.\n\n```\nYou 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.\n\nRULES -- these are hard constraints, not suggestions:\n- You may search the codebase and read any file\n- You may RUN these specific test/build commands: [TEST_COMMANDS]\n- You may NOT edit, create, or delete any files\n- You may NOT run commands that modify state (no git commit, no npm install, no file writes)\n- You may NOT install packages or access the network\n- Report what you OBSERVE, not what you expect or hope\n\nSPEC NAME: [SPEC_NAME]\n\nACCEPTANCE CRITERIA:\n[ACCEPTANCE_CRITERIA]\n\nTEST PLAN:\n[TEST_PLAN]\n\nCONSTRAINTS:\n[CONSTRAINTS_OR_NONE]\n\nYOUR TASK:\nFor each acceptance criterion, determine if it PASSES or FAILS based on evidence:\n\n1. Run the test commands listed above. Record the output.\n2. For each acceptance criterion:\n   a. Check if there is a corresponding test and whether it passes\n   b. If no test exists, read the relevant source files to verify the criterion is met\n   c. If the criterion cannot be verified by reading code or running tests, mark it MANUAL CHECK NEEDED\n3. For criteria about build/test passing, actually run the commands and report results.\n\nOUTPUT FORMAT -- you MUST use this exact format:\n\nVERIFICATION REPORT\n\n| # | Criterion | Verdict | Evidence |\n|---|-----------|---------|----------|\n| 1 | [criterion text] | PASS/FAIL/MANUAL CHECK NEEDED | [what you observed] |\n| 2 | [criterion text] | PASS/FAIL/MANUAL CHECK NEEDED | [what you observed] |\n[continue for all criteria]\n\nSUMMARY: X/Y criteria passed. [Z failures need attention. / All criteria verified.]\n\nIf any test commands fail to run (missing dependencies, wrong command, etc.), report the error as evidence for a FAIL verdict on the relevant criterion.\n```\n\n## Step 5: Format and Present the Verdict\n\nTake the subagent\'s response and present it to the user in this format:\n\n```\n## Verification Report -- [Spec Name]\n\n| # | Criterion | Verdict | Evidence |\n|---|-----------|---------|----------|\n| 1 | ... | PASS | ... |\n| 2 | ... | FAIL | ... |\n\n**Overall: X/Y criteria passed.**\n\n[If all passed:]\nAll criteria verified. Ready to commit and open a PR.\n\n[If any failed:]\nN failures need attention. Review the evidence above and fix before proceeding.\n\n[If any MANUAL CHECK NEEDED:]\nN criteria need manual verification -- they can\'t be checked by reading code or running tests alone.\n```\n\n## Step 6: Suggest Next Steps\n\nBased on the verdict:\n\n- **All PASS:** Suggest committing and opening a PR, or running `$joycraft-session-end` to capture discoveries.\n- **Some FAIL:** List the failed criteria and suggest the user fix them, then run `$joycraft-verify` again.\n- **MANUAL CHECK NEEDED items:** Explain what needs human eyes and why automation couldn\'t verify it.\n\n**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.\n\n## Edge Cases\n\n| Scenario | Behavior |\n|----------|----------|\n| 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 |\n| All tests pass but a criterion is not testable | Mark as MANUAL CHECK NEEDED with explanation |\n| Subagent can\'t run tests (missing deps) | Report the error as FAIL evidence |\n| No specs found and no path given | Tell user to provide a spec path or create a spec first |\n| Spec status is "Complete" | Still run verification -- "Complete" means the implementer thinks it\'s done, verification confirms |\n'
 };
 var PI_SKILLS = {
@@ -300,7 +300,7 @@ var PI_SKILLS = {
   "joycraft-session-end.md": "---\nname: joycraft-session-end\ndescription: Wrap up a session \u2014 capture discoveries, verify, prepare for PR or next session\n---\n\n# Session Wrap-Up \u2014 Feature Finisher\n\nThis is the **once-per-feature finisher** \u2014 the heavy bookend that runs **once**, when the feature's specs are done, not after every spec. It is the **only validation gate** in the loop and the single place that pushes and opens the PR.\n\n> **Two-tier wrap-up.** The light per-spec step is `joycraft-spec-done` (status bump `todo \u2192 in-review` + commit, no validation/push/PR \u2014 it runs after each spec). This skill is the heavy counterpart: full validation, consolidate the discovery stubs spec-done left behind, graduate every `in-review` spec to `done`, push, and open the PR. See `docs/reference/spec-status-lifecycle.md` for the `todo \u2192 in-review \u2192 done` lifecycle.\n\nComplete these steps in order.\n\n## 1. Consolidate Discoveries\n\n**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.\n\nThis is the **consolidation** pass: `joycraft-spec-done` may have left terse 2-line discovery **stubs** during the feature (one per surprising spec). Curate and expand those stubs into proper discovery docs now, and capture anything else surprising from the feature as a whole. If any stubs exist at `docs/discoveries/`, consolidate them (merge related ones, expand each into the full format below); then create or update a discovery file at `docs/discoveries/YYYY-MM-DD-topic.md`. Lazy-create the `docs/discoveries/` directory if it doesn't exist.\n\n(Discoveries stay flat at `docs/discoveries/` rather than per-feature, since they often span features and are read serendipitously rather than via a known path.)\n\nThe discovery file MUST start with YAML frontmatter \u2014 the 4-field personal schema:\n\n```yaml\n---\nstatus: todo\nowner: <resolved name>\ncreated: YYYY-MM-DD\nfeature: <slug-of-related-feature>   # omit if not feature-tied\n---\n```\n\n**Owner resolution:** look up the owner name in this order \u2014 (1) `git config user.name`, (2) value in your auto-memory `joycraft-owner.txt` if present, (3) ask the user once and persist.\n\nOnly capture what's NOT obvious from the code or git diff:\n- \"We thought X but found Y\" \u2014 assumptions that were wrong\n- \"This API/library behaves differently than documented\" \u2014 external gotchas\n- \"This edge case needs handling in a future spec\" \u2014 deferred work with context\n- \"The approach in the spec didn't work because...\" \u2014 spec-vs-reality gaps\n- Key decisions made during implementation that aren't in the spec\n\n**Do NOT capture:**\n- Files changed (that's the diff)\n- What you set out to do (that's the spec)\n- Step-by-step narrative of the session (nobody re-reads these)\n\nUse this format:\n\n```markdown\n# Discoveries \u2014 [topic]\n\n**Date:** YYYY-MM-DD\n**Spec:** [link to spec if applicable]\n\n## [Discovery title]\n**Expected:** [what we thought would happen]\n**Actual:** [what actually happened]\n**Impact:** [what this means for future work]\n```\n\nIf nothing surprising happened, skip the discovery file entirely. No discovery is a good sign \u2014 the spec was accurate.\n\n## 1b. Update Context Documents\n\nIf `docs/context/` exists, quickly check whether this session revealed anything about:\n\n- **Production risks** \u2014 did you interact with or learn about production vs staging systems? \u2192 Update `docs/context/production-map.md`\n- **Wrong assumptions** \u2014 did the agent (or you) assume something that turned out to be false? \u2192 Update `docs/context/dangerous-assumptions.md`\n- **Key decisions** \u2014 did you make an architectural or tooling choice? \u2192 Add a row to `docs/context/decision-log.md`\n- **Unwritten rules** \u2014 did you discover a convention or constraint not documented anywhere? \u2192 Update `docs/context/institutional-knowledge.md`\n\nWhen you UPDATE a context doc, also bump (or add) its YAML frontmatter \u2014 the 2-field shared schema:\n\n```yaml\n---\nlast_updated: YYYY-MM-DD\nlast_updated_by: <resolved name>\n---\n```\n\nIf the file already has the frontmatter, update the `last_updated` and `last_updated_by` fields in place. If it doesn't, prepend a fresh block. Context docs are *shared* artifacts (no single owner) \u2014 the shared schema reflects that.\n\nSkip this if nothing applies. Don't force it \u2014 only update when there's genuine new context.\n\n## 2. Run Validation \u2014 the ONLY validation gate\n\nThis is **mandatory** and it is the **only** validation gate in the loop: `joycraft-spec-done` deliberately skips validation (it trusts implement's per-spec TDD), so this feature-level run is the single cross-spec safety net. Never skip it.\n\nRun the project's validation commands. Check AGENTS.md for project-specific commands. Common checks:\n\n- Type-check (e.g., `tsc --noEmit`, `mypy`, `cargo check`)\n- Tests (e.g., `npm test`, `pytest`, `cargo test`)\n- Lint (e.g., `eslint`, `ruff`, `clippy`)\n\nFix any failures before proceeding. **If validation fails, stop \u2014 do NOT graduate specs to `done` and do NOT push.**\n\n## 3. Graduate Specs `in-review \u2192 done`\n\nThis step graduates the feature's finished specs to their terminal state. Because session-end runs once at the end, **multiple specs may be waiting** in `in-review` (one per spec the loop completed via `joycraft-spec-done`). Graduate **all** of them, in **both** systems (the queue JSON and the frontmatter must never disagree):\n\nFor each spec in `docs/features/<slug>/specs/` (or `docs/bugfixes/<area>/` for bugfixes \u2014 scan recursively) whose status is `in-review`:\n\n1. **Queue JSON** \u2014 `joycraft-mark-done <spec-id> --to done <specs-dir>` (the `--to done` graduation; find `<spec-id>` by matching the entry's `file`).\n2. **Frontmatter** \u2014 edit the spec file's YAML `status:` to `done`.\n\nRules:\n- Only graduate specs that are `in-review`. A spec still at `todo` was never started \u2014 **leave it `todo` and report it as remaining** (the feature isn't fully done; see the PR gate in step 5).\n- Never write `done` for work nothing has validated \u2014 this validation run (step 2) is what licenses the graduation. (Once `verify-in-loop` ships, an independent verify performs the `in-review \u2192 done` transition; until then, this step does.)\n- `done` means **verified**, not **merged**. A merged PR is a git fact, never a spec status \u2014 do not invent a `merged` status or any fourth state beyond `todo`/`in-review`/`done`.\n\nIf working from a Feature Brief at `docs/features/<slug>/brief.md`, also check off completed specs in the decomposition table.\n\n## 4. Commit\n\nCommit all changes including the discovery file (if created) and spec status updates. The commit message should reference the spec if applicable.\n\n## 5. Push and PR (if autonomous git is enabled)\n\n**Check AGENTS.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\":\n\n1. **Push immediately.** Run `git push origin <branch>` \u2014 do not ask, do not hesitate.\n2. **Open a PR if the feature is complete.** The feature is complete when every spec is `done` (none left at `todo`/`in-review`). Check the queue JSON / decomposition table \u2014 if all specs are `done`, run `gh pr create` with a summary of all completed specs. Do not ask first.\n3. **If specs remain (`todo`),** still push. The PR comes when the feature's last spec is graduated.\n\nIf AGENTS.md does NOT have autonomous git rules (or has \"ASK FIRST\" for pushing), ask the user before pushing.\n\n## 6. Report and Hand Off\n\n```\nFeature complete.\n- Feature: [slug]\n- Specs graduated to done: [N] (remaining at todo: [N])\n- Build: [passing / failing]\n- Discoveries: [N consolidated / none]\n- Pushed: [yes / no \u2014 and why not]\n- PR: [opened #N / not yet \u2014 N specs remaining]\n- Next: [what comes after this feature]\n```\n\nEnd with the canonical Handoff block. Include any discovery and updated-context paths produced.\n\n## Recommended Next Steps\n\nNext:\n```bash\n/skill:joycraft-implement docs/features/<slug>/specs/<next-spec>.md\n```\nRun /new first.\n\nIf all specs in the feature are complete, hand off to a feature-level wrap-up instead (PR review, etc.) \u2014 the Handoff block is just the slash command for whatever the next move is.\n",
   "joycraft-setup.md": '---\nname: joycraft-setup\ndescription: Set up Joycraft and get started on this project -- the first-time entry point. Run this when you\'re configuring your project, onboarding, or asking "where do I begin?" / "how do I set this up?"\n---\n\n# Setup \u2014 The First-Run Door\n\nThis is the obvious starting point for setting up Joycraft on this project. It does no work of its own \u2014 it routes you to the skill that does the real assessment and onboarding.\n\n**Run `/skill:joycraft-tune`.**\n\n`/skill:joycraft-tune` detects your project\'s current harness state, scores it, applies the upgrades it can, and on a first run kicks off the context-onboarding pass for you. That\'s the whole setup flow \u2014 this alias just exists so "set up", "get started", and "first time" lead you there.\n\nDo not re-implement assessment or scoring here; hand off to `/skill:joycraft-tune`.\n',
   "joycraft-spec-done.md": "---\nname: joycraft-spec-done\ndescription: Lightweight per-spec wrap-up \u2014 bump status to in-review, terse discovery if surprised, commit. Run after each spec in checkpoint/isolated mode; no validation, no push, no PR.\n---\n\n# Spec Done (Lightweight Per-Spec Wrap-Up)\n\nYou just finished implementing **one** atomic spec. This is the fast handshake that runs **once per spec**, before context clears \u2014 the `todo \u2192 in-review` transition in the lifecycle (`docs/reference/spec-status-lifecycle.md`). It is deliberately tiny: it does exactly four things and nothing more.\n\n> **This is NOT session-end.** It does **not** run validation, push, or open a PR. It trusts the TDD you just did in `joycraft-implement`. The heavy once-per-feature wrap-up (full validation + consolidate discoveries + push + PR) is `joycraft-session-end`, which runs once at the end of the feature.\n>\n> **On the Pi isolated-mode loop** (`joycraft-implement-loop`), this same four-step logic runs as a fresh-process step after each implement \u2014 the loop calls spec-done between specs and session-end once at the end.\n>\n> **Usually you don't run this by hand:** `joycraft-implement` performs these four steps itself at the end of every checkpoint/isolated spec (and `joycraft-implement-feature` drives whole queues). This skill remains the canonical definition of the wrap-up \u2014 run it manually after ad-hoc work done outside the implement skill, or when an implement run was interrupted before wrapping up.\n\n## Step 1: Bump status to `in-review` \u2014 in BOTH systems\n\nA spec's status lives in two places that must never disagree (the desync this feature exists to kill): the **queue JSON** and the spec's **frontmatter**. Update both to `in-review`.\n\n1. **Queue JSON** \u2014 use the script, not a bespoke `sed`:\n   ```bash\n   joycraft-mark-done <spec-id> --to in-review <specs-dir>\n   ```\n   Find `<spec-id>` by reading `<specs-dir>/.joycraft-spec-queue.json` and matching the entry whose `file` is the spec you just implemented. `<specs-dir>` is the folder containing the spec (e.g. `docs/features/<slug>/specs`). If the spec isn't in the manifest, `joycraft-mark-done` exits non-zero with a clear error \u2014 **surface that error, don't silently skip the bump**.\n2. **Frontmatter** \u2014 edit the spec file's YAML `status:` field to `in-review`.\n\nDo **not** graduate to `done`. The agent never self-certifies \u2014 `done` is reached only by `joycraft-session-end` (or, later, an independent verify). `spec-done` only ever reaches `in-review`.\n\n## Step 2: Terse discovery stub \u2014 ONLY if something surprised you\n\nDid anything during implementation **contradict the spec** or surprise you (an assumption that was wrong, an external API that behaved differently, an edge case the spec missed)?\n\n- **No** \u2192 skip this step entirely. A spec that went as written needs no discovery. This is the common case.\n- **Yes** \u2192 write a **2-line stub** (not a full discovery doc) at `docs/discoveries/YYYY-MM-DD-topic.md`: one line on what contradicted the spec, one line pointing at the spec/file. `joycraft-session-end`'s consolidation pass later expands these stubs into proper discovery docs \u2014 keep it terse here.\n\n## Step 3: Commit\n\nCommit the spec's implementation changes plus the status edits (and the stub, if any) with the convention:\n\n```\nspec: <spec-name>\n```\n\nKeep scope disciplined \u2014 commit the spec's changes and its status edits, not unrelated working-tree noise.\n\n## Step 4: Stop\n\nThat's it. **No** validation re-run, **no** push, **no** PR \u2014 those belong to `joycraft-session-end` at feature end. Hand off and keep the loop moving.\n\n## Recommended Next Steps\n\nIf more specs remain in this feature (checkpoint/isolated mode), continue to the next one:\n\n```bash\n/skill:joycraft-implement docs/features/<slug>/specs/<next-spec>.md\n```\n\nWhen the feature's last spec is done, run the feature finisher once:\n\n```bash\n/skill:joycraft-session-end\n```\n\nRun /new before your next step \u2014 your artifacts are saved to files.\n",
-  "joycraft-tune.md": "---\nname: joycraft-tune\ndescription: Assess and upgrade your project's AI development harness \u2014 score 7 dimensions, apply fixes, show path to Level 5\n---\n\n# Tune \u2014 Project Harness Assessment & Upgrade\n\nYou are evaluating and upgrading this project's AI development harness.\n\n## Step 1: Detect Harness State\n\nCheck for: AGENTS.md (with meaningful content), `docs/features/<slug>/` (briefs + specs), `docs/bugfixes/<area>/`, `docs/discoveries/`, `docs/context/*.md` fact-docs, `docs/context/reference/` long-form docs, `.pi/skills/`, and test configuration.\n\n## Step 2: Route\n\n- **No harness** (no AGENTS.md or just a README): Recommend `npx joycraft init` and stop.\n- **Harness exists**: Continue to assessment.\n\n## Step 3: Assess \u2014 Score 7 Dimensions (1-5 scale)\n\nRead AGENTS.md and explore the project. Score each with specific evidence:\n\n| Dimension | What to Check |\n|-----------|--------------|\n| Spec Quality | `docs/features/<slug>/specs/` (scan recursively; also `docs/bugfixes/<area>/`) \u2014 structured? acceptance criteria? self-contained? |\n| Spec Granularity | Can each spec be done in one session? |\n| Behavioral Boundaries | ALWAYS/ASK FIRST/NEVER sections (or equivalent rules under any heading) |\n| Skills & Hooks | `.pi/skills/` files, hooks config |\n| Documentation | `docs/` structure, templates, referenced from AGENTS.md. Reward a lean + pointered AGENTS.md. **Flag a AGENTS.md exceeding ~200 lines** \u2014 recommend extracting long sections into `docs/context/reference/` and replacing them with a `## Context Map` pointer table. This is advisory only; tune never auto-edits AGENTS.md. |\n| Knowledge Capture | `docs/discoveries/`, `docs/context/*.md` fact-docs, `docs/context/reference/` long-form docs \u2014 existence AND real content |\n| Testing & Validation | Test framework, CI pipeline, validation commands in AGENTS.md |\n\nScore 1 = absent, 3 = partially there, 5 = comprehensive. Give credit for substance over format.\n\n## Step 4: Write Assessment\n\nWrite to `docs/skill: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).\n\n## Step 5: Apply Upgrades\n\nApply using three tiers \u2014 do NOT ask per-item permission:\n\n**Tier 1 (silent):** Create missing dirs, install missing skills, copy missing templates, create AGENTS.md.\n\n**Private-profile note:** If `.gitignore` ignores the harness dirs (`.claude/`, `.agents/`, `.pi/` \u2014 the `private` profile), teammates who clone won't get the skill files. Ensure CLAUDE.md and AGENTS.md each carry a one-line note \u2014 append if absent, idempotent (match on the phrase \"After cloning, run\"): `> **Private setup:** The harness dirs (.claude/, .agents/, .pi/) are gitignored in this repo, so they aren't committed. After cloning, run \\`npx joycraft init\\` to regenerate the skill files locally.` Skip entirely under the `shared` profile.\n\n**Before Tier 2, ask about git autonomy:** Cautious (ask before push/PR) or Autonomous (push + PR without asking)?\n\n**First-run context onboarding:** On a first run (the context layer is empty or absent), invoke `/skill:joycraft-gather-context` for the read-then-offer onboarding pass \u2014 it owns reading existing docs, offering a gap-only interview, and populating `docs/context/` (fact-docs and `docs/context/reference/`). Do NOT run a separate risk interview here; gather is the onboarding path. On a recurring run of an already-populated project, skip this \u2014 gather is the first-run path, not forced every time.\n\nFrom git-autonomy and gather, generate: AGENTS.md boundary rules, `.claude/settings.json` deny patterns. Also recommend a permission mode (`auto` for most; `dontAsk` + allowlist for high-risk).\n\n**Tier 2 (show diff):** Add missing AGENTS.md sections (Boundaries, Workflow, Key Files). Draft from real codebase content. Append only \u2014 never reformat existing content.\n\n**Tier 3 (confirm first):** Rewriting existing sections, overwriting customized files, suggesting test framework installs.\n\nAfter applying, append to `docs/skill:joycraft-history.md` and show a consolidated upgrade results table.\n\n## Step 6: Show Path to Level 5\n\nShow 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).\n\n**Tip:** Run `/skill:joycraft-optimize` to audit your session's token overhead \u2014 plugins, MCP servers, and harness file sizes.\n\n## Edge Cases\n\n- **AGENTS.md is just a README:** Treat as no harness.\n- **Non-Joycraft skills:** Acknowledge, don't replace.\n- **Rules under non-standard headings:** Give credit for substance.\n- **Previous assessment exists:** Read it first. If nothing to upgrade, say so.\n- **Non-Joycraft content in AGENTS.md:** Preserve as-is. Only append.\n",
+  "joycraft-tune.md": "---\nname: joycraft-tune\ndescription: Assess and upgrade your project's AI development harness \u2014 score 7 dimensions, apply fixes, show path to Level 5\n---\n\n# Tune \u2014 Project Harness Assessment & Upgrade\n\nYou are evaluating and upgrading this project's AI development harness.\n\n## Step 1: Detect Harness State\n\nCheck for: AGENTS.md (with meaningful content), `docs/features/<slug>/` (briefs + specs), `docs/bugfixes/<area>/`, `docs/discoveries/`, `docs/context/*.md` fact-docs, `docs/context/reference/` long-form docs, `.pi/skills/`, and test configuration.\n\n## Step 2: Route\n\n- **No harness** (no AGENTS.md or just a README): Recommend `npx joycraft init` and stop.\n- **Harness exists**: Continue to assessment.\n\n## Step 3: Assess \u2014 Score 7 Dimensions (1-5 scale)\n\nRead AGENTS.md and explore the project. Score each with specific evidence:\n\n| Dimension | What to Check |\n|-----------|--------------|\n| Spec Quality | `docs/features/<slug>/specs/` (scan recursively; also `docs/bugfixes/<area>/`) \u2014 structured? acceptance criteria? self-contained? |\n| Spec Granularity | Can each spec be done in one session? |\n| Behavioral Boundaries | ALWAYS/ASK FIRST/NEVER sections (or equivalent rules under any heading) |\n| Skills & Hooks | `.pi/skills/` files, hooks config |\n| Documentation | `docs/` structure, templates, referenced from AGENTS.md. Reward a lean + pointered AGENTS.md. **Flag a AGENTS.md exceeding ~200 lines** \u2014 recommend extracting long sections into `docs/context/reference/` and replacing them with a `## Context Map` pointer table. This is advisory only; tune never auto-edits AGENTS.md. |\n| Knowledge Capture | `docs/discoveries/`, `docs/context/*.md` fact-docs, `docs/context/reference/` long-form docs \u2014 existence AND real content |\n| Testing & Validation | Test framework, CI pipeline, validation commands in AGENTS.md |\n\nScore 1 = absent, 3 = partially there, 5 = comprehensive. Give credit for substance over format.\n\n## Step 4: Write Assessment\n\nWrite to `docs/skill: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).\n\n## Step 5: Apply Upgrades\n\nApply using three tiers \u2014 do NOT ask per-item permission:\n\n**Tier 1 (silent):** Create missing dirs, install missing skills, copy missing templates, create AGENTS.md.\n\n**Private-profile note:** If `.gitignore` ignores the harness dirs (`.claude/`, `.agents/`, `.pi/` \u2014 the `private` profile), teammates who clone won't get the skill files. Ensure CLAUDE.md and AGENTS.md each carry a one-line note \u2014 append if absent, idempotent (match on the phrase \"After cloning, run\"): `> **Private setup:** The harness dirs (.claude/, .agents/, .pi/) are gitignored in this repo, so they aren't committed. After cloning, run \\`npx joycraft init\\` to regenerate the skill files locally \u2014 it only creates missing files and leaves your committed \\`CLAUDE.md\\`, \\`AGENTS.md\\`, and \\`docs/\\` untouched (use \\`--force\\` only if you deliberately want to regenerate them).` Skip entirely under the `shared` profile.\n\n**Already-tracked harness files (private profile):** If the project is on the `private` profile but `git ls-files` shows tracked files under `.claude/`, `.agents/`, or `.pi/`, those files were committed before the switch and the gitignore won't untrack them. Surface the copy-pasteable fix once, prominently, in your upgrade results \u2014 `git rm -r --cached .claude .agents .pi` \u2014 and note it's advisory (never run git yourself). Skip when no harness files are tracked, and skip entirely under `shared`.\n\n**Before Tier 2, ask about git autonomy:** Cautious (ask before push/PR) or Autonomous (push + PR without asking)?\n\n**First-run context onboarding:** On a first run (the context layer is empty or absent), invoke `/skill:joycraft-gather-context` for the read-then-offer onboarding pass \u2014 it owns reading existing docs, offering a gap-only interview, and populating `docs/context/` (fact-docs and `docs/context/reference/`). Do NOT run a separate risk interview here; gather is the onboarding path. On a recurring run of an already-populated project, skip this \u2014 gather is the first-run path, not forced every time.\n\nFrom git-autonomy and gather, generate: AGENTS.md boundary rules, `.claude/settings.json` deny patterns. Also recommend a permission mode (`auto` for most; `dontAsk` + allowlist for high-risk).\n\n**Tier 2 (show diff):** Add missing AGENTS.md sections (Boundaries, Workflow, Key Files). Draft from real codebase content. Append only \u2014 never reformat existing content.\n\n**Tier 3 (confirm first):** Rewriting existing sections, overwriting customized files, suggesting test framework installs.\n\nAfter applying, append to `docs/skill:joycraft-history.md` and show a consolidated upgrade results table.\n\n## Step 6: Show Path to Level 5\n\nShow 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).\n\n**Tip:** Run `/skill:joycraft-optimize` to audit your session's token overhead \u2014 plugins, MCP servers, and harness file sizes.\n\n## Edge Cases\n\n- **AGENTS.md is just a README:** Treat as no harness.\n- **Non-Joycraft skills:** Acknowledge, don't replace.\n- **Rules under non-standard headings:** Give credit for substance.\n- **Previous assessment exists:** Read it first. If nothing to upgrade, say so.\n- **Non-Joycraft content in AGENTS.md:** Preserve as-is. Only append.\n",
   "joycraft-verify.md": '---\nname: joycraft-verify\ndescription: Spawn an independent verifier subagent to check an implementation against its spec -- read-only, no code edits, structured pass/fail verdict\n---\n\n# Verify Implementation Against Spec\n\nThe user wants independent verification of an implementation. Your job is to find the relevant spec, extract its acceptance criteria and test plan, then use the `subagent` tool with agent `joycraft-verifier` to check each criterion and produce a structured verdict.\n\n**Why a separate subagent?** 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.\n\n## Step 1: Find the Spec\n\nIf the user provided a spec path (e.g., `/skill:joycraft-verify docs/features/<slug>/specs/add-widget.md`), use that path directly.\n\nIf no path was provided, scan `docs/features/*/specs/` recursively for spec files (and `docs/bugfixes/<area>/` for bugfixes). Pick the most recently modified `.md` file. If no specs exist, tell the user:\n\n> No specs found under `docs/features/*/specs/` or `docs/bugfixes/`. Please provide a spec path: `/skill:joycraft-verify path/to/spec.md`\n\n## Step 2: Read and Parse the Spec\n\nRead the spec file and extract:\n\n1. **Spec name** -- from the H1 title\n2. **Acceptance Criteria** -- the checklist under the `## Acceptance Criteria` section\n3. **Test Plan** -- the table under the `## Test Plan` section, including any test commands\n4. **Constraints** -- the `## Constraints` section if present\n\nIf the spec has no Acceptance Criteria section, tell the user:\n\n> This spec doesn\'t have an Acceptance Criteria section. Verification needs criteria to check against. Add acceptance criteria to the spec and try again.\n\nIf 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.\n\n## Step 3: Identify Test Commands\n\nLook for test commands in these locations (in priority order):\n\n1. The spec\'s Test Plan section (look for commands in backticks or "Type" column entries like "unit", "integration", "e2e", "build")\n2. The project\'s AGENTS.md (look for test/build commands in the Development Workflow section)\n3. Common defaults based on the project type:\n   - Node.js: `npm test` or `pnpm test --run`\n   - Python: `pytest`\n   - Rust: `cargo test`\n   - Go: `go test ./...`\n\nBuild a list of specific commands the verifier should run.\n\n## Step 4: Deploy the Verifier Subagent\n\nUse the `subagent` tool with agent `joycraft-verifier`. Pass the prompt below, replacing placeholders with the actual content extracted in Steps 2-3.\n\n```\nYou 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.\n\nRULES -- these are hard constraints, not suggestions:\n- You may search the codebase and read any file\n- You may RUN these specific test/build commands: [TEST_COMMANDS]\n- You may NOT edit, create, or delete any files\n- You may NOT run commands that modify state (no git commit, no npm install, no file writes)\n- You may NOT install packages or access the network\n- Report what you OBSERVE, not what you expect or hope\n\nSPEC NAME: [SPEC_NAME]\n\nACCEPTANCE CRITERIA:\n[ACCEPTANCE_CRITERIA]\n\nTEST PLAN:\n[TEST_PLAN]\n\nCONSTRAINTS:\n[CONSTRAINTS_OR_NONE]\n\nYOUR TASK:\nFor each acceptance criterion, determine if it PASSES or FAILS based on evidence:\n\n1. Run the test commands listed above. Record the output.\n2. For each acceptance criterion:\n   a. Check if there is a corresponding test and whether it passes\n   b. If no test exists, read the relevant source files to verify the criterion is met\n   c. If the criterion cannot be verified by reading code or running tests, mark it MANUAL CHECK NEEDED\n3. For criteria about build/test passing, actually run the commands and report results.\n\nOUTPUT FORMAT -- you MUST use this exact format:\n\nVERIFICATION REPORT\n\n| # | Criterion | Verdict | Evidence |\n|---|-----------|---------|----------|\n| 1 | [criterion text] | PASS/FAIL/MANUAL CHECK NEEDED | [what you observed] |\n| 2 | [criterion text] | PASS/FAIL/MANUAL CHECK NEEDED | [what you observed] |\n[continue for all criteria]\n\nSUMMARY: X/Y criteria passed. [Z failures need attention. / All criteria verified.]\n\nIf any test commands fail to run (missing dependencies, wrong command, etc.), report the error as evidence for a FAIL verdict on the relevant criterion.\n```\n\n## Step 5: Format and Present the Verdict\n\nTake the subagent\'s response and present it to the user in this format:\n\n```\n## Verification Report -- [Spec Name]\n\n| # | Criterion | Verdict | Evidence |\n|---|-----------|---------|----------|\n| 1 | ... | PASS | ... |\n| 2 | ... | FAIL | ... |\n\n**Overall: X/Y criteria passed.**\n\n[If all passed:]\nAll criteria verified. Ready to commit and open a PR.\n\n[If any failed:]\nN failures need attention. Review the evidence above and fix before proceeding.\n\n[If any MANUAL CHECK NEEDED:]\nN criteria need manual verification -- they can\'t be checked by reading code or running tests alone.\n```\n\n## Step 6: Suggest Next Steps\n\nBased on the verdict:\n\n- **All PASS:** Suggest committing and opening a PR, or running `/skill:joycraft-session-end` to capture discoveries.\n- **Some FAIL:** List the failed criteria and suggest the user fix them, then run `/skill:joycraft-verify` again.\n- **MANUAL CHECK NEEDED items:** Explain what needs human eyes and why automation couldn\'t verify it.\n\n**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.\n\n## Edge Cases\n\n| Scenario | Behavior |\n|----------|----------|\n| 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 |\n| All tests pass but a criterion is not testable | Mark as MANUAL CHECK NEEDED with explanation |\n| Subagent can\'t run tests (missing deps) | Report the error as FAIL evidence |\n| No specs found and no path given | Tell user to provide a spec path or create a spec first |\n| Spec status is "Complete" | Still run verification -- "Complete" means the implementer thinks it\'s done, verification confirms |\n'
 };
 var PI_SCRIPTS = {
@@ -497,4 +497,4 @@ export {
   PI_EXTENSIONS,
   PI_AGENTS
 };
-//# sourceMappingURL=chunk-UEG5IO6Q.js.map
+//# sourceMappingURL=chunk-3JVMOJTA.js.map