The Blueprint

The technical recipe that lives in your repository, right next to the code.

What It Is

When the ticket is complete, the developer runs /scaffold. Blackbox reads the structured ticket and generates a Blueprint that lives inside the project repository. It is not a copy of the ticket. It is the translation of the ticket into a technical recipe: what to build, where in the codebase, and how to verify it is done.

Every decision, every constraint, every requirement. Permanent and searchable, not lost in a chat window.

Anatomy

Ticket-Owned

Generated instantly when running /scaffold. Comes directly from the ticket.

  • Goal
  • Context
  • Requirements
  • UI / UX
  • Constraints

Developer-Owned

Filled in locally via /refine and during implementation. This is where the technical thinking lives.

  • Codebase Context
  • Implementation Plan
  • Technical Decisions
  • Validation

The Blueprint carries only two external links: the ticket URL and the PR link. No status, no changelog. Your project management tool handles that.

Lifecycle

Step 1 — Generated

/scaffold reads the ticket and creates the Blueprint instantly. The Ticket-Owned sections are populated automatically.

Step 2 — Refined

/refine spawns three parallel research agents that explore the codebase, map affected files, find existing patterns, and surface gaps. Then drives a guided Q&A to fill the Developer-Owned sections.

Step 3 — Built

As implementation progresses through /implement, /review-code, and /wrap-up, the Blueprint tracks every decision made. When the PR is created, the Blueprint is the permanent record of everything that happened.

See the Blueprint in action

The full workflow shows how the Blueprint fits between the ticket and the pull request.

Explore the workflow