v0.1.2 — commit at each gate

The first change driven by evidence rather than design.

The test

A fresh agent — no knowledge of this project, no context beyond the repository itself — was given one message: "Read blueprint/START-HERE.md and follow it. I want a thing that tracks my expenses."

It did not start writing code. It ran DISCOVER, wrote 14 numbered acceptance criteria, worked through every phase, and shipped a working expense tracker with 110 passing tests. Its state file passed validate.py --strict --release. When it hit a gate it could not satisfy — DISCOVER requires human confirmation and no human was available — it recorded the unmet criterion as a known issue instead of quietly skipping it, and it reported the one thing it could not verify (a manual browser pass) rather than claiming it.

What went wrong

It ran git init during BUILD. So its first commit contained the requirements, the design, the ADRs and the first hundred lines of code all at once. The process was followed correctly — but the history could not prove it, and neither could file timestamps.

The fix

• DISCOVER now opens by putting the project under version control, before the first artifact is written.
• workflow.md gains a "Commit at each gate" section — a rollback point at every gate, and a history that shows requirements preceded code rather than being reconstructed afterwards.
• DISCOVER, DESIGN and PLAN require their artifact committed before the gate closes.
• The mistake is recorded as a DISCOVER common failure, where an agent will actually read it.

Three tests guard the change. The method is otherwise unchanged from v0.1.1 — nothing in an existing project needs to move.

Requirements: Python 3.9+ for the optional validator. Nothing else.

v0.1.1 — Windows install, demo, code of conduct

A documentation and usability release. The method itself is unchanged from v0.1.0 — if you are already using Blueprint, nothing in your project needs to move.

Fixed

Windows install instructions. Every command in the quick start was cp and /tmp, so a Windows user could not copy-paste it. Both the README and docs/quickstart.md now carry PowerShell blocks alongside the shell ones, and a documentation test fails if either goes missing.

Added

• A demo. An animated terminal at the top of the README showing the validator reject a task marked complete with no evidence, then pass once the proving command is recorded. Every line is a literal capture of real output, asserted by a test so it cannot drift into fiction.
• CODE_OF_CONDUCT.md — Contributor Covenant 2.1, with reporting routed through GitHub rather than an email address.

Changed

• The README opens with the failure Blueprint prevents rather than a description of what it is.
• validate.py prints paths relative to the working directory when the project is inside it, instead of a full absolute path that wrapped the line on Windows.

Requirements: Python 3.9+ for the optional validator. Nothing else.

v0.1.0 — first release

Blueprint is a folder of instructions you copy into a project. It gives an AI coding agent a lifecycle it cannot skip, rules that outrank the prompt, a memory that survives between sessions, and a definition of done that requires evidence.

It is not an agent or a model. It is the layer that makes the agent you already use behave like a professional engineer.

What is in this release

• Constitution — eleven non-negotiable rules, anchored on evidence over claims.
• Workflow — DISCOVER → DESIGN → PLAN → BUILD → VERIFY → SHIP, with an explicit gate rule: you cannot enter a phase until the previous one's exit criteria are recorded.
• State — one state.md holding phase, current task, completed work with evidence, blockers, decisions and the next action. A cold session reads it and continues.
• Loops — per task: IMPLEMENT → TEST → REVIEW → FIX → VERIFY, with a two-attempt limit and a structured blocker format.
• blueprint/validate.py — standard-library-only check for state structure, phase gates, evidence lines and ADR consistency, plus a --release scan for secrets and personal data.
• Adapters — AGENTS.md and CLAUDE.md, pointers only. Claude Code, Codex, Cursor and Gemini CLI, with no per-vendor copy of the method to drift apart.
• Example — a complete run in examples/task-tracker, from a vague idea to a working, tested tool.

Install

git clone --depth 1 https://github.com/Potato7711/blueprint.git /tmp/blueprint
cp -r /tmp/blueprint/blueprint /tmp/blueprint/AGENTS.md your-project/

Then tell your agent: Read blueprint/START-HERE.md and follow it.

The bug that made the case

Dogfooding found three real defects before release. The example crashed with UnicodeEncodeError on its ordinary list --all path: the design specified a tick character, and the unit tests captured stdout with io.StringIO, which never encodes — so a crash survived a fully green suite until the tool was run in a real terminal during VERIFY.

The same class of bug turned up in its error messages, and again in Blueprint's own validator output. All three are fixed, and capturing output is not the same as writing it is now a documented VERIFY failure mode.

Requirements: Python 3.9+ for the optional validator. Nothing else.