openclaw-control-plane/AGENT_BOARD.md

# OpenClaw Agent Control Board

> Source of truth for multi-agent work across the Windows PC workspace and the VPS `/opt/service` workspace.

## Mission

Bring the Windows 11 always-on PC, Tencent Cloud VPS OpenClaw Gateway, phone Control UI, optional Tailscale path, and later channels such as QQ into a controlled multi-device OpenClaw workflow.

## Current Decision

- Shared mechanism: use the VPS Gitea repository as the durable sync point.
- Repository mode: standalone Gitea repository `openclaw-control-plane`.
- Repository URL: `https://git.smartmotor.cloud/wangzhendong/openclaw-control-plane.git`.
- Authentication mode: HTTPS access from both the Windows PC and VPS.
- Default branch: `main`.
- PC control-plane path: `D:\openclaw-control-plane`.
- VPS control-plane path: `/home/ubuntu/openclaw-control-plane`.
- Secrets policy: no password, token, API key, or `OPENCLAW_GATEWAY_TOKEN` may be written into repo files, handoffs, evidence, or chat.
- Frozen website policy: strict freeze during ICP/public-security filing review. Agents must not change the `smartmotor.cloud` homepage, content reachable from homepage links, static assets, Nginx routing, bind mounts, container images, or `/opt/services/docker-composite.yml` entries that could alter public website output.
- Communication MVP: use Git-backed polling sync scripts under `sync/` plus task files under `tasks/`. This reduces manual pull/push but is not the final async-notification design.
- Sync-health monitoring: CORRECTION monitors tracked heartbeat and error files under `sync-state/`; no separate sync monitor agent is used at this stage.
- COACH role: the main user-facing chat acts as COACH by default, guiding workflow usability, session freeze, and knowledge capture without replacing ORCHESTRATOR.
- Future communication target: when the baseline path is stable, design an event-driven coordinator using Gitea webhooks, Gitea Issues, OpenClaw events, or Cursor SDK agent orchestration.

## Agent Roles

| Role | Scope | May Write |
|---|---|---|
| ORCHESTRATOR | Requirements alignment, task split, dependency tracking, final acceptance | `AGENT_BOARD.md`, `handoff/ORCHESTRATOR.md` |
| PC_EXECUTOR | Windows PC, Tailscale, OpenClaw CLI/node, local service install | `handoff/PC_EXECUTOR.md`, `evidence/pc-*`, `rollback/pc-*` |
| VPS_EXECUTOR | VPS `/opt/service`, Gateway, Docker stack, Nginx, Gitea, approvals | `handoff/VPS_EXECUTOR.md`, `evidence/vps-*`, `rollback/vps-*` |
| PC_VERIFIER | Independent read-only validation of PC executor results | `handoff/PC_VERIFIER.md`, `evidence/verify-pc-*` |
| VPS_VERIFIER | Independent read-only validation of VPS executor results | `handoff/VPS_VERIFIER.md`, `evidence/verify-vps-*` |
| CORRECTION | Detect drift, sync-health failures, conflicts, unsafe changes, missing evidence, and rollback needs | `handoff/CORRECTION.md`, `tasks/T7-correction-monitor.md` |
| COACH | Guide user experience, session freeze, knowledge capture, and reusable method | `handoff/COACH.md`, `USER_STATUS.md`, `docs/`, `knowledge/`, `archive/` |

## Quality Gates

| Gate | Required Evidence | Owner | Status |
|---|---|---|---|
| G0 Requirements aligned | User-approved mission, roles, and acceptance criteria | ORCHESTRATOR | Pending |
| G1 Baseline discovered | PC and VPS read-only status snapshots | PC_EXECUTOR, VPS_EXECUTOR, verifiers | Pending |
| G2 Gateway/node pairing ready | PC `node run` evidence and VPS approval evidence | PC_EXECUTOR, VPS_EXECUTOR | Pending |
| G3 Execution smoke test | Harmless command result proves execution came from the PC node | PC_VERIFIER | Pending |
| G4 Persistent service verified | `node install/start/status` and reboot survival evidence | PC_VERIFIER, CORRECTION | Pending |
| G5 Security posture reviewed | Secrets absent, public exposure avoided, least-privilege notes captured | VPS_VERIFIER, CORRECTION | Pending |

## Active Tasks

| ID | Task | Owner | Depends On | Status |
|---|---|---|---|---|
| T0 | Create local control-plane scaffold | ORCHESTRATOR | None | Done |
| T1 | Create standalone Gitea repo for this control plane | User + ORCHESTRATOR | T0 | Done |
| T2 | Sync this scaffold to Gitea and open on PC/VPS Cursor | ORCHESTRATOR + VPS_EXECUTOR | T1 | Done |
| T2.1 | Add polling sync and task-file communication MVP | ORCHESTRATOR | T2 | In Progress |
| T3 | Run read-only PC baseline discovery | PC_EXECUTOR | T2.1 | Ready |
| T4 | Run read-only VPS baseline discovery | VPS_EXECUTOR | T2.1 | Ready |
| T5 | Verify both baselines before any config change | PC_VERIFIER + VPS_VERIFIER | T3, T4 | Pending |
| T8 | Solidify COACH role, session freeze, and knowledge capture | COACH | T2.1 | In Progress |

## Acceptance Criteria Draft

- The PC can act as an OpenClaw execution node connected to the existing Gateway.
- The Gateway continues to coexist with Nginx, Gitea, Confluence, and Postgres on the VPS.
- The existing `smartmotor.cloud` website content remains unchanged during filing review, including homepage content and linked content reachable from the homepage.
- No PC service port is exposed directly to the public internet.
- Tailscale is optional for the OpenClaw public Gateway path, but available for safer device-to-device operations.
- Phone can be used as a control client after the execution path is stable.
- Later QQ or other channels are added only after the Gateway/node path is verified.

## Operating Rules

- Agents must read this file before doing work.
- Executors must not accept work outside their named scope.
- Executors must not validate their own work as complete.
- VPS-related agents must treat the `smartmotor.cloud` website defined by `/opt/services/docker-composite.yml` as frozen: no edits to homepage content, linked page content, routing, static assets, bind mounts, container images, or Nginx rules that could alter what public visitors see.
- Polling sync scripts are convenience automation only. If they report conflict, authentication failure, or unexpected files, stop and let CORRECTION review.
- Sync scripts must publish non-secret heartbeat/error status under `sync-state/`. Heartbeat older than 2 minutes is warning; older than 5 minutes is blocked.
- Task files under `tasks/` are the agent-to-agent work contract. Chat messages are not the source of truth.
- COACH should keep user-facing guidance in `USER_STATUS.md` and reusable practice in `docs/`, `knowledge/`, and `archive/`.
- Before context exhaustion or major handoff, active roles must perform session freeze using `docs/SESSION_FREEZE_PROTOCOL.md`.
- Any system-level change requires a rollback note before execution.
- Any blocking issue must be recorded in the relevant handoff file and surfaced to ORCHESTRATOR.