blueprint-xml

Behavior-driven development for the agentic era.

Run it in a folder that has a blueprint.xml. It tells you, in human words, what is done and what is left.

$ blueprint
hermetic-client
Project Progress: 53.3%
─────────────────────────────
Application .......... 37.5%
  Layout ............. 40%
    Navbar ........... 0%
    Player ........... 0%
    TrackList ........ 0%
  Modals ............. 33.3%
    Album ............ 0%
    Extend ........... 0%
Library .............. 66.7%
  distribute-album ... 0%
Workflows ............ 75%
  Settings ........... 50%
    Save ............. 0%  ✗ persist-llm-settings

By default it lists only what is incomplete or missing — the work that remains. blueprint --all shows the finished parts too.

No scenarios

Cucumber-style BDD describes behavior with Given / When / Then scenarios. We do not. Our behaviors are the real, named parts of the program — the nodes a human and an AI both already think in:

<Blueprint name="hermetic-client">
  <Application>
    <Layout>
      <Navbar/>
      <ComposeForm done="true"/>
    </Layout>
    <Modals>
      <Compose done="true"/>
      <Album/>
      <Extend/>
    </Modals>
  </Application>

  <Workflows>
    <Settings>
      <Save test="persist-llm-settings" pass="false"/>
    </Settings>
  </Workflows>
</Blueprint>

A node has presence. It is not a concept ("the app should be fast") and not a demand ("support offline"). It is a thing: a component, a workflow, an action. High level, because Actions and Workflows and XML UI control are high level — but never so high that they stop being real.

The one honest rule

Every smallest named thing (a leaf) is one unit of work. A branch is worth the sum of the leaves beneath it. Progress is units done over units declared.

• done="true" — it exists.
• test="..." pass="true|false" — its truth is checked, not claimed. A failing test counts as not done, no matter what anyone wrote.
• progress="0.5" — an escape hatch for honestly-partial work.

The more detail you declare, the more honest the denominator. That is why a richly-described <Layout> can read 0.4%: you can see everything inside it, and almost none of it exists yet.

The library

Two words.

import { blueprint } from "blueprint-xml";

const report = blueprint.read("blueprint.xml");  // understand the plan
blueprint.show(report);                           // make progress visible

report.percent; // 53.33...

read teaches that a plan can be understood. show teaches that progress should be seen. The XML reader and the math are tiny and ours — no dependencies.

How it earns its keep: GOOD MEMORY

The intended workflow:

1. Build a real program with an AI (messy, fast, alive).
2. Ask a strong AI to transform that program into a blueprint.xml — the real parts, marked for what truly exists, with tests on what matters.
3. From then on, the blueprint is the memory. On any resume — new session, new model, after a context wipe — you run blueprint and instantly see the shape and the remaining work. No re-reading the mountain of source.

A blueprint speaks human, so a human trusts it. It runs, so it stays honest.

Coming second (the wise and formal)

Per the Teenage Savant style, the spark runs first; rigor arrives as a plugin, never as the doorman. Next: blueprint.use(tests(...)) to execute real test suites and overwrite declared pass with measured truth.

Develop

npm start      # render the bundled example
npm test       # node --test