docs(agent-workflows): Cursor Cloud Agents parallel workflow (#1480)#1740
Closed
CodeGhost21 wants to merge 4 commits into
Closed
docs(agent-workflows): Cursor Cloud Agents parallel workflow (#1480)#1740CodeGhost21 wants to merge 4 commits into
CodeGhost21 wants to merge 4 commits into
Conversation
…yhumansai#1480) Documents the pilot-then-scale workflow for running 15-20 Cursor Cloud Agents in parallel against the codebase. Covers per-lane ownership boundaries to prevent file collisions, launch trigger format, branch/PR conventions, quality gates the agent runs inside its container, secrets posture for agent runs, and the operator dashboard for batch progress. Closes tinyhumansai#1480
Pure whitespace: prettier widened existing markdown tables to the standard column width and inserted a required blank line after a heading that the new edits made the linter notice. No content change.
…ai#1480) Adds scripts/agent-batch-overlap.mjs, the pre-launch collision check referenced in the Cursor Cloud Agents workflow doc. Reads a JSON batch file, reports lane assignments / pairwise path overlap / choke-point conflicts, and exits non-zero on collisions. Negative-tested against an intentionally bad batch (caught out-of-lane paths, same-lane duplicates, and parent/child path overlap). Also adds docs/agent-workflows/pilot-batch-1480.json — the validated pilot batch for issue tinyhumansai#1480 covering three lane-disjoint upstream issues (tinyhumansai#1502 frontend-ui, tinyhumansai#1675 rust-core/agent, tinyhumansai#1599 ci-config). The script reports PASS on this pilot. Updates cursor-cloud-agents.md to drop the "if not present yet" caveat since the helper now exists, and to point at the canonical batch format.
Adds scripts/agent-batch-comments.mjs — reads the same batch JSON shape as the overlap helper and prints a copy-pasteable parent-issue body plus one launch comment per child issue. Makes the launch step reproducible for any batch, not just hand-edited for the pilot. Updates the operator runbook in cursor-cloud-agents.md to reference the generator and renumbers the steps to include the new "Generate the paste buffer" step between the collision check and opening the parent issue.
Contributor
📝 WalkthroughWalkthroughThis PR establishes end-to-end infrastructure for parallel Cursor Cloud Agents: a comprehensive runbook specifying agent preflight, branch/PR conventions, lane-based ownership boundaries, quality gates, and secrets posture; two new validation and generation scripts to pre-check batch collisions and generate GitHub comments; pilot batch configuration; and updated contributor guide documentation. ChangesCursor Cloud Agents Workflow
Sequence DiagramsequenceDiagram
participant Operator as Operator
participant BatchJSON as Batch JSON<br/>(pilot-batch-1480.json)
participant Overlap as agent-batch-overlap.mjs
participant Comments as agent-batch-comments.mjs
participant GitHub as GitHub Issues/PRs
participant Agent as Cursor Cloud Agent
participant QualityGates as Quality Gates<br/>(format, test, coverage)
Operator->>BatchJSON: Select issues & assign lanes
Operator->>Overlap: Run collision check
Overlap->>Overlap: Validate paths in lanes
Overlap->>Overlap: Detect overlaps & choke-points
Overlap-->>Operator: PASS/FAIL report
Operator->>Comments: Generate parent issue & launch comments
Comments->>Comments: Build checklist & lane assignments
Comments-->>Operator: Markdown copy-buffer
Operator->>GitHub: Post parent issue with checklist
Operator->>GitHub: Post per-issue launch comment
GitHub-->>Agent: Trigger Cursor Cloud Agent
Agent->>Agent: Run preflight checks
Agent->>Agent: Checkout & verify workspace binding
Agent->>GitHub: Create branch cursor/issue-N-slug
Agent->>Agent: Implement within lane scope
Agent->>QualityGates: Run format/lint/typecheck/tests
Agent->>QualityGates: Enforce diff-coverage ≥80%
Agent->>GitHub: Push PR with required label
GitHub-->>Operator: Dashboard update (Project board, checklist)
Operator->>Operator: Monitor blocked PRs, reconcile merged
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Warning There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure. 🔧 ESLint
ESLint skipped: no ESLint configuration detected in root package.json. To enable, add Tip 💬 Introducing Slack Agent: The best way for teams to turn conversations into code.Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.
Built for teams:
One agent for your entire SDLC. Right inside Slack. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (3)
docs/agent-workflows/cursor-cloud-agents.md (1)
109-112: ⚡ Quick winRemove vague "etc." from script invocation description.
Line 112 says the script reports choke-point conflicts and ends with "etc." — but the script's collision categories are finite and well-defined (lane assignments, path overlap, choke-point conflicts). The "etc." suggests open-ended output when the script's reports are actually exhaustive.
✂️ Clarify script output description
-The script reports lane assignments, pairwise path overlap, and choke-point conflicts (`src/core/all.rs`, controller registries, `tauri.conf.json`, `package.json`, `Cargo.lock`, `pnpm-lock.yaml`, etc.). It exits non-zero on any collision. +The script reports lane assignments, pairwise path overlap, and choke-point conflicts. It exits non-zero on any collision.The detailed choke-point list is already covered at line 102; repeating a partial list here adds no value.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/agent-workflows/cursor-cloud-agents.md` around lines 109 - 112, Update the description of the batch-check script invocation to remove the vague "etc." and make the output categories explicit: state that node scripts/agent-batch-overlap.mjs docs/agent-workflows/<your-batch>.json reports lane assignments, pairwise path overlap, and choke-point conflicts (and that it exits non-zero on any collision). Replace the trailing "etc." with that explicit, finite list (or simply end the sentence after "choke-point conflicts") so readers know the script's reports are exhaustive; reference the collision detection implementation files (src/core/all.rs) and related config registries only if you want to point to where each category originates.scripts/agent-batch-overlap.mjs (1)
213-222: ⚡ Quick winFix same-lane collision logic for rust-core lanes.
The parallel-safe lane filtering has a logic error. Line 220 correctly returns
false(non-fatal) for any lane starting withrust-core/, but line 221 checks!PARALLEL_OK.includes(lane)wherelaneis something like"rust-core/agent"whilePARALLEL_OKcontains"rust-core/<domain>"(the template string literal). This check will never match, making line 221 unreachable for rust-core lanes.The early return at line 220 makes line 221 dead code for rust-core lanes, so the current behavior is correct but confusing.
♻️ Clearer same-lane collision logic
const PARALLEL_OK = ["rust-core/<domain>"]; const fatalSameLane = sameLaneCollisions.filter((nums) => { const lane = issues.find((i) => i.number === nums[0]).lane; - if (lane.startsWith("rust-core/")) return false; // sub-domains are distinct - return !PARALLEL_OK.includes(lane); + // rust-core/<domain> lanes are parallel-safe (each subdomain is distinct) + return !lane.startsWith("rust-core/"); });This removes the unused
PARALLEL_OKarray and clarifies the intent: rust-core lanes are always parallel-safe.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@scripts/agent-batch-overlap.mjs` around lines 213 - 222, The collision filter is confusing because PARALLEL_OK contains the template "rust-core/<domain>" which never matches real lanes like "rust-core/agent", making the includes check unreachable for rust-core lanes; remove the PARALLEL_OK array and simplify the fatalSameLane filter in the sameLaneCollisions logic (referencing fatalSameLane, sameLaneCollisions, and issues) so it explicitly returns false for lanes that start with "rust-core/" and otherwise treats the collision as fatal (i.e., return true for non-rust-core lanes).scripts/agent-batch-comments.mjs (1)
36-43: ⚡ Quick winConsider handling empty title after sanitization.
The
slug()function has a fallback whenbaseis empty after sanitization, but the logicbase || ...may not trigger ifbaseis a non-empty string of only hyphens (which.slice(0, 50)could produce before the final.replace(/^-+|-+$/g, "")is evaluated).♻️ Slightly more robust slug generation
function slug(title, number) { const base = (title || `issue-${number}`) .toLowerCase() .replace(/[^a-z0-9]+/g, "-") - .replace(/^-+|-+$/g, "") - .slice(0, 50); - return base || `issue-${number}`; + .replace(/^-+|-+$/g, ""); + const trimmed = base.slice(0, 50).replace(/^-+|-+$/g, ""); + return trimmed || `issue-${number}`; }This ensures the final trim happens after slicing, preventing edge cases where slicing cuts mid-cleanup.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@scripts/agent-batch-comments.mjs` around lines 36 - 43, The slug() function can produce an all-hyphen or empty string if slicing happens before the final trim; update the sanitization order in slug(title, number) to: lower-case, replace non-alphanumerics with "-", then slice to 50 chars, then trim leading/trailing hyphens, and finally check if the resulting base is empty and return `issue-${number}` as fallback; locate the slug function and apply these changes so the final replace(/^-+|-+$/g, "") runs after .slice(...) and the empty-string fallback is applied to the trimmed result.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/agent-workflows/cursor-cloud-agents.md`:
- Line 102: Update the choke-point files list in the docs to match the
CHOKE_POINTS constant in scripts/agent-batch-overlap.mjs: add Cargo.toml and
pnpm-lock.yaml and replace ambiguous names with the full paths used in the
script (e.g., app/package.json and app/src-tauri/tauri.conf.json), ensuring the
doc line that currently mentions `src/core/all.rs`, controller registries,
JSON-RPC dispatch, `tauri.conf.json`, `package.json`, `Cargo.lock` mirrors the
exact set and path formatting from CHOKE_POINTS in agent-batch-overlap.mjs.
In `@scripts/agent-batch-comments.mjs`:
- Around line 52-53: The returned markdown link in
scripts/agent-batch-comments.mjs uses a "../blob/main/docs/..." path which won't
resolve in GitHub issue bodies; update the link to a repo-root–relative path by
removing the "../" (e.g.,
"/blob/main/docs/agent-workflows/cursor-cloud-agents.md" or the correct
repo-root absolute path) and make the same change for the other doc link
referenced at the later template (the second occurrence around line 67) so both
issue-body links are repo-relative.
---
Nitpick comments:
In `@docs/agent-workflows/cursor-cloud-agents.md`:
- Around line 109-112: Update the description of the batch-check script
invocation to remove the vague "etc." and make the output categories explicit:
state that node scripts/agent-batch-overlap.mjs
docs/agent-workflows/<your-batch>.json reports lane assignments, pairwise path
overlap, and choke-point conflicts (and that it exits non-zero on any
collision). Replace the trailing "etc." with that explicit, finite list (or
simply end the sentence after "choke-point conflicts") so readers know the
script's reports are exhaustive; reference the collision detection
implementation files (src/core/all.rs) and related config registries only if you
want to point to where each category originates.
In `@scripts/agent-batch-comments.mjs`:
- Around line 36-43: The slug() function can produce an all-hyphen or empty
string if slicing happens before the final trim; update the sanitization order
in slug(title, number) to: lower-case, replace non-alphanumerics with "-", then
slice to 50 chars, then trim leading/trailing hyphens, and finally check if the
resulting base is empty and return `issue-${number}` as fallback; locate the
slug function and apply these changes so the final replace(/^-+|-+$/g, "") runs
after .slice(...) and the empty-string fallback is applied to the trimmed
result.
In `@scripts/agent-batch-overlap.mjs`:
- Around line 213-222: The collision filter is confusing because PARALLEL_OK
contains the template "rust-core/<domain>" which never matches real lanes like
"rust-core/agent", making the includes check unreachable for rust-core lanes;
remove the PARALLEL_OK array and simplify the fatalSameLane filter in the
sameLaneCollisions logic (referencing fatalSameLane, sameLaneCollisions, and
issues) so it explicitly returns false for lanes that start with "rust-core/"
and otherwise treats the collision as fatal (i.e., return true for non-rust-core
lanes).
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 8749c421-1343-42bd-970b-c7f76d7f7a33
📒 Files selected for processing (5)
AGENTS.mddocs/agent-workflows/cursor-cloud-agents.mddocs/agent-workflows/pilot-batch-1480.jsonscripts/agent-batch-comments.mjsscripts/agent-batch-overlap.mjs
|
|
||
| - **One agent per lane per batch.** A 15-20 agent batch must use at least 9 lanes (one of each above) or split a lane along path-disjoint sub-trees. `rust-core/<domain>` is naturally parallel because each domain lives in its own subdirectory; treat `rust-core/memory` and `rust-core/cron` as two distinct lanes. | ||
| - **No cross-lane edits.** If an issue actually needs changes in two lanes (e.g. a Rust core change plus a frontend rendering tweak), split it into two issues with explicit dependency order. The dependent issue is launched only after the upstream PR merges. | ||
| - **Schema and contract files (`src/core/all.rs`, controller registries, JSON-RPC dispatch, `tauri.conf.json`, `package.json`, `Cargo.lock`):** these are choke points. Only one agent per batch may modify any of these. The operator marks the chosen agent as the **schema owner** for the batch; other agents must request the schema owner to land their entry first or defer to the next batch. |
Contributor
There was a problem hiding this comment.
Synchronize choke-point files list with script.
The choke-point files listed here don't exactly match CHOKE_POINTS in scripts/agent-batch-overlap.mjs. The script includes Cargo.toml and pnpm-lock.yaml which aren't mentioned in the documentation, and uses full paths (app/package.json, app/src-tauri/tauri.conf.json) for clarity.
📋 Align documentation with script implementation
-**Schema and contract files (`src/core/all.rs`, controller registries, JSON-RPC dispatch, `tauri.conf.json`, `package.json`, `Cargo.lock`):** these are choke points.
+**Schema and contract files** (`src/core/all.rs`, `src/rpc/dispatch.rs`, `app/src-tauri/tauri.conf.json`, `app/package.json`, `Cargo.lock`, `Cargo.toml`, `pnpm-lock.yaml`): these are choke points.This matches the complete list at lines 44-52 in agent-batch-overlap.mjs.
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| - **Schema and contract files (`src/core/all.rs`, controller registries, JSON-RPC dispatch, `tauri.conf.json`, `package.json`, `Cargo.lock`):** these are choke points. Only one agent per batch may modify any of these. The operator marks the chosen agent as the **schema owner** for the batch; other agents must request the schema owner to land their entry first or defer to the next batch. | |
| - **Schema and contract files** (`src/core/all.rs`, `src/rpc/dispatch.rs`, `app/src-tauri/tauri.conf.json`, `app/package.json`, `Cargo.lock`, `Cargo.toml`, `pnpm-lock.yaml`): these are choke points. Only one agent per batch may modify any of these. The operator marks the chosen agent as the **schema owner** for the batch; other agents must request the schema owner to land their entry first or defer to the next batch. |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/agent-workflows/cursor-cloud-agents.md` at line 102, Update the
choke-point files list in the docs to match the CHOKE_POINTS constant in
scripts/agent-batch-overlap.mjs: add Cargo.toml and pnpm-lock.yaml and replace
ambiguous names with the full paths used in the script (e.g., app/package.json
and app/src-tauri/tauri.conf.json), ensuring the doc line that currently
mentions `src/core/all.rs`, controller registries, JSON-RPC dispatch,
`tauri.conf.json`, `package.json`, `Cargo.lock` mirrors the exact set and path
formatting from CHOKE_POINTS in agent-batch-overlap.mjs.
Comment on lines
+52
to
+53
| return `Pilot batch for the Cursor Cloud Agents workflow defined in | ||
| [\`docs/agent-workflows/cursor-cloud-agents.md\`](../blob/main/docs/agent-workflows/cursor-cloud-agents.md). |
Contributor
There was a problem hiding this comment.
Fix relative documentation links in parent issue body.
The relative path ../blob/main/docs/... won't resolve correctly in GitHub issue bodies. Issue markdown doesn't support directory traversal; it needs repo-relative paths without ../.
🔗 Proposed fix for documentation links
-[\`docs/agent-workflows/cursor-cloud-agents.md\`](../blob/main/docs/agent-workflows/cursor-cloud-agents.md).
+[\`docs/agent-workflows/cursor-cloud-agents.md\`](/tinyhumansai/openhuman/blob/main/docs/agent-workflows/cursor-cloud-agents.md).Apply the same pattern at line 67:
-Pilot acceptance check (see [\`cursor-cloud-agents.md\`](../blob/main/docs/agent-workflows/cursor-cloud-agents.md#pilot-acceptance-check)):
+Pilot acceptance check (see [\`cursor-cloud-agents.md\`](/tinyhumansai/openhuman/blob/main/docs/agent-workflows/cursor-cloud-agents.md#pilot-acceptance-check)):🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@scripts/agent-batch-comments.mjs` around lines 52 - 53, The returned markdown
link in scripts/agent-batch-comments.mjs uses a "../blob/main/docs/..." path
which won't resolve in GitHub issue bodies; update the link to a
repo-root–relative path by removing the "../" (e.g.,
"/blob/main/docs/agent-workflows/cursor-cloud-agents.md" or the correct
repo-root absolute path) and make the same change for the other doc link
referenced at the later template (the second occurrence around line 67) so both
issue-body links are repo-relative.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
docs/agent-workflows/cursor-cloud-agents.mddocumenting the pilot-then-scale workflow for running 15-20 Cursor Cloud Agents in parallel against this repo without file collisions or duplicated work.src/core/all.rs,package.json,Cargo.lock,tauri.conf.json, ...).scripts/agent-batch-overlap.mjs— the pre-launch collision check. Reads a JSON batch file, reports lane / path / choke-point conflicts, exits non-zero on collision.scripts/agent-batch-comments.mjs— generates the parent-issue body and per-issue launch comments from the same batch JSON, so the launch step is reproducible (no hand-edited prompts).docs/agent-workflows/pilot-batch-1480.json— a validated 3-issue pilot batch (Reduce bottom tabs to make the app feel cleaner #1502 frontend-ui, AI repeats every Chinese response twice when asked to answer in Chinese #1675 rust-core/agent, feat(release): add official Linux aarch64 (ARM64) release binaries #1599 ci-config). Overlap script reports PASS.AGENTS.mdalongside the existing Codex web checklist.Problem
Issue #1480 asks for a documented, automated workflow that can run ~15-20 Cursor Cloud Agents in parallel against OpenHuman without branch collisions, duplicated work, lost context, secrets leakage, or low-quality PRs. Today there is no documented workflow for this; agents have no shared lane definition, no shared launch trigger format, no shared dashboard, and no shared secrets posture. The result is unsafe to scale.
Solution
A single runbook plus two small scripts:
scripts/codex-pr-preflight.mjsso the Cursor channel and the Codex channel share one env check.cursor/<ISSUE-NUMBER>-<short-slug>, push to the agent's fork, PR againsttinyhumansai/openhuman:main, labelcursor-cloud-agent.src/core/all.rs,package.json,Cargo.lock, etc.) get one schema owner per batch..env.exampleonly; no production OAuth, signing, updater, or external-integration credentials.cursor-cloud-agentlabel, plus agh pr listsnapshot. Two consecutive CI failures route to a human.agent-batch-overlap.mjsvalidates a batch JSON, thenagent-batch-comments.mjsprints the parent-issue body + per-issue launch comments derived from that same JSON. Negative-tested both: overlap script catches out-of-lane paths, same-lane collisions, and parent/child path overlap.The runbook deliberately reuses the Codex checklist for the parts that are channel-agnostic (preflight, validation, PR template, duplicate PR cleanup) rather than forking a parallel copy that will drift.
Submission Checklist
N/A: docs + repo-operator scripts; the scripts were manually negative-tested (out-of-lane path, same-lane duplicate, choke-point conflict — all caught with exit code 1).N/A: docs + operator scripts not executed in the product runtime; not covered by Vitest or cargo-llvm-cov.N/A: workflow doc, no product feature row.## Related—N/A: no feature IDs touched.docs/RELEASE-MANUAL-SMOKE.md) —N/A: does not touch release-cut surfaces.Closes #NNNin the## Relatedsection.Impact
Related
node scripts/agent-batch-comments.mjs docs/agent-workflows/pilot-batch-1480.json.AI Authored PR Metadata
Linear Issue
Commit & Branch
Validation Run
pnpm --filter openhuman-app format:check— passes on the four touched files (cursor-cloud-agents.md, AGENTS.md, agent-batch-overlap.mjs, agent-batch-comments.mjs)pnpm typecheck— N/A: no TS changesValidation Blocked
command:N/Aerror:N/Aimpact:N/ABehavior Changes
docs/agent-workflows/cursor-cloud-agents.md; new section inAGENTS.mdlinking to it; two new scripts underscripts/for operators preparing a batch.Parity Contract
Duplicate / Superseded PR Handling
Summary by CodeRabbit
Documentation
Chores