Skill: jkobject/orchestration-setups (version 0.1.2)

--- name: claude-code-control-plane description: "Hybrid orchestration skill where OpenClaw stays the control plane and ACP Claude Code is the default execution backend for coding work." metadata: {"openclaw":{"emoji":"🧭"}} --- # 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 ```text project-specs/ shared-specs/ shared-artifacts/ runs/<run-id>/ worker-state/ ``` ## Prompt template for ACP workers ```text ## 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.

path: README.md
content: # Orchestrator a la oh-my-codex and gastown for Openclaw

Goal: avoid making the main OpenClaw session a heavy execution runtime while keeping it as the control plane.

## Package entrypoint

- `SKILL.md` is the root skill entrypoint for ClawHub / OpenClaw.
- `docs/` contains the design, runtime notes, reproduction guide, and test results.
- `packs/` contains reusable workflow/agent/template assets.
- `examples/` contains minimal session launch patterns.

## Recommendation

**Start here:**
- **OpenClaw main session** = planner, router, durable state, human interface
- **ACP Claude Code sessions** = default execution workers
- **ACP Codex sessions** = optional secondary builder / reviewer / fixer workers
- **Artifacts + handoffs** = file-native state under shared artifact directories and run-state directories

This keeps the fragile part small: the main session decides and tracks, but the real long coding work happens in external ACP workers.

## Why change the setup

The current issue is not that every worker gets Active Memory.
The issue is that the **main OpenClaw orchestrator session** can accumulate runtime overhead on user-triggered prompt build hooks, while it is also the place that calls `sessions_spawn`, `sessions_list`, and other orchestration tools.

So the safer design is:
- thin control plane in OpenClaw
- heavy execution in ACP workers
- minimal plugin dependence on the orchestrator session

## Setup matrix

| Setup | What it is | Pros | Cons | Use for |
|---|---|---|---|---|
| **A. OpenClaw-only** | Main session + OpenClaw subagents everywhere | Unified tools, simple mental model | More coupling to gateway/session internals | Short multi-step tasks |
| **B. OpenClaw + ACP Claude Code** | OpenClaw orchestrates, Claude Code executes | Best default for real coding projects, persistent sessions, less pressure on main lane | Slightly more moving parts | Main recommendation |
| **C. OpenClaw + ACP Codex** | Same as B but Codex workers | Strong code search/edit/test loops, good cost profile | Slightly less strong on ambiguous planning/review prose | Batch edits, parallel fixes |
| **D. Hybrid ACP** | Claude Code planners/reviewers + Codex builders | Strongest team pattern for medium/large repos | More orchestration discipline needed | Larger engineering work |
| **E. External-first swarm** | Very thin OpenClaw, most work done outside it | Maximum isolation from gateway quirks | Less unified state unless carefully documented | Big coding swarms, later phase |

## Available orchestration workflows

### `review-loop`
Classic builder → reviewer → fix loop.

Use it for:
- non-trivial code changes
- document or spec review
- any task where you want a clean quality gate before shipping

### `deep-research`
Parallel research fan-out followed by synthesis.

Use it for:
- literature scans
- competitive / technical landscape surveys
- collecting evidence from several parallel workers before one synthesis pass

### `project-builder`
Structured project build flow with a planner/builder/reviewer pattern and worktree-aware module splitting.

Use it for:
- multi-file engineering tasks
- greenfield feature scaffolding
- work that benefits from parallel builder streams with explicit reviewer feedback

### `batch-review`
One reviewer pattern over a set of items/artifacts.

Use it for:
- many related diffs
- content batches
- repeated checks over a list of outputs

### `watchdog`
Lightweight monitoring / stale-run detection pattern.

Use it for:
- surfacing stalled runs
- retry / escalation checks
- lightweight operational monitoring

## Validation status

Not all workflows are validated at the same depth yet.

| Workflow / backend | Validation level | Status |
|---|---|---|
| **OpenClaw subagent backend** | Real smoke test | ✅ validated |
| **Claude Code ACP backend** | Real smoke test | ✅ validated |
| **Codex ACP backend** | Real smoke test | ✅ validated |
| **`review-loop`** | Runtime smoke test executed successfully | ✅ validated at V1 runtime level |
| **`deep-research`** | Parallel handoff generation checked manually (`--count 3`) | 🟡 structure validated, not yet end-to-end on a full real case |
| **`project-builder`** | Module-targeted handoff generation checked manually (`--targets backend,frontend`) | 🟡 structure validated, not yet end-to-end on a full real case |
| **`batch-review`** | Present in pack, no dedicated smoke test yet | ⚪ not yet explicitly validated |
| **`watchdog`** | Present in pack, no dedicated smoke test yet | ⚪ not yet explicitly validated |

So the honest answer is:
- **no, they are not all validated equally yet**
- the **execution backends** are now validated
- `review-loop` is the most concretely validated workflow
- `deep-research` and `project-builder` are structurally validated but still deserve a real end-to-end run
- `batch-review` and `watchdog` are packaged but still lighter-confidence

## Final recommendation

### Phase 1, adopt now
**Setup B: OpenClaw + ACP Claude Code**

Pattern:
1. Keep OpenClaw as the control plane
2. Spawn Claude Code ACP sessions for actual implementation
3. Use one persistent thread/session per workstream
4. Store state in files, not in session memory
5. Keep the main session lightweight during orchestration

### Phase 2, when needed
**Setup D: Hybrid ACP**
- Claude Code for planning, architecture, nuanced review
- Codex for focused implementation, patching, repetitive batch work

## Control plane rules

1. **OpenClaw should not be the main execution engine** for long coding swarms.
2. **Every workstream gets a file-native state path**:
   - task/spec file
   - shared artifacts directory
   - run-state directory for handoffs, checkpoints, and reviews
3. **ACP workers own code changes**.
4. **OpenClaw owns routing, checkpoints, retries, and reporting**.
5. **Git worktrees per builder stream** when multiple workers touch code.

## Minimal operating model

- **Planner**: OpenClaw main or Claude Code ACP
- **Builder**: Claude Code ACP session
- **Reviewer**: Claude Code ACP session or Codex ACP session
- **Fixer**: Codex ACP session for targeted repair loops
- **Human checkpoint**: OpenClaw main session

## Suggested first implementation

- Root skill entrypoint: `SKILL.md`
- Handoff/state kept in a file-native orchestration runtime
- Claude Code ACP as the default worker backend
- Previous architecture material bundled directly under `docs/` and `packs/` so the historical design base stays attached to the new proposal

## Bundled previous work

