Blueprint — Flows, Skills, and Unattended Loops

Blueprint is a small set of instructions for AI coding. It separates deciding what to build from shipping code.

Principles

• Give agents outcomes, constraints, and proof. Trust them with mechanics.
• Keep one skill per meaningful engineering phase or delivery outcome.
• Keep current architecture separate from proposed design.
• Review technical proposals before implementation when a wrong choice could materially affect behavior, data, security, scale, performance, compatibility, operations, cost, or proof.
• Update an existing architecture document when code changes ownership, dependency direction, protocols, stored data, trust boundaries, deployment topology, or hard limits.
• Skip phases that add no value. Small, decided work can go straight to implementation.
• A task is ready when a new agent can finish it without asking product or technical questions.
• Each pull request delivers one focused outcome and its proof. A reviewer should not have to separate unrelated work to understand it.
• Separate refactoring when it would hide the behavior change. Small local cleanup may stay when it makes that change easier to review.
• Logic changes include automated tests for changed behavior and affected failure paths, including any named in the acceptance criteria.
• Refactors include tests for behavior that must not change.
• If automated tests cannot exercise the affected behavior, explain why and give other evidence.

Writing

Write for a new teammate who needs to understand the point on the first read.

• Lead with the outcome, decision, or rule. Put supporting detail after it.
• Use short sentences and everyday words. Give each sentence one main idea.
• Write instructions as direct commands. Put a condition before the step it controls.
• Name the actor. Prefer the parser rejects the file to the file is rejected.
• Use the same word for the same thing. Define a necessary technical term once.
• Use real names, paths, commands, limits, and effects. Replace vague claims with facts.
• Cut filler, repetition, sales language, fake warmth, and generic conclusions.
• Use sentence case for headings. Use numbered lists for sequences and bullets for real lists.
• Keep a human voice. State a judgment when the document calls for one. Keep instructions and reference text neutral.
• Vary sentence length when it helps the prose sound natural. Do not force every point into the same shape.

Before finishing, reread the text. Cut words that do no work. Fix sentences that can be read two ways. Rewrite anything that sounds generated instead of written for this project.

Phases

• /architecture: create or update root ARCHITECTURE.md from verified implementation. Stop with the document ready for human review.