Skip to content

AGENTS.md

Latest commit

 

History

History
89 lines (63 loc) · 5.87 KB

AGENTS.md

File metadata and controls

89 lines (63 loc) · 5.87 KB
Raw

AGENTS.md

Context for AI coding assistants (Cursor, Claude Code, GitHub Copilot, etc.) working in this repository.

Progressive disclosure: Read this file first, then the package guide for the tree you are editing — cdk/AGENTS.md, cli/AGENTS.md, agent/AGENTS.md, or docs/AGENTS.md.

Your role

You are an ABCA (Autonomous Background Coding Agents on AWS) contributor: AWS CDK (TypeScript), Python agent runtime, CLI, and docs. Users submit coding tasks; agents work autonomously in isolated cloud environments and open pull requests for review.

Deeper design: Developer guide, Architecture, Orchestrator.

Commands (run these)

mise run install          # yarn workspaces + agent Python (uv)
mise run build            # agent quality + cdk + cli + docs (parallel)
mise run security         # secrets, deps, sast, grype, retire, gh-actions, agent
mise run hooks:install    # prek git hooks (also runs at end of install)
mise run hooks:run        # pre-commit + pre-push locally

Security subtasks: mise run security:secrets, security:sast, security:sast:masking, security:deps, security:retire, security:gh-actions. For security:sast:masking allowlist intentional fallbacks with an inline nosemgrep: <rule-id> -- <reason> comment.

Package commands: cdk/AGENTS.md, cli/AGENTS.md, agent/AGENTS.md, docs/AGENTS.md.

Run mise tasks --all with MISE_EXPERIMENTAL=1 for the full list. Prefer mise tasks over raw jest, tsc, or cdk for full suites; package guides show targeted npx jest / uv run pytest for single files.

Git workflow

approved issue → git fetch origin main → worktree → branch → implement → local checks → PR

Branch names: (feat|fix|chore|docs)/<issue-number>-short-description (e.g. docs/191-agents-md-split).

After merging main into your branch:

  1. mise //cdk:eslint and mise //cli:eslint (both use --fix)
  2. Commit any auto-fixes (CI "Fail build on mutation" rejects uncommitted lint output)
  3. mise run build

Worktrees: node_modules/ and agent/.venv/ are per-tree. Run mise run install in each new worktree.

Where to make changes

Change Primary location Also update Package guide
REST API, Lambdas, orchestration cdk/src/handlers/, cdk/src/stacks/, cdk/src/constructs/ cdk/test/ cdk/AGENTS.md
Shared API types cdk/src/handlers/shared/types.ts cli/src/types.ts cdk/AGENTS.md, cli/AGENTS.md
bgagent CLI cli/src/, cli/test/ cli/src/types.ts if API changes cli/AGENTS.md
Agent runtime agent/src/ agent/tests/, agent/README.md agent/AGENTS.md
Progress events agent/src/progress_writer.py, agent/src/pipeline.py, agent/src/runner.py agent/tests/test_progress_writer.py; cli/src/commands/watch.ts agent/AGENTS.md, cli/AGENTS.md
User-facing / design prose docs/guides/, docs/design/ mise //docs:sync docs/AGENTS.md
ADRs docs/decisions/ mise //docs:sync docs/AGENTS.md
Monorepo CI / tasks mise.toml, scripts/, .github/workflows/ — —

Boundaries

  • ✅ Always: Use an approved GitHub issue before implementing (ADR-003); branch from main via worktree; run mise run build before opening a PR; regenerate Starlight mirrors when editing docs/guides/, docs/design/, or CONTRIBUTING.md; add dependencies to the owning package package.json (cdk/, cli/, or docs/)
  • ⚠️ Ask first: New CDK stacks or constructs, agent contract changes, new dependencies, major refactors, CI workflow edits
  • 🚫 Never: Edit on main; edit docs/src/content/docs/ by hand; commit secrets; implement without an approved issue (conversational "go ahead" is not approval); run raw jest/tsc/cdk when a mise task exists

Common mistakes

  • No approved issue — Create issue → approved label → self-assign → comment "Starting implementation". See ADR-003.
  • Branch without issue number — Unauthorized work.
  • MISE_EXPERIMENTAL=1 — Required for mise //cdk:build and other namespaced tasks (CONTRIBUTING.md).
  • prek install fails — Another hook manager owns core.hooksPath; see CONTRIBUTING.md.
  • Package-specific pitfalls — API type drift, CDK test bundling, Cedar parity, generated docs: see package AGENTS.md files.

Tech stack

  • Node 22 (mise) · TypeScript 6.x · Python ≥3.13 (agent, uv)
  • AWS CDK aws-cdk-lib 2.x · @aws-cdk/aws-bedrock-alpha, @aws-cdk/aws-bedrock-agentcore-alpha, cdk-nag
  • Test / lint — Jest 30, ESLint flat config (cdk/eslint.config.mjs, cli/eslint.config.mjs), Ruff (agent)
  • Cedar — @cedar-policy/cedar-wasm 4.8.2 (cdk) + cedarpy==4.8.4 (agent); must bump together
  • Tooling — mise, Yarn workspaces, prek hooks, Starlight docs sync

Repository structure

Path Role
cdk/ CDK app (@abca/cdk) — cdk/AGENTS.md
cli/ bgagent CLI — cli/AGENTS.md
agent/ Python runtime (bundled into CDK image) — agent/AGENTS.md
docs/ Guides, design, Starlight site — docs/AGENTS.md
mise.toml Monorepo tasks; config_roots: cdk, agent, cli, docs
CONTRIBUTING.md Contribution guidelines