Skip to content

See how your app actually fits together. An interactive, plain-English map of your codebase, drawn by Claude or Codex.

13.1 KB
Raw Blame

Developing Floorplan

Repo layout

.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
  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
    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

Try your working copy

Install from your local folder instead of GitHub:

claude plugin marketplace add /path/to/floorplan
claude plugin install floorplan@floorplan

A 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 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/project

build.mjs needs a floorplan/architecture.json in the project, so run the skill once first, or write a small one by hand (schema).

Tests

npm test

The 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
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
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)

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.

Extending the viewer

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);
  • addHeaderButton and addPanelSection('overview' | 'item', fn);
  • modal, toast, store;
  • 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.

Adding an agent

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 in DETECT that 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 in ENGINES with its name, where to get it, find (where its CLI lives, plus a --<name> <path> override) and run (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.

Guidelines

  • 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.
  • Keep examples generic. Code comments, docs and prompts must not describe any real private project.

Maintaining

Branches and commits

  • main is 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-guards
    • feat/codex-support
    • docs/…, 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 #N in a commit or merge message closes the issue when it reaches main.
    • Refs #N links 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.md conflicts by keeping both entries.

  • Delete branches once merged.

Versions and the changelog

  • 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 ## Unreleased at the top of CHANGELOG.md:
    • in plain language;
    • crediting whoever reported or fixed it, e.g. "Reported by @name in #1, fixed by @name in #3".

Releasing

  1. 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
    
  2. Bump version in .claude-plugin/plugin.json and .codex-plugin/plugin.json, and the version badge in README.md.
  3. Rename ## Unreleased in CHANGELOG.md to ## X.Y.Z (YYYY-MM-DD).
  4. Write the release's fingerprints, after the version bump:
    node tools/checksums.mjs
    
  5. Commit as Floorplan X.Y.Z: <one-line headline> and push main.
  6. Tag and push the tag. This also checks that plugin.json and the marketplace entry agree:
    claude plugin tag . -m "Floorplan %s" --push
    
  7. On GitHub, publish a release from the tag (floorplan--vX.Y.Z), titled Floorplan X.Y.Z, with that version's changelog section as its notes.
  8. Reply on every issue and pull request the release fixes: what changed, the version, and how to get it (claude plugin update floorplan@floorplan).

Issues and pull requests

  • 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.
  • 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.