diff --git a/AGENT_BOARD.md b/AGENT_BOARD.md index 434fb7e..c7468fa 100644 --- a/AGENT_BOARD.md +++ b/AGENT_BOARD.md @@ -19,6 +19,7 @@ Bring the Windows 11 always-on PC, Tencent Cloud VPS OpenClaw Gateway, phone Con - 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 @@ -31,6 +32,7 @@ Bring the Windows 11 always-on PC, Tencent Cloud VPS OpenClaw Gateway, phone Con | 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 @@ -54,6 +56,7 @@ Bring the Windows 11 always-on PC, Tencent Cloud VPS OpenClaw Gateway, phone Con | 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 @@ -74,5 +77,7 @@ Bring the Windows 11 always-on PC, Tencent Cloud VPS OpenClaw Gateway, phone Con - 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. diff --git a/README.md b/README.md index aaad895..bf85014 100644 --- a/README.md +++ b/README.md @@ -9,12 +9,27 @@ Shared control-plane repository for coordinating Cursor agents across: ## Start Here +The user should normally read only: + +1. `USER_STATUS.md` + Every agent must read: 1. `AGENT_BOARD.md` 2. Its assigned file under `handoff/` 3. `.cursor/rules/agent-orchestration.mdc` +COACH sessions should also read: + +1. `handoff/COACH.md` +2. `docs/MULTI_AGENT_CURSOR_PLAYBOOK.md` +3. `docs/SESSION_FREEZE_PROTOCOL.md` +4. `knowledge/LESSONS_LEARNED.md` + +## Roles + +COACH is a guidance role normally carried by the main user-facing chat session. It does not require a separate agent window by default. ORCHESTRATOR remains responsible for task planning and acceptance gates. + ## Hard Safety Rule During ICP/public-security filing review, the existing `smartmotor.cloud` website is frozen. Do not change homepage content, linked page content reachable from the homepage, static assets, Nginx routing, Docker bind mounts, container images, or `/opt/services/docker-composite.yml` entries that could alter public website output. diff --git a/handoff/COACH.md b/handoff/COACH.md new file mode 100644 index 0000000..fbc87fa --- /dev/null +++ b/handoff/COACH.md @@ -0,0 +1,43 @@ +# COACH Handoff + +## Role + +COACH is the user-facing guidance role for the OpenClaw multi-agent workflow. By default, COACH is carried by the main chat session and does not require a separate Cursor agent window. + +## Scope + +- Help the user understand the current phase and single next action. +- Keep the workflow from devolving into manual cross-agent task management. +- Ensure `USER_STATUS.md` remains the human-facing status page. +- Trigger session freeze and knowledge capture before context exhaustion or handoff. +- Preserve reusable lessons in `knowledge/LESSONS_LEARNED.md`. +- Recommend improvements to the Cursor multi-agent method. + +## Boundaries + +- Do not replace ORCHESTRATOR's ownership of task decomposition and acceptance gates. +- Do not perform PC/VPS configuration changes. +- Do not bypass CORRECTION, verifier, or safety gates. +- Do not ask the user to manage internal task IDs unless debugging the control plane itself. + +## Current State + +- COACH role is confirmed by the user. +- COACH runs in a separate Cursor window from PC/VPS execution agents. +- `USER_STATUS.md` is the user's primary state page. +- Current project phase remains target-design confirmation before any connection/setup work. + +## Next Actions + +1. Keep guiding the user through OpenClaw target-design confirmation. +2. Ask ORCHESTRATOR to update `USER_STATUS.md` when user-facing state changes. +3. Freeze session state before context exhaustion or major handoff. +4. Capture reusable process insights in `knowledge/LESSONS_LEARNED.md`. + +## Resume Prompt + +```text +You are COACH for the OpenClaw multi-agent Cursor workflow. +Read USER_STATUS.md, AGENT_BOARD.md, handoff/COACH.md, docs/MULTI_AGENT_CURSOR_PLAYBOOK.md, docs/SESSION_FREEZE_PROTOCOL.md, and knowledge/LESSONS_LEARNED.md. +Guide the user with one clear next action. Do not perform PC/VPS configuration changes. +``` diff --git a/sync-state/heartbeat-pc.json b/sync-state/heartbeat-pc.json index 850f69b..e6d03a5 100644 --- a/sync-state/heartbeat-pc.json +++ b/sync-state/heartbeat-pc.json @@ -1,8 +1,8 @@ { "host": "pc", - "time": "2026-05-15T16:48:30+08:00", + "time": "2026-05-15T16:49:32+08:00", "branch": "main", - "head": "9c80dec", + "head": "e8640ea", "status": "dirty", "intervalSeconds": 30, "heartbeatEverySeconds": 60 diff --git a/sync/sync-agent.ps1 b/sync/sync-agent.ps1 index 31e6e65..5e15404 100644 --- a/sync/sync-agent.ps1 +++ b/sync/sync-agent.ps1 @@ -22,6 +22,9 @@ $AllowedPaths = @( "tasks", "sync", "sync-state", + "docs", + "knowledge", + "archive", ".gitattributes", ".gitignore" ) diff --git a/sync/sync-agent.sh b/sync/sync-agent.sh index f234bd6..95cd462 100644 --- a/sync/sync-agent.sh +++ b/sync/sync-agent.sh @@ -23,6 +23,9 @@ ALLOWED_PATHS=( "tasks" "sync" "sync-state" + "docs" + "knowledge" + "archive" ".gitattributes" ".gitignore" )