AlmogBaku/visual-plan
AlmogBaku/visual-plan has 26 GitHub stars and 1 forks. GitHot measured 0 stars in 24 hours. Last checked 2026-11-17 01:26 UTC. Last push 2026-11-04.
What you can do
- Zoomable map of the target design. One overview diagram; click a box to zoom in (map → zoom → detail), with input, inside, output, and one real example at each level.
- Only your decisions, as controls. Each open decision has its context, one-line options with the recommendation first, and a panel per option (how, gains, costs, effort, reversible). Nothing is preselected.
- Respond and Lock. One button returns every pick, struck row, and comment as a single markdown message. The Lock button appears only when no decision is open.
- Plain words, linted. Prose follows ASD-STE100 Simplified Technical English, and the pack checks it, along with "no code in the plan" and retired terms.
Measured star growth
- in 24h
- 0
- in 7 days
- Collecting history
- in 15 days
- Collecting history
- in 1 month
- Collecting history
Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.
About
Agent skill: the design of one change as one interactive page — zoomable map, your decisions as controls, lock it. For Claude Code, Codex & co.
AIREADME.md
Originalvisual-plan
The design of one change, on one interactive page. See it, answer it, lock it.
⭐ If it saves you from one 10-page plan, star it on GitHub.
Features • Installation • Usage • How it works • Example

Coding agents got good at building. Now they write 10-page plans, and the two decisions that are actually yours are buried on page 7. visual-plan is an agent skill that writes the design for one change as a single self-contained HTML page: a map of the target design you can click into, your open decisions as controls on the part they change, and a lock. The implementation plan (tasks, files, tests) comes after the lock, as a separate document.
Features
- Zoomable map of the target design. One overview diagram; click a box to zoom in (map → zoom → detail), with input, inside, output, and one real example at each level.
- Only your decisions, as controls. Each open decision has its context, one-line options with the recommendation first, and a panel per option (how, gains, costs, effort, reversible). Nothing is preselected.
- Respond and Lock. One button returns every pick, struck row, and comment as a single markdown message. The Lock button appears only when no decision is open.
- Plain words, linted. Prose follows ASD-STE100 Simplified Technical English, and the pack checks it, along with "no code in the plan" and retired terms.
- Built in a subagent. The page builder writes, packs, and lints the page in its own context and returns only a path and the open decisions, so your main session stays clean.
- One file. The output is one self-contained
plan.html: no network, no build, no framework. Open it from disk, host it anywhere, or drop it into an artifact. - Design, not tasks. Built around the target state. No task lists, no code sketches, no who-does-what.
Installation
With the skills CLI, for any supported agent:
npx skills add AlmogBaku/visual-plan
Or clone it into your agent's skills folder. For Claude Code:
git clone https://github.com/AlmogBaku/visual-plan ~/.claude/skills/visual-plan
For Codex and other agents, clone it wherever your agent loads skills from. The entry point is SKILL.md.
[!NOTE] The pack needs only Node.js. There is nothing to
npm install: the one parser it uses (js-yaml) is vendored.
Usage
Ask your agent for it by name, in the session where you are designing a change:
/visual-plan for adding "send later" to the composer
make a visual plan for moving auth to the new gateway
The agent reads the code the change touches and settles what the page will say. Then a subagent (the
page builder) writes plan.yaml, packs it, and fixes every lint error, and hands back only the path and
the list of open decisions. The YAML, the HTML, and the lint rounds never enter your main session's
context. You pick options and leave comments on the page, press Respond, and paste
the markdown it gives you back into the chat; the agent answers there first, then updates the page. When
nothing is open, you lock it, and only then does the implementation plan get written.
[!NOTE] On the bundled example, the page builder reads and writes about 15k tokens (references plus the content file) and returns about 0.2k. Runtimes without subagents build the page inline.
[!TIP] Planning skills can call it too. Any skill that wants an interactive brief can ask visual-plan for the page and name where the locked HTML is saved.
The pack
The agent writes data, never HTML. The pack lints the content file and composes it with the runtime:
node runtime/pack.mjs plan.yaml # → plan.html
node runtime/pack.mjs plan.yaml --out page.html # choose the output file
node runtime/pack.mjs plan.yaml --strict # warnings fail the build
It also accepts plan.json, or plan.js with window.PLAN = {...}.
How it works
A page is a list of blocks. The core blocks are always present, in this order:
| Block | Holds |
|---|---|
| opening | The change and the place, in a few words, and what this page is |
| problem | What breaks, for whom, why now, and only the parts of today's code the plan replaces |
| map | The overview diagram of the target design, as a node tree, with a two-line walkthrough |
| decisions | Settled decisions as a table; open decisions as questions with options |
| goal | The acceptance checks |
| scope | What is out |
Extras appear only when they have content: examples, design reference, terms, traces, constraints, data models, risks and behaviour changes, reused parts.
A page has two states. Open: one or more decisions wait for you, and the Respond sheet has no Lock. Locked: every decision is settled and dated. A plan moves from open to locked by your answers, never by the agent's choice, and a change after the lock reopens it.
The full contract lives in the skill:
SKILL.md what the page is and is not, the steps, the two states
references/sections.md each block: what it holds, and the mistake it exists to prevent
references/nodes.md the node tree and its views: diagram, ports, calls, machine, table, options, section
references/words.md the STE writing rules and the badge vocabulary
runtime/ visualplan.css, visualplan.js, and pack.mjs (lint + compose)
Example
examples/ holds a full synthetic plan: Send later for a made-up mail app, PostBox, with two open
decisions. Pack it and open it:
node runtime/pack.mjs examples/example.yaml
open examples/example.html # xdg-open on Linux

Made by @AlmogBaku · from the talk FML. My Plan Slopped to 10 Pages: Visual Plans to the Rescue