OpenForge v2#

PRD-to-implementation pipeline for OpenClaw.

OpenForge takes a structured PRD (Product Requirements Document) and executes it through staged phases: parallel where possible, with model routing, quality gates, and automatic review-to-fix loops. No Python, no custom agent registration, no install step — runs entirely through native OpenClaw tools ( sessions_spawn, exec, read, write).

---

What OpenForge Does#

1. Parses a PRD markdown file into phases and tasks
2. Spawns sub-agents for phases that can run in parallel
3. Routes each task to the right model tier (Haiku → Sonnet/GPT → Opus)
4. Gates each phase: pass/fail check after completion
5. Auto-fixes: when a review phase finds issues, a fix agent is spawned and the review re-runs (up to 3 cycles)
6. Escalates when retries are exhausted or a gate fails hard

---

What OpenForge Does NOT Do#

• Does not run a CLI — it IS the agent execution loop
• Does not add an OS-level sandbox beyond the agent's existing workspace constraints
• Does not require or manage custom agent registration

---

Safety & Scope#

• OpenForge operates within the user's configured workspace directory
• Sub-agents inherit the same workspace constraints as the orchestrator
• PRD trust model: PRDs define what code to write and what shell commands to run as gates. Review PRDs before execution — they have the same trust level as code you would run. Do not execute PRDs from untrusted sources.
• Secret safety: Never include secrets, API keys, or credentials in PRD files. PRD content is passed to sub-agents verbatim. OpenForge does not scan for embedded secrets — keep them in environment variables.
• Gate commands: Gate commands are run via exec in the working directory. Only build/test/lint commands are expected — for example: npm test, npm run build, pytest, cargo test, go test, ruff check. Before executing any gate, OpenForge validates that the command does not contain shell metacharacters ( ;, &&, ||, |, $(, backticks, >, <) unless the PRD explicitly marks the phase with Shell-Gate: true. Gates that fail this check are rejected with an error. Review all gate commands in your PRD before execution.
• No credentials are bundled, stored, or transmitted by OpenForge
• All execution is local to the OpenClaw agent environment
• No data is sent to external endpoints beyond your configured AI model providers

---

PRD Format#

A PRD is a markdown file. OpenForge reads it top-to-bottom and extracts phases.

Minimal PRD#

markdown

# PRD: My Feature

## Objective
Build a CSV export endpoint for the API.

## Phases

### Phase: scaffold [parallel]
**Model:** sonnet
**Tasks:**
- Create the route handler in `src/routes/export.ts`
- Write the CSV serializer in `src/lib/csv.ts`

**Gate:** `npm run build` must pass

### Phase: test [depends: scaffold]
**Model:** sonnet
**Tasks:**
- Write unit tests for the CSV serializer
- Write integration test for the export endpoint

**Gate:** `npm test` must pass

### Phase: review [depends: test]
**Model:** opus
**Type:** review
**Tasks:**
- Review the full implementation for correctness, edge cases, and security
- Check error handling on malformed input

**Gate:** Review must find zero blocking issues

PRD Fields#

FieldRequiredValuesMeaningModel:Nohaiku, sonnet, gpt, opusModel tier for this phaseType:Noimpl, review, extractPhase type; controls prompting style[parallel]NoFlag in phase headerPhase can run alongside other [parallel] phasesdepends:NoPhase name(s)This phase waits for named phases to completeGate:NoShell command or descriptionMust pass before next phase startsMax-Retries:NoInteger (default: 2)Gate failure retries before escalationShell-Gate:NotrueAllow shell metacharacters in gate command (use only for trusted, reviewed gates)

Phase Types#

• impl (default) — implementation work; agent writes code, files, configs
• review — evaluative; agent produces a structured findings report; triggers auto-fix loop if issues found
• extract — lightweight parsing or summarization; routed to Haiku

---

Model Routing#

AliasMaps ToUse Forhaiku``claude-haiku / cheapest availableExtraction, parsing, structured outputsonnet``claude-sonnetImplementation, research, multi-file workgpt``gpt-4o or equivalentAlternative implementation pathopus``claude-opusJudgment, review, final quality gate

OpenForge maps these aliases to whatever models are configured in your OpenClaw instance. If a model alias isn't available, Sonnet is used as the safe fallback.

---

Execution Protocol#

When OpenForge is triggered, follow this exact sequence:

Step 1 — Parse the PRD#

Read the PRD file. Extract:

• Title and objective
• All phases in order, with their model, type, dependencies, gate, and task list
• Identify which phases are [parallel] and which have depends: constraints

Build a dependency graph. Phases with no depends: and tagged [parallel] can be spawned simultaneously.

Horizon-Bounded Decomposition: Estimate the total step count across all phases. If the PRD contains > 40 estimated steps, decompose complex phases into sub-phases of ≤ 20 steps each before execution. If 20–40 steps, insert a midpoint quality checkpoint between phases. Under 20 steps, execute directly. This prevents accuracy collapse on long-horizon tasks (research: LORE benchmark shows accuracy → 0 past 120 steps).

Step 2 — Pre-flight check#

Before spawning anything:

• Confirm the PRD has at least one phase
• Confirm all depends: references name real phases
• Confirm the working directory exists (if specified)
• If any check fails: halt and report the problem clearly

Step 3 — Execute phases#

For each wave of phases (phases whose dependencies are all satisfied):

If multiple phases are [parallel]: spawn them as sub-agents simultaneously using sessions_spawn. Pass each sub-agent:

• The full PRD context
• Its specific phase tasks
• The model to use
• The gate command (if any)
• The working directory

If a phase has depends:: wait for all named phases to complete before spawning.

Sequential phases (no [parallel] tag): run one at a time in declaration order.

Step 4 — Gate evaluation#

After each phase completes:

1. If a gate command is specified:
   • Validate the gate command first. Reject commands containing shell metacharacters ( ;, &&, ||, |, $(, `, >, <) unless the phase includes Shell-Gate: true. This prevents accidental or malicious arbitrary shell execution from PRD content.
   • Run the validated gate command with exec
2. Erosion check (code phases): If the phase produced code, measure structural complexity. If cyclomatic complexity mass in high-CC functions (CC > 10) increased > 5% compared to the prior phase's baseline, flag for review or force a refactoring sub-phase before proceeding. This prevents quality degradation across sequential phases (research: SlopCodeBench shows structural erosion in 80% of agent trajectories).
3. If the gate passes (exit 0): mark phase complete, proceed
4. If it fails: retry the phase up to Max-Retries times (default: 2), passing the failure output as context
5. If retries exhausted: escalate to Corbin and halt

Step 5 — Review-to-fix loop#

For phases with Type: review:

1. The review agent produces a structured findings report
2. Parse the report for blocking/required issues
3. If issues exist:
   • Spawn a fix sub-agent (same model tier as the implementation phase, or Sonnet default) with the findings as context
   • After fix agent completes, re-run the review phase
   • Repeat up to 3 cycles
4. If issues persist after 3 cycles: escalate with full findings history
5. If no blocking issues: mark review phase complete

Review agent prompt structure:

text

You are performing a structured code review.

Context:
{phase tasks and objective}

Working directory: {cwd}

Produce a report in this exact format:

## Findings

### Blocking
- [issue description] — [file:line if known]

### Required Changes
- [issue description]

### Suggestions
- [issue description]

### Summary
PASS | FAIL

If PASS: no Blocking or Required Changes items.
If FAIL: at least one Blocking or Required Changes item exists.

Fix agent prompt structure:

text

You are implementing fixes identified in a code review.

Review findings:
{findings report}

Fix all Blocking and Required Changes items. Do not change anything not listed.
Working directory: {cwd}

When complete, summarize what you changed.

Step 6 — Completion#

When all phases pass their gates:

1. Write a completion summary to .openforge/run-{timestamp}.md in the working directory (if a cwd was specified)
2. Report success with phase outcomes and any escalations that occurred
3. If any phases were skipped or escalated, report them explicitly

---

Sub-agent Prompting#

When spawning a sub-agent for a phase, include:

text

You are executing Phase: {phase_name} of an OpenForge PRD run.

## Objective
{PRD objective}

## Your Tasks
{task list}

## Working Directory
{cwd or "not specified — use judgment"}

## Prior Phase Outputs
{summaries from completed phases, if any}

## Gate
After completing your tasks, the following command will be run to validate your work:
{gate command or "none"}

## Constraints
- Only modify files relevant to your tasks
- Do not expose credentials, API keys, or secrets
- Write a brief summary of what you did when complete

## Model
You are running as: {model alias}

---

Escalation Protocol#

Escalate to the human (Corbin / operator) when:

1. A gate fails after all retries are exhausted
2. A review-to-fix loop hits 3 cycles without reaching PASS
3. The PRD has structural errors that prevent execution
4. A phase sub-agent returns an error that can't be recovered
5. A phase declares escalate: true explicitly

Escalation message format:

text

⚠️ OpenForge Escalation

PRD: {title}
Phase: {phase_name}
Reason: {specific failure reason}

What happened:
{summary of attempts}

Gate output (if applicable):
{last gate failure output, truncated to 500 chars}

Recommended next step:
{specific suggestion — fix the gate command, revise the PRD, or manual intervention}

---

Security Constraints#

• Sub-agents run with the same permissions as the parent agent within the workspace directory
• Gate commands are run with exec in the working directory. Review gate commands before running against production systems. Avoid destructive commands (e.g., rm -rf).
• OpenForge writes one artifact ( .openforge/run-{timestamp}.md) to the working directory. No other writes are made by the orchestrator itself.
• No network connections are made by OpenForge itself — only your configured AI model providers are contacted via the OpenClaw agent interface

---

Example: Full Parallel PRD#

markdown

# PRD: Auth Refactor

## Objective
Replace the custom session cookie system with JWT-based auth.

## Phases

### Phase: research [parallel]
**Model:** haiku
**Type:** extract
**Tasks:**
- Read `src/auth/` and summarize all current auth entry points
- List all routes that call `req.session`

### Phase: design [parallel]
**Model:** opus
**Type:** review
**Tasks:**
- Design the JWT strategy: token structure, expiry policy, refresh approach
- Identify migration risks

### Phase: implement [depends: research, design]
**Model:** sonnet
**Tasks:**
- Implement JWT middleware in `src/auth/jwt.ts`
- Replace session calls in all routes identified in research phase
- Update `src/auth/index.ts` to export new middleware

**Gate:** `npm run build && npm test`
**Max-Retries:** 3

### Phase: security-review [depends: implement]
**Model:** opus
**Type:** review
**Tasks:**
- Review JWT implementation for common vulnerabilities (alg confusion, weak secret, missing expiry check)
- Review token storage and transmission

**Gate:** Review must find zero Blocking issues

In this PRD:

• research and design run in parallel (no dependencies, both tagged [parallel])
• implement waits for both, then runs with Sonnet
• security-review runs last with Opus, triggers auto-fix loop if issues are found

---

Limitations (v2)#

• Parallel phase results are collected via sub-agent completion events — if a sub-agent times out, that phase's output may be missing
• Review-to-fix loops use the same working directory; if the fix agent introduces regressions, OpenForge will catch them at the gate but won't automatically revert
• Gate commands run in the working directory with no isolation — avoid destructive commands (e.g., rm -rf)
• No persistent run state across sessions — if the parent agent session ends mid-run, the run cannot be resumed (sub-agents completing after session end will still announce results but the orchestrator won't act on them)
• Model alias resolution depends on your OpenClaw instance's configured models; if opus isn't available, Sonnet will be used silently

---

Quick Reference#

What you wantHow to triggerRun a PRD"Run this PRD: [paste or path]"Dry-run (plan only)"Plan this PRD without executing"Run a single phase"Run only the implement phase of this PRD"Skip a phaseAdd Skip: true to the phase headerForce a modelAdd Model: opus to any phaseCap retriesAdd Max-Retries: 1 to a phaseParallel phasesAdd [parallel] to phase header