---

name: plan-it description: HTML-first persistent planning skill. Generates a single self-contained plan.html with interactive phases, drag-and-drop tickets, sliders, mockups, and embedded JSON state. Survives /clear via session catchup, tamper-protected by SHA-256, mirrors across 17 IDEs, ships 10 templates across Thariq's 9 categories, exports back to Markdown on demand. Use when asked to "plan it", "make me an html plan", "show me the plan", "render the plan", or when starting any multi-step task that needs a navigable artifact instead of a markdown wall. user-invocable: true allowed-tools: "Read Write Edit Bash Glob Grep WebFetch" hooks: UserPromptSubmit: - hooks: - type: command command: "if [ -f plan.html ]; then PY=$(command -v python3 || command -v python); HELPER="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/skills/plan-it}/scripts/plan-hook.py"; if [ -z "$PY" ] || [ ! -f "$HELPER" ]; then HELPER=$(ls "$HOME/.claude/skills/plan-it/scripts/plan-hook.py" "$HOME/.claude/plugins/marketplaces/plan-it/scripts/plan-hook.py" 2>/dev/null | head -1); fi; if [ -n "$PY" ] && [ -n "$HELPER" ] && [ -f "$HELPER" ]; then "$PY" "$HELPER" inject --mode summary --lines 30; else echo '[plan-it] plan.html present but helper script not found. Run /plan to re-init.'; fi; fi" PreToolUse: - matcher: "Write|Edit|Bash|Read|Glob|Grep" hooks: - type: command command: "if [ -f plan.html ]; then PY=$(command -v python3 || command -v python); HELPER="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/skills/plan-it}/scripts/plan-hook.py"; if [ -z "$PY" ] || [ ! -f "$HELPER" ]; then HELPER=$(ls "$HOME/.claude/skills/plan-it/scripts/plan-hook.py" "$HOME/.claude/plugins/marketplaces/plan-it/scripts/plan-hook.py" 2>/dev/null | head -1); fi; if [ -n "$PY" ] && [ -n "$HELPER" ] && [ -f "$HELPER" ]; then "$PY" "$HELPER" inject --mode active-phase --lines 15; fi; fi" PostToolUse: - matcher: "Write|Edit" hooks: - type: command command: "if [ -f plan.html ]; then echo '[plan-it] Update plan.html embedded JSON with what you just did (progress_log + phase status). The data lives in <script type="application/json" id="plan-data">. Do not edit the render layer.'; fi" Stop: - hooks: - type: command command: "if [ -f plan.html ]; then PY=$(command -v python3 || command -v python); HELPER="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/skills/plan-it}/scripts/plan-hook.py"; if [ -z "$PY" ] || [ ! -f "$HELPER" ]; then HELPER=$(ls "$HOME/.claude/skills/plan-it/scripts/plan-hook.py" "$HOME/.claude/plugins/marketplaces/plan-it/scripts/plan-hook.py" 2>/dev/null | head -1); fi; if [ -n "$PY" ] && [ -n "$HELPER" ] && [ -f "$HELPER" ]; then "$PY" "$HELPER" check-complete; fi; fi" PreCompact: - matcher: "*" hooks: - type: command command: "if [ -f plan.html ]; then echo '[plan-it] PreCompact: context compaction about to occur.'; echo 'Before compaction completes: ensure plan.html embedded JSON captures recent progress_log entries and current_phase status.'; echo 'plan.html remains on disk and will be re-read after compaction.'; PY=$(command -v python3 || command -v python); HELPER="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/skills/plan-it}/scripts/plan-hook.py"; if [ -z "$PY" ] || [ ! -f "$HELPER" ]; then HELPER=$(ls "$HOME/.claude/skills/plan-it/scripts/plan-hook.py" "$HOME/.claude/plugins/marketplaces/plan-it/scripts/plan-hook.py" 2>/dev/null | head -1); fi; if [ -n "$PY" ] && [ -n "$HELPER" ] && [ -f "$HELPER" ]; then "$PY" "$HELPER" attestation; fi; fi; exit 0" metadata: version: "0.2.0"

plan-it

HTML-first persistent planning. Work like Thariq: ship a single navigable artifact instead of a markdown wall the human will skip.

FIRST: Restore Context

Before doing anything else, check if plan.html exists:

1. If yes: read plan.html, the hooks will auto-inject the active-phase summary on every prompt.
2. Run session catchup to surface any unsynced edits from the previous session:

$(command -v python3 || command -v python) ${CLAUDE_PLUGIN_ROOT}/scripts/session-catchup.py "$(pwd)"

If catchup reports unsynced context: run git diff --stat, read plan.html's embedded JSON, update progress_log, then proceed.

Why HTML, not Markdown

Per Thariq Shihipar's 2026-05-08 essay ("The Unreasonable Effectiveness of HTML"): the format the agent emits is the control surface the human inspects. With Opus 4.7's 1M context, token cost is the wrong metric. Engagement is. HTML preserves spatial relationships, interactivity, density-without-scroll, and visual hierarchy that markdown linearizes away. Sliders + drag-cards + copy-buttons + mockups are first-class.

Where files go

| Location | What goes there | |---|---| | Skill directory (${CLAUDE_PLUGIN_ROOT}/) | Templates, scripts, reference docs | | Your project directory | plan.html (single source of truth) |

Quick start

Before ANY complex task:

1. Pick a template + create plan.html. Run /plan or bash scripts/init-plan.sh <template>. Available templates: implementation-plan, three-approaches, ticket-triage, feature-flag-editor, module-map, annotated-pr, living-design-system, animation-sandbox, weekly-status, incident-timeline.
2. Open it. Run /plan-render or bash scripts/render-plan.sh. The page opens in your default browser.
3. Interact. Drag cards, move sliders, write notes. State persists in the embedded JSON.
4. Update via the JSON, never the render layer. The block <script type="application/json" id="plan-data"> is the source of truth.
5. Optional: lock it. Run /plan-attest to compute and store SHA-256. Any future tamper of plan.html blocks injection until you re-attest.

The core pattern

Context Window = RAM (volatile, limited)
Filesystem     = Disk (persistent, unlimited)
plan.html      = the canonical surface — visual to humans, structured to agents

The JSON data layer travels everywhere. The render layer is the human's UX.

Plan-data JSON schema (v0.2.0)

{
  "schema_version": "0.2.0",
  "plan_title": "...",
  "goal": "...",
  "current_phase": 1,
  "template": "implementation-plan",
  "ownership": "agent",
  "created_at": "ISO 8601",
  "updated_at": "ISO 8601",
  "gate": {"enforce_evidence": false, "require_approval": false},
  "phases": [
    {
      "id": 1,
      "title": "...",
      "status": "pending|in_progress|complete|blocked",
      "approval": {
        "state": "pending|approved|rejected|changes_requested",
        "approach": "...", "blast_radius": ["..."],
        "confidence": "high|medium|low", "cost_estimate": "light|medium|heavy",
        "decided_at": null, "decided_by": null, "note": ""
      },
      "items": [{"text": "...", "done": false, "owner": null}],
      "evidence": [{"command": "...", "output": "...", "exit_code": 0, "probe": "...", "checked_at": "ISO 8601"}],
      "milestones": ["..."]
    }
  ],
  "findings": [...],
  "progress_log": [...],
  "decisions": [...],
  "errors": [...],
  "history": [{"ts": "ISO 8601", "kind": "created|approved|rejected|completed|sealed", "phase": null, "summary": "...", "prev_hash": "...", "hash": "..."}],
  "integrity": {"algo": "SHA-256", "value": null, "sealed_at": null, "scope": "plan-data-v1", "sections": {"phases": "...", "gate": "...", "history": "..."}},
  "attestation_sha256": null
}

Every v0.2.0 field is optional and additive. A pre-0.2.0 plan (no gate, integrity, evidence, or approval) behaves byte-identically to before: no gate, no badge, no new advisories. ownership is optional ("agent", "user", "shared").

Trust layer (v0.2.0)

plan.html is a verified, two-way trust surface, not just a render. Four cohering pieces, all expressed in the flagship implementation-plan template and enforced in the deterministic hook layer:

• Completion evidence with an opt-in gate. A phase carries evidence[] = the command run, its verbatim output, and a re-runnable probe (all three are required for the gate to count it). The Stop hook flags any phase marked complete without an evidence pack. When gate.enforce_evidence is true it blocks the stop (the agent must supply proof or reopen the phase). The gate checks that proof is PRESENT and RE-RUNNABLE; it does not, and cannot, decide the pasted output is genuine. The probe is for the human or CI to re-run. No LLM judges itself done, and the gate never auto-runs a probe (that would be an RCE footgun).
• Approval cards (two-way). Each phase can show a proposed approach, blast_radius, and the agent's confidence/cost_estimate (labelled an estimate, not measured). The human approves or rejects inside the page; the decision and timestamp are written to the JSON and the hook surfaces them so the agent sees them. A rejected phase visually locks every downstream phase.
• Integrity badge (authenticated). /plan-attest writes a SHA-256 content seal into integrity. The browser recomputes it live (vendored SHA-256, offline) and shows verified / edited-since-seal / not-sealed, naming which sections changed. Separately, the existing whole-file sidecar hash still gates hook injection on tamper.
• History (credible). history[] is an append-only, hash-chained log. Every seal and decision is logged.

Honesty boundary (state it, never exceed it): the seal is tamper-EVIDENT, not tamper-proof. It proves the content matches the last seal; divergence is visible. A determined agent can re-run /plan-attest to re-seal forged state, so re-sealing is a deliberate act and every seal is logged in history. Say "verified against seal", never "guaranteed" or "tamper-proof". gate.enforce_evidence and gate.require_approval are meant to be human-set; if sealed, flipping them shows as a gate divergence.

Available commands

| Command | What it does | |---|---| | /plan | Create a new plan.html from a template | | /plan-render | Open plan.html in your default browser | | /plan-attest | Lock the plan with SHA-256 attestation (--show, --clear) | | /plan-status | Print one-line plan status to terminal | | /plan-export markdown | Flatten plan.html → task_plan.md (bidirectional) | | /plan-export json | Export the embedded JSON to plan.json | | /plan-goal | Compose with Claude Code's /goal — derive termination condition | | /plan-loop | Compose with Claude Code's /loop — re-read on every tick |

In-browser Save (v0.1.1)

Six interactive templates (implementation-plan, annotated-pr, feature-flag-editor, incident-timeline, animation-sandbox, ticket-triage) ship a Save button in the header. Clicking it writes the current plan state back to disk:

• Chromium browsers (Chrome, Edge, Opera, Brave) use the File System Access API. First click opens a file picker; subsequent saves overwrite the same handle in place. No download dialog.
• Firefox, Safari, and FSA-disabled environments fall back to downloading a replacement plan.html into the browser's default download directory. Move the file into the project root to replace the original.

Before serializing, the handler pushes the in-memory plan object into the embedded <script type="application/json" id="plan-data"> block so the saved file carries the new state. The render layer clears its containers on every page load, so re-opening a saved file does not double-render the cards baked into the serialized DOM. After a Save, the agent can re-read plan.html and see the user's edits.

The four pure display/export templates (living-design-system, module-map, three-approaches, weekly-status) do not need Save: they have no state to persist.

Critical rules

1. Create plan first

Never start a complex task without plan.html. Use /plan even for "quick" work — it forces a phase breakdown before code.

2. JSON is the source of truth

The render lay