---
name: onboard-repo
description: >-
  Onboard a new GitHub repository to the ABCA platform by adding a Blueprint CDK
  construct. Use when the user says "onboard a repo", "add a repository",
  "register a repo", "new repo", "Blueprint construct", "REPO_NOT_ONBOARDED error",
  or gets a 422 error about an unregistered repository.
---

# Repository Onboarding

You are guiding the user through onboarding a new GitHub repository to ABCA. Repositories must be registered as `Blueprint` constructs in the CDK stack before tasks can target them.

## Step 1: Gather Repository Details

Use AskUserQuestion to collect:
- **Repository**: GitHub `owner/repo` format
- **Compute type**: `agentcore` (default) or `ecs`
- **Model preference**: Claude Sonnet 4 (default), Claude Opus 4 (complex repos), or Claude Haiku (lightweight). **Important:** Models must be specified using their cross-region inference profile ID (e.g. `us.anthropic.claude-opus-4-20250514-v1:0`), not the raw foundation model ID. On-demand invocation of raw model IDs is not supported for most models.
- **Max turns**: Default 100 (range: 1-500)
- **Max budget**: USD cost ceiling per task (optional)
- **Custom GitHub PAT**: If this repo needs a different token than the platform default

## Step 2: Read the Current Stack

Read the CDK stack file to understand existing Blueprint definitions:

```
Read cdk/src/stacks/agent.ts
```

Identify:
- Where existing Blueprint constructs are defined
- The `repoTable` reference used
- Any patterns for compute/model overrides

### Sample blueprint repo without a code change

The stack’s **AgentPlugins** blueprint uses a `repo` value resolved in this order: **`BLUEPRINT_REPO`** (environment variable) → CDK context **`blueprintRepo`** → default `awslabs/agent-plugins` (see `blueprintRepo` in `cdk/src/stacks/agent.ts`). If the user only needs to target a fork of the sample repo, they can set `export BLUEPRINT_REPO=owner/repo` or pass `-c blueprintRepo=owner/repo` (or set `"context": { "blueprintRepo": "..." }` in `cdk/cdk.json`) and redeploy, instead of adding a new `Blueprint` construct.

## Step 3: Add the Blueprint Construct

Add a new `Blueprint` construct instance to the stack. Follow the existing pattern. Example:

```typescript
new Blueprint(this, 'MyRepoBlueprint', {
  repo: 'owner/repo',
  repoTable: repoTable.table,
  // Optional overrides:
  // computeType: 'agentcore',
  // modelId: 'us.anthropic.claude-sonnet-4-20250514-v1:0',
  // maxTurns: 100,
  // maxBudgetUsd: 50,
  // runtimeArn: runtime.runtimeArn,
  // githubTokenSecretArn: 'arn:aws:secretsmanager:...',
});
```

Use a descriptive construct ID derived from the repo name.

### Model ID and IAM Permissions

When specifying a non-default model via `agent.modelId`, three things are required:

