Agent Instructions — ADP (Agentic Developer Platform)

For deployment, follow the canonical agent deployment guide. It owns account confirmation, phase ordering, private journals, recovery, verification and when to request user input. Use the quickstart for source and published-release commands. The references below supplement those instructions.

Resource Map

Read docs/adp-platform-deployment/deployment-manifest.md for the complete mapping of every resource to its AWS service, module, and validation command. Use it to validate each phase after completion.

What This Repo Contains

Three modules on a shared AWS platform:

Shared infrastructure: platform/infra/ (VPC, EKS, ECR, IAM).

Deployment Playbook

Follow deploy-with-agent.md for deployment behavior, account confirmation, journal handling, verification, and when to involve the user. Use the quickstart for the customer launcher and the phase reference for manual diagnosis. Keep deployment procedures in those documents rather than duplicating them here.

Deploy-path note: earlier versions of this file inlined a 10-phase playbook with an upfront "Phase 0: GitHub setup" (setup-org.sh + 3 org-owned apps) that stood up ARC self-hosted runners as the agent onboarding/deploy path. That onboarding path is superseded by the webhook-ingress flow (GitHub webhook → Lambda → SQS → KEDA → agent-worker; see deploy-quickstart.md) — for summoning an agent to do open-ended work, use webhook-ingress, not ARC.

ARC runners are NOT deprecated as an execution model, though. They remain a first-class, complementary capability: deterministic GitHub Actions pipelines on EKS that an agent can trigger and monitor — the right tool when you need a known, auditable, repeatable sequence of steps (e.g. complex multi-stage deployments) rather than open-ended agent reasoning. Setup + usage for that path lives in modules/agent-factory/SETUP-GUIDE.md.

Troubleshooting Reference

Use this when things go wrong. Do not show this to the user — use it to diagnose and fix issues yourself.

Terraform init fails

• ACCOUNT_ID placeholder not replaced → run sed -i "s/ACCOUNT_ID/$(aws sts get-caller-identity --query Account --output text)/g" on the tfvars file
• S3 bucket doesn't exist → run bootstrap.sh first

EKS nodes not appearing

• Auto Mode takes 3-5 min. Wait and retry kubectl get nodes.
• If still empty after 5 min, check: kubectl get events --all-namespaces --sort-by='.lastTimestamp' | tail -20

Gateway pods CrashLoopBackOff

• kubectl logs -n adp-gateway -l app=bedrockgateway --previous --tail=50
• Missing configmap: kubectl get configmap bedrockgateway-config -n adp-gateway
• Missing secret: kubectl get secret bedrockgateway-secrets -n adp-gateway
• RDS not reachable: check security groups allow EKS → RDS on port 5432

CloudFront 502

• ALB not yet created by Ingress controller. Check: kubectl get ingress -n adp-gateway
• Wait 2-3 minutes for ALB provisioning, then check again.

Frontend blank page

• Wrong VITE_API_URL during build. Rebuild with VITE_API_URL="/api" npm run build — must match gateway-deploy.yml (/api, NOT /api/gateway); the wrong prefix makes every SPA call hit the S3 HTML fallback with HTTP 200 and crash the dashboard.
• Stale cache: aws cloudfront create-invalidation --distribution-id <id> --paths "/*"

All GitHub logins denied after a broker deploy

• Symptom: every "Sign in with GitHub" (including yours) fails, but /api/health is healthy and gateway pods are Running — so it is NOT the CloudFront /api fail-destroy class.
• Broker logs show: ALLOWLIST_MODE=open without ALLOW_OPEN_SIGNUP=true is a misconfiguration; denying sign-in (aws logs tail /aws/lambda/bedrockgw-<env>-github-auth-broker --since 15m).
• Cause: the #3986 fail-closed broker CODE publishes on merge, but the ALLOW_OPEN_SIGNUP env var only lands via gateway-infra-apply.yml. On an env still set to ALLOWLIST_MODE=open, the gap between the two is a total login outage.
• Emergency fix + durable remediation: docs/runbooks/github-auth-allowlist-remediation.md (adds ALLOW_OPEN_SIGNUP=true to the live Lambda to restore login in ~30s, then move the env to mode=org).

CodeBuild fails

• Only 4 docker-build projects use CodeBuild (gateway-build, chat-agent, agent-gateway, arc-runner). They are Terraform-managed in platform/infra/modules/codebuild/. Everything else (terraform apply, npm build, kubectl apply) runs directly on the ARC runner.
• Check logs: aws codebuild batch-get-builds --ids <build-id> --query 'builds[0].logs.deepLink' --output text
• IAM propagation: if role was just created, wait 15 seconds and retry

Destroy / Teardown

Use platform/scripts/undeploy.sh --dry-run to preview an explicitly authorized teardown, then follow the account-confirmation gate and teardown reference. The shell entrypoint and .github/workflows/undeploy.yml use the shared teardown engine. It stops on failure and orders factory removal before webhook/KEDA. The backend and GitHub credentials/key survive by default. Do not substitute deploy-all.sh --destroy or manually delete retained resources to force success. For reinstallation, follow the canonical guide's retained-resource reconciliation.

Key Files Reference

Non-Interactive Shell Rules

Always use non-interactive flags to avoid hanging:

• cp -f, mv -f, rm -f
• terraform apply -auto-approve, terraform init -input=false
• apt-get -y, yum -y
• Never use interactive editors (vim, nano) — use cat > or sed
• kubectl apply (already non-interactive)

Issue-authoring convention (MANDATORY for every new issue)

Use the canonical developer issue template or epic template, following the issue-authoring guide. GitHub exposes the same bodies as Developer task and Engineering epic. The guide specifies native parent links, stable AC/EC/scenario IDs and controlled, independently verifiable tests; the walkthrough includes filled examples and an optional offline format check. The guide owns the requirements; do not create another inline template here.

Keep these sections in order: The problem in plain terms, Description, Impact analysis, Design, Deployment, Validation. Use stable acceptance IDs with action, expected result, evidence, phase and owner. Distinguish implementation readiness from unresolved live access and deployment prerequisites. Name the completion boundary explicitly; a merged PR is not live acceptance.

The guide also covers compact test-coverage issues, discovery, and run-only versus build-and-run evaluations. Keep established AIDLC approval gates and branch protections. Filing or editing an issue does not authorize deployment or dispatch; use core-workflow's current dispatch mechanism when dispatch is requested.