planpack

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

1. 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.
2. Edit planpack/pack.json: set name to planpack (keep) and title to a short human title like "<Repo> Planning".
3. 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.
4. Tell the user how to open it: node planpack/serve.mjs → http://localhost:4770, or open planpack/index.html directly in Chrome/Edge.
5. 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.