1. **Use the inference profile ID, not the raw model ID, when Bedrock requires it.** For `InvokeModel` / streaming, specify the cross-Region **inference profile** identifier (or ARN) where the Bedrock User Guide calls for it — not only the bare `anthropic.*` foundation model ID. Examples:
   - Sonnet 4.6 (US geography profile): `us.anthropic.claude-sonnet-4-6`
   - Sonnet 4: `us.anthropic.claude-sonnet-4-20250514-v1:0`
   - Opus 4: `us.anthropic.claude-opus-4-20250514-v1:0`
   - Haiku 4.5: `us.anthropic.claude-haiku-4-5-20251001-v1:0`

   See [Use an inference profile in model invocation](https://docs.aws.amazon.com/bedrock/latest/userguide/inference-profiles-use.html).

2. **Grant the runtime IAM permissions for the model.** The Blueprint construct does not automatically grant `bedrock:InvokeModel*` — this is by design (least privilege). You must add a `grantInvoke` block in the stack for each model used:
   ```typescript
   const opusModel = new bedrock.BedrockFoundationModel('anthropic.claude-opus-4-20250514-v1:0', {
     supportsAgents: true,
     supportsCrossRegion: true,
   });
   opusModel.grantInvoke(runtime);

   const opusProfile = bedrock.CrossRegionInferenceProfile.fromConfig({
     geoRegion: bedrock.CrossRegionInferenceProfileRegion.US,
     model: opusModel,
   });
   opusProfile.grantInvoke(runtime);
   ```

3. **Account-level Bedrock model access (separate from IAM).** The runtime role must be allowed to invoke the model, and the **AWS account** must be able to use that model in Bedrock: complete [model access](https://docs.aws.amazon.com/bedrock/latest/userguide/model-access.html) prerequisites (AWS Marketplace actions on first serverless use where applicable, Anthropic first-time use / `PutUseCaseForModelAccess` for Anthropic models, valid payment method for Marketplace-backed models). For geographic cross-Region inference profiles, IAM and SCPs must allow Bedrock in **source and destination** Regions per [Supported Regions and models for inference profiles](https://docs.aws.amazon.com/bedrock/latest/userguide/inference-profiles-support.html).

## Step 4: Deploy

After adding the Blueprint, the stack must be redeployed:

```bash
export MISE_EXPERIMENTAL=1
mise //cdk:compile   # Verify TypeScript compiles
mise //cdk:test      # Run tests
mise //cdk:diff      # Preview changes
```

Show the diff to the user. If it looks correct, ask if they want to deploy now.

```bash
mise //cdk:deploy
```

## Step 5: Verify

After deployment, verify the repo config was written to DynamoDB:

```bash
aws dynamodb scan --table-name <RepoTableName> \
  --filter-expression "repo = :r" \
  --expression-attribute-values '{":r":{"S":"owner/repo"}}' \
  --output json
```

## Per-Repository Configuration Reference

| Setting | Purpose | Default |
|---------|---------|---------|
| `compute_type` | Execution strategy | `agentcore` |
| `runtime_arn` | AgentCore runtime override | Platform default |
| `model_id` | AI model for tasks | Platform default (Sonnet 4) |
| `max_turns` | Turn limit per task | 100 |
| `max_budget_usd` | Cost ceiling per task | Unlimited |
| `system_prompt_overrides` | Custom system instructions | None |
| `github_token_secret_arn` | Repo-specific GitHub token | Platform default |
| `poll_interval_ms` | Completion polling frequency | 30000ms |

Task-level parameters override Blueprint defaults. If neither specifies a value, platform defaults apply.

## Common Issues

- **422 "Repository not onboarded"** — Blueprint hasn't been deployed yet. Add the construct and redeploy.
- **Preflight failures after onboarding** — GitHub PAT may lack permissions for the new repo. Check the PAT's fine-grained access includes the target repository with Contents (read/write) and Pull requests (read/write) permissions.
- **400 "Invocation with on-demand throughput isn't supported"** — The Blueprint `modelId` is using a raw foundation model ID instead of an inference profile ID. Change e.g. `anthropic.claude-opus-4-20250514-v1:0` to `us.anthropic.claude-opus-4-20250514-v1:0`.
- **403 "not authorized to perform bedrock:InvokeModelWithResponseStream"** — The runtime IAM role lacks permissions for the model specified in the Blueprint. Add `grantInvoke` for both the model and its cross-region inference profile in `agent.ts`.
- **Model not available / "not available on your Bedrock deployment"** — IAM is not the whole story: the account must meet [Bedrock model access](https://docs.aws.amazon.com/bedrock/latest/userguide/model-access.html) for that model family and Region, and `modelId` should be an **enabled** inference profile ID (for example `us.anthropic.claude-sonnet-4-6`) where Bedrock requires it. After fixing access in the console, align Blueprint / DynamoDB `model_id` and redeploy if you change IAM grants.