System Dependencies
This skill requires the following system capabilities:
| Dependency | Purpose | Required? | Check |
|---|
python3 | Dashboard server (port 8765) | Yes | python3 --version |
node / npm | Project builds, Playwright | For web projects | node -v, npm -v |
playwright | E2E browser testing (Reviewers) | Optional, for E2E | npx playwright --version |
| ACP runtime | Builder/Reviewer agent execution | Optional, see below | Platform-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
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):
{
"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:
| Option | Configuration | Notes |
|---|
| ACP + qoder | runtime: "acp", agentId: "qoder" | Default, requires acpx plugin |
| ACP + claude | runtime: "acp", agentId: "claude" | Alternative ACP agent |
| ACP + codex | runtime: "acp", agentId: "codex" | OpenAI Codex |
| Subagent runtime | runtime: "subagent" | Built-in, no extra setup |
| PTY coding agents | exec with PTY | Claude 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
- Primary: Your preferred coding agent (e.g., qoder, claude)
- Fallback 1: Alternative ACP agent (e.g., claude if qoder is 429'd)
- 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 operationsexec — for running builds, tests, serverssessions_spawn, sessions_send, sessions_list — for agent communicationsubagents — for managing spawned agents
In openclaw.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:
{
"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
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
{
"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:
<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
pending → in_progress → ready_for_review → in_review → accepted
↑ |
└── needs_revision ──┘
Critical Rules
| Rule | Description |
|---|
| One action per heartbeat | Never do multiple spawns in one cycle |
| Spawn Reviewer immediately | Never leave ready_for_review more than one cycle |
| Reviewer writes results | Must write to review_history array, never just change state |
| E2E smoke test | Mandatory for bugfixes and new features before delivery |
| No archive copies | DO NOT copy project-state.json to archive/ |
Common Issues
| Issue | Fix |
|---|
| 429 rate limit | Wait, then re-spawn. Do NOT self-accept |
| Missing E2E | Bugfix/feature accepted → must spawn E2E Reviewer |
| Reviewer not spawned | Check sessions_list, spawn if missing |
| Builder timeout | Check if files exist, accept if complete |
| Archive duplicates | Orchestrator should NOT copy to archive/ |
Dashboard
Dashboard is included in assets/server.py and assets/dashboard.html.
Usage:
- Copy
assets/server.py and assets/dashboard.html to your project root directory
- Run:
python3 server.py
- 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.
