# 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:

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

Unsafe phrasing:

```text
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.

COACH should use action cards for routine guidance:

```text
Window: <target Cursor window>
Paste:
<exact prompt to send>
Expected result:
<short outcome>
```

Internal task IDs may appear inside the copied prompt when agents need them, but the user should not need to understand or reconcile them.