docs: add least-privilege deployment roles and deployment guide

[scottschreckengaust]

Summary

• Validated least-privilege IAM policies for the CloudFormation execution role through end-to-end deployment testing on a clean AWS account (us-east-1). The original single monolithic policy was replaced with a 3-way split to stay under the IAM managed policy 6,144-character limit:
  • IaCRole-ABCA-Infrastructure — CloudFormation, IAM, VPC, Route 53 Resolver DNS Firewall
  • IaCRole-ABCA-Application — DynamoDB, Lambda, API Gateway, Cognito, WAFv2, EventBridge, Secrets Manager (+ optional ECS)
  • IaCRole-ABCA-Observability — Bedrock AgentCore, Bedrock Guardrails, CloudWatch, X-Ray, S3, KMS, ECR, SSM, STS
• Fixed Quick Start deployment blockers found during end-to-end walkthrough:
  • X-Ray update-trace-segment-destination fails on fresh accounts without a CloudWatch Logs resource policy — added prerequisite aws logs put-resource-policy command
  • mise run build fails without AWS credentials (CDK synth does AZ lookups) — added note and common error entry
  • Added common error entries for non-TTY deploy approval and build credential issues
  • Added AWS_PROFILE guidance for multi-profile users
• Fixed abca-plugin gaps discovered during deep review:
  • /setup skill Phase 3 was missing the logs put-resource-policy prerequisite (same X-Ray bug)
  • /deploy skill had no least-privilege guidance — added section with re-bootstrap command and reference to DEPLOYMENT_ROLES.md
  • CLAUDE.md had no reference to the plugin — added pointer so sessions discover guided workflows
• Add docs/guides/DEPLOYMENT_GUIDE.md covering architecture, scale-to-zero analysis (~$140-150/month idle), and complete AWS services inventory
• Update docs/design/COST_MODEL.md with corrected baseline, scale-to-zero section, and updated references
• Add .gitignore entries for Claude Code plugin artifacts (.mcp.json, .remember/)
• Add docs-sync pre-commit hook to auto-regenerate Starlight mirrors

Review feedback addressed

Changes made after code review:

#	Issue	Resolution
1	SecretsManager Resource: "*"	Split GetRandomPassword into own statement; all other actions scoped to backgroundagent-*
2	Deploy SKILL.md references non-existent IaCRole-ABCA-Policy	Updated to reference all three policy names
3	DEPLOYMENT_GUIDE.md has no Starlight mirror	Added route mapping, mirror, and sidebar entry
4	iam:PassRole without conditions	Added IAMPassRole statement with iam:PassedToService condition (7 services); AttachRolePolicy restriction added as iterative tightening item
5	aws-service-role/* allows any service-linked role	Added iam:AWSServiceName as iterative tightening item
6	KMS kms:CreateGrant on Resource: "*"	Added kms:ResourceAliases as iterative tightening item
7	X-Ray resource policy grants Resource: "*"	Scoped to arn:aws:logs:*:${ACCOUNT_ID}:log-group:aws/spans
8	Inconsistent placeholder names	Unified to ACCOUNT_ID with substitution note
9	ACCOUNT_ID captured but never used	Now used by scoped X-Ray resource policy (item 7)
10	Session timeout "8 hours" vs "9 hours"	Clarified: 8h = AgentCore service limit, 9h = orchestrator executionTimeout
11	VPC endpoint cost underestimated	Corrected from ~$50/mo to ~$102/mo (7×2 AZs×$0.01/hr×730hrs); baseline updated to ~$140-150/mo
12	Region wildcards	Kept as iterative tightening item #3 (users deploy to different regions)

Deployment validation test matrix

Four configurations are tested across the full stack lifecycle (create → task → update → destroy):

#	IAM Policy	ECS Compute	Purpose
V1	AdministratorAccess (default bootstrap)	Off (AgentCore only)	Baseline — confirms stack works with default permissions
V2	AdministratorAccess	On (ECS Fargate)	Baseline with ECS — confirms ECS compute path works
V3	Least-privilege (3-way split)	Off (AgentCore only)	Primary validation — confirms scoped policies are sufficient
V4	Least-privilege (3-way split)	On (ECS Fargate)	Confirms ECS statement + scoped policies work together

Lifecycle steps per variation

Each variation runs through:

1. Create — Fresh cdk deploy from clean state (no existing stack). Validates all resource creation permissions.
2. Task — Submit a coding task via CLI, wait for agent to complete and open a PR. Validates runtime permissions (Secrets Manager read, DynamoDB, AgentCore/ECS invocation).
3. Update — Modify a Blueprint parameter and redeploy. Validates stack update permissions (resource modifications, not just creation).
4. Destroy — cdk destroy to tear down all resources. Validates deletion permissions.

Pre-test setup (once per account)

• CDK bootstrap (default for V1/V2, re-bootstrap with --cloudformation-execution-policies for V3/V4)
• X-Ray resource policy (aws logs put-resource-policy)
• GitHub PAT stored in Secrets Manager (post first deploy)
• Cognito user created (post first deploy)

Pass criteria

• Create: Stack reaches CREATE_COMPLETE with no permission errors in CloudFormation events
• Task: Task reaches COMPLETED status with a PR URL in the output
• Update: Stack reaches UPDATE_COMPLETE
• Destroy: Stack reaches DELETE_COMPLETE (AgentCore ENI timing retries are acceptable)

Progress is reported as individual PR comments (one per lifecycle step per variation, ~16 total).

Files changed

File	What Changed
docs/design/DEPLOYMENT_ROLES.md	3-way policy split; IAMPassRole with PassedToService condition; split SecretsManager; iterative tightening items for AttachRolePolicy, CreateServiceLinkedRole, KMS; unified ACCOUNT_ID placeholder
docs/guides/DEPLOYMENT_GUIDE.md	New: architecture, scale-to-zero (~$140-150/mo), AWS services inventory; corrected VPC endpoint cost; clarified session timeouts
docs/guides/QUICK_START.md	X-Ray resource policy scoped to aws/spans; build credential note; AWS_PROFILE guidance; 4 new common errors
docs/design/COST_MODEL.md	Corrected VPC endpoint cost (~$102/mo); baseline updated to ~$140-150/mo; clarified session timeouts; scale-to-zero section
docs/abca-plugin/skills/setup/SKILL.md	Scoped X-Ray resource policy
docs/abca-plugin/skills/deploy/SKILL.md	Updated to 3-way policy split
docs/scripts/sync-starlight.mjs	Added DEPLOYMENT_GUIDE route mapping and mirror
docs/astro.config.mjs	Added Deployment Guide sidebar entry
CLAUDE.md	Added plugin reference
AGENTS.md	Strengthened docs-sync instructions
.gitignore	Added .mcp.json, .remember/
.pre-commit-config.yaml	Added docs-sync pre-commit hook

Test plan

• Deploy with AdministratorAccess on clean account — passed (initial validation)
• CloudTrail analysis of all CFN execution role actions — 36 gaps identified
• Deploy with scoped 3-way policy split — passed after 7 iterations (initial validation)
• Stack update with scoped policies — passed (initial validation)
• Smoke test (task submission, PR creation) — passed (initial validation)
• Stack destroy with scoped policies — passed with AgentCore ENI retry (initial validation)
• ECS statement fits in Application policy under size limit — verified (4,110 / 6,144 chars with ECS + split SM)
• Verify all markdown links resolve between new and existing docs
• Starlight mirrors regenerated and astro check passed
• V1: Admin / No ECS — create → task → update → destroy
• V2: Admin / ECS — create → task → update → destroy
• V3: Least-priv / No ECS — create → task → update → destroy
• V4: Least-priv / ECS — create → task → update → destroy

🤖 Generated with Claude Code

[krokoko]

Overall this is a high-quality, deployment-validated PR that replaces AdministratorAccess with scoped IAM policies — a significant security improvement. However, all three reviewers flagged issues
that should be addressed before merge.

---

Critical (must fix)

1. SecretsManager Resource includes bare "*" — grants full account access to all secrets

File: docs/design/DEPLOYMENT_ROLES.md (and Starlight mirror)

The SecretsManager statement lists "*" as a second resource alongside the scoped ARN, completely negating least-privilege. Actions like GetSecretValue, DeleteSecret, and PutSecretValue become
account-wide.

Fix: Split GetRandomPassword (the only action that requires "") into its own statement:
{
"Sid": "SecretsManager",
"Action": ["secretsmanager:CreateSecret", "...all others except GetRandomPassword..."],
"Resource": "arn:aws:secretsmanager::㊙️backgroundagent-"
},
{
"Sid": "SecretsManagerAccountLevel",
"Action": "secretsmanager:GetRandomPassword",
"Resource": "*"
}

2. Deploy SKILL.md references non-existent policy name IaCRole-ABCA-Policy

File: docs/abca-plugin/skills/deploy/SKILL.md

The skill tells users to bootstrap with a single IaCRole-ABCA-Policy, but DEPLOYMENT_ROLES.md defines three policies (-Infrastructure, -Application, -Observability). Users following this skill will
get a deployment failure.

Fix: Update to reference all three --cloudformation-execution-policies flags, matching DEPLOYMENT_ROLES.md.

3. DEPLOYMENT_GUIDE.md has no Starlight mirror — broken link on docs site

File: docs/src/content/docs/architecture/Cost-model.md

The Starlight mirror of COST_MODEL.md contains Deployment guide as a raw relative path because the sync script has no route mapping for it. This is a broken link on
the deployed Starlight site.

Fix: Either add DEPLOYMENT_GUIDE to explicitGuideRoutes in sync-starlight.mjs and create a mirror, or remove the link from content that gets mirrored.

---

High (strongly recommend fixing)

4. iam:PassRole and iam:AttachRolePolicy without conditions — privilege escalation path

File: docs/design/DEPLOYMENT_ROLES.md, IAMRolesAndPolicies statement

Without an iam:PassedToService condition on PassRole and no policy restriction on AttachRolePolicy, the execution role could create a backgroundagent-dev-* role, attach AdministratorAccess to it, pass
it to Lambda, and invoke it — full account compromise.

Fix: Add iam:PassedToService condition limiting to lambda.amazonaws.com, ecs-tasks.amazonaws.com, apigateway.amazonaws.com, logs.amazonaws.com, bedrock.amazonaws.com.

5. aws-service-role/* allows creating any service-linked role

File: docs/design/DEPLOYMENT_ROLES.md, IAMRolesAndPolicies statement

Combined with iam:CreateServiceLinkedRole, the resource arn:aws:iam:::role/aws-service-role/ allows creating service-linked roles for any AWS service.

Fix: Add an iam:AWSServiceName condition scoped to only the services ABCA actually uses.

6. KMS kms:CreateGrant on Resource: "*" — can delegate key access across account

The CDK bootstrap key alias (alias/cdk-hnb659fds-*) is deterministic. Consider adding a kms:ResourceAliases condition to scope this.

7. X-Ray resource policy in QUICK_START.md grants Resource: "*" to xray.amazonaws.com

Fix: Scope to arn:aws:logs::ACCOUNT_ID:log-group:aws/spans and arn:aws:logs::ACCOUNT_ID:log-group:aws/spans:*.

8. Inconsistent placeholder names (ACCOUNT vs ACCOUNT_ID)

The bootstrap command uses ACCOUNT, the trust policy uses ACCOUNT_ID, and the IAM ARNs use * for the account field. Should be unified with a single ACCOUNT_ID placeholder and a note at the top
explaining substitution.

---

Medium (should fix)

9. ACCOUNT_ID variable captured but never used

Files: QUICK_START.md, setup/SKILL.md (and Starlight mirror)

ACCOUNT_ID=$(aws sts get-caller-identity ...) is set but never referenced. Either remove it or use it to scope the resource policy ARN.

10. Session timeout inconsistency: "8 hours" vs "9 hours"

• DEPLOYMENT_GUIDE.md says "8 hours (AgentCore session)"
• COST_MODEL.md (updated in this PR) says "9 hours"
• Code: executionTimeout: Duration.hours(9) at task-orchestrator.ts:173
• Pre-existing COST_MODEL.md line 46 still says "8-hour max session timeout" (not updated)

These are actually two different limits (AgentCore service limit vs. orchestrator timeout), but this needs explicit clarification.

11. VPC endpoint cost may be underestimated

The PR claims ~$50/month for 7 endpoints across 2 AZs. AWS pricing: 7 x 2 AZs x $0.01/hr x 730 hrs = ~$102/month. This would push the total baseline to ~$135-145/month. (Pre-existing issue in
COST_MODEL.md, perpetuated in the new DEPLOYMENT_GUIDE.md.)

12. Region wildcards throughout all policies

All ARNs use * for region despite ABCA deploying to a single region. The "Iterative tightening" section mentions this but it could be a stronger recommendation.

[scottschreckengaust]

1. SecretsManager Resource includes bare "*"

The "*" is intentional — secretsmanager:GetRandomPassword is an account-level API that does not support resource-level permissions (it generates a random string without referencing any secret). Splitting it into its own statement would push the Application policy over the IAM 6,144-character limit (the 3-way split was specifically sized to stay under this). Added an entry to the Resource-level permission constraints table documenting this, with a pointer to the Iterative tightening section for post-deployment refinement.

2. Deploy SKILL.md references non-existent policy name IaCRole-ABCA-Policy

Fixed — updated to reference all three policies (IaCRole-ABCA-Infrastructure, -Application, -Observability) with the three --cloudformation-execution-policies flags matching DEPLOYMENT_ROLES.md.

3. DEPLOYMENT_GUIDE.md has no Starlight mirror — broken link on docs site

Fixed — added DEPLOYMENT_GUIDE to explicitGuideRoutes in sync-starlight.mjs, added a mirrorMarkdownFile() call to generate the mirror at getting-started/Deployment-guide.md, and added a sidebar entry in astro.config.mjs. The COST_MODEL.md links now rewrite to /getting-started/deployment-guide instead of the raw relative path.

[scottschreckengaust]

V1: Admin / No ECS — Task

✅ Passed — Task 01KQ0VB0GSYS245NH2Q4ZGN41K completed in 124s, $0.14.

• PR: chore(github): add CODEOWNERS file with default owner scottschreckengaust/agent-plugins#3
• Status: COMPLETED
• Agent created CODEOWNERS file and opened PR successfully.

[scottschreckengaust]

V1: Admin / No ECS — Update

✅ Passed — Stack reached UPDATE_COMPLETE. Added systemPromptOverrides to Blueprint and redeployed successfully.

[scottschreckengaust]

V1: Admin / No ECS — Destroy

⏳ In progress (retry) — First delete attempt hit the known AgentCore ENI cleanup timing issue (security group + 2 subnets retained by ela-attach managed ENIs). Retrying delete — ENIs typically release within 10-30 min after runtime deletion. This is a known operational note, not a permissions issue.

[scottschreckengaust]

V1: Admin / No ECS — Destroy

✅ Passed (with known ENI retry) — Stack deleted. AgentCore-managed ENIs (ela-attach) held references to the security group and subnets, requiring --retain-resources on the VPC, 2 subnets, and 1 SG. These orphaned resources will be cleaned up once ENIs release (~10-30 min). This is a known operational characteristic, not a permissions issue.

V1 Summary: All 4 lifecycle steps passed (Create ✅ → Task ✅ → Update ✅ → Destroy ✅).

[scottschreckengaust]

V2: Admin / ECS — Create

✅ Passed — Stack reached CREATE_COMPLETE with ECS Fargate cluster, task definition, and Docker image asset. Submitting smoke test task now.

[scottschreckengaust]

V2: Admin / ECS — Task

✅ Passed — Task completed in 130s, $0.16.

• PR: chore(config): add .editorconfig with standard formatting settings scottschreckengaust/agent-plugins#4
• Status: COMPLETED
• Agent created .editorconfig and opened PR (routes to AgentCore; ECS cluster deployed but not task-routed).

[scottschreckengaust]

V2: Admin / ECS — Update

✅ Passed — Stack reached UPDATE_COMPLETE. Removed systemPromptOverrides from Blueprint and redeployed with ECS cluster intact.

[scottschreckengaust]

V2: Admin / ECS — Destroy

✅ Passed (with known ENI retry) — Same AgentCore ENI timing pattern as V1. Used --retain-resources on VPC/subnets/SG, stack deleted successfully. Orphaned resources cleaned up separately.

V2 Summary: All 4 lifecycle steps passed (Create ✅ → Task ✅ → Update ✅ → Destroy ✅).

Now setting up V3 (least-privilege / no ECS) — creating IAM policies and re-bootstrapping.

[scottschreckengaust]

V3: Least-priv / No ECS — Create

✅ Passed (after 2 policy fixes) — Stack reached CREATE_COMPLETE with scoped 3-way IAM policies.

Two permission gaps found and fixed during V3 validation:

1. SecretsManager resource scope — CDK generates the GitHub token secret as GitHubTokenSecret09BC4210-*, not backgroundagent-*. Added GitHubTokenSecret* to the resource list. (commit 3adb6e2)
2. PassedToService missing services — vpc-flow-logs.amazonaws.com (VPC Flow Log role) and bedrock-agentcore.amazonaws.com (AgentMemory service role) were missing from the condition. Added both. (commit 6cd306b)

Submitting smoke test task now.

[scottschreckengaust]

V3: Least-priv / No ECS — Task

✅ Passed — Task completed in 124s, $0.14.

• PR: chore(git): add .gitattributes with LF line ending normalization scottschreckengaust/agent-plugins#5
• Status: COMPLETED
• Agent created .gitattributes and opened PR under scoped IAM policies.

[scottschreckengaust]

V3: Least-priv / No ECS — Update

✅ Passed — Stack reached UPDATE_COMPLETE under scoped IAM policies.

[scottschreckengaust]

V3: Least-priv / No ECS — Destroy

✅ Passed (with X-Ray internal error retry) — Most resources deleted cleanly. AWS::XRay::ResourcePolicy delete hit an AWS internal error (InternalFailure) — not a permissions issue. Retried with --retain-resources and manually cleaned up the orphaned X-Ray policy.

V3 Summary: All 4 lifecycle steps passed (Create ✅ → Task ✅ → Update ✅ → Destroy ✅).

Two policy fixes discovered and committed during V3:

• GitHubTokenSecret* added to SecretsManager resource scope
• vpc-flow-logs.amazonaws.com and bedrock-agentcore.amazonaws.com added to PassedToService

Starting V4 (least-priv / ECS) now.

[scottschreckengaust]

V4: Least-priv / ECS — Create

✅ Passed — Stack reached CREATE_COMPLETE with ECS cluster + scoped 3-way IAM policies (Application policy v3 includes ECS statement, 4,167 / 6,144 chars). Submitting smoke test task now.

[scottschreckengaust]

V4: Least-priv / ECS — Task

✅ Passed — Task completed in 129s, $0.16.

• PR: chore(license): replace Apache 2.0 with MIT license scottschreckengaust/agent-plugins#6
• Status: COMPLETED
• Agent created LICENSE file and opened PR under scoped IAM policies + ECS cluster.

[scottschreckengaust]

V4: Least-priv / ECS — Update

✅ Passed — Stack reached UPDATE_COMPLETE under scoped IAM policies + ECS.

[scottschreckengaust]

V4: Least-priv / ECS — Destroy

✅ Passed (with X-Ray internal error + ENI retry) — Same patterns as V3. X-Ray ResourcePolicy delete hit AWS InternalFailure, and AgentCore ENIs held VPC resources. Both are AWS service timing issues, not permissions. Used --retain-resources and cleaned up manually.

V4 Summary: All 4 lifecycle steps passed (Create ✅ → Task ✅ → Update ✅ → Destroy ✅).

---

Full Test Matrix Results

#	Policy	ECS	Create	Task	Update	Destroy
V1	Admin	Off	✅	✅ PR #3, $0.14, 124s	✅	✅ (ENI retry)
V2	Admin	On	✅	✅ PR #4, $0.16, 130s	✅	✅ (ENI retry)
V3	Least-priv	Off	✅ (2 policy fixes)	✅ PR #5, $0.14, 124s	✅	✅ (X-Ray internal)
V4	Least-priv	On	✅	✅ PR #6, $0.16, 129s	✅	✅ (X-Ray + ENI)

16/16 test points passed.

Policy fixes discovered during validation

1. SecretsManager resource scope — Added GitHubTokenSecret* pattern (CDK-generated secret name doesn't use backgroundagent- prefix) — commit 3adb6e2
2. PassedToService missing services — Added vpc-flow-logs.amazonaws.com and bedrock-agentcore.amazonaws.com — commit 6cd306b

Known destroy patterns (not permissions-related)

• AgentCore ENIs (ela-attach) hold SG/subnet references for 10-30 min after runtime deletion → use --retain-resources then clean up
• X-Ray ResourcePolicy delete intermittently returns InternalFailure → retain and delete manually via aws xray delete-resource-policy

Account cleanup completed

• Orphaned VPC resources (subnets, SGs, VPCs) cleaned up after ENI release
• Orphaned X-Ray resource policies deleted
• CDK bootstrap stack retained (reusable)

[scottschreckengaust]

@krokoko - ready for review, all four matrix tests are complete