high perf orchestration a la oh my codex & gastown

Hybrid orchestration skill where OpenClaw stays the control plane and ACP Claude Code is the default execution backend for coding work.

Security Scan

The skill's documentation and runtime instructions broadly match an orchestration purpose, but there are mismatches and operational recommendations (missing helper scripts, implicit secret needs, and an unsafe ACPX permission suggestion) that do not line up with the declared requirements and raise concern.

Purpose & Capability

The skill claims to be an instruction-only orchestration pattern (no binaries, no env vars), and much of the content is consistent with OpenClaw orchestration + ACP backends. However, several parts of the docs require gateway configuration and secrets (e.g., injecting OPENAI_API_KEY for Codex ACP, ACPX permissionMode changes) and reference helper scripts (scripts/orchestration/*.py) that are not present in the provided file manifest. Those requirements are not declared in the skill metadata and are not obviously proportionate to a purely-documentation skill.

Instruction Scope

SKILL.md and the docs instruct the orchestrator to run tool-level actions (sessions_spawn, launcher preflight, mark_launch, etc.), to read/write file-native handoffs, and to modify gateway runtime configuration. Those instructions are within an orchestration scope, but they also assume the existence of helper scripts and gateway-level changes that are not included. The docs recommend changing ACPX permissionMode to 'approve-all' for unattended runs — a broad permission change that goes beyond normal documentation and materially affects gateway policy.

Install Mechanism

There is no install spec and no code files included (instruction-only), which reduces installation risk. However, the runtime docs repeatedly reference scripts (scripts/orchestration/*.py) and helper scripts (prepare_project_builder.py, launcher_preflight.py) that are not present in the package manifest; this suggests either missing implementation or expectation that the user already has these scripts installed elsewhere.

Credentials

The skill metadata declares no required environment variables, but the docs explicitly instruct adding an OPENAI_API_KEY to the gateway environment for Codex ACP and recommend an ACPX policy change ('permissionMode': 'approve-all'). Asking operators to inject API keys into the gateway and to relax ACPX permissions is a high-privilege operational change and is not justified in the metadata; this is disproportionate and a security concern.

Persistence & Privilege

The skill does not request always:true and is user-invocable with normal autonomous invocation defaults. It describes spawning persistent ACP sessions and storing file-native state, which is expected for orchestration. Autonomous invocation is the platform default; this alone is not a red flag, but it does increase the blast radius if combined with the other noted concerns (gateway policy change, secrets).

What to consider before installing

What to check before installing or using this skill: - Verify presence of helper scripts: the docs reference many scripts under scripts/orchestration/ (prepare_project_builder.py, launcher_preflight.py, mark_launch.py, etc.). These are not in the provided file list. Ask the author for the missing scripts or confirm you already have trusted copies before relying on the instructions. - Secrets and gateway changes: the package metadata says no env vars are required, but the docs instruct injecting OPENAI_API_KEY into the gateway environment for Codex ACP and changing ACPX policy to permissionMode: 'approve-all'. Those are privileged operational changes. Do NOT apply permissionMode: 'approve-all' in production without understanding the security implications. If you must provide an API key, store it securely and scope it appropriately. - Principle of least privilege: prefer explicit approval/interactive permission flows for ACP sessions where possible. The suggested 'approve-all' mode increases risk of unattended agents performing actions without human review. - Confirm what will be invoked: the skill's instructions assume the orchestrator can call sessions_spawn and related OpenClaw tooling. Confirm your gateway and agent environment expose these APIs and that the skill will not try to exfiltrate unrelated secrets. The skill's file-based handoff model is reasonable for orchestration, but the missing scripts and the gateway tweaks are the main gaps. - Test in an isolated environment: run any suggested setup (especially gateway changes and API-key injection) in a non-production/test environment first. Audit logs and limit network access for any worker sessions you spawn. If you need higher assurance: request the full implementation (all referenced scripts) and an explanation for why ACPX permissionMode must be relaxed, or prefer a variant that uses explicit, limited approvals and documents exactly which secrets and host-level changes are required.

Claude Code Control Plane

Use this when the user wants multi-step coding orchestration without making the main OpenClaw session carry the execution load.

Core idea

• OpenClaw main session = planner, router, state owner, human interface
• ACP Claude Code sessions = default builders/reviewers
• ACP Codex sessions = optional targeted fixer/batch workers
• Files = source of truth for handoffs and state

This skill is for hybrid orchestration, not pure OpenClaw swarms.

When to use

Use this skill when:

• the task is primarily coding or engineering
• the work may span hours
• you may want several workers over time
• the main OpenClaw session should stay stable and lightweight
• session/tool reliability matters more than having every worker inside OpenClaw

Do not use this skill when:

• the task is a quick question
• the task is a tiny one-shot edit
• the work depends mostly on OpenClaw-native tools rather than coding runtime

Default architecture

Roles

• Orchestrator: OpenClaw main session
• Builder: ACP Claude Code session
• Reviewer: ACP Claude Code session or ACP Codex session
• Fixer: ACP Codex session when patches are narrow and repetitive

State

Every workstream must have:

1. a task/spec file
2. a shared artifact path
3. a clear handoff packet written before spawn
4. a rolling worker summary file for context rollover

Launch policy

Default spawn

For a real coding worker, prefer:

• sessions_spawn
• runtime: "acp"
• explicit agentId
• thread: true
• mode: "session"

This gives a persistent coding worker instead of a fragile short-lived chat worker.

Suggested defaults

• Claude Code builder: persistent ACP session bound to the thread/workstream
• Claude Code reviewer: separate persistent ACP session for clean review context
• Codex fixer: one-shot or persistent depending on volume

Orchestration modes

1. Single builder

Use when one worker can do the task.

Pattern:

• OpenClaw defines task
• Claude Code builds
• OpenClaw reviews result and reports

2. Builder + reviewer

Use by default for non-trivial code changes.

Pattern:

• Claude Code builder session
• Claude Code or Codex reviewer session
• OpenClaw resolves disagreement and reports back

3. Project builder

Use when there is a real repo/worktree with multiple steps.

Pattern:

• planner/spec handoff
• builder session for implementation
• reviewer session for gaps
• fixer loop only on concrete deltas

4. Hybrid swarm

Use only when the work is large enough to justify multiple workers.

Pattern:

• Claude Code: architect / planner / nuanced reviewer
• Codex: mechanical builders / fixers
• OpenClaw: state machine + human checkpoints

Guardrails

1. Do not keep complex run state only in session chat.
2. Do not spawn workers before writing the handoff file.
3. Do not let the orchestrator become the builder.
4. Use worktrees for parallel builders.
5. Prefer fewer persistent workers over many throwaway workers.
6. If OpenClaw runtime looks unhealthy, stop spawning and continue with ACP sessions already alive.
7. Every long-running worker should maintain a rolling summary file covering:
   • what it has done
   • what it is doing now
   • what it learned / what matters next
8. When a worker nears context pressure, compress to file first, then resume or replace the worker from that file instead of letting it drift into a weak soft-stop.

Recommended file layout

project-specs/
shared-specs/
shared-artifacts/
runs/<run-id>/
worker-state/

Prompt template for ACP workers

## TASK
<exact task>

## EXPECTED OUTPUT
<artifact paths + format>

## MUST DO
- read the listed files first
- write artifacts before claiming completion
- report only the concise delta

## MUST NOT
- do not overwrite unrelated files
- do not self-approve
- do not hide uncertainty

## CONTEXT
- repo/worktree:
- files to read first:
- artifact path:

Recommended starting default

For now, the safest default is:

• OpenClaw main = orchestrator
• Claude Code ACP = primary builder
• Claude Code ACP or Codex ACP = reviewer
• file-native handoffs everywhere

That is the baseline setup this skill assumes.