{"_id":"@aws-mdaa/agent-rules","_rev":"3-7baf3441ac032f21bd5b6204adfeee39","name":"@aws-mdaa/agent-rules","dist-tags":{"latest":"1.8.1"},"versions":{"1.7.0":{"name":"@aws-mdaa/agent-rules","version":"1.7.0","author":{"url":"https://aws.amazon.com/solutions","name":"Amazon Web Services"},"license":"Apache-2.0","_id":"@aws-mdaa/agent-rules@1.7.0","maintainers":[{"name":"mdaa-dev-team","email":"mdaa-dev-team@amazon.com"}],"homepage":"https://github.com/aws/modern-data-architecture-accelerator#readme","bugs":{"url":"https://github.com/aws/modern-data-architecture-accelerator/issues"},"nx":{"targets":{"build":{"inputs":["{workspaceRoot}/agent_rules/**/*.md","{workspaceRoot}/.kiro/steering/**","{workspaceRoot}/.claude/rules/**","{workspaceRoot}/.cursor/rules/**","{workspaceRoot}/.windsurf/rules/**","{workspaceRoot}/.github/instructions/**","{workspaceRoot}/.github/copilot-instructions.md","{workspaceRoot}/CLAUDE.md"],"outputs":["{workspaceRoot}/.kiro/steering","{workspaceRoot}/.claude/rules","{workspaceRoot}/.cursor/rules","{workspaceRoot}/.windsurf/rules","{workspaceRoot}/.github/instructions","{workspaceRoot}/.github/copilot-instructions.md","{workspaceRoot}/CLAUDE.md"]}}},"dist":{"shasum":"39a27bd02f7adea88ec75c40f7955eb1c61ec7f3","tarball":"https://registry.npmjs.org/@aws-mdaa/agent-rules/-/agent-rules-1.7.0.tgz","fileCount":41,"integrity":"sha512-shauuu0cpioqeSNUPh3KDi88KVhCWFm8UFzZiOeeBvlhwSBSSw3JSxcGpCFnLMBJRugAL+Xh3QqWcZGOCtsGyw==","signatures":[{"sig":"MEQCIEBUVYDS7B9QfddCRv0tWSMu+SlyXyDtAP6t9Zf9Sh6IAiA/eW820FwnJHv31MQKadQ5IAKO3C+M1XuIOE919QciCw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":135534},"main":"lib/index.js","_from":"file:/Users/guoneng/projects/mdaa/mdaa-pipeline/npmjs-build/mdaa/target/package-build/aws-mdaa-agent-rules-1.7.0.tgz","types":"lib/index.d.ts","scripts":{"lint":"eslint --max-warnings 0 -c ../../../eslint.config.mjs","test":"jest --passWithNoTests --coverage","build":"tsc && node lib/run-projections.js","watch":"tsc -w","test:package-docs":"../../../scripts/generate_docs/test_package_docs.sh"},"_npmUser":{"name":"mdaa-dev-team","email":"mdaa-dev-team@amazon.com"},"_resolved":"/Users/guoneng/projects/mdaa/mdaa-pipeline/npmjs-build/mdaa/target/package-build/aws-mdaa-agent-rules-1.7.0.tgz","_integrity":"sha512-shauuu0cpioqeSNUPh3KDi88KVhCWFm8UFzZiOeeBvlhwSBSSw3JSxcGpCFnLMBJRugAL+Xh3QqWcZGOCtsGyw==","repository":{"url":"git+https://github.com/aws/modern-data-architecture-accelerator.git","type":"git"},"_npmVersion":"10.9.4","description":"Tool-agnostic AI agent steering rules for MDAA. Authors rules once and projects them to per-tool layouts (Kiro, Claude Code, GitHub Copilot, Cursor, Windsurf).","directories":{},"_nodeVersion":"24.12.0","dependencies":{"js-yaml":"4.2.0"},"_hasShrinkwrap":false,"devDependencies":{"jest":"29.7.0","ts-jest":"29.4.9","ts-node":"10.9.2","typescript":"5.9.3","@types/jest":"29.5.14","@types/node":"22.9.0","@types/js-yaml":"4.0.9"},"_npmOperationalInternal":{"tmp":"tmp/agent-rules_1.7.0_1784277671867_0.8155717367172235","host":"s3://npm-registry-packages-npm-production"}},"1.8.0":{"name":"@aws-mdaa/agent-rules","version":"1.8.0","author":{"url":"https://aws.amazon.com/solutions","name":"Amazon Web Services"},"license":"Apache-2.0","_id":"@aws-mdaa/agent-rules@1.8.0","maintainers":[{"name":"mdaa-dev-team","email":"mdaa-dev-team@amazon.com"}],"homepage":"https://github.com/aws/modern-data-architecture-accelerator#readme","bugs":{"url":"https://github.com/aws/modern-data-architecture-accelerator/issues"},"nx":{"targets":{"build":{"inputs":["{workspaceRoot}/agent_rules/**/*.md","{workspaceRoot}/.kiro/steering/**","{workspaceRoot}/.claude/rules/**","{workspaceRoot}/.cursor/rules/**","{workspaceRoot}/.windsurf/rules/**","{workspaceRoot}/.github/instructions/**","{workspaceRoot}/.github/copilot-instructions.md","{workspaceRoot}/CLAUDE.md"],"outputs":["{workspaceRoot}/.kiro/steering","{workspaceRoot}/.claude/rules","{workspaceRoot}/.cursor/rules","{workspaceRoot}/.windsurf/rules","{workspaceRoot}/.github/instructions","{workspaceRoot}/.github/copilot-instructions.md","{workspaceRoot}/CLAUDE.md"]}}},"dist":{"shasum":"139452518a6795b23530dd1558f5746fd0170c1a","tarball":"https://registry.npmjs.org/@aws-mdaa/agent-rules/-/agent-rules-1.8.0.tgz","fileCount":41,"integrity":"sha512-5zoEuCXjgNI+GVoy+/2CZPc0wG9izmJq7pprbtLZTp43YmXXllCKVNtgcVfXhEi8iWWLpmOae2aJcVGnTytI0Q==","signatures":[{"sig":"MEUCIQDGmLvKuuXwxuq0Mkg0Rfierge0oclwErugY+gNjaJRfAIgGNFVPvDUZIdDBUVRjTBDfOylWlPR9k+IwBnltfEOelg=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEUCIQCCoTr4kC1eVWLM5+3xA5Ezmkf1W8mV2PnjQT81h9iU6gIgLZNGOifuc1C09mqBR6x44U61C3YQNzJ5GF85UJCcCSs=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":135534},"main":"lib/index.js","_from":"file:/Users/guoneng/.cache/mdaa-publish/mdaa/target/package-build/aws-mdaa-agent-rules-1.8.0.tgz","types":"lib/index.d.ts","scripts":{"lint":"eslint --max-warnings 0 -c ../../../eslint.config.mjs","test":"jest --passWithNoTests --coverage","build":"tsc && node lib/run-projections.js","watch":"tsc -w","test:package-docs":"../../../scripts/generate_docs/test_package_docs.sh"},"_npmUser":{"name":"mdaa-dev-team","email":"mdaa-dev-team@amazon.com"},"_resolved":"/Users/guoneng/.cache/mdaa-publish/mdaa/target/package-build/aws-mdaa-agent-rules-1.8.0.tgz","_integrity":"sha512-5zoEuCXjgNI+GVoy+/2CZPc0wG9izmJq7pprbtLZTp43YmXXllCKVNtgcVfXhEi8iWWLpmOae2aJcVGnTytI0Q==","repository":{"url":"git+https://github.com/aws/modern-data-architecture-accelerator.git","type":"git"},"_npmVersion":"10.9.8","description":"Tool-agnostic AI agent steering rules for MDAA. Authors rules once and projects them to per-tool layouts (Kiro, Claude Code, GitHub Copilot, Cursor, Windsurf).","directories":{},"_nodeVersion":"22.23.1","dependencies":{"js-yaml":"4.3.1"},"_hasShrinkwrap":false,"devDependencies":{"jest":"29.7.0","ts-jest":"29.4.9","ts-node":"10.9.2","typescript":"5.9.3","@types/jest":"29.5.14","@types/node":"22.9.0","@types/js-yaml":"4.0.9"},"_npmOperationalInternal":{"tmp":"tmp/agent-rules_1.8.0_1788287947649_0.8045553327788646","host":"s3://npm-registry-packages-npm-production"}},"1.8.1":{"nx":{"targets":{"build":{"inputs":["{workspaceRoot}/agent_rules/**/*.md","{workspaceRoot}/.kiro/steering/**","{workspaceRoot}/.claude/rules/**","{workspaceRoot}/.cursor/rules/**","{workspaceRoot}/.windsurf/rules/**","{workspaceRoot}/.github/instructions/**","{workspaceRoot}/.github/copilot-instructions.md","{workspaceRoot}/CLAUDE.md"],"outputs":["{workspaceRoot}/.kiro/steering","{workspaceRoot}/.claude/rules","{workspaceRoot}/.cursor/rules","{workspaceRoot}/.windsurf/rules","{workspaceRoot}/.github/instructions","{workspaceRoot}/.github/copilot-instructions.md","{workspaceRoot}/CLAUDE.md"]}}},"_id":"@aws-mdaa/agent-rules@1.8.1","bugs":{"url":"https://github.com/aws/modern-data-architecture-accelerator/issues"},"dist":{"shasum":"f9e0cc1ef9c110d342d5824563d615c725e48c86","tarball":"https://registry.npmjs.org/@aws-mdaa/agent-rules/-/agent-rules-1.8.1.tgz","fileCount":41,"integrity":"sha512-rZr8WJDjy7lw9IV4ap14sY+O1HTabQK4gBOcfqDFvVbe0LWIbwjSb2qsn5SjcnhW4XCMsBPT+Wb8VWhqlALU1Q==","signatures":[{"sig":"MEYCIQDwYEdWM/vvFgPhlci9mbnD53D5jET4qU8i9JK0jDBXZAIhAKxcHg04ECscMpbsDSbm3sBNBavyDM4bOFMzdj63JM0B","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDcZdiInoYiXh0Tcuy69JkO033uT1nNN4TRA0YNba6rpAIgAvEpz2eMKw/iJP4iBCdu2ZWiGANiPbdNyRkvOBoXhrs="}],"unpackedSize":135534},"main":"lib/index.js","name":"@aws-mdaa/agent-rules","_from":"file:/Users/guoneng/.cache/mdaa-publish/mdaa/target/package-build/aws-mdaa-agent-rules-1.8.1.tgz","types":"lib/index.d.ts","author":{"url":"https://aws.amazon.com/solutions","name":"Amazon Web Services"},"license":"Apache-2.0","scripts":{"lint":"eslint --max-warnings 0 -c ../../../eslint.config.mjs","test":"jest --passWithNoTests --coverage","build":"tsc && node lib/run-projections.js","watch":"tsc -w","test:package-docs":"../../../scripts/generate_docs/test_package_docs.sh"},"version":"1.8.1","_npmUser":{"name":"mdaa-dev-team","email":"mdaa-dev-team@amazon.com"},"homepage":"https://github.com/aws/modern-data-architecture-accelerator#readme","_resolved":"/Users/guoneng/.cache/mdaa-publish/mdaa/target/package-build/aws-mdaa-agent-rules-1.8.1.tgz","_integrity":"sha512-rZr8WJDjy7lw9IV4ap14sY+O1HTabQK4gBOcfqDFvVbe0LWIbwjSb2qsn5SjcnhW4XCMsBPT+Wb8VWhqlALU1Q==","repository":{"url":"git+https://github.com/aws/modern-data-architecture-accelerator.git","type":"git"},"_npmVersion":"10.9.8","description":"Tool-agnostic AI agent steering rules for MDAA. Authors rules once and projects them to per-tool layouts (Kiro, Claude Code, GitHub Copilot, Cursor, Windsurf).","directories":{},"maintainers":[{"name":"mdaa-dev-team","email":"mdaa-dev-team@amazon.com"}],"_nodeVersion":"22.23.1","dependencies":{"js-yaml":"4.3.1"},"_hasShrinkwrap":false,"devDependencies":{"jest":"29.7.0","ts-jest":"29.4.9","ts-node":"10.9.2","typescript":"5.9.3","@types/jest":"29.5.14","@types/node":"22.9.0","@types/js-yaml":"4.0.9"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/agent-rules_1.8.1_1789416944432_0.982134370552542"}}},"time":{"created":"2026-07-17T08:41:11.704Z","modified":"2026-09-14T20:15:44.724Z","1.7.0":"2026-07-17T08:41:12.020Z","1.8.0":"2026-09-01T18:39:07.734Z","1.8.1":"2026-09-14T20:15:44.520Z"},"bugs":{"url":"https://github.com/aws/modern-data-architecture-accelerator/issues"},"author":{"url":"https://aws.amazon.com/solutions","name":"Amazon Web Services"},"license":"Apache-2.0","homepage":"https://github.com/aws/modern-data-architecture-accelerator#readme","repository":{"url":"git+https://github.com/aws/modern-data-architecture-accelerator.git","type":"git"},"description":"Tool-agnostic AI agent steering rules for MDAA. Authors rules once and projects them to per-tool layouts (Kiro, Claude Code, GitHub Copilot, Cursor, Windsurf).","maintainers":[{"name":"mdaa-dev-team","email":"mdaa-dev-team@amazon.com"}],"readme":"# `@aws-mdaa/agent-rules`\n\nTool-agnostic AI agent steering rules for MDAA. Author each rule once under\nthe repo-root `agent_rules/<name>.md` directory and project a thin,\ntool-specific wrapper into every supported assistant's expected layout.\n\n## Why\n\nMDAA contributors and downstream consumers use a mix of AI coding assistants:\nKiro, Claude Code, GitHub Copilot, Cursor, Windsurf. Each tool reads rules\nfrom a different path with a different frontmatter dialect. Maintaining a full\ncopy of every rule per tool causes drift. This package keeps the canonical\ncontent in one place and emits per-tool projections deterministically.\n\nProjections contain **only** tool-specific frontmatter plus a reference back\nto the canonical source — no rule body is duplicated. Editing a rule's content\ndoes not change any projection; only changing its scope, globs, description, or\ntool list does.\n\n## Layout\n\nThe canonical rules live at the **repo root** (`agent_rules/`), so they can be\ncopied wholesale into consumer projects (e.g. by `mdaa init`) with their\nrepo-root-relative references intact. The tooling that projects them lives in\nthis package.\n\n```\nagent_rules/                   # canonical rules at repo root: frontmatter + body\n├── review-compliance.md\n├── developer-coding-standards.md\n├── user-config-authoring.md\n└── ...\n\npackages/utilities/agent-rules/\n├── lib/                   # TypeScript source\n│   ├── types.ts\n│   ├── manifest.ts        # frontmatter parser + validator, rulesForTool()\n│   ├── source-loader.ts   # auto-discovers agent_rules/*.md, parses frontmatter\n│   ├── include-resolver.ts\n│   ├── projectors/        # one file per supported tool\n│   ├── projector.ts       # writes projections, prunes stale files\n│   └── run-projections.ts # build entry point\n├── test/                  # jest unit + integration tests\n└── README.md\n```\n\nThere is no `manifest.yaml` and no CLI. Rules are auto-discovered from the\nrepo-root `agent_rules/` directory and metadata is read from each file's\nfrontmatter.\n\n## Naming convention\n\nRule file stems are prefixed by audience:\n\n| Prefix       | Audience                                            |\n| ------------ | --------------------------------------------------- |\n| `review-`    | Consumed by the CI review agents                    |\n| `developer-` | Guidance for developers working in the repo         |\n| `user-`      | Guidance for end-users configuring/deploying MDAA   |\n\n## Canonical rule format\n\nEach rule is a Markdown file under `agent_rules/<name>.md` with tool-agnostic\nYAML frontmatter followed by the body:\n\n```markdown\n---\nscope: fileMatch # always | auto | manual | fileMatch\ndescription: ... # optional; one-line summary surfaced by auto-loaders\nglobs: # required when scope: fileMatch\n  - 'packages/**/*.ts'\ntools: # optional; defaults to all supported tools\n  - kiro\n---\n\n# Rule Title\n\nBody content...\n```\n\nThe frontmatter is tool-agnostic. The projector translates it into each tool's\nnative dialect (`scope: manual` → Kiro `inclusion: manual`, Cursor\n`alwaysApply: false`, Windsurf `trigger: manual`, etc.).\n\nRule bodies may use the Kiro `#[[file:RELATIVE_PATH]]` directive to reference\nsibling repo files (e.g. `CONTRIBUTING.md`); Kiro resolves these at runtime.\n\n### Scopes\n\n| Scope       | Behavior                                                                                                |\n| ----------- | ------------------------------------------------------------------------------------------------------- |\n| `always`    | Loaded into every agent session unconditionally                                                         |\n| `auto`      | Loaded automatically by tools that support description-based activation; degrades to `manual` elsewhere |\n| `manual`    | Loaded only when explicitly referenced                                                                  |\n| `fileMatch` | Loaded when the agent operates on files matching `globs`                                                |\n\n### Per-tool overrides\n\nSet `tools: [kiro]` on a rule that only makes sense in one host. For example,\n`review-preamble.md` is restricted to Kiro because the MDAA review-agent\ninfrastructure (`scripts/review/lib/kiro_integration.py`) consumes it directly.\n\n## Supported tools\n\n| Tool           | Output path                                                                               | Reference style                          |\n| -------------- | ----------------------------------------------------------------------------------------- | ---------------------------------------- |\n| Kiro           | `.kiro/steering/<name>.md`                                                                | `#[[file:...]]` include directive        |\n| Claude Code    | `CLAUDE.md` (always rules), `.claude/rules/<name>.md` (others)                            | Markdown link to canonical source        |\n| GitHub Copilot | `.github/copilot-instructions.md` (always), `.github/instructions/<name>.instructions.md` | Markdown link; `applyTo` for `fileMatch` |\n| Cursor         | `.cursor/rules/<name>.mdc`                                                                | `@`-mention; `alwaysApply` + `globs`     |\n| Windsurf       | `.windsurf/rules/<name>.md`                                                               | `@`-mention; `trigger:` frontmatter      |\n\nEach projected file references the canonical body at\n`agent_rules/<name>.md` rather than inlining it.\n\n## Building projections\n\n```bash\n# From this package directory\nnpm run build        # tsc + regenerate all projections\n\n# From the repo root\nnpx nx build @aws-mdaa/agent-rules\n```\n\n`run-projections.ts` is invoked automatically as part of `npm run build`. It is\nidempotent: files whose contents already match are not rewritten, and stale\nfiles in each tool's output directory (e.g. a rule that was renamed or removed)\nare pruned automatically.\n\n## Programmatic API\n\n```ts\nimport { loadSources, projectKiro, projectClaude, project } from '@aws-mdaa/agent-rules';\n\nconst sources = loadSources(); // auto-discovers agent_rules/*.md\nconst kiro = projectKiro(sources.rules); // ProjectionResult\nconst claude = projectClaude(sources.rules);\n\nproject({ consumerRoot: process.cwd() }); // write all projections\n```\n\nThe full type surface lives in `lib/index.ts`.\n\n## Editing rules\n\n1. Edit the canonical file under `agent_rules/<name>.md` (frontmatter and/or body).\n2. Run `npm run build` to regenerate projections.\n3. Commit the canonical rule and the regenerated projections together.\n\nBecause content changes don't alter the thin projections, most content-only\nedits regenerate nothing — only scope/glob/description/tool changes do.\n\n> **Never edit the projected files directly** (`.kiro/steering/`,\n> `.claude/rules/`, `.cursor/rules/`, `.github/instructions/`,\n> `.windsurf/rules/`, `CLAUDE.md`). They are generated and carry an\n> auto-generated banner. Edits will be overwritten on the next build.\n\n## Why are projections checked in?\n\nA developer must be fully set up immediately after checkout, with no extra\nbuild step. Committing the projections means every tool works on clone. The\nprojections are marked `linguist-generated` in `.gitattributes` so they\nauto-collapse in MR diffs.\n\nThe MDAA review-agent infrastructure additionally has hard dependencies on the\ncanonical sources:\n\n- `scripts/review/lib/kiro_integration.py` reads `review-preamble.md` directly\n  (it does not resolve Kiro includes, so it reads the canonical source, not the\n  `.kiro/steering/` wrapper).\n- Each review agent prompt embeds a\n  `#[[file:agent_rules/<rule>.md]]` directive resolved\n  at runtime.\n- `_steering_link()` in `scripts/review/lib/thread_lifecycle.py` builds GitLab\n  URLs to the canonical sources for MR review threads.\n\n## Guardrails\n\n- `test/byte-equivalence.test.ts` asserts that every checked-in projection\n  matches what the projector produces and that no stale/unprojected files\n  remain in `.kiro/steering/`.\n- The projector prunes stale files in each output directory on every run.\n\n## License\n\nApache-2.0 — see the repository [LICENSE](../../../LICENSE.txt).\n","readmeFilename":"README.md"}