Openforge

Staged, multi-model PRD execution for OpenClaw. Write a PRD with phased sections, model routing, and validation gates — OpenForge executes it across local an...

Security Scan

The skill’s declared purpose (orchestrating PRDs across models) matches what the instructions do, but the runtime protocol grants broad file, shell, and agent privileges without sandboxing or secret protection — risky and worth caution.

Purpose & Capability

Name and description (PRD orchestration, phased execution, model routing) align with the instructions: parsing a PRD, spawning sub-agents, routing tasks, evaluating gates, and running fixes. No unrelated credentials or binaries are requested, and no install step is required, which is coherent for a purely-instruction orchestration skill.

Instruction Scope

SKILL.md instructs the agent to read PRD files, spawn sub-agents (sessions_spawn) with full PRD context, run arbitrary gate commands via exec, and read/write project files and working directories. It explicitly states it does not sandbox or secret-scan PRDs. Those instructions allow arbitrary code execution and broad filesystem access derived from the PRD content, which goes well beyond mere parsing/analysis and creates a high-risk execution surface.

Install Mechanism

Instruction-only skill with no install spec and no code files — lowest install risk. Nothing is downloaded or written during installation because there is no install step.

Credentials

The skill declares no required environment variables or credentials, but its runtime behavior (passing full PRD context to sub-agents, running shell gates, reading/writing workspace files) can expose secrets present in the repository or PRD to models/sub-agents and to any shell commands run. There is no built-in secret redaction or justification for exposing broad file/exec access.

Persistence & Privilege

always:false and normal autonomous invocation. The skill does not request permanent inclusion, but it does instruct the agent to modify files and run gate commands in the working directory—effectively granting the agent write and execution privileges in the workspace. This is not an installation privilege escalation, but it is a powerful runtime capability that should be limited to trusted contexts.

What to consider before installing

This skill is coherent with its stated purpose (it really is an orchestration protocol), but it intentionally runs arbitrary gate commands and spawns sub-agents with the full PRD and workspace context while explicitly not providing sandboxing or secret scanning. Only use it on trusted repositories/PRDs that contain no secrets. Before installing/using: (1) ensure PRDs are sanitized (no API keys, passwords, tokens), (2) run the skill inside an isolated CI/container environment with limited filesystem access and no secrets mounted, (3) prefer adding a policy that disallows or strictly limits gate shell commands, and (4) consider requiring secret-scanning or a review step before allowing the skill to execute gates that run shell commands. If you need stricter safety (automatic redaction, scope enforcement, or sandboxed execution), this skill explicitly says it does not provide those protections.

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 sandbox agent actions or enforce file-scope restrictions at OS level
• Does not protect against malicious PRDs (treat PRDs like code)
• Does not require or manage custom agent registration
• Does not guarantee secret scanning — don't put secrets in PRDs

---

PRD Format

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

Minimal PRD

# 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

Field	Required	Values	Meaning
Model:	No	haiku, sonnet, gpt, opus	Model tier for this phase
Type:	No	impl, review, extract	Phase type; controls prompting style
[parallel]	No	Flag in phase header	Phase can run alongside other [parallel] phases
depends:	No	Phase name(s)	This phase waits for named phases to complete
Gate:	No	Shell command or description	Must pass before next phase starts
Max-Retries:	No	Integer (default: 2)	Gate failure retries before escalation

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

Alias	Maps To	Use For
haiku	claude-haiku / cheapest available	Extraction, parsing, structured output
sonnet	claude-sonnet	Implementation, research, multi-file work
gpt	gpt-4o or equivalent	Alternative implementation path
opus	claude-opus	Judgment, 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.

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, run it with exec
2. If it passes (exit 0): mark phase complete, proceed
3. If it fails: retry the phase up to Max-Retries times (default: 2), passing the failure output as context
4. 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:

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:

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:

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:

⚠️ 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

• Never include secrets, API keys, or credentials in PRDs. OpenForge passes PRD content to sub-agents verbatim.
• PRD files are trusted input. Treat them like code. Don't execute PRDs from untrusted sources.
• Sub-agents run with the same permissions as the parent agent. OpenForge does not add a sandbox layer.
• Gate commands are run with exec. Review gate commands before running against production systems.
• OpenForge writes one artifact (.openforge/run-{timestamp}.md) to the working directory. No other writes are made by the orchestrator itself.

---

Example: Full Parallel PRD

# 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 want	How to trigger
Run 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 phase	Add Skip: true to the phase header
Force a model	Add Model: opus to any phase
Cap retries	Add Max-Retries: 1 to a phase
Parallel phases	Add [parallel] to phase header