RFC: modular ABCA deployment profiles and CLI setup wizard

Start with the proposed bgagent setup entry point, AgentStack, and the abca.deployment.json profile described in the issue. Read the existing CDK and mise deployment path, then inspect the planned CDK and CLI test areas. Done means the acceptance criteria are met across profile handling, regional validation, conditional resources, migration safety, and documentation.

Primary area

Cross-cutting: CDK infrastructure, CLI, integrations, CI, and documentation.

Summary

ABCA currently deploys almost every capability even when operators do not use—or cannot access—the underlying services. The default root template is approximately 479 resources, while #735 reports configurations reaching 486 of CloudFormation's 500-resource limit.

Introduce a bgagent setup wizard that recommends a governed minimal deployment and asks operators only about optional features:

• Slack
• Linear
• Jira
• Deploy-preview screenshots
• AWS Agent Registry
• Tool Gateway

The selection should be persisted and used consistently by local CDK deployments and CI.

Motivation

Customers using only ABCA's core CLI and GitHub workflow should not need infrastructure for unused integrations or region-limited services.

Service availability also varies by AWS Region. An operator may be unable to deploy a selected capability even if they want it. For example, AWS Agent Registry is currently available in only five Regions: us-east-1, us-west-2, ap-northeast-1, ap-southeast-2, and eu-west-1.

Regional availability can change, so ABCA should validate against maintained service-capability data rather than assume every service exists everywhere. See the AWS documentation for supported AgentCore Regions.

Unused or unavailable features currently add Lambdas, tables, secrets, IAM policies, API routes, alarms, deployment time, operating cost, and security-review surface. They may also cause the entire deployment to fail late with an unclear unsupported-service error.

Approximate optional-feature footprints in the current root template are:

Feature	Resources
Slack	27
Linear	15
Jira	15
Deploy-preview screenshots	16
Agent Registry	2 root resources plus approximately 60 nested resources

This issue complements #735, which tracks the immediate CloudFormation limits, and #377, which covers separating infrastructure and runtime deployment lifecycles. No existing issue appears to cover optional deployment composition and its CLI experience.

Proposed solution

Governed minimal deployment

The recommended minimal profile must retain everything necessary to operate ABCA safely:

• AgentCore runtime and secure VPC/egress controls
• Task API and Cognito/API-key authentication
• Task state, events, admission, and concurrency controls
• Repository onboarding and GitHub task/PR workflow
• Cedar HITL policies, approvals, and audit events
• Required secrets, attachments, reconciliation, logging, alarms, and diagnostics

All listed optional features should default to disabled when creating a new profile.

Compute selection remains unchanged and outside the first wizard version.

Persistent deployment profile

Add a versioned, non-secret repository configuration:

{
  "schemaVersion": 1,
  "features": {
    "slack": false,
    "linear": false,
    "jira": false,
    "deployPreviewScreenshots": false,
    "agentRegistry": false,
    "toolGateway": false
  }
}

Store it as abca.deployment.json at the repository root.

CDK and CI must consume the same file. Explicit command-line context overrides may take precedence.

For backward compatibility, deployments without this file must preserve today's default/full topology. Shipping this feature must not silently delete resources from existing installations.

Regional capability validation

Maintain a typed capability catalog for region-limited features. Each entry should identify:

• feature name;
• required AWS services;
• supported Regions;
• authoritative source and last-verified date;
• maturity status where relevant;
• remediation when the target Region is unsupported.

The wizard should determine the target Region before asking about optional features.

For an unsupported feature, it should:

• display the feature as unavailable in the selected Region;
• default it to disabled;
• explain which Regions currently support it;
• prevent deployment unless the operator selects a different Region or disables it.

The same validation must run during CDK synthesis when a concrete Region is available, preventing the CLI from being the only enforcement point.

Regional availability data must have a documented update process and tests so it does not become stale as AWS expands service coverage.

bgagent setup wizard

Add a top-level interactive command that:

1. Detects the repository, AWS account, Region, stack name, and existing deployment.
2. Validates required core services in the selected Region.
3. Loads availability information for optional features.
4. Recommends the minimal profile for new installations.
5. Asks only about optional features available in the target Region.
6. Explains maturity, dependencies, regional limitations, and approximate resource footprint.
7. Writes abca.deployment.json.
8. Synthesizes the selected deployment and displays a summary and cdk diff.
9. Requires explicit confirmation before removing state-bearing resources.
10. Deploys using the existing mise/CDK path.
11. Configures the CLI from the resulting stack outputs.

For existing deployments, the wizard should detect and preselect deployed features so rerunning it does not propose accidental deletion.

Support non-interactive automation:

bgagent setup --features slack,jira --yes
bgagent setup --features none --no-deploy

A non-interactive request for an unsupported feature must fail with an actionable error rather than silently omit it.

Conditional CDK composition

Create one validated DeploymentFeatures configuration and pass it into AgentStack. Avoid unrelated context checks scattered throughout the stack.

When a feature is disabled, do not synthesize its:

• API routes and authorizers
• Lambdas and IAM permissions
• DynamoDB tables
• Secrets
• Fan-out or orchestration wiring
• Alarms
• CloudFormation outputs

Substantial optional modules should be moved into nested stacks. This recovers root-stack headroom even for operators who enable every feature.

Shared issue-orchestration resources should only deploy when Linear or Jira is enabled. GitHub screenshot-to-Linear wiring should only exist when both corresponding features are enabled.

CLI commands for omitted modules—for example, bgagent slack setup—should fail with an actionable message directing the operator to rerun bgagent setup.

Compatibility and migration

• No deployment profile: preserve the current deployment topology.
• New installation using the wizard: recommend the minimal profile.
• Existing installation: detect currently deployed features and preserve them by default.
• An enabled feature that is unavailable in the selected Region must produce an actionable validation error.
• Disabling integrations or Registry may delete tables, secrets, installations, mappings, or registry records.
• The wizard must show destructive changes and require explicit confirmation.
• Re-enabling a removed stateful module may create empty infrastructure unless an import/recovery path is documented.
• Existing CDK context switches should remain supported during migration.

Out of scope

• Runtime feature toggles that do not use CloudFormation
• Selecting ECS or Lambda MicroVM compute in the initial wizard
• Making authentication, Cedar HITL, secure egress, or core governance optional
• Automatically relocating an existing deployment to another Region
• Replacing the deployment-lifecycle work proposed in #377

Acceptance criteria

• bgagent setup recommends the governed minimal profile for new deployments.
• A minimal deployment can submit a task, enforce Cedar approvals, run the agent, and open or update a GitHub PR.
• The wizard detects the target AWS Region before presenting optional features.
• Unsupported features are clearly marked and cannot be selected accidentally.
• Non-interactive deployments fail clearly when requesting an unsupported feature.
• CDK synthesis validates region-limited features independently of the CLI.
• Regional capability data includes its source, verification date, tests, and update instructions.
• Disabled features produce no resources, routes, permissions, wiring, or outputs.
• Every optional feature can be enabled independently where regionally supported.
• Linear-specific screenshot behavior only exists when both features are enabled.
• An absent profile preserves current behavior.
• Existing features are detected and preselected by the wizard.
• Resource deletion requires a visible diff and explicit confirmation.
• Local and CI synthesis consume the same profile.
• CDK tests cover minimal, legacy-full, optional-module, and unsupported-Region configurations.
• CLI tests cover regional availability, interactive defaults, existing-stack detection, non-interactive operation, cancellation, and deployment failures.
• Root-stack resource and template usage remain below the 90% budget tracked with #735.
• Deployment, regional availability, upgrade, removal, and data-loss behavior are documented.