Skip to content

zergzorg/html-plan-review

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

7 Commits
examples
examples
 
 
integrations/codex-skill
integrations/codex-skill
 
 
src/html_plan_review
src/html_plan_review
 
 
.gitignore
.gitignore
 
 
LICENSE
LICENSE
 
 
README.md
README.md
 
 
pyproject.toml
pyproject.toml
 
 

Repository files navigation

HTML Plan Review

MIT License Python >=3.10 No Runtime Dependencies Local First Agent Agnostic Works with Claude Code Works with OpenAI Codex Works with Cursor Works with Windsurf Works with Aider

AI plan review tool, reviewable plan skill, and agent handoff workflow for coding agents.

Reviewable HTML implementation plans with inline comments, block/section comments, local autosave, and handoff prompts for any AI coding agent.

HTML Plan Review is a small, dependency-free local tool for turning implementation plans into interactive browser-review artifacts. It is useful when Markdown plans are not enough and you want a reviewer to point at exact text, code, tasks, sections, or acceptance criteria before an AI coding agent or developer continues the work.

The project is agent-agnostic. It works with any tool that can read local files and follow a prompt, including Claude Code, OpenAI Codex, ChatGPT, Cursor, Windsurf, Aider, GitHub Copilot Chat, Gemini CLI, Cline, Continue, Roo Code, and custom local agents.

Search keywords: AI plan review, plan skill, Claude Code skill, Codex skill, Cursor agent workflow, Windsurf Cascade workflow, Aider planning workflow, reviewable implementation plan, HTML planning tool, agent handoff prompt, coding agent planning.

Features

  • Plan skill workflow for AI coding agents.
  • Reviewable implementation plans for agentic coding workflows.
  • Self-contained HTML plan template with inline CSS and JavaScript.
  • Comment on selected text or code.
  • Comment on a whole block with a compact + button.
  • Comment on a whole section by clicking + on a heading.
  • Persistent yellow highlights for reviewed targets.
  • Pencil edit button for quickly editing existing comments.
  • Right-side comment panel with open/resolved state.
  • Local review server with autosave.
  • Structured review artifacts: JSON, Markdown, saved plan body, and pending handoff request.
  • Status buttons that copy a prompt for any AI coding agent.
  • No runtime Python dependencies.

Quick Start

Clone the repository:

git clone https://github.com/zergzorg/html-plan-review.git
cd html-plan-review

Run the sample plan directly from the source tree:

PYTHONPATH=src python -m html_plan_review.server examples/sample-plan.html

Open:

http://127.0.0.1:4177/plan

Or open the sample directly:

http://127.0.0.1:4177/plan/sample-plan

Installation

Option 1: pipx

pipx install git+https://github.com/zergzorg/html-plan-review.git

Run:

html-plan-review-server examples/sample-plan.html

Option 2: pip

python -m pip install git+https://github.com/zergzorg/html-plan-review.git

Run:

html-plan-review-server path/to/your-plan.html

Option 3: editable local install

git clone https://github.com/zergzorg/html-plan-review.git
cd html-plan-review
python -m pip install -e .

Creating a Plan

Use the template:

src/html_plan_review/assets/html-plan-template.html

Replace these placeholders:

{{PLAN_TITLE}}
{{PLAN_ID}}
{{PLAN_STATUS}}
{{PLAN_CREATED}}
{{PLAN_SCOPE}}
{{PLAN_BODY}}

{{PLAN_BODY}} should be valid HTML. Recommended structure:

<h2>Overview</h2>
<p>Short summary of the change.</p>

<h2>Implementation Steps</h2>
<div class="task">
  <h3>Task 1: Implement the change</h3>
  <p><strong>Files:</strong> <code>src/example.py</code></p>
  <label><input type="checkbox"> Add the implementation.</label><br>
  <label><input type="checkbox"> Add a regression test.</label>
</div>

<h2>Validation Commands</h2>
<pre><code>python -m pytest</code></pre>