This folder now includes the prior material we had already developed:
- V1 control-plane spec
- OMC/Gastown audit
- runtime docs (`README`, `SCHEMAS`, `COMMUNICATION`, `OPENCLAW_LAUNCHER`, `PROJECT_BUILDER_WORKTREE`)
- agent / workflow / template packs

See:
- `SKILL.md`
- `docs/setup-matrix.md`
- `docs/design/`
- `docs/runtime/`
- `docs/reproduction.md`
- `docs/test-results.md`
- `packs/`
- `examples/session-patterns.md`


path: docs/design/control-plane-v1.md
content: # Orchestration Control Plane V1

## Goal
Build an OpenClaw-native orchestration layer that supports:
- deep research
- builder/reviewer/fix loops
- project builder with reviewer-guided retries
- long-running work over hours
- durable run state and recovery
- mixed tasks (code, research, docs, ops), not just coding

## V1 Principles
1. **OpenClaw-native**: use sessions, cron, heartbeat, shared files.
2. **Durable state beats prompt memory**: every run must be resumable from files.
3. **Typed retries**: not blind retry, but fix-loop / partial rebuild / replan.
4. **Workflow-first**: reusable declarative workflows, not ad hoc orchestration each time.
5. **Human-visible checkpoints**: every phase produces an artifact and a state update.
6. **Cheap ops, expensive judgment**: scheduler/monitoring can be cheap; routing/review stays high-quality.

---

## Architecture Overview

### Layer 1: Orchestrator Skill (policy + routing)
Keep one primary skill:
- `skills/agent-team-orchestration/`

Responsibilities:
- choose workflow
- choose agent roles
- choose model category
- define handoff format
- define retry / escalation rules
- explain when to use each mode

This layer is the **brain**, not the runtime.

### Layer 2: Declarative Control Plane (files)
New directory:

```text
agent/orchestration/
  agents/
    planner.yaml
    researcher.yaml
    synthesizer.yaml
    architect.yaml
    builder.yaml
    reviewer.yaml
    tester.yaml
    critic.yaml
    integrator.yaml
    ops.yaml
  workflows/
    deep-research.yaml
    review-loop.yaml
    project-builder.yaml
    batch-review.yaml
    watchdog.yaml
  runs/
    <run-id>/
      state.json
      plan.md
      events.jsonl
      handoffs/
      outputs/
      reviews/
      checkpoints/
      working-memory/
  templates/
    handoff.md
    review.md
    checkpoint.md
    temporary-context.md
  COMMUNICATION.md
```

This layer is the **shared source of truth**.

### Layer 3: Local Runtime (dispatcher + monitor)
Small local helper code, e.g.:

```text
scripts/orchestration/
  run_workflow.py
  dispatch_step.py
  complete_step.py
  apply_review.py
  prepare_project_builder.py
  watchdog.py
  status.py
```

Responsibilities:
- create run ids
- materialize workflow state
- dispatch sub-agents / sessions
- update run state after each completion
- apply retry policy
- trigger escalations
- resume stalled runs from file state

This layer is the **engine**.

---

## Communication Model

The system should treat communication as 3 separate layers:

### 1. Stable shared context
This is the project-level context every agent should consult.

Canonical files:
- `README.md`
- `CLAUDE.md`

For project work, these live at the repository or worktree root.

### 2. Directed handoff
This is the explicit A -> B relay between phases or agents.

Canonical location:
- `runs/<run-id>/handoffs/`

### 3. Shared temporary context
This is richer short-lived context that survives retries, agent death, or replacement.

Canonical location:
- `runs/<run-id>/working-memory/`

Use it for:
- failed attempts
- intermediate notes
- unresolved questions
- partial decompositions
- integration gotchas

---

## Core File Schemas

### `agents/*.yaml`
Defines stable agent archetypes.

Example fields:
- `name`
- `purpose`
- `best_for`
- `avoid_for`
- `default_model_category`
- `allowed_tools`
- `input_contract`
- `output_contract`
- `reviewer_for`

Example:
```yaml
name: reviewer
purpose: verify artifacts against spec and catch gaps
best_for:
  - correctness checks
  - edge cases
  - scope drift detection
avoid_for:
  - first-pass implementation
  - writing specs it will later approve
default_model_category: brain
output_contract:
  - verdict
  - issues_by_severity
  - minimal_fix_scope
  - escalate_if_systemic
```

### `workflows/*.yaml`
Defines reusable state machines.

Example fields:
- `workflow_id`
- `goal`
- `phases`
- `entry_conditions`
- `artifacts`
- `retry_modes`
- `escalation_rules`
- `completion_conditions`

### `runs/<run-id>/state.json`
Durable run state.

Example fields:
```json
{
  "run_id": "prj-2026-04-20-001",
  "workflow": "project-builder",
  "status": "in_progress",
  "phase": "review",
  "iteration": 2,
  "active_agents": ["builder-backend", "reviewer-main"],
  "canonical_artifacts": {
    "spec": "shared/specs/foo.md",
    "implementation": "shared/artifacts/foo/",
    "review": "shared/reviews/foo-round2.md"
  },
  "last_decision": "Fix loop on backend module only",
  "next_action": "dispatch partial rebuild",
  "blockers": [],
  "history": []
}
```

### `events.jsonl`
Append-only event log.
Each event contains:
- timestamp
- actor
- phase
- event_type
- artifact path
- summary

This is crucial for recovery and observability.

---

## V1 Workflows

### 1. `deep-research`
Use for broad investigation.

Flow:
1. planner creates question decomposition
2. 3-6 researchers run in parallel on non-overlapping angles
3. synthesizer merges findings
4. critic reviews for gaps / weak evidence
5. optional second pass if critic finds major gaps
6. final synthesis

Artifacts:
- `shared/specs/<topic>-plan.md`
- `shared/artifacts/<topic>/research-*.md`
- `shared/reviews/<topic>-critic.md`
- `shared/specs/<topic>-final.md`

Retry modes:
- `targeted-research-pass`
- `re-synthesis`

### 2. `review-loop`
Use for a bounded build + review cycle.

Flow:
1. builder creates artifact
2. reviewer evaluates
3. if pass -> done
4. if fail -> builder fix loop
5. max 3 iterations before escalation

Reviewer output must be structured:
- verdict: pass/fail
- issue list
- severity
- minimal fix scope
- whether issue is local or systemic

### 3. `project-builder`
Use for end-to-end project work.

Flow:
1. interview/spec
2. architecture
3. parallel builders by module
4. integration
5. review
6. typed retry:
   - local fix loop
   - partial rebuild
   - replan
7. integration review
8. ship

This is the main answer to the “Ralph loop for project building” requirement.

#### Git-backed execution requirement
For `project-builder`, execution should happen inside a git-backed repository or worktree, not only inside orchestration state files.

