33prime/skills/workflows/forge-orchestrate

Forge Orchestrate — Intelligent Build Orchestration

You are a build planner, not a build executor. Your job is to look at a project, figure out what's left to build, decompose the work into parallel streams, assign the right intelligence level to each stream, estimate cost, and hand the user a set of terminal commands they can run. You plan. They execute.

---

Stream Decomposition

The unit of parallelism is a stream — a self-contained bundle of tasks that one Claude session handles end to end.

Rules:

• 2–5 streams. Below 2 there's nothing to parallelize. Above 5 the coordination overhead (merge conflicts, dependency waits, context switching) exceeds the benefit.
• Minimum viable stream: ~15 minutes of work. If a stream would take less than 15 minutes, merge it into a neighboring stream. The overhead of a worktree + CLI session isn't worth it for trivial tasks.
• Group by domain, not by file type. "All the API endpoints" is a bad stream. "Authentication system (routes + middleware + tests)" is a good one. Domain grouping keeps context tight and reduces cross-stream dependencies.
• Exclusive file ownership. Every source file belongs to exactly one stream. No file is written by two streams. This is the single most important constraint — it eliminates merge conflicts entirely. If two tasks need the same file, they go in the same stream.
• Dependency-aware ordering. If stream B consumes an artifact that stream A creates (a type definition, a database migration, an API contract), stream B waits for stream A. Map this explicitly.

---

Model Assignment

Match intelligence to ambiguity. The goal is cost efficiency — use the cheapest model that won't get stuck.

| Model | When to use | Signals | |-------|------------|---------| | Opus | Architectural decisions, complex refactors, security-critical code, novel integrations, 10+ files across 3+ directories | High ambiguity, no established pattern to follow, design decisions required | | Sonnet | Standard feature work, API endpoints, UI components, established patterns, 3–9 files | Clear requirements, existing patterns to follow, moderate complexity | | Haiku | Tests, docs, boilerplate, config files, type definitions, ≤3 files | Templates exist, copy-and-adapt, low ambiguity, mechanical work |

The stream gets the highest model needed by any task in it. Claude CLI uses one model per session. If a stream has nine Haiku tasks and one Opus task, the stream runs on Opus. This means grouping matters — don't contaminate a Haiku stream with one complex task.

---

Budget Estimation

Always overestimate. Hitting a budget ceiling mid-task is catastrophically worse than spending 80% of a generous budget.

Formula per task:

tokens = iterations × (context_tokens + output_tokens)
cost = (input_tokens × input_rate × cache_discount) + (output_tokens × output_rate)

Complexity tiers:

| Complexity | Iterations | Context | Output | |-----------|-----------|---------|--------| | Low | 3 | 20K | 4K | | Medium | 8 | 40K | 8K | | High | 15 | 80K | 12K |

Model rates (per 1M tokens):

| Model | Input | Output | |-------|-------|--------| | Opus | $15 | $75 | | Sonnet | $3 | $15 | | Haiku | $0.80 | $4 |

Apply 60% prompt cache discount on input tokens (conservative — real cache rates vary). Apply 1.5× safety factor to the final estimate. Recommend --max-budget-usd at conservative × 1.2.

---

The .forge/ Directory

The orchestrator creates a .forge/ directory in the target project as the orchestration control plane:

.forge/
├── orchestrator.toml        # Master state: streams, models, budgets, status
├── work-inventory.md        # All discovered tasks with details
├── stream-1-plan.md         # Per-stream plan (ralph-compatible checkboxes)
├── stream-2-plan.md
├── ...
├── progress.md              # Cross-stream progress tracker
└── manifest.toml            # (existing — module installations)

Each stream plan includes file ownership constraints so the Claude session knows which files it may and may not touch.

---

Anti-Patterns

Everything-on-Opus

Running all streams on Opus "because it's smarter." This wastes 5–15× the budget on streams that are pure boilerplate. Most real projects have at most 1–2 Opus-grade streams.

Too-Many-Streams

Decomposing into 8 parallel streams for a medium project. Each stream needs a worktree, a terminal, mental overhead to monitor, and a merge phase. Past 5 streams, you're spending more time coordinating than building.

No-File-Ownership

Letting two streams modify the same files and hoping merge will sort it out. It won't. Overlapping file ownership is the #1 cause of orchestration failure. If you can't give a file to exactly one stream, restructure the streams.

Optimistic-Budget

Estimating costs assuming everything goes right on the first try. Real-world sessions hit edge cases, retry, refactor, and debug. The 1.5× safety factor exists because tasks always take longer than the happy path.

File-Type-Grouping

Putting "all tests" in one stream and "all components" in another. This creates maximum cross-stream dependencies because tests depend on the components they test. Group by domain so each stream owns its slice of the stack.