@dansyuqri/spark-joy 0.1.4 → 0.2.0

package/README.md

@@ -14,9 +14,15 @@
   <img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="MIT license">
 </p>
 
-AI-assisted pull requests are often thousands of lines long, too big to review properly in one go. spark-joy has Claude break a big PR or MR into small, ordered chunks, then opens a local app where you review them one batch at a time. You tick chunks off, leave notes, and finish with a summary of everything the PR changes.
+AI-written PRs are often thousands of lines long: too big to review properly. spark-joy has Claude split a PR into small, ordered chunks, then opens a local app where you review them one at a time, see how they connect on a map, and finish with a summary of what the PR does.
 
-It works from plain git, so it works the same for GitHub, GitLab or anything else. Nothing is posted anywhere; your notes export as markdown you can paste into the PR.
+**Example:** spark-joy's own history, one 7.8k-line diff, became **18 chunks of 141–369 lines**, every hunk placed exactly once. The 2.7k-line lockfile went straight to *skim*.
+
+<p align="center"><img src="assets/demo.gif" width="800" alt="Choosing a review order, reviewing a chunk with a line note, then zooming into a chunk on the map"></p>
+
+Writing the big PR yourself? spark-joy can also split your staged, uncommitted or branch changes into small stacked PRs. See [Split your own changes](#split-your-own-changes).
+
+Works from plain git, so GitHub, GitLab or anything else. Nothing is posted anywhere; notes export as markdown for the PR.
 
 Inspired by [mr-cast](https://github.com/phanshiyu/mr-cast).
 
@@ -39,13 +45,19 @@ spark-joy serve     →  review app    choose an order, review chunk by chunk, e
 
 ## Install
 
-Requires Node 22 or newer and git. Published on npm as [`@dansyuqri/spark-joy`](https://www.npmjs.com/package/@dansyuqri/spark-joy).
+Requires Node 24 or newer and git. Published on npm as [`@dansyuqri/spark-joy`](https://www.npmjs.com/package/@dansyuqri/spark-joy).
+
+Install the CLI, then add the skill to Claude Code, either as a plugin:
 
 ```sh
 npm install -g @dansyuqri/spark-joy
-spark-joy install-skill            # or --project to install into ./.claude/skills
+```
+```
+/plugin install spark-joy --marketplace Dansyuqri/spark-joy
 ```
 
+or straight from the CLI: `spark-joy install-skill` (add `--project` to install into `./.claude/skills`).
+
 ## Use
 
 In Claude Code, inside the repo with the branch checked out:
@@ -67,17 +79,39 @@ In the app:
 | Command | What it does |
 | --- | --- |
 | `spark-joy extract [base] [--working]` | Diff `merge-base(base, HEAD)..HEAD` (or the working tree) into a run in `.spark-joy/<branch>/` |
+| `spark-joy extract --staged \| --uncommitted` | Diff `HEAD` against the index or the working tree, for splitting |
 | `spark-joy outline` | Compact list of every file and hunk with sizes and flags |
 | `spark-joy show <ids…> \| --file <path>` | Print hunks in full; accepts ranges like `h003..h010` |
 | `spark-joy links` | Cross-file links: which hunk uses a name another defines |
 | `spark-joy validate [--json]` | Check `plan.json` against the hunks |
 | `spark-joy serve [--port n]` | Start the review app |
 | `spark-joy export [--stdout]` | Write `review.md` |
+| `spark-joy split [--check cmd] [--apply]` | Turn a split plan into stacked local branches |
 | `spark-joy install-skill [--project]` | Install the Claude Code skill |
 
 `base` defaults to `origin/HEAD`, then `origin/main`, `origin/master` or `main`. Runs are stored in `.spark-joy/`, which ignores itself in git.
 
-The plan format is documented in [skill/SKILL.md](skill/SKILL.md), and the schema is in [shared/schema.ts](shared/schema.ts).
+The plan format is documented in [SKILL.md](plugin/skills/spark-joy/SKILL.md), and the schema is in [shared/schema.ts](shared/schema.ts).
+
+## Split your own changes
+
+Writing the big PR yourself? Ask Claude to "split my changes into smaller PRs". It turns your staged changes, uncommitted changes or whole branch into small PRs, each built on the one before.
+
+<p align="center"><img src="assets/split.gif" width="800" alt="Extracting uncommitted changes, previewing five stacked PRs in the app, checking each PR's tests, then creating the branches"></p>
+
+1. **Extract** what you want to split: `--staged`, `--uncommitted`, or a base branch for the whole branch.
+2. **Plan.** Claude groups every change into ordered PRs: each must build on the ones before, and lockfiles go with the change that needs them. Preview the stack in the app; the Map shows how the PRs depend on each other.
+3. **Check.** `split` builds the PRs and confirms the last one matches your changes exactly. `--check` runs your tests on each PR in a temporary worktree.
+4. **Apply.** `split --apply` creates the local branches and writes each PR's title and description to `prs.md`. Nothing is pushed.
+
+```sh
+spark-joy extract --uncommitted                 # or --staged, or a base for the whole branch
+spark-joy split                                 # dry run
+spark-joy split --check "npm ci && npm test"    # optional
+spark-joy split --apply                         # creates <branch>-split/1-…, 2-…
+```
+
+Your working tree, staged files and current branch are never touched: the PRs are built from a temporary git index. If anything doesn't add up, no branches are created.
 
 ## Develop
 
@@ -92,8 +126,8 @@ npm run dev:app      # Vite dev server; proxies /api to a running `spark-joy ser
 
 Layout:
 
-- `cli/`: commands, diff parsing, splitting, classification, server.
+- `cli/`: commands, diff parsing, splitting, classification, server, stacked-branch builder.
 - `shared/`: schemas, validation and derived state, used by both the CLI and the app.
 - `src/`: the React review app.
-- `skill/`: the Claude Code skill.
+- `plugin/`: the Claude Code plugin and skill.
 - `test/`: Vitest, with a fixture git repo.