Requirements:
- repository/worktree root exists
- `README.md` and `CLAUDE.md` live there and are treated as stable shared context
- parallel builders should use isolated worktrees/branches when practical
- GitHub remote should exist for durable sync on GitHub-backed projects
- worktree prep should be reproducible via a helper (V1: `prepare_project_builder.py`)
- worktrees should live outside the repo working tree (V1 target: `<worktree-root>/...`)

The orchestration layer should therefore manage both:
- run-local state (`runs/<run-id>/...`)
- project state (repo/worktree + git history)

#### Typed retry policy
When review fails, classify the failure:

**A. Local defect**
- example: bug in one module
- action: builder fix loop
- owner: same builder if possible
- max: 2-3 rounds

**B. Cross-module mismatch**
- example: API contract drift between frontend/backend
- action: partial rebuild + reintegration
- owner: affected builders + integrator

**C. Architectural/spec issue**
- example: reviewer says the implementation follows a bad plan
- action: replan loop
- owner: planner/architect

Do not restart the whole project by default.

### 4. `batch-review`
Use for many similar items.

Flow:
1. split batch
2. dispatch M parallel reviewers/builders
3. aggregate results
4. optional second batch for failed items only

### 5. `watchdog`
Health monitoring workflow.

Flow:
1. inspect active runs
2. detect stale state / missing events / excessive retries
3. mark run as healthy, stalled, or escalated
4. optionally trigger wake / summary / recovery step

---

## Handoff Contract (mandatory)
Every inter-agent handoff must contain:
1. what was done
2. canonical artifact paths
3. how to verify
4. known issues
5. exact next action
6. whether retry should be local / partial / replan

Template:
```markdown
## What was done
...

## Canonical artifacts
- ...

## Verification
- ...

## Known issues
- ...

## Retry classification
- local-fix | partial-rebuild | replan | none

## Next action
- ...
```

---

## Reviewer Contract (mandatory)
Reviewer outputs must be machine-usable.

Template:
```markdown
## Verdict
pass | fail

## Severity
low | medium | high | critical

## Issues
- [id] description

## Minimal fix scope
- exact modules / files / artifacts affected

## Classification
local-defect | cross-module | architecture-spec

## Recommended next step
fix-loop | partial-rebuild | replan | escalate
```

Without this structure, retries become noisy and wasteful.

---

## Retry and Escalation Policy

### Retry rules
- same builder retries local fixes when feasible
- max 3 retries for same failure class
- if same failure repeats twice with no delta -> escalate
- if reviewer flags systemic problem -> no local retry, go to partial rebuild or replan

### Escalation triggers
- same failure repeated twice
- run exceeds expected scope by 2x
- no event/checkpoint for threshold duration
- missing canonical artifact
- contradictory reviews

### Escalation targets
- stronger reviewer
- planner/architect
- human

---

## Observability V1
We do not need a full dashboard yet, but we do need:
- `state.json` as the source of truth
- `events.jsonl` append-only log
- `plan.md` human-readable summary
- periodic summaries via cron / heartbeat

Minimal statuses:
- `queued`
- `assigned`
- `in_progress`
- `review`
- `fix_loop`
- `partial_rebuild`
- `replan`
- `blocked`
- `done`
- `failed`
- `escalated`

---

## OpenClaw Integration

### Sessions
- use `sessions_spawn` for specialized workers
- use persistent sessions only when role continuity matters
- otherwise prefer one-shot runs plus durable file state

### Heartbeat
Heartbeat should not merely say “still running”. It should:
- advance active runs
- inspect stalled ones
- recover the next step from `state.json`
- notify only on meaningful progress, blockers, or decision requests

### Cron
Use cron for:
- watchdog checks
- stale run detection
- daily/periodic summaries
- wake-up of long-running orchestration runs

### Shared directories
Canonical artifact routing:
- `shared/specs/`
- `shared/artifacts/`
- `shared/reviews/`
- `shared/decisions/`
- `shared/learnings/`

---

## What stays out of V1
Do **not** build yet:
- full UI/dashboard
- automatic model optimization engine
- 20+ agent zoo
- complex external scheduler
- merge queue like Gastown refinery
- mailbox simulation between agents
- autonomous indefinite loops with weak stop conditions

V1 should stay small, legible, and robust.

---

## Recommended Initial Agent Set (10)
1. planner
2. researcher
3. synthesizer
4. critic
5. architect
6. builder
7. reviewer
8. tester
9. integrator
10. ops

This is enough to cover research + project work.

---

## Recommended Implementation Order

### Phase 1: Foundations
- create `agent/orchestration/agents/`
- create `agent/orchestration/workflows/`
- define YAML schemas
- create run directory structure
- define handoff/review templates

### Phase 2: Runtime core
- implement run creation
- implement state transitions
- implement event logging
- implement dispatch of first workflow step
- implement retry classification

### Phase 3: First workflows
- `review-loop`
- `deep-research`
- `project-builder`

### Phase 4: Recovery + ops
- watchdog script
- stale-run detection
- heartbeat integration
- cron summaries

### Phase 5: Hardening
- better summaries
- replay/resume helpers
- reviewer conflict handling
- richer run analytics

---

## Success Criteria for V1
V1 is successful when we can run:
1. one deep research task end-to-end
2. one builder/reviewer/fix loop with structured retries
3. one project-builder run with at least one reviewer-guided relaunch
4. one interrupted run that resumes from files without manual reconstruction

---

## Short Positioning
- **OMC inspiration**: named workflows, clean UX, staged execution
- **Gastown inspiration**: durable state, recovery, watchdog mindset
- **Our version**: lighter, file-native, OpenClaw-native, cross-domain


path: docs/design/omc-gastown-audit.md
content: # Audit — Orchestration V1 vs OMC + Gastown

## Scope
Audit of the current OpenClaw-native orchestration V1 against the essential ideas that looked most valuable in:
- Oh My Claude Code (workflow UX, staged loops, named modes)
- Gastown (durable runtime, work tracking, watchdog/recovery, git-backed execution)

## Summary verdict
The V1 now covers the main structural essentials, but not all the automation depth.

### Covered well
- reusable named workflows
- durable run state outside chat memory
- explicit handoffs
- shared temporary context
- structured review + typed retry routing
- watchdog / stale detection
- project-builder as git/worktree-backed execution
- stable shared context via `README.md` + `CLAUDE.md`

### Covered partially
- agent identity continuity
- recovery automation after failure
- escalation system
- observability / dashboarding
- GitHub durability beyond remote detection
- automatic dispatch of real subagents from the runtime itself

### Not in V1 on purpose
- heavy autonomous daemon layer
- merge queue / refinery equivalent
- full mailbox system
- large-scale scheduler
- GitHub push automation without explicit human decision

