plan-it - GitLite

KO | EN

gitlite — search

#vue #terminal #rag #data-science #artificial-intelligence #devops #codex #mcp #command-line #react

plan-it

(★ 9)

HTML-first persistent planning skill for Claude Code, Cursor, and 15 other agents. One self-contained plan.html. Survives /clear. SHA-256 attested.

파일 탐색기

ZIP 다운로드

- marketplace.json
- plugin.json
- plan-attest.md
- plan-export.md
- plan-goal.md
- plan-loop.md
- plan-render.md
- plan-status.md
- plan.md
- - 2026-05-19-plan-it-design.md
- anti-slop.md
- EVAL.md
- installation.md
- quickstart.md
- windows.md
- demo-plan-template.html
- demo-plan.attestation
- demo-plan.html
- README.md
- trust-surface-demo.html
- banner.svg
- plan-it-banner.png
- attest-plan.ps1
- attest-plan.sh
- bump-version.py
- export-markdown.py
- init-plan.ps1
- init-plan.sh
- plan-hook.py
- render-plan.ps1
- render-plan.sh
- session-catchup.py
- sync-ide-folders.py
- - SKILL.md
- animation-sandbox.html
- annotated-pr.html
- feature-flag-editor.html
- implementation-plan.html
- incident-timeline.html
- living-design-system.html
- loop.md
- module-map.html
- three-approaches.html
- ticket-triage.html
- weekly-status.html
- - canon-conformance.js
  - canon.js
  - template-runtime.js
- conftest.py
- test_a11y.py
- test_bump_version.py
- test_canonical_script_sync.py
- test_commands.py
- test_export_markdown.py
- test_init_plan.py
- test_integrity_seal.py
- test_node_conformance.py
- test_plan_hook.py
- test_save_handler.py
- test_security.py
- test_session_catchup.py
- test_skill_frontmatter.py
- test_templates_render.py
.gitattributes
.gitignore
AGENTS.md
CHANGELOG.md
CITATION.cff
CLAUDE.md
CONTRIBUTORS.md
LICENSE
pyproject.toml
pyrightconfig.json
README.md
SECURITY.md

# CDN으로 사용하기

jsDelivr

jsDelivr는 공개 GitHub 리포지토리를 별도 설정 없이 CDN으로 즉시 서빙합니다. 버전과 파일을 고르면 웹페이지에 바로 붙일 수 있는 링크와 예시 코드가 만들어집니다.

버전

파일

링크

예시

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<div align="center">
<img src="media/plan-it-banner.png" alt="plan-it - see your plan" width="100%">
</div>

> **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))

[![Version](https://img.shields.io/badge/version-0.2.0-brightgreen)](https://github.com/OthmanAdi/plan-it/releases)
[![Tests](https://img.shields.io/badge/tests-225%2F225_green-brightgreen)](https://raw.githubusercontent.com/OthmanAdi/plan-it/main/tests/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Claude Code Plugin](https://img.shields.io/badge/Claude%20Code-Plugin-blue)](https://code.claude.com/docs/en/plugins)
[![17 IDEs](https://img.shields.io/badge/IDEs-17-orange)](https://raw.githubusercontent.com/OthmanAdi/plan-it/main/)
[![HTML First](https://img.shields.io/badge/HTML-first-c8553d)](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).