plan-review

Files (22)

• SKILL.md
• LICENSE · assets/fluidplan/
• OFL.txt · assets/fluidplan/
• README.md · assets/fluidplan/
• app.css · assets/fluidplan/
• base.css · assets/fluidplan/
• components.css · assets/fluidplan/
• geist-latin-wght-normal.woff2 · assets/fluidplan/
• geist-mono-latin-wght-normal.woff2 · assets/fluidplan/
• tokens.css · assets/fluidplan/
• overview.css · assets/
• review.css · assets/
• review.html · assets/
• format.md · references/
• plan-markdown.mjs · scripts/
• plan-overview.mjs · scripts/
• plan-review.mjs · scripts/
• review-data.mjs · scripts/
• review-server.mjs · scripts/
• tailnet-proxy.mjs · scripts/
• overview.test.mjs · test/
• review.test.mjs · test/

SKILL.md (first lines)

# Plan review

Use this for several decisions that can change a proposed plan. For one question, ask in the conversation. The page is a review surface; the final implementation plan must still follow the `planning` skill.

This skill is based on [Fluidplan](https://github.com/morganhub/fluidplan) by morganhub (MIT licence). Its workflow of decision cards that a person answers in rounds, ending in a `DECISIONS.md` file, is the model for this one. The page styles and fonts in `assets/fluidplan/` are copied from it; see the `README.md` and `LICENSE` there. The CLI, server and review page were written for this repository and do less than Fluidplan's own app.

Run the bundled CLI from the project root with `node ~/.agents/skills/plan-review/scripts/plan-review.mjs`. Node 20 or later is required. If the shared install path is unavailable, locate this skill's `scripts/plan-review.mjs` beside this file.

1. Inspect the request, any source plan, and relevant project files. Identify decisions the person can genuinely make. Write plain language about the consequence of each option.
2. Run `new <id> --title "..."` to create `.plan-review/<id>/plan.json`. Replace its example decision with pages and decisions in [the data format](references/format.md). Use stable IDs. Include enough context, reasons, and option consequences for a person to answer. Run `check <id>` and fix errors.
3. Run `serve <id>` in the background. Then run `node <skill folder>/scripts/tailnet-proxy.mjs <printed URL>` in the background. On a machine running Tailscale it prints a `http://100.x.x.x:<port>/p/...` address that the person's other devices on their tailnet can open; give them that address as well as the local one. Elsewhere it prints a note and exits, and the local URL is the only one. The proxy opens the page to the tailnet, so if your permissions ask for approval, ask the person rather than looking for another route. The browser saves answers on the local machine. Keep the agent turn open when possible. If the browser cannot reach the URL, run `page <id>` and give the person the standalone HTML file. Ask them to copy or download its answers and paste or attach them. Record a downloaded packet with `import <id> <answers.json>`, then run `submit <id>`.
4. Once the person selects **Send answers**, run `digest <id>`. If the agent cannot be woken automatically, the person can say “sent” in the conversation. Treat rewrites and questions as requests for revision. Preserve accepted decisions and all answers that did not need revision.
5. Update `plan.json` for every decision listed under `revise`, adding `"revision": { "round": <next round>, "note": "What changed" }`. Run `check <id>`, then `next <id>`. The page reloads to show the revised cards. Repeat until `digest` has no revisions or unanswered decisions.
6. Run `finish <id>` to write `DECISIONS.md`. Load `planning` and write one implementation-ready Markdown plan based on the settled decisions. Keep that plan in the location and format required by `planning`; do not treat the review JSON as the final plan. Report both paths and the plan overview addresses that `planning` asks for.

The CLI owns `state.json`; the browser or `import` owns `answers.json`; the agent owns `plan.json`. Never silently treat an unanswered card as agreement. Do not use `next --force` or edit state files by hand. The server binds to `127.0.0.1`, and its tokenized URL is local to the current review. The Tailscale proxy listens only on the machine's Tailscale address and passes on only requests made to that address by the review's own page; `tailscale serve` is not used because it needs root.

From tobywise/agent-skills, MIT.

More from tobywise/agent-skills