Forge reference

This is the lookup table behind Forge, for when you know the request and need the exact boundary. Everything here composes, so any row can be a whole request on its own. The one thing to understand: every entry below has a stopping point, and Forge reports which phases ran, which were reused, and which are still pending.

The five phases

Existing accepted evidence can satisfy a phase when its identity and relevance are recorded.

Phase	Consumes	Produces	Stops at
Spec	Your request, existing tickets, standing specs, decisions, repository facts	A PRD, issue, bug report, design or technical spec, with Given/When/Then scenarios	An approved draft. No build authority
Plan	The accepted spec or ticket, decisions, current code, repository harness	The approach, reusable machinery, seams, dependencies, outcome issues with observable acceptance	The approach. Build is recorded as pending
Build	The accepted spec and plan, harness rules, the current code	One integrated candidate, simplified, with an independent review verdict	The reviewed candidate. Acceptance is not claimed
Acceptance	The review-passed candidate, scenarios, non-functional requirements, the accepted design revision	Run-by-run evidence, plus browser and visual proof for UI work	A verdict on real behavior. Nothing is published
Ship	The review-passed and acceptance-passed candidate, plus your authorization	One freshness check, a concise closure record, and only the publication you granted	The authorized action, and nothing beyond it

An accepted ticket can satisfy Spec, and a brief note can satisfy Plan. The phase is still accounted for. When acceptance fails, the whole accepted packet returns to Build, and the affected review and acceptance evidence are reassessed against the changed candidate.

Work families

Forge infers the smallest family from your request and the artifacts you reference. An explicit family wins.

Family	Use it for	Spec looks like	Plan looks like
Project	A multi-outcome product or technical end state	A concise PRD, plus design and technical specs when they earn their place	Outcome issues with observable acceptance criteria
Issue	An accepted feature, improvement, polish item, tech task, or patch	The ticket itself, not a copy of it	Brief engineering notes
Bug	An observed discrepancy	Expected and actual behavior, impact, and the available reproduction	Ranked hypotheses and the cheapest distinguishing check
Work	A bounded deliverable that is not software	The deliverable’s purpose, audience, constraints, and proof	Whatever the deliverable needs, without software ceremony

Do not guess a bug’s cause in the spec; that is Plan’s job. Hotfix urgency changes depth and sequencing, not the truth or the gates.

The five review dimensions

The independent reviewer owns coverage and one integrated verdict. Small work narrows the report, not the coverage.

Dimension	Applies when	What it judges
Code Review	Code (including UI markup and styles), tests, executable configuration, or agent instructions that control execution change	Defects, regressions, security, code and test quality, lint and types, engineering standards
Taste	UI behavior, rendered surfaces, or UI design artifacts change	Accepted visual fidelity, interaction states, accessibility, UI conventions
Quality	A knowledge-work deliverable is the reviewed outcome	Accuracy against sources, completeness, reasoning, usefulness, writing and artifact standards
Spec	Every candidate	The approved end state, constraints, omissions, invented requirements, preservation
Craft	Every candidate	Proportionality, overbuilding, underbuilding, whether the remedy fits the evidenced problem

A CSS-only change activates both Code Review and Taste. Source correctness and rendered result are separate claims.
A pure design artifact with no code change activates Taste without Code Review.
Loop records and routine software docs do not activate Quality. A separately requested report or document does.
You can replace a dimension with your team’s own skill, or disable it with a reason. A disabled dimension reports as DISABLED, which is distinct from NOT_APPLICABLE and is not a pass.

Verdicts: PASS, REVISE, FAIL, RETHINK, READY_FOR_USER, BLOCKED, INCONCLUSIVE, and STOPPED.

Direct-entry requests

Each row is a complete request, and each one ends where the table says.

Request	What you get	Where it stops
`Forge explore …`	Research, evidence, options, and unanswered questions	At the answer. No delivery authority
`Forge spec …`	Product, design, technical, issue, bug, or general-work intent	At an approved draft
`Forge spec design …`	A codebase-anchored single-page visual study, with identified design intent	At the study. Not implementation
`Forge plan …`	The implementation approach and a useful delivery breakdown	Before Build
`Forge build …`	Implementation, integration, simplification, independent review, and repair	Before Acceptance
`Forge simplify …`	A behavior-preserving cleanup of the candidate	Inside Build. Not a phase of its own
`Forge review …`	A read-only engineering verdict over one candidate	At the report. Nothing is edited
`Forge acceptance …` or `Forge verify …`	Actual acceptance, including browser QA when it applies	Before Ship
`Forge ship …`	Authorized publication and concise complete-candidate closure	At the authorized action
`Forge spec apply …`	An approved change applied during Spec, document-only	At the provenance record
`Forge kb ask / add / update / remove / verify / history …`	Queries or maintenance of durable project knowledge	At the knowledge result

Forge spec merge is legacy wording for the same operation as Forge spec apply. There is no separate intake request: context gathering and work-family detection happen inside Spec.

Files Forge writes

A managed loop lives in the target repository and stays readable.

.forge/
├── identities.json             stable document IDs and readable codes
└── loops/<loop-id>/
    ├── index.md                current outcome, authority, candidate, next action
    ├── decisions.md            disclosed human decisions, protected from generic edits
    ├── log.md                  concise lifecycle events and handoffs
    ├── spec/                   only the artifacts this work needs
    │   ├── product.md          product intent or PRD
    │   ├── design.md           design guidance with linked mocks or boards
    │   ├── tech.md             technical constraints and contracts
    │   ├── work.md             general-purpose outcome
    │   ├── issues/             issue or bug tickets
    │   ├── plan.md             implementation notes when a separate file adds value
    │   └── change.md           proposed standing-spec delta and behavioral scenarios
    ├── build/log.md            build evidence, reviews, findings, repairs
    ├── verify/                 acceptance and visual evidence
    └── ship.md                 authorized publication and concise closure

docs/specs/                     standing specifications
docs/knowledge/                 optional knowledge bundle

decisions.md records the source, the quote, the scope, and the authorization, and a generic edit cannot rewrite it. Behavioral requirements use Given/When/Then scenarios where behavior matters.

Good to know

Five phases, four work families, five review dimensions, and eleven direct-entry requests.
Spec and Craft apply to every candidate. Code Review, Taste, and Quality follow the outcome.
Small work uses one independent reviewer and one compact report. Larger work earns focused judges. Staffing does not reduce coverage.
A disabled dimension reports as DISABLED, separate from NOT_APPLICABLE and from a returned verdict.
Only an explicit human waiver lets an integrated PASS exclude a required dimension, and that PASS is labelled with the exclusion.
Three substantive repair cycles is the cap. After that Forge records a rethink with the failed invariant, the common cause, and a simpler approach.
Acceptance never reports unrun evidence as a pass.
A document-only spec apply is provenance. Build review and acceptance still judge the result.
Knowledge retrieval and structure checks establish authority and structure, never compliance or acceptance.

Next step

Package your own repeatable work as a skill or a named agent in Build skills and named agents.

Get started

Work in Bright

Modes and agents

Forge

Extend Bright

Workspace

Playbooks

Reference

The five phases

Work families

The five review dimensions

Direct-entry requests

Files Forge writes

Good to know

Next step

​The five phases

​Work families

​The five review dimensions

​Direct-entry requests

​Files Forge writes

​Good to know

​Next step

The five phases

Work families

The five review dimensions

Direct-entry requests

Files Forge writes

Good to know

Next step