mcpField
M
melech-plan-review

melech-plan-review

github.com/adirdAgent workflows4541 installsUpdated 3w ago
Repository

About melech-plan-review

A skill for presenting a proposed solution as a reviewable plan page rather than a code deep dive. It uses a git-like file tree with highlighted sections, collects reader comments, and waits for an approval, comment, or rejection before proceeding.

Key features

  1. 01Git-like red and green file tree
  2. 02Section markers and concise change descriptions
  3. 03HTML review page generation
  4. 04In-page comment collection
  5. 05Approval, comment, or rejection workflow

Use cases

  1. 01Previewing a proposed change for product readers
  2. 02Collecting feedback before implementation
  3. 03Reviewing a plan that exists only in chat

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/adird/agent-shell-hamelech --skill melech-plan-review

After installing, type/melech-plan-reviewin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

README.md
template.html
evals/
evals.json
evals/fixtures/invoice-reminders/
invoice-reminders-plan-review.json
PLAN.md
evals/fixtures/invoice-reminders/apps/api/src/billing/
invoices.ts
scripts/
review_server.py

Details

From the project README

Plan review

Foresee this solution before they approve it. Show what would change, and what they should expect, as a file tree of git-like red and green lines, as if the PR is ready and they are reviewing the changes tab.

The page is for them or a product reader. They are not looking to deep-dive the code.

Mark each part of a file with a blue @@ section @@ line. Indent the way a diff would. Write a sentence when the behavior is the point. Write a short code line when that is easier to read than the sentence. Do not paste the surrounding implementation.

Open it for review

Copy template.html to <plan-name>-plan-review.html next to the plan file, or in the repo root when the plan lives only in the chat. Fill every {{TOKEN}}.

Serve it in the background with scripts/review_server.py beside this file:

python3 <skill-dir>/scripts/review_server.py <plan-name>-plan-review.html

It opens the page and prints the URL and the review file path. Comments save to <plan-name>-plan-review.json next to the page as the reader writes them.

Wait for the verdict

Ask one question with three options: Approve, Commented, Rejected. Use your question tool if you have one. Otherwise ask in chat and end the turn.

When they answer, read the review file. It has an overall summary and comments. Each comment has a body and the places it points at: file, lines, and the quote they selected. One comment can point at several lines, or at places in several files. A file of null is the page header.

  • Approve: the plan stands. Fold in any comments, then stop the server. Do not start implementing unless they ask.
  • Commented: answer each comment in chat, change the plan where a comment asks, and rewrite the page. Rename the review file to <plan-name>-plan-review-<round>.json, ask them to refresh the tab, and ask again.
  • Rejected: read the comments for why. If there are none, ask what is wrong. Do not rewrite the page until the direction is clear. Stop the server.

Comments

Markdown supported