Bridge

Build Plan output files

When you tap Start a venture on a constellation, Bridge generates exactly eight markdown files plus one CLI overlay file. Together they are the spec set — a portable, agent-readable plan you drop into your project directory and pipe to any coding agent.

The set

00_index.md          ← entry point; agent reads first
01_brief.md          ← what to build, why, for whom
02_user_flow.md      ← the one demonstrable end-to-end flow
03_architecture.md   ← system shape, stack, structure
04_data_model.md     ← entities, schemas, function signatures
05_tasks.md          ← atomic ordered tasks; agent updates as work progresses
06_acceptance.md     ← testable conditions for "done"
07_scope.md          ← positive scope statements; what's in this prototype

Plus one overlay file at the project root:

AGENTS.md             ← points your coding agent at the spec set

Why eight files

The files are scoped tight so the whole set fits inside any modern coding agent's context window without crowding out the agent's working memory. The total set targets around 4,000 tokens — well under the context-rot degradation threshold researchers have measured for current frontier models.

File-by-file

00_index.md (≤300 words) — entry point

Read first by the agent. Tells the agent what each file contains and the order to consult them.

Contains:

  • One-paragraph project summary.
  • File-by-file table: filename → purpose → when to consult.
  • Reading order: 00 → 07 → 01 → 02 → 03 → 04 → 05 → 06. (Constraints in 07_scope.md get read second to capture attention budget early.)

01_brief.md (≤500 words) — what and why

The product brief.

Contains:

  • Problem statement (one paragraph).
  • Target user (one paragraph, specific — not "everyone").
  • Success metric (one sentence).
  • Background context — 3–5 bullets of relevant prior thinking from your notes.

02_user_flow.md (≤400 words) — the demonstrable flow

The single end-to-end user flow the prototype must demonstrate. If this flow completes, the prototype is "done."

Contains:

  • Flow name.
  • Numbered steps in EARS notation: "WHEN [trigger], THE System SHALL [response]."
  • Edge cases (3–5 bullets).

03_architecture.md (≤700 words) — system shape

Where stack appears. Each choice carries a one-sentence rationale.

Contains:

  • Stack declaration (frontend / backend / database / runtime / deployment), each line with rationale.
  • Directory structure (5–15 lines).
  • Key external dependencies with rationale.
  • Architectural constraints (3–5 bullets).

If your notes specified a stack preference, that becomes a hard constraint here. Otherwise, your agent picks.

04_data_model.md (≤500 words) — pre-defined structures

Every data structure the prototype needs, defined once at the top. Tasks in 05_tasks.md reference these by name rather than re-defining them inline.

Sections:

  • Entities — field names, types, constraints.
  • Schemas — JSON shapes the prototype reads/writes.
  • Function signatures — the public API the prototype exposes.
  • Initial seed data, if the demo flow needs any.

05_tasks.md (≤1000 words) — atomic work, agent-maintained

The implementation checklist. The agent reads this most directly and updates it as work progresses — marking each task done and adding a one-line deviation note if the implementation diverged.

The file opens with a maintenance instruction that tells the agent to update task status after completing each one. The plan files become the status — Bridge doesn't track it externally.

Each task lists:

  • An ID (e.g. T01).
  • A Status (pending / done).
  • Dependencies (other task IDs, or none).
  • References (to entries in 04_data_model.md by name).
  • An accept-when condition.

06_acceptance.md (≤300 words) — testable conditions

Global "done" gate. Distinct from per-task acceptance.

Contains:

  • A bulleted list of verifiable conditions. Each is one sentence, present tense, testable.
  • One end-to-end test scenario exercising the user flow from 02_user_flow.md.

Every condition is runnable verification. "GET /api/notes returns 200 with a JSON array of length 3." Not "The API works."

07_scope.md (≤300 words) — positive scope statements

What this prototype is. Positive boundaries, not negation.

Contains:

  • Scope statement (3–5 bullets). Examples:
    • "Scope: single-user, local-only, no authentication."
    • "Scope: demo data hardcoded in seed file."
  • Compliance constraints inferred from your notes, if any:
    • "License: permissive only (MIT, Apache 2.0, BSD)."
    • "Data: no PII, no production data, no third-party data sharing."

AGENTS.md — CLI overlay

Generated alongside the eight files. You drop it at your project root. It tells your coding agent the reading order:

# Project: <name>

This project is planned by Bridge. Read the plan documents in this order:

1. 00_index.md (orients you)
2. 07_scope.md (what's in scope)
3. 01_brief.md (what and why)
4. 03_architecture.md (stack, structure)
5. 04_data_model.md (pre-defined structures)
6. 05_tasks.md (the work)

For acceptance criteria, consult 06_acceptance.md.
For the user flow, consult 02_user_flow.md.

## Working agreement

- Execute tasks in the order listed in 05_tasks.md unless dependencies force otherwise.
- After each task, verify the task's "Accept when" condition before moving on.
- Update 05_tasks.md per its maintenance instruction.
- Reference pre-defined structures from 04_data_model.md by name in code.
- Stay within the scope in 07_scope.md. Surface scope concerns before expanding.

How the spec set evolves

When you regenerate a Build Plan (by starting a venture again from the same note), the new run uses your current context: latest notes, latest expansions, latest user-behavior memory. The old version stays in the Plan tab archive.

The spec set is task-relevant context only. Background lives in 00_index.md and 01_brief.md. Implementation files reference those on demand.

Next

← Back to DocsPre-order Bridge