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