Spec
Spec decides what the accepted outcome is, produces the smallest useful artifact, and stops before anything gets planned or built.
Spec defines accepted intent. It owns discovery, context retrieval, the informed questions worth asking you, and the proposed change to standing meaning. It can stop with nothing more than a useful draft, and it never authorizes Build or Ship.
Intake isn't a separate phase in Forge. Context gathering, source retrieval,
workflow detection, and authority framing all live here. For open-ended
investigation with no artifact and no delivery commitment, use Forge explore
instead.
Who owns it
It depends on the outcome. Product Manager owns product intent and observable Issue acceptance. Designer owns journeys, visual intent, states, accessibility, and responsiveness. Architect owns load-bearing contracts, data ownership, trust boundaries, and migration. Engineer owns bug records and technical assessment. For non-software work, the relevant professional defines the deliverable.
Your current request can be the ready Issue when it states the outcome, boundaries, and observable completion. When those are missing, PM authors or completes the Issue with Engineer input, at either depth. Designer and Architect join before any work that depends on them, on the triggers in depth and control.
What it produces
The smallest useful artifact, chosen from templates rather than a mandatory document stack:
| Workflow | Artifact |
|---|---|
| Project | A concise PRD in product.md, plus design.md when experience decisions matter and tech.md when contracts, data, trust boundaries, migration, failure behavior, or material NFRs need early alignment |
| Issue | A reused ready Issue, or issue.md authored by PM with effort and complexity, uncertainty, depth, specialist assignments, and proof |
| Bug | bug.md with expected and actual behavior, impact, available reproduction, and applicable scenarios |
| Design | design.md and visual.md with flows, states, responsive and accessibility intent, and an identified mock or visual board |
| Work | work.md with the deliverable, audience, goals, constraints, source standard, and proof |
When the proposed behavior changes standing requirements, spec-change.md names
the additions, modifications, removals, preserved commitments, affected knowledge,
source authority, and full Given/When/Then scenarios. A removal expressed by
omission doesn't count, and standing Spec never gets copied into a second corpus.
Behavior gets explicit scenarios with stable IDs:
Scenario: SCN-…
Given <accepted starting state>
When <observable actor action or event>
Then <observable outcome>Prototypes and mocks stay identified as decision evidence until you accept their meaning. The accepted visual revision, its states, and representative viewports get recorded so Review and Acceptance can later compare the actual result against them.
What proof it needs
After the applicable authority gate, a separate fast checker runs a boundary fidelity check against the retained accepted baseline, the approved change, the scenarios, the decisions, and the source. It looks at fidelity, clarity, consistency, demonstrability, cost, and downstream usability.
That check can't replace a human decision or authorize protected standing-Spec writes. If the checker isn't available, or the meaning is ambiguous, the gap goes to the responsible owner, and newly consequential meaning goes back to you.
Forge retrieves relevant standing Spec, decisions, domain concepts, processes,
interfaces, and existing solutions before authoring, and uses forge kb ask to
pull existing authority and vocabulary. Missing coverage shows up as a visible gap
rather than a reason to block. It asks you only about consequential choices it
can't retrieve, and it includes a recommendation when it does. There's no fixed
interview, no mandatory document spine, and no empty sections to fill in.
Applying an approved change
Spec records and approves proposed standing meaning without routinely installing
it. When you explicitly request Forge spec apply <change>, Forge prepares the
exact approved standing-Spec and related knowledge bytes and uses the CLI's
guarded memory mechanics with an application: spec manifest. Routine Finish can
invoke the same operation at actual work completion. Direct Spec and Plan work
remains proposal-only. The accepted baseline and approved change remain retained
inputs, independent of the current write base and canonical result.
The result is document-only. The receipt proves the checked document mutation and nothing else, so the installed meaning stays unproved until Build Review and Acceptance judge the complete candidate. The current working tree is the write base and the observable target; it's never evidence that its own pre-apply contents were accepted.
Where it stops
In Guided delivery, Spec presents new or materially revised meaning and stops
before Plan, with your approval as the next action. A direct Forge spec call
stops at the artifact, including under Auto.
Spec returns the artifact paths, accepted and open decisions, proposed Spec or knowledge meaning when present, the preservation chain, boundary-check status, and next requested boundary. A separate Spec apply returns its authority inputs, receipt, and result hashes. Installed target meaning is marked document-only, with runtime proof pending.
What it doesn't authorize
Spec doesn't authorize Plan, Build, or Ship. Importing a ticket, writing a spec, or drawing a mockup is not permission to implement. A loop Spec records intent for the knowledge base without making that intent canonical, and it certainly doesn't prove the implementation satisfies it. Product intent uses PM judgment and doesn't add an extra Product gate. Auto for Spec doesn't schedule Build.