feat(agent-workflows): Cursor Cloud Agents parallel workflow (#1480)#1759
Merged
senamakel merged 3 commits intoMay 15, 2026
Merged
Conversation
…ansai#1480) Adds a documented multi-agent workflow plus zero-dep operator tooling for running up to 25 Cursor Cloud Agents in parallel against OpenHuman: - docs/agent-workflows/cursor-cloud-agents.md — workflow doc covering batch spec, branch/PR conventions, ownership boundaries, quality gates, secrets posture, progress visibility, and pilot-then-scale. - scripts/agent-batch/ — Node 20+ stdlib only: validate.mjs schema + naming + prefix-only ownership rules overlap.mjs mechanical disjointness proof across owned_paths launch.mjs per-agent launch comment with required reading and validation commands status.mjs one gh-pr-list call + single tracking comment updated in place via <!-- batch:<id> --> marker - docs/agent-workflows/pilot-batch-example.json — canonical 3-agent spec used by the doc walkthrough and the test fixtures. - node:test suite (25 cases) covering schema, overlap, branch regex, argv parsing, and end-to-end CLI behaviour from a fixture. - package.json — pnpm agent-batch / agent-batch:test entrypoints. Quality gates are reused, not re-implemented: agents run the same format:check / typecheck / lint / focused tests / >=80% diff coverage as any other PR per .github/workflows/{coverage,pr-quality}.yml.
Contributor
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (1)
🚧 Files skipped from review as they are similar to previous changes (1)
📝 WalkthroughWalkthroughAdds a batch-spec-driven Cursor Cloud Agents workflow: a JSON batch contract and operator playbook, a validation/overlap library, CLI verbs (validate/overlap/launch/status) with tests, package scripts, a 3-agent pilot example, and status posting via the ChangesCursor Cloud Agents Parallel Workflow
sequenceDiagram
participant Operator as Operator
participant StatusCLI as StatusCLI
participant GitHubCLI as GitHubCLI
participant TrackingIssue as TrackingIssue
Operator->>StatusCLI: pnpm agent-batch status spec.json --post
Note right of StatusCLI: loadSpec + validateSpec
alt fixture provided
StatusCLI->>StatusCLI: use fixture PR data
else no fixture
StatusCLI->>GitHubCLI: gh pr list --label batch:<batch_id>
GitHubCLI-->>StatusCLI: PR list JSON
end
StatusCLI->>StatusCLI: render markdown table
StatusCLI->>GitHubCLI: gh api list comments on tracking issue (marker)
GitHubCLI-->>StatusCLI: existing comment id? / none
alt existing comment
StatusCLI->>GitHubCLI: gh api PATCH /comments/:id (updated table)
else
StatusCLI->>GitHubCLI: gh api POST /issues/:issue_number/comments (new comment)
end
GitHubCLI-->>TrackingIssue: comment posted or updated
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related issues
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 Comment |
- Drop "(AC #N)" suffixes from section headings so anchors stay simple kebab-case (the body still names the AC for each section). Restores the #secrets-posture cross-link. - Replace placeholder "[#1234](…)" link syntax in the progress-table example with code spans — lychee was resolving "…" as a relative file path and erroring.
![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: 4
🧹 Nitpick comments (1)
scripts/agent-batch/launch.mjs (1)
1-108: ⚡ Quick winAdd integration tests for launch.mjs.
While
validate.mjs,overlap.mjs, andstatus.mjshave integration test coverage incli.test.mjs,launch.mjsis untested. Adding tests that verify the rendered output format,--agentfiltering, and overlap-blocking behavior would improve confidence in this CLI's correctness.🤖 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/launch.mjs` around lines 1 - 108, Add integration tests for scripts/agent-batch/launch.mjs: write tests in the existing cli.test.mjs that invoke the CLI entrypoint (main via running node launch.mjs or importing and calling main with mocked process.argv) to assert (1) the rendered output from renderComment contains the expected sections and values for a sample spec, (2) the --agent flag filters to a single agent (use parseArgs/flags simulation or pass args) and prints only that agent, and (3) findOverlaps blocking behavior returns a non-zero exit and error message when overlaps exist (mock loadSpec/validateSpec/findOverlaps to supply a colliding spec). Use the same test harness style as validate.mjs/overlap.mjs/status.mjs tests in cli.test.mjs so the new tests integrate with existing fixtures and assertions.
🤖 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 29: Update the broken fragment link in cursor-cloud-agents.md: replace
the link target `#secrets-posture` used in the batch description with the
correct GitHub anchor `#secrets-posture-ac-5` (or alternatively rename the
heading "## Secrets posture (AC `#5`)" to "## Secrets posture" so the existing
anchor works); locate the reference to `#secrets-posture` in the batch example
and change it to `#secrets-posture-ac-5` to match the generated anchor for the
heading.
- Around line 117-118: Replace the placeholder markdown links using the ellipsis
link text (e.g., `[`#1234`](…)` and `[`#1235`](…)`) which the link-checker attempts
to validate; instead, change those to non-clickable code-formatted text (e.g.,
``[`#1234`]``) or real example URLs (e.g., `https://example.com/...`) so the table
rows like `a01 | `#1234` | cursor/a01-1234-… | [`#1234`](…) | ✓ green` no longer
contain `(...)` link targets that break the link-checker; update both
occurrences (`[`#1234`](…)`, `[`#1235`](…)`) consistently in the table.
In `@scripts/agent-batch/status.mjs`:
- Around line 156-169: The PATCH call is passing the whole comment via a
command-line arg which can hit OS arg-length limits; modify the spawnSync
invocation that builds the gh api PATCH for
repos/${spec.base_repo}/issues/comments/${id} (the spawnSync call using "PATCH"
and `body=${body}`) to mirror the POST pattern: replace `-f body=${body}` with
`--body-file -` in the args and provide the comment text via spawnSync's input
(stdin) option (keeping encoding:"utf8"); keep the same error check on r.status
and include stderr in the thrown Error as before.
- Around line 117-133: The jq filter currently emits wrapped arrays per page
causing concatenated array fragments that break JSON.parse; update the gh
spawnSync call to emit newline-separated objects by changing the jq expression
to output objects (e.g., remove the outer [...] so it uses '.[] | select(...) |
{id, html_url}'), then replace the single JSON.parse(list.stdout || "[]") logic
with parsing newline-delimited JSON from list.stdout (split on newlines, filter
out empty lines, and JSON.parse each line) to produce the existing array; refer
to the spawnSync invocation, the list variable, COMMENT_MARKER(spec.batch_id),
and the existing constant to locate where to change the jq filter and parsing.
---
Nitpick comments:
In `@scripts/agent-batch/launch.mjs`:
- Around line 1-108: Add integration tests for scripts/agent-batch/launch.mjs:
write tests in the existing cli.test.mjs that invoke the CLI entrypoint (main
via running node launch.mjs or importing and calling main with mocked
process.argv) to assert (1) the rendered output from renderComment contains the
expected sections and values for a sample spec, (2) the --agent flag filters to
a single agent (use parseArgs/flags simulation or pass args) and prints only
that agent, and (3) findOverlaps blocking behavior returns a non-zero exit and
error message when overlaps exist (mock loadSpec/validateSpec/findOverlaps to
supply a colliding spec). Use the same test harness style as
validate.mjs/overlap.mjs/status.mjs tests in cli.test.mjs so the new tests
integrate with existing fixtures and assertions.
🪄 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: c9d91abb-168c-46a3-b5c0-74db7f126a49
📒 Files selected for processing (11)
docs/agent-workflows/cursor-cloud-agents.mddocs/agent-workflows/pilot-batch-example.jsonpackage.jsonscripts/agent-batch/__tests__/cli.test.mjsscripts/agent-batch/__tests__/lib.test.mjsscripts/agent-batch/cli.mjsscripts/agent-batch/launch.mjsscripts/agent-batch/lib.mjsscripts/agent-batch/overlap.mjsscripts/agent-batch/status.mjsscripts/agent-batch/validate.mjs
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 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 58: The table row for `tracking_issue` includes an unclear "AC `#6`"
reference; update that row (the `tracking_issue` entry) to either remove "AC `#6`"
or replace it with a short inline explanation such as "Acceptance Criteria 6
(see issue `#1480` for details)" so readers without issue context understand the
meaning; ensure the change preserves the existing description "One upstream
issue per batch; that issue's comment thread is the dashboard" while making the
AC reference explicit or omitted.
🪄 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: c613661b-fdfd-4541-8da9-44a1cfb22e31
📒 Files selected for processing (1)
docs/agent-workflows/cursor-cloud-agents.md
| | `batch_id` | yes | Stable identifier — appears in PR bodies and the tracking comment. | | ||
| | `base_repo` | yes | Always `tinyhumansai/openhuman` unless explicitly delegated. | | ||
| | `base_branch` | yes | `main`. | | ||
| | `tracking_issue` | yes | One upstream issue per batch; that issue's comment thread is the dashboard (AC #6). | |
Contributor
There was a problem hiding this comment.
Clarify the "AC #6" reference.
The reference to "AC #6" assumes readers have context from issue #1480. Consider either removing the AC reference or briefly explaining it inline.
📝 Suggested fix
-| `tracking_issue` | yes | One upstream issue per batch; that issue's comment thread is the dashboard (AC `#6`). |
+| `tracking_issue` | yes | One upstream issue per batch; that issue's comment thread is the dashboard. |📝 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
| | `tracking_issue` | yes | One upstream issue per batch; that issue's comment thread is the dashboard (AC #6). | | |
| | `tracking_issue` | yes | One upstream issue per batch; that issue's comment thread is the dashboard. | |
🤖 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 58, The table row for
`tracking_issue` includes an unclear "AC `#6`" reference; update that row (the
`tracking_issue` entry) to either remove "AC `#6`" or replace it with a short
inline explanation such as "Acceptance Criteria 6 (see issue `#1480` for details)"
so readers without issue context understand the meaning; ensure the change
preserves the existing description "One upstream issue per batch; that issue's
comment thread is the dashboard" while making the AC reference explicit or
omitted.
- Parse `gh api --paginate` output as NDJSON: the jq filter ran per page,
so wrapping in `[...]` produced concatenated array fragments that broke
JSON.parse. Drop the outer array and split/parse line-by-line.
- Send the PATCH comment body via stdin (`-F body=@-`) instead of
`-f body=${body}`, so long markdown tables don't risk ARG_MAX.
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
2 participants
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
pnpm agent-batch <validate|overlap|launch|status>enforces schema, proves ownership disjointness, generates per-agent launch comments, and rewrites a single tracking comment with a PR/CI status table.format:check,typecheck,lint, focused tests, ≥80% diff coverage) — does not re-implement them.Problem
OpenHuman has no documented or automated workflow for running ~15–20 Cursor Cloud Agents in parallel. Without one, batches collide on branches/files, drop quality gates, or run with overscoped credentials. Issue #1480 asks for a documented, observable, secret-safe pilot that can scale to 15–20 concurrent agents.
Solution
A JSON batch spec is the single source of truth:
scripts/agent-batch/validate.mjs— schema, kebab-case ids,cursor/<id>-<issue>-<slug>branches, prefix-only ownership (no globs), 25-agent hard cap.scripts/agent-batch/overlap.mjs— mechanical pairwise prefix-containment check acrossowned_paths, with an explicitallowed_shared_pathsescape hatch for unavoidably-shared files (e.g. the coverage matrix).scripts/agent-batch/launch.mjs— emits a per-agent comment that names owned paths, required reading, validation commands, and PR rules so every agent inherits the same constraints.scripts/agent-batch/status.mjs— onegh pr list --label batch:<id>call per batch; rewrites a single tracking comment via a<!-- batch:<id> -->marker so the issue thread does not fill with stale tables.The workflow doc (
docs/agent-workflows/cursor-cloud-agents.md) covers setup, batch input format, branch/PR conventions, ownership boundaries, quality gates (linking to the existingcoverage.ymlandpr-quality.yml), secrets posture, progress visibility, and pilot-then-scale (N=3 → N=5 → N=15–20).Submission Checklist
node:testcases underscripts/agent-batch/__tests__/covering schema, overlap (disjoint + collision), branch regex (positive + negative), argv parsing, and end-to-end CLI behaviour via a fixture.docs/agent-workflows/andscripts/agent-batch/, both outside the Vitest (app/coverage/lcov.info) andcargo-llvm-covroots;diff-coverexcludes unmeasured files automatically per.github/workflows/coverage.yml. The new scripts are themselves covered by the includednode:testsuite (pnpm agent-batch:test).## Related— N/A: no matrix rows touched.status.mjsshells togh(already a dev prereq).docs/RELEASE-MANUAL-SMOKE.md) — N/A: no release-cut surface touched.Closes #NNNin the## Relatedsection.Impact
node --test+node:child_processonly.package.jsonaddsagent-batchandagent-batch:testnpm scripts.scripts/agent-batch/(chmod +x on the CLI entrypoints).Related
AI Authored PR Metadata (required for Codex/Linear PRs)
Linear Issue
Commit & Branch
agent-workflows-cursor-cloud-14809d403ff3e4a3673ea3752401ee059ad0d1f4fba5Validation Run
pnpm --filter openhuman-app format:check— clean (Prettier --write applied during authoring, re-checked clean).pnpm typecheck— clean (no.tsfiles touched).pnpm agent-batch:test— 25/25 pass, ~271 ms.pnpm rust:checksuccessfully on this branch.)Validation Blocked
command:N/Aerror:N/Aimpact:N/ABehavior Changes
pnpm agent-batch …) and a documented multi-agent workflow. No runtime behavior changes.pnpm agent-batchverbs anddocs/agent-workflows/cursor-cloud-agents.md.Parity Contract
Duplicate / Superseded PR Handling
Summary by CodeRabbit
New Features
Documentation
Tests
Chores