Handbook

Blueprints Wizard overview

The Blueprints Wizard is a guided flow inside Forge Studio that walks a team through mission, context, clarification, targets, scope, run plan, review, recheck, and optional Cursor Launch Pack export. It aligns with…

Concept · Updated 2026-08-22

What it is

The Blueprints Wizard is a guided flow inside Forge Studio that walks a team through mission, context, clarification, targets, scope, run plan, review, recheck, and optional Cursor Launch Pack export. It aligns with Blueprints concepts; it does not automatically modify your blueprints/ git submodule.

Terms (quick read)

Term	Plain language
Wizard	Guided planning / assessment workflow — structured steps and artifacts, not auto-edits to your repo.
Forge Studio	Local workspace UI where the Wizard runs (`/studio/`).
Artifact bundle / pack	Emphasis the session gives to planning vs engineering vs execution outputs (labels vary by build).

Good for / not for

Good for	Not the best tool when…
Facilitated workshops with a shared narrative	You only need a one-line edit in existing Markdown
Aligning before branching or a new initiative	You want unattended automation to bump git submodules
Producing exports and packs for the next engineering step	Your team will not read or update session notes

Inputs and outputs (conceptual)

Phase	You bring	You leave with
Mission through scope	Context, constraints, disagreements	Shared targets and an explicit increment
Run plan through review	Owners, risks, dependencies	Ordered steps and generated artifacts
Recheck / experimental	Policy for exports	Packaged handoff (for example Cursor Launch Pack) when enabled

Trust boundaries (Studio ↔ Lenses ↔ outbound)

Wizard trust boundaries

Maps who triggers work, what Lenses executes locally, and what crosses outbound surfaces.

Actor / triggerThe facilitator or operator starts a Wizard action in Studio.
System stepLenses stores session JSON and runs bounded server routes.
Outcome / handoffArtifacts and exports leave the session for human review.
Note: Git working treeThe Blueprints submodule stays outside automatic mutation.

  Trust boundaries (Studio ↔ Lenses ↔ outbound)

  Actor / trigger
      |
      v
  System step
      |
      v
  Outcome / handoff

  Note: Git working tree

Wizard stores session JSON locally; LLM and Fleet calls are explicit POST surfaces

Boundary	Shipped today	Your responsibility
Git working tree	Wizard does not auto-commit Blueprints submodule bumps	Review exports before `git add`
`.lenses-local/`	Session envelope + telemetry land here	Back up or wipe per policy (Security and local-first)
LLM vendor	Optional refine/interpret calls via server-side POST routes	Redact prompts; use corporate gateways when required
Forge Fleet	Optional job orchestration when enabled	Treat bearer tokens like production secrets

Deep dives: Wizard — operator trust boundaries and Wizard — builder session HTTP API.

Session lifecycle (happy path)

Wizard session lifecycle

From Hub session creation through core planning steps to a reviewable session outcome.

StartCreate or resume a session on the Wizard Hub.
Core steps (see walkthrough below)Walk mission, context, scope, run plan, and review.
OutcomeFinish with shared targets, run plan, and optional export.

  Session lifecycle (happy path)

  Start
      |
      v
  Core steps (see walkthrough below)
      |
      v
  Outcome

Hub creates id; session route loads stepper; exports are explicit actions

Wizard session state machine

Session states advance on the happy path; recheck or repair can loop before export.

StartHub creates a session id and loads the stepper route.
Core steps (see walkthrough below)States mirror mission-through-review phases in the walkthrough.
OutcomeTerminal state when review completes and exports are ready.

  Session lifecycle (happy path)

  Start
      |
      v
  Core steps (see walkthrough below)
      |
      v
  Outcome

Happy path advances; recheck or repair can loop until consistency passes

When to use it

When you want a facilitated workshop, a shared narrative before branching, or a bootstrap for a new initiative — not when you only need a one-line edit in existing Blueprints files.

Prerequisites

Studio overview — server and /studio/ work.
Wizard routes visible in the sidebar (see Enable below).

Steps

Enable (if the Wizard is hidden)

Visibility depends on how your Lenses build and server are configured. If the Wizard does not appear in the Studio sidebar, confirm you are on a build that includes it, or ask whoever maintains your Lenses installation. Operator-level configuration is documented in the forge-lenses repository on GitHub.

Open the Wizard

Go to /studio/.
Open Blueprints Wizard (experimental) in the sidebar.
You land on the Hub at /studio/blueprints/wizard — create or resume a session.

How to verify success

Hub loads and lets you create a session.
A session URL matches /studio/blueprints/wizard/session/<id>.

Forge Lenses