Skip to content
Back to search

jspark-forge

MarketplaceWorks with Claude CodeGitHub

A Claude Code plugin for non-technical builders. Pick up where you left off in 30 seconds after a crash, logout or usage limit. Blocks dangerous commands with hooks. Remembers your decisions. Free and open source (MIT). By JSPARK AI.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/harishgoswami23--jspark-forge/badge.svg)](/listings/harishgoswami23--jspark-forge)

HTML

<a href="/listings/harishgoswami23--jspark-forge"><img src="/api/listings/harishgoswami23--jspark-forge/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Needs Claude Code, git and **Node.js 18 or newer**. If Node.js is missing or too old, JSPARK Forge says so when Claude Code starts (*"JSPARK Forge is off: it needs Node.js 18 or newer…"*) instead of failing silently.

/plugin install jspark-forge --marketplace harishgoswami23/jspark-forge

That is the whole install. superpowers comes with it. On first start JSPARK Forge sets up, by itself, each with its undo:

- **Auto-update.** It switches on updates for the JSPARK Forge marketplace (one key in your `settings.json`, once per machine), so each new version loads the next time Claude Code starts. Undo: `/plugin`, then **Marketplaces**, then **jspark-forge**. - **The code map** (codebase-memory-mcp 0.12.1), as a plugin server. Undo: `- code-map: off` under `## Settings` in `rules.md`, or `JSPARK_FORGE_CODE_MAP=off`. - **Playwright** (`@playwright/mcp` 0.0.86), as a plugin server, so Claude can check its own screens. It gives Claude tools only in a project with a front end. It needs Node.js 20 or newer and stays off on Node.js 18 and 19. Undo: `- playwright: off` under `## Settings` in `rules.md`, or `JSPARK_FORGE_PLAYWRIGHT=off`. - **frontend-design and Chrome DevTools**, added once, in the background, from Anthropic's plugin directory. They load the next time Claude Code starts. Undo: `/plugin uninstall frontend-design@claude-plugins-official` and `/plugin uninstall chrome-devtools-mcp@claude-plugins-official`. - **A status line**, only when you have none. Undo: `/jspark-forge:init --undo-statusline`.

Undo for the two servers stops them but does not delete them. They sit in `~/.claude/jspark-forge/engines/` (under `CLAUDE_CONFIG_DIR` if you set it); delete that folder to remove them. They are installed again on the next start unless you have switched them off.

To stop the automatic switch-on of auto-update and the two companions, set `JSPARK_FORGE_AUTO_SETUP=off`.

What this adds to your machine, said plainly: each of the two servers is installed once with `npm` into `~/.claude/jspark-forge/engines/`, in the background, the first time it starts (not inside a hook; the first session may have to be restarted when the install ends), and the two companions are added with `claude plugin install`, once. Those are the only times JSPARK Forge goes online. On Windows, Defender has been seen to flag the code map engine's program wrongly (a false positive): allow it, or switch the code map off.

- **Each git project switches on by itself** the first time you open Claude Code in it: a hidden `.jspark-forge/` folder appears. Commit `rules.md`, `decisions.md`, `launch.md` and `.gitignore` to share them, and build graph files with their briefs (`graphs/*.md`, `briefs/*.md`). Everything else (handoff, log, the state of a running build graph, local copies of published pages) stays local and git-ignored. If `.jspark-forge/.gitignore` goes missing, it is made again at the next session start. Old archived handoffs and the files of repos you reviewed are cleared after 30 days, and old session records (ended over 7 days ago, or untouched for 30) at a session start. Folders that are not git projects are left alone. - **Switches** under `## Settings` in `rules.md`: `- notes: off` stops the "add a note" reminder before commits; `- statusline-segment: off` hides JSPARK Forge's part of the status line; `- short-answers: off` switches off the short-by-default rule; `- stay-reachable: off` switches off the stay-reachable rule (below); `- fresh-session: off` stops the "start a new session" note; `- ui-skills: off`, `- code-map: off` and `- playwright: off` are described above. - **Asking a question while Claude works.** A message you send mid-task reaches Claude only when its current command ends, so a 10-minute test run can make you wait 10 minutes. JSPARK Forge tells Claude at every session start to run long commands in the background and to answer your mid-task question first. It is a rule, not a hook: nothing

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 31 lines
  1. {
  2. "name": "jspark-forge",
  3. "owner": {
  4. "name": "JSPARK AI"
  5. },
  6. "metadata": {
  7. "description": "JSPARK Forge and superpowers in one install: superpowers (by Jesse Vincent) is a declared dependency, listed from its own repository, not copied."
  8. },
  9. "plugins": [
  10. {
  11. "name": "jspark-forge",
  12. "source": "./",
  13. "description": "Resume after a crash, logout or limit. Rules enforced by hooks.",
  14. "category": "development",
  15. "dependencies": [
  16. "superpowers"
  17. ]
  18. },
  19. {
  20. "name": "superpowers",
  21. "source": {
  22. "source": "url",
  23. "url": "https://github.com/obra/superpowers.git",
  24. "sha": "22f0b463e7a5e579904dd6211a520321035526f7"
  25. },
  26. "description": "By Jesse Vincent (MIT). Brainstorm, plan, test first, review, verify. Listed here from its own repository; JSPARK Forge does not copy or change it.",
  27. "homepage": "https://github.com/obra/superpowers",
  28. "category": "development"
  29. }
  30. ]
  31. }
README.md · README · 487 lines · 1 finding marked
  1. <p align="center">
  2. <a href="https://github.com/harishgoswami23/jspark-forge">
  3. <picture>
  4. <source media="(prefers-color-scheme: dark)" srcset="assets/jspark-ai-logo-dark.jpeg">
  5. <img alt="JSPARK AI" src="assets/jspark-ai-logo-light.jpeg" width="360">
  6. </picture>
  7. </a>
  8. </p>
  9. # JSPARK Forge
  10. **Claude Code forgets. JSPARK Forge doesn't. Open Claude Code and pick up where you left off in 30 seconds.**
  11. *Rules enforced by hooks, not by hoping Claude remembers.*
  12. A Claude Code based coding tool for non-technical founders: it is a plugin for Claude Code, so you can build software
  13. without being a coder and without losing your place. Built for Claude Code, by JSPARK AI. Free and open source (MIT).
  14. > **Plan-limit saves need a plan that reports usage: Claude Pro, Max, Ultra or Team** (Team: observed, re-checked
  15. > each release). Claude Code shares plan usage (5-hour and weekly limits) only with plans that report it. On any plan, JSPARK Forge still saves before the context limit and after every
  16. > step, and `/jspark-forge:handoff` saves on demand.
  17. <p align="center"><img alt="A Claude Code window is closed mid-task; a new session shows where the work stood and carries on" src="assets/demo-resume.gif" width="820"></p>
  18. <p align="center"><em>An illustration of the flow, with the words JSPARK Forge prints. Not a screen recording.</em></p>
  19. <!-- The GIF is made by docs/launch/make_demo_gif.py. To replace it with a real screen recording: docs/demo-gif-script.md. -->
  20. ---
  21. ## What it does
  22. 1. **Saves where you are, all the time.** A one-page handoff (task, step, next action, what was running, what is
  23. waiting on you) is rewritten on every save trigger below. The task is your last real request (not "go on", and not a
  24. helper's report); the four requests before it and the end of Claude's last reply are kept, work in another git
  25. project is named ("Also worked in"), and step progress is read from Claude Code's task tools as well as the plan.
  26. It counts the files not committed (an untracked folder counts every file in it, up to 2000) and says when a repo
  27. has no commits yet. Resuming a session never wipes the history.
  28. 2. **Shows it back after any cutoff, and asks first.** Open Claude Code again: JSPARK Forge shows where you were and
  29. asks "Continue?" before picking the old task back up. No command to type. If your first message already says
  30. "continue", it does not ask a second time. If the last session was cut off by a crash
  31. or a power cut, it also says so and tells Claude to check what was half done first (see "When it saves").
  32. 3. **Blocks dangerous actions.** A published list, enforced by hooks, with a typed confirmation to override.
  33. 4. **Keeps a short action log** for the step that was cut off (7 days, then a one-paragraph summary per day).
  34. 5. **Keeps Claude grounded, and short.** Two rules at every session start. Grounding: cite the file and line, say
  35. "not found" otherwise, never describe code it has not read. Short by default: lead with the answer, bullets or a
  36. table for lists, one line of explanation unless you ask for more, and always the warnings, risks, decisions and
  37. blockers. `- short-answers: off` switches the second one off.
  38. 6. **Keeps open questions in sight.** A question Claude asks you that holds up work stays on a "waiting on you" list
  39. until you answer it: in the status line (`⏳ 2 waiting on you · oldest 14h`), first thing at the next session
  40. start, and in the handoff, so a cutoff cannot bury it. A question can say what it blocks and whether the answer can
  41. be undone, and shows `blocks launch item: <title>` when it names an item on your launch list. After you answer,
  42. Claude offers to record the answer as a decision.
  43. 7. **Keeps a local copy of every page Claude publishes.** A link can stop working when you change account; a file
  44. does not. In your own projects the page's file is copied into `.jspark-forge/artifacts/` and listed in
  45. `.jspark-forge/artifacts.md` with its link. A page published without a file is listed as having no copy, and Claude
  46. is told to save it. Session start and `/jspark-forge:check` list pages whose copy is missing. Claude is warned when
  47. it writes a document into a temporary folder, and once a day session start lists up to 5 such documents that are
  48. not in the project. The copies stay on your machine: they are not committed.
  49. Your work stays on your machine. No telemetry. JSPARK Forge goes online only when `npm` installs the two servers (once, in the background, on
  50. their first start) and when it adds two companions with `claude plugin install` (see Install).
  51. ## How JSPARK Forge differs
  52. | | Claude Code alone | Method / workflow kits | Large all-in-one kits | **JSPARK Forge** |
  53. |---|---|---|---|---|
  54. | Back to work after a crash or limit from a one-page handoff, shown when you open Claude Code | Reopens the whole old conversation | No | Not as a core feature | **Yes** |
  55. | Save forced at 95 % of context or plan usage | No | No | No | **Yes** (plan usage: Pro/Max/Ultra/Team) |
  56. | Dangerous actions blocked by hooks, with a published list and typed override | Permission prompts only | Instructions Claude may forget | Varies, many hooks | **Yes, every hook documented** |
  57. | Small: one job, a handful of hooks | n/a | Yes | No | **Yes** |
  58. Beyond the handoff (where you were), JSPARK Forge keeps the **why** (decision memory), the **what and where** (a code
  59. map, with codebase-memory-mcp), **long builds** that survive a cutoff (build graphs), and a **launch
  60. list** against scope creep. It also has **guest mode** (review someone else's repo without writing anything into it),
  61. **readonly sources** (keep an old system next to the new one, never edited) and a health check
  62. (`/jspark-forge:doctor`). Each is described below.
  63. ## Decision memory (the why)
  64. Decisions, rules and lessons for a project live in `.jspark-forge/decisions.md` (commit it to share with your team).
  65. Each is one line, tied to the files it covers. Just before Claude edits one of those files, it sees the decisions that
  66. touch it (as data, not orders). After a commit that settles a choice, or a plan you approve in plan mode, JSPARK Forge
  67. offers *"Record the decision?"*; nothing is recorded without your yes. When a commit changes a covered file, the
  68. decision is flagged for a look: at most once a day for each decision, and not in the 14 days after it was recorded or
  69. verified.
  70. - `/jspark-forge:decide` records, updates, verifies or retires a decision. To turn one into a hard block, it prints
  71. the line to add to `rules.md` (`forge.js decide --promote <id>`); it never edits `rules.md` itself.
  72. - `/jspark-forge:decisions` lists what is on file. `/jspark-forge:check` asks whether each is still true.
  73. - `/jspark-forge:handoff done` offers once to record the task's lasting lessons as decisions.
  74. ## Code map (the what and where)
  75. [codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp) comes with JSPARK Forge, as a plugin server
  76. (version 0.12.1, installed once with `npm` into `~/.claude/jspark-forge/engines/` in the background on the first start, then started by a small launcher). Claude can answer
  77. "who calls X" and "what breaks if I change Y" from a map of your code instead of reading file after file. JSPARK Forge
  78. keeps the map fresh in the background after commits, and adds how fresh each answer is ("as of <commit>"). Switch it
  79. off with `- code-map: off` under `## Settings` in `rules.md`, or `JSPARK_FORGE_CODE_MAP=off`; then these features stay
  80. quiet and everything else works. `/jspark-forge:doctor` reports whether the engine started.
  81. Migrating from an old system listed as a readonly source (below)? Claude can index it as well, as its own map, and
  82. answer "where is X in the old code?". Those answers are labelled **old code**, with the old system's commit; if the old
  83. code changed since it was indexed, Claude is told to index it again first. It is never edited.
  84. ## Skills and briefs for your project
  85. `/jspark-forge:new-skill <name>` creates a project skill from a checked template, and `/jspark-forge:new-brief <name>`
  86. a brief (one job for one helper: goal, what it may and may not change, when it is done). Both are checked for missing
  87. parts. `JSPARK-FORGE.md` in this repo is the whole method in plain words, for any AI tool.
  88. ## Database layout
  89. `/jspark-forge:schema [table]` shows the tables, columns, keys and foreign keys your SQL migration files describe,
  90. with the file and line each came from, the commit it was read at, and the decisions that touch each migration file.
  91. It reads the files in `migrations/`, `db/migrations/`, `supabase/migrations/` or `prisma/migrations/` (one layout per
  92. folder, never merged) and never connects to a database. What it cannot read is marked "uncertain", never guessed.
  93. ## Works best with superpowers
  94. JSPARK Forge does not teach Claude *how* to build. [superpowers](https://github.com/obra/superpowers) by Jesse
  95. Vincent (MIT) does: brainstorm, plan, test first, review, verify. **It is installed together with JSPARK Forge**: it is
  96. a declared dependency, listed in the JSPARK Forge marketplace from its own repository (nothing is copied or changed).
  97. The handoff then shows superpowers plan progress ("Task 3 of 8"). Who decides what: superpowers sets the method,
  98. JSPARK Forge sets the guard rails (resume, block list, decisions, grounding), and your own instruction beats both.
  99. Already had superpowers from another marketplace? Then it is installed twice and its skills show twice; JSPARK Forge
  100. tells you once which copy to remove.
  101. ## Building a UI?
  102. Most of the UI kit arrives by itself (see Install): **frontend-design** and **Chrome DevTools MCP** (so Claude sees
  103. console errors, performance and layout shift) are added once in the background, and **Playwright MCP** (so Claude can
  104. check its own screens) ships with JSPARK Forge and serves tools only in projects with a front end. Only one step is
  105. yours, because it depends on the project. In your own React project, JSPARK Forge says one line, once, if it is
  106. missing:
  107. - **shadcn MCP** (React projects): `npx shadcn@4.23.0 mcp init --client claude`
  108. **Having the skills is not the same as using them.** So in your own project with a front end, JSPARK Forge tells
  109. Claude at every session start, and every helper that builds, plans or reviews, to load frontend-design and your brand
  110. skill before it designs or changes anything a user sees, and to check the result on the real page. Name your brand
  111. skill once with `- brand-skill: <name>` under `## Settings`: in `~/.claude/jspark-forge/rules.md` for every project,
  112. or in a project's `rules.md` for that project. With none named, Claude is told to look for a brand skill among its
  113. skills and to ask you before it chooses colours or a typeface itself. `- ui-skills: off` switches the rule off, and
  114. `/jspark-forge:doctor` says which skills a project uses.
  115. Then give the product its own brand rules and build screens through a checked path:
  116. - **Brand skill:** copy `templates/brand-skill.md` to `skills/brand/SKILL.md` in your project and fill in colours,
  117. type, spacing, components and voice. Claude follows it for anything a user sees and ends with a screenshot check.
  118. - **The `ui` build graph:** `/jspark-forge:build` with the `ui` template runs design direction (strongest model) →
  119. **you approve the look** → build → three checks that must pass (screens match the approved look; no accessibility
  120. violations axe can find, at phone and desktop width, light and dark; Lighthouse scores) → a design review → **your
  121. final approval**. The check files are ready to copy from `templates/ui/`. Choices and sources: `docs/ui-research.md`.
  122. This makes good UI the default path, not luck. The look is still only as good as the direction you approve.
  123. ## Launch list
  124. Keeps scope creep in sight before a launch. `/jspark-forge:launch` creates `.jspark-forge/launch.md` (commit it): a
  125. launch date, 5 blank slots for what must work, a "Critical paths" line and an "After launch" list. Until that file
  126. exists, JSPARK Forge does nothing here. Then, in your own projects only:
  127. - each session starts with the launch date and the open and done items (titles are passed to Claude as data);
  128. - a prompt that sounds like new scope ("can we add", "while we're at it", "add a new feature") gets one line suggesting
  129. `/jspark-forge:scope`, at most every 30 minutes, only when someone is at the keyboard, never at 95 % usage;
  130. - `/jspark-forge:scope` shows the facts first (the list count, "this becomes #8", critical paths touched, and an
  131. estimate only after 10 finished items with dates), then asks: now, after launch, a smaller version, or drop;
  132. - items that arrived with git are listed to you once; every change through JSPARK Forge is announced.
  133. It never blocks anything.
  134. ## When it saves (published list)
  135. 1. Every message from you.
  136. 2. After any tool call that writes or edits a file.
  137. 3. Once a minute while Claude works without writing files (commands, helpers, a new branch).
  138. 4. After any commit Claude makes (a commit you make yourself is noticed at the next save).
  139. 5. When Claude finishes a reply.
  140. 6. Just before the conversation is compacted.
  141. 7. When the session ends.
  142. 8. At **80 %** of context or plan usage (quiet) and at **95 %** (forced, and you see:
  143. *"Usage at 95 %. Handoff saved. Next session, JSPARK Forge shows where you were."*).
  144. 9. When you sign in again during a session. You are told to start a new session and say "resume" if you changed
  145. account. This rests on a notice from Claude Code that has not yet been seen to arrive after `/login`, so do not
  146. count on it.
  147. `/jspark-forge:handoff` saves on demand. A save is written only when there is work to resume.
  148. A crash or a hard limit gives no warning, so at most the last minute of work is lost, and the next session is also
  149. given what the action log holds after the last save.
  150. If the machine itself dies (a power cut, a crash, a killed window):
  151. - **Saves are forced to disk** before they replace the old file, and the handoff before the newest is kept. If the
  152. newest is damaged, the one before it is shown and the doctor says so. If both are, the next session is given what
  153. the action log holds.
  154. - **What is in flight is recorded:** each command, file write or helper that has started and not finished.
  155. - **At the next start** you are told the last session "was cut off, or is still open in another window" (JSPARK Forge
  156. cannot tell the two apart). Claude is told what was half done: what was in flight, which background commands and
  157. helpers are gone (dev servers die with the machine; Claude asks before starting them again), which files written in
  158. the last 2 minutes are now missing, empty or end in NUL bytes, what was logged after the last save, and Claude's last
  159. words. Claude checks before carrying on.
  160. It waits 90 seconds of silence (10 minutes when all that is left is a command in flight, such as a long test run)
  161. before it says so; a session you open again under its own id is checked after 15 seconds. It never changes another window's files, and it stays quiet after a session that ended normally
  162. and in a folder that is not a git repo.
  163. **What a crash can still lose:** the reply Claude was writing, output a program had not yet written to disk, and the
  164. newest log lines if the cut came before they reached the disk. The NUL-byte check is a hint, not proof. Secrets quoted
  165. in what it shows are hidden on a best-effort basis: common shapes, not every secret.
  166. ## What it blocks (published list)
  167. Each needs you to type `CONFIRM <name>` to allow it once (then Claude Code's normal yes/no prompt). When JSPARK Forge
  168. blocks something, Claude is told: *"Do not try an equivalent command; tell the user and stop."*
  169. | Name | Blocks |
  170. |---|---|
  171. | `rm-rf-outside` | `rm -rf`, `Remove-Item -Recurse`, `rd /s` outside the project, and inside it on the project root, `.` or `.git`. On your home folder, the root or a whole drive it is **always refused** |
  172. | `git-force-push-main` | `git push --force` / `--force-with-lease` to `main` or `master` |
  173. | `git-reset-hard` | `git reset --hard`; also `git checkout -- .`, `git restore .`, `git restore --staged .` at the project root |
  174. | `git-clean-fdx` | `git clean -fdx` |
  175. | `git-stash-drop` | `git stash drop`, `git stash clear` |
  176. | `sql-destroy` | `DROP`, `TRUNCATE`, `DELETE` without `WHERE` (psql, mysql, sqlite3, sqlcmd, `Invoke-Sqlcmd`, database MCP tools) |
  177. | `db-write` | A write to a production database: any statement that is not a read (`SELECT`, `WITH … SELECT`, `EXPLAIN`, `SHOW`, `DESCRIBE`) through a database MCP server or a client (`psql`, `mysql`, `sqlite3` on a remote host, `mongosh`, `redis-cli`, `sqlcmd`, `Invoke-Sqlcmd`, `pg_restore -d`), a script file, redirect or pipe into a remote client (its content is unknown), `supabase db push`, `prisma db push` / `migrate deploy` / `migrate reset`, the write tools of Redis, DynamoDB and MongoDB servers, and migration-apply, merge, reset and restore tools of database MCP servers. Reads are never blocked. Production is every database MCP server and every host except localhost, `127.x.x.x`, `::1`, a Unix socket or a local file (a host in an unresolved variable, a `service=` or a `--login-path` counts as production); to mark one as dev, add `- database dev: host:*.dev.internal` (every host in the command must match), `- database dev: mcp:local_postgres` (an exact MCP server name, or `mcp:local_*` for a prefix) or a bare exact host or server name under `## Settings` in **your own** `~/.claude/jspark-forge/rules.md` (a project's `rules.md` cannot, like `disable:`). A seatbelt, not a sandbox: SQL inside a stored procedure is not seen, and JSPARK Forge never connects to a database |
  178. | `secret-files` | Editing `.env*`, key, secret and credential files, also via `>`, `tee`, `Set-Content`, `Out-File` (templates such as `.env.example` and `.env.sample` are allowed) |
  179. | `chmod-wide` | `chmod 777`, `chmod -R`, `icacls … /grant Everyone:F` |
  180. | `pipe-to-shell` | `curl … \| sh`, `iwr … \| iex`, `iex (irm …)` and similar |
  181. | `readonly-source` | Any change to an old system listed under `## Sources` in `rules.md` (below). **Always refused** |
  182. | `forge-state` | Any change to a build graph's running record (`.jspark-forge/state/graph-*`), and running JSPARK Forge's own hooks from the shell. **Always refused**: only JSPARK Forge writes it. A command that only *looks* like it might write the record asks you first (Claude Code's normal yes/no prompt, no CONFIRM) |
  183. | `guest-quarantine` | In a repo you are reviewing, after `/jspark-forge:init --guest`: its install, build, test and run commands (see guest mode). One CONFIRM covers the rest of that session |
  184. Bash, Git Bash, PowerShell and cmd forms are all matched (PowerShell from v0.1.1), also when one shell starts another
  185. (`powershell -Command "…"`, `bash -c "…"`, `cmd /c "…"`). Commands inside `$( )`, backticks, `if` / `for` blocks,
  186. `eval`, `find -exec` and PowerShell script blocks are checked too; a commit message is text, not a command. A command
  187. with two different blocks needs both CONFIRMs.
  188. Add your own in `.jspark-forge/rules.md` ("Confirm" or "Never" lines; commit it to share them with your team), or in
  189. `~/.claude/jspark-forge/rules.md` for every project. Switching a built-in block off (`- disable: chmod-wide`) works
  190. only in that personal file: a project's `rules.md` may come from a repo you cloned, so it can add rules but never
  191. remove one. Blocks also fire inside helper agents.
  192. **Migrating from an old system?** List it under `## Sources` in `rules.md` (`- readonly: ../legacy-app : migrating
  193. from`): Claude can read it but any change to it (edit, write, move, delete, `sed -i`, `git -C … commit`) is always
  194. refused, with no CONFIRM. Remove the line to allow edits. The handoff names it and its commit.
  195. This is a seatbelt, not a sandbox: a deliberately disguised command can get past pattern matching.
  196. ## Install
  197. Needs Claude Code, git and **Node.js 18 or newer**. If Node.js is missing or too old, JSPARK Forge says so when Claude
  198. Code starts (*"JSPARK Forge is off: it needs Node.js 18 or newer…"*) instead of failing silently.
  199. ```
  200. /plugin install jspark-forge --marketplace harishgoswami23/jspark-forge
  201. ```
  202. That is the whole install. superpowers comes with it. On first start JSPARK Forge sets up, by itself, each with its undo:
  203. - **Auto-update.** It switches on updates for the JSPARK Forge marketplace (one key in your `settings.json`, once per
  204. machine), so each new version loads the next time Claude Code starts. Undo: `/plugin`, then **Marketplaces**, then
  205. **jspark-forge**.
  206. - **The code map** (codebase-memory-mcp 0.12.1), as a plugin server. Undo: `- code-map: off` under `## Settings` in
  207. `rules.md`, or `JSPARK_FORGE_CODE_MAP=off`.
  208. - **Playwright** (`@playwright/mcp` 0.0.86), as a plugin server, so Claude can check its own screens. It gives Claude
  209. tools only in a project with a front end. It needs Node.js 20 or newer and stays off on Node.js 18 and 19. Undo:
  210. `- playwright: off` under `## Settings` in `rules.md`, or `JSPARK_FORGE_PLAYWRIGHT=off`.
  211. - **frontend-design and Chrome DevTools**, added once, in the background, from Anthropic's plugin directory. They load
  212. the next time Claude Code starts. Undo: `/plugin uninstall frontend-design@claude-plugins-official` and
  213. `/plugin uninstall chrome-devtools-mcp@claude-plugins-official`.
  214. - **A status line**, only when you have none. Undo: `/jspark-forge:init --undo-statusline`.
  215. Undo for the two servers stops them but does not delete them. They sit in `~/.claude/jspark-forge/engines/` (under
  216. `CLAUDE_CONFIG_DIR` if you set it); delete that folder to remove them. They are installed again on the next start unless
  217. you have switched them off.
  218. To stop the automatic switch-on of auto-update and the two companions, set `JSPARK_FORGE_AUTO_SETUP=off`.
  219. What this adds to your machine, said plainly: each of the two servers is installed once with `npm` into `~/.claude/jspark-forge/engines/`, in the
  220. background, the first time it starts (not inside a hook; the first session may have to be restarted when the install ends), and the two companions are added with `claude plugin install`, once.
  221. Those are the only times JSPARK Forge goes online. On Windows, Defender has been seen to flag the code map engine's
  222. program wrongly (a false positive): allow it, or switch the code map off.
  223. - **Each git project switches on by itself** the first time you open Claude Code in it: a hidden `.jspark-forge/`
  224. folder appears. Commit `rules.md`, `decisions.md`, `launch.md` and `.gitignore` to share them, and build graph files
  225. with their briefs (`graphs/*.md`, `briefs/*.md`). Everything else (handoff, log, the state of a running build graph,
  226. local copies of published pages) stays local and git-ignored. If `.jspark-forge/.gitignore` goes missing, it is made
  227. again at the next session start. Old archived handoffs and the files of repos you reviewed are cleared after 30
  228. days, and old session records (ended over 7 days ago, or untouched for 30) at a session start. Folders that are not
  229. git projects are left alone.
  230. - **Switches** under `## Settings` in `rules.md`: `- notes: off` stops the "add a note" reminder before commits;
  231. `- statusline-segment: off` hides JSPARK Forge's part of the status line; `- short-answers: off` switches off the
  232. short-by-default rule; `- stay-reachable: off` switches off the stay-reachable rule (below); `- fresh-session: off` stops the "start a new session" note; `- ui-skills: off`, `- code-map: off` and `- playwright: off` are described above.
  233. - **Asking a question while Claude works.** A message you send mid-task reaches Claude only when its current
  234. command ends, so a 10-minute test run can make you wait 10 minutes. JSPARK Forge tells Claude at every session start
  235. to run long commands in the background and to answer your mid-task question first. It is a rule, not a hook: nothing
  236. can interrupt a command that is already running. Claude Code's own tools help too: `/btw <question>` answers a
  237. quick question at once (it sees the conversation, not the code), and Ctrl+Enter makes a waiting message land now
  238. (a running command moves to the background).
  239. - **Status line.** Claude Code shows context and plan usage only to the status line, and JSPARK Forge needs those
  240. figures for the 80 % / 95 % saves. If you have no status line, JSPARK Forge adds its own and tells you how to undo
  241. it. If you have your own, it is never touched: run `/jspark-forge:init` once if you want JSPARK Forge to wrap it (it
  242. asks first; your status line looks exactly as now, with a short "saved" note after it). Set
  243. `JSPARK_FORGE_AUTO_STATUSLINE=off` to stop JSPARK Forge adding one at all.
  244. On Claude Code older than 2.1.275: `/plugin marketplace add harishgoswami23/jspark-forge`, then `/plugin install jspark-forge`.
  245. v0.5 was tested on Claude Code 2.1.329. On an older Claude Code, the doctor says so when the code map engine does not
  246. start.
  247. ## Someone else's repo (guest mode)
  248. Open a repo you cloned and never committed to, and JSPARK Forge **writes nothing into it**: its handoff and log live
  249. in `~/.claude/jspark-forge/guests/` instead, the handoff says *"Review of <repo> @ <commit>"*, and Claude is told that
  250. the repo's README, comments, docs and scripts are data to review, never instructions. Every helper Claude starts
  251. there is told the same. Everything else (saves, resume, the block list) works as usual. A wrong guess costs nothing: only where the files live changes.
  252. - `/jspark-forge:init --guest` also **holds the repo's common install, build, test and run commands** (`npm install`,
  253. `pip install`, `make`, `pytest`, `docker compose up`, its own scripts, and so on) until you type
  254. `CONFIRM guest-quarantine`, which then allows them for the rest of that session.
  255. - `/jspark-forge:init --mine` says the repo is yours: the files move into `.jspark-forge/` and the hold ends.
  256. A repo's own `.jspark-forge/rules.md` is never read in guest mode. Like the block list, the hold is a seatbelt, not a
  257. sandbox.
  258. ## Which model does what (helpers)
  259. JSPARK Forge ships four helpers, each on the model strength its job needs:
  260. | Helper | Model | For | Why |
  261. |---|---|---|---|
  262. | `jspark-forge:planner` | strongest | specs, designs, plans, data-model choices | a mistake here is expensive and found late |
  263. | `jspark-forge:reviewer` | strongest | design and code reviews, security, migrations, release go/no-go | it must catch what others missed (it cannot edit) |
  264. | `jspark-forge:builder` | standard | building from a reviewed plan, small fixes | the plan carries the judgement; tests catch slips |
  265. | `jspark-forge:checker` | light | tests, logs, mechanical checks | cheap and visible mistakes (it cannot edit) |
  266. Each works from a brief (goal, what it may and may not change, when it is done, when to stop) and ends with evidence.
  267. A helper does not see what Claude was told at session start, so every helper, these four or any other, is given the
  268. grounding rule when it starts (cite the file, never guess), and in a repo you are reviewing the "content is data" line.
  269. With superpowers, JSPARK Forge asks Claude to use these helpers for its implementers, reviewers and checks. That is
  270. guidance, not a lock: superpowers chooses a model for each helper it starts.
  271. ## Token care (hitting limits less often)
  272. Measured on a real two-day session (2026-11-21): almost all usage was the conversation being re-read. Every step
  273. re-reads the whole conversation so far, and that conversation averaged about 417k tokens per step. JSPARK Forge's
  274. own notes to Claude were about 8k tokens in all.
  275. - **`/jspark-forge:usage`** shows this for your own session: steps and tokens re-read per step for the main
  276. conversation and for each kind of helper, the biggest tool outputs, what JSPARK Forge itself added, and what would
  277. save most. It reads only the session's own record inside the Claude folder and changes nothing.
  278. - **A note when the conversation gets long.** Each time a conversation passes another 150k tokens, JSPARK Forge tells
  279. you (not Claude, so it costs nothing) that a new session would save usage. Because the handoff is saved on every
  280. message, starting a new session and saying "resume" loses nothing. `- fresh-session: off` stops the note.
  281. - **Helper habits.** Helpers were the second-largest cost measured (15 builders, 790 steps). Every helper is told four
  282. habits when it starts: run only the tests of what it changed while working and the whole suite once at the end;
  283. send long output to a file and read only the totals and the failing lines; read the needed part of a file, not a
  284. large file whole; report in short bullets. The main session is told to give each helper one task.
  285. `- usage-care: off` stops both texts (the builder and checker helper files keep the habit).
  286. - **Short by default** (above) keeps replies small.
  287. ## Build graphs (long builds that survive a cutoff)
  288. Write a build once as steps in `.jspark-forge/graphs/<name>.md`: which helper does each step, what it hands to the
  289. next, which steps run side by side, which checks must pass, and where you must act. `/jspark-forge:build <name>` runs
  290. it; JSPARK Forge keeps the record, so a crash, a usage limit or a new session picks up at the running step.
  291. - **Templates:** software, documents, spike, ui, and planned (for when the spec and plan are already written).
  292. - **Shared in git:** the graph file and its briefs (`.jspark-forge/briefs/*.md`). The run state stays on your machine.
  293. - **Your test command:** a template's check says `npm test` only as a placeholder. Set it to your project's own test
  294. command before you trust the graph; `/jspark-forge:build` has Claude do this from your project's files.
  295. - **Builders commit** their step's work on the current branch (no merge, no push): the review step needs those commits.
  296. - **A check that takes longer than 10 minutes** (a long end-to-end suite): one tool call waits 10 minutes at most, so
  297. Claude runs `forge.js graph gate <name> <step>` in the background instead. JSPARK Forge then runs the check's own
  298. commands itself, with no time limit, and records their real exit codes.
  299. - **Better checks (v0.7).** A check step can say more:
  300. ```
  301. ## e2e (gate)
  302. - before: free memory 4 GB
  303. - before: port 5432 open
  304. - before: container app-db running
  305. - run: npx playwright test
  306. - retry: npx playwright test --last-failed
  307. ```
  308. - **`before:`** what must be true before the check starts (free memory, a port open or free, a Docker container
  309. running). If it is not, the check is not started and nothing fails: you are told what is missing, instead of
  310. finding out 20 minutes in.
  311. - **`retry:`** your test tool's own command for "run only what failed". If the full run fails, only what failed
  312. runs again; if that passes, the full command must pass once more. A retry alone never completes a check.
  313. - **Results without reading logs.** Each run is recorded: how many tests passed, failed and were skipped, and the
  314. names of the failing ones (node:test, TAP, jest, vitest, pytest, Playwright, mocha, go test). `graph status` lists
  315. the runs side by side and, while a run is going, says how far it has got ("31 of 63 tests done, 0 failed").
  316. - **Flaky is said out loud.** A test that failed and then passed with no change to the code is named as flaky
  317. every time. It is not counted as fixed.
  318. - **Cost as you go.** Every step ends with the time and tokens used so far.
  319. What JSPARK Forge checks, what it guards, and what it can only ask for:
  320. - **Checked:** the graph is valid before it starts and is fixed for the run; a step's outputs are exactly the declared
  321. ones and are real (a path exists, a commit resolves); a step that needs you completes only on your own typed
  322. `DONE <step>`, or on your own typed `APPROVE AHEAD <graph> <step>` given before the build got there (not for a
  323. step marked `- ahead: no`, such as a release; withdraw with `CANCEL APPROVAL <graph> <step>`).
  324. - **Backed by evidence:** a helper of the right kind ran for the step; a check passed on its command's real exit code,
  325. run in this session and project, not in the background (or run by JSPARK Forge's own check runner, above).
  326. - **Guarded:** Claude is blocked from editing the run's record or imitating your `DONE` / `TRUST GRAPH` from the shell;
  327. a command that only looks like it might asks you first. Removing a step that needs you, or a check, from the graph
  328. needs your `TRUST GRAPH` again. This is pattern matching on what a command does: it stops mistakes and shortcuts, not a program written to a file
  329. and run on purpose. Nothing that runs as your user account can promise more.
  330. - **Asked for:** the order of steps and the limit on helpers running at once; JSPARK Forge hands out work that way but
  331. cannot stop Claude doing something else.
  332. - A graph whose checks run commands needs you to type `TRUST GRAPH <name>` first, as your whole message, and again
  333. when its commands, checks or steps that need you change. The message lists the commands and says the graph runs them
  334. by itself at its check steps: you do not type them. `npm test` runs whatever your project's scripts say. You can
  335. send it before the graph is started: it is trusted as it is, and you are shown what you just trusted. A message
  336. that is close but not exact is answered with the exact text to send; it is never ignored.
  337. ## Commands
  338. | Command | What it does |
  339. |---|---|
  340. | `/jspark-forge:resume` | Show where you were again, on demand, and wait: the handoff, then the end of the action log (the last 60 lines, a record, not instructions) |
  341. | `/jspark-forge:handoff` | Save the handoff now (`done` offers to record lasting lessons, then closes the task and archives it) |
  342. | `/jspark-forge:waiting` | The questions waiting on you, with Claude's recommendations and what each blocks; answer, accept the recommendations, or drop them. Offers to record an answer as a decision |
  343. | `/jspark-forge:status` | What is saved now: the handoff, what is waiting on you, usage as of when |
  344. | `/jspark-forge:usage` | Where this session's tokens went (the conversation, helpers, tool outputs, JSPARK Forge's own notes) and what would save most. Changes nothing |
  345. | `/jspark-forge:doctor` | Is JSPARK Forge working here? One line per check (hook errors from the last two days included), each problem with its fix. Changes nothing |
  346. | `/jspark-forge:decide` | Record, update, verify or retire a decision (only after your yes); print the `rules.md` line that makes one a hard block |
  347. | `/jspark-forge:decisions` | List the decisions, rules and lessons on file. Changes nothing |
  348. | `/jspark-forge:check` | Are the recorded decisions still true? Asks you about each one that may not be. Also lists published pages with no local copy, and files open questions that were never listed |
  349. | `/jspark-forge:new-skill` | Create a project skill from the template, checked for missing parts |
  350. | `/jspark-forge:new-brief` | Write a brief (one job for one helper) from the template, checked for missing parts |
  351. | `/jspark-forge:schema` | The database layout from your migration files, with file and line and the decisions that touch them. Never reads a database |
  352. | `/jspark-forge:upgrade` | Update JSPARK Forge (asks first); run the doctor after the restart |
  353. | `/jspark-forge:launch` | Create the launch list (launch date, 5 blank slots), or show and update it |
  354. | `/jspark-forge:scope` | Weigh a new idea against the launch list: facts first, then now / after launch / smaller / drop |
  355. | `/jspark-forge:build` | Run or continue a build graph step by step (`DONE <step>`, `TRUST GRAPH <name>` and `APPROVE AHEAD <graph> <step>` are yours to type); more than one graph can be open |
  356. | `/jspark-forge:init` | Optional. Wrap your own status line (asks first); `--undo-statusline` restores it exactly; `--guest` / `--mine` for someone else's repo or your own |
  357. ## Uninstall
  358. 1. `/jspark-forge:init --undo-statusline` (restores your status line exactly; if you forget, it keeps working as
  359. before anyway).
  360. 2. `/plugin uninstall jspark-forge`. superpowers stays installed; `claude plugin prune` removes it if nothing else
  361. needs it.
  362. 3. frontend-design and Chrome DevTools stay installed: remove them with `/plugin uninstall <id>` (the ids are in
  363. Install). The auto-update key can be turned off in `/plugin`, under **Marketplaces**.
  364. 4. Optional: delete the `.jspark-forge/` folder in your projects and `~/.claude/jspark-forge/`.
  365. ## Privacy
  366. Your files and the handoff stay on your machine. The handoff holds paths, short text and the last lines of Claude's reply, never file contents. The log
  367. hides likely secrets (keys, tokens, passwords) before writing. After a cut-off session, Claude's last words are read
  368. from the end of that session's transcript, only when that file is inside the Claude home. JSPARK Forge itself sends nothing anywhere. It goes
  369. online only through `npm` (the one-time install of the code map and Playwright servers) and through `claude plugin install`
  370. (once, for the two companions). Those two programs, and the servers they run, are not JSPARK Forge's own code. A hook
  371. never waits on a download.
  372. ## Every hook, documented
  373. Every hook runs `node scripts/forge.js <event>` and fails open: an error never blocks Claude Code. A hook that fails
  374. skips its save or block, so the error is not hidden: `/jspark-forge:doctor` counts hook errors from the last two days,
  375. and a session start says so once a day. Files are written
  376. only in the project's `.jspark-forge/` (or, for a repo you are reviewing, `~/.claude/jspark-forge/guests/<id>/`).
  377. Details per feature: [design-v0.1.md](docs/design-v0.1.md), [design-v0.1.1.md](docs/design-v0.1.1.md),
  378. [design-v0.2.md](docs/design-v0.2.md), [design-v0.3.md](docs/design-v0.3.md), [design-v0.4.md](docs/design-v0.4.md).
  379. Before each release, every promise in the spec is checked against the code and its tests; what is partly built or not
  380. built is listed in [spec-coverage.md](docs/spec-coverage.md).
  381. | Hook (time limit) | What it does | What it writes | Can it block? |
  382. |---|---|---|---|
  383. | SessionStart (10 s; a Node check first, 5 s) | Switches JSPARK Forge on in a git project; shows where you were and waits; the crash check after a cut-off session; questions waiting on you; the grounding rule; the short-by-default rule; decision index; code map freshness; launch list; a running build graph; pages with no local copy; one-time tips; at most once a day each: a hook error was logged, documents left in a temporary folder, a repo with no commits yet | the handoff state, the action log, `state/` files | No |
  384. | UserPromptSubmit (10 s) | Switches JSPARK Forge on if session start missed it; saves the handoff on each message from you; your `CONFIRM <name>`, `TRUST GRAPH <name>`, `DONE <step>`, `APPROVE AHEAD <graph> <step>`, `CANCEL APPROVAL <graph> <step>`; clears a question you answered; offers to record a decision; the launch-scope nudge | handoff, confirm tokens, session state, graph trust and state | No |
  385. | PreToolUse (3 s; shell, edits, the question tool, MCP tools) | The block list (asks or denies); files a question you are asked; the decisions about a file just before Claude edits it; the notes reminder before a commit; notes an allowed command, file write or helper as in flight | waiting list, "already shown" ids, in-flight records | **Yes**: deny or ask |
  386. | PostToolUse (10 s) | Saves after file changes and commits, and once a minute while Claude works; clears the in-flight record; keeps a local copy of a published page; warns about a document written to a temporary folder; offers to record a decision; stale-decision flags; code map freshness on map answers; build graph evidence (gate results, helper tokens); "recorded" notices | handoff, task and session state, map and graph state, `artifacts/` and `artifacts.md` | No |
  387. | PostToolUseFailure (10 s) | Logs the failure; clears the in-flight record; a failed gate command stops a build graph | log, graph state | No |
  388. | Stop (10 s) | Saves the handoff after each reply; files a closing question when there is work; clears what was in flight | handoff, waiting list | No |
  389. | PreCompact (10 s) | Saves before compaction (prints nothing) | handoff | No |
  390. | SessionEnd (1 s) | Marks the session ended | session state | No |
  391. | Notification, sign-in only (10 s) | Shows one line when a sign-in completes during a session, saves the handoff and writes the log, and says how to carry on after a change of account (not yet seen to arrive after `/login`) | the handoff, the action log | No |
  392. | SubagentStart / SubagentStop (10 s) | Tracks running helpers; build graph evidence that a helper ran; at start also gives every helper the grounding rule, in a repo you are reviewing the "content is data" line, and in a front-end project the UI rule | session and graph state | No |
  393. The status line (if you let JSPARK Forge add or wrap it) writes usage figures to `usage/` and shows "saved …" and
  394. "waiting on you". The code map's background refresh (`scripts/map-refresh.js`) is started by hooks and runs
  395. codebase-memory-mcp's indexer; it never blocks a hook.
  396. ## Credits and licence
  397. MIT. Built for Claude Code; not made or endorsed by Anthropic. superpowers is by its own authors under its own
  398. licence.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.