Planning documents

Planning documents are the contract between you and the factory: they define what gets built. This page covers how they're generated, versioned, reviewed, and approved.

The document tree

Each product has a tree of documents, organized by section. What's in the tree depends on the TOC you approved — architecture, requirements, designs, acceptance criteria, and other documents from the planning catalog, scoped to your product's classification. Some catalog entries are collections that hold a family of related documents rather than a single one.

Open any document from the tree on the request or project page to read it, see its version history, and act on it.

Versions

Every document is versioned:

• Each generation, direct edit, or accepted vibe-editor patch produces a new version.
• The version history is always visible; you can open the content of any prior version.
• A document tracks both its latest version and its current (approved) version — external share links only ever show approved content.

Reviewing a document

For each document version you have four moves:

Approve

Marks the version as approved. Approvals gate the pipeline — the build phase won't start until the plan is approved, and share-link viewers only see approved versions. In a share portal, external reviewers can also record their approval on a document.

Request changes

Sends the version back with your notes. The notes travel with the document so the regenerating agent (or a teammate) knows exactly what to fix.

Edit

You can revise a document yourself:

• Directly, in the editor.
• Conversationally, via the vibe editor — tell it what you want changed in plain language and accept or discard the patch it proposes. See Document editor.

Regenerate

Re-runs the pipeline step that produced the document, generating a fresh version. Use this when the document misses the point entirely and notes wouldn't be enough.

Feedback and comments

Documents accumulate feedback: your review notes, teammate comments, and comments left by external reviewers through share links (tagged with their source so you can tell them apart). Feedback is the raw material for revision passes.

Architect review

Before build, the plan as a whole goes through an architect review — an agent pass that checks the documents against each other for consistency and completeness. Issues it finds come back to you as review output on the affected documents, to resolve before approving the plan for build.

Approval gates in practice

The plan is what gets built

The build agents work from the approved documents — not from your original request text, and not from anything discussed but never written down. If it matters, make sure it's in an approved document before the build starts.

A typical review loop looks like:

1. A document version is generated and appears as pending.
2. You read it. Small issues → fix them yourself with the vibe editor. Larger issues → Request changes with notes, or Regenerate.
3. When it says what you mean, Approve.
4. Repeat across the tree. When the plan is approved, the pipeline advances to Build.

Costs

Each document generation is a run with a visible cost. The TOC screen gave you an estimate up front; the request's cost breakdown shows the actual spend per stage as documents are produced.

Reverting the planning phase

If planning went badly wrong, a project can be reverted to an earlier snapshot (see Pipeline overview). Documents and runs created after the snapshot are discarded, so export or note anything you want to keep first.

Next

• Document editor — editing documents by chat.
• Build and review — what happens after the plan is approved.