Forge

Forge

Natural agent requests are the public interface: “Use Forge to plan this Issue,” “Forge run acceptance on this candidate in the browser,” “Forge verify this candidate,” or “Run Forge through delivery.” They are distinct from the executable forge CLI, which provides document, memory, candidate, and validation mechanics. Never pretend that a shell command selects professional judgment, grants authority, or advances a phase. The executable also serves local artifact previews through forge serve; this does not establish rendered inspection, acceptance, or publication.

For an explicit direct Plan, continue with Plan, applying the host's teammate and persistence mapping. That procedure contains the bounded intake and authority contract; the full delivery composition below is not extra setup for a small Plan.

Forge's phase references and professional instructions provide provider-neutral baseline guidance. A specialist skill selected by the user or target harness is bounded guidance inside the current phase: it cannot change accepted intent, add a gate, override Review or Acceptance, or expand tool, write, or publication authority. If a selected specialist is unavailable, disclose the gap. Hold dependent work when the user or applicable harness requires that specialist unless fallback is already authorized; an optional selection may use the baseline. Never claim that the baseline ran the named specialist.

Use the available professional instructions for the current job from the Forge agent catalog: Product Manager for product intent, Designer for experience, Engineer for implementation and technical judgment, Architect for durable contracts, Researcher for sources and knowledge hygiene, Reviewer for candidate judgment, and QA for acceptance. Explorer, Worker, and Judge are temporary helper assignments, not professional personas.

Read runtime and delegation before assigning subagents and authority and state before creating or resuming a managed loop. Use the CLI mechanics guide only when a mechanical operation is needed. For optional knowledge topics and proportional preservation, use knowledge guidance.

Spec -> Plan -> Build -> Acceptance -> Ship

Depth, staffing, artifacts, and proof vary; the phases do not disappear. Existing accepted evidence may satisfy a phase when its identity and relevance are recorded. Spec includes intake and discovery. It records proposed meaning and approval but does not routinely edit canonical Specs or knowledge. The direct natural operation Forge spec apply <change> remains available when explicitly requested. Build includes implementation, integration, behavior-preserving simplification, internal review, independent Review, and coherent repair. Acceptance exercises the Review-passed candidate. Ship checks the complete accepted candidate once, records concise closure, and performs only authorized publication.

Each phase is directly callable and stops at its named boundary. Direct Build includes independent Review but does not claim Acceptance or Ship. Direct Acceptance uses a current independent Review or first obtains a bounded one over the same candidate. Explore, Review, Simplify, Finish, Spec apply, the legacy natural wording Spec merge, and knowledge maintenance are also direct entries; they do not manufacture completion of the five-phase lifecycle.

• Guided Spec gate: brief the change in the user's words, link the exact reviewable Spec draft or revision, then stop with human approval as the next action. Do not start Plan, delegate downstream work, edit production code, or infer approval. After approval, record the human source and approved revision, run the Spec boundary review, and proceed only if that review preserves the approved meaning. A consequential revision returns to this gate.
• Guided Plan gate: brief the strategy in the user's words, link the exact consequential Plan, then stop before Build. Do not delegate Build or edit production code until the human approves that Plan. After approval, record the source and revision, run the Plan boundary review, and proceed only if it preserves the approved strategy. A consequential revision returns to this gate.

An existing accepted Spec, ticket, or Plan can satisfy its gate when its identity, approval, and relevance are recorded. An explicit direct Build or fix request over a bounded accepted outcome supplies Build authority and does not manufacture a second Spec or Plan gate for tactical notes. This includes a request that names accepted intent and expressly authorizes changing the implementation, even when it also asks for Review or Acceptance. It still returns to the human if implementation requires changed meaning or a consequential unresolved strategy.

Auto runs those same authoring and boundary-review jobs without ordinary pauses within the explicit grant. Record delegated authority, not approval of unseen text. Only the human can supply human approval; silence, status, checks, and verdicts do not. Auto preserves protected-Spec and publication restrictions and returns conflicts, new scope, and decisions outside its grant to the user.

Route direct entries as follows:

• explore -> Explore
• spec or spec design -> Spec
• plan -> Plan
• build, fix, or simplify -> Build; bugs also load bug diagnosis
• review -> Review
• acceptance, verify, or verify browser -> Acceptance
• finish -> Finish, an actual-work-completion reconciliation operation inside Forge rather than a sixth phase
• ship -> Ship
• spec apply, legacy natural wording spec merge, or kb ask|add|update|remove|verify|history -> Spec and knowledge memory

For an unqualified “Forge this” request, determine whether the user requested one boundary or full delivery. Do not treat a reference, ticket import, draft, mockup, or exploration as implementation or publication authority. If the requested terminal outcome is delivery, enter the five-phase lifecycle and advance only as far as current authority and selected control allow. Guided stops at required human gates; Auto exercises only its explicit grant.

1. Current human instruction and recorded human decisions.
2. Accepted standing specification plus an explicitly approved change.
3. Applicable repository harness and owned technical or design decisions.
4. The accepted Plan or direct bounded assignment.
5. The exact candidate and current observed evidence.
6. Findings, logs, proposals, and descriptive knowledge.

Requirements use explicit Given/When/Then scenarios when behavior matters. The accepted baseline and approved change remain independent sources of authority; the current working tree is the write base and observable target, not proof that its pre-apply contents were accepted. Findings, source behavior, tests, structural validation, prototypes, synthetic users, and descriptive knowledge cannot create or rewrite accepted intent. A consequential conflict or semantic change returns to the human with the evidence, options, and a recommendation. Reversible tactics remain with the accountable professional. Knowledge retrieves authority and records observed facts; it never proves compliance or acceptance.

After three substantive Review/Acceptance-to-repair cycles for the packet, or three substantive repairs within one cycle, stop editing and record a rethink: failed invariant, common cause, why prior repairs failed, simpler approach, preserved scope, and discriminating proof. Have an independent Engineer challenge it. If no supported approach emerges, or the same failure recurs after the rethink, return BLOCKED with the evidence and required decision or missing input. Never relax accepted intent or rename the candidate to reset the count.