---

## Coverage matrix

### 1. Named reusable workflows
**Why it matters:** both external systems rely on named modes / repeatable workflow units.

Status: **YES**

Implemented as:
- `agent/orchestration/workflows/review-loop.yaml`
- `deep-research.yaml`
- `project-builder.yaml`
- `batch-review.yaml`
- `watchdog.yaml`

### 2. Durable run state outside session memory
**Why it matters:** this is the core thing both systems do better than prompt-only orchestration.

Status: **YES**

Implemented as:
- `runs/<run-id>/state.json`
- `plan.md`
- `events.jsonl`
- `working-memory/`
- `handoffs/`
- `reviews/`

### 3. Agent role registry
**Why it matters:** both systems depend on stable agent roles.

Status: **YES / PARTIAL**

Implemented as:
- agent archetypes in `agent/orchestration/agents/*.yaml`

Missing depth:
- no long-lived per-agent persona/history beyond role + slot

### 4. Explicit A -> B communication
**Why it matters:** handoffs / routing packets are essential in both.

Status: **YES**

Implemented as:
- `handoffs/`
- template `handoff.md`
- `dispatch_step.py`

### 5. Shared stable context
**Why it matters:** you explicitly asked for this, and it matches the best part of Claude Code style workflows.

Status: **YES**

Implemented as:
- `README.md`
- `CLAUDE.md`
- detection in `run_workflow.py`
- propagation into dispatch prompts

### 6. Shared temporary context
**Why it matters:** crucial when an agent dies or a retry needs more than the final handoff.

Status: **YES**

Implemented as:
- `runs/<run-id>/working-memory/`
- `temporary-context.md`
- documented in `COMMUNICATION.md`

### 7. Structured review and fix loops
**Why it matters:** OMC-style verify/fix loops are one of the strongest ideas.

Status: **YES**

Implemented as:
- `review.md`
- `apply_review.py`
- typed routing: `fix-loop`, `partial-rebuild`, `replan`

### 8. Recovery / restart friendliness
**Why it matters:** Gastown's big strength is surviving interruption.

Status: **PARTIAL**

Implemented as:
- durable state
- event log
- working memory
- worktree protocol
- resume order documented in `PROJECT_BUILDER_WORKTREE.md`

Missing depth:
- no automatic replacement-agent relaunch yet
- no automatic resume planner yet

### 9. Watchdog / stale detection
**Why it matters:** both systems care about not leaving work silently stuck.

Status: **YES**

Implemented as:
- `watchdog.py`
- `watchdog.yaml`
- stale/block/escalate status transitions

### 10. Observability / status surface
**Why it matters:** users need to see what is running and where it is blocked.

Status: **PARTIAL**

Implemented as:
- `status.py`
- `state.json`
- `events.jsonl`
- `plan.md`

Missing depth:
- no dashboard / TUI / rich summary view yet

### 11. Git-backed project execution
**Why it matters:** this is a key Gastown-like property and important for real project work.

Status: **YES**

Implemented as:
- `prepare_project_builder.py`
- `PROJECT_BUILDER_WORKTREE.md`
- `project-builder.yaml` requirements
- worktree root outside repo: `<worktree-root>/...`

### 12. GitHub durability awareness
**Why it matters:** project-builder should know if the repo is actually GitHub-backed.

Status: **PARTIAL**

Implemented as:
- GitHub remote detection in `prepare_project_builder.py`

Missing depth:
- no push / PR workflow yet
- no branch publish helper yet

### 13. Parallel work decomposition
**Why it matters:** both systems assume parallel sub-work when useful.

Status: **YES / PARTIAL**

Implemented as:
- `dispatch_step.py --count N`
- `dispatch_step.py --targets a,b,c`
- `deep-research` parallel branches
- `project-builder` by-module slots

Missing depth:
- no automatic aggregator / join controller yet

### 14. Escalation path
**Why it matters:** both systems avoid silent flailing.

Status: **YES / PARTIAL**

Implemented as:
- `escalated` status
- retry caps
- watchdog transitions
- `templates/escalation.md`
- `scripts/orchestration/escalate_run.py`
- escalation artifacts under `runs/<run-id>/escalations/`

Missing depth:
- no notifier / auto-routing yet

### 15. Runtime-native spawning of subagents
**Why it matters:** this is where OMC feels magical.

Status: **PARTIAL**

Current behavior:
- runtime generates canonical handoffs/prompts
- runtime now also generates launch manifests under `runs/<run-id>/launch/`
- `OPENCLAW_LAUNCHER.md` defines the bridge to actual `sessions_spawn`
- `list_pending_launches.py` + `mark_launch.py` add the receipt-side mechanics
- actual spawning remains orchestrator-side in OpenClaw

Remaining gap:
- no automatic manifest consumer wired directly into tool calls yet

---

## Bottom line
What felt essential from the two external systems is now mostly present in V1, especially the things that matter most structurally:
- workflows
- state
- communication
- retries
- watchdog
- recovery substrate
- git/worktree project execution

What is still missing is mostly **automation depth**, not **architecture**.

The biggest remaining gaps are:
1. launcher that actually spawns/reattaches OpenClaw subagents from the workflow runtime
2. richer observability
3. explicit escalation artifacts / notifications
4. GitHub publish / PR helpers for project-builder


path: docs/reproduction.md
content: # Reproducing the Setup

This package is meant to give another user and another agent the same orchestration shape without inheriting any private local setup.

## Goal

Reproduce this operating model:
- **OpenClaw main session** as control plane
- **Claude Code ACP** as default execution backend
- **Codex ACP** as secondary execution/fixer backend
- **File-native state** for handoffs, rolling summaries, checkpoints, and reviews

## Required pieces

### 1. OpenClaw gateway
A working OpenClaw installation with gateway access.

### 2. ACPX / ACP harnesses
You need the ACPX plugin and the backends you want to use.

Validated harness aliases in this setup:
- `claude`
- `codex`

### 3. Claude Code ACP unattended policy
For unattended Claude Code ACP runs, the gateway-side ACPX plugin should use:

```json
{
  "plugins": {
    "entries": {
      "acpx": {
        "enabled": true,
        "config": {
          "permissionMode": "approve-all",
          "nonInteractivePermissions": "deny"
        }
      }
    }
  }
}
```

This avoids failing on impossible interactive approval prompts while still denying non-interactive permission requests cleanly.

### 4. Codex ACP authentication
Codex ACP needs an OpenAI API key exposed to the gateway service environment.

Example systemd user drop-in:

```ini
[Service]
Environment="OPENAI_API_KEY=<your-openai-api-key>"
```

