See how your app actually fits together. An interactive, plain-English map of your codebase, drawn by Claude or Codex.
JavaScript ai-codingarchitecture-diagramclaudeclaude-codeclaude-code-plugincodebase-visualizationcodexcodex-plugindeveloper-toolsonboardingopenaivibe-coding
Blueprints: resolve design review items on the map
Hayden Smithbeff5d631795
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 474c57a..6044769 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -2,7 +2,7 @@## Unreleased-- **Blueprints: plan it before you build it.** Share a PRD, a spec or a description of something you want to build, and Floorplan draws the map of what it would take: every part, file, endpoint and screen, how they connect, and the outside services they rely on. It's marked as planned (dashed cards and a **Blueprint** label), Health becomes a design review of the plan (endpoints anyone could use, decisions the PRD leaves open, loose ends), and each part has **Build this with Claude** (or Codex), a ready request to build it as planned. Switch the Ask bar to **Change** to shape the plan from the map ("also plan out refunds"): the map redraws with the new and changed pieces highlighted, and **Undo** puts it back. Once the code exists, the map can switch to the real code.+- **Blueprints: plan it before you build it.** Share a PRD, a spec or a description of something you want to build, and Floorplan draws the map of what it would take: every part, file, endpoint and screen, how they connect, and the outside services they rely on. It's marked as planned (dashed cards and a **Blueprint** label), Health becomes a design review of the plan (endpoints anyone could use, decisions the PRD leaves open, loose ends), and each part has **Build this with Claude** (or Codex), a ready request to build it as planned. Switch the Ask bar to **Change** to shape the plan from the map ("also plan out refunds"): the map redraws with the new and changed pieces highlighted, and **Undo** puts it back. Design review items can be settled the same way with **Resolve on the map**: an open question just needs your answer. Once the code exists, the map can switch to the real code.## 0.2.2 (2026-10-28)diff --git a/docs/how-it-works.md b/docs/how-it-works.mdindex eb79837..0d70686 100644--- a/docs/how-it-works.md+++ b/docs/how-it-works.md@@ -99,7 +99,7 @@ A blueprint is a map of something that isn't built yet. The AI reads a PRD or a- Health becomes a **design review** of the plan: endpoints anyone could use to change data, endpoints with no decision on who may use them, open questions, and pieces nothing connects to;- every part has **Build this with Claude** (or Codex): a request to build that part as planned, listing its files, endpoints and what it relies on;- Ask answers from the plan and the PRD, since there's no code to read;-- the Ask bar's **Change** switch takes requests like "also plan out refunds": the agent returns the updated plan, the map's server checks it with `plan.mjs` and `build.mjs` (sending problems back once), saves it and redraws the map with the changes highlighted, and **Undo** puts the previous plan back. The agent stays read-only: only the server writes, and only `plan.json`, `architecture.json` and `recent-work.json`.+- the Ask bar's **Change** switch takes requests like "also plan out refunds": the agent returns the updated plan, the map's server checks it with `plan.mjs` and `build.mjs` (sending problems back once), saves it and redraws the map with the changes highlighted, and **Undo** puts the previous plan back. Each design review item's **Resolve on the map** fills in that request for you: an open question just needs your answer. The agent stays read-only: only the server writes, and only `plan.json`, `architecture.json` and `recent-work.json`.Updating a blueprint redraws it from `plan.json`. Once the code exists, `refresh.mjs --from-code` maps the real code instead, and `plan.json` stays.diff --git a/skills/floorplan/SKILL.md b/skills/floorplan/SKILL.mdindex 594b2c8..900c5c8 100644--- a/skills/floorplan/SKILL.md+++ b/skills/floorplan/SKILL.md@@ -29,7 +29,7 @@ If the user wants to plan something they haven't built ("here's my PRD", "I want4. **Write `floorplan/architecture.json`** as for a code map (parts, external nodes for the services and data plan.json names, 1–3 flows for the PRD's main user stories, a tour), with globs covering the planned paths. Plain language for everyone, as in step 4 below.5. **Run `node ${CLAUDE_SKILL_DIR}/scripts/plan.mjs <root>`, then build.mjs** (step 5 below). Fix what they report until both are clean. Skip describe.mjs and recent.mjs: names and descriptions come from plan.json. A blueprint adds no notes to CLAUDE.local.md, since there's no code to look up yet.6. **Show it** with open.mjs (step 8).-7. **Report** (instead of step 8's report): the URL; the shape of the system in 3–5 lines; the stack you chose; your main assumptions; and the design review's questions and warnings. Tell them each part has **Build this with Claude** (or Codex) for a ready request to build just that part; that they can switch the map's Ask bar to **Change** and ask for additions or changes ("also plan out refunds"), and the map redraws with what changed highlighted; that plan.json and architecture.json are theirs to edit or to ask you to change; and that the map stays out of git.+7. **Report** (instead of step 8's report): the URL; the shape of the system in 3–5 lines; the stack you chose; your main assumptions; and the design review's questions and warnings. Tell them each part has **Build this with Claude** (or Codex) for a ready request to build just that part; that they can switch the map's Ask bar to **Change** and ask for additions or changes ("also plan out refunds"), and the map redraws with what changed highlighted (the design review's **Resolve on the map** fills in such a request, so open questions just need their answer); that plan.json and architecture.json are theirs to edit or to ask you to change; and that the map stays out of git.To change a blueprint, edit plan.json and architecture.json and run `refresh.mjs`, which redraws it from plan.json. Once the code exists and the user wants a map of it, run `refresh.mjs <root> --from-code`, then carry on as for a refresh. plan.json stays where it is.diff --git a/skills/floorplan/assets/graph-query.js b/skills/floorplan/assets/graph-query.jsindex 3f4c1e7..489bf0e 100644--- a/skills/floorplan/assets/graph-query.js+++ b/skills/floorplan/assets/graph-query.js@@ -222,7 +222,7 @@ function floorplanChangeInstructions(G) {`Read floorplan/plan.json and floorplan/architecture.json first${src ? `, and ${src} (the PRD it was planned from) when the request touches what the PRD says` : ''}. You can look things up on the map with \`node floorplan/query.mjs find "<words>"\` and \`show <id>\`.`,'plan.json format: { source, stack[], assumptions[], questions[{question, about[]}], files[{path, name, description, screen?, uses[], calls["METHOD /path"], services[node ids], data[node ids]}], endpoints[{method, path, file, name, description, access: public|signed-in|team|webhook|internal, who?, publicBecause?}] }. Every endpoint\'s file is a planned file, every call matches a planned endpoint exactly, and services/data name nodes in architecture.json.','architecture.json: { project, nodes[{id, label, kind, parent?, summary, paths[globs]}], edges[], flows[{id, title, steps[{node, note}]}], tour[] }. Kinds: ui service worker library feature data config test script infra external. External nodes (outside services, the database) own no files. Every planned file must fall under some node\'s paths, so add or widen globs for new folders. Flow and tour steps point at node ids or planned file paths.',- 'Change only what the request needs, the way the rest of the plan is written: same stack and conventions, plain language for everyone, real file paths. Keep every other file, endpoint, id and description exactly as it is. If the PRD or plan already decided something, follow it; record a new choice in assumptions and a real open decision in questions. If the request removes something, remove everything that only it used.',+ 'Change only what the request needs, the way the rest of the plan is written: same stack and conventions, plain language for everyone, real file paths. Keep every other file, endpoint, id and description exactly as it is. If the PRD or plan already decided something, follow it; record a new choice in assumptions and a real open decision in questions. If the request removes something, remove everything that only it used. If it answers one of plan.json\'s questions, remove that question, build the answer into the plan, and record it in assumptions; if it settles who may use an endpoint, set access (and who or publicBecause). Many requests come from the map\'s design review: settle exactly what it names.','Reply with JSON only: {"title", "summary", "plan", "architecture", "changes", "followups"}. plan and architecture are the complete updated files as JSON text, not just the changed parts. changes lists every new or changed file, endpoint ("METHOD /path") or node id with a note on how it serves the request.','Do not edit any files yourself: the map server checks your JSON, saves it and redraws the map.',].join('\n');diff --git a/skills/floorplan/assets/serve.mjs b/skills/floorplan/assets/serve.mjsindex 54bf7ac..49f0b77 100644--- a/skills/floorplan/assets/serve.mjs+++ b/skills/floorplan/assets/serve.mjs@@ -296,11 +296,12 @@ function runAgent(res, send, body) {send('start', { id });child.stdin.end(run.input);let buf = '', stderr = '', done = false;- // writing a whole updated plan takes a while with nothing to report: say so after a quiet spell- let quiet = null;- const hush = () => { clearTimeout(quiet); if (body.mode === 'change' && !done) quiet = setTimeout(() => { if (!done) send('progress', { text: 'Writing the updated plan' }); }, 12000); };+ // working out and writing a whole updated plan has long stretches with nothing to report: say so after a quiet spell+ let quiet = null, said = '';+ const say = (text) => { if (!done && text !== said) { said = text; send('progress', { text }); } };+ const hush = () => { clearTimeout(quiet); if (body.mode === 'change' && !done) quiet = setTimeout(() => say('Working on the updated plan'), 12000); };const out = {- progress: (text) => { if (!done) { send('progress', { text }); hush(); } },+ progress: (text) => { if (!done) { say(text); hush(); } },answer: (data) => { if (!done) { done = true; clearTimeout(quiet); resolve(data); } },fail: (message) => { if (!done) { done = true; clearTimeout(quiet); reject(new Error(message)); } },};diff --git a/skills/floorplan/assets/ui/20-health.js b/skills/floorplan/assets/ui/20-health.jsindex 4d0a4cd..71b4e65 100644--- a/skills/floorplan/assets/ui/20-health.js+++ b/skills/floorplan/assets/ui/20-health.js@@ -55,6 +55,14 @@if (isOpen) closeList();SC.showBoard({ title: issue.title, question: issue.detail, items });}+ // a served blueprint settles review items on the map: the request goes into the Ask bar's Change mode,+ // for the person to finish (an open question needs their answer) or edit, then send+ const here = (issue) => PLAN && !!issue.change && !!SC.canChange?.();+ function resolveHere(issue) {+ if (isOpen) closeList();+ if (!SC.draftChange(issue.change)) { fixWith(issue); return; }+ SC.toast(issue.kind === 'question' ? 'Type your answer, then press Enter' : 'Edit the request if you like, then press Enter');+ }function fixWith(issue) {SC.modal({title: `${FIX} with ${A.name}`,@@ -77,12 +85,13 @@${locText(issue)}<div class="hc-a">${onMap(issue) ? `<button class="btn soft" data-hc-show="${idx}">${SC.iconI('search')}Show on map</button>` : ''}- <button class="btn soft" data-hc-fix="${idx}">${SC.iconI('spark')}${FIX} with ${A.name}</button>+ ${here(issue) ? `<button class="btn soft" data-hc-here="${idx}">${SC.iconI('spark')}Resolve on the map</button>` : `<button class="btn soft" data-hc-fix="${idx}">${SC.iconI('spark')}${FIX} with ${A.name}</button>`}</div></div>`;const bindIssues = (el) => {el.querySelectorAll('[data-hc-show]').forEach((b) => b.addEventListener('click', (ev) => { ev.stopPropagation(); showOnMap(issues[+b.dataset.hcShow]); }));el.querySelectorAll('[data-hc-fix]').forEach((b) => b.addEventListener('click', (ev) => { ev.stopPropagation(); fixWith(issues[+b.dataset.hcFix]); }));+ el.querySelectorAll('[data-hc-here]').forEach((b) => b.addEventListener('click', (ev) => { ev.stopPropagation(); resolveHere(issues[+b.dataset.hcHere]); }));};const headline = () => urgent ? `${SC.plural(urgent, 'thing')} need${urgent === 1 ? 's' : ''} attention` : issues.length ? 'Nothing urgent' : 'No problems found';const breakdown = () => `<div class="hc-sub">${ORDER.filter(count).map((s) => `<span><i class="dot" style="background:${SEV[s].color}"></i>${count(s)} ${SEV[s].word}</span>`).join('')}</div>`;@@ -99,7 +108,9 @@const list = issues.map((i, idx) => [i, idx]).filter(([i]) => i.severity === sev);return list.length ? `<div class="sec"><h3>${h(SEV[sev].group)} <span class="c">${list.length}</span></h3>${list.map(([i, idx]) => issueHtml(i, idx)).join('')}</div>` : '';}).join('');- const foot = issues.length ? `<div class="sec" style="color:var(--text-3);font-size:12px;line-height:1.6">These are automatic hints. “${FIX} with ${A.name}” gives you a request to paste into ${A.app}; ${PLAN ? 'it explains the choice and updates the plan once you decide' : 'it checks the code before changing anything'}.</div>` : '';+ const foot = !issues.length ? '' : `<div class="sec" style="color:var(--text-3);font-size:12px;line-height:1.6">These are automatic hints. ${issues.some(here)+ ? `“Resolve on the map” puts a request in the Ask bar’s Change mode: finish or edit it, press Enter, and ${A.name} updates the plan and redraws the map. Undo puts it back.`+ : `“${FIX} with ${A.name}” gives you a request to paste into ${A.app}; ${PLAN ? 'it explains the choice and updates the plan once you decide' : 'it checks the code before changing anything'}.`}</div>`;return top + groups + foot;}function openList() {diff --git a/skills/floorplan/assets/viewer.html b/skills/floorplan/assets/viewer.htmlindex 64a63b7..385b82d 100644--- a/skills/floorplan/assets/viewer.html+++ b/skills/floorplan/assets/viewer.html@@ -1975,7 +1975,7 @@ function renderChips() {const box = $('#ask-chips');box.innerHTML = askState.context.map((id) => { const i = info(id); return `<span class="chip" title="${h(i.path || '')}"><span class="ico" style="--c:${colorOf(i)}">${icon(iconKey(i))}</span><span>${h(i.name)}</span><button type="button" data-rm="${h(id)}" aria-label="Remove">${iconI('x')}</button></span>`; }).join('');box.querySelectorAll('[data-rm]').forEach((b) => b.onclick = () => { askState.context = askState.context.filter((x) => x !== b.dataset.rm); renderChips(); askInput.focus(); });- askInput.placeholder = !askState.engine ? 'Asking is unavailable' : askState.context.length ? 'Ask about this…' : `Ask anything about ${G.project.name}…`;+ askInput.placeholder = !askState.engine ? 'Asking is unavailable' : askState.mode === 'change' ? (askState.context.length ? 'What should change here?' : 'Ask for a change, e.g. “also plan out refunds”…') : askState.context.length ? 'Ask about this…' : `Ask anything about ${G.project.name}…`;askSend.disabled = !askState.engine;}askInput.addEventListener('keydown', (ev) => { if (ev.key === 'Backspace' && !askInput.value && askState.context.length) { askState.context.pop(); renderChips(); } });@@ -2106,6 +2106,16 @@ window.Floorplan = Object.freeze({closeMenus: () => { closeMenu(); fm.classList.remove('open'); legendEl.classList.remove('open'); },// askingaddAskContext, ask: (text) => { askInput.value = text; submitAsk(); }, askEngine: () => askState.engine,+ // a blueprint's Change mode: whether it's available here, and putting a request in the Ask bar to finish and send+ canChange: () => canChange(),+ draftChange(text) {+ if (!canChange()) return false;+ setAskMode('change');+ askInput.value = text;+ askInput.focus();+ askInput.setSelectionRange(text.length, text.length);+ return true;+ },// chromeaddHeaderButton({ id, label = '', icon: ic, svg, title = '', onClick }) {const b = document.createElement('button');diff --git a/skills/floorplan/references/blueprint.md b/skills/floorplan/references/blueprint.mdindex f1e2435..4f055cf 100644--- a/skills/floorplan/references/blueprint.md+++ b/skills/floorplan/references/blueprint.md@@ -73,7 +73,7 @@ plan.mjs's "calls to planned endpoints" counts each call; the build's "http" lin## Changes from the map-When the map is open through its server (open.mjs), the Ask bar has an **Ask / Change** switch. A change request ("also plan out refunds", "drop the admin page") goes to the same agent, read-only. It replies with the complete updated plan.json and architecture.json, and the server checks them with plan.mjs and build.mjs. If the checks fail, or new files fall under no part, it sends the problems back once. Then it saves the files, redraws the map (open tabs reload), and highlights the new and changed cards as recent work, with **Undo**. The replaced files are kept in `floorplan/.cache/history/`. Changes you make by hand or through this skill work the same way: edit the files and run refresh.mjs.+When the map is open through its server (open.mjs), the Ask bar has an **Ask / Change** switch. A change request ("also plan out refunds", "drop the admin page") goes to the same agent, read-only. It replies with the complete updated plan.json and architecture.json, and the server checks them with plan.mjs and build.mjs. If the checks fail, or new files fall under no part, it sends the problems back once. Then it saves the files, redraws the map (open tabs reload), and highlights the new and changed cards as recent work, with **Undo**. The replaced files are kept in `floorplan/.cache/history/`. Each design review item has **Resolve on the map**, which puts a ready request in Change mode: an open question's request ends with "My answer:" for the person to finish, and the agent then removes the question and builds the answer into the plan. Changes you make by hand or through this skill work the same way: edit the files and run refresh.mjs.## What the design review checks@@ -83,4 +83,4 @@ When the map is open through its server (open.mjs), the Ask bar has an **Ask / C- endpoints no planned screen or service calls;- planned files connected to nothing.-Each has **Resolve with Claude/Codex**, a request to settle it and update the plan.+Each has **Resolve on the map** when the map is served (see above), and otherwise **Resolve with Claude/Codex**, a request to paste into the agent.diff --git a/skills/floorplan/scripts/lib/blueprint.mjs b/skills/floorplan/scripts/lib/blueprint.mjsindex bd3aeb5..7f9e4a6 100644--- a/skills/floorplan/scripts/lib/blueprint.mjs+++ b/skills/floorplan/scripts/lib/blueprint.mjs@@ -147,6 +147,9 @@ export function buildPlanHealth({ graph, scan }) {};const line = (r) => `- ${r.m} ${r.p} (${r.f})${r.name ? ` — ${r.name}` : ''}`;const rebuild = 'Then rebuild the blueprint: run plan.mjs and build.mjs from the Floorplan skill, as its instructions say.';+ // each item also carries `change`: a request to settle it from the map (the Ask bar's Change mode), for the person to finish or edit+ const names = (xs, max = 6) => { const l = xs.slice(0, max).concat(xs.length > max ? [`${xs.length - max} more`] : []); return l.length < 2 ? l.join('') : `${l.slice(0, -1).join(', ')} and ${l.at(-1)}`; };+ const ep = (r) => `${r.m} ${r.p}`;// ---------- who may call each endpoint ----------const accessOf = (r) => bp.access?.[routeKey(r.m, r.p)];@@ -154,6 +157,7 @@ export function buildPlanHealth({ graph, scan }) {const openWrites = routes.map((r, i) => ({ r, i })).filter(({ r }) => accessOf(r) === 'public' && WRITE.has(r.m) && !r.publicBecause);if (openWrites.length) issues.push({id: 'plan-open-writes', kind: 'unprotected-endpoint', severity: 'medium',+ change: `Review who may use ${names(openWrites.map(({ r }) => ep(r)))}: anyone can change data through ${openWrites.length === 1 ? 'it' : 'them'} now. `,title: openWrites.length === 1 ? 'Anyone could change data through one planned endpoint' : `Anyone could change data through ${openWrites.length} planned endpoints`,detail: `The plan lets ${openWrites.length === 1 ? 'this endpoint' : 'these endpoints'} create, change or delete data with no sign-in. That's right for things like signing up or a guest checkout, but worth a second look before building: ${openWrites.length === 1 ? 'it is' : 'they are'} the easiest thing for a stranger to misuse.`,items: openWrites.slice(0, 24).map(({ i }) => 'r:' + i),@@ -164,6 +168,7 @@ export function buildPlanHealth({ graph, scan }) {const unknown = routes.map((r, i) => ({ r, i })).filter(({ r }) => !accessOf(r));if (unknown.length) issues.push({id: 'plan-no-access', kind: 'unprotected-endpoint', severity: 'medium',+ change: `Decide who may use ${names(unknown.map(({ r }) => ep(r)))}, going by the PRD. `,title: unknown.length === 1 ? 'The plan doesn’t say who may use one endpoint' : `The plan doesn’t say who may use ${unknown.length} endpoints`,detail: `Deciding who can use each part of the system now (anyone, signed-in customers, only managers, your own team, another service) is much easier than adding sign-in checks after it's built.`,items: unknown.slice(0, 24).map(({ i }) => 'r:' + i),@@ -177,6 +182,7 @@ export function buildPlanHealth({ graph, scan }) {const items = [...new Set(q.about.map(refOf).filter(Boolean))];issues.push({id: 'plan-question:' + k, kind: 'question', severity: 'medium',+ change: `Open question: "${q.question}" My answer: `,title: q.question,detail: 'The PRD doesn’t answer this, and the answer changes what gets built. Decide it before building the parts it touches.',items, notes: Object.fromEntries(items.map((id) => [id, 'Depends on an open question'])),@@ -190,6 +196,7 @@ export function buildPlanHealth({ graph, scan }) {const unusedRoutes = routes.map((r, i) => ({ r, i })).filter(({ r, i }) => !called.has(i) && !['webhook', 'internal', 'public'].includes(accessOf(r)));if (unusedRoutes.length) issues.push({id: 'plan-unused-endpoints', kind: 'unused-file', severity: 'low',+ change: `Nothing calls ${names(unusedRoutes.map(({ r }) => ep(r)))}. Add the screen or service that should use ${unusedRoutes.length === 1 ? 'it' : 'them'}, or remove ${unusedRoutes.length === 1 ? 'it' : 'them'} if not needed. `,title: unusedRoutes.length === 1 ? 'Nothing in the plan uses one endpoint' : `Nothing in the plan uses ${unusedRoutes.length} endpoints`,detail: `No planned page or service calls ${unusedRoutes.length === 1 ? 'it' : 'them'}. Either a screen that needs ${unusedRoutes.length === 1 ? 'it is' : 'them is'} missing from the plan, or ${unusedRoutes.length === 1 ? 'it isn’t' : 'they aren’t'} needed.`,items: unusedRoutes.slice(0, 24).map(({ i }) => 'r:' + i),@@ -204,6 +211,7 @@ export function buildPlanHealth({ graph, scan }) {const loose = graph.files.filter((f) => !linked.has('f:' + f.p) && !screenFiles.has(f.p) && !routeFiles.has(f.p));if (loose.length) issues.push({id: 'plan-loose-files', kind: 'unused-file', severity: 'low',+ change: `${names(loose.map((f) => f.p))} ${loose.length === 1 ? 'isn’t' : 'aren’t'} connected to anything. Connect ${loose.length === 1 ? 'it' : 'them'} to what should use ${loose.length === 1 ? 'it' : 'them'}, or remove ${loose.length === 1 ? 'it' : 'them'}. `,title: loose.length === 1 ? 'One planned file isn’t connected to anything' : `${loose.length} planned files aren’t connected to anything`,detail: `Nothing in the plan uses ${loose.length === 1 ? 'it' : 'them'}, and ${loose.length === 1 ? 'it doesn’t' : 'they don’t'} use anything. That usually means a connection is missing from the plan.`,items: loose.slice(0, 24).map((f) => 'f:' + f.p),diff --git a/tests/blueprint.test.mjs b/tests/blueprint.test.mjsindex 9ddf3f6..d665ba3 100644--- a/tests/blueprint.test.mjs+++ b/tests/blueprint.test.mjs@@ -80,6 +80,14 @@ test('Health is a design review of the plan', () => {assert.deepEqual(routesOf(issues[3]), ['DELETE /api/walkers/:id']);assert.deepEqual(issues[4].items, ['f:api/src/lib/geo.ts']);assert.match(issues[0].fix, /floorplan\/plan\.json/);+ // each item also has a request to settle it from the map, for the person to finish or edit+ assert.deepEqual(issues.map((i) => i.change), [+ 'Review who may use POST /api/auth/signup: anyone can change data through it now. ',+ 'Decide who may use DELETE /api/walkers/:id, going by the PRD. ',+ 'Open question: "Can owners cancel a walk for free, and up to when?" My answer: ',+ 'Nothing calls DELETE /api/walkers/:id. Add the screen or service that should use it, or remove it if not needed. ',+ 'api/src/lib/geo.ts isn’t connected to anything. Connect it to what should use it, or remove it. ',+ ]);assert.match(buildOut, /DESIGN REVIEW {2}0 important · 3 worth fixing · 2 minor/);});