@fableplan/fableplan 1.0.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,14 @@
+{
+  "name": "fableplan",
+  "description": "Marketplace for the fableplan Claude Code plugin: Fable 5-driven implementation planning before building.",
+  "owner": {
+    "name": "Richard Kuo"
+  },
+  "plugins": [
+    {
+      "name": "fableplan",
+      "source": "./",
+      "description": "Delegates implementation planning to a Fable 5 planning subagent, then builds from the vetted plan — posting it to a referenced GitHub issue along the way."
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,12 @@
+{
+  "name": "fableplan",
+  "displayName": "fableplan",
+  "version": "1.0.0",
+  "description": "Delegates implementation planning to a Fable 5 planning subagent, then builds from the vetted plan — posting it to a referenced GitHub issue along the way.",
+  "author": {
+    "name": "Richard Kuo"
+  },
+  "repository": "https://github.com/richkuo/fableplan",
+  "license": "MIT",
+  "keywords": ["planning", "fable", "subagent", "github-issues"]
+}

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,83 @@
+# fableplan
+
+A [Claude Code](https://claude.com/claude-code) skill that delegates implementation planning to a **Fable 5** planning subagent, then builds from that plan in your main session — and, when a GitHub issue is referenced, posts the vetted plan to the issue as a comment.
+
+The idea: let a dedicated planning model (Fable 5) produce a concrete, ordered implementation plan before any code is written, review it against the real codebase, preserve it on the tracker, and only then build — in an isolated git worktree so your working tree is never touched.
+
+## What it does
+
+Trigger it with `/fableplan`, "fableplan this", or "plan this with fable", plus a task description and optionally a GitHub issue (`#N`, a full URL, or `owner/repo#N`).
+
+The skill then runs a 7-step flow:
+
+1. **Resolve the GitHub issue** (only if one is referenced) so the planner works from the real requirements, not a paraphrase.
+2. **Dispatch the Fable 5 Plan subagent**, confirm it made no edits, and save the plan verbatim to a scratch file.
+3. **Sanity-check the plan** against the actual codebase (files, symbols, conventions). It stops and asks you if the plan is structurally wrong rather than silently re-planning.
+4. **Post the vetted plan** to the GitHub issue as a comment (only if one was referenced).
+5. **Present the plan** to you.
+6. **Set up an isolated git worktree** so the build never touches your current workspace.
+7. **Build** the task from the plan, inside that worktree.
+
+## Install
+
+### As a plugin (recommended)
+
+This repo is a Claude Code plugin marketplace. Inside any Claude Code session:
+
+```
+/plugin marketplace add richkuo/fableplan
+/plugin install fableplan@fableplan
+```
+
+The skill is picked up automatically from the plugin's `skills/` directory, and updates flow through the plugin system.
+
+### Ask Claude Code to install it
+
+Paste this straight into a Claude Code prompt:
+
+```
+Install the fableplan skill from https://github.com/richkuo/fableplan into ~/.claude/skills — fetch skills/fableplan/SKILL.md and place it at ~/.claude/skills/fableplan/SKILL.md
+```
+
+### With `npx skills`
+
+If you use [Vercel Labs' `skills` CLI](https://github.com/vercel-labs/skills), it discovers the `skills/fableplan/SKILL.md` layout automatically:
+
+```sh
+npx skills add richkuo/fableplan
+```
+
+This installs into `.claude/skills/` (and any other agents it detects). It's a third-party tool, separate from the official plugin marketplace above.
+
+### Manual (single file)
+
+A Claude Code skill is just a directory containing a `SKILL.md`, so you can also install it with one command — no clone needed:
+
+```sh
+mkdir -p ~/.claude/skills/fableplan && curl -fsSL https://raw.githubusercontent.com/richkuo/fableplan/master/skills/fableplan/SKILL.md -o ~/.claude/skills/fableplan/SKILL.md
+```
+
+This puts it in your personal skills directory (`~/.claude/skills/`), available in every project. To scope it to a single project instead, put the file at `<repo>/.claude/skills/fableplan/SKILL.md`.
+
+### Verify
+
+Start a new Claude Code session (or restart the current one), then run:
+
+```
+/fableplan <task to plan>
+```
+
+## Requirements
+
+- Claude Code with access to the `fable` model for the planning subagent.
+- `gh` (GitHub CLI), authenticated, if you want the issue-comment step.
+- A git repository for the build step (the skill stops and asks if the working directory isn't one).
+
+## Notes
+
+- The planning subagent always runs on Fable 5 regardless of your main session's model.
+- The skill adapts to the target repo's conventions (e.g. its `CLAUDE.md`); behavior isn't hardcoded to any one project.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/bin/install.mjs

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+import { cpSync, existsSync, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const SKILL = 'fableplan';
+const pkgRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const src = join(pkgRoot, 'skills', SKILL);
+
+if (!existsSync(join(src, 'SKILL.md'))) {
+	console.error(`fableplan: could not find skills/${SKILL}/SKILL.md in the package.`);
+	process.exit(1);
+}
+
+const project = process.argv.includes('--project');
+const skillsDir = project
+	? join(process.cwd(), '.claude', 'skills')
+	: join(homedir(), '.claude', 'skills');
+const dest = join(skillsDir, SKILL);
+
+mkdirSync(skillsDir, { recursive: true });
+cpSync(src, dest, { recursive: true });
+
+const scope = project ? 'this project' : 'your personal skills';
+console.log(`fableplan installed into ${scope}:\n  ${dest}`);
+console.log('\nRestart Claude Code (or start a new session), then run:\n  /fableplan <task to plan>');

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@fableplan/fableplan",
+  "version": "1.0.0",
+  "description": "Installer for the fableplan Claude Code skill: plan with Fable 5, build with your main-session model.",
+  "type": "module",
+  "bin": {
+    "fableplan": "bin/install.mjs"
+  },
+  "files": [
+    "bin",
+    "skills",
+    ".claude-plugin",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "claude-code",
+    "claude",
+    "skill",
+    "plugin",
+    "fable",
+    "planning"
+  ],
+  "homepage": "https://github.com/richkuo/fableplan#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/richkuo/fableplan.git"
+  },
+  "author": "Richard Kuo",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/fableplan/SKILL.md

@@ -0,0 +1,96 @@
+---
+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).
+  - 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.