After changing the service environment:
1. `systemctl --user daemon-reload`
2. restart the OpenClaw gateway
3. rerun a smoke test

### 5. Rolling worker context
Long-running workers should maintain a rolling summary file that captures:
- what they have done
- what they are doing now
- what they learned / what matters next

This is required for context rollover, worker replacement, and graceful recovery under context pressure.

## Minimal smoke tests

### Claude Code ACP
Spawn a tiny worker that writes one `ok` file.
If it completes, the unattended policy is functioning.

### Codex ACP
Spawn a tiny worker that writes one `ok` file.
If it completes, the API key wiring is functioning.

## What this package does not include

- your secrets
- your service files
- your local gateway path layout
- your personal project/task data

It contains only the reusable orchestration pattern, docs, workflow packs, and skill instructions.


path: docs/runtime/COMMUNICATION.md
content: # Communication Model

The orchestration system uses 3 communication layers.

## 1. Stable shared context
Repository or worktree root context shared by all agents.

Canonical files:
- `README.md` — project overview, purpose, layout, usage
- `CLAUDE.md` — agent instructions, architecture notes, conventions, current status

This is the long-lived context every agent should read before doing meaningful work.

## 2. Directed handoff
Agent A -> Agent B transition packet.

Purpose:
- explain what was done
- point to canonical artifacts
- state how to verify
- classify retry mode if needed
- define the exact next action

Location:
- `agent/orchestration/runs/<run-id>/handoffs/`

## 3. Shared temporary context
Rich but temporary shared state for the active run.

Purpose:
- preserve reasoning breadcrumbs between agents
- recover after agent death / kill / timeout
- store partial findings, failed attempts, open questions, intermediate notes

Location:
- `agent/orchestration/runs/<run-id>/working-memory/`

Examples:
- failed approach notes
- partial decompositions
- module-specific TODOs
- unresolved reviewer concerns
- integration gotchas

## Git / worktree rule for project-builder
For `project-builder`, the execution context should be a git-backed project/worktree.

Requirements:
- one repository root or worktree per active project run
- `README.md` and `CLAUDE.md` at the worktree root
- isolated branches/worktrees for parallel builders when possible
- GitHub remote configured for durable sync when the project is meant to live on GitHub

This makes runs reproducible and lets another agent resume from real project state, not only chat memory.


path: docs/runtime/OPENCLAW_LAUNCHER.md
content: # OpenClaw Launcher Protocol

## Goal
Bridge durable run state to actual OpenClaw subagent launches.

## Input
Launch manifests generated in:
- `runs/<run-id>/launch/`

Each manifest points to:
- run id
- phase
- role/agent
- handoff path
- project/worktree context
- suggested label

## Launcher behavior
An OpenClaw orchestrator session should:
1. run `python3 scripts/orchestration/launcher_preflight.py`
2. list pending launch manifests (`scripts/orchestration/list_pending_launches.py`)
3. read the referenced handoff markdown
4. call `sessions_spawn` with that handoff as the task prompt
5. only record a launch receipt via `scripts/orchestration/mark_launch.py` when the spawn is confirmed healthy

## Current blocker, clarified
The failure observed on 2026-04-20 and reproduced on 2026-04-21 is **not well explained by “hard-coded logic” or by heartbeat `999d` alone**.

What we can actually support with evidence is:
- `sessions_spawn` still times out even after heartbeat returned to `1d`
- similar spawn failures were already visible before the `999d` change
- the gateway log now shows repeated `active-memory timeout after 8000ms`, `lane wait exceeded`, and then gateway/tool timeouts

So the current best explanation is **gateway responsiveness / main-lane congestion**, not the orchestration design itself.

## Receipt rule
A `childSessionKey` returned alongside `status: error` is **not** a trustworthy launch receipt.

Treat a launch as real only when one of these is true:
- `sessions_spawn` returns success
- the child session becomes observable from the session tree
- an internal completion/update event proves the spawned child exists

Until then, do not mark the manifest as launched.

## Why manifests exist
Local scripts do not own OpenClaw tool access. The manifest is the durable bridge between file-native orchestration state and tool-native subagent spawning.

## Minimal contract
- handoff markdown remains the canonical task packet
- launch manifest is the canonical spawn request
- launch receipt is the canonical proof that an OpenClaw child session was spawned
- the orchestrator session remains the authority that actually launches agents


path: docs/runtime/PROJECT_BUILDER_WORKTREE.md
content: # Project Builder — Git Worktree Protocol

## Goal
Run `project-builder` against a real git repository/worktree so another agent can resume from concrete project state, not only chat state.

## Layout
- canonical repo root: existing git repository
- worktree base: `<worktree-root>/<repo>/<run-id>/`
- branch naming: `orch/<run-id>/<slot>`
- one worktree per active builder slot when parallel module work is needed

## Stable shared context
At each worktree root, expect:
- `README.md`
- `CLAUDE.md`

These are the first files a replacement agent should read.

## Shared temporary context
Per-run temporary context remains in:
- `agent/orchestration/runs/<run-id>/working-memory/`

Use it for:
- partial notes
- failed approaches
- unresolved questions
- integration concerns
- reviewer follow-up items

## Directed communication
Directed handoffs remain in:
- `agent/orchestration/runs/<run-id>/handoffs/`

## Resume protocol after agent failure
Replacement agent reads, in order:
1. worktree `README.md`
2. worktree `CLAUDE.md`
3. latest run handoff
4. run `working-memory/`
5. `git status`
6. latest relevant diff / branch history

## GitHub requirement
For GitHub-backed projects, a GitHub remote should exist before production use of `project-builder`.

The V1 helper validates whether a GitHub remote is configured. Pushing remains an explicit action, not an implicit side effect.


path: docs/runtime/README.md
content: # Orchestration V1

Minimal OpenClaw-native control plane for multi-agent workflows.

> Note: this document is preserved as a **runtime reference** from the original V1 implementation. It describes the original file-native runtime shape and may mention helper scripts that are not bundled directly inside this public folder.

## Layout
- `agents/` agent archetypes and contracts
- `workflows/` reusable workflow state machines
- `runs/` durable run state
- `templates/` handoff/review/checkpoint/temporary-context templates
- `scripts/orchestration/` runtime helpers
- `COMMUNICATION.md` communication model (stable context, handoff, temporary context)
- `PROJECT_BUILDER_WORKTREE.md` git/worktree protocol for project-builder
- `OPENCLAW_LAUNCHER.md` launcher protocol from launch manifests to real subagent spawns

## Typical flow
1. Create a run
2. Dispatch the current phase
3. Execute work with a sub-agent using the generated handoff packet
4. Mark the phase complete, or apply a structured review to route retries
5. Use watchdog/status for recovery and monitoring

