@dansyuqri/spark-joy 0.2.0 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (7) hide show
  1. package/README.md +18 -17
  2. package/dist/app/assets/{index-CX9CpO88.js → index-_XxERk0m.js} +1 -1
  3. package/dist/app/index.html +1 -1
  4. package/dist/cli.js +24 -6
  5. package/dist/cli.js.map +1 -1
  6. package/package.json +4 -1
  7. package/plugin/skills/spark-joy/SKILL.md +1 -1
package/README.md CHANGED
@@ -14,7 +14,7 @@
14
14
  <img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="MIT license">
15
15
  </p>
16
16
 
17
- 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.
17
+ AI-written PRs are often thousands of lines long: too big to review properly. spark-joy has your coding agent 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.
18
18
 
19
19
  **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*.
20
20
 
@@ -30,12 +30,12 @@ Inspired by [mr-cast](https://github.com/phanshiyu/mr-cast).
30
30
 
31
31
  ```
32
32
  spark-joy extract → hunks.json every hunk of the diff gets an id (h001, h012.1, …)
33
- Claude (the skill) → plan.json hunks grouped into chunks, in two review orders, plus a feature list
33
+ the agent (skill) → plan.json hunks grouped into chunks, in two review orders, plus a feature list
34
34
  spark-joy validate → ok / errors every non-mechanical hunk is in exactly one chunk, sizes are sane
35
35
  spark-joy serve → review app choose an order, review chunk by chunk, export review.md
36
36
  ```
37
37
 
38
- - **Claude never copies code into the plan.** It refers to hunks by id, and `validate` checks that no change is missing or reviewed twice.
38
+ - **The agent never copies code into the plan.** It refers to hunks by id, and `validate` checks that no change is missing or reviewed twice.
39
39
  - **Two review orders.** *Foundations first* goes types → logic → callers → tests. *By feature* follows one capability at a time, end to end. You pick one, and can switch later without losing progress.
40
40
  - **Mechanical changes are separated.** Lockfiles, generated files, binaries, renames and whitespace-only changes go into a collapsed *skim* section.
41
41
  - **Chunks stay small.** The target is 100–300 changed lines and validation warns above 400. Large hunks are split at function boundaries so they can go into different chunks.
@@ -47,26 +47,27 @@ spark-joy serve → review app choose an order, review chunk by chunk, e
47
47
 
48
48
  Requires Node 24 or newer and git. Published on npm as [`@dansyuqri/spark-joy`](https://www.npmjs.com/package/@dansyuqri/spark-joy).
49
49
 
50
- Install the CLI, then add the skill to Claude Code, either as a plugin:
50
+ spark-joy is an [Agent Skill](https://agentskills.io) plus a CLI, so it works with Claude Code, Codex, Gemini CLI, Cursor, OpenCode and other agents that read `SKILL.md`.
51
51
 
52
52
  ```sh
53
53
  npm install -g @dansyuqri/spark-joy
54
+ spark-joy install-skill
54
55
  ```
55
- ```
56
- /plugin install spark-joy --marketplace Dansyuqri/spark-joy
57
- ```
58
-
59
- or straight from the CLI: `spark-joy install-skill` (add `--project` to install into `./.claude/skills`).
60
56
 
61
- ## Use
57
+ `install-skill` copies the skill to `~/.claude/skills` (Claude Code) and `~/.agents/skills` (Codex, Gemini CLI, Cursor, OpenCode and others).
58
+ - `--agent claude` or `--agent agents` installs to one of them only.
59
+ - `--project` installs into the repo.
60
+ - `--print` prints the skill for agents without skill support: paste it into `AGENTS.md` or the agent's instructions.
62
61
 
63
- In Claude Code, inside the repo with the branch checked out:
62
+ In Claude Code you can install it as a plugin instead:
64
63
 
65
64
  ```
66
- /spark-joy
65
+ /plugin install spark-joy --marketplace Dansyuqri/spark-joy
67
66
  ```
68
67
 
69
- Or say "help me review this PR in chunks". Claude extracts the diff, reads it, writes and validates the plan, and starts the app at http://127.0.0.1:4848.
68
+ ## Use
69
+
70
+ Inside the repo with the branch checked out, ask your agent to "review this PR in chunks" (in Claude Code, `/spark-joy` also works). The agent extracts the diff, reads it, writes and validates the plan, and starts the app at http://127.0.0.1:4848.
70
71
 
71
72
  In the app:
72
73
 
@@ -87,7 +88,7 @@ In the app:
87
88
  | `spark-joy serve [--port n]` | Start the review app |
88
89
  | `spark-joy export [--stdout]` | Write `review.md` |
89
90
  | `spark-joy split [--check cmd] [--apply]` | Turn a split plan into stacked local branches |
90
- | `spark-joy install-skill [--project]` | Install the Claude Code skill |
91
+ | `spark-joy install-skill [--agent a] [--project] [--print]` | Install the agent skill |
91
92
 
92
93
  `base` defaults to `origin/HEAD`, then `origin/main`, `origin/master` or `main`. Runs are stored in `.spark-joy/`, which ignores itself in git.
93
94
 
@@ -95,12 +96,12 @@ The plan format is documented in [SKILL.md](plugin/skills/spark-joy/SKILL.md), a
95
96
 
96
97
  ## Split your own changes
97
98
 
98
- 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.
99
+ Writing the big PR yourself? Ask your agent 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.
99
100
 
100
101
  <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>
101
102
 
102
103
  1. **Extract** what you want to split: `--staged`, `--uncommitted`, or a base branch for the whole branch.
103
- 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.
104
+ 2. **Plan.** The agent 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.
104
105
  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.
105
106
  4. **Apply.** `split --apply` creates the local branches and writes each PR's title and description to `prs.md`. Nothing is pushed.
106
107
 
@@ -129,5 +130,5 @@ Layout:
129
130
  - `cli/`: commands, diff parsing, splitting, classification, server, stacked-branch builder.
130
131
  - `shared/`: schemas, validation and derived state, used by both the CLI and the app.
131
132
  - `src/`: the React review app.
132
- - `plugin/`: the Claude Code plugin and skill.
133
+ - `plugin/`: the skill, packaged as a Claude Code plugin.
133
134
  - `test/`: Vitest, with a fixture git repo.