Blueprint
The blueprint is the second step of the Flow workflow. In this guide, you will learn:
- What the blueprint skill does and how it uses the harness docs
- How the planning interview works
- What the blueprint produces
Overview
The blueprint skill turns the
brief into a technical implementation plan. Where the brief says what the user experiences, the blueprint decides how the application will deliver it: the database schema, the models, the controllers, the validation, the authorization, the response shape, the routes.
You invoke it with the change name from the brief step:
/flow-blueprint project-archivingThe skill reads brief.md, plans against it, and writes blueprint.md into the same change folder. It inspects your codebase freely but never writes application code. Planning is read-only.
Grounded in the harness
The blueprint is not planned from the agent's memory of AdonisJS. At each step, the skill reads the relevant docs from the knowledge base and plans against what it finds there. A config key, a file path, an API surface: all of it traces to a harness doc read during the session, not to training data.
The blueprint skill ships in per-stack variants. The version installed in your project matches the rendering stack you chose during installation, so an API project gets API-shaped plans and an Inertia project gets Inertia-shaped plans.
How the planning works
The skill first classifies the change: greenfield, an extension, a refactor, a modification, or a bug fix. A bug fix small enough to be a few lines skips planning entirely. The classification decides which planning steps apply.
It then runs a short discovery pass, reading the existing files the change will touch so the plan fits the codebase as it actually is, not a blank slate.
From there it walks the technical dimensions of the change one step at a time: the schema, the migrations and models, the controllers, any services, the validation rules, the authorization, the response layer, the routes, and the events. Each step reads its harness docs, proposes a decision, and waits for your approval before the next step begins. When controllers or routes are involved, the skill runs the CRUDDY controllers skill to name them.
Decisions, not code
The blueprint records decisions, not finished code. It names which pieces wire together, which constraints the harness docs surfaced, and which alternatives were rejected. It does not contain complete controller methods or service classes.
This is deliberate. The build skill writes the actual code, re-reading the harness docs as it goes. A blueprint full of literal implementation would go stale against the harness and turn the build step into a copy-paste exercise rather than a grounded one.
What the blueprint produces
The skill writes blueprint.md into the change folder. It carries a summary, the target shape, and one section per technical dimension the change touches, each opening with a record of the harness docs it was planned against.