rk-skills 1.0.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,14 @@
+{
+  "name": "rk-skills",
+  "description": "Marketplace for rk-skills: Richard Kuo's personal Claude Code skill collection.",
+  "owner": {
+    "name": "Richard Kuo"
+  },
+  "plugins": [
+    {
+      "name": "rk-skills",
+      "source": "./",
+      "description": "Richard Kuo's personal Claude Code skills: GitHub issue/PR/release workflow automation and Fable-driven planning."
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,12 @@
+{
+  "name": "rk-skills",
+  "displayName": "rk-skills",
+  "version": "1.0.0",
+  "description": "Richard Kuo's personal Claude Code skills: GitHub issue/PR/release workflow automation and Fable-driven planning.",
+  "author": {
+    "name": "Richard Kuo"
+  },
+  "repository": "https://github.com/richkuo/rk-skills",
+  "license": "MIT",
+  "keywords": ["skills", "workflow", "github-issues", "pull-requests", "release", "fable", "planning"]
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Richard Kuo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,61 @@
+# rk-skills
+
+Richard Kuo's personal [Claude Code](https://claude.com/claude-code) skills — the custom skills, global instructions, and slash command I use across every session.
+
+The real files live in this repo. On my machine they're symlinked into `~/.claude`, so editing in either place is the same file and a `git commit` here captures the change. Third-party / marketplace-installed skills are deliberately excluded — they're reinstallable and not authored by me.
+
+## Skills
+
+Most workflow skills come in two forms: a **base** skill that does one step, and a **`-loop`** variant that drives the whole thing autonomously through review to a merged PR.
+
+- **Issues** — `new-issue`, `validate-issue`, `work-on-issue` (+ `-loop` variants): file a fully-specified, complexity-scored issue; verify its claims against the actual code; implement it end-to-end in an isolated worktree and open a PR.
+- **PR review** — `fix-pr-review` (+ `-loop`): re-validate every review finding against the code, fix the ones that hold, push, and re-trigger review until approved.
+- **Docs & release** — `sync-docs`, `sync-docs-release`, `create-release`: refresh `CLAUDE.md`/`README`/`SKILL.md` from recent commits, and cut versioned GitHub releases.
+- **Fable-driven** — `fableplan`, `fable-validate`, `fable-new-issue` (+ `-loop` variants): delegate planning / validation / issue-drafting to a Fable 5 subagent, then build with your main-session model.
+
+Also included:
+
+- `CLAUDE.md` — my global instructions for all Claude Code sessions (linked to `~/.claude/CLAUDE.md`). Many skills above are tuned to the conventions defined here (attribution footers, complexity scores, the branch+PR workflow).
+- `commands/commit.md` — the `/commit` slash command (linked to `~/.claude/commands/commit.md`).
+
+## Install (as a plugin)
+
+This repo is a Claude Code plugin marketplace. In any Claude Code session:
+
+```
+/plugin marketplace add richkuo/rk-skills
+/plugin install rk-skills@rk-skills
+```
+
+Claude Code auto-discovers everything under `skills/` (and the `/commit` command). `CLAUDE.md` is my personal global config and is **not** installed by the plugin — treat it as a reference. Restart Claude Code (or start a new session), then trigger any skill by name, e.g. `/fableplan <task>`.
+
+Prefer to install a single skill? Each is just a directory with a `SKILL.md`, so you can copy one in directly:
+
+```sh
+mkdir -p ~/.claude/skills/work-on-issue && \
+  curl -fsSL https://raw.githubusercontent.com/richkuo/rk-skills/main/skills/work-on-issue/SKILL.md \
+  -o ~/.claude/skills/work-on-issue/SKILL.md
+```
+
+## Install (with npx)
+
+Copy every skill into your personal `~/.claude/skills/` with one command — no marketplace, no clone:
+
+```sh
+npx rk-skills
+```
+
+Add `--project` to install into the current repo's `.claude/skills/` instead. This path is copy-based — re-run it to update — whereas the plugin above auto-updates. It installs the **skills only**; not `CLAUDE.md` (my personal global config) or the `/commit` command.
+
+## Restore on a new machine (my setup)
+
+Clone this repo, then run `./install.sh`. It symlinks every tracked item into `~/.claude`, backing up any existing real file to `<name>.bak` first. It only ever replaces symlinks — it never deletes your data.
+
+```bash
+git clone git@github.com:richkuo/rk-skills.git ~/Work/rk-skills
+cd ~/Work/rk-skills && ./install.sh
+```
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/bin/install.mjs

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+import { cpSync, existsSync, mkdirSync, readdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const pkgRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const skillsSrc = join(pkgRoot, 'skills');
+
+if (!existsSync(skillsSrc)) {
+	console.error('rk-skills: could not find the skills/ directory in the package.');
+	process.exit(1);
+}
+
+// Each skill is a directory under skills/ that contains a SKILL.md.
+const skills = readdirSync(skillsSrc, { withFileTypes: true })
+	.filter((entry) => entry.isDirectory())
+	.map((entry) => entry.name)
+	.filter((name) => existsSync(join(skillsSrc, name, 'SKILL.md')))
+	.sort();
+
+if (skills.length === 0) {
+	console.error('rk-skills: no skills found to install.');
+	process.exit(1);
+}
+
+const project = process.argv.includes('--project');
+const skillsDir = project
+	? join(process.cwd(), '.claude', 'skills')
+	: join(homedir(), '.claude', 'skills');
+
+mkdirSync(skillsDir, { recursive: true });
+for (const name of skills) {
+	cpSync(join(skillsSrc, name), join(skillsDir, name), { recursive: true });
+}
+
+const scope = project ? 'this project' : 'your personal skills';
+console.log(`rk-skills installed ${skills.length} skills into ${scope}:`);
+console.log(`  ${skillsDir}`);
+console.log(`  ${skills.join(', ')}`);
+console.log('\nRestart Claude Code (or start a new session), then invoke any skill by name, e.g.\n  /fableplan <task to plan>');

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "rk-skills",
+  "version": "1.0.0",
+  "description": "Installer for Richard Kuo's personal Claude Code skills — GitHub issue/PR/release workflow automation and Fable-driven planning.",
+  "type": "module",
+  "bin": {
+    "rk-skills": "bin/install.mjs"
+  },
+  "files": [
+    "bin",
+    "skills",
+    ".claude-plugin",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "claude-code",
+    "claude",
+    "skills",
+    "plugin",
+    "workflow",
+    "github-issues",
+    "pull-requests",
+    "fable"
+  ],
+  "homepage": "https://github.com/richkuo/rk-skills#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/richkuo/rk-skills.git"
+  },
+  "author": "Richard Kuo",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/create-release/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: create-release
+description: Use when the user asks to "create a release", "cut a release", "tag a version", "publish release notes", or ship a new versioned GitHub release for the current repo.
+---
+
+# create-release
+
+**This skill is a dispatch shim. Do not perform the work yourself.**
+
+Immediately invoke the `create-release-runner` subagent via the Agent tool, which runs on Sonnet and contains the full create-release workflow.
+
+## Required invocation
+
+Call the Agent tool with:
+
+- `subagent_type`: `create-release-runner`
+- `description`: `Cut and publish a release`
+- `prompt`: Pass through the user's request verbatim, plus any context the user already provided in this session (target version or bump type, whether to bump an in-app version, release-notes specifics, etc.). The agent has its own copy of the workflow — do not paste workflow steps into the prompt. Include only the inputs it needs.
+- `model`: Omit by default — the agent runs on Sonnet via its pinned frontmatter. **Override only if the user explicitly names a different LLM** when invoking the skill (e.g. "create a release with opus", "/create-release use haiku"). Map the request to the matching `model` value (`opus`, `sonnet`, or `haiku`) and pass it; the Agent tool's `model` parameter takes precedence over the agent's frontmatter. Do not infer an override from anything other than an explicit model name.
+
+After the agent returns, relay its summary (and the release URL) to the user. Do not re-execute its work.
+
+## Why this exists
+
+The full create-release workflow lives in `~/.claude/agents/create-release-runner.md` with `model: sonnet` pinned in frontmatter. Routing through the agent keeps release runs on Sonnet by default — but an explicit user LLM choice overrides it via the Agent tool's `model` parameter.

package/skills/fable-new-issue/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: fable-new-issue
+description: Use when the user wants a GitHub issue created by a Fable 5 subagent. Spins up a read-only subagent running on Fable 5 that executes the new-issue procedure (duplicate check, code grounding, approach design, complexity score) and returns a fully-composed issue draft, which the main agent spot-checks and files. Trigger on "/fable-new-issue", "fable new issue <description>", or "create this issue with fable".
+---
+
+# fable-new-issue
+
+Delegate issue drafting to a **Fable 5** subagent, then file it from the main agent. The subagent only researches and composes — it never files, edits files, or posts to GitHub; the main agent handles filing and all follow-on actions.
+
+## Input
+
+Same as `new-issue`:
+- A description of the bug/feature/task to file.
+- **Nothing** — derive from the current conversation. Since the subagent can't see this conversation, the main agent first writes a faithful summary of the discussed bug/design/follow-up (with any file paths or symbols already named) to a scratchpad file and hands that path to the subagent as the source description.
+- Optionally `owner/repo` or a repo path when the issue belongs elsewhere.
+
+## Steps
+
+### 1. Resolve the drafting procedure
+
+Locate the `new-issue` SKILL.md the subagent must follow — prefer the project-local copy over the global one:
+
+1. `<repo>/.claude/skills/new-issue/SKILL.md` (if it exists)
+2. `~/.claude/skills/new-issue/SKILL.md`
+
+Record the absolute path. If neither exists, stop and tell the user.
+
+If the input is conversation-derived, write the scratchpad summary now (see Input). Do NOT pre-research or pre-draft the issue yourself — the subagent owns steps 1–6 of the procedure up to (but not including) the `gh issue create` call.
+
+### 2. Dispatch the Fable 5 drafting subagent
+
+Snapshot `git status --porcelain` before dispatching, then call the Agent tool with:
+
+- `subagent_type`: `Plan` (read-only: no Edit/Write, keeps drafting side-effect-free)
+- `model`: `fable` (the whole point — the draft must come from Fable 5)
+- `run_in_background`: `false` — filing depends on the draft
+- `description`: `Draft issue: <short topic>`
+- `prompt`: hand it everything needed to draft independently:
+  - The user's description verbatim (or the scratchpad summary path), the working directory, and the target repo if not the current checkout.
+  - Instruct it to **read the SKILL.md at the recorded path and execute its steps 1 through 6 exactly** — repo/duplicate check, claim grounding with `file:line` citations traced against the correct baseline, approach design, complexity score, scope check, and full body composition per the step-6 template.
+  - It must STOP before filing: no `gh issue create`, no `gh issue edit`, no comments posted, no file edits — including via Bash (it lacks Edit/Write but still has Bash, so state this explicitly). Read-only `gh` calls (`gh issue list`, `gh pr list`, `gh repo view`, `gh label list`) are expected and allowed.
+  - Return as its final message: (a) any duplicate found (URL + why it matches) — in which case no draft; (b) otherwise the complete issue draft — exact title with `[C<score>]` prefix and the full body per the template — plus one line stating which baseline claims were traced against, and any unfiled follow-up candidates from the scope check.
+
+If the call returns null or errors, retry once; if it fails again, report the failure to the user instead of drafting yourself.
+
+When the result arrives:
+- Diff `git status --porcelain` against the snapshot to confirm no file changes; if changed, tell the user and ask whether to revert before continuing.
+- Save the draft verbatim to a scratchpad file immediately, so it survives context summarization.
+
+### 3. Duplicate gate
+
+If the subagent reported a duplicate, stop and surface it — offer to update/comment on the existing issue instead. Nothing is filed.
+
+### 4. Spot-check the draft
+
+Before filing, spot-check the draft's load-bearing `file:line` citations against the code and confirm the body meets the new-issue bar: complexity rationale as first line matching the title prefix, Problem/Goal/Approach/Acceptance criteria all concrete, no time/effort estimates, ELI18 title. Fix small inaccuracies yourself and note them (update the scratchpad copy); if the draft is structurally wrong (untraceable central claim, stale baseline, stub-like body), do NOT silently re-dispatch — tell the user what's off and let them decide.
+
+### 5. File it (main agent)
+
+File per new-issue step 6: `gh issue create --title "[C<score>] <title>" --body-file <body-file>` (with `-R owner/repo` if cross-repo; labels only when the repo visibly uses them and the fit is unambiguous).
+
+Footer: since the draft came from the Fable 5 subagent, use `Created with LLM: Fable 5 | high | Harness: Claude Code | fable-new-issue`. A repo CLAUDE.md footer format overrides.
+
+### 6. Report
+
+Terse: issue URL, number, one-line summary, complexity score, any unfiled follow-ups from the subagent, and a note that small spot-check fixes were applied (if any). Offer "validate issue" / "work on issue" as next steps in one line.
+
+## Notes
+
+- The drafting subagent runs on Fable 5 regardless of the main agent's model — `model: fable` forces it.
+- One subagent, one draft: don't fan out or re-run for a second opinion unless the user asks.
+- Never file a placeholder or thin body — if the subagent's draft isn't complete, it doesn't get filed; that rule outranks finishing the run.

package/skills/fable-new-issue-loop/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: fable-new-issue-loop
+description: Use when the user asks to have a Fable 5 subagent draft and file a GitHub issue, then autonomously drive it all the way to a reviewed PR in one shot — "fable-new-issue-loop", "fable create the issue and run it to completion". Runs fable-new-issue to create a fully-specified issue (drafted by a Fable 5 subagent), then hands the new issue number to validate-issue-loop (validate → update → work-on-issue-loop) — stopping instead when a duplicate is found or the discussion hasn't converged on one issue.
+---
+
+# fable-new-issue-loop
+
+Chain fable-new-issue → validate-issue-loop into one autonomous run: a Fable 5 subagent drafts the issue, the main agent files it, and the loop drives it to a reviewed PR without a human in between. Identical to new-issue-loop except the front of the chain is fable-new-issue.
+
+**Do not skip filing a complete issue.** The downstream loop validates and implements *the issue text* — a thin or unverified draft propagates straight into the PR. Every step of fable-new-issue still runs (subagent drafting, duplicate gate, spot-check, filing); only the "offer next steps and wait" step is replaced by the handoff.
+
+## Input
+
+Same as fable-new-issue: an optional description of what the issue should cover; with no input, derive it from the current conversation. Optionally `owner/repo` when the issue belongs elsewhere.
+
+## Steps
+
+### 1. Run fable-new-issue
+
+Invoke the `fable-new-issue` skill (Skill tool, `skill: fable-new-issue`) with the user's description (or conversation-derived scope). Let it run its full process — Fable 5 subagent draft, duplicate gate, spot-check, filing. Capture the created issue number from its report.
+
+### 2. Stop gate — cases the loop can't safely continue
+
+| Condition | Action |
+|---|---|
+| The subagent found an existing open issue/PR already covering it (no issue filed) | **STOP.** Report the duplicate and the offer to update/comment instead — whether to merge scopes is a human call. |
+| The conversation held several distinct candidates | If one clearly converged, file it and **continue the chain with it**; the unfiled candidates go in the final report. If none clearly converged, **STOP** — report the candidates and ask which to file. Never bundle, never auto-file the extras. |
+| The draft was structurally wrong and fable-new-issue paused for a human decision | **STOP.** Relay what's off — don't file or re-dispatch on your own. |
+| The scope check named unfiled follow-ups | Continue with the **core issue only**; relay the unfiled follow-ups in the final report. |
+
+Otherwise (one issue filed cleanly), continue.
+
+### 3. Hand off to validate-issue-loop
+
+Invoke the `validate-issue-loop` skill (Skill tool, `skill: validate-issue-loop`) with the issue from step 1 passed explicitly — don't let it default to "latest open issue" and risk racing another just-filed issue. If filed to a repo other than the current checkout, pass the full `owner/repo#N` reference, not the bare number. Its own scope gate (too large / infeasible / already-addressed) still applies and may stop the run; that's the designed behavior, not a failure.
+
+Validating an issue this chain just filed is not redundant: validate-issue re-traces the claims against the code independently, catching anything the Fable draft or the spot-check got wrong.
+
+### 4. Report
+
+Relay validate-issue-loop's final summary (PR URL, review cycles, verdict), prefixed with one line covering the front of the chain: issue number/URL filed (drafted by Fable 5), complexity score, and any unfiled follow-ups from step 2.
+
+**Cap the whole report at 55 words, ELI18** — plain language, no jargon, as if explaining the outcome to a smart 18-year-old with no context on this codebase.
+
+## Red Flags — STOP
+
+| Situation | Action |
+|---|---|
+| Tempted to skip the Fable subagent and draft/file the issue yourself to go faster | Never — the draft coming from Fable 5 is the point of this skill |
+| fable-new-issue stopped on a duplicate or a structurally-wrong draft | Stop and report per step 2 — don't file anyway |
+| Tempted to hand off without an explicit issue reference | Always pass the issue from step 1 — `owner/repo#N` if filed cross-repo — "latest issue" can race |
+| validate-issue-loop's scope gate stops the run | Report its disposition faithfully — don't override and implement anyway |

package/skills/fable-validate/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: fable-validate
+description: Use when the user wants a GitHub issue validated by a Fable 5 subagent. Spins up a read-only subagent running on Fable 5 that executes the validate-issue procedure (claim tracing, architecture/consistency checks, complexity score), then relays the verdict back to the main agent, which presents it and takes any follow-on action (update issue, work on issue). Trigger on "/fable-validate", "fable validate <issue>", or "validate this with fable".
+---
+
+# fable-validate
+
+Delegate issue validation to a **Fable 5** subagent, then act on its verdict in the main agent. The subagent only validates — it never edits files or the issue; the main agent handles all follow-on actions.
+
+## Input
+
+Same as `validate-issue`:
+- Full URL: `https://github.com/<owner>/<repo>/issues/<N>`
+- Short form: `#<N>` or bare `<N>` (current repo)
+- `owner/repo#N`
+- **Nothing** — default to the latest open issue in the current repo.
+
+## Steps
+
+### 1. Resolve the validation procedure and the issue
+
+Locate the `validate-issue` SKILL.md the subagent must follow — prefer the project-local copy over the global one, since a repo may customize the procedure:
+
+1. `<repo>/.claude/skills/validate-issue/SKILL.md` (if it exists)
+2. `~/.claude/skills/validate-issue/SKILL.md`
+
+Record the absolute path. If neither exists, stop and tell the user.
+
+If the user referenced an issue, note the number/repo but do NOT fetch or pre-validate it yourself — the subagent owns steps 0–7 of the procedure, including fetching. If no issue was referenced, the subagent resolves the latest open issue itself per the procedure.
+
+### 2. Dispatch the Fable 5 validation subagent
+
+Do not validate the issue yourself first — the subagent owns the validation. Snapshot `git status --porcelain` before dispatching (the tree may already be dirty), then call the Agent tool with:
+
+- `subagent_type`: `Plan` (read-only: no Edit/Write, keeps validation side-effect-free)
+- `model`: `fable` (the whole point — the validation must come from Fable 5)
+- `run_in_background`: `false` — everything downstream depends on the verdict
+- `description`: `Validate issue #<N>` (or `Validate latest issue`)
+- `prompt`: hand it everything needed to validate independently:
+  - The issue reference exactly as the user gave it (or "no issue referenced — resolve the latest open issue per the procedure"), plus the working directory.
+  - Instruct it to **read the SKILL.md at the recorded path and execute its steps 0 through 7 exactly** — baseline resolution, fetch with `--comments` + PR timeline check, claim extraction, depth-rule verification with `file:line` citations, 5a/5c/5b proposal checks, complexity score, scope disposition, and the step-7 verdict format.
+  - It must STOP at step 7: no step 7.5/8 actions, no `gh issue edit`, no comments posted, no file edits — including via Bash (it lacks Edit/Write but still has Bash, so state this explicitly).
+  - Return the complete step-7 verdict verbatim as its final message, plus one line stating which baseline (branch/commit) claims were traced against.
+
+The subagent's final message comes back as the tool result; it is not shown to the user.
+
+If the call returns null or errors (user skip, terminal API failure), retry once; if it fails again, report the failure to the user instead of validating yourself.
+
+When the result arrives:
+- Run `git status --porcelain` and diff against the pre-dispatch snapshot to confirm the subagent made no file changes. If it did, tell the user and ask whether to revert before continuing.
+- Save the verdict verbatim to a scratchpad file immediately, so it survives context summarization and later steps can quote it exactly.
+
+### 3. Spot-check the verdict
+
+Before presenting it, spot-check the verdict's load-bearing findings against the code: the `file:line` citations for any ❌/⚠️ claims resolve to real code saying what the verdict says, and the verdict doesn't contradict repo conventions (CLAUDE.md). Evidence outranks verdicts — a subagent citation that contradicts its own mark means the mark is wrong. Fix small inaccuracies yourself and note them (update the scratchpad copy); if the verdict is structurally wrong (e.g. traced a stale baseline, missed the central claim), do NOT silently re-dispatch — tell the user what's off and let them decide whether to re-run with Fable 5 or proceed.
+
+### 4. Relay the verdict to the user
+
+Present the vetted verdict in the validate-issue step-7 format, noting it was produced by Fable 5 and which baseline it traced. Nothing is posted to GitHub at this stage — validation alone never writes to the issue.
+
+### 5. Follow-on actions (main agent)
+
+Handle the user's reply per the validate-issue procedure — these are main-agent actions, never re-delegated:
+
+- **"update issue"** → apply the suggested title/body edits per validate-issue step 8, including its claim-verification gate and final consistency pass. Footer: since the findings came from the Fable 5 subagent, use `Validated with LLM: Fable 5 | high | Harness: Claude Code | fable-validate` (stack under any existing footer lines per step 8; a repo CLAUDE.md footer format overrides).
+- **"work on issue"** → hand off to the `work-on-issue` skill per validate-issue step 7.5, surfacing any step-6.5 scope disposition first.
+- **"split issue" / "decompose"** → file the proposed parts per validate-issue step 6.5, each fully specified.
+
+## Notes
+
+- The validation subagent runs on Fable 5 regardless of the main agent's model — `model: fable` on the Agent call forces it.
+- One subagent, one verdict: don't fan out or re-run for a second opinion unless the user asks.
+- If the user's reference turns out not to be fetchable (wrong number, no auth), the subagent will report that per the procedure — relay it; never validate against a paraphrase.

package/skills/fable-validate-loop/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: fable-validate-loop
+description: Use when the user asks to validate a GitHub issue with Fable 5 and then autonomously drive it to a reviewed PR in one shot — "fable-validate-loop", "fable validate and work on #N", "fully automate issue #N with fable". Runs fable-validate, auto-applies its update-issue edits when the verdict calls for it, has fableplan produce and post a Fable 5 implementation plan (skipped for issues below C50 with no safety flags), then hands off to work-on-issue-loop — stopping instead when validation flags the issue as too large, architecturally infeasible, or already addressed by an existing PR.
+---
+
+# fable-validate-loop
+
+Chain fable-validate → (conditional) update issue → fableplan → work-on-issue-loop into one autonomous run: Fable 5 validates the issue, the main agent fixes the issue description if needed, Fable 5 plans the implementation (plan posted to the issue), and work-on-issue-loop implements the plan and drives the PR through review to convergence. This is fable-validate's interactive handoff made unattended — the loop reads its own verdicts and proceeds, instead of waiting for the user to reply.
+
+**Do not skip or reorder the chain.** Validation gates planning (a plan built on refuted claims is wrong), and the plan gates implementation (that's the point of routing through fableplan). The only sanctioned skip is the step-4 complexity gate (low-complexity issues bypass fableplan). Every other step of each skill still runs; only the "wait for the user's reply" moments are replaced by the decision rules below.
+
+## Input
+
+Same defaults as fable-validate: issue URL, `#<N>` / `<N>` / `owner/repo#N`, or nothing (defaults to the latest open issue in the current repo).
+
+## Steps
+
+### 1. Run fable-validate
+
+Invoke the `fable-validate` skill for the target issue (Skill tool, `skill: fable-validate`). Let it run fully — Fable 5 subagent validation, spot-check, verdict — producing the standard verdict block:
+
+```
+**#<N>: Update issue description? <Yes|No>**  ·  Complexity: <score>/100 — <driver>  ·  Scope: <OK | too large — split/umbrella/narrow>
+```
+
+Treat the verdict as structured output to parse yourself, not a prompt to wait on. Record the resolved issue number — every later step targets exactly this issue.
+
+### 2. Scope gate — stop if the issue is unsafe to auto-implement
+
+Check the verdict's **Scope** field, **Architecture** section, and **Concerns** (for an already-addressing PR) before doing anything else:
+
+| Condition | Action |
+|---|---|
+| `Scope: too large` (split / umbrella / narrow flagged) | **STOP.** Report the disposition and proposed parts. Implementing a multi-part issue as one PR reproduces the scope problem in the diff — splitting is a human call. |
+| Architecture marked ❌ **Infeasible** | **STOP.** Report the infeasibility and the "Optimal direction" note; planning and implementing a design the validation rejected would ship the wrong fix. |
+| A **merged** PR already implements the fix | **STOP.** Report the PR and the close/repurpose recommendation — nothing left to implement. |
+| An **open** PR is already addressing the issue | **STOP.** Report the overlapping PR; supersede/join/wait is a human call. |
+
+Otherwise (Scope: OK; architecture ✅/⚠️ or not applicable; no PR already addressing it), continue.
+
+### 3. Apply the update-issue edits, if called for
+
+If the verdict says **Update issue description? Yes**, apply the suggested title/body edits now per fable-validate step 5 / validate-issue step 8 — claim-verification gate, final consistency pass, and the stacked attribution line (`Validated with LLM: Fable 5 | high | Harness: Claude Code | fable-validate-loop`) — from the current checkout (no worktree for issue edits).
+
+If **No**, skip straight to step 4.
+
+**Order matters:** the edits land before fableplan runs, so the Fable 5 planner fetches and plans against the corrected issue, not the flawed original.
+
+### 4. Run fableplan — planning phase only (skip below C50)
+
+**Complexity gate:** if the verdict's validated complexity score is **below 50**, skip fableplan and go straight to step 5 — work-on-issue-loop plans adequately for low-complexity changes on its own. **Safety carve-out (overrides the gate):** if the validation flags money, data integrity, security, or an auto-protective mechanism anywhere in its findings, run fableplan regardless of score.
+
+Otherwise, invoke the `fableplan` skill for the same issue number (Skill tool, `skill: fableplan`), and **scope it to its planning phase — steps 1 through 5 only**: fetch the issue, dispatch the Fable 5 Plan subagent, sanity-check the plan against the code, post the vetted plan as an issue comment, and relay it. **Do NOT execute fableplan's steps 6–7 (worktree + build)** — implementation belongs to work-on-issue-loop in step 5, which owns the implement → PR → review chain; building here would duplicate it outside that chain.
+
+Give the planning subagent the validation verdict (the scratchpad copy from step 1) alongside the issue — the plan must respect what validation established (verified/refuted claims, the Optimal-direction note when architecture was ⚠️, 5b concerns).
+
+Keep the vetted plan's scratchpad file — step 5 passes it through. If fableplan fails after its internal retry, stop and report; don't fall back to planning yourself or implementing unplanned.
+
+### 5. Hand off to work-on-issue-loop
+
+Invoke the `work-on-issue-loop` skill for the same issue number (Skill tool, `skill: work-on-issue-loop`). Pass the issue number through explicitly — don't let it re-resolve "latest issue" — and instruct it that the implementation must follow the Fable 5 plan: point it at the plan's scratchpad file and the posted issue comment (`## Implementation plan (Fable 5)`), and tell it deviations from the plan are allowed only when the code contradicts the plan, and must be named in the PR body. (If step 4 was skipped by the complexity gate, there is no plan — hand off the issue alone and note the skip.)
+
+It runs its full loop: work-on-issue implements in a worktree, opens the PR, triggers `@claude` review, and fix-pr-review cycles until convergence.
+
+### 6. Report
+
+Relay work-on-issue-loop's final summary (PR URL, review cycles, final verdict), prefixed with one line covering the head of the chain: scope gate passed, issue updated or not, plan posted (comment URL) or skipped by the complexity gate. 
+
+**Cap the whole report at 55 words, ELI18** — plain language, no jargon, as if explaining the outcome to a smart 18-year-old with no context on this codebase.
+
+## Red Flags — STOP
+
+| Situation | Action |
+|---|---|
+| Tempted to skip validation or planning and jump to implementation | Never reorder — validate-then-plan-then-build is the point of this skill; the only sanctioned skip is the step-4 complexity gate (<C50, no safety flags) |
+| `Scope: too large`, Architecture ❌ Infeasible, or a PR already addressing the issue | Stop and report per step 2 — the cases the loop can't safely auto-resolve |
+| Tempted to wait for a literal user reply to fable-validate's or fableplan's prompt | Parse the output yourself and proceed per the step rules |
+| Verdict says Update issue description? Yes | Apply the edits **before** fableplan runs, so the plan targets the corrected issue |
+| fableplan about to enter its build steps (6–7) | Don't — stop it at step 5; work-on-issue-loop owns implementation |
+| fableplan's sanity-check finds the plan structurally wrong | Stop and report — don't hand a broken plan to work-on-issue-loop, and don't silently re-plan |

package/skills/fableplan/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: fableplan
+description: Use when the user wants a task planned by a Fable 5 planning subagent before building it. Spins up a Plan subagent running on Fable 5 to produce an implementation plan, relays the plan back to the main agent to build, and — if a GitHub issue is referenced — posts the plan as a comment on that issue. Trigger on "/fableplan", "fableplan this", or "plan this with fable".
+---
+
+# fableplan
+
+Delegate planning to a **Fable 5** Plan subagent, then build from its plan in the main agent. The main agent does the building — the subagent only plans.
+
+## Input
+
+The user provides a task description, and optionally a GitHub issue:
+- A task in prose ("fableplan adding X to Y").
+- A GitHub issue reference — full URL, `#<N>`, bare `<N>`, or `owner/repo#N`. When present, the plan is also posted as an issue comment.
+- If neither is obvious, ask the user what to plan before dispatching.
+
+## Steps
+
+### 1. Resolve the GitHub issue (only if one is referenced)
+
+If the user named an issue, fetch it so the subagent plans against the real requirements, not a paraphrase:
+
+```
+gh issue view <N> --json number,title,body,url
+```
+
+For the `owner/repo#N` form (or a full URL to another repo), add `-R owner/repo` — a bare `gh issue view <N>` only resolves against the current repo.
+
+If the command fails (wrong number, no auth, no repo), stop and tell the user — never proceed by planning against your paraphrase of an issue you couldn't fetch.
+
+Record the issue number and URL — you'll need them in step 4. If no issue is referenced, skip this and step 4's posting.
+
+### 2. Dispatch the Fable 5 Plan subagent
+
+Do not re-plan the task yourself first — the subagent owns the plan. Snapshot `git status --porcelain` before dispatching (the tree may already be dirty), then call the Agent tool with:
+
+- `subagent_type`: `Plan`
+- `model`: `fable` (this is the whole point of the skill — the plan must come from Fable 5)
+- `run_in_background`: `false` — every later step depends on the plan, so wait for it synchronously instead of doing other work first
+- `description`: `Plan <short task name>`
+- `prompt`: Hand the subagent everything it needs to plan independently — the full task description, the issue title/body if one was fetched, the working directory, and any constraints the user stated. Tell it explicitly:
+  - Produce a concrete, ordered implementation plan (files to create/modify, the approach, build sequence, risks/edge cases, and how to verify).
+  - Plan the absolute-best solution the task calls for, evaluated as if cost, effort, time, token spend, and code volume were unlimited — they are not factors and must never narrow the option space. The only constraints that override "best" are correctness and safety.
+  - Return the plan as its final message in clean Markdown suitable to (a) act on directly and (b) post verbatim as a GitHub issue comment.
+  - It is planning only — it must NOT make code edits, including via Bash (no writing/modifying files, no commits). The subagent lacks Edit/Write, but still has Bash, so this must be stated explicitly.
+
+The Plan subagent's final message is returned to you as the tool result; it is not shown to the user.
+
+If the call returns null or errors (user skip, terminal API failure), retry once; if it fails again, report the failure to the user instead of planning yourself.
+
+When the result arrives:
+- Run `git status --porcelain` and compare against the pre-dispatch snapshot to confirm the subagent made no file changes despite the no-edit instruction. If it did, tell the user and ask whether to revert before continuing.
+- Save the plan verbatim to a scratchpad file immediately, so it survives context summarization during a long build and step 4 can post it exactly as produced.
+
+### 3. Sanity-check the plan against the code
+
+Before posting or presenting it, verify the plan's load-bearing claims against the actual codebase: the files it says to modify exist, the functions/symbols it references are real, and it doesn't contradict repo conventions (CLAUDE.md). Fix small inaccuracies yourself and note them; if the plan is structurally wrong (built on a file or mechanism that doesn't exist), do NOT automatically re-dispatch the Plan subagent — stop and tell the user what's failing, and let them decide whether to re-plan with Fable 5, adjust the task, or proceed anyway. If you fixed small inaccuracies, update the scratchpad file from step 2 so it reflects the corrected plan before step 4 posts it.
+
+### 4. Post the plan to the GitHub issue (only if one was resolved in step 1)
+
+Now that the plan has passed the sanity-check, save it to the issue as a comment before building, so the vetted plan is preserved on the issue regardless of how the build goes. This comment is not updated after the build.
+
+```
+gh issue comment <N> --body-file <tmpfile>
+```
+
+Add `-R owner/repo` when the issue lives in another repo (as in step 1). Use the scratchpad file from step 2 (with any step-3 corrections) as the body-file base — it avoids shell-escaping problems with Markdown. Prefix the comment so its origin is clear with a heading line `## Implementation plan (Fable 5)` above the plan body, and end the body with the standard metadata footer:
+
+```
+---
+Created with: Fable 5 | high | Claude Code | fableplan
+```
+
+After posting, give the user the comment URL `gh` returns. Follow the repo's CLAUDE.md conventions for comment formatting if any apply (e.g. avoid `#N` auto-links in list items). If no issue is referenced, skip this step.
+
+### 5. Relay the plan to the user
+
+Present the vetted plan to the user (the main agent). This is the plan you will build from.
+
+### 6. Set up an isolated git worktree
+
+Before making any code changes, move the build into its own git worktree so it never touches the user's current workspace. If the directory isn't a git repository, tell the user and ask how to proceed rather than building in place. Otherwise create a fresh branch and worktree for the task:
+
+```
+git worktree add ../<repo>-fableplan-<short-task-name> -b fableplan/<short-task-name>
+```
+
+Do all of step 7's building inside that worktree. When the build is done, follow the repo's usual conventions for merging or opening a PR from the branch, and remove the worktree once it's no longer needed (`git worktree remove <path>`).
+
+### 7. Build
+
+In the worktree from step 6, the main agent builds the task per the plan. Confirm with the user first only if the plan reveals ambiguity or a decision the user must make; otherwise proceed.
+
+## Notes
+
+- The Plan subagent runs on Fable 5 regardless of the main agent's model — `model: fable` on the Agent call forces it.
+- If the user did not reference an issue, never invent one or post anywhere — just plan and build.