forge-orchestrator
Skill0 starsChanged 9 months agoMITView on GitHub
Master orchestrator that sequences forge-research and forge-builder through milestone-gated cycles with adversarial review, testing, brainstorming, and compound learning. Designed for long-running autonomous sessions. Invoke with /forge [goal]. Do NOT use for single research questions (use forge-research) or simple builds (use forge-builder).
1 other project uses a version of this.
Adopted by
Most recently taken up by
- cedricgnans/forge-solotheir own version, first seen Aug 19, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 1
- cedricgnans/forge-solo★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository17 other files it gives its agents.
- AGENTS.mdAGENTS.md
- auditing-skillsSkill
- creating-skillsSkill
- forge-builderSkill
- forge-claude-teamsSkill
- forge-codex-multiagentSkill
- forge-researchSkill
- handoff-freshSkill
- handoffSkill
- managing-doc-manifestSkill
- okfSkill
- pickupSkill
- studySkill
- syncing-docsSkill
- testing-skillsSkill
- updating-skillsSkill
- wrapSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
26 rules. About 0 are common, 17 are distinctive, and 9 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈17
Distinctive · estimate
This author's own choices. Worth a look.
9
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 130
Test review: coverage gaps, missing scenarios
- Distinctive: line 160
All critical review findings addressed
- Distinctive: line 175
Before codifying learnings, verify that what was built actually matches what was requested:
- Very specific: line 182
Check for "merged" items: if a todo was merged into another, verify the merged item's implementation covers the original acceptance …
- Distinctive: line 183
Check for pinned requests: if the user requested the same thing twice or more, it is pinned critical — cannot be closed without all three …
- Very specific: line 184
Write reconciliation result to architect/review-findings/{milestone}-goal-reconciliation.md
- Distinctive: line 195
After gate passes, codify learnings:
- Distinctive: line 196
Update CLAUDE.md with conventions/patterns discovered this milestone
- Distinctive: line 198
Check SUGGESTIONS.md for human feedback:
- Distinctive: line 202
Update TODO.md with deferred items and next steps
- Distinctive: line 203
Update FORGE-MEMORY.md with learnings (minimum-signal gate: "Will a future agent act better knowing this?")
- Distinctive: line 204
Update FORGE-STATUS.md with current state
- Distinctive: line 205
Update FORGE-HANDOFF.md (full checkpoint)
- Distinctive: line 207
Transition to next milestone immediately: Read the next milestone's scope from TODO.md right now.
- Distinctive: line 211
If this is the last milestone, proceed to Step 3.
- Very specific: line 259
Write handoff to architect/agent-contexts/{name}.md for workers.
- Very specific: line 267
Use general-purpose for thread coordinators or tasks that don't match a custom agent
- Distinctive: line 294
Check FORGE-STATUS.md on startup.
- Distinctive: line 297
Resume: read FORGE-STATUS.md, pick up from last phase transition
- Very specific: line 315
If changed: parse ## New / ## Active Directives for unprocessed items
- Distinctive: line 317
Update hash in FORGE-STATUS.md
- Distinctive: line 335
When a global limit is hit: save state, present summary, ask user to continue or stop.
- Very specific: line 350
When spawning build agents with FILE SCOPE declarations, the orchestrator writes the scope to .claude/forge-scopes.json:
- Very specific: line 382
Create or update .claude/settings.local.json with the PreToolUse hook entry:
- Very specific: line 401
If .claude/settings.local.json already exists, merge the PreToolUse entry rather than overwriting.
- Very specific: line 417
Never retry a crashed agent — spawn fresh.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Forge Orchestrator
Sequences research and building through milestone-gated cycles with review, improvement, and compound learning.
Workflow Overview
- [ ] 1. Intake and orientation → produces: milestones in TODO.md, CLAUDE.md updated
── GATE A: milestones defined + platform practices read ──
- [ ] 2. For each milestone:
RESEARCH → PLANNING
── GATE B: reviewed plan exists before code changes ──
→ BUILD → REVIEW → SECOND-OPINION
── GATE C: review findings serialized before improvement ──
→ IMPROVEMENT → QUALITY GATE
── GATE D: gate passed before goal reconciliation ──
→ GOAL RECONCILIATION
── GATE E: all acceptance criteria have evidence before learning codification ──
→ COMPOUND
- [ ] 3. Finalization → produces: completion summaryStep Completion Protocol
Every phase must produce visible output before the next phase begins. GATE markers are hard checkpoints.
- GATE A (after Step 1): Milestones must be written to TODO.md and platform practices must be read. If you haven't parsed milestones or read the practices guide, STOP.
- GATE B (after PLANNING, before BUILD): A reviewed implementation plan must exist. If the adversarial reviewer hasn't critiqued the plan, STOP — building without a reviewed plan is the #1 cause of rework.
- GATE C (after REVIEW + SECOND-OPINION, before IMPROVEMENT): All review findings must be collected and serialized to
architect/review-findings/. If you haven't fanned out reviewers, STOP — skipping fresh-context review eliminates 40-60% of quality improvement. - GATE D (after QUALITY GATE, before GOAL RECONCILIATION): The quality gate must have passed. If the gate hasn't been evaluated, STOP — ungated work codifies bad patterns.
- GATE E (after GOAL RECONCILIATION, before COMPOUND): Every acceptance criterion must have code evidence and test evidence. If any criterion lacks evidence, STOP — codifying completion on unverified work propagates false confidence to future milestones.
Why gates matter: Without them, the natural tendency is to shortcut from BUILD directly to the next milestone, skipping review (the primary quality mechanism), improvement (the fix application), and compound (the learning codification). Each shortcut degrades output quality and compounds across milestones.
Step 1: Intake and Orientation
a. Read FORGE-HANDOFF.md if it exists (resumption). Follow the Bootstrap sequence in it b. Read FORGE-STATUS.md, CLAUDE.md, TODO.md, FORGE-MEMORY.md, architect/ if they exist c. If none exist: create CLAUDE.md and TODO.md from project scan d. Platform detection:
- Claude Code (Agent/TeamCreate tools present) → read forge-claude-teams SKILL.md
- Codex CLI (spawn_agent/AGENTS.md present) → read forge-codex-multiagent SKILL.md
- Fallback: assume Claude Code, log warning e. Create HUMAN-INPUT.md, MISSION-CONTROL.md, FORGE-HANDOFF.md templates if missing (see steering-templates.md and state-templates.md) f. Check HUMAN-INPUT.md and MISSION-CONTROL.md for pre-existing directives g. Parse goal into milestones (see milestone-template.md)
- Open-ended goals ("make this better"): scan codebase, identify top 5-10 improvements, present for user approval before proceeding
- Concrete goals: structure into milestones directly
h. Write initial plan to TODO.md
i. Add forge sections to CLAUDE.md (see claude-md-sections.md)
j. Add forge artifacts to .git/info/exclude:
FORGE-STATUS.md,FORGE-HANDOFF.md,FORGE-MEMORY.md,HUMAN-INPUT.md,MISSION-CONTROL.md,SUGGESTIONS.md,DEFERRED-CHANGES.md,architect/agent-contexts/,architect/review-findings/,.claude/forge-scopes.jsonk. Create.claude/forge-scopes.jsonwith empty agents map:{"agents": {}}l. Install scope guard hook: copy.claude/skills/forge-orchestrator/hooks/forge-scope-guard.shto.claude/hooks/forge-scope-guard.sh, make executable, and add PreToolUse hook entry to.claude/settings.local.json(see Scope Guard Installation below)
GATE A checkpoint: Do not proceed to Step 2 unless you have (1) parsed the goal into milestones written to TODO.md, (2) read the platform practices guide, and (3) created all steering file templates. If any of these are missing, go back now.
Step 2: Milestone Loop
CHECK HUMAN-INPUT.md, MISSION-CONTROL.md, and SUGGESTIONS.md AT EVERY PHASE TRANSITION.
RESEARCH PHASE
- Launch forge-research for unknowns in the current milestone
- Research runs to completion before building starts
- Output:
architect/research/{topic}.md - Skip if milestone has no research needs
PLANNING PHASE (complexity-adaptive)
Complexity tiers:
- Simple (single file, clear spec): skip detailed planning, inline approach notes
- Standard: concise approach with key decisions
- Complex (multi-file, unknowns, architectural): detailed plan with >=2 approaches + trade-offs
Steps:
- Draft implementation plan for this milestone
- Self-critique the plan
- Spawn adversarial reviewer: "Find flaws in this plan"
- Iterate until no CRITICAL/HIGH findings remain (max 3 iterations)
- MEDIUM and LOW findings are acceptable — note for implementation awareness
GATE B checkpoint: Do not proceed to BUILD unless you have a reviewed implementation plan. If the plan has not been self-critiqued AND adversarially reviewed (for standard/complex milestones), STOP — building without a reviewed plan is the #1 cause of rework across milestones.
BUILD PHASE
- Launch forge-builder with the refined plan
- Builder executes with self-review and self-improvement loops
- Builder writes completion signal when done
- Orchestrator waits for completion before proceeding
REVIEW PHASE (parallel fan-out, FRESH context)
CRITICAL: All review agents run in FRESH context. They receive ONLY:
- The milestone spec/requirements
- The git diff of changes
- Relevant test results
They do NOT receive the builder's conversation history. Fresh-context review avoids confirmation bias (40-60% quality improvement per ASDLC research).
Batch 1 (up to 4 parallel — critical reviews):
- Adversarial review: bugs, logic errors, security issues
- Feature-presence review: verify each acceptance criterion has corresponding code paths and tests
- Performance review: inefficiencies, bottlenecks
- Test review: coverage gaps, missing scenarios
Batch 2 (after batch 1 — enhancement reviews):
- Documentation: update/create docs for changes made
- Brainstorm: improvements, optimizations
Orchestrator collects all findings and serializes to architect/review-findings/{milestone}.md.
SECOND-OPINION PHASE (optional)
- Try other CLIs if available (Codex, Gemini, Claude). Send git diff + intent
- Skip unavailable CLIs gracefully. Note which were unavailable
- Common case: all unavailable → skip entirely, note in summary
GATE C checkpoint: Do not proceed to IMPROVEMENT unless review findings are collected and serialized to
architect/review-findings/{milestone}.md. If you have not fanned out review agents in fresh context, STOP — skipping fresh-context review eliminates 40-60% of quality improvement. The review fan-out is the orchestrator's primary quality mechanism.
IMPROVEMENT PHASE
- Consolidate all review findings
- Classify each finding:
- Bug fix → apply immediately
- Improvement (existing functionality) → apply
- New feature → write to SUGGESTIONS.md, do not implement
- Launch forge-builder with consolidated fixes and improvements
- Re-run quality gates after improvements
QUALITY GATE
Pass criteria (ALL must hold):
- Tests pass
- All critical review findings addressed
- No regressions
- Diminishing returns check: did this cycle improve substantially over last?
Outcomes:
- Pass → proceed to GOAL RECONCILIATION GATE
- Fail → loop back to BUILD PHASE (max 2 retries per milestone)
- Fail after 2 retries → escalate to user with details
GATE D checkpoint: Do not proceed to GOAL RECONCILIATION unless the quality gate has been explicitly evaluated and passed. If you are about to reconcile goals or move to the next milestone without a gate evaluation, STOP — ungated work codifies bad patterns that propagate to all future milestones.
GOAL RECONCILIATION GATE
Prevents false completion — the #1 cause of user trust erosion.
Before codifying learnings, verify that what was built actually matches what was requested:
- Extract acceptance criteria from the milestone spec in TODO.md
- For each criterion, require:
- Code evidence: file:line where the behavior is implemented
- Test evidence: named test that validates the behavior
- Runtime evidence (if applicable): screenshot, log output, or manual verification note
- Check for "merged" items: if a todo was merged into another, verify the merged item's implementation covers the original acceptance criteria. Merged ≠ Complete — status stays
in_progressuntil behavior ships - Check for pinned requests: if the user requested the same thing twice or more, it is pinned critical — cannot be closed without all three evidence types
- Write reconciliation result to
architect/review-findings/{milestone}-goal-reconciliation.md
Outcomes:
- All criteria have evidence → proceed to COMPOUND
- Any criterion lacks evidence → loop back to BUILD PHASE with the unmet criteria as the scope (max 1 retry)
- Retry exhausted → escalate to user: "These acceptance criteria have no implementation evidence: {list}"
GATE E checkpoint: Do not proceed to COMPOUND unless every acceptance criterion has code + test evidence mapped in the goal reconciliation artifact. If you are about to codify learnings or move to the next milestone without verifying criteria, STOP — unverified completion is the #1 cause of user trust erosion and compounds across milestones.
COMPOUND STEP
After gate passes, codify learnings:
- Update CLAUDE.md with conventions/patterns discovered this milestone
- Consolidate SUGGESTIONS.md (deduplicate, sort by confidence)
- Check SUGGESTIONS.md for human feedback:
- Approved → add as new milestones or append to upcoming milestone scope
- Rejected → mark status
rejected, skip - Needs-revision → incorporate comments, refine plan, mark
planned
- Update TODO.md with deferred items and next steps
- Update FORGE-MEMORY.md with learnings (minimum-signal gate: "Will a future agent act better knowing this?")
- Update FORGE-STATUS.md with current state
- Update FORGE-HANDOFF.md (full checkpoint)
- Git commit milestone output
- Transition to next milestone immediately: Read the next milestone's scope from TODO.md right now. Do NOT produce a standalone summary between milestones — on Codex CLI, a text-only response (no tool calls) ends the turn and halts the orchestration. The summary is implicit in the state files you just updated. If this is the last milestone, proceed to Step 3.
Step 3: Finalization
a. Run full test suite
b. Update CLAUDE.md with what was built
c. Update TODO.md with completion status
d. Consolidate SUGGESTIONS.md (deduplicate, reconcile, sort by confidence)
e. Generate summary: what was done, what was deferred, what needs human attention
f. Update FORGE-STATUS.md with final state
g. Cleanup: delete architect/agent-contexts/, architect/review-findings/, DEFERRED-CHANGES.md
Milestone Structure
Each milestone has explicit per-step success criteria. Without them, agents frequently skip steps or declare premature completion.
Reference: milestone-template.md
Parallelism Model
Parallelized serial threads — parallel THREADS each running sequential work internally.
| Pattern | Parallelism | Rationale |
| Independent milestones | Parallel threads (2-3 max) | Each thread owns its files |
| Phases within a milestone | Sequential within thread | Context accumulation, data deps |
| Build agents on related files | Sequential within thread | Cascading changes need prior ctx |
| Review/audit after build | Fan-out within thread (3 max) | Independent read-only reviewers |
| Research queries | Fan-out within thread (3-5 max) | Independent info gathering |
| Two threads modifying same file | NEVER | Redesign decomposition |
| Build and review simultaneously | NEVER | Review needs completed code |
| Multiple threads writing same output | NEVER | Orchestrator is single writer |
Agent Spawning Protocol
For every sub-agent:
- Draft context handoff using the 7-tag XML template (see sub-agent-template.md)
- Declare FILE SCOPE: For build agents, add a structured FILE SCOPE block (own/read/deny) to
<boundaries>and write the scope to.claude/forge-scopes.jsonkeyed by the agent's worktree absolute path. Skip for read-only agents (research, review). - Validate: prompt under 4K tokens, end-state objective, parseable output-format
- Write handoff to
architect/agent-contexts/{name}.mdfor workers; inline for quick tasks - Model: inherit (no override, no downgrades)
- Isolation:
"worktree"for build agents; shared for research/review - Agent type: use the specific custom agent for each role:
- forge-build-worker (
.claude/agents/forge-build-worker.md): implementation work with file-scope ownership - forge-research-worker (
.claude/agents/forge-research-worker.md): web research and codebase exploration (read-only) - forge-adversarial-reviewer (
.claude/agents/forge-adversarial-reviewer.md): critical review with confidence gating - forge-performance-auditor (
.claude/agents/forge-performance-auditor.md): metric-driven performance analysis - Use
general-purposefor thread coordinators or tasks that don't match a custom agent
- forge-build-worker (
- Validate output on return (see Sub-Agent Output Quality Bar)
Sub-Agent Output Quality Bar
| Dimension | Pass (2) | Marginal (1) | Fail (0) |
| Schema | Exact match | Minor deviations | Missing sections |
| Evidence | All cited | Some unsourced | No evidence |
| Scope | Within bounds | Minor creep | Significant OOS |
| Completeness | All addressed | Most addressed | Key missing |
| Actionability | Immediately usable | Needs interpretation | Needs rework |
Minimum: 8/10. Score 6-7: request corrections (1 retry). Below 6: re-spawn with revised prompt. Do not surface scores to user — internal quality control only.
Compaction Survival
Reference: compaction-protocol.md
Concurrent Invocation Protection
Check FORGE-STATUS.md on startup. If an active run exists:
- Recent (<1 hour): warn user — "A forge orchestration is in progress. Resume or start fresh?"
- Stale (>1 hour): warn user — "Found abandoned forge run from {timestamp}. Resume or start fresh?"
- Resume: read FORGE-STATUS.md, pick up from last phase transition
- Fresh: archive FORGE-STATUS.md to
FORGE-STATUS.{timestamp}.md, start clean
Human Steering
Three async communication channels (human writes at any time, agent reads at phase transitions):
| File | Direction | Purpose |
| SUGGESTIONS.md | Bidirectional | Agent writes suggestions, human approves/rejects |
| HUMAN-INPUT.md | Human → Agent | New work items, brainstorming ideas |
| MISSION-CONTROL.md | Human → Agent | Steering directives, course corrections |
Change detection: At each phase transition:
- Read the file
- Compare hash against last-seen hash (stored in FORGE-STATUS.md)
- If changed: parse
## New/## Active Directivesfor unprocessed items - Process items, move to
## Processed/## Acknowledged - Update hash in FORGE-STATUS.md
Templates: steering-templates.md
Exit Conditions
| Condition | Threshold |
| Milestone gate pass | Per-milestone criteria |
| Diminishing returns | <10% new actionable findings |
| Quality gate retries | Max 2 per milestone |
| Plan review iterations | Max 3 per milestone |
| Research depth cycles | Max 3 per research campaign |
| User intervention | Save state immediately |
| Global circuit breaker | Max 10 milestones, max 50 agent spawns per run |
When a global limit is hit: save state, present summary, ask user to continue or stop.
Merge Strategy
Worktree branches merge one at a time:
- Dependency order first (if deps exist between agents)
- Completion order for independent agents (first-to-finish merges first)
- Merge conflict → STOP, present to user. Do not auto-resolve cross-agent conflicts
Scope Registry
When spawning build agents with FILE SCOPE declarations, the orchestrator writes the scope to .claude/forge-scopes.json:
{
"agents": {
"/absolute/path/to/.claude/worktrees/agent-name": {
"name": "agent-name",
"owns": ["src/auth/*", "src/middleware/auth.*"],
"readonly": ["src/config/*"],
"deny": ["src/routes/*"]
}
}
}The forge-scope-guard PreToolUse hook reads this file to validate file edits against declared scope. The registry is keyed by worktree absolute path (the agent's cwd).
The orchestrator creates this file during Step 1 (Intake) and updates it each time a build agent is spawned. Read-only agents (research, review) are not added to the registry.
Scope Guard Installation
During Step 1 (Intake), the orchestrator installs the scope guard hook:
- Copy the hook script:
mkdir -p .claude/hooks cp .claude/skills/forge-orchestrator/hooks/forge-scope-guard.sh .claude/hooks/forge-scope-guard.sh chmod +x .claude/hooks/forge-scope-guard.sh - Create or update
.claude/settings.local.jsonwith the PreToolUse hook entry:{ "hooks": { "PreToolUse": [ { "matcher": "Edit|Write", "hooks": [ { "type": "command", "command": ".claude/hooks/forge-scope-guard.sh" } ] } ] } } - If
.claude/settings.local.jsonalready exists, merge the PreToolUse entry rather than overwriting.
The hook is warn-only (exit 0 always). It logs scope violations to stderr, which appears in the agent's conversation as a warning. It does NOT block edits.
Error Recovery
| Failure | Response |
| Agent crash | Spawn FRESH agent with same context + failure note |
| Quality gate fail | Fix → re-gate (max 2) → escalate to user |
| Merge conflict | Present to user, pause orchestration |
| Context overflow | Compaction survival protocol (see reference) |
| All second-opinion CLIs unavailable | Skip phase, note in summary |
Never retry a crashed agent — spawn fresh. Never send_input to a failed agent.
Self-Evolution
Version 1.4.0. See CHANGELOG.md.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

