[ayushtr-aws]

Fork-only prototype. Upstream #836 is an RFC-proposal without the approved label (ADR-003); the governance gate was waived by the fork owner for this prototype. Not intended for aws-samples until the RFC is approved.

Why

ABCA deploys Slack, Linear, Jira, deploy-preview screenshots and the Agent Registry for every operator, whether used or not, and only discovers an unsupported Region (e.g. Agent Registry outside its five Regions) late inside CloudFormation. That costs resources (~146 of 463 root resources), IAM/secret surface and deploy time, and eats the 490-resource budget. Implements aws-samples#836.

Approach

One validated DeploymentFeatures value is resolved in main.ts (abca.deployment.json → per-feature context switches override → legacy topology when no profile) and passed to AgentStack; constructs never read feature context directly. Disabled modules are omitted, not relocated: Slack/Linear/Jira/screenshots attach routes to the shared Task API RestApi, and ADR-023 §1 plus the CDK stack-decomposition guidance rule out cross-stack route extraction without a migration rehearsal. A regional capability catalog (contracts/deployment-capabilities.json, verified 2026-10-25 against the AgentCore Regions page) is enforced at synth for concrete Regions and mirrored into the CLI. bgagent setup diffs a temporary candidate profile and only writes the repo file after confirmation. Decision recorded in ADR-024 (proposed).

Deliberate deviations from the issue (in ADR-024): the orchestration table + live reconciler stay core (the reconciler owns per-task budget rollups); the task table's LinearIssueIndex/JiraIssueIndex GSIs stay (schema change out of scope); nested-stack extraction of route-owning integrations is not done.

Changes

• cdk/src/deployment/{features,capabilities}.ts: profile parsing (strict, schemaVersion: 1, every feature explicit), precedence, deploymentProfile=<path>|none, Region validation.
• cdk/src/stacks/agent.ts: gates every optional module, its grants, env, alarms and outputs. Stranded-orchestration sweep and heartbeat only with Linear/Jira. Screenshot→tracker wiring only when both are on. New DeploymentFeatures output.
• cdk/src/constructs/task-api.ts: WAF body-size exemptions only for deployed webhook paths (legacy statements unchanged).
• ecs-agent-cluster.ts, lambda-microvm-compute.ts, github-screenshot-integration.ts: tracker OAuth / index grants follow the selection.
• cdk/src/main.ts: reads the repo profile; Region check before any AWS lookup.
• cli/src/commands/setup.ts (bgagent setup):
  • Region first, plus a core check.
  • Preselects deployed features; marks unavailable ones as unselectable.
  • --features, --yes, --no-deploy, --accept-data-loss, repeatable -c/--context.
  • Diff gate for delete/replace/orphan of state-bearing resources.
  • Refuses runs that would drop compute_types/networkTopology.
  • Configures the CLI afterwards.
• cli/src/feature-guard.ts: slack/linear/jira/github webhook-* fail fast pointing at bgagent setup. slack setup no longer runs an ungated deploy.
• cdk/mise.toml: //cdk:diff forwards args. .dockerignore excludes the profile.

Tests & checks

• CDK census grows 122 → 142 profiles. Feature cells (minimal, each feature alone, Linear+Jira, Linear+screenshots, all; both topologies) assert:
  • disabled features leave no resources, outputs, routes, Lambda permissions or IAM grants on tracker secrets/indexes;
  • catalogued footprints stay within 15% of synthesis (an order-independent check).
• Unit tests cover profile parsing/precedence, Region checks (synth + buildApp), compute-role grants across all three backends, and the screenshot grants.
• CLI tests (59 new across setup/profile/guard/parity):
  • interactive defaults, Region-unavailable features, existing-stack detection (output + legacy inference);
  • non-interactive runs, cancellation/EOF (exit 130), and failures in diff, deploy and stack reads;
  • context conflicts, data-loss gating including --no-deploy, real cdk diff impact words, and guard wiring on the real commands.
• Legacy template compared with main (normalized for asset hashes and timestamps): identical except the new DeploymentFeatures output.
• Commands run:
  • mise run build ✅ (CDK 6,001/6,001, CLI 1,147/1,147, agent, docs, synth)
  • mise run drift-prevention ✅
  • security:sast ✅ (justified nosemgrep on operator-local paths)
  • security:secrets ✅, security:retire ✅, security:gh-actions ✅
  • mise run hooks:run: every hook passes except the pre-push security aggregate, which fails because of the two items below.
• ❌ security:deps: 26 existing OSV advisories in lockfiles this PR doesn't touch (same on main).
• ❌ security:sast:masking: 3 existing findings, identical on main (chore(security): clean up 21 pre-existing silent-success-masking findings on main aws-samples/sample-autonomous-cloud-coding-agents#756); this PR adds none.
• Bootstrap/IAM policy bundle: n/a (no new resource types).
• Not verified live. I have not deployed a minimal stack, so the acceptance criterion "minimal deployment can submit a task, enforce Cedar approvals, run the agent, open a PR" is unverified.

Documentation

• DEPLOYMENT_GUIDE.md#deployment-profiles covers the profile format, precedence, the wizard, what disabling removes, data loss, regional data and how to update it.
• Also updated: Quick start, the Slack/Linear/Jira/screenshot guides, the DEVELOPER_GUIDE census section, ARCHITECTURE, the CLI README, AGENTS.md routing and pitfalls, and ADR-024.
• Starlight mirrors regenerated: yes.

Self-review

• Agents run:
  • CDK correctness reviewer: no blocking findings; 4 should-fix, all fixed.
  • CLI code-reviewer + silent-failure-hunter + test-analyzer: 1 blocking (replacement detection) + 8 should-fix, all fixed.
  • Security reviewer: 2 MEDIUM (compute-role OAuth grants, replacement detection) + 2 LOW, all fixed.
• Omitted: type-design-analyzer, because the new types are plain records mirrored from existing idioms.
• Human heuristics: Proportionality ✅ · Coherence ✅ · Clarity ✅ · Appropriateness ✅.
• Known nits left in:
  • approximateResources are standalone deltas; Linear and Jira share about 10 resources, so the sum overstates savings. Labelled as such.
  • Account display for new installs is best-effort (no STS dependency was added, to avoid a new dependency).

Update: guided bgagent setup

Follow-up commits (1a709b7…895f6b5) change the wizard flow to: confirm account → pick or name a deployment → choose compute (new installs only) → choose features → review → change summary → deploy? → live progress → result plus next steps.

• Account: confirmed through STS GetCallerIdentity, showing the account and role. Declining stops before anything is read or written. @aws-sdk/client-sts reuses the version already in yarn.lock, so the lockfile is unchanged.
• Deployments:
  • Lists the ABCA stacks in the Region. You can update one, or create a new one under a name you choose; taken and unlisted existing names are rejected.
  • Each extra stack gets abca.deployment.<stack>.json. CDK prefers that file and falls back to abca.deployment.json.
• Compute (new installs only): AgentCore (default), ECS, or both, stored as the profile's optional compute. buildApp applies it unless compute_types/compute_type context is set. Existing stacks keep their backends; setup can add one but refuses to remove one.
• Account preparation, after confirmation:
  • Installs or updates ABCA's least-privilege CDK bootstrap (mise //cdk:bootstrap now accepts an aws://account/region argument).
  • Sets the bootstrap ComputeTypes parameter, always including AgentCore.
  • Never touches a standard CDK bootstrap.
• Container engine: uses CDK_DOCKER, else Docker, else Finch (passing CDK_DOCKER=finch).
• UX:
  • Plain-language change summary instead of the raw cdk diff.
  • Live per-component progress board with ✓/✗.
  • Failure screen naming the component and CloudFormation's reason (cascading cancellations hidden).
  • Raw logs in ~/.bgagent/logs/<stack>/, because clean:disk wipes cdk.out.
• Docs and ADR: ADR-024 adds decisions 7 (first-install compute and account preparation) and 8 (several deployments per checkout and account). The deployment guide, CLI README and Starlight mirrors are updated.

Checks (at 895f6b5)

• mise run build ✅ (CDK 6,009/6,009, CLI 1,194/1,194, agent, docs, synth). drift-prevention ✅. security:sast ✅. security:secrets ✅.
• security:sast:masking: only the 3 findings that already exist on main (chore(security): clean up 21 pre-existing silent-success-masking findings on main aws-samples/sample-autonomous-cloud-coding-agents#756).
• Live run: bgagent setup deployed forked-test-abca to us-east-1 through Finch, ending at the next-steps screen: AgentCore, with Linear and deploy-preview screenshots enabled; 385 resources created.