.html plan, not a to-do list.
implementation-plan turns an objective, a GitHub/GitLab issue, or a markdown
plan into a single self-contained, interactive HTML document — steps, tests, acceptance
criteria, effort estimate, and copy-paste implement prompts, all portable in one file.
It plans; it does not implement (until you tell it to).
One HTML file with everything a plan needs, readable in any browser with no external CSS, no CDN, and no build step. Checkbox and status state live as HTML attributes, so progress travels with the file across machines, browsers, and git.
Context, a prominent objective, numbered step cards (action + why + expandable verify), a Tests section, interactive acceptance criteria, end-to-end verification, and a completion checklist.
An auto-generated file-tree, an auto-derived effort badge, and three ready-to-paste prompts — implement, goal, and (when warranted) workflow.
Plan status, type, effort, repo, paths, and prompts are embedded as <meta>
tags so the plans gallery and hooks can read the file without parsing prose.
Native checkboxes, a Save-as-PDF button, per-prompt Copy buttons, and a progress
indicator. Minimal JS only enhances; the checked attribute is the source of truth.
Explicit, with full flag control. $ARGUMENTS carries
the objective and flags.
/plan-agent:implementation-plan add dark mode toggle --quickAuto-activates when you ask to “create a plan document” or “generate an HTML plan.” Flags can’t be passed, so it runs the full workflow (Clarify + Align + Interview) by default and infers the objective from context.
Both paths apply the same input detection: issue references, an existing
.html plan to revise, or a .md file to convert.
The first non-flag token decides what the skill is working from. Detection order
is issue-ref → .html → .md → plain objective.
All non-flag text becomes the objective. Empty on the command path → it asks once via
AskUserQuestion.
A GitHub/GitLab URL, bare #42, or a plain integer. Fetched via gh/glab;
title → objective, body → context, labels → --type hint, URL → frontmatter. Falls back
gracefully if the CLI call fails.
A .html token targets an existing plan to extend. Path-safe (basename only, resolved
under plan roots); reads the <title> as the objective fallback.
A .md token enters conversion mode — maps sections 1:1 into the HTML skeleton, carries
frontmatter over, and implies --no-clarify --no-align --no-interview since committed
markdown is pre-validated.
Command-path only. Absent flags fall back to smart defaults — --type is
inferred from the objective’s leading verb; the skip flags are opt-in and never inferred.
| Flag | Effect |
|---|---|
| --quick | Shorthand for --no-clarify --no-align --no-interview. Skips Clarify (1), Align (5), Interview (5b), and Explore (0b). |
| --no-clarify | Skip Step 1 Clarify only. |
| --no-align | Skip Step 5 Align only. |
| --no-interview | Skip Step 5b Interview only. |
| --workflow | Always emit a workflow prompt, bypassing the complexity heuristic. |
--type <kind> | Preset frontmatter type: feature · fix · refactor · docs · chore. |
--template <name> | Skeleton variant. Only default ships today; minimal/adr/spike are planned. |
--dir <path> | Override directory resolution; write the plan here. |
--priority <level> | Write priority: frontmatter — low · medium · high · critical. |
--type: create/add/build/implement → feature ·
fix/repair/patch/resolve → fix · refactor/rename/extract/move/convert → refactor ·
document → docs · anything else → chore.
A real, ordered pipeline. Some steps are conditional (issue ref present, flags set); the numbering reflects the sequence the skill actually walks.
If in plan mode, silently call ExitPlanMode first — writing an HTML file is a filesystem
mutation the harness would otherwise force to markdown, defeating the skill’s whole guarantee.
When an issue reference was detected, fetch it and inject title, body, labels, and URL as planning inputs.
skipped when no issue referenceRead the codebase — Glob for files, Grep for symbols, Read for architecture — proportional to scope, to ground the plan in what actually exists.
skipped when --quickResolve ambiguous requirements via AskUserQuestion; use WebSearch/WebFetch
when research would strengthen the plan. Well-specified requests skip it.
Resolve the plans directory (settings precedence, --dir override, docs/plans/ fallback),
pick a verb-target filename, and compute the implement, goal, workflow prompts + effort level.
Embed status, effort, type, created, repo-name, file/path, and prompt <meta> tags in the
<head> — plus optional priority and issue tags, and any extraFrontmatter from settings.
Enforce the verb-target kebab-case filename before writing. Backed by the
validate-plan-filename PostToolUse hook.
Batched AskUserQuestion confirming each step maps to the objective — step-to-objective
alignment, not final approval.
Stress-test the draft across 1–3 rounds scaled by complexity, with a mandatory UI/accessibility round when UI signals appear. See §06.
skipped when --quick / --no-interviewClassify Tier 1 vs Tier 2 and populate the Tests section, always including the objective-verification test. Never skipped by any flag. See §07.
Keep the three status representations in sync — <html data-status>,
<meta>, and the visible badge — as the plan advances todo → in-progress → completed.
Deliver + verify rendering: spin up a local HTTP server, screenshot via the browser MCP, and send the
file with SendUserFile. Falls back to file delivery in headless environments. Mandatory.
Ask what’s next: implement now, run as workflow, review the plan (foreground or background), edit, or exit. See §08 for the implement path’s three gates.
Complexity detection sets the depth; every question references specific plan details — no generic prompts. A UI override forces Round 2 whenever the plan touches React/Vue/Svelte, JSX/CSS/HTML, or UX terms.
| Scope | Rounds | Covers |
|---|---|---|
| Short / focused 1–2 files | 1 | Technical & trade-offs — the most uncertain decision, build-vs-buy, perf/data model, integration points. |
| Medium UI + logic, or 2 domains | 1 + 2 | Adds 2a UI/UX & flows and 2b Accessibility & semantic (keyboard, ARIA, WCAG 2.1 AA, semantic HTML). |
| Complex architecture, 3+ domains | 1 + 2 + 3 | Adds edge cases & best practices — failure modes, race conditions, regression risk, open questions. |
After the rounds, the skill summarizes confirmed decisions and surfaced concerns, then offers to fold the findings back into the plan before moving to Tests.
Tier is chosen by what the steps actually touch, never by the type: field. A
chore that changes import paths is Tier 1; a chore that moves docs is Tier 2.
Choosing “Implement now” lifts the scope constraint for that session and walks each step,
then runs three mandatory gates in order before a plan can be marked completed.
Verify each #criteria-list checkbox against the real codebase and add the checked
attribute only when met. Unverifiable items are surfaced for a keep/leave decision.
Run the objective-verification test plus the plan’s Verification steps. On failure, a bounded fix-and-re-verify loop (up to 3 attempts) then a user choice: keep trying, mark in-progress, or mark completed anyway.
Confirm all steps done, all criteria checked, status set. Incomplete items populate a Completion Report
(<dt>/<dd>) naming the exact step or criterion and why. Then commit source + plan together.
/workflows-compatible prompt for
parallel subagents · Review the plan launches the seven-reviewer review-plan Agent Team
(foreground or background) · Edit loops back for revisions · Exit leaves the plan at todo.
A short Read and implement all steps… line; its Copy button actually builds a richer,
status-aware prompt from live DOM state via buildImplementPrompt().
An outcome-driven sibling — Achieve this goal: … — giving the implementer latitude to deviate
when a better path to the same outcome exists. Never omitted.
Emitted with --workflow, or automatically when the plan touches 4+ files across 2+ top-level
dirs. Repetitive per-file changes, parallelizable steps, and cross-checking are not auto-detected — opt in
explicitly. Otherwise the block is removed entirely.
Deterministic from step count, distinct file count, and interview tier → Low / Medium / High. Drives a
coloured badge, a meta-row chip, and the data-effort attribute.
Both are colour-coded in the rendered plan. Status is carried in three synced places; effort is auto-derived and never author-set.
Pure CSS / inline SVG only — no CDN, no <canvas>, no charting library. The
file-tree is auto-generated; the rest are opt-in and deleted (markup + sidebar link) when unused.
| Component | Use when the plan… | Mode |
|---|---|---|
| File-tree | references any file — scanned from step text, badged new / modified / deleted / generated | auto |
| Flow / pipeline | has a process, data flow, or architecture sequence | opt-in |
| Comparison grid | weighs a 2–3-way trade-off (kept/dropped, before/after) | opt-in |
| Bar chart | shows a distribution or relative magnitudes | opt-in |
| Data table | maps structured data (file→change, option→behaviour) | opt-in |
Accessibility is baked in: tables carry a <caption> and scoped headers, charts show a visible
numeric value plus a descriptive aria-label, and file badges use a text label alongside colour.
<meta> tagsMachine-readable metadata the plans gallery and hooks consume without reading prose.
<!-- always present -->
<meta name="plan-status" content="todo | in-progress | completed">
<meta name="plan-effort" content="low | medium | high">
<meta name="plan-type" content="feature | fix | refactor | docs | chore">
<meta name="plan-created" content="YYYY-MM-DD">
<meta name="plan-repo" content="<repo-name>">
<meta name="plan-file" content="<basename>.html">
<meta name="plan-path" content="docs/plans/<basename>.html">
<meta name="plan-implement" content="Read and implement all steps…">
<meta name="plan-goal" content="Achieve this goal: …">
<!-- conditional -->
<meta name="plan-workflow" content="Run a workflow to implement…"> // when generated
<meta name="plan-issue" content="<issue-url>"> // when seeded from an issue
<meta name="plan-priority" content="low | medium | high | critical"> // when --priority setThe skill produces a plan document. It does not implement anything — until you pick “Implement now” at Step 8, which lifts the constraint for that session alone.
plansDirectory (or docs/plans/).