docs: add AGENTS.md for AI agent contributors

[dgandhi62]

Adds an AGENTS.md file — a contributor-focused guide optimized for AI agents working on this repository. The structure is inspired from the existing AGENTS file here - https://github.com/aws/aws-cdk/blob/main/AGENTS.md

What it covers

• Repository overview and package map
• CLI layer model (CLI → toolkit-lib → supporting libraries)
• Key design decisions (IoHost pattern, generated command definitions, bundling)
• Non-obvious file locations
• Quick reference commands (build, test, lint)
• Testing patterns (unit tests, integration tests, mocking)
• Code style rules (derived from actual eslint config)
• Error handling with ToolkitError
• PR conventions (scopes, title format, contributor statement)
• Anti-patterns to avoid
• Environment setup

Why

The main aws-cdk repo has an AGENTS.md that's been effective at guiding AI agents through contributions. This repo needs its own version since the architecture, tooling, and conventions are fundamentally different (Projen-managed monorepo, CLI/toolkit-lib layering, generated files, bundling, etc.).

Verification

All claims were fact-checked against the actual codebase:

• File paths verified to exist
• ESLint rules confirmed (no-console, no-require-imports, consistent-type-imports, no-relative-packages)
• Package dependencies and dependency flow confirmed from package.json files
• PR scopes confirmed from .github/workflows/pull-request-lint.yml
• Bundled license list confirmed from .projenrc.ts
• ToolkitError constructor signature confirmed from source

Checklist

• This change contains a major version upgrade for a dependency and I confirm all breaking changes are addressed
  • Release notes for the new version:

---

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license

[github-actions]

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Scanned Files

None