openclaw-control-plane/docs/MULTI_AGENT_CURSOR_PLAYBOOK.md

Multi-Agent Cursor Playbook

This playbook captures the OpenClaw control-plane practice so it can be reused for other long-running Cursor multi-agent tasks.

Core Pattern

Use three layers:

• User layer: USER_STATUS.md and COACH guidance. This is the only layer the user should need to read.
• Orchestration layer: AGENT_BOARD.md, tasks/, and role handoffs. ORCHESTRATOR owns this layer.
• Evidence layer: evidence/, rollback/, sync-state/, and phase archives. Executors and verifiers write durable facts here.

Cursor Window Layout

Recommended windows:

• COACH window: main user conversation, guidance, workflow design, and knowledge capture.
• PC control-plane window: ORCHESTRATOR, CORRECTION, PC executor/verifier roles.
• VPS control-plane window: VPS executor/verifier roles.
• Dedicated terminals: PC and VPS sync scripts. Do not let normal chat agents own these long-running terminals.

Role Boundaries

• ORCHESTRATOR owns requirements, task split, dependency state, and acceptance gates.
• EXECUTOR roles do only assigned work and do not accept their own output.
• VERIFIER roles independently review evidence.
• CORRECTION detects drift, sync-health failures, safety violations, and missing evidence.
• COACH helps the user navigate the workflow and preserves lessons learned.

Communication

The MVP uses Git polling:

• PC script: sync/sync-agent.ps1
• VPS script: sync/sync-agent.sh
• Health files: sync-state/heartbeat-*.json and sync-state/error-*.md

Git is the durable source of truth. It is not a real-time message bus. Upgrade later to webhooks, Gitea Issues, OpenClaw events, or a Cursor SDK coordinator.

Safety Gates

• Freeze smartmotor.cloud website output during filing review.
• Do not store secrets in files, evidence, commits, or chat.
• Do not enter mutation stages while sync health is blocked.
• Require rollback notes before persistent service, routing, firewall, Docker, or environment changes.

User Experience Rule

Do not ask the user to manage internal task numbers. When status is confusing, update USER_STATUS.md and give one next action.