Repository preparation

The Quick Start covers the basic setup: forking a sample repo, creating a PAT, registering a Blueprint, and storing the token in Secrets Manager. This section covers what you need beyond that.

Pre-flight checks

After deployment, the orchestrator calls the GitHub API before starting each task to verify your token has enough privilege. This catches common mistakes (like a read-only PAT) before compute is consumed. If the check fails, the task transitions to FAILED with a clear reason like INSUFFICIENT_GITHUB_REPO_PERMISSIONS instead of failing deep inside the agent run.

Permission requirements vary by task type:

• new_task and pr_iteration require Contents (read/write) and Pull requests (read/write).
• pr_review only needs Triage or higher since it does not push branches.

Classic PATs with repo + read:org scopes also work and are required when fine-grained tokens cannot reach the target repo (collaborator access, cross-org repos). See agent/README.md for when to use which token type.

Quick setup (single repo)

To point the default Blueprint at your own repo without editing code, pass it as a CDK context variable or environment variable:

# Context variable (preferred)
MISE_EXPERIMENTAL=1 mise //cdk:deploy -- -c blueprintRepo=your-org/your-repo

# Or environment variable
BLUEPRINT_REPO=your-org/your-repo MISE_EXPERIMENTAL=1 mise //cdk:deploy

The default is awslabs/agent-plugins. For a quick end-to-end test, fork that repo and pass your fork (e.g. -c blueprintRepo=jane-doe/agent-plugins).

Multiple repositories

To onboard additional repositories, add more Blueprint constructs in cdk/src/stacks/agent.ts and append them to the blueprints array (used to aggregate DNS egress allowlists):

new Blueprint(this, 'MyServiceBlueprint', {
  repo: 'acme/my-service',
  repoTable: repoTable.table,
});

Each Blueprint supports per-repo overrides grouped into nested props (BlueprintProps in cdk/src/constructs/blueprint.ts):

new Blueprint(this, 'MyServiceBlueprint', {
  repo: 'acme/my-service',
  repoTable: repoTable.table,
  compute: { runtimeArn: '...' },                    // override the default runtime ARN
  agent: {
    modelId: 'us.anthropic.claude-sonnet-4-6',       // foundation model override
    maxTurns: 150,                                    // default turn limit for this repo
    systemPromptOverrides: 'Extra instructions...',   // appended to the platform prompt
  },
  credentials: { githubTokenSecretArn: '...' },       // per-repo GitHub token secret
  pipeline: {
    pollIntervalMs: 5000,                             // poll interval awaiting completion
    buildCommand: 'npm run build && npm test',        // build/test verification (default: mise run build)
    lintCommand: 'npm run lint',                      // lint verification (default: mise run lint)
  },
});

If you use a custom compute.runtimeArn or credentials.githubTokenSecretArn, pass the ARNs to TaskOrchestrator via additionalRuntimeArns and additionalSecretArns so the Lambda has IAM permission. See Repo onboarding for the full model.

Build-regression gating (important for non-mise repos)

Before opening a PR, the agent runs a build and lint command in its cloud container — once on the clean clone (baseline) and again after its changes. If the build was green before and fails after, the task fails (a build-regression gate). This is a compile/test verification, not a deployment — your app’s actual deploy stays in your own CI/CD after the PR merges.

The command defaults to mise run build / mise run lint. A repo that uses mise with build / lint tasks gets gating for free. A repo that uses npm, gradle, cargo, make, etc. must set pipeline.buildCommand (and optionally lintCommand) to its real command — otherwise the default mise run build finds no task, build-regression gating is silently OFF, and a change that breaks the build still reports success. When that happens the agent surfaces a ⚠️ Build-regression gating is OFF warning on the PR so the gap is visible, but the fix is to configure the command. For #247 orchestration this matters doubly: dependent sub-issues stack onto a predecessor’s branch, so an unverified broken predecessor propagates downstream.

Redeploy after changing Blueprints: mise //cdk:deploy.

Customizing the agent image

The default image (agent/Dockerfile) includes Python, Node 24 (LTS), git, gh, Claude Code CLI, and mise. If your repositories need additional runtimes (Java, Go, native libs), extend the Dockerfile. A normal cdk deploy rebuilds the image asset.

Writing Cedar policies for the repo

A blueprint can declare its own security.cedarPolicies rules on top of the built-in hard/soft-deny starter set. Hard-deny rules absolutely block a tool call; soft-deny rules pause the agent and ask a human before proceeding.

See the Cedar policy guide for the full authoring reference — vocabulary (execute_bash, write_file, context.command, context.file_path), annotations (@rule_id, @tier, @approval_timeout_s, @severity, @category), worked examples, multi-match rules, and cross-engine parity testing with contracts/cedar-parity/ fixtures.

Other options

• Stack name - The default is backgroundagent-dev (set in cdk/src/main.ts). If you rename it, update all --stack-name references.
• Making repos agent-friendly - Add CLAUDE.md, .claude/rules/, and clear build commands. See the Prompt guide for details.