## Commands
```bash
python3 scripts/orchestration/run_workflow.py project-builder --goal "Build X" --project-root /path/to/repo
python3 scripts/orchestration/prepare_project_builder.py <run-id> --project-root /path/to/repo --slot main --bootstrap-context
python3 scripts/orchestration/dispatch_step.py <run-id> --targets backend,frontend
python3 scripts/orchestration/complete_step.py <run-id> --summary "Spec done" --artifact spec=shared/specs/x.md
python3 scripts/orchestration/apply_review.py <run-id> agent/orchestration/runs/<run-id>/reviews/review-round1.md
python3 scripts/orchestration/escalate_run.py <run-id> --severity high --reason "..." --target human --next-action "..."
python3 scripts/orchestration/list_pending_launches.py
python3 scripts/orchestration/launcher_preflight.py
python3 scripts/orchestration/mark_launch.py <manifest-path> <session-key>
python3 scripts/orchestration/publish_worktree_branch.py <run-id> --slot main
python3 scripts/orchestration/status.py
python3 scripts/orchestration/watchdog.py --stale-minutes 45
```

## Notes
- Dispatch currently generates handoff packets and updates durable run state.
- Actual sub-agent spawning remains OpenClaw-native from the orchestrator session.
- Run `launcher_preflight.py` before launching manifests. If it reports gateway pressure, do not trust an erroring `sessions_spawn` result as a real launch.
- Stable project context should live in `README.md` + `CLAUDE.md` at the repo/worktree root when available.
- Rich temporary shared context lives under `runs/<run-id>/working-memory/`.
- This keeps V1 robust without coupling local scripts to a specific external runtime.


path: docs/runtime/SCHEMAS.md
content: # V1 Schemas

## Agent YAML
Required keys:
- `name`
- `purpose`
- `best_for`
- `avoid_for`
- `default_model_category`
- `input_contract`
- `output_contract`
- `reviewer_for`

## Workflow YAML
Required keys:
- `workflow_id`
- `goal`
- `entry_conditions`
- `phases`
- `completion_conditions`

Optional keys:
- `retry_modes`
- `retry_targets`
- `escalation_rules`

### Phase fields
Required:
- `id`

Optional:
- `agent`
- `output`
- `parallelism`
- `orchestrator_decision`
- `optional_if`

## Run state JSON
Required keys:
- `run_id`
- `workflow`
- `goal`
- `status`
- `phase`
- `phase_index`
- `iteration`
- `active_agents`
- `canonical_artifacts`
- `last_decision`
- `next_action`
- `blockers`
- `history`
- `created_at`
- `updated_at`
- `context`

Optional but recommended keys:
- `project_root`
- `shared_context_files`
- `missing_context_files`

## Review markdown
Use `agent/orchestration/templates/review.md` and keep these headings:
- `## Verdict`
- `## Severity`
- `## Issues`
- `## Minimal fix scope`
- `## Classification`
- `## Recommended next step`

The parser in `scripts/orchestration/apply_review.py` depends on those headings.


path: docs/setup-matrix.md
content: # Detailed Setup Matrix

## A. OpenClaw-only orchestration

### Shape
- main OpenClaw session orchestrates
- OpenClaw subagents do the work

### Strengths
- one tool universe
- one memory/runtime surface
- simple for short and medium tasks

### Weaknesses
- orchestration reliability depends more directly on gateway/session internals
- plugin/runtime hooks on the main session matter more
- not ideal for big coding swarms

### Verdict
Good for light orchestration, not the best default for 10+ heavy coding workers.

---

## B. OpenClaw control plane + ACP Claude Code workers

### Shape
- OpenClaw main = planning, state, checkpoints, reporting
- Claude Code ACP sessions = execution

### Strengths
- strong coding agent with persistent thread/session model
- less pressure on OpenClaw subagent path
- clean separation between control plane and execution plane

### Weaknesses
- requires better handoff discipline
- slightly more operational surface

### Verdict
**Best starting point.**

---

## C. OpenClaw control plane + ACP Codex workers

### Shape
- OpenClaw main = planning/control
- Codex ACP sessions = builders / patchers / testers

### Strengths
- efficient for repetitive code tasks
- good for broad patching and mechanical iteration
- useful as a cheaper parallel execution plane

### Weaknesses
- not my first choice for ambiguous architectural review
- may need stronger reviewer guardrails for subtle product/spec work

### Verdict
Great as a secondary execution engine, or for cost-sensitive parallel fix loops.

---

## D. Hybrid ACP team

### Shape
- OpenClaw main = orchestrator
- Claude Code ACP = architecture / nuanced builder / reviewer
- Codex ACP = fast builder / fixer / batch patcher

### Strengths
- best role specialization
- strongest for medium/large engineering efforts
- lets each runtime do what it is best at

### Weaknesses
- needs disciplined routing and file contracts
- easiest setup to get messy if handoffs are weak

### Verdict
Best long-term target once the simpler Claude Code-first version is working.

---

## E. External-first swarm

### Shape
- OpenClaw becomes almost only a coordinator / observer
- most heavy work happens in ACP/external coding sessions

### Strengths
- isolates heavy execution from OpenClaw runtime quirks
- can scale farther for coding-only swarms

### Weaknesses
- weakest integration with memory, messaging, and internal tools
- requires deliberate synchronization of state back into the shared file/state layer

### Verdict
Useful later, but not the best first refactor.

---

# Recommended target architecture

## Default
- **Control plane**: OpenClaw main
- **Default execution plane**: ACP Claude Code
- **Secondary execution plane**: ACP Codex when useful
- **State plane**: project/task files + `shared/` + `agent/orchestration/runs/`

## Routing rules

### Use OpenClaw-only when
- the task is short
- the task needs many first-class internal tools
- there are <= 2 workers and low code volume

### Use ACP Claude Code when
- the task is a real coding workstream
- the worker needs to stay persistent over time
- the repo context is large
- you want a builder or reviewer with strong coding depth

### Use ACP Codex when
- the task is patch-heavy or repetitive
- the changes are localized and testable
- you want a fast secondary worker for fix loops

### Use Hybrid ACP when
- there are multiple modules
- planning and execution deserve specialization
- you want builder/reviewer separation at runtime level

# Operational guardrails

1. Do not let the OpenClaw main session become a chatty execution worker.
2. Prefer persistent ACP sessions (`thread: true`, `mode: "session"`) for long coding work.
3. Use one worktree per builder stream when parallel edits are real.
4. Always materialize handoffs into files before launching workers.
5. Use OpenClaw for checkpoints and human-facing summaries, not for every edit.


path: docs/test-results.md
content: # Test Results

## Goal
Check whether the documented orchestration backends are actually runnable from the current environment.

