git:20260511.5aa3ee5 to git:20260613.140b89d

---

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

```

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

```bash

```

## 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.