System Dependencies#

This skill requires the following system capabilities:

DependencyPurposeRequired?Checkpython3Dashboard server (port 8765)Yespython3 --version``node / npmProject builds, PlaywrightFor web projectsnode -v, npm -v``playwrightE2E browser testing (Reviewers)Optional, for E2Enpx playwright --versionACP runtimeBuilder/Reviewer agent executionOptional, see belowPlatform-specific

No specific coding agent is required. The default configuration uses ACP + qoder, but you can use any available agent runtime. See First-Time Setup for configuration options.

Security Notes#

⚠️ Dashboard server ( server.py):

• Binds to 127.0.0.1:8765 only — never expose to public network
• Serves files from the project directory — verify no secrets (API keys, tokens) are present
• Includes path traversal protection via safe_path() check

⚠️ Code execution:

• Builders and Reviewers will execute and run arbitrary project code
• For web projects: HTTP server serves project files locally
• E2E tests use Playwright to open and interact with pages in a real browser
• Only run on machines where executing generated code is acceptable
• Use containers/VMs for untrusted projects

First-Time Setup#

When a user installs this skill for the first time, guide them through the following steps:

Step 1: Create Project Workspace#

bash

mkdir -p my-projects/{requests/done,logs}
cp <skill-dir>/assets/server.py my-projects/
cp <skill-dir>/assets/dashboard.html my-projects/
cd my-projects

This creates the project root with all required directories and the Dashboard assets.

Step 2: Configure Orchestrator Agent#

Create an Orchestrator agent in your openclaw.json (or equivalent config):

json

{
  "id": "orchestrator",
  "name": "Orchestrator",
  "workspace": "<your-path>/my-projects"
}

Give the Orchestrator a heartbeat prompt that references references/orchestrator-rules.md.

Step 3: Configure Builder Agent(s)#

Choose your preferred coding agent(s). Options:

OptionConfigurationNotesACP + qoderruntime: "acp", agentId: "qoder"Default, requires acpx pluginACP + clauderuntime: "acp", agentId: "claude"Alternative ACP agentACP + codexruntime: "acp", agentId: "codex"OpenAI CodexSubagent runtimeruntime: "subagent"Built-in, no extra setupPTY coding agentsexec with PTYClaude Code, Codex CLI, etc.

The Orchestrator rules ( references/orchestrator-rules.md) default to ACP + qoder, but you should update the agent ID to match your setup.

Recommended: Set up a 3-tier fallback chain

1. Primary: Your preferred coding agent (e.g., qoder, claude)
2. Fallback 1: Alternative ACP agent (e.g., claude if qoder is 429'd)
3. Fallback 2: Built-in subagent runtime

Step 4: Allow Tool Access#

Ensure your Orchestrator and Builder agents have access to:

• read, write, edit — for file operations
• exec — for running builds, tests, servers
• sessions_spawn, sessions_send, sessions_list — for agent communication
• subagents — for managing spawned agents

In openclaw.json:

json

{
  "tools": {
    "sessions": {
      "visibility": "all"
    },
    "agentToAgent": {
      "enabled": true,
      "allow": ["main", "orchestrator", "qoder-dev", "claude-dev"]
    }
  },
  "acp": {
    "enabled": true,
    "backend": "acpx",
    "defaultAgent": "qoder",
    "allowedAgents": ["qoder", "claude", "codex"]
  }
}

Step 5: Choose Your LLM#

Set the default model for the Orchestrator and agents:

json

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "your-provider/your-model"
      }
    }
  }
}

For coding agents (qoder, claude, codex), they use their own model — no LLM config needed.

Step 6: Verify Setup#

bash

cd my-projects
python3 server.py
# Open http://localhost:8765 — should show empty dashboard

---

Harness Deep Coding System#

Multi-agent development: Orchestrator decomposes → Builders code → Reviewers verify → E2E test → deliver.

Roles#

User-Facing Agent (you)#

• Gather requirements through conversation
• Create request JSON at projects/requests/TIMESTAMP.json (use actual timestamp)
• Notify Orchestrator via sessions_send to agent:orchestrator:main
• Report progress every heartbeat when project is active

Orchestrator#

• Decomposes project into 2-4 modules + mandatory integration-test
• Creates project-state.json with module states
• Spawns Builders and Reviewers via sessions_spawn
• Monitors progress via heartbeat, handles failures
• Runs E2E smoke test after bugfix/feature accepted

Builder#

• Codes independently per module
• Uses configured agent runtime (ACP subagent, or fallback)
• Writes to logs/builder-MODULE.log (APPEND, UTC+8)

Reviewer#

• MUST actually test the application, not just read code
• For web projects: serve via HTTP, verify in browser
• Writes detailed review results to review_history
• Writes to logs/reviewer-MODULE.log (APPEND, UTC+8)

User-Facing Workflow#

1. Gather Requirements#

• What to build, key features, constraints, tech stack
• Break into 2-4 logical modules (data → core → render → UI)
• Auto-add final integration-test module depending on ALL others

2. Create Request#

json

{
  "name": "Project Name",
  "description": "What it does",
  "owner": "user name",
  "tags": ["web", "game"]
}

Path: <project-root>/requests/TIMESTAMP.json (use actual timestamp)

3. Notify Orchestrator#

Send to agent:orchestrator:main:

• Request file path
• Instructions to decompose into modules
• Create project-state.json
• Spawn Builder for first module
• Use per-agent logs, APPEND mode, UTC+8
• Run E2E smoke test after acceptance

4. Progress Reporting#

Read project-state.json every heartbeat:

• Report completion % and module states
• Announce 100% completion

Project Structure#

All paths are relative to your project root directory:

text

<project-root>/
├── projects-registry.json          ← All projects overview
├── server.py                       ← Dashboard server (port 8765)
├── dashboard.html                  ← Dashboard UI
├── requests/
│   └── done/                       ← Processed requests
├── logs/                           ← Agent activity logs
├── PROJECT-SLUG/
│   ├── project-state.json           ← Module states, review history
│   ├── logs/
│   │   ├── orchestrator.log         ← Orchestrator decisions
│   │   ├── builder-MODULE.log       ← Each Builder writes own file
│   │   └── reviewer-MODULE.log      ← Each Reviewer writes own file
│   └── SOURCE CODE (generated files)

See references/architecture.md for full project structure, module lifecycle, and dashboard details.

Module Lifecycle#

text

pending → in_progress → ready_for_review → in_review → accepted
                        ↑                    |
                        └── needs_revision ──┘

Critical Rules#

RuleDescriptionOne action per heartbeatNever do multiple spawns in one cycleSpawn Reviewer immediatelyNever leave ready_for_review more than one cycleReviewer writes resultsMust write to review_history array, never just change stateE2E smoke testMandatory for bugfixes and new features before deliveryNo archive copiesDO NOT copy project-state.json to archive/

Common Issues#

IssueFix429 rate limitWait, then re-spawn. Do NOT self-acceptMissing E2EBugfix/feature accepted → must spawn E2E ReviewerReviewer not spawnedCheck sessions_list, spawn if missingBuilder timeoutCheck if files exist, accept if completeArchive duplicatesOrchestrator should NOT copy to archive/

Dashboard#

Dashboard is included in assets/server.py and assets/dashboard.html.

Usage:

1. Copy assets/server.py and assets/dashboard.html to your project root directory
2. Run: python3 server.py
3. Open: http://localhost:8765

Security: The server binds to 127.0.0.1 only and includes path traversal protection.

Features: project list, completion status, module states, agent activity timeline.