## 2026-04-21 smoke tests

### 1. OpenClaw subagent
**Status:** PASS

What was tested:
- spawned a simple `runtime="subagent"` worker
- asked it to write `test-artifacts/openclaw-subagent-ok.txt`

Result:
- worker completed successfully
- file creation succeeded

### 2. ACP Claude Code
**Status:** PASS (after ACPX permission policy fix)

What was tested:
- spawned a simple `runtime="acp"`, `agentId="claude"` worker
- asked it to write a control file under `test-artifacts/`

Result:
- initial attempt failed with: **Permission prompt unavailable in non-interactive mode**
- fixed by setting ACPX runtime policy to:
  - `permissionMode: "approve-all"`
  - `nonInteractivePermissions: "deny"`
- after gateway restart, Claude Code ACP completed successfully

Interpretation:
- Claude Code ACP is now usable for unattended smoke-test level runs in this environment

### 3. ACP Codex
**Status:** PASS (after OpenAI key injection)

What was tested:
- spawned a simple `runtime="acp"`, `agentId="codex"` worker
- asked it to write a control file under `test-artifacts/`

Result:
- initial attempt failed with: **Authentication required**
- fixed by injecting `OPENAI_API_KEY` into the `openclaw-gateway.service` environment from the existing OpenClaw auth profile
- after gateway restart, Codex ACP completed successfully

Interpretation:
- Codex ACP is now usable for unattended smoke-test level runs in this environment

## Current practical conclusion

What works right now:
- OpenClaw subagents
- ACP Claude Code
- ACP Codex

## Recommendation

Keep the repo architecture Claude Code first.
Claude Code ACP and Codex ACP are now both validated for basic unattended runs here.
Use Claude Code as the default builder/reviewer backend, and Codex as a secondary builder/fixer where useful.


path: examples/session-patterns.md
content: # Session Patterns

## Default builder spawn

Use a persistent ACP Claude Code session for real coding work:

```json
{
  "task": "Implement the feature from shared/specs/x.md and write outputs under shared/artifacts/x/",
  "label": "x-builder",
  "runtime": "acp",
  "agentId": "claude",
  "thread": true,
  "mode": "session",
  "timeoutSeconds": 1200,
  "runTimeoutSeconds": 1200
}
```

## Reviewer spawn

```json
{
  "task": "Review the implementation in shared/artifacts/x/ against shared/specs/x.md. Return concrete deltas only.",
  "label": "x-reviewer",
  "runtime": "acp",
  "agentId": "claude",
  "thread": true,
  "mode": "session",
  "timeoutSeconds": 1200,
  "runTimeoutSeconds": 1200
}
```

## Targeted fixer spawn with Codex

```json
{
  "task": "Apply only the reviewer deltas listed in shared/reviews/x-round1.md. Keep the patch minimal.",
  "label": "x-fixer",
  "runtime": "acp",
  "agentId": "codex",
  "thread": true,
  "mode": "session",
  "timeoutSeconds": 1200,
  "runTimeoutSeconds": 1200
}
```

## Rule of thumb

- **Claude Code**: default builder/reviewer
- **Codex**: narrow fixer / patch worker
- **OpenClaw**: routing, state, summaries, human checkpoints


path: packs/agents/architect.yaml
content: name: architect
purpose: define structure, interfaces, and decomposition before build
best_for:
  - system design
  - module boundaries
  - tradeoff framing
avoid_for:
  - approving own architecture
  - low-level mechanical edits
default_model_category: brain
input_contract:
  - goal
  - constraints
  - spec
output_contract:
  - architecture plan
  - module split
  - risks
reviewer_for:
  - planner


path: packs/agents/builder.yaml
content: name: builder
purpose: produce artifacts that implement an approved plan or fix a bounded issue
best_for:
  - implementation
  - drafting
  - targeted revisions
avoid_for:
  - approving own work
  - open-ended planning
default_model_category: deep
input_contract:
  - canonical task brief
  - artifact targets
  - constraints
  - current review feedback if any
output_contract:
  - changed artifacts
  - verification notes
  - known limitations
  - next handoff
reviewer_for:
  - none


path: packs/agents/critic.yaml
content: name: critic
purpose: challenge a synthesis, plan, or design by surfacing weak evidence and hidden assumptions
best_for:
  - gap detection
  - adversarial review
  - robustness checks
avoid_for:
  - first-pass creation
default_model_category: brain
input_contract:
  - target artifact
  - evaluation criteria
output_contract:
  - weaknesses
  - missing evidence
  - recommended next pass
reviewer_for:
  - synthesizer
  - planner


path: packs/agents/integrator.yaml
content: name: integrator
purpose: merge module outputs into a consistent combined artifact
best_for:
  - interface alignment
  - final assembly
  - dependency stitching
avoid_for:
  - open-ended architecture work
default_model_category: deep
input_contract:
  - module artifacts
  - contract expectations
output_contract:
  - integrated artifact
  - integration notes
  - remaining mismatches
reviewer_for:
  - builder


path: packs/agents/ops.yaml
content: name: ops
purpose: inspect run health, summarize status, and detect stale or risky execution
best_for:
  - watchdog duties
  - summaries
  - stale-run checks
avoid_for:
  - product decisions
  - approving content quality
default_model_category: quick
input_contract:
  - run states
  - event logs
output_contract:
  - health assessment
  - anomalies
  - recommended intervention
reviewer_for:
  - none


path: packs/agents/planner.yaml
content: name: planner
purpose: decompose a goal into an execution plan with explicit deliverables and decision points
best_for:
  - scoping
  - decomposition
  - sequencing
avoid_for:
  - final approval
  - implementation-heavy work
default_model_category: brain
input_contract:
  - problem statement
  - constraints
  - success criteria
output_contract:
  - phases
  - deliverables
  - decision points
  - risks
reviewer_for:
  - deep-research
  - project-builder


path: packs/agents/researcher.yaml
content: name: researcher
purpose: investigate one bounded angle and produce evidence-backed findings
best_for:
  - literature review
  - web research
  - source gathering
avoid_for:
  - final synthesis
  - final decision making
default_model_category: deep
input_contract:
  - research angle
  - scope limit
  - expected output format
output_contract:
  - findings
  - evidence
  - open questions
reviewer_for:
  - none


path: packs/agents/reviewer.yaml
content: name: reviewer
purpose: verify artifacts against spec and classify failures for the next retry mode
best_for:
  - correctness checks
  - edge-case review
  - scope drift detection
  - failure classification
avoid_for:
  - first-pass implementation
  - approving work it authored
default_model_category: brain
input_contract:
  - canonical artifacts
  - expected outcome
  - verification criteria