Running the Review Server

Serve one plan:

html-plan-review-server docs/plans/active/my-plan.html

Serve multiple plans:

html-plan-review-server docs/plans/active/a.html docs/plans/completed/b.html

Use a custom port:

html-plan-review-server --port 4180 docs/plans/active/my-plan.html

Use a repository root and auto-discover plans in docs/plans/active and docs/plans/completed:

html-plan-review-server --repo-root .

Review Artifacts

In server mode, comments and handoff requests are saved under:

docs/plans/.reviews/<plan_id>/

Files:

  • comments.json — machine-readable review source of truth.
  • comments.md — readable review summary.
  • plan-content.html — saved plan body without utility buttons.
  • request.json — created when a status button is clicked.

comments.json contains comments with:

  • id
  • planId
  • blockId
  • quote
  • text
  • targetType: selection, block, or section
  • resolved
  • createdAt
  • updatedAt

Agent-Agnostic Handoff

The status buttons express reviewer intent:

  • Return for rework
  • In progress
  • Ready to execute
  • Closed

When clicked in server mode, a status button:

  1. Saves comments and plan content.
  2. Writes request.json.
  3. Copies a status-aware prompt to the clipboard.

Paste that prompt into your preferred AI coding agent or developer workflow.

Common compatible workflows:

  • Claude Code — paste the generated prompt and let it read docs/plans/.reviews/<plan_id>/.
  • OpenAI Codex / ChatGPT — paste the prompt in the coding thread and ask it to process the pending review.
  • Cursor — paste the prompt into Agent mode with the repository open.
  • Windsurf — paste the prompt into Cascade with the repository open.
  • Aider — paste the prompt and include the HTML plan/review files as context.
  • GitHub Copilot Chat — paste the prompt in an agent-capable workspace.
  • Gemini CLI — paste the prompt from the repository root.
  • Cline / Continue / Roo Code / custom agents — point the agent at the review directory from the prompt.

Typical search/use-case phrases this project is meant to satisfy:

  • plan skill for Claude Code
  • Codex plan review workflow
  • Cursor plan review tool
  • Windsurf agent planning workflow
  • Aider implementation plan review
  • AI coding agent handoff prompt
  • reviewable implementation plan
  • HTML plan with comments

Direct File Mode

Opening a plan via file:// works, but browsers cannot silently write files to disk. In direct file mode:

  • comments are stored in localStorage
  • JSON/Markdown/HTML export buttons are visible
  • no request.json is created automatically

Use the local server for normal review work.

Agent Integrations

The core project does not require any specific AI product. However, if you want your AI assistant to understand how to generate and manage HTML plans automatically, you should install the provided Agent Skill.

The reference skill instructions live under: integrations/codex-skill/SKILL.md

How to Install and Update the Skill

Because the skill is a Markdown prompt, there are several ways to install and maintain it:

Option A: Ask your AI Agent (Recommended) You can simply give your AI agent the URL to this repository and ask it to install or update the skill. Prompt example:

"Read the skill instructions from https://raw.githubusercontent.com/zergzorg/html-plan-review/main/integrations/codex-skill/SKILL.md and install it into your local skills directory. If I already have an html-plan-manager skill, update it to match the latest logic."

Option B: Git Clone (Best for automatic updates) Clone the repository directly into your agent's skills folder:

git clone https://github.com/zergzorg/html-plan-review.git ~/.agents/skills/html-plan-manager

To update: Just navigate to that folder and run git pull. Your agent will instantly read the newest instructions.

Option C: Manual Copy

  1. Open integrations/codex-skill/SKILL.md
  2. Copy the contents.
  3. Paste it into your agent's system prompt, .cursorrules, or custom instructions. To update: You will need to manually revisit the repository, copy the latest text, and replace your old prompt.

You can add similar prompt/skill files for Claude Code, Cursor, Windsurf, Aider, Copilot Chat, Gemini CLI, or any internal agent. The review artifacts are plain files, so no product-specific API is required.

Security Notes

  • The server binds to 127.0.0.1 by default.
  • Review artifacts are written only to the local filesystem.
  • Do not expose the server to a public network unless you understand the risks.
  • Review comments may contain private project details. Do not commit .reviews/ directories unless that is intentional.

License

MIT. See LICENSE.

HTML Plan Review на русском

AI plan review tool, reviewable plan skill и workflow передачи задач AI-агентам.

HTML Plan Review — это локальный инструмент для интерактивных HTML-планов работ: комментарии к выделенному тексту, комментарии к блокам и разделам, autosave на локальный сервер и структурированный prompt для передачи работы любому AI-агенту.

Инструмент полезен, когда обычного Markdown-плана мало и нужно точно показать, какой фрагмент плана надо исправить, согласовать или взять в работу.

Проект не привязан к конкретному AI-продукту. Он работает с любым инструментом, который умеет читать локальные файлы и выполнять prompt: Claude Code, OpenAI Codex, ChatGPT, Cursor, Windsurf, Aider, GitHub Copilot Chat, Gemini CLI, Cline, Continue, Roo Code и кастомные локальные агенты.

Ключевые запросы: AI plan review, plan skill, Claude Code skill, Codex skill, Cursor agent workflow, Windsurf Cascade workflow, Aider planning workflow, reviewable implementation plan, HTML planning tool, agent handoff prompt, coding agent planning.

Возможности

  • Plan skill workflow для AI coding agents.
  • Reviewable implementation plans для agentic coding workflows.
  • Самодостаточный HTML-шаблон с inline CSS и JavaScript.
  • Комментарии к выделенному тексту или коду.
  • Комментарии к целому блоку через компактную кнопку +.
  • Комментарии к целому разделу через + на заголовке.
  • Желтая подсветка уже прокомментированных областей.
  • Кнопка-карандаш для быстрого редактирования существующего комментария.
  • Правая панель комментариев со статусом open/resolved.
  • Локальный review-server с autosave.
  • Структурированные artifacts: JSON, Markdown, сохраненное тело плана и pending request.
  • Status-кнопки, которые копируют prompt для любого AI-агента.
  • Нет runtime-зависимостей Python.

Быстрый старт

Склонируйте репозиторий:

git clone https://github.com/zergzorg/html-plan-review.git
cd html-plan-review

Запустите пример прямо из исходников:

PYTHONPATH=src python -m html_plan_review.server examples/sample-plan.html

Откройте список планов:

http://127.0.0.1:4177/plan

Или пример напрямую:

http://127.0.0.1:4177/plan/sample-plan

Установка

Вариант 1: pipx

pipx install git+https://github.com/zergzorg/html-plan-review.git

Запуск:

html-plan-review-server examples/sample-plan.html

Вариант 2: pip

python -m pip install git+https://github.com/zergzorg/html-plan-review.git

Запуск:

html-plan-review-server path/to/your-plan.html

Вариант 3: локальная editable-установка

git clone https://github.com/zergzorg/html-plan-review.git
cd html-plan-review
python -m pip install -e .

Создание плана

Используйте шаблон:

src/html_plan_review/assets/html-plan-template.html

Замените placeholder-ы:

{{PLAN_TITLE}}
{{PLAN_ID}}
{{PLAN_STATUS}}
{{PLAN_CREATED}}
{{PLAN_SCOPE}}
{{PLAN_BODY}}

{{PLAN_BODY}} должен быть валидным HTML. Рекомендуемая структура:

<h2>Overview</h2>
<p>Краткое описание изменения.</p>

<h2>Implementation Steps</h2>
<div class="task">
  <h3>Task 1: Implement the change</h3>
  <p><strong>Files:</strong> <code>src/example.py</code></p>
  <label><input type="checkbox"> Add the implementation.</label><br>
  <label><input type="checkbox"> Add a regression test.</label>
</div>

<h2>Validation Commands</h2>
<pre><code>python -m pytest</code></pre>

Запуск review-server

Один план:

html-plan-review-server docs/plans/active/my-plan.html

Несколько планов:

html-plan-review-server docs/plans/active/a.html docs/plans/completed/b.html

Другой порт:

html-plan-review-server --port 4180 docs/plans/active/my-plan.html

Автопоиск HTML-планов в docs/plans/active и docs/plans/completed:

html-plan-review-server --repo-root .

Review artifacts

В server-mode комментарии и handoff-request сохраняются в:

docs/plans/.reviews/<plan_id>/

Файлы:

  • comments.json — машинно-читаемый источник истины по комментариям.
  • comments.md — человекочитаемая сводка review.
  • plan-content.html — сохраненное тело плана без служебных кнопок.
  • request.json — создается при клике по status-кнопке.

comments.json содержит:

  • id
  • planId
  • blockId
  • quote
  • text
  • targetType: selection, block или section
  • resolved
  • createdAt
  • updatedAt

Передача любому AI-агенту

Status-кнопки фиксируют намерение ревьюера:

  • вернуть в переделку
  • в работу
  • готово к исполнению
  • закрыто

При клике в server-mode кнопка:

  1. Сохраняет комментарии и тело плана.
  2. Создает request.json.
  3. Копирует prompt в буфер обмена.

Этот prompt можно вставить в ваш AI-agent workflow.

Совместимые сценарии:

  • Claude Code — вставьте prompt и дайте агенту прочитать docs/plans/.reviews/<plan_id>/.
  • OpenAI Codex / ChatGPT — вставьте prompt в coding thread и попросите обработать pending review.
  • Cursor — вставьте prompt в Agent mode с открытым репозиторием.
  • Windsurf — вставьте prompt в Cascade с открытым репозиторием.
  • Aider — вставьте prompt и добавьте HTML-план/review-файлы в контекст.
  • GitHub Copilot Chat — вставьте prompt в workspace с агентным режимом.
  • Gemini CLI — вставьте prompt из корня репозитория.
  • Cline / Continue / Roo Code / кастомные агенты — укажите агенту review directory из prompt.

Типовые поисковые/use-case формулировки:

  • plan skill for Claude Code
  • Codex plan review workflow
  • Cursor plan review tool
  • Windsurf agent planning workflow
  • Aider implementation plan review
  • AI coding agent handoff prompt
  • reviewable implementation plan
  • HTML plan with comments

Режим открытия файла напрямую

План можно открыть напрямую через file://, но браузер не может незаметно записывать файлы на диск. В таком режиме:

  • комментарии хранятся в localStorage
  • видны кнопки экспорта JSON/Markdown/HTML
  • request.json не создается автоматически

Для обычной работы лучше использовать локальный server mode.

Интеграции с агентами

Основной проект не требует конкретного AI-продукта. Опциональные инструкции для интеграций лежат в:

integrations/

Сейчас добавлено:

  • integrations/codex-skill/SKILL.md — опциональная инструкция для Codex skills.

По аналогии можно добавить prompt/skill-файлы для Claude Code, Cursor, Windsurf, Aider, Copilot Chat, Gemini CLI или внутреннего агента. Review artifacts — это обычные файлы, поэтому product-specific API не нужен.

Безопасность

  • По умолчанию сервер слушает только 127.0.0.1.
  • Artifacts пишутся только в локальную файловую систему.
  • Не открывайте сервер в публичную сеть без понимания рисков.
  • Комментарии могут содержать приватные детали проекта. Не коммитьте .reviews/, если это не осознанное решение.

Лицензия

MIT. См. LICENSE.

About

AI plan review tool and plan skill for Claude Code, Codex, Cursor, Windsurf, Aider and other coding agents

Topics

html review planning cursor ai-planning codex windsurf ai-agent aider coding-agents claude-code agent-workflow implementation-plan plan-skill reviewable-plan

Resources

Readme

License

MIT license
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages