Skip to content

AGENTS.md

Latest commit

 

History

History
161 lines (147 loc) · 10.2 KB

AGENTS.md

File metadata and controls

161 lines (147 loc) · 10.2 KB
Raw

Agent Instructions

What this repo is

Pulumi AWSX provider/component library. Core behavior is implemented in awsx/ (TypeScript) and provider/ (Go schema generation). The repo also contains legacy TypeScript components in awsx-classic/. Most files in sdk/ and several workflow files are generated artifacts.

Start Here

  • Makefile - canonical local command surface.
  • .ci-mgmt.yaml - source-of-truth for generated CI workflows and Make targets.
  • docs/ai-harness/README.md - current AI harness state and known gaps.
  • docs/ai-harness/testing.md - guidance for writing new AWSX tests.
  • REVIEW.md - AWSX-specific review notes that are not generic PR-review advice.
  • .agents/skills/triage-provider-issue/SKILL.md - APM-managed initial issue assessment when ownership or the next evidence artifact is unclear.
  • .agents/skills/stage-pulumi-provider-repro/SKILL.md - APM-managed durable Pulumi repro staging when triage selects that next step.
  • .agents/skills/awsx-issue-planning/SKILL.md - pre-implementation planning for nontrivial AWSX issues where scope, API shape, compatibility, or spec needs are unsettled.
  • .agents/skills/awsx-start-issue-planning-session/SKILL.md - manual-only starter for planning an issue in a fresh session and stopping before edits.
  • .agents/skills/awsx-implement-approved-plan/SKILL.md - manual-only launcher for implementing an already reviewed AWSX plan.
  • .agents/skills/awsx-component-design/SKILL.md - tactical authoring workflow for modern awsx/** component changes.
  • .agents/skills/awsx-breaking-change-evaluation/SKILL.md - compatibility and schema public-surface review workflow.
  • .agents/skills/awsx-test-authoring/SKILL.md - test-selection and assertion guidance for modern AWSX changes.
  • .agents/skills/awsx-aws-service-validation/SKILL.md - AWS service fact, docs, provider-surface, and regional availability validation.
  • .claude/skills/ - symlinks to most repo-local .agents/skills/ entries so Claude Code sees the same skill sources; manual-only launcher skills may use small Claude wrappers for Claude-specific invocation controls.
  • provider/pkg/schemagen/ - schema generation logic.
  • provider/cmd/pulumi-resource-awsx/ - provider schema output and embedding.
  • awsx/ - TypeScript provider implementation + Jest tests.
  • awsx-classic/ - legacy TypeScript components and compatibility surface.
  • examples/ - integration/acceptance tests (real AWS resources).
  • CONTRIBUTING.md and DEVELOPMENT.md - contributor docs.

AI Harness

  • Keep harness docs small and AWSX-specific. Do not add placeholder docs or generic "remember to test" guidance.
  • Add harness material only when it captures a real repo pattern, repeated mistake, or concrete review rule.
  • If a session reveals missing guidance, update the smallest existing harness file first.

Use the focused harness entry points this way:

  • AGENTS.md owns repo map, commands, generated boundaries, and path-triggered validation.
  • REVIEW.md owns the short AWSX-specific review checklist.
  • Repo-owned .agents/skills/awsx-* entries are the source of truth for AWSX skills. Core provider skills are declared in apm.yml and deployed locally; do not edit their generated copies under .agents/skills/ or .claude/skills/.
  • Start issue work with triage-provider-issue when ownership or the next evidence artifact is unclear. Use stage-pulumi-provider-repro when triage selects a durable Pulumi repro.
  • Once AWSX ownership is established, use .agents/skills/awsx-issue-planning/SKILL.md when a nontrivial issue still has unsettled scope, API shape, compatibility, or spec needs. Produce the planning brief and stop by default; do not let the same session self-approve implementation unless the prompt explicitly asks to proceed after planning without a maintainer review checkpoint.
  • Use .agents/skills/awsx-start-issue-planning-session/SKILL.md and .agents/skills/awsx-implement-approved-plan/SKILL.md only when explicitly invoked as session launchers. They are control-flow wrappers around the tactical AWSX skills, not ambient guidance.
  • Treat prior rollout summaries, memories, or old worktree diffs for the same issue as historical attempts, not accepted design guidance.
  • .agents/skills/awsx-issue-planning/SKILL.md applies before editing when a nontrivial issue needs scope, API-shape, current-usability, compatibility, proof-strategy, or checked-in-spec decisions.
  • .agents/skills/awsx-component-design/SKILL.md applies when designing or reviewing modern awsx/** component shape: args, outputs, child resources, names, providers, regions, defaults, and registerOutputs.
  • .agents/skills/awsx-breaking-change-evaluation/SKILL.md applies when a change may affect existing users: schema or generated SDK surface, child identity, aliases, defaults, provider/region behavior, or upgrade previews.
  • .agents/skills/awsx-test-authoring/SKILL.md applies when choosing or writing proof: Jest mocks, schema/SDK checks, provider-upgrade tests, targeted acceptance tests, and assertion quality.
  • .agents/skills/awsx-aws-service-validation/SKILL.md applies when a change depends on AWS service behavior, API or CloudFormation constraints, regional availability, or disagreement between AWS docs and @pulumi/aws.
  • docs/ai-harness/testing.md is the human-readable overview for AWSX test choices; prefer the test-authoring skill for tactical rule-by-rule guidance. Known remaining harness gaps: final abstraction admission rules, component invariant audit for parentage/registerOutputs/region propagation, and modern component replay or snapshot fixture strategy.

Command Canon

  • Build provider + SDKs + install SDKs: make build
  • Regenerate schema + SDKs: make generate
  • Build provider binary: make provider
  • Build SDKs only: make build_sdks
  • Install SDKs only: make install_sdks
  • Lint: make lint
  • AWSX TypeScript/Jest tests (fast): make test_provider
  • Full integration suite (AWS-backed, CI-only locally): make test
  • Targeted integration tests: GOTESTARGS="-run TestName" make test
  • Regenerate workflows/Makefile from ci-mgmt: make ci-mgmt

Prefer the make targets. If you must regenerate without the mise/upstream prerequisites they depend on, note two traps:

  • pulumi-gen-awsx resolves its input path relative to the working directory, so it must be run from the repo root (go build -o /tmp/pgen ./cmd/pulumi-gen-awsx from provider/, then /tmp/pgen schema --out provider/cmd/pulumi-resource-awsx from the root). Run from provider/ it exits 1 with no message.
  • The SDK generators stamp the version, so running them without VERSION set rewrites sdk/nodejs/package.json, sdk/python/pyproject.toml, the pulumi-plugin.json files, Pulumi.Awsx.csproj, sdk/java/build.gradle, and sdk/go/awsx/internal/pulumiUtilities.go. Revert that churn; keep only the API diff.

yarn --cwd awsx lint currently fails on a pre-existing no-unused-expression in awsx/ec2/vpc.ts. Check the failure against master before attributing it to your change.

Generated Boundaries

Never hand-edit generated outputs as the source of truth:

  • sdk/**
  • provider/cmd/pulumi-resource-awsx/schema.json
  • provider/cmd/pulumi-resource-awsx/schema-embed.json
  • awsx/schema-types.ts (regenerate with yarn --cwd awsx gen-types after a schema change)
  • ci-mgmt-generated workflow YAML and gh-aw .lock.yml files under .github/workflows/
  • .github/aw/actions-lock.json
  • Makefile

Use source files + regeneration commands instead. Some workflow source files also live under .github/workflows/. Edit those source files only when they are the source of truth, then regenerate/validate the generated outputs.

When reviewing generated workflow or Makefile changes, do not assume they were hand-edited only because generated files changed. First check whether .ci-mgmt.yaml changed, or whether the commit/PR notes explicitly say make ci-mgmt was run for a generated refresh or tool-pin update. Flag generated workflow changes only when there is no corresponding source-of-truth change or documented regeneration reason.

If You Change...

  • awsx/** -> run make test_provider
  • awsx-classic/** -> run yarn --cwd awsx-classic lint
  • provider/pkg/schemagen/** -> run make schema && make generate
  • .ci-mgmt.yaml -> run make ci-mgmt
  • examples/** -> run targeted acceptance tests locally; do not run the full make test suite locally
  • docs/ai-harness/** or REVIEW.md -> keep the guidance specific to AWSX and remove duplicated command lists

Key Invariants

  • Schema generation changes can affect all language SDKs.
  • make test creates real AWS resources and can incur cost.
  • CI/workflow edits should be made via .ci-mgmt.yaml, not by hand in generated workflow files.
  • AWSX components are remote components (super(..., true /*remote*/)): their children are constructed inside the provider, not in the user's program. Client-side transformations never see those children; only engine-side transforms do. Say transforms when recommending a user-side escape hatch, and do not assume a user can reach a child resource any other way.
  • A child's Pulumi resource name is its identity. Changing one replaces the resource, and for a subnet that means a delete/recreate that fails while ENIs are attached. Prefer expressing a user-visible naming change through the AWS Name tag and keeping the Pulumi resource name stable. subnetNameTagStrategy in awsx/ec2/vpc.ts does exactly this: a spec's resourceName is always the index-based name and is what every child is created under, while nameTag is the only thing subnetNameTagStrategy="AvailabilityZone" changes - so no aliases are needed. If a change genuinely must rename a resource, it has to be opt-in and carry an alias back to the old name.

Forbidden Actions

  • No destructive git (git reset --hard, force push, checkout discard) without explicit approval.
  • No hand-edits to generated files without corresponding source/regeneration changes.
  • Do not claim checks passed unless you ran them.

Escalate Immediately If

  • Unsure whether a touched file is source or generated.
  • Public SDK surface changes are introduced by schema edits.
  • CI behavior change cannot be expressed cleanly via .ci-mgmt.yaml.