Skip to content

AGENTS.md

Latest commit

 

History

History
22 lines (13 loc) · 2.84 KB

AGENTS.md

File metadata and controls

22 lines (13 loc) · 2.84 KB
Raw

AGENTS.md

See CLAUDE.md for the full architecture overview (plugin structure, frameworks, connectors, and the Finding data contract). This file captures durable, non-obvious notes for coding agents working in this repo.

Repo shape

This repo is a Claude Code plugin marketplace: 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; "running the app" means running the Node CLI scripts, the test suite, the optional local dashboard server, and/or the Vite frontends.

Setup, tests, and checks

  • Runtime: Node.js (CI pins Node 20; Node 22 works). Single npm install at the repo root installs all toolkit + test deps. There are no committed lockfiles, so installs resolve latest within semver ranges.
  • Tests/lint/build commands are defined in the root package.json scripts and .github/workflows/; prefer those as the source of truth. Core checks: npm run test:contract, npm run test:plugin-manifests, npm run test:grc-diagrams, npm run test:contract:findings, npm run test:unit (runs every tests/*.test.{js,mjs,cjs} suite, so new test files are picked up without CI changes). Markdown lint matches the pre-commit hook: npx markdownlint-cli2@0.18.1 (config in .markdownlint-cli2.jsonc); note the repo currently has some pre-existing MD022 warnings.

Gotchas

  • Network-dependent scripts: frameworks.js (and other scripts that fetch the SCF API at grcengclub.github.io/scf-api) fail in restricted-egress environments with SCF fetch failed and no cached copy. This is an environment limitation, not a code bug. For an offline core-functionality smoke test use node plugins/grc-engineer/scripts/map-control.js <iac-file> soc2 (also supports iso27001, nist800-53) — it maps IaC patterns (e.g. aws_iam_role, aws_security_group, kms_key_id, encrypted = true) to controls with no network access.
  • Optional local dashboard: node plugins/dashboards/compliance-posture/scripts/serve.js --demo --host=127.0.0.1 --port=8787. Args MUST use --key=value syntax (space-separated like --host 127.0.0.1 is mis-parsed and the server fails to bind). --demo serves built-in sample runs so no grc-data/ is needed.
  • Optional React/Vite apps are independent npm projects (not wired into the root via workspaces); each needs its own npm install in its directory: demo/claude-grc-portfolio (Vite dev on port 5173, npm run dev/npm run build) and plugins/trust-center/frontend (its backend is AWS serverless / deploy-only, not runnable locally).

Cursor Cloud specific instructions

All of the notes above apply to Cursor Cloud agents. In particular, Cursor Cloud VMs run with restricted egress, so expect the SCF-fetching scripts to fail as described in Gotchas and use the offline smoke test instead.