output_contract:
  - verdict
  - issues_by_severity
  - minimal_fix_scope
  - classification
  - recommended_next_step
reviewer_for:
  - builder
  - architect
  - synthesizer


path: packs/agents/synthesizer.yaml
content: name: synthesizer
purpose: merge parallel findings into a coherent, decision-ready document
best_for:
  - synthesis
  - comparison
  - drafting conclusions
avoid_for:
  - raw source collection
  - approving own synthesis
default_model_category: brain
input_contract:
  - source memos
  - target structure
output_contract:
  - merged synthesis
  - gaps
  - claims_with_support
reviewer_for:
  - researcher


path: packs/templates/checkpoint.md
content: phase: ...
completed: ...
canonical_artifacts:
  - ...
last_decision: ...
next_action: ...
blockers:
  - ...


path: packs/templates/escalation.md
content: # Escalation

## Severity
low | medium | high | critical

## Run
...

## Phase
...

## Why this is escalated
...

## What has already been tried
- ...

## Recommended target
human | architect | reviewer | stronger-model | defer

## Recommended next action
- ...


path: packs/templates/handoff.md
content: ## What was done
...

## Canonical artifacts
- ...

## Verification
- ...

## Known issues
- ...

## Retry classification
- local-fix | partial-rebuild | replan | none

## Next action
- ...


path: packs/templates/project-builder-CLAUDE.md
content: # CLAUDE.md

## Project architecture
- ...

## Conventions
- ...

## Key files and directories
- ...

## Known constraints
- ...

## Current plan
- ...

## Open issues / risks
- ...

## What the next agent should read first
1. README.md
2. this CLAUDE.md
3. latest run handoff
4. run working-memory
5. git status / diff


path: packs/templates/project-builder-README.md
content: # Project Overview

## What this project is
...

## Primary goal of the current run
...

## Main modules / areas
- ...

## How to validate success
- ...

## Important external dependencies
- ...

## Current status
- ...


path: packs/templates/review.md
content: ## Verdict
pass | fail

## Severity
low | medium | high | critical

## Issues
- [id] description

## Minimal fix scope
- exact modules / files / artifacts affected

## Classification
local-defect | cross-module | architecture-spec

## Recommended next step
fix-loop | partial-rebuild | replan | escalate


path: packs/templates/temporary-context.md
content: # Temporary Context

## Current subproblem
...

## What has already been tried
- ...

## Partial findings
- ...

## Open questions
- ...

## Known pitfalls
- ...

## Suggested next move for the next agent
- ...


path: packs/workflows/batch-review.yaml
content: workflow_id: batch-review
goal: Process many similar items in bounded parallel batches
entry_conditions:
  - items can be reviewed or revised independently
phases:
  - id: split_batch
    agent: planner
    output: batch_plan
  - id: process_items
    agent: reviewer
    parallelism: 2-5
    output: item_reviews
  - id: aggregate
    agent: synthesizer
    output: batch_summary
retry_modes:
  failed_items_only: targeted-second-batch
retry_targets:
  failed_items_only: process_items
completion_conditions:
  - batch_summary_exists


path: packs/workflows/deep-research.yaml
content: workflow_id: deep-research
goal: Parallel research with synthesis and critique
entry_conditions:
  - question is broad enough to split into angles
phases:
  - id: plan
    agent: planner
    output: research_plan
  - id: parallel_research
    agent: researcher
    parallelism: 3-6
    output: angle_memos
  - id: synthesize
    agent: synthesizer
    output: draft_synthesis
  - id: critique
    agent: critic
    output: critique
  - id: targeted_second_pass
    optional_if: critique_identifies_major_gaps
retry_modes:
  missing_evidence: targeted-research-pass
  weak_synthesis: re-synthesis
retry_targets:
  missing_evidence: parallel_research
  weak_synthesis: synthesize
completion_conditions:
  - final_synthesis_exists
  - critique_resolved_or_accepted


path: packs/workflows/project-builder.yaml
content: workflow_id: project-builder
goal: End-to-end project execution with reviewer-guided retries
requirements:
  git_worktree: true
  github_remote: true
  stable_shared_context:
    - README.md
    - CLAUDE.md
  shared_temporary_context: runs/<run-id>/working-memory/
  prep_helper: scripts/orchestration/prepare_project_builder.py
  branch_pattern: orch/<run-id>/<slot>
  worktree_root_pattern: <worktree-root>/<repo>/<run-id>/<slot>
entry_conditions:
  - project goal is defined
  - deliverables are explicit enough to plan
phases:
  - id: spec
    agent: planner
    output: project_spec
  - id: architecture
    agent: architect
    output: architecture_plan
  - id: build_modules
    agent: builder
    parallelism: by_module
    output: module_artifacts
  - id: integrate
    agent: integrator
    output: integrated_artifact
  - id: review
    agent: reviewer
    output: structured_review
  - id: retry_router
    orchestrator_decision: true
  - id: integration_review
    agent: reviewer
    output: final_review
retry_modes:
  local-defect: fix-loop
  cross-module: partial-rebuild
  architecture-spec: replan
retry_targets:
  local-defect: build_modules
  cross-module: build_modules
  architecture-spec: architecture
escalation_rules:
  - if_same_failure_repeats_twice: escalate
  - if_no_checkpoint_for: 45m
  - if_scope_exceeds_expected_by: 2x
completion_conditions:
  - final_review_verdict == pass
  - canonical_artifacts_complete


path: packs/workflows/review-loop.yaml
content: workflow_id: review-loop
goal: Bounded builder-reviewer cycle with structured retries
entry_conditions:
  - task has a clear artifact target
  - success criteria are known
phases:
  - id: build
    agent: builder
    output: artifact
  - id: review
    agent: reviewer
    output: structured_review
  - id: route_retry
    orchestrator_decision: true
retry_modes:
  local-defect: fix-loop
  cross-module: partial-rebuild
  architecture-spec: replan
retry_targets:
  local-defect: build
  cross-module: build
  architecture-spec: build
escalation_rules:
  - if_same_failure_repeats_twice: escalate
  - if_iterations_gt: 3
completion_conditions:
  - reviewer_verdict == pass


path: packs/workflows/watchdog.yaml
content: workflow_id: watchdog
goal: Detect stale, blocked, or risky orchestration runs and recommend the next action
entry_conditions:
  - at least one active run exists
phases:
  - id: inspect_runs
    agent: ops
    output: health_report
  - id: classify_risk
    agent: reviewer
    output: risk_classification
  - id: route_recovery
    orchestrator_decision: true
retry_modes:
  stale_run: inspect_runs
retry_targets:
  stale_run: inspect_runs
completion_conditions:
  - risk_classification_exists


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)