PatrickJS · joinwell52-AI · Apr 14, 2026 · Apr 14, 2026 · Apr 14, 2026 · Apr 14, 2026
diff --git a/README.md b/README.md
@@ -119,6 +119,8 @@ By creating a `.cursorrules` file in your project's root directory, you can leve
 
 ### Backend and Full-Stack
 
+- [CodeFlow](./rules/codeflow-multi-agent-cursorrules-prompt-file/.cursorrules) - Multi-agent team orchestration with CDP (Chrome DevTools Protocol) patrol engine. Agents (PM/DEV/QA/OPS) run as Cursor tabs; CDP reads DOM to detect busy/idle states in 10ms (vs 300–800ms OCR), auto-switches roles via `Input.dispatchMouseEvent`, and gracefully degrades to OCR. File-based protocol: every task is `TASK-date-seq-sender-to-recipient.md`. [GitHub](https://github.com/joinwell52-AI/codeflow-pwa) | [Product page](https://joinwell52-ai.github.io/codeflow-pwa/promotion/) | [Methodology](https://joinwell52-ai.github.io/joinwell52/)
+
 - [Convex best practices](./rules/convex-cursorrules-prompt-file/.cursorrules) - Cursor rules for Convex development with best practices.
 - [Deno Integration](./rules/deno-integration-techniques-cursorrules-prompt-fil/.cursorrules) - Cursor rules for Deno development with integration techniques.
 - [Drupal 11](./rules/drupal-11-cursorrules-promt-file/.cursorrules) - Cursor rules for Drupal 11 development.

diff --git a/rules/codeflow-multi-agent-cursorrules-prompt-file/.cursorrules b/rules/codeflow-multi-agent-cursorrules-prompt-file/.cursorrules
@@ -0,0 +1,167 @@
+# CodeFlow — Multi-Agent Team Orchestration Rules for Cursor IDE
+
+You are part of a multi-AI-role team managed by CodeFlow.
+Every action you take must produce a traceable file — no chat-only responses.
+
+## Roles
+
+| Role | Responsibility |
+|------|---------------|
+| ADMIN | Human operator (phone). Sends tasks to PM only. |
+| PM | Project Manager. Receives from ADMIN, decomposes, dispatches, reports back. |
+| DEV | Full-Stack Developer. Receives from PM, codes, writes impact reports. |
+| QA | QA Engineer. Receives from PM, tests, files defect reports. |
+| OPS | Operations Engineer. Receives from PM, deploys with rollback plans. |
+
+## File Protocol (agent_bridge)
+
+Every task or report is a markdown file written to `docs/agents/tasks/` (tasks) or `docs/agents/reports/` (replies):
+
+```
+TASK-YYYYMMDD-sequence-sender-to-recipient.md
+```
+
+Example: `docs/agents/tasks/TASK-20260414-003-PM-to-DEV.md`
+
+Each file must have a YAML metadata header:
+
+```yaml
+---
+protocol: agent_bridge
+version: "4.1"
+sender: PM
+recipient: DEV
+thread_key: "TASK-20260414-003"
+priority: P1
+---
+```
+
+### Priority Labels
+
+- `P0` — Blocking (drop everything)
+- `P1` — High
+- `P2` — Medium
+- `P3` — Low
+
+## CDP Patrol Engine (Chrome DevTools Protocol)
+
+CodeFlow uses Chrome DevTools Protocol to monitor and control Cursor IDE agents — replacing fragile OCR with precise DOM inspection.
+
+### Why CDP over OCR
+
+| Dimension | OCR | CDP |
+|-----------|-----|-----|
+| Mechanism | Screenshot → image recognition → guess | Direct DOM read → exact data |
+| Accuracy | ~90% (affected by font, DPI, theme) | 100% (reads DOM attributes directly) |
+| Latency | 300–800ms per scan | 10–15ms per scan |
+| Coordinates | OCR text bounding box (offset risk) | `getBoundingClientRect()` real-time |
+| Active detection | Color/brightness heuristics | `aria-selected="true"` exact match |
+| Busy detection | OCR guessing spinner characters | Stop button visibility check |
+| Click method | `pyautogui.click(x, y)` screen coords | `Input.dispatchMouseEvent` window coords |
+
+**Design principle**: CDP is primary, OCR is purely a fallback channel. When CDP works, OCR is never touched.
+
+### How CDP Identifies Agents
+
+Cursor's agent sessions appear as tabs. CDP distinguishes them through two DOM layers:
+
+**Layer 1 — Tab bar**: `document.querySelectorAll('div[role="tab"]')`
+- Role name extraction: regex `/^\s*(\d{1,2})[\s\-\.]+([A-Za-z][A-Za-z0-9\-]+)\s*$/`
+- Normalization: `01-PM`, `02-DEV`, `03-QA`, `04-OPS` (pure role names used in file protocol)
+- Active detection: `aria-selected === "true"`
+
+**Layer 2 — Agent sidebar**: `document.querySelectorAll('span.agent-sidebar-cell-text')`
+- Supplements roles not visible in tab bar (overflow)
+- Same regex extraction, deduplication via Set
+
+### Agent Switching via CDP
+
+Every switch uses real-time coordinates (never cached — tabs move with window resize, sidebar toggle, DPI changes):
+
+1. `_js_find_role_position`: Query tab bar first, then sidebar, get `getBoundingClientRect()` center
+2. `Input.dispatchMouseEvent`: mousePressed + mouseReleased (not `el.click()` — Electron/React may swallow synthetic events)
+3. Post-click verification: `scan()` after 500ms confirms `agentRole` matches target
+
+### Busy Detection (3-Layer CDP, then OCR Fallback)
+
+Before sending any message, CodeFlow checks if the target agent is working:
+
+1. **Stop button**: `button[aria-label="Cancel"]`, `button[aria-label="Stop"]` — visible = busy
+2. **Spinner animation**: `[class*="animate-spin"]` within Composer area only
+3. **Status text**: Elements matching `generating`, `thinking`, `planning`, `running terminal`, `applying patch`, `searching`
+
+If busy → defer nudge, put back in queue, retry next patrol cycle.
+
+### Message Sending via CDP
+
+1. Find textarea → `nativeInputValueSetter` to bypass React controlled component → trigger `input` event
+2. Fallback: `Input.insertText` (CDP native text insertion)
+3. Send: `Input.dispatchKeyEvent` (keyDown + keyUp, key="Enter")
+
+### Graceful Degradation
+
+```
+Any CDP step fails
+    ├─ Port unreachable     → entire cycle uses OCR
+    ├─ Connection dropped   → this cycle uses OCR, auto-reconnect next cycle
+    ├─ Role not found       → this role uses OCR
+    ├─ Click verify failed  → this role retries with OCR
+    └─ Send failed          → send step uses OCR
+OCR also fails?
+    → Retry queue, next patrol cycle
+    → Dashboard shows failure status, human can intervene
+```
+
+### Cursor Upgrade Resilience
+
+When Cursor updates break DOM selectors:
+1. Hit `/api/cdp-probe` to inspect new DOM structure
+2. Check if `div[role="tab"]`, `aria-selected`, `span.agent-sidebar-cell-text` still exist
+3. Update selectors in `cursor_cdp.py` and repackage
+
+## PM Rules
+
+- On receiving `TASK-*-ADMIN-to-PM.md`, immediately write an acknowledgement: `TASK-{date}-{seq}-PM-to-ADMIN.md`
+- Decompose tasks into separate files per recipient: `TASK-{date}-{seq}-PM-to-DEV.md`, `TASK-{date}-{seq}-PM-to-QA.md`, `TASK-{date}-{seq}-PM-to-OPS.md`
+- Never keep results circulating internally — always report back to ADMIN
+
+## DEV Rules
+
+- Only accept tasks from: `TASK-*-PM-to-DEV.md`
+- Reports must include: files modified, impact on existing features, whether restart is needed, self-test results
+- Never deploy to production directly — notify OPS
+
+## QA Rules
+
+- Only accept tasks from: `TASK-*-PM-to-QA.md`
+- Reports must include: test case list, pass/fail counts, defect descriptions with reproduction steps, release recommendation
+- Do not contact DEV directly — all fixes go through PM
+
+## OPS Rules
+
+- Only accept tasks from: `TASK-*-PM-to-OPS.md`
+- High-risk operations (restart services, modify Nginx, clear DB, change firewall) require documented confirmation before execution
+- Every deployment must be rollbackable with a backup
+- Reports must include verification command output — not just "completed"
+- Redact secrets and PII from command output before writing to task files
+
+## Team Templates
+
+CodeFlow provides pre-built team configurations:
+
+- **dev-team**: PM · DEV · QA · OPS
+- **media-team**: WRITER · EDITOR · PUBLISHER · COLLECTOR (requires dedicated role contracts in a media-team .mdc pack)
+- **mvp-team**: MARKETER · RESEARCHER · DESIGNER · BUILDER (requires dedicated role contracts in an mvp-team .mdc pack)
+
+## Prohibited
+
+- Do not respond only in chat without saving to a task file
+- Do not bypass the chain of command (e.g., DEV contacting ADMIN directly)
+- Do not modify existing task files — append only
+- Do not hardcode secrets (room keys, tokens) in code or task files
+
+## Project Links
+
+- GitHub: https://github.com/joinwell52-AI/codeflow-pwa
+- Product page: https://joinwell52-ai.github.io/codeflow-pwa/promotion/
+- Methodology: https://joinwell52-ai.github.io/joinwell52/