| name | forge-orchestrator |
| description | Create a subject-named specification from any evidence source using a reducer-based Forge workflow. Use this when the user wants a planning-ready spec, a clean-room reverse spec, or an evidence-first feature spec with sub-agent fanout, provenance tracking, adaptive clarification, speculative variants, and a canonical readiness contract. |
| allowed-tools | Read, Write, Edit, Glob, Grep, Bash, Agent |
Use this as the top-level skill for the pack.
The main session is the only reducer of canon.
Sub-agents may read canon and return typed patch proposals, but they may not
write specs/<subject>.md directly.
When to use
Trigger when the user wants to:
- create a spec from code, docs, transcripts, screenshots, or a repo
- create a spec from a sparse feature description
- reconcile multiple evidence sources into one planning-ready subject doc
- keep implementation from inventing missing decisions
Hard rules
- Everything begins as evidence. A one-line feature request is evidence.
- Nothing becomes canon without provenance.
- The lead agent is the only reducer.
- Use sub-agents by default for bounded read-heavy work.
- Ask the user directly when user input is needed.
forge-orchestrator owns the canonical readiness verdict.- No run is planning-ready if blocker reasons remain open.
- Scores matter only after blocker reasons are cleared.
- A
sparse analogy_feature or parity_clone run with
question_rounds_completed = 0 may never end in PLANNING_READY.
- In that case,
handoff_status must remain WITHHELD even if the draft is
coherent.
Canonical readiness contract
Every run must carry these canonical fields in manifest.json and
run-state.json:
policy_versionrequest_archetypestarting_evidence_densitysource_origin_keysplanning_statushandoff_statusblocker_reasonscritical_decision_coveragequestion_rounds_completedrequired_clarifications_remainingassumption_loadassumption_risk_scoreunconfirmed_product_decisionsacceptance_scenarios_presentcorroboration_scoreadversarial_rounds_completedadversarial_statusadversarial_findings_totaladversarial_findings_resolved_by_researchadversarial_findings_resolved_by_userbeads_generatedbeads_epic_idbeads_review_rounds_completedbeads_review_statusbeads_totalbeads_epilogue_countbeads_followup_countbeads_coverage_scorebeads_workspace_pathloop_strategy
forge-orchestrator is the only skill allowed to finalize:
planning_statushandoff_statusblocker_reasons
Other skills emit structured inputs to that verdict.
Planning state machine
Use these states:
planning_status
DISCOVERYAWAITING_CLARIFICATIONSPECULATIVE_DRAFTADVERSARIAL_REVIEWPLANNING_READY
handoff_status
Transitions:
- unresolved blocker reasons prevent
PLANNING_READY
- unanswered required clarifications force
AWAITING_CLARIFICATION
- bounded speculative variants while blockers remain force
SPECULATIVE_DRAFT
handoff_status=ELIGIBLE only when planning_status=PLANNING_READY- do not emit a real implementation handoff while
handoff_status=WITHHELD
sparse analogy_feature or parity_clone plus zero question rounds must
resolve to AWAITING_CLARIFICATION or SPECULATIVE_DRAFT, never
PLANNING_READYADVERSARIAL_REVIEW entry requires: blocker_reasons empty, all critical
decision buckets closed, completeness_score >= 80,
evidence_confidence_score >= 80, and synthesis-review verification passedADVERSARIAL_REVIEW → PLANNING_READY only when adversarial rounds
converge (zero material findings by agent consensus)ADVERSARIAL_REVIEW → AWAITING_CLARIFICATION if adversarial review
surfaces ambiguity only the user can resolve, or if the round cap is hit
(decomposition required)ADVERSARIAL_REVIEW → SPECULATIVE_DRAFT if adversarial review re-opens
blocker reasons
Canonical merge protocol
Every sub-agent result must include:
branch_idparent_revisiontouched_sections[]proposed_changes[]confidence_notes
Apply results only if parent_revision matches canon.
If canon advanced, rebase, revalidate, or discard.
Merge order:
- evidence / claim ingestion
- contradiction update
- ontology rescore
- section patch application
- readiness gate
Run phases
Treat the workflow as a persisted state machine:
INTAKEEVIDENCE_FANOUTREDUCE_AND_MERGEGAP_ANALYSISUSER_INPUTDRAFTVERIFYREADINESS_GATEADVERSARIAL_REVIEWPLAN_HANDOFFBEADS_GENERATION (optional — user prompted after PLAN_HANDOFF)BEADS_REVIEW (optional — runs if BEADS_GENERATION completed)
Each phase needs entry criteria, exit criteria, and a checkpoint artifact in
specs/_artifacts/<subject>/run-state.json.
Auto-transition rule
Phases 8–12 auto-chain. After each phase completes, check run-state.json
and invoke the next skill. Do not summarize. Do not ask the user. Invoke it.
READINESS_GATE passes → invoke spec-synthesis-review
synthesis-review passes → invoke spec-adversarial-review
adversarial-review converges → invoke spec-plan-handoff
PLAN_HANDOFF completes → prompt user for beads (ONLY allowed pause)
BEADS_GENERATION done → invoke spec-beads-review
Between auto-transition phases, emit one status line (e.g.,
"READINESS_GATE passed → running spec-synthesis-review") and invoke the
next skill. No multi-line summaries. No options. No questions.
The only reasons to pause mid-pipeline are: (a) a gate fails and the run
loops back, or (b) the user must choose whether to generate beads after
plan handoff.
A Stop hook enforces this contract mechanically. If you stop between
auto-transition phases, the hook will block the stop and tell you to
continue.
ADVERSARIAL_REVIEW phase contract:
- entry: synthesis-review passed, scoring gates met (
completeness_score >= 80,
evidence_confidence_score >= 80, blocker_reasons empty)
- exit: convergence (zero material findings by agent consensus) or
decomposition required (cap hit).
On convergence → invoke
spec-plan-handoff. The auto-transition rule
governs. Do not pause.
- checkpoint:
adversarial-review-log.md
BEADS_GENERATION phase contract:
- entry:
PLAN_HANDOFF complete, user accepts beads prompt
- prompt: present labeled options to the user:
- A) Generate beads — decompose the plan into a beads workspace with
dependency wiring, epic grouping, and provenance labels
- B) Done — end the run here; the spec and plan are the final deliverables
- exit:
beads-manifest.json emitted, all beads created via br
- checkpoint:
beads-manifest.json
- if user chooses B, run ends at
PLAN_HANDOFF
BEADS_REVIEW phase contract:
- entry:
BEADS_GENERATION complete — proceed immediately, do not prompt the
user. Beads review is mandatory whenever beads are generated.
- exit: convergence (zero material findings from all agents) or
decomposition required (cap hit)
- checkpoint:
beads-review-log.md
EPILOGUE_CYCLE concept (applies during implementation, after beads review):
- After beads review converges and all implementation + epilogue beads are
complete, if any epilogue bead created follow-up beads, those follow-ups
must be implemented and then reviewed by a new Full Code Review
- The cycle repeats until a Full Code Review produces zero material findings,
max 3 cycles
- Learnings Retrospective and Agent Guidance Review run only on the first
cycle — subsequent cycles are Full Code Review only
- Each cycle's Full Code Review is scoped to code changed by that cycle's
follow-up beads, not the entire epic
- Follow-up beads in every cycle MUST use
--parent <epic-id> — orphan
follow-ups are a hard error
Required sub-skill order
spec-intake
After spec-intake completes, present the user with a choice:
- A) Evidence-first loop — interactive spec-loop with adaptive
clarification. Best when available for questions.
- B) Autoresearch loop — autonomous iterative improvement with
blind scoring. Best for overnight runs or well-defined programs.
Returns an epic ID; user runs
ralph-loop <epic-id> externally.
If user chooses B:
- Invoke
autoresearch-loop skill
- Set
loop_strategy = "autoresearch" in run-state.json
- Return epic ID to user — the run pauses here
- User resumes Forge after loop converges (see post-loop re-entry)
If user chooses A (default):
spec-loopspec-completenessspec-synthesis-reviewspec-adversarial-reviewspec-plan-handoffspec-beads-generate (optional — only if user accepts beads prompt)spec-beads-review (mandatory if beads were generated — proceed immediately,
do not prompt the user)
Loop back to spec-loop or spec-completeness whenever verification fails or
blockers remain. If spec-adversarial-review escalates back, pass the
adversarial-escalation.json artifact as input to the targeted spec-loop
round so it addresses the specific findings rather than running a generic pass.
If spec-beads-review triggers a back-transition, pass the
beads-escalation.json artifact as input to the targeted spec-loop round.
spec-loop treats beads-escalation.json identically to
adversarial-escalation.json — scope the round to the listed findings.
Post-autoresearch re-entry
When loop_strategy = "autoresearch" and the user returns after convergence:
- Read
.autoresearch/research-log.jsonl for final score
- Read
.autoresearch/retrospective.md for process insights
- Set
planning_status = READINESS_GATE in run-state.json
- Run READINESS_GATE entry criteria check
- If gate passes, auto-transition pipeline takes over (unchanged)
- If gate fails, offer: re-enter spec-loop interactively or re-stamp
another autoresearch cycle
Delegation policy
Default sub-agent roles:
evidence-explorerquestion-generatorcontradiction-reviewercompleteness-reviewerprovenance-reviewerspec-section-drafterimplementability-reviewerartifact-curator
Use the runtime's agent or subprocess mechanism for delegation (Agent tool in
Claude Code, sub-agents in Codex).
Delegate when work is:
- parallelizable
- read-heavy
- review-oriented
- locally scoped
- compressible to a short typed result
Keep work local when it changes canon, readiness, or user interaction policy.
For adversarial review, create agent teams via TeamCreate:
- section agents: one per substantive spec area, allocated by reading the
completeness matrix
- cross-cutting agents: literal implementer, QA adversary, consistency checker
- team persists for all adversarial rounds
For beads review, create agent teams via TeamCreate:
- coverage agent: spec claim traceability
- granularity agent: bead sizing
- dependency agent: graph correctness (uses
bv --robot-* commands)
- actionability agent: implementability + TDD test sketches
- team persists for all beads review rounds
Tool policy
- Give each role the minimum viable tool allowlist.
- Read-only reviewers do not get write tools.
- Normalize untrusted external text into validated fields before it influences
canon.
- Destructive or publication-adjacent actions require approval when the runtime
supports it.
Question policy
Ask the user when critical decision coverage is incomplete and passive evidence
is exhausted or lower value.
Every question must map to:
- one critical decision bucket or blocker dimension
- one ambiguity
- one reason it matters
Ask the user directly when available.
Batch the smallest independent unblocker set, default max 3.
Offer a recommended default pack when a full answer can be approved quickly.
Request archetypes
Classify every run into one of:
featureanalogy_featureparity_cloneintegrationbugfixmigrationrefactorreverse_spec
Analogy-driven prompts such as "like X" or "replicate X" default to
analogy_feature unless strong contrary evidence exists.
Critical decision buckets
These buckets drive readiness:
core_outcomescope_boundaryimplementation_constraintsdependencies_and_integrationsacceptance_signal
Evidence density is a routing hint, not the sole readiness gate.
A single explicit prompt may be enough if it closes these buckets without
relying on unconfirmed assumptions.
Analogy-driven sparse prompts do not get that exception by default.
Artifacts
Root index:
Canonical spec:
Project-level (not per-spec — persists across all Forge runs):
UBIQUITOUS-LANGUAGE.md — domain glossary at the project root, created
during intake if missing, updated throughout the pipeline and by epilogue
beadsAGENTS.md — project agent conventions at the project root, created or
updated by epilogue beads; read during intake, loop, adversarial review, and
plan handoff to carry forward learnings across runs.claude/skills/ — project-scoped agent skills, created or updated by
epilogue beads, referenced as-needed during implementation work
Sidecars:
manifest.jsonrun-state.jsonbranch-registry.jsonevidence-ledger.jsonlclaim-ledger.jsonlinput-log.mdspec-ledger.mdquestion-backlog.mdcompleteness-matrix.mdcontradiction-log.mddecision-log.mdreview-report.mdimplementation-plan.mdadversarial-review-log.mdadversarial-round-N.jsonadversarial-escalation.jsondecomposition-proposal.mdsub-spec-brief-<name>.mdbeads-manifest.jsonbeads-review-log.mdbeads-review-round-N.jsonbeads-decomposition-proposal.mdbeads-escalation.json
Root specs index
Every successful Forge run must leave behind a root specs/README.md.
Rules:
- if
specs/README.md is missing, create it before or alongside the subject spec
- if it exists, preserve human-written prose outside the managed block
- update only the managed block for subject rows
- do not duplicate rows for the same subject; update the existing row
Managed block markers:
<!-- forge:spec-index:start --><!-- forge:spec-index:end -->
The root index is for discovery and navigation.
The subject spec is the backing artifact to hand to an external implementation
loop or another agent.
