diff --git a/README.md b/README.md index 63c6a2ff..6e97fa51 100644 --- 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 new file mode 100644 index 00000000..0d9bc997 --- /dev/null +++ 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/