| name | planpack |
| description | Bootstrap and operate a planpack — a portable, git-versioned planning pack (graph wiki + comments) shared between humans and LLM agents, dropped into any repository as a planpack/ folder. Use when the user says planpack, planning pack, plan graph, wants a shared planning/brainstorming space with an LLM, asks to set up planpack in a repo, or asks to resolve plan comments / open questions in a planpack. |
planpack
A planpack is a self-contained planpack/ folder inside a host repository:
markdown/HTML nodes forming a graph wiki, append-only JSONL comment threads,
a derived index/graph.json, and a single-page UI (index.html + optional
serve.mjs). Humans browse and comment in the UI; agents collaborate by
editing the files.
Which workflow?
- Target repo has no
planpack/ folder → Bootstrap below.
- Target repo already has one → Operate below.
Bootstrap
- Copy the entire
template/ directory from this skill folder into the repo
root as planpack/. Verify the copy is complete — it must contain
index.html, parser.js, serve.mjs, cli.mjs, build-index.mjs,
AGENTS.md, README.md, pack.json, and the nodes/, comments/,
index/ folders.
- Edit
planpack/pack.json: set name to planpack (keep) and title to a
short human title like "<Repo> Planning".
- Verify the setup works before telling the user it is ready:
node planpack/cli.mjs list → must print a JSON array of the seed nodes.node planpack/cli.mjs reindex → must report writing index/graph.json.git check-ignore planpack (in a git repo) → must match nothing; if the
pack is ignored, tell the user versioning is the point and ask before
touching .gitignore.- If Node ≥18 is unavailable, say so: the UI still works by opening
planpack/index.html directly in Chrome/Edge, but serve.mjs/cli.mjs
need Node. Fix or flag this rather than skipping verification silently.
- Tell the user how to open it:
node planpack/serve.mjs → http://localhost:4770,
or open planpack/index.html directly in Chrome/Edge.
- The template ships with tutorial nodes tagged
seed. Offer the user a
choice, recommending the first option:
- Map the repo now (recommended) — give the user a mental model of the
codebase they can browse immediately: run the clear the seeds and map
this repo procedure defined at the end of
planpack/AGENTS.md (explore
the host repo, then write a welcome note, 2–5 code-area nodes with
refs into the most important modules, and one open question asking
where to focus next — planpack/cli.mjs create handles the file format
and reindexing for you).
- Keep the tutorial seeds — the user explores the seeded pack first and
can ask for the repo mapping at any time later.
Do not add anything outside the planpack/ folder.
Operate
Read planpack/AGENTS.md in the target repo and follow it — it is the canonical
protocol (node schemas, the comment lifecycle, the inbox, housekeeping). In short:
- Prefer the deterministic CLI over hand-editing files. It validates input,
generates ids/timestamps, and reindexes after every write:
node planpack/cli.mjs help lists all commands. For multiple writes, pipe
ops as JSON to node planpack/cli.mjs batch — one process, one reindex,
no shell-quoting issues.
- Your inbox =
node planpack/cli.mjs inbox (unresolved root comments in
comments/*.jsonl + question nodes with status: open).
- Resolve by doing the actual work, then
cli.mjs reply and cli.mjs resolve.
Never rewrite comment files — append only.
- Nodes:
cli.mjs create / update / get / list / search. After any hand edit,
regenerate the index: node planpack/build-index.mjs.
