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.

Multi-Window Role Confirmation

When several Cursor windows are open, every window should make its role visible before work starts:

• Put the active role at the top of the working context or first message, such as Role: ORCHESTRATOR, Role: VPS_VERIFIER, or Role: PC_EXECUTOR.
• Before sending an execution or authorization prompt, check the visible workspace path and the relevant handoff/*.md file.
• Prompts that authorize token use, node run, approve, service changes, Docker/Nginx changes, firewall changes, or other mutation must echo the intended role and workspace in the first sentence.
• If the target role and current window role do not match, do not reinterpret the prompt. Stop and ask the user to resend it to the correct window.
• Verifier windows must not accept ORCHESTRATOR or EXECUTOR work, even if the requested content looks reasonable.
• ORCHESTRATOR must adopt or correct any cross-role control-plane edits before executors act on them.

Example safe authorization phrasing:

Target role: PC_EXECUTOR in D:\openclaw-control-plane.
Authorize only T9 foreground node run under docs/G2_RUNBOOK.md.

Unsafe phrasing:

Go ahead with G2.

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.
• Treat role mismatch as a safety blocker for execution or authorization prompts.

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.