<div align="center">
<img src="media/plan-it-banner.png" alt="plan-it - see your plan" width="100%">
</div>
# plan-it
> **Stop reading walls of markdown. Start *seeing* your plan.**
> An HTML-first planning skill for Claude Code, Cursor, and 15 other agents. One file. Survives `/clear`. SHA-256 attested.
```
npx skills add OthmanAdi/plan-it
```
Or from npm: `pi install npm:plan-it` ([package](https://www.npmjs.com/package/plan-it))
[](https://github.com/OthmanAdi/plan-it/releases)
[](tests/)
[](https://opensource.org/licenses/MIT)
[](https://code.claude.com/docs/en/plugins)
[](#supported-platforms-17)
[](https://claude.com/blog/using-claude-code-the-unreasonable-effectiveness-of-html)
## The pitch
Markdown plans don't get read.
You write a phase breakdown. You drop a hundred bullets. The agent skims. You skim. By phase 3 nobody knows what was decided in phase 1. By phase 5 the plan is a wall of text nobody opens.
plan-it gives you a single `plan.html` instead. Tabs. Drag-cards. Sliders. Mockups. Copy-as-markdown when you need it back as text. Embedded JSON as the canonical state. Open it in your browser. Drag a card. Watch a checkbox. Read it like a dashboard, not a thread.
It survives `/clear` because the file lives on disk and the hooks re-inject the active phase on every prompt. It's tamper-protected by SHA-256. It ships across 17 IDEs day 1.
```
/plan implementation-plan
/plan-render
```
Two commands. You're in.
## A verified, two-way trust surface (v0.2.0)
84% of developers use AI coding tools; 3% highly trust the output. The bottleneck is verification, not generation. A plan only matters if it is read, trusted, and steerable. So plan.html does four things, all inside the one file you already open:
- **Completion is shown, not claimed.** A phase reads `complete` with an evidence pack attached: the command that ran, its verbatim output, and a re-runnable probe. The Stop hook flags a `complete` phase with no evidence, and blocks it when you opt in. The gate checks that proof is present and re-runnable. It does not decide your output is genuine; the probe is there for you or CI to re-run.
- **Integrity is visible.** `/plan-attest` writes a SHA-256 content seal. The page recomputes it live in your browser and shows a badge: verified against seal, edited since seal (naming what changed), or not sealed. It is tamper-evident, not tamper-proof: a re-seal of edited state is possible and is logged in the plan history, so it is a visible act.
- **You approve inside the artifact.** Each phase can show a proposed approach, its blast radius, and the agent's confidence and cost estimate. You approve or reject in the page; the decision flows back to the agent through the embedded JSON. A rejected phase locks everything downstream.
- **There is a chain of custody.** An append-only, hash-chained history logs every seal and decision.
This is expression and guarantee on top of what plan-it already had (HTML, embedded JSON, SHA-256 attestation, hooks), not a rebuild. The trust UI ships in the `implementation-plan` template; see [`examples/trust-surface-demo.html`](examples/trust-surface-demo.html). The honesty bar and what the eval does and does not measure are in [`docs/EVAL.md`](docs/EVAL.md).
## What you get
10 ready-to-use HTML templates across all 9 categories Thariq named in [the gallery](https://thariqs.github.io/html-effectiveness):
| Template | What it does |
|---|---|
| **implementation-plan** | Phases + mockups + data-flow diagram + risk table |
| **three-approaches** | Side-by-side approach comparison with pros/cons/effort meters |
| **ticket-triage** | Drag-and-drop Now/Next/Later/Cut board with markdown export |
| **feature-flag-editor** | Grouped toggles + dependency warnings + diff-copy |
| **module-map** | Inline SVG architecture diagram with pan/zoom |
| **annotated-pr** | Unified diff with margin annotations + severity tags |
| **living-design-system** | Color/type/spacing/component variants, click to copy CSS var |
| **animation-sandbox** | Sliders for duration + easing, copy-as-CSS button |
| **weekly-status** | Shipping/Slipping/Blocked + sparkline of slip days |
| **incident-timeline** | Minute-by-minute post-mortem with log excerpts + action items |
Plus a CLI to bring them up: `/plan`, `/plan-render`, `/plan-attest`, `/plan-status`, `/plan-export markdown`, `/plan-goal`, `/plan-loop`.
## Why HTML, not markdown
[Thariq Shihipar called it](https://claude.com/blog/using-claude-code-the-unreasonable-effectiveness-of-html) on 2026-05-08:
> "The format the agent emits is the control surface the human inspects, not a wrapper around it."
With Opus 4.7 at 1M tokens, the cost argument for markdown is dead. The constraint that's left is engagement. A plan only matters if it gets read. HTML preserves spatial layout, interactivity, comparisons, mockups, all the things markdown linearizes away.
plan-it is the persistent skill for that thesis. Web-artifacts-builder makes one-shot artifacts. Playground makes throwaway tools. Frontend-design produces components. None of them survive `/clear`. None mirror to 17 IDEs. None ship SHA-256 attestation. plan-it does all three.
## What plan-it ships
| Capability | plan-it |
|---|:---:|
| Persistent across `/clear` | yes |
| Multi-IDE adapters | 17 |
| SHA-256 tamper attestation | yes |
| Live in-browser integrity badge | yes |
| Completion-evidence gate (opt-in blocking) | yes |
| In-artifact approval gates (HITL) | yes |
| Append-only hash-chained history | yes |
| Lifecycle hooks | 5 |
| HTML output | yes |
| Planning-specific templates | 10 |
| Single-file offline (no CDN) | yes |
| Bidirectional Markdown export | yes |
| Parity-locked version bumper across IDE mirrors | yes |
| Pytest coverage | 225 green |
## The thesis we ship on
> "HTML is the new markdown. I've stopped writing markdown files for almost everything and switched to using Claude Code to generate HTML for me."
> [Thariq Shihipar](https://x.com/trq212/status/2052811606032269638), Anthropic engineer
plan-it is the persistent, multi-IDE planning skill for the era that line opened.
## Install
### Claude Code plugin marketplace
```
/plugin marketplace add OthmanAdi/plan-it
/plugin install plan-it@plan-it
```
### Any agent-skills-compliant IDE
```
npx skills add OthmanAdi/plan-it
```
### Pi Coding Agent (npm)
```
pi install npm:plan-it
```
### Manual
```
git clone https://github.com/OthmanAdi/plan-it
ln -s "$PWD/plan-it/skills/plan-it" ~/.claude/skills/plan-it
```
## Supported platforms (17)
**Hooks lifecycle enabled** (auto re-inject on every prompt, session catchup, SHA-256 attestation, PreCompact flush):
Claude Code · Cursor · Codex · GitHub Copilot · Mastra Code · OpenCode · Hermes · CodeBuddy · Factory Droid · Gemini CLI · Kiro
**Standard agent-skills support**:
Continue · Pi Agent · OpenClaw · Antigravity · Kilocode · AdaL CLI
11 byte-identical script + template mirrors plus the canonical `skills/plan-it/` bundle. SKILL.md is English across all mirrors; localizations (ar/de/es/zh/zht) are on the roadmap, shipped as real translations rather than English-body placeholders when ready.
## Quick demo
```bash
git clone https://github.com/OthmanAdi/plan-it && cd plan-it
bash scripts/init-plan.sh implementation-plan
bash scripts/render-plan.sh
```
The browser opens. The plan is live. Drag a card. Toggle a checkbox. Click **Copy as Markdown**. Paste it anywhere.
Want it locked? `bash scripts/attest-plan.sh`. Now any byte change to `plan.html` blocks hook injection until you re-attest. Trust boundary on disk.
Want it back as text? `python scripts/export-markdown.py`. You get `task_plan.md`, `findings.md`, `progress.md`, exact same shape as planning-with-files. Hand-edit anywhere.
## Architecture
```mermaid
flowchart LR
U[User prompt] --> CC[Claude Code]
CC --> HK[/SKILL.md hooks/]
HK --> PH[plan-hook.py]
PH --> READ[(plan.html<br/>embedded JSON)]
PH --> SHA{SHA-256<br/>match?}
SHA -->|verified| INJ[Inject plan-data block]
SHA -->|tampered| BLK[Block injection]
INJ --> CC
```
In 80 characters:
```
plan.html = <style> + <script type=application/json id=plan-data> + <script>
```
JSON is the source of truth. The render layer is derived. Diffs are clean. The agent reads the JSON. The human sees the dashboard.
Hooks re-inject the active phase on every prompt with `===BEGIN PLAN DATA===` markers (never `---`, because that breaks Claude Code's skill loader, [carried lesson from planning-with-files v2.38.1](https://github.com/OthmanAdi/planning-with-files/releases/tag/v2.38.1)).
## Round-trip with markdown
```mermaid
flowchart LR
PH[(plan.html<br/>embedded JSON)] -->|/plan-export markdown| TP[task_plan.md]
PH -->|/plan-export markdown| FN[findings.md]
PH -->|/plan-export markdown| PR[progress.md]
TP -.hand-edit.-> PH
FN -.hand-edit.-> PH
PR -.hand-edit.-> PH
```
For chained agents, git-committed specs, or anyone who wants source text back, `/plan-export markdown` flattens the JSON into a planning-with-files compatible trio (`task_plan.md` + `findings.md` + `progress.md`). The HTML stays canonical; the markdown is a derived view. Edit either side, the JSON is the contract.
## Token-cost honesty
HTML uses about 2-3x the tokens of markdown for the same plan. On Opus 4.7's 1M context that's nothing. For chained agents or git-committed specs, run `/plan-export markdown`, the JSON round-trips clean to three planning-with-files-compatible files.
## Built on the shoulders of
- **planning-with-files** ([OthmanAdi](https://github.com/OthmanAdi/planning-with-files)), the markdown predecessor. Hook lifecycle, session catchup, SHA-256 attestation, parity-locked bumper, 17-IDE distribution all carry over to plan-it.
## Status
- **v0.2.0** (2026-06-13). Verified, two-way trust surface: completion evidence with an opt-in blocking gate, a live in-browser integrity badge (vendored offline SHA-256, conformance-tested against the Python sealer), in-artifact approval gates that lock downstream phases on reject, and an append-only hash-chained history. Schema 0.2.0 (additive). Trust UI ships in `implementation-plan`. 225/225 pytest tests green. See `docs/EVAL.md` for the honesty bar.
- **v0.1.1** (2026-05-22). Save button, idempotent re-render, sanitizer for agent-side injection, and issue #3 fix (literal `</script>` substring in a JS comment was killing tab rendering). 207/207 pytest tests green. 15-file parity-locked. Sync-verify clean.
- **v0.1.0** (2026-05-20). First cut. 120/120 pytest tests green.
- Roadmap: real localizations (ar/de/es/zh/zht), MDX output mode, team mode, here.now publish integration.
## License
MIT. See [LICENSE](LICENSE).
Built by [Ahmad Othman Ammar Adi](https://github.com/OthmanAdi).