.claude-plugin/
plugin.json the plugin: name, version, author
marketplace.json this repo as its own one-plugin marketplace
icon.png
.codex-plugin/
plugin.json the same plugin for Codex (same skill, same version)
icon.png
.agents/plugins/
marketplace.json this repo as a Codex marketplace
skills/floorplan/
SKILL.md the workflow Claude and Codex follow
agents/openai.yaml how Codex lists the skill
workflow.json the same steps as SKILL.md, as data, for running without an agent session
references/ formats and style guides Claude reads while working
schema.md architecture.json and recent-work.json
choosing-boundaries.md how to carve a codebase into a good map
writing-descriptions.md plain-language names and descriptions
blueprint.md plan.json, for a map planned from a PRD
scripts/ Node.js, no dependencies; Claude runs these
status.mjs is there a map, and how stale is it (runs when the skill loads)
scan.mjs repos, files, imports, endpoints, requests → .cache/scan.json
plan.mjs a blueprint's plan.json → the same .cache/scan.json
build.mjs validate, assign files, connect, Health, screens → graph.json + index.html
describe.mjs worksheets for Claude to name and describe files and endpoints
refresh.mjs incremental update: re-scan, carry over, flag changes, rebuild
recent.mjs facts for marking recent work
open.mjs start or reuse the map's server, and open the browser
lib/ extraction, import resolution, route matching, Health, screens, which agent is running, helpers
assets/
viewer.html the map (template the build fills in)
ui/ viewer extensions: Theme button, blueprints, glossary, Health, recent work, screens, tour, waitlist card
graph-query.js shared map lookups (viewer, query.mjs, Ask instructions)
serve.mjs copied into each project's floorplan/ folder; answers through Claude Code or Codex
page-safety.mjs the one way data and code go into a page's <script> blocks, and its Content-Security-Policy
(used by build.mjs, and copied next to serve.mjs)
query-cli.mjs becomes floorplan/query.mjs
logo.png, favicon.png
vendor/ bundled layout engine (elkjs) and fonts, with their licenses
tests/ regression tests and the sample projects they map
tools/checksums.mjs writes CHECKSUMS.txt for a release, and checks an installed copy against it
CHECKSUMS.txt SHA-256 of every file the plugin runs from, as of the last release
docs/ these guides
Install from your local folder instead of GitHub:
claude plugin marketplace add /path/to/floorplan
claude plugin install floorplan@floorplanA plugin installed from a local folder runs straight from it, so edits apply in the next session with no update step.
To try it in Codex, see Trying a working copy. Codex copies a local plugin when you add it, so run codex plugin add floorplan@floorplan again after each change. --agent claude|codex|none on build.mjs (or FLOORPLAN_AGENT) and --engine claude|codex on serve.mjs let you try either agent's map from anywhere.
The scripts also run on their own, which is the fastest way to work on them:
node skills/floorplan/scripts/scan.mjs /path/to/project
node skills/floorplan/scripts/build.mjs /path/to/project
node skills/floorplan/scripts/open.mjs /path/to/projectbuild.mjs needs a floorplan/architecture.json in the project, so run the skill once first, or write a small one by hand (schema).
npm testThe tests use Node's built-in test runner, so there's nothing to install (npm test is the same as node --test). GitHub runs them on every push and pull request on Linux and Windows with Node 18, 20 and 22, and on macOS weekly and on demand (Actions → macOS → Run workflow), since its macOS machines are often all busy.
| File | What it checks |
|---|---|
parsing.test.mjs |
imports, endpoints, web requests and doc comments, per language and framework |
helpers-lib.test.mjs |
globs, file types, command-line flags, fallback names |
secrets.test.mjs |
Health finds secrets, masks them, and ignores placeholders |
health.test.mjs |
which endpoints Health calls open to anyone (FastAPI and Express samples in fixtures/) |
public-by-design.test.mjs |
what Health leaves alone because it's public on purpose (feeds, addresses a project publishes, cached responses, routes with nothing private, Payload CMS, tracker tokens, files a tool opens), each with a near miss it must still report |
stack-health.test.mjs |
Health's checks for Supabase row-level security, Firebase rules, Stripe webhook signatures, secret keys in public variables and CORS, with look-alikes each must leave alone, and a whole sample app done wrong and done right |
django.test.mjs |
Django: an app's urls.py included under a prefix, and the website's requests matched to it |
fastify.test.mjs |
Fastify: plugins registered with a prefix, nested registers, and the website's requests reaching the right plugin (sample in fixtures/) |
route-table-keys.test.mjs |
route tables keyed by "METHOD /path" in JavaScript and Python: which tables count, each entry's handler, the website's requests reaching them, and Health staying quiet about their sign-in (sample in fixtures/) |
firebase.test.mjs |
Firebase Cloud Functions: callables and onRequest functions as endpoints, the website's calls to them, Screens, Health, background functions (React + Firebase sample in fixtures/) |
blueprint.test.mjs |
a map planned from a PRD before any code exists: plan.json errors, endpoints and calls, Screens, the design review, refreshing and switching to the real code (sample PRD in fixtures/) |
blueprint-change.test.mjs |
changing a blueprint from the map: the agent's updated plan is checked, saved and highlighted, retried once when it fails the checks, and undone (stand-in CLI in fixtures/fake-cli/) |
large-files.test.mjs |
files over the scan's size limit stay on the map with their line count, and the scan, Health and the map say they weren't read |
sample-app.test.mjs |
a whole map of a two-repo shop: endpoints, cross-repo requests, Health, offline map, no secret values written, updates |
worksheets.test.mjs |
the description worksheets quote each endpoint's code and very short files whole, within their caps, with secrets masked and .env-style files never quoted, and list the files that import, request or name each file |
plain-language.test.mjs |
the build's warnings, never errors, about developer words in part labels and summaries on a map for everyone (product names and developer maps left alone, screen words such as "hook" and "component" flagged only where they mean screens, the word list kept in step with the writing guide, the --json shape), and about parts with many files in folders of their own |
hostile-content.test.mjs |
mapping code you didn't write: hostile text in every model-written and scan-derived field leaves a page whose data parses and round-trips exactly (built, served, exported, Export button); secrets written into descriptions are masked with a warning naming the file and field, while prose, commit hashes and UUIDs stay; every page's Content-Security-Policy matches its scripts' hashes; invalid patterns are named build errors; config files and files built to slow pattern matching don't stall the scan; invisible and reordering characters are shown as markers |
serve.test.mjs |
the map's server: 127.0.0.1 only, its own host names only, token and same-origin checks, nothing served from outside its folder |
export.test.mjs |
exporting a copy to share: what's left out by default, the extras when asked, the Export button's endpoint |
phone.test.mjs |
phone and tablet layout: the top bar wraps instead of overflowing, icon-only buttons keep a name, 44 px touch targets, the details sheet that opens when a box is tapped, the zoom buttons in the top row, the folding description and the AI-tool note shown only while asking (checks on the built page, not a real screen) |
ask.test.mjs |
asking through Claude Code or Codex: which one is used, read-only, follow-ups, sign-in errors (stand-in CLIs in fixtures/fake-cli/) |
agents.test.mjs |
telling Claude Code from Codex, and what a map built by each records and writes |
unattended.test.mjs |
running without an agent session: a small driver follows workflow.json through a first map and a refresh with canned answers, using only --json and exit codes; the optional plain-language step (reworded, left alone, rejected for changing more than wording, or failed, with the map completing every time); nothing written outside floorplan/, a map that names no agent, git failures that fail loudly, the workflow file's names and schemas, maskSecrets as a stable export, and no change without unattended mode |
read-only-install.test.mjs |
a skill whose files are read-only builds a map twice, and the files it puts next to the map stay writable, including over read-only ones an earlier version left (skips itself where read-only doesn't stop the user writing) |
release.test.mjs |
the version agrees across both plugins' plugin.json, the README badge, the changelog and CHECKSUMS.txt |
supply-chain.test.mjs |
what the plugin can do stays what Is it safe to install? says: no hooks, MCP servers or dependencies, one outbound request, a fixed list of programs and pre-approved scripts, no code loaded at run time, the vendored layout engine unchanged |
touch.test.mjs |
touch gestures: a drag follows one finger and ends on a cancelled touch, two-finger pinch and pan, nothing re-fits the map mid-gesture (checks on the built page, not a real screen) |
sandboxed.test.mjs |
a map whose browser refuses storage, the clipboard or new windows (a sandboxed frame, strict settings): settings kept in memory for the visit, no tour on its own, #tour=0, "Copied" only when it was, the address shown when a window is blocked, and nothing changed where storage works (the page's own code run against a pretend browser, not a real frame) |
Sample projects are written to a temp folder by helpers.mjs (shopApp()) or copied from tests/fixtures/. Anything secret-looking is assembled at runtime, so no real-looking key is ever committed.
When you fix a bug in what Floorplan detects, add a sample that shows it, and check the test fails without your fix.
Files in skills/floorplan/assets/ui/ are inlined into every map, in name order. They talk to the viewer only through window.Floorplan, which offers:
- the graph and lookups;
- navigation (
go,open,reveal,showBoard,playFlow); addHeaderButtonandaddPanelSection('overview' | 'item', fn);modal,toast,store(settings for this browser;store.persistentis false when the browser won't keep them past this visit, and they're held in memory instead);copy(text), which resolves true only when the text was really copied and otherwise shows it to copy by hand, andopenWindow(url), which shows the address when the browser blocks a new window. Use these rather thannavigator.clipboardorwindow.open, so the map behaves in a sandboxed frame too;- events (
on('ready' | 'render' | 'panel' | 'technical')); exported, set in an exported copy: leave out anything there that needs Claude, Codex or the map's server.
20-health.js and 25-recent.js are good examples.
There are two lists, and an agent can be on one or both:
- The agent that built the map, in
scripts/lib/agent.mjs: an entry inDETECTthat recognises it from the variables it sets for every command it runs. The map records it, so its prompts name the right agent. - The agent that answers questions, in
assets/serve.mjs: an entry inENGINESwith its name, where to get it,find(where its CLI lives, plus a--<name> <path>override) andrun(the arguments and how to read its output into progress and an answer).
An engine must be read-only in a way its CLI enforces, not only because the prompt asks; if it can't be, say so plainly in the docs. Set structured: true only when the CLI holds answers to the schema, because changing a blueprint from the map relies on it; without it, the map doesn't offer Change. Never take the command to run from the page or from saved settings. Add a stand-in CLI to tests/fixtures/fake-cli/ and tests like ask.test.mjs.
- No dependencies. The scripts must run anywhere Node 18+ does, with nothing to install.
- Plain language first. Anything the map shows people should make sense to an app's owner, not just its engineers.
- Never store or print secret values. Health findings record where a secret is and a masked hint, never the value.
- One description of the process.
workflow.jsondescribes the same steps as SKILL.md, for running Floorplan without an agent session (unattended.md). When you change one, change the other, and point atreferences/rather than repeating them. - Keep examples generic. Code comments, docs and prompts must not describe any real private project.
-
mainis always releasable. Every change reaches it through its own branch, merged with a merge commit (git merge --no-ff), so each change reads as one unit in the history. -
Name branches by what they are, with the issue number when there is one:
fix/4-fastapi-annotated-guardsfeat/codex-supportdocs/…,chore/…
A branch made with GitHub's Create a branch button on an issue (
2-reaching-outside-repo) is fine too. -
Commit messages start with a short summary in the imperative ("Bundle the layout engine"), and the body says why.
Fixes #Nin a commit or merge message closes the issue when it reachesmain.Refs #Nlinks it without closing.
-
Contributors' pull requests keep their commits and authorship. Merge them with a merge commit ("Merge pull request #N from user/branch"), and resolve
CHANGELOG.mdconflicts by keeping both entries. -
Delete branches once merged.
- Versions follow semantic versioning. Before 1.0:
- a patch (0.1.x) for fixes and small improvements;
- a minor version (0.x.0) for new features, or anything that changes what people install or run.
- Users only receive an update when the version changes, so release fixes promptly rather than leaving them on
main. - Every change people will notice adds a line under
## Unreleasedat the top ofCHANGELOG.md:- in plain language;
- crediting whoever reported or fixed it, e.g. "Reported by @name in #1, fixed by @name in #3".
- On an up-to-date
main, run the tests and check the manifests, including the official plugin directory's requirements:npm test claude plugin validate . --profile directory
- Bump
versionin.claude-plugin/plugin.jsonand.codex-plugin/plugin.json, and the version badge inREADME.md. - Rename
## UnreleasedinCHANGELOG.mdto## X.Y.Z (YYYY-MM-DD). - Write the release's fingerprints, after the version bump:
node tools/checksums.mjs
- Commit as
Floorplan X.Y.Z: <one-line headline>and pushmain. - Tag and push the tag. This also checks that
plugin.jsonand the marketplace entry agree:claude plugin tag . -m "Floorplan %s" --push
- On GitHub, publish a release from the tag (
floorplan--vX.Y.Z), titledFloorplan X.Y.Z, with that version's changelog section as its notes. - Reply on every issue and pull request the release fixes: what changed, the version, and how to get it (
claude plugin update floorplan@floorplan).
- Reply to new issues within a few days, even if only to say you've seen them.
- Label each one (
bug,enhancement,question). - Assign yourself when you pick it up.
- Label each one (
- Ask for the shape of a problem, never for private code, secrets or screenshots of a private map.
- Thank contributors, and credit them in the changelog and release notes.
- Close an issue with a comment that names the release containing the fix.
- Security reports go through SECURITY.md, privately. Don't discuss them in public issues until a fix is released.