docs: add AGENTS.md with Cursor Cloud dev environment notes

[ethanolivertroy]

Summary

Sets up and verifies the development environment for this repo (Claude Code GRC plugin marketplace) and documents durable, non-obvious startup/run notes for future cloud agents.

This repo is mostly Markdown/YAML/JSON plugin content plus a root Node.js (ESM) toolkit of CLI scripts, a schema/contract test suite, and a few independent React/Vite apps. There is no backend service or database.

Changes

• Add AGENTS.md with a ## Cursor Cloud specific instructions section covering: runtime (Node 20 in CI / 22 verified), npm install at root, where test/lint/build commands live, network-dependent SCF scripts (frameworks.js) that fail under restricted egress, a pre-existing CommonJS-under-ESM breakage in scan-iac.js/test-control.js, correct --key=value args for the dashboard server, and the independent Vite apps.

Verification

• npm install (root)
• npm run test:contract, npm run test:plugin-manifests, npm run test:grc-diagrams, npm run test:contract:findings, npm run test:wiz-inspector — all pass
• node plugins/grc-engineer/scripts/map-control.js <tf> soc2 — offline core CLI maps 8 controls
• demo/claude-grc-portfolio: npm install + npm run build + npm run dev (port 5173)
• compliance-posture dashboard server (--demo, port 8787)

No application code changed.

  

Summary by CodeRabbit

• Documentation
  • Updated repository guidance with clearer setup, testing, and local development instructions, including notes for offline smoke testing and common script execution caveats.
  • Refreshed README and related docs links for Claude Cowork third-party platform resources to point to the official documentation page.

[coderabbitai]

Warning

Review limit reached

@cursor[bot], you've reached your PR review limit, so we couldn't start this review.

Next review available in: 27 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 9750a5f9-b355-4136-97e4-d230cdec70c3

📥 Commits

Reviewing files that changed from the base of the PR and between 5ba3154 and e52c48e.

📒 Files selected for processing (1)

• AGENTS.md

📝 Walkthrough

Walkthrough

AGENTS.md adds repository operating instructions, and the README and Claude Cowork docs update their Cowork guidance links to the official claude.com documentation page.

Changes

Repository guidance

Layer / File(s)	Summary
Repo instructions AGENTS.md	Adds repo operating guidance for architecture references, runtime and install assumptions, canonical test/lint/build commands, offline smoke testing, an ESM/CommonJS execution caveat, and optional dashboard/frontend commands.
Official Cowork links README.md, docs/CLAUDE-COWORK.md	Updates the Cowork third-party platform guidance links and text to point to the official claude.com documentation page.

Estimated code review effort: 1 (Trivial) | ~2 minutes

Possibly related issues

• Create AGENTS.md for Codex repo instructions codex-grc-engineering#3 — Adds durable AGENTS.md repo instructions, matching the issue’s request for repository guidance.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: adding AGENTS.md with Cursor Cloud development environment notes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch cursor/setup-dev-environment-becc

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[greptile-apps]

Greptile Summary

This PR adds AGENTS.md to document durable, non-obvious setup and run notes for cloud coding agents (Node version, test commands, network limitations, the CommonJS-under-ESM breakage in two scripts, dashboard arg syntax, and independent Vite app setup), and updates two instances of the Claude Cowork third-party platform guide link to the new claude.com/docs URL.

• AGENTS.md is a new file consolidating gotchas and startup guidance that would otherwise require trial-and-error; no application code is touched.
• README.md and docs/CLAUDE-COWORK.md replace the old support.claude.com Intercom article URL with the canonical claude.com/docs/cowork/3p/overview docs page.

Confidence Score: 5/5

Documentation-only change with no application code modified; safe to merge.

All three changed files are pure documentation. AGENTS.md accurately reflects the repo's structure and known quirks. The two URL updates replace a deprecated Intercom support article with the canonical docs page. No logic, schema, or configuration is affected.

No files require special attention.

Important Files Changed

Filename	Overview
AGENTS.md	New file documenting cloud agent setup, test commands, known gotchas, and dashboard arg syntax for this repo; content is accurate and well-structured with no code changes.
README.md	Two link updates: text and URL for the Claude Cowork third-party platform guide updated to point at the new claude.com/docs path; no logic changes.
docs/CLAUDE-COWORK.md	URL-only update for the Cowork third-party platform guide link; link text unchanged, consistent with its surrounding context.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Cloud Agent enters repo] --> B[Read AGENTS.md]
    B --> C[npm install at repo root]
    C --> D{Network available?}
    D -- Yes --> E[Run full test suite\nnpm run test:contract etc.]
    D -- No / Restricted egress --> F[Offline smoke test\nnode map-control.js tf soc2]
    E --> G{Need dashboard?}
    F --> G
    G -- Yes --> H[node serve.js --demo\n--host=127.0.0.1 --port=8787]
    G -- No --> I[Done]
    H --> I
    B --> J{Vite app needed?}
    J -- Yes --> K[cd demo/claude-grc-portfolio\nnpm install && npm run dev]
    J -- No --> C

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
    A[Cloud Agent enters repo] --> B[Read AGENTS.md]
    B --> C[npm install at repo root]
    C --> D{Network available?}
    D -- Yes --> E[Run full test suite\nnpm run test:contract etc.]
    D -- No / Restricted egress --> F[Offline smoke test\nnode map-control.js tf soc2]
    E --> G{Need dashboard?}
    F --> G
    G -- Yes --> H[node serve.js --demo\n--host=127.0.0.1 --port=8787]
    G -- No --> I[Done]
    H --> I
    B --> J{Vite app needed?}
    J -- Yes --> K[cd demo/claude-grc-portfolio\nnpm install && npm run dev]
    J -- No --> C

Loading

_{Reviews (3): Last reviewed commit: "docs(AGENTS.md): restructure so general ..." | Re-trigger Greptile}

[qodo-code-review]

PR Summary by Qodo

Docs: add AGENTS.md with Cursor Cloud dev environment notes
📝 Documentation 🕐 Less than 5 minutes

Description

• Add AGENTS.md with durable repo startup/run notes for Cursor Cloud agents.
• Document root Node runtime, install flow, and canonical test/lint/build entrypoints.
• Call out network-dependent scripts and known ESM/CommonJS pitfalls to avoid false regressions.

Diagram

graph TD
AGENT["Cloud agent"] --> DOC["AGENTS.md"] --> INSTALL["Root npm install"] --> SCRIPTS["Root scripts"]
SCRIPTS --> CLI["Offline CLI"]
SCRIPTS --> DASH["Dashboard server"]
SCRIPTS --> VITE["Vite apps"]
CLI --> SCF{{"SCF API"}}

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Fold notes into CLAUDE.md

• ➕ Single canonical agent doc to maintain
• ➕ Keeps architecture + operational notes together
• ➖ CLAUDE.md is already long and architecture-focused
• ➖ Operational Cursor Cloud caveats may get lost/noisier for non-cloud contributors

2. Create CONTRIBUTING.md / DEVELOPMENT.md

• ➕ Matches common OSS conventions for dev setup docs
• ➕ Clear entrypoint for humans, not just agents
• ➖ Adds another doc to keep in sync
• ➖ Doesn’t specifically target cloud-agent caveats unless duplicated

3. Move key run commands to README and keep AGENTS.md minimal

• ➕ Improves discoverability for all users
• ➕ Reduces “where do I start” friction
• ➖ README can become cluttered with operational edge cases
• ➖ Still needs a place for detailed Cursor Cloud constraints

Recommendation: Keeping these notes in a dedicated AGENTS.md is a good fit because they’re operational, non-obvious, and cloud-agent specific. Consider copying only the 2–3 most universal commands (install + core tests) into README or a CONTRIBUTING/DEVELOPMENT doc for broader discoverability, while leaving Cursor Cloud quirks (restricted egress, ESM/CommonJS pitfalls, dashboard arg parsing) in AGENTS.md.

Files changed (1) +14 / -0

Documentation (1) +14 / -0

AGENTS.mdAdd Cursor Cloud dev-environment runbook for repo tooling +14/-0

Add Cursor Cloud dev-environment runbook for repo tooling

• Introduces AGENTS.md to capture durable setup and execution notes for cloud agents. Documents Node runtime expectations, root install and script entrypoints, known network-dependent scripts and pre-existing ESM/CommonJS breakage, and how to run the optional dashboard and independent Vite apps.

AGENTS.md

ⓘ You are approaching your monthly quota for Qodo. Upgrade your plan

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0)

Great, no issues found!

Qodo reviewed your code and found no material issues that require review

ⓘ You are approaching your monthly quota for Qodo. Upgrade your plan

[ajy0127]

Verified every factual claim against main: root package.json is ESM ("type": "module"), all five test scripts exist, scan-iac.js/test-control.js CommonJS breakage is real and pre-existing, no lockfiles, CI pins Node 20. Useful durable notes. Contains the same link-fix hunks as #200, which merges first; identical hunks so no conflict risk.