Setup

ABCA First-Time Setup

You are guiding a developer through the complete ABCA setup process. Work through each phase sequentially, verifying success before moving on. Use AskUserQuestion when you need input.

Phase 1: Verify Prerequisites

Check each prerequisite and report status. Run these checks:

# Check each tool
aws --version 2>/dev/null
docker --version 2>/dev/null
mise --version 2>/dev/null
node --version 2>/dev/null
cdk --version 2>/dev/null
yarn --version 2>/dev/null

Required tools:

• AWS CLI (configured with credentials for a dedicated AWS account)
• Docker (running — needed for local agent runs and CDK asset builds)
• mise (task runner and version manager — https://mise.jdx.dev/)
• Node.js 22.x (managed by mise)
• Yarn Classic 1.22.x (via Corepack)
• AWS CDK CLI >= 2.233.0
• GitHub fine-grained PAT with repository access

For any missing tool, provide the specific installation command for the user's platform. Do NOT proceed until all prerequisites are met.

Phase 2: Toolchain Setup

Run these steps in order, verifying each:

1. mise trust — Trust the project config
2. mise install — Install tool versions
3. corepack enable && corepack prepare yarn@1.22.22 --activate — Enable Yarn
4. Verify: node --version (should be v22.x), yarn --version (should be 1.22.x)
5. export MISE_EXPERIMENTAL=1 — Required for namespaced tasks
6. mise run install — Install all workspace dependencies
7. mise run build — Full monorepo build (agent quality + CDK + CLI + docs)

Common Phase 2 snags to pre-empt (don't let these read as a broken environment):

• "yarn: command not found" → Corepack wasn't activated (step 3).
• prek install fails about core.hooksPath → another hook manager owns hooks; suggest git config --unset-all core.hooksPath.
• Node, Yarn, AND CDK all "not found" at once → expected before mise install finishes; mise provisions them.
• mise install fails Node on GPG verification (headless/EC2, no gpg-agent) → mise settings set node.gpg_verify false (still checksum-verified), retry.
• "config not trusted" for ~/.config/mise/config.toml → run mise trust on the user-global config too, not just the project one.
• In a non-interactive/spawned shell, mise may not be on PATH → use ~/.local/bin/mise or mise exec --.

Phase 3: One-Time Host Setup (build architecture)

The agent image is built for linux/arm64 (AgentCore runs on Graviton). On an x86_64 build host this is the most common first-deploy blocker — the image build dies with exec /bin/sh: exec format error. Register QEMU emulation once per host:

docker run --privileged --rm tonistiigi/binfmt --install arm64

If docker run --privileged is blocked (security-managed hosts), deploy from a native arm64 host (Graviton EC2 / Apple Silicon) instead. On Apple Silicon / arm64 hosts, skip this phase.

X-Ray tracing is OPTIONAL — do not gate deployment on it. The stack ships with X-Ray→CloudWatch-Logs export disabled (tracingEnabled in agent.ts), so it deploys and runs fully without any X-Ray setup. Do NOT run aws xray update-trace-segment-destination as a prerequisite — on a security-managed AWS Org account an SCP can make that call fail with AccessDeniedException no matter what, dead-ending the user on a step the platform doesn't use. Mention tracing only as an opt-in extra.