From 4b29a615cfebf10a8c03f1698bc6a1a179112c90 Mon Sep 17 00:00:00 2001 From: Ray Smets Date: Mon, 13 Apr 2026 12:21:06 -0700 Subject: [PATCH 01/20] wip --- .claude-plugin/plugin.json | 7 ++ README.md | 36 ++++++++- agents/agent-debugger.md | 61 +++++++++++++++ agents/cdk-expert.md | 48 ++++++++++++ commands/abca-status.md | 52 +++++++++++++ commands/abca-submit.md | 43 +++++++++++ hooks/hooks.json | 13 ++++ skills/deploy/SKILL.md | 83 ++++++++++++++++++++ skills/onboard-repo/SKILL.md | 103 ++++++++++++++++++++++++ skills/setup/SKILL.md | 99 ++++++++++++++++++++++++ skills/submit-task/SKILL.md | 136 ++++++++++++++++++++++++++++++++ skills/troubleshoot/SKILL.md | 146 +++++++++++++++++++++++++++++++++++ 12 files changed, 826 insertions(+), 1 deletion(-) create mode 100644 .claude-plugin/plugin.json create mode 100644 agents/agent-debugger.md create mode 100644 agents/cdk-expert.md create mode 100644 commands/abca-status.md create mode 100644 commands/abca-submit.md create mode 100644 hooks/hooks.json create mode 100644 skills/deploy/SKILL.md create mode 100644 skills/onboard-repo/SKILL.md create mode 100644 skills/setup/SKILL.md create mode 100644 skills/submit-task/SKILL.md create mode 100644 skills/troubleshoot/SKILL.md diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 00000000..31e87569 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,7 @@ +{ + "name": "abca-getting-started", + "version": "1.0.0", + "description": "Getting started guide and developer toolkit for ABCA (Autonomous Background Coding Agents on AWS). Provides guided setup, deployment, task submission, repository onboarding, and troubleshooting workflows.", + "author": "aws-samples", + "homepage": "https://github.com/aws-samples/sample-autonomous-cloud-coding-agents" +} diff --git a/README.md b/README.md index ecfaa43a..b01d414b 100644 --- a/README.md +++ b/README.md @@ -69,7 +69,41 @@ See the full [ROADMAP](./docs/guides/ROADMAP.md) for details on each iteration. ## Getting started -### Installation and deployment +### Claude Code plugin (recommended) + +This repository ships a [Claude Code plugin](https://docs.anthropic.com/en/docs/claude-code/plugins) that provides guided workflows for setup, deployment, task submission, and troubleshooting. When you open this project in Claude Code, the plugin is auto-discovered from the `.claude-plugin/` directory. + +**Using the plugin:** + +The plugin is automatically available when you clone this repo and open it in Claude Code. No manual installation needed — Claude Code discovers the `.claude-plugin/plugin.json` at the project root. + +| Component | What it does | +|-----------|-------------| +| `/setup` | Guided first-time setup: prerequisites, toolchain, deploy, smoke test | +| `/deploy` | Deploy, diff, or destroy the CDK stack with pre-checks | +| `/onboard-repo` | Add a new GitHub repository via Blueprint construct | +| `/submit-task` | Submit a coding task with prompt quality coaching | +| `/troubleshoot` | Diagnose deployment, auth, or task execution issues | +| `/abca-status` | Quick platform health check | +| `/abca-submit` | Shortcut for task submission | + +Specialized agents (`cdk-expert`, `agent-debugger`) are also available for CDK development and task failure investigation. + +**For local plugin development:** + +If you're modifying the plugin itself, the component files live at the project root: + +``` +.claude-plugin/plugin.json # Plugin manifest +skills/ # Guided workflow skills (SKILL.md in subdirs) +agents/ # Specialized subagent definitions +commands/ # Slash commands +hooks/hooks.json # SessionStart hook for project context +``` + +After editing plugin files, run `/reload-plugins` in Claude Code to pick up changes. No restart required. + +### Manual installation and deployment Install [mise](https://mise.jdx.dev/getting-started.html) if you want to use repo tasks (`mise run install`, `mise run build`). For monorepo-prefixed tasks (`mise //cdk:build`, etc.), set **`MISE_EXPERIMENTAL=1`** — see [CONTRIBUTING.md](./CONTRIBUTING.md). diff --git a/agents/agent-debugger.md b/agents/agent-debugger.md new file mode 100644 index 00000000..724ab757 --- /dev/null +++ b/agents/agent-debugger.md @@ -0,0 +1,61 @@ +--- +name: agent-debugger +description: >- + Debugs ABCA agent runtime issues — task failures, preflight errors, agent + execution problems, and log analysis. Use when investigating why a task failed, + analyzing CloudWatch logs, or debugging the Python agent code. +tools: + - Read + - Grep + - Glob + - Bash +--- + +You are a debugging specialist for the ABCA agent runtime. You diagnose task execution failures by analyzing logs, events, and agent code. + +## Your Expertise + +- Task lifecycle: SUBMITTED -> HYDRATING -> RUNNING -> COMPLETED/FAILED +- Agent runtime: Python code in `agent/src/` (pipeline.py, runner.py, config.py, hooks.py, policy.py) +- System prompts: `agent/prompts/` with base template and per-task-type variants +- Orchestrator: Lambda durable functions managing task state +- Preflight checks: GitHub API validation before compute allocation + +## Debugging Workflow + +1. **Get task events** to understand what happened: + ```bash + node cli/lib/bin/bgagent.js events --output json + ``` + +2. **Check event types** for clues: + - `preflight_failed` — GitHub access issue (PAT permissions, repo existence) + - `guardrail_blocked` — Content screening rejected the prompt + - `admission_rejected` — Concurrency limit or validation failure + - `task_failed` — Agent runtime error + - `task_timed_out` — 9-hour limit exceeded + +3. **For runtime failures**, check CloudWatch logs: + ```bash + aws logs filter-log-events --log-group-name /aws/lambda/backgroundagent-dev-orchestrator \ + --filter-pattern "" --limit 50 + ``` + +4. **For agent code issues**, read the relevant Python source: + - `agent/src/pipeline.py` — Main execution pipeline + - `agent/src/runner.py` — Task runner loop + - `agent/src/config.py` — Configuration loading + - `agent/src/hooks.py` — Lifecycle hooks + - `agent/prompts/` — System prompt templates + +5. **For local reproduction**, use: + ```bash + DRY_RUN=1 ./agent/run.sh "owner/repo" "task description" + ``` + +## Common Failure Patterns + +- **PAT scope too narrow**: Preflight fails because fine-grained token doesn't include the target repo +- **Missing CLAUDE.md**: Agent can't find build/test commands, wastes turns exploring +- **Stuck in test loop**: Agent repeatedly fails tests without making progress — reduce max_turns +- **Memory/compute limits**: 2 vCPU, 8 GB RAM — large monorepos may need optimization diff --git a/agents/cdk-expert.md b/agents/cdk-expert.md new file mode 100644 index 00000000..a999533d --- /dev/null +++ b/agents/cdk-expert.md @@ -0,0 +1,48 @@ +--- +name: cdk-expert +description: >- + AWS CDK and ABCA infrastructure expert. Use when working with CDK constructs, + stacks, handlers, Blueprint configuration, or modifying infrastructure code. + Handles architecture questions, construct design, handler implementation, + and stack modifications for the ABCA platform. +tools: + - Read + - Grep + - Glob + - Bash + - Edit + - Write +--- + +You are an expert AWS CDK developer specializing in the ABCA (Autonomous Background Coding Agents) platform. You have deep knowledge of CDK v2, TypeScript, and the ABCA architecture. + +## Your Expertise + +- **CDK Constructs**: Blueprint, TaskApi, TaskOrchestrator, database constructs +- **Lambda Handlers**: Task CRUD, orchestration, webhooks, shared utilities +- **AWS Services**: API Gateway, Lambda, DynamoDB, Secrets Manager, Cognito, Bedrock, AgentCore, Step Functions +- **Testing**: Jest tests mirroring the source structure under `cdk/test/` + +## Project Layout + +- `cdk/src/stacks/agent.ts` — Main stack definition +- `cdk/src/constructs/` — Reusable CDK constructs +- `cdk/src/handlers/` — Lambda handler implementations +- `cdk/src/handlers/shared/` — Shared logic (types, validation, context hydration, etc.) +- `cdk/test/` — Jest tests mirroring source structure + +## Key Conventions + +- Shared API types live in `cdk/src/handlers/shared/types.ts` — if you change these, `cli/src/types.ts` MUST stay in sync +- Use `mise //cdk:compile` to verify TypeScript, `mise //cdk:test` for tests, `mise //cdk:synth` to synthesize +- Blueprint constructs are the mechanism for repository onboarding — they write RepoConfig records to DynamoDB +- cdk-nag is enabled for security/compliance checks +- Follow existing patterns: look at how current constructs and handlers are structured before adding new ones + +## When Helping Users + +1. Always read relevant source files before suggesting changes +2. Run `mise //cdk:compile` after TypeScript changes to verify +3. Run `mise //cdk:test` after logic changes +4. Show `mise //cdk:diff` output before recommending deployment +5. Flag any security implications of infrastructure changes diff --git a/commands/abca-status.md b/commands/abca-status.md new file mode 100644 index 00000000..8ea2727d --- /dev/null +++ b/commands/abca-status.md @@ -0,0 +1,52 @@ +--- +name: abca-status +description: Check ABCA platform status — stack health, running tasks, and recent task history +allowed-tools: + - Bash + - Read +--- + +# ABCA Platform Status + +Check the current state of the ABCA platform and report a concise status summary. + +## Checks to Run + +Run these in parallel where possible: + +1. **Stack status:** + ```bash + aws cloudformation describe-stacks --stack-name backgroundagent-dev \ + --query 'Stacks[0].{Status:StackStatus,Updated:LastUpdatedTime}' --output json 2>/dev/null || echo "Stack not found" + ``` + +2. **Running tasks:** + ```bash + cd cli && node lib/bin/bgagent.js list --status RUNNING,SUBMITTED,HYDRATING --output json 2>/dev/null || echo "CLI not configured" + ``` + +3. **Recent completed tasks:** + ```bash + cd cli && node lib/bin/bgagent.js list --limit 5 --output json 2>/dev/null || echo "CLI not configured" + ``` + +4. **Local build health:** + ```bash + export MISE_EXPERIMENTAL=1 && mise run //cdk:compile 2>&1 | tail -5 + ``` + +## Output Format + +Present a concise status report: + +``` +ABCA Platform Status +==================== +Stack: [UPDATE_COMPLETE | CREATE_COMPLETE | ...] +Updated: [timestamp] +Active: [N] tasks running +Recent: [N] tasks in last batch (show status breakdown) +Build: [PASS | FAIL with error summary] +``` + +If the CLI isn't configured, note this and suggest running the `setup` skill. diff --git a/commands/abca-submit.md b/commands/abca-submit.md new file mode 100644 index 00000000..8a58b741 --- /dev/null +++ b/commands/abca-submit.md @@ -0,0 +1,43 @@ +--- +name: abca-submit +description: Quick task submission shortcut — submit a coding task with guided prompts +arguments: + - name: repo + description: "GitHub repository in owner/repo format" + required: false + - name: description + description: "Task description or issue number" + required: false +allowed-tools: + - Bash + - Read +--- + +# Quick Task Submission + +Submit a task to ABCA quickly. If arguments are missing, ask the user. + +## Collect Required Info + +If `$ARGUMENTS.repo` is not provided, ask for the repository (owner/repo format). +If `$ARGUMENTS.description` is not provided, ask what the agent should do. + +## Determine Task Type + +Parse the description to infer the type: +- If it looks like a PR number or mentions "review PR": use `--review-pr` +- If it mentions "iterate on PR" or "fix PR feedback": use `--pr` +- If it's an issue number (just a number): use `--issue` +- Otherwise: use `--task` with the text description + +## Submit + +```bash +cd cli && node lib/bin/bgagent.js submit \ + --repo $REPO \ + $FLAGS \ + --max-turns 100 \ + --wait +``` + +Show the task ID and status. If `--wait` is used, show the final outcome including PR URL if created. diff --git a/hooks/hooks.json b/hooks/hooks.json new file mode 100644 index 00000000..5d9311d7 --- /dev/null +++ b/hooks/hooks.json @@ -0,0 +1,13 @@ +{ + "SessionStart": [ + { + "matcher": "", + "hooks": [ + { + "type": "prompt", + "prompt": "You are working in the ABCA (Autonomous Background Coding Agents on AWS) repository — a self-hosted platform for background coding agents.\n\nKey directories: cdk/src/ (CDK infra), agent/src/ (Python agent), cli/src/ (bgagent CLI), docs/ (documentation).\n\nEssential commands (require MISE_EXPERIMENTAL=1): mise run install, mise run build, mise //cdk:compile, mise //cdk:test, mise //cdk:deploy.\n\nCritical: types in cdk/src/handlers/shared/types.ts must stay in sync with cli/src/types.ts. Don't edit docs/src/content/docs/ directly — it's generated.\n\nTask types: new_task (create PR), pr_iteration (update PR), pr_review (review PR).\n\nAvailable plugin skills: /setup, /deploy, /onboard-repo, /submit-task, /troubleshoot\nAvailable commands: /abca-status, /abca-submit\nAvailable agents: cdk-expert, agent-debugger\n\nDocs: https://aws-samples.github.io/sample-autonomous-cloud-coding-agents/" + } + ] + } + ] +} diff --git a/skills/deploy/SKILL.md b/skills/deploy/SKILL.md new file mode 100644 index 00000000..ca0471cd --- /dev/null +++ b/skills/deploy/SKILL.md @@ -0,0 +1,83 @@ +--- +name: deploy +description: >- + Deploy, diff, or destroy the ABCA CDK stack. Handles pre-deployment validation, + synthesis, and post-deployment verification. Use when the user says "deploy", + "cdk deploy", "deploy the stack", "destroy", "cdk diff", "what changed", + "redeploy", or "update the stack". +--- + +# ABCA Deployment + +You are managing CDK deployment for the ABCA platform. Determine the user's intent and execute the appropriate workflow. + +## Determine Action + +Ask the user (or infer from context) which action they want: +- **deploy** — Build and deploy the CDK stack +- **diff** — Show what would change without deploying +- **destroy** — Tear down the stack (requires explicit confirmation) +- **synth** — Synthesize CloudFormation without deploying + +## Pre-Deployment Checks + +Before any deployment action, verify: + +1. **Build is clean:** + ```bash + export MISE_EXPERIMENTAL=1 + mise run build + ``` + This runs agent quality checks, CDK compilation + tests, CLI build, and docs build. Do NOT deploy if the build fails. + +2. **Docker is running** — Required for CDK asset bundling +3. **AWS credentials are configured** — `aws sts get-caller-identity` + +## Deploy Workflow + +```bash +export MISE_EXPERIMENTAL=1 +mise run //cdk:deploy +``` + +After successful deployment, retrieve and display stack outputs: +```bash +aws cloudformation describe-stacks --stack-name backgroundagent-dev \ + --query 'Stacks[0].Outputs' --output table +``` + +Key outputs to highlight: `ApiUrl`, `RuntimeArn`, `UserPoolId`, `AppClientId`, `GitHubTokenSecretArn`. + +## Diff Workflow + +```bash +export MISE_EXPERIMENTAL=1 +mise run //cdk:diff +``` + +Summarize the changes: new resources, modified resources, removed resources. Flag any potentially destructive changes (resource replacements, security group changes). + +## Destroy Workflow + +**CRITICAL: Ask for explicit confirmation before destroying.** Use AskUserQuestion to confirm, explaining consequences. + +```bash +export MISE_EXPERIMENTAL=1 +mise run //cdk:destroy +``` + +## Synth Workflow + +```bash +export MISE_EXPERIMENTAL=1 +mise run //cdk:synth +``` + +Output goes to `cdk/cdk.out/`. Useful for reviewing generated CloudFormation templates. + +## Post-Deployment + +After a successful deploy, remind the user to: +- Store/update the GitHub PAT in Secrets Manager if this is a fresh deployment +- Onboard repositories via Blueprint constructs if needed +- Run a smoke test: `curl -s -H "Authorization: $TOKEN" $API_URL/tasks` diff --git a/skills/onboard-repo/SKILL.md b/skills/onboard-repo/SKILL.md new file mode 100644 index 00000000..eb298803 --- /dev/null +++ b/skills/onboard-repo/SKILL.md @@ -0,0 +1,103 @@ +--- +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) +- **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 + +## 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, + // Optional overrides: + // computeType: 'agentcore', + // modelId: '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. + +## Step 4: Deploy + +After adding the Blueprint, the stack must be redeployed: + +```bash +export MISE_EXPERIMENTAL=1 +mise run //cdk:compile # Verify TypeScript compiles +mise run //cdk:test # Run tests +mise run //cdk:diff # Preview changes +``` + +Show the diff to the user. If it looks correct, ask if they want to deploy now. + +```bash +mise run //cdk:deploy +``` + +## Step 5: Verify + +After deployment, verify the repo config was written to DynamoDB: + +```bash +aws dynamodb scan --table-name \ + --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. diff --git a/skills/setup/SKILL.md b/skills/setup/SKILL.md new file mode 100644 index 00000000..21d92d5b --- /dev/null +++ b/skills/setup/SKILL.md @@ -0,0 +1,99 @@ +--- +name: setup +description: >- + Guided installation and first-time setup for ABCA. Walks through prerequisites, + toolchain installation, dependency setup, and initial deployment. Use when the user + says "set up the project", "get started", "install", "first time setup", + "how do I start", "prerequisites", or is new to the project. +--- + +# 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: + +```bash +# 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) + +If `mise run install` fails with "yarn: command not found", Corepack wasn't activated. If `prek install` fails about `core.hooksPath`, another hook manager owns hooks — suggest `git config --unset-all core.hooksPath`. + +## Phase 3: One-Time AWS Setup + +```bash +aws xray update-trace-segment-destination --destination CloudWatchLogs +``` + +This must be run once per AWS account before first deployment. + +## Phase 4: First Deployment + +Guide through: + +1. `mise run //cdk:bootstrap` — Bootstrap CDK (if not already done for this account/region) +2. `mise run //cdk:deploy` — Deploy the stack (~9.5 minutes) +3. Retrieve stack outputs: + ```bash + aws cloudformation describe-stacks --stack-name backgroundagent-dev \ + --query 'Stacks[0].Outputs' --output table + ``` +4. Store the GitHub PAT in Secrets Manager using the `GitHubTokenSecretArn` output +5. Create a Cognito user (self-signup is disabled): + ```bash + aws cognito-idp admin-create-user --user-pool-id $USER_POOL_ID \ + --username user@example.com --temporary-password 'TempPass123!@#' + aws cognito-idp admin-set-user-password --user-pool-id $USER_POOL_ID \ + --username user@example.com --password 'YourPermanentPass123!@#' --permanent + ``` + +## Phase 5: Smoke Test + +1. Authenticate and get a JWT token +2. Test the API: `curl -s -H "Authorization: $TOKEN" $API_URL/tasks` +3. Configure the CLI: + ```bash + cd cli && mise run build + node lib/bin/bgagent.js configure \ + --api-url $API_URL --region $REGION \ + --user-pool-id $USER_POOL_ID --client-id $APP_CLIENT_ID + node lib/bin/bgagent.js login --username user@example.com + ``` + +## Completion + +After all phases pass, summarize: +- Stack outputs (API URL, User Pool ID, etc.) +- Next steps: onboard a repository (use the `onboard-repo` skill) +- Point to the User Guide: https://aws-samples.github.io/sample-autonomous-cloud-coding-agents/user-guide/introduction/ diff --git a/skills/submit-task/SKILL.md b/skills/submit-task/SKILL.md new file mode 100644 index 00000000..b0f38bcc --- /dev/null +++ b/skills/submit-task/SKILL.md @@ -0,0 +1,136 @@ +--- +name: submit-task +description: >- + Submit a coding task to the ABCA platform via CLI or REST API. Guides prompt + quality, task type selection, and cost controls. Use when the user says "submit a task", + "create a task", "run the agent", "send task to agent", "bgagent submit", + "new_task", "pr_iteration", "pr_review", "review a PR", or wants to automate coding work. +--- + +# Submit a Coding Task + +You are helping the user submit a well-crafted coding task to the ABCA platform. Good prompts are critical — the agent works autonomously without asking clarifying questions. + +## Step 1: Determine Task Type + +Use AskUserQuestion to understand what the user wants: + +| Type | When to use | Outcome | +|------|------------|---------| +| `new_task` | Implement a feature, fix a bug, refactor code | Creates a branch + opens a PR | +| `pr_iteration` | Address review feedback on an existing PR | Updates the existing PR | +| `pr_review` | Get a structured code review (read-only) | Posts review comments | + +## Step 2: Collect Task Details + +Based on the task type, gather: + +**For `new_task`:** +- Repository (`owner/repo`) +- GitHub issue number (preferred — agent fetches full context) OR text description +- If using text: the desired end state, scope constraints, acceptance criteria + +**For `pr_iteration`:** +- Repository (`owner/repo`) +- PR number +- Optional: Additional guidance ("Focus on security feedback only") + +**For `pr_review`:** +- Repository (`owner/repo`) +- PR number +- Optional: Review focus ("Check for SQL injection", "Review test coverage") + +## Step 3: Prompt Quality Check + +Before submitting, validate the prompt against these principles: + +**Good prompts:** +- Describe the desired END STATE, not step-by-step instructions +- Are specific about scope (one logical change per task) +- State preconditions and constraints ("Use React 18, not 19") +- Define verifiable goals ("npm test must pass") +- Provide examples when behavior is ambiguous +- Reference relevant files/modules (not specific line numbers) + +**Bad prompts (fix these before submitting):** +- Too vague: "Fix the bug" -> "Fix 500 on POST /users when email has plus signs" +- Too prescriptive: "Change line 42" -> "Increase auth timeout to 10s for slow connections" +- Kitchen sink: "Fix login, add dark mode, update README" -> Split into separate tasks +- Missing context: "Make it work like the other service" -> Describe explicitly + +If the prompt needs improvement, suggest a rewritten version before submitting. + +## Step 4: Set Cost Controls + +Recommend appropriate limits based on task complexity: + +| Task complexity | Suggested max_turns | Suggested max_budget | +|----------------|--------------------|--------------------| +| Typo/config change | 10-30 | $1-5 | +| Bug fix (clear scope) | 50-100 | $5-20 | +| New feature | 100-200 | $20-50 | +| Large refactor | 200-500 | $50-100 | +| PR iteration | 30-100 | $5-20 | +| PR review | 30-80 | $5-10 | + +## Step 5: Submit + +**Via CLI (preferred):** +```bash +# From the cli/ directory after building +node lib/bin/bgagent.js submit \ + --repo owner/repo \ + --issue 42 \ + --max-turns 100 \ + --max-budget 20 \ + --wait # Optional: poll until completion +``` + +**CLI flag reference:** +- `--repo owner/repo` (required) +- `--issue N` — GitHub issue number +- `--task "description"` — Text description +- `--pr N` — PR number (sets type to pr_iteration) +- `--review-pr N` — PR number (sets type to pr_review) +- `--max-turns N` — Turn limit (1-500) +- `--max-budget N` — USD cost limit ($0.01-$100) +- `--idempotency-key KEY` — Deduplication key for safe retries +- `--wait` — Poll until terminal status +- `--output json|text` — Output format + +At least one of `--issue`, `--task`, `--pr`, or `--review-pr` is required. + +**Via REST API:** +```bash +curl -X POST "$API_URL/tasks" \ + -H "Authorization: $TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "repo": "owner/repo", + "issue_number": 42, + "task_type": "new_task", + "max_turns": 100, + "max_budget_usd": 20 + }' +``` + +## Step 6: Monitor + +After submission, show how to check status: +```bash +node lib/bin/bgagent.js status +node lib/bin/bgagent.js events +node lib/bin/bgagent.js list --status RUNNING +``` + +Task states: SUBMITTED -> HYDRATING -> RUNNING -> COMPLETED/FAILED/CANCELLED/TIMED_OUT + +## Input Mode Quick Reference + +- `--issue` only: Issue is well-written with clear requirements +- `--task` only: Ad-hoc work or pre-issue tasks +- `--issue + --task`: Issue context + scope narrowing or extra guidance +- `--pr` only: Address all PR review feedback +- `--pr + --task`: PR feedback + focused scope +- `--review-pr` only: Full structured code review +- `--review-pr + --task`: Focused review on specific concerns diff --git a/skills/troubleshoot/SKILL.md b/skills/troubleshoot/SKILL.md new file mode 100644 index 00000000..1fc78210 --- /dev/null +++ b/skills/troubleshoot/SKILL.md @@ -0,0 +1,146 @@ +--- +name: troubleshoot +description: >- + Diagnose and fix common ABCA issues: deployment failures, preflight errors, + authentication problems, agent failures, and build issues. Use when the user says + "troubleshoot", "debug", "not working", "error", "failed", "help me fix", + "preflight_failed", "task failed", "deploy failed", "auth error", "401", "422", "503", + or describes something not working as expected. +--- + +# ABCA Troubleshooting + +You are diagnosing an issue with the ABCA platform. Follow a systematic approach: gather symptoms, check the most common causes, and apply targeted fixes. + +## Step 1: Identify the Problem Category + +Determine which area the issue falls into: + +1. **Build/Compilation** — TypeScript errors, test failures, lint issues +2. **Deployment** — CDK deploy/synth failures, CloudFormation errors +3. **Authentication** — Cognito errors, token issues, 401 responses +4. **Task Submission** — 422 errors, validation failures, guardrail blocks +5. **Task Execution** — Preflight failures, agent failures, timeouts +6. **Local Agent Testing** — Docker issues, run.sh problems + +## Build/Compilation Issues + +```bash +export MISE_EXPERIMENTAL=1 +mise run //cdk:compile 2>&1 | tail -50 # TypeScript errors +mise run //cdk:test 2>&1 | tail -50 # Test failures +``` + +**Common causes:** +- Missing `mise run install` after pulling changes +- `yarn: command not found` — Run `corepack enable && corepack prepare yarn@1.22.22 --activate` +- Type mismatches after editing `cdk/src/handlers/shared/types.ts` without updating `cli/src/types.ts` + +## Deployment Issues + +```bash +# Check CloudFormation events for the failed stack +aws cloudformation describe-stack-events --stack-name backgroundagent-dev \ + --query 'StackEvents[?ResourceStatus==`CREATE_FAILED` || ResourceStatus==`UPDATE_FAILED`].[LogicalResourceId,ResourceStatusReason]' \ + --output table +``` + +**Common causes:** +- Docker not running — Required for CDK asset bundling +- Missing CDK bootstrap — Run `mise run //cdk:bootstrap` +- IAM permission issues — Check `aws sts get-caller-identity` +- Region mismatch — Ensure consistent region across all commands + +## Authentication Issues + +```bash +# Verify credentials +aws sts get-caller-identity + +# Check Cognito user exists +aws cognito-idp admin-get-user \ + --user-pool-id $USER_POOL_ID \ + --username user@example.com +``` + +**Common causes:** +- "App client does not exist" — Region mismatch between CLI config and stack deployment +- Token expired — Re-authenticate with `bgagent login` +- 401 on API calls — Token not included or malformed in Authorization header +- User not created — Self-signup is disabled; admin must create users + +## Task Submission Issues (422 / 400) + +**"Repository not onboarded" (422):** +- The repo needs a Blueprint construct. Use the `onboard-repo` skill. + +**"GUARDRAIL_BLOCKED" (400):** +- Task description triggered Bedrock Guardrails content screening +- Review and rephrase the task description to remove potentially flagged content + +**Validation errors:** +- Check required fields: `repo` is required, plus at least one of `issue_number`, `task_description`, `pr_number` +- `max_turns` range: 1-500 +- `max_budget_usd` range: $0.01-$100 + +## Task Execution Issues + +```bash +# Check task events for details +node lib/bin/bgagent.js events --output json +``` + +**`preflight_failed`:** +- GitHub PAT lacks permissions for the repo +- Repository doesn't exist or is private without proper token scope +- Check event `reason` and `detail` fields for specifics +- Verify PAT: fine-grained token must include the target repository with Contents (read/write), Pull Requests (read/write), Issues (read) + +**`task_failed`:** +- Agent encountered an error during execution +- Check CloudWatch logs for the session +- Common: repo build/test commands not documented in CLAUDE.md + +**`task_timed_out`:** +- 9-hour maximum exceeded +- Consider reducing scope or increasing `max_turns` for complex tasks +- Check if the agent is stuck in a loop (review logs) + +**Concurrency limit:** +- Default: 3 concurrent tasks per user +- Wait for running tasks to complete or cancel them + +## Local Agent Testing Issues + +```bash +# Verify Docker is running +docker info + +# Test locally with dry run +DRY_RUN=1 ./agent/run.sh "owner/repo" "Test task" +``` + +**Common causes:** +- Missing environment variables: `GITHUB_TOKEN`, `AWS_REGION` +- Docker not running or insufficient resources (needs 2 vCPU, 8 GB RAM) +- Missing AWS credentials for Bedrock access + +## Diagnostic Commands Quick Reference + +```bash +# Stack status +aws cloudformation describe-stacks --stack-name backgroundagent-dev --query 'Stacks[0].StackStatus' + +# Stack outputs +aws cloudformation describe-stacks --stack-name backgroundagent-dev --query 'Stacks[0].Outputs' --output table + +# Task status +node lib/bin/bgagent.js status +node lib/bin/bgagent.js events --output json + +# List running tasks +node lib/bin/bgagent.js list --status RUNNING + +# Build health +mise run build +``` From 68dbf2894453adc8549cba3d1d24aa967d6ef644 Mon Sep 17 00:00:00 2001 From: Ray Smets Date: Mon, 13 Apr 2026 12:50:25 -0700 Subject: [PATCH 02/20] wip2 --- .../agents}/agent-debugger.md | 0 .../agents}/cdk-expert.md | 0 .../commands}/abca-status.md | 0 .../commands}/abca-submit.md | 0 .claude-plugin/hooks/hooks.json | 15 ++++ .../skills}/deploy/SKILL.md | 0 .../skills}/onboard-repo/SKILL.md | 0 .../skills}/setup/SKILL.md | 0 .../skills}/submit-task/SKILL.md | 0 .../skills}/troubleshoot/SKILL.md | 0 Plans/encapsulated-scribbling-sutherland.md | 70 +++++++++++++++ README.md | 85 ++++++++++++++----- hooks/hooks.json | 13 --- 13 files changed, 149 insertions(+), 34 deletions(-) rename {agents => .claude-plugin/agents}/agent-debugger.md (100%) rename {agents => .claude-plugin/agents}/cdk-expert.md (100%) rename {commands => .claude-plugin/commands}/abca-status.md (100%) rename {commands => .claude-plugin/commands}/abca-submit.md (100%) create mode 100644 .claude-plugin/hooks/hooks.json rename {skills => .claude-plugin/skills}/deploy/SKILL.md (100%) rename {skills => .claude-plugin/skills}/onboard-repo/SKILL.md (100%) rename {skills => .claude-plugin/skills}/setup/SKILL.md (100%) rename {skills => .claude-plugin/skills}/submit-task/SKILL.md (100%) rename {skills => .claude-plugin/skills}/troubleshoot/SKILL.md (100%) create mode 100644 Plans/encapsulated-scribbling-sutherland.md delete mode 100644 hooks/hooks.json diff --git a/agents/agent-debugger.md b/.claude-plugin/agents/agent-debugger.md similarity index 100% rename from agents/agent-debugger.md rename to .claude-plugin/agents/agent-debugger.md diff --git a/agents/cdk-expert.md b/.claude-plugin/agents/cdk-expert.md similarity index 100% rename from agents/cdk-expert.md rename to .claude-plugin/agents/cdk-expert.md diff --git a/commands/abca-status.md b/.claude-plugin/commands/abca-status.md similarity index 100% rename from commands/abca-status.md rename to .claude-plugin/commands/abca-status.md diff --git a/commands/abca-submit.md b/.claude-plugin/commands/abca-submit.md similarity index 100% rename from commands/abca-submit.md rename to .claude-plugin/commands/abca-submit.md diff --git a/.claude-plugin/hooks/hooks.json b/.claude-plugin/hooks/hooks.json new file mode 100644 index 00000000..5f3aac2d --- /dev/null +++ b/.claude-plugin/hooks/hooks.json @@ -0,0 +1,15 @@ +{ + "hooks": { + "SessionStart": [ + { + "matcher": "", + "hooks": [ + { + "type": "prompt", + "prompt": "You are working in the ABCA (Autonomous Background Coding Agents on AWS) repository — a self-hosted platform for background coding agents.\n\nKey directories: cdk/src/ (CDK infra), agent/src/ (Python agent), cli/src/ (bgagent CLI), docs/ (documentation).\n\nEssential commands (require MISE_EXPERIMENTAL=1): mise run install, mise run build, mise //cdk:compile, mise //cdk:test, mise //cdk:deploy.\n\nCritical: types in cdk/src/handlers/shared/types.ts must stay in sync with cli/src/types.ts. Don't edit docs/src/content/docs/ directly — it's generated.\n\nTask types: new_task (create PR), pr_iteration (update PR), pr_review (review PR).\n\nAvailable plugin skills: /setup, /deploy, /onboard-repo, /submit-task, /troubleshoot\nAvailable commands: /abca-status, /abca-submit\nAvailable agents: cdk-expert, agent-debugger\n\nDocs: https://aws-samples.github.io/sample-autonomous-cloud-coding-agents/" + } + ] + } + ] + } +} diff --git a/skills/deploy/SKILL.md b/.claude-plugin/skills/deploy/SKILL.md similarity index 100% rename from skills/deploy/SKILL.md rename to .claude-plugin/skills/deploy/SKILL.md diff --git a/skills/onboard-repo/SKILL.md b/.claude-plugin/skills/onboard-repo/SKILL.md similarity index 100% rename from skills/onboard-repo/SKILL.md rename to .claude-plugin/skills/onboard-repo/SKILL.md diff --git a/skills/setup/SKILL.md b/.claude-plugin/skills/setup/SKILL.md similarity index 100% rename from skills/setup/SKILL.md rename to .claude-plugin/skills/setup/SKILL.md diff --git a/skills/submit-task/SKILL.md b/.claude-plugin/skills/submit-task/SKILL.md similarity index 100% rename from skills/submit-task/SKILL.md rename to .claude-plugin/skills/submit-task/SKILL.md diff --git a/skills/troubleshoot/SKILL.md b/.claude-plugin/skills/troubleshoot/SKILL.md similarity index 100% rename from skills/troubleshoot/SKILL.md rename to .claude-plugin/skills/troubleshoot/SKILL.md diff --git a/Plans/encapsulated-scribbling-sutherland.md b/Plans/encapsulated-scribbling-sutherland.md new file mode 100644 index 00000000..f1e35189 --- /dev/null +++ b/Plans/encapsulated-scribbling-sutherland.md @@ -0,0 +1,70 @@ +# Plan: Bundle Local Plugin Into a Single Directory + +## Context + +The local plugin for this project isn't showing up in Claude Code's `/plugin` list. Two issues: +1. Plugin components (`skills/`, `agents/`, `commands/`, `hooks/`) are scattered at the **project root**, separate from the manifest at `.claude-plugin/plugin.json` +2. The plugin isn't registered in `.claude/settings.json` under `enabledPlugins` + +The user wants everything consolidated into one directory. + +## Approach + +Move all plugin component directories into `.claude-plugin/` alongside `plugin.json`, then register the plugin in settings. + +### Step 1: Move component directories into `.claude-plugin/` + +Move these from project root into `.claude-plugin/`: +- `skills/` → `.claude-plugin/skills/` +- `agents/` → `.claude-plugin/agents/` +- `commands/` → `.claude-plugin/commands/` +- `hooks/` → `.claude-plugin/hooks/` + +Resulting structure: +``` +.claude-plugin/ +├── plugin.json +├── skills/ +│ ├── setup/SKILL.md +│ ├── deploy/SKILL.md +│ ├── onboard-repo/SKILL.md +│ ├── submit-task/SKILL.md +│ └── troubleshoot/SKILL.md +├── agents/ +│ ├── agent-debugger.md +│ └── cdk-expert.md +├── commands/ +│ ├── abca-status.md +│ └── abca-submit.md +└── hooks/ + └── hooks.json +``` + +### Step 2: Register plugin in `.claude/settings.json` + +Add `"abca-getting-started@local": true` to `enabledPlugins`: + +```json +{ + "enabledPlugins": { + "pyright-lsp@claude-plugins-official": true, + "code-review@claude-plugins-official": true, + "pr-review-toolkit@claude-plugins-official": true, + "abca-getting-started@local": true + } +} +``` + +### Step 3: Update README.md if it references old paths + +Check if the README references the old root-level paths and update accordingly. + +## Files to modify +- `.claude/settings.json` — add plugin registration +- `skills/`, `agents/`, `commands/`, `hooks/` — move into `.claude-plugin/` +- `README.md` — update paths if needed + +## Verification +1. Restart Claude Code in the project directory +2. Run `/plugin` — the `abca-getting-started` plugin should appear under Project plugins +3. Test a skill trigger (e.g., mention "setup" or "deploy") to confirm components load diff --git a/README.md b/README.md index b01d414b..58c7c544 100644 --- a/README.md +++ b/README.md @@ -71,37 +71,80 @@ See the full [ROADMAP](./docs/guides/ROADMAP.md) for details on each iteration. ### Claude Code plugin (recommended) -This repository ships a [Claude Code plugin](https://docs.anthropic.com/en/docs/claude-code/plugins) that provides guided workflows for setup, deployment, task submission, and troubleshooting. When you open this project in Claude Code, the plugin is auto-discovered from the `.claude-plugin/` directory. +This repository ships a [Claude Code plugin](https://docs.anthropic.com/en/docs/claude-code/plugins) that provides guided workflows for setup, deployment, task submission, and troubleshooting. -**Using the plugin:** +#### Installing the plugin -The plugin is automatically available when you clone this repo and open it in Claude Code. No manual installation needed — Claude Code discovers the `.claude-plugin/plugin.json` at the project root. +```bash +git clone https://github.com/aws-samples/sample-autonomous-cloud-coding-agents.git +cd sample-autonomous-cloud-coding-agents +claude --plugin-dir .claude-plugin +``` + +The `--plugin-dir` flag tells Claude Code to load the local plugin from the `.claude-plugin/` directory. The plugin's skills, commands, agents, and hooks will be available immediately. + +> **Tip:** If you use Claude Code via VS Code or JetBrains, you can add `--plugin-dir .claude-plugin` to the extension's CLI arguments setting. + +#### What the plugin provides + +**Skills** (guided multi-step workflows — Claude activates these automatically based on your request): + +| Skill | Triggers on | What it does | +|-------|------------|--------------| +| `setup` | "get started", "install", "first time setup" | Full guided setup: prerequisites, toolchain, deploy, smoke test | +| `deploy` | "deploy", "cdk diff", "destroy" | Deploy, diff, or destroy the CDK stack with pre-checks | +| `onboard-repo` | "add a repo", "onboard", 422 errors | Add a new GitHub repository via Blueprint construct | +| `submit-task` | "submit task", "run agent", "review PR" | Submit a coding task with prompt quality coaching | +| `troubleshoot` | "debug", "error", "not working", "failed" | Diagnose deployment, auth, or task execution issues | -| Component | What it does | -|-----------|-------------| -| `/setup` | Guided first-time setup: prerequisites, toolchain, deploy, smoke test | -| `/deploy` | Deploy, diff, or destroy the CDK stack with pre-checks | -| `/onboard-repo` | Add a new GitHub repository via Blueprint construct | -| `/submit-task` | Submit a coding task with prompt quality coaching | -| `/troubleshoot` | Diagnose deployment, auth, or task execution issues | -| `/abca-status` | Quick platform health check | -| `/abca-submit` | Shortcut for task submission | +**Commands** (slash commands for quick actions): -Specialized agents (`cdk-expert`, `agent-debugger`) are also available for CDK development and task failure investigation. +| Command | What it does | +|---------|-------------| +| `/abca-status` | Quick platform health check: stack status, running tasks, build health | +| `/abca-submit [repo] [description]` | Shortcut for task submission with auto-detected task type | -**For local plugin development:** +**Agents** (specialized subagents, spawned automatically or via the Agent tool): -If you're modifying the plugin itself, the component files live at the project root: +| Agent | When it's used | +|-------|---------------| +| `cdk-expert` | CDK architecture, construct design, handler implementation, stack modifications | +| `agent-debugger` | Task failure investigation, CloudWatch log analysis, agent runtime debugging | + +**Hook** (runs automatically): + +A `SessionStart` hook injects ABCA project context (key directories, commands, conventions) into every Claude Code session. + +#### Local plugin development + +If you're modifying the plugin itself, here's the file layout: ``` -.claude-plugin/plugin.json # Plugin manifest -skills/ # Guided workflow skills (SKILL.md in subdirs) -agents/ # Specialized subagent definitions -commands/ # Slash commands -hooks/hooks.json # SessionStart hook for project context +.claude-plugin/ + plugin.json # Plugin manifest (name, version, description) + skills/ + setup/SKILL.md # First-time setup workflow + deploy/SKILL.md # CDK deployment workflow + onboard-repo/SKILL.md # Repository onboarding workflow + submit-task/SKILL.md # Task submission with prompt coaching + troubleshoot/SKILL.md # Diagnostic workflow + agents/ + cdk-expert.md # CDK infrastructure specialist + agent-debugger.md # Task failure debugger + commands/ + abca-status.md # /abca-status command + abca-submit.md # /abca-submit command + hooks/ + hooks.json # SessionStart hook configuration ``` -After editing plugin files, run `/reload-plugins` in Claude Code to pick up changes. No restart required. +**Key conventions:** +- All plugin components live inside `.claude-plugin/` alongside the manifest +- Skills live in subdirectories with a `SKILL.md` file (not flat `.md` files) +- Agents and commands are flat `.md` files with YAML frontmatter +- Hooks use JSON configuration in `hooks/hooks.json` + +**After editing plugin files**, restart Claude Code with `claude --plugin-dir .claude-plugin` to pick up changes. ### Manual installation and deployment diff --git a/hooks/hooks.json b/hooks/hooks.json deleted file mode 100644 index 5d9311d7..00000000 --- a/hooks/hooks.json +++ /dev/null @@ -1,13 +0,0 @@ -{ - "SessionStart": [ - { - "matcher": "", - "hooks": [ - { - "type": "prompt", - "prompt": "You are working in the ABCA (Autonomous Background Coding Agents on AWS) repository — a self-hosted platform for background coding agents.\n\nKey directories: cdk/src/ (CDK infra), agent/src/ (Python agent), cli/src/ (bgagent CLI), docs/ (documentation).\n\nEssential commands (require MISE_EXPERIMENTAL=1): mise run install, mise run build, mise //cdk:compile, mise //cdk:test, mise //cdk:deploy.\n\nCritical: types in cdk/src/handlers/shared/types.ts must stay in sync with cli/src/types.ts. Don't edit docs/src/content/docs/ directly — it's generated.\n\nTask types: new_task (create PR), pr_iteration (update PR), pr_review (review PR).\n\nAvailable plugin skills: /setup, /deploy, /onboard-repo, /submit-task, /troubleshoot\nAvailable commands: /abca-status, /abca-submit\nAvailable agents: cdk-expert, agent-debugger\n\nDocs: https://aws-samples.github.io/sample-autonomous-cloud-coding-agents/" - } - ] - } - ] -} From 3c2ad3a7b38b8bb28e4d14c727fb659e9b290329 Mon Sep 17 00:00:00 2001 From: bgagent Date: Mon, 13 Apr 2026 15:53:03 -0700 Subject: [PATCH 03/20] name --- README.md | 28 +++++++--------- .../agents/agent-debugger.md | 31 +++++++++++++---- .../agents/cdk-expert.md | 33 ++++++++++++++----- .../hooks/hooks.json | 2 +- {.claude-plugin => abca-plugin}/plugin.json | 0 .../skills/abca-status/SKILL.md | 2 +- .../skills/abca-submit/SKILL.md | 14 +++----- .../skills/deploy/SKILL.md | 0 .../skills/onboard-repo/SKILL.md | 0 .../skills/setup/SKILL.md | 0 .../skills/submit-task/SKILL.md | 0 .../skills/troubleshoot/SKILL.md | 0 12 files changed, 67 insertions(+), 43 deletions(-) rename {.claude-plugin => abca-plugin}/agents/agent-debugger.md (71%) rename {.claude-plugin => abca-plugin}/agents/cdk-expert.md (67%) rename {.claude-plugin => abca-plugin}/hooks/hooks.json (79%) rename {.claude-plugin => abca-plugin}/plugin.json (100%) rename .claude-plugin/commands/abca-status.md => abca-plugin/skills/abca-status/SKILL.md (90%) rename .claude-plugin/commands/abca-submit.md => abca-plugin/skills/abca-submit/SKILL.md (67%) rename {.claude-plugin => abca-plugin}/skills/deploy/SKILL.md (100%) rename {.claude-plugin => abca-plugin}/skills/onboard-repo/SKILL.md (100%) rename {.claude-plugin => abca-plugin}/skills/setup/SKILL.md (100%) rename {.claude-plugin => abca-plugin}/skills/submit-task/SKILL.md (100%) rename {.claude-plugin => abca-plugin}/skills/troubleshoot/SKILL.md (100%) diff --git a/README.md b/README.md index 58c7c544..6d917b87 100644 --- a/README.md +++ b/README.md @@ -78,12 +78,12 @@ This repository ships a [Claude Code plugin](https://docs.anthropic.com/en/docs/ ```bash git clone https://github.com/aws-samples/sample-autonomous-cloud-coding-agents.git cd sample-autonomous-cloud-coding-agents -claude --plugin-dir .claude-plugin +claude --plugin-dir abca-plugin ``` -The `--plugin-dir` flag tells Claude Code to load the local plugin from the `.claude-plugin/` directory. The plugin's skills, commands, agents, and hooks will be available immediately. +The `--plugin-dir` flag tells Claude Code to load the local plugin from the `abca-plugin/` directory. The plugin's skills, commands, agents, and hooks will be available immediately. -> **Tip:** If you use Claude Code via VS Code or JetBrains, you can add `--plugin-dir .claude-plugin` to the extension's CLI arguments setting. +> **Tip:** If you use Claude Code via VS Code or JetBrains, you can add `--plugin-dir abca-plugin` to the extension's CLI arguments setting. #### What the plugin provides @@ -96,13 +96,8 @@ The `--plugin-dir` flag tells Claude Code to load the local plugin from the `.cl | `onboard-repo` | "add a repo", "onboard", 422 errors | Add a new GitHub repository via Blueprint construct | | `submit-task` | "submit task", "run agent", "review PR" | Submit a coding task with prompt quality coaching | | `troubleshoot` | "debug", "error", "not working", "failed" | Diagnose deployment, auth, or task execution issues | - -**Commands** (slash commands for quick actions): - -| Command | What it does | -|---------|-------------| -| `/abca-status` | Quick platform health check: stack status, running tasks, build health | -| `/abca-submit [repo] [description]` | Shortcut for task submission with auto-detected task type | +| `abca-status` | "status", "health check", "is ABCA running" | Quick platform health check: stack status, running tasks, build health | +| `abca-submit` | "submit task", "quick submit" | Shortcut for task submission with auto-detected task type | **Agents** (specialized subagents, spawned automatically or via the Agent tool): @@ -120,7 +115,7 @@ A `SessionStart` hook injects ABCA project context (key directories, commands, c If you're modifying the plugin itself, here's the file layout: ``` -.claude-plugin/ +abca-plugin/ plugin.json # Plugin manifest (name, version, description) skills/ setup/SKILL.md # First-time setup workflow @@ -128,23 +123,22 @@ If you're modifying the plugin itself, here's the file layout: onboard-repo/SKILL.md # Repository onboarding workflow submit-task/SKILL.md # Task submission with prompt coaching troubleshoot/SKILL.md # Diagnostic workflow + abca-status/SKILL.md # Quick platform health check + abca-submit/SKILL.md # Quick task submission shortcut agents/ cdk-expert.md # CDK infrastructure specialist agent-debugger.md # Task failure debugger - commands/ - abca-status.md # /abca-status command - abca-submit.md # /abca-submit command hooks/ hooks.json # SessionStart hook configuration ``` **Key conventions:** -- All plugin components live inside `.claude-plugin/` alongside the manifest +- All plugin components live inside `abca-plugin/` alongside the manifest - Skills live in subdirectories with a `SKILL.md` file (not flat `.md` files) -- Agents and commands are flat `.md` files with YAML frontmatter +- Agents are flat `.md` files with YAML frontmatter - Hooks use JSON configuration in `hooks/hooks.json` -**After editing plugin files**, restart Claude Code with `claude --plugin-dir .claude-plugin` to pick up changes. +**After editing plugin files**, restart Claude Code with `claude --plugin-dir abca-plugin` to pick up changes. ### Manual installation and deployment diff --git a/.claude-plugin/agents/agent-debugger.md b/abca-plugin/agents/agent-debugger.md similarity index 71% rename from .claude-plugin/agents/agent-debugger.md rename to abca-plugin/agents/agent-debugger.md index 724ab757..2055abc6 100644 --- a/.claude-plugin/agents/agent-debugger.md +++ b/abca-plugin/agents/agent-debugger.md @@ -1,14 +1,33 @@ --- name: agent-debugger -description: >- +description: | Debugs ABCA agent runtime issues — task failures, preflight errors, agent execution problems, and log analysis. Use when investigating why a task failed, analyzing CloudWatch logs, or debugging the Python agent code. -tools: - - Read - - Grep - - Glob - - Bash + + + Context: User has a failed task and wants to know why + user: "My task failed, can you check what happened?" + assistant: "I'll use the agent-debugger to investigate the failure." + Task failure investigation triggers agent-debugger. + + + + Context: User sees a preflight error + user: "I'm getting GITHUB_UNREACHABLE errors on my tasks" + assistant: "I'll use the agent-debugger to diagnose the preflight failure." + Preflight error diagnosis triggers agent-debugger. + + + + Context: User wants to check CloudWatch logs for a task + user: "Can you check the logs for task abc-123?" + assistant: "I'll use the agent-debugger to analyze the CloudWatch logs." + Log analysis triggers agent-debugger. + +model: sonnet +color: red +tools: ["Read", "Grep", "Glob", "Bash"] --- You are a debugging specialist for the ABCA agent runtime. You diagnose task execution failures by analyzing logs, events, and agent code. diff --git a/.claude-plugin/agents/cdk-expert.md b/abca-plugin/agents/cdk-expert.md similarity index 67% rename from .claude-plugin/agents/cdk-expert.md rename to abca-plugin/agents/cdk-expert.md index a999533d..e420f4b4 100644 --- a/.claude-plugin/agents/cdk-expert.md +++ b/abca-plugin/agents/cdk-expert.md @@ -1,17 +1,34 @@ --- name: cdk-expert -description: >- +description: | AWS CDK and ABCA infrastructure expert. Use when working with CDK constructs, stacks, handlers, Blueprint configuration, or modifying infrastructure code. Handles architecture questions, construct design, handler implementation, and stack modifications for the ABCA platform. -tools: - - Read - - Grep - - Glob - - Bash - - Edit - - Write + + + Context: User wants to add a new CDK construct + user: "I need to add a new construct for the notification system" + assistant: "I'll use the cdk-expert to design and implement the construct." + CDK construct work triggers cdk-expert. + + + + Context: User wants to modify a Lambda handler + user: "The create-task handler needs a new validation check" + assistant: "I'll use the cdk-expert to implement the handler change." + Handler modification triggers cdk-expert. + + + + Context: User asks about ABCA infrastructure architecture + user: "How does the orchestrator interact with the compute environment?" + assistant: "I'll use the cdk-expert to explain the architecture." + Architecture questions trigger cdk-expert. + +model: sonnet +color: blue +tools: ["Read", "Grep", "Glob", "Bash", "Edit", "Write"] --- You are an expert AWS CDK developer specializing in the ABCA (Autonomous Background Coding Agents) platform. You have deep knowledge of CDK v2, TypeScript, and the ABCA architecture. diff --git a/.claude-plugin/hooks/hooks.json b/abca-plugin/hooks/hooks.json similarity index 79% rename from .claude-plugin/hooks/hooks.json rename to abca-plugin/hooks/hooks.json index 5f3aac2d..29f9c4b7 100644 --- a/.claude-plugin/hooks/hooks.json +++ b/abca-plugin/hooks/hooks.json @@ -6,7 +6,7 @@ "hooks": [ { "type": "prompt", - "prompt": "You are working in the ABCA (Autonomous Background Coding Agents on AWS) repository — a self-hosted platform for background coding agents.\n\nKey directories: cdk/src/ (CDK infra), agent/src/ (Python agent), cli/src/ (bgagent CLI), docs/ (documentation).\n\nEssential commands (require MISE_EXPERIMENTAL=1): mise run install, mise run build, mise //cdk:compile, mise //cdk:test, mise //cdk:deploy.\n\nCritical: types in cdk/src/handlers/shared/types.ts must stay in sync with cli/src/types.ts. Don't edit docs/src/content/docs/ directly — it's generated.\n\nTask types: new_task (create PR), pr_iteration (update PR), pr_review (review PR).\n\nAvailable plugin skills: /setup, /deploy, /onboard-repo, /submit-task, /troubleshoot\nAvailable commands: /abca-status, /abca-submit\nAvailable agents: cdk-expert, agent-debugger\n\nDocs: https://aws-samples.github.io/sample-autonomous-cloud-coding-agents/" + "prompt": "You are working in the ABCA (Autonomous Background Coding Agents on AWS) repository — a self-hosted platform for background coding agents.\n\nKey directories: cdk/src/ (CDK infra), agent/src/ (Python agent), cli/src/ (bgagent CLI), docs/ (documentation).\n\nEssential commands (require MISE_EXPERIMENTAL=1): mise run install, mise run build, mise //cdk:compile, mise //cdk:test, mise //cdk:deploy.\n\nCritical: types in cdk/src/handlers/shared/types.ts must stay in sync with cli/src/types.ts. Don't edit docs/src/content/docs/ directly — it's generated.\n\nTask types: new_task (create PR), pr_iteration (update PR), pr_review (review PR).\n\nAvailable plugin skills: /setup, /deploy, /onboard-repo, /submit-task, /troubleshoot, /abca-status, /abca-submit\nAvailable agents: cdk-expert, agent-debugger\n\nDocs: https://aws-samples.github.io/sample-autonomous-cloud-coding-agents/" } ] } diff --git a/.claude-plugin/plugin.json b/abca-plugin/plugin.json similarity index 100% rename from .claude-plugin/plugin.json rename to abca-plugin/plugin.json diff --git a/.claude-plugin/commands/abca-status.md b/abca-plugin/skills/abca-status/SKILL.md similarity index 90% rename from .claude-plugin/commands/abca-status.md rename to abca-plugin/skills/abca-status/SKILL.md index 8ea2727d..0a702c50 100644 --- a/.claude-plugin/commands/abca-status.md +++ b/abca-plugin/skills/abca-status/SKILL.md @@ -1,6 +1,6 @@ --- name: abca-status -description: Check ABCA platform status — stack health, running tasks, and recent task history +description: Check ABCA platform status — stack health, running tasks, and recent task history. Use when the user says "status", "health check", "is ABCA running", "check platform", or "what's the state". allowed-tools: - Bash - Read diff --git a/.claude-plugin/commands/abca-submit.md b/abca-plugin/skills/abca-submit/SKILL.md similarity index 67% rename from .claude-plugin/commands/abca-submit.md rename to abca-plugin/skills/abca-submit/SKILL.md index 8a58b741..4bd131f5 100644 --- a/.claude-plugin/commands/abca-submit.md +++ b/abca-plugin/skills/abca-submit/SKILL.md @@ -1,13 +1,7 @@ --- name: abca-submit -description: Quick task submission shortcut — submit a coding task with guided prompts -arguments: - - name: repo - description: "GitHub repository in owner/repo format" - required: false - - name: description - description: "Task description or issue number" - required: false +description: Quick task submission shortcut — submit a coding task with guided prompts. Use when the user says "submit task", "run agent on", "submit to ABCA", or "quick submit". +argument-hint: [description] allowed-tools: - Bash - Read @@ -19,8 +13,8 @@ Submit a task to ABCA quickly. If arguments are missing, ask the user. ## Collect Required Info -If `$ARGUMENTS.repo` is not provided, ask for the repository (owner/repo format). -If `$ARGUMENTS.description` is not provided, ask what the agent should do. +If the repository is not provided, ask for the repository (owner/repo format). +If the description is not provided, ask what the agent should do. ## Determine Task Type diff --git a/.claude-plugin/skills/deploy/SKILL.md b/abca-plugin/skills/deploy/SKILL.md similarity index 100% rename from .claude-plugin/skills/deploy/SKILL.md rename to abca-plugin/skills/deploy/SKILL.md diff --git a/.claude-plugin/skills/onboard-repo/SKILL.md b/abca-plugin/skills/onboard-repo/SKILL.md similarity index 100% rename from .claude-plugin/skills/onboard-repo/SKILL.md rename to abca-plugin/skills/onboard-repo/SKILL.md diff --git a/.claude-plugin/skills/setup/SKILL.md b/abca-plugin/skills/setup/SKILL.md similarity index 100% rename from .claude-plugin/skills/setup/SKILL.md rename to abca-plugin/skills/setup/SKILL.md diff --git a/.claude-plugin/skills/submit-task/SKILL.md b/abca-plugin/skills/submit-task/SKILL.md similarity index 100% rename from .claude-plugin/skills/submit-task/SKILL.md rename to abca-plugin/skills/submit-task/SKILL.md diff --git a/.claude-plugin/skills/troubleshoot/SKILL.md b/abca-plugin/skills/troubleshoot/SKILL.md similarity index 100% rename from .claude-plugin/skills/troubleshoot/SKILL.md rename to abca-plugin/skills/troubleshoot/SKILL.md From b2533baa9fee73a590c62925b019267f7f697470 Mon Sep 17 00:00:00 2001 From: bgagent Date: Mon, 13 Apr 2026 16:00:16 -0700 Subject: [PATCH 04/20] chore: gitignore Plans/ and remove from tracking Co-Authored-By: Claude Opus 4.6 (1M context) --- .gitignore | 1 + Plans/encapsulated-scribbling-sutherland.md | 70 --------------------- 2 files changed, 1 insertion(+), 70 deletions(-) delete mode 100644 Plans/encapsulated-scribbling-sutherland.md diff --git a/.gitignore b/.gitignore index 4c18cdf8..0317435f 100644 --- a/.gitignore +++ b/.gitignore @@ -54,3 +54,4 @@ junit.xml .parcel-cache/ !/.github/workflows/docs.yml local-docs/ +Plans/ diff --git a/Plans/encapsulated-scribbling-sutherland.md b/Plans/encapsulated-scribbling-sutherland.md deleted file mode 100644 index f1e35189..00000000 --- a/Plans/encapsulated-scribbling-sutherland.md +++ /dev/null @@ -1,70 +0,0 @@ -# Plan: Bundle Local Plugin Into a Single Directory - -## Context - -The local plugin for this project isn't showing up in Claude Code's `/plugin` list. Two issues: -1. Plugin components (`skills/`, `agents/`, `commands/`, `hooks/`) are scattered at the **project root**, separate from the manifest at `.claude-plugin/plugin.json` -2. The plugin isn't registered in `.claude/settings.json` under `enabledPlugins` - -The user wants everything consolidated into one directory. - -## Approach - -Move all plugin component directories into `.claude-plugin/` alongside `plugin.json`, then register the plugin in settings. - -### Step 1: Move component directories into `.claude-plugin/` - -Move these from project root into `.claude-plugin/`: -- `skills/` → `.claude-plugin/skills/` -- `agents/` → `.claude-plugin/agents/` -- `commands/` → `.claude-plugin/commands/` -- `hooks/` → `.claude-plugin/hooks/` - -Resulting structure: -``` -.claude-plugin/ -├── plugin.json -├── skills/ -│ ├── setup/SKILL.md -│ ├── deploy/SKILL.md -│ ├── onboard-repo/SKILL.md -│ ├── submit-task/SKILL.md -│ └── troubleshoot/SKILL.md -├── agents/ -│ ├── agent-debugger.md -│ └── cdk-expert.md -├── commands/ -│ ├── abca-status.md -│ └── abca-submit.md -└── hooks/ - └── hooks.json -``` - -### Step 2: Register plugin in `.claude/settings.json` - -Add `"abca-getting-started@local": true` to `enabledPlugins`: - -```json -{ - "enabledPlugins": { - "pyright-lsp@claude-plugins-official": true, - "code-review@claude-plugins-official": true, - "pr-review-toolkit@claude-plugins-official": true, - "abca-getting-started@local": true - } -} -``` - -### Step 3: Update README.md if it references old paths - -Check if the README references the old root-level paths and update accordingly. - -## Files to modify -- `.claude/settings.json` — add plugin registration -- `skills/`, `agents/`, `commands/`, `hooks/` — move into `.claude-plugin/` -- `README.md` — update paths if needed - -## Verification -1. Restart Claude Code in the project directory -2. Run `/plugin` — the `abca-getting-started` plugin should appear under Project plugins -3. Test a skill trigger (e.g., mention "setup" or "deploy") to confirm components load From bab8794b4e2c06fd567ea2b17ea4e3228e7f6ab7 Mon Sep 17 00:00:00 2001 From: bgagent Date: Tue, 14 Apr 2026 14:03:15 -0700 Subject: [PATCH 05/20] test(plugin): add testing strategy and fix agent-debugger path bug MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Run 4-layer validation (structural, agent config, content integrity, hooks) across all plugin components. Fix incorrect path reference in agent-debugger.md: agent/prompts/ → agent/src/prompts/. Co-Authored-By: Claude Opus 4.6 (1M context) --- abca-plugin/TESTING.md | 175 +++++++++++++++++++++++++++ abca-plugin/agents/agent-debugger.md | 4 +- 2 files changed, 177 insertions(+), 2 deletions(-) create mode 100644 abca-plugin/TESTING.md diff --git a/abca-plugin/TESTING.md b/abca-plugin/TESTING.md new file mode 100644 index 00000000..9d269c21 --- /dev/null +++ b/abca-plugin/TESTING.md @@ -0,0 +1,175 @@ +# ABCA Plugin — Testing Strategy & Results + +> Testing report for the Claude Code plugin at `abca-plugin/`. +> Generated: 2026-04-14 + +## Testing Strategy + +Since this plugin is a **markdown/config-based Claude Code plugin** (no executable code — only SKILL.md files, agent profiles, hooks.json, and plugin.json), traditional unit tests don't apply. Instead, we use a **multi-layer validation approach**: + +### Layer 1: Structural Validation +Verify the plugin manifest, file organization, and component discovery. + +| Check | Description | +|-------|-------------| +| Manifest validity | `plugin.json` has required fields (`name`, `version`, `description`, `author`) | +| Component discovery | All agents, skills, and hooks are in correct directories | +| No orphaned files | Every file belongs to a recognized plugin component | +| Valid JSON | `plugin.json` and `hooks.json` parse without errors | +| Valid YAML frontmatter | All `.md` components have parseable frontmatter | + +### Layer 2: Agent Configuration Validation +Verify agent definitions are well-formed and reference valid resources. + +| Check | Description | +|-------|-------------| +| Required frontmatter | Each agent has `model`, `description`, `tools` | +| Valid model values | Model is `opus`, `sonnet`, or `haiku` | +| Valid tool names | All tools are recognized Claude Code tools | +| File path accuracy | Paths in system prompts exist in the repo | +| Capability alignment | Examples match declared tools (e.g., debug agent has no Edit/Write) | + +### Layer 3: Content Integrity Verification +Verify that all commands, paths, and cross-references in skill content are accurate. + +| Check | Description | +|-------|-------------| +| File path references | All referenced repo paths exist | +| Mise task references | All `mise run` commands map to valid tasks | +| CLI command accuracy | All `bgagent` commands/flags match the actual CLI | +| Skill cross-references | Skills referencing other skills point to ones that exist | +| AWS CLI syntax | AWS CLI commands use valid subcommands | + +### Layer 4: Hook Validation +Verify hook configuration is correct and content is accurate. + +| Check | Description | +|-------|-------------| +| JSON structure | `hooks.json` has valid structure | +| Event names | Hook events are supported by Claude Code | +| Content accuracy | Skills and agents listed in hook prompt all exist | +| No sensitive data | No credentials or secrets in hook prompts | + +--- + +## Test Results + +### Layer 1: Structural Validation — PASS + +| Check | Result | Notes | +|-------|--------|-------| +| `plugin.json` valid JSON | PASS | All required fields present | +| `name` field | PASS | `abca-getting-started` — valid kebab-case | +| `version` field | PASS | `1.0.0` — valid semver | +| `description` field | PASS | Present and descriptive | +| `author` field | PASS | `aws-samples` | +| Agent files discovered | PASS | 2 agents in `agents/` | +| Skill files discovered | PASS | 7 skills in `skills/*/SKILL.md` | +| Hook file discovered | PASS | `hooks/hooks.json` present | +| No orphaned files | PASS | Every file is part of a component | + +### Layer 2: Agent Configuration — PASS (1 issue found) + +**cdk-expert.md** — All checks PASS + +| Check | Result | +|-------|--------| +| Has `model`, `description`, `tools` | PASS | +| Model `sonnet` is valid | PASS | +| Tools `[Read, Grep, Glob, Bash, Edit, Write]` valid | PASS | +| File paths exist | PASS | +| 3 `` blocks present | PASS | + +**agent-debugger.md** — 1 FAIL + +| Check | Result | Notes | +|-------|--------|-------| +| Has `model`, `description`, `tools` | PASS | | +| Model `sonnet` is valid | PASS | | +| Tools `[Read, Grep, Glob, Bash]` valid | PASS | | +| No Edit/Write (read-only debugger) | PASS | | +| 3 `` blocks present | PASS | | +| File path `agent/prompts/` exists | **FAIL** | Should be `agent/src/prompts/` | + +### Layer 3: Content Integrity — PASS + +**File Paths (6/6 PASS)** + +| Path | Referenced In | Result | +|------|--------------|--------| +| `cli/lib/bin/bgagent.js` | abca-status, abca-submit, submit-task, troubleshoot | PASS | +| `cdk/src/stacks/agent.ts` | onboard-repo | PASS | +| `cdk/src/handlers/shared/types.ts` | troubleshoot | PASS | +| `cli/src/types.ts` | troubleshoot | PASS | +| `agent/run.sh` | troubleshoot | PASS | +| `cdk/cdk.out/` | deploy | PASS | + +**Mise Tasks (10/10 PASS)** + +| Command | Result | +|---------|--------| +| `mise run build` | PASS | +| `mise run install` | PASS | +| `mise run //cdk:compile` | PASS | +| `mise run //cdk:test` | PASS | +| `mise run //cdk:deploy` | PASS | +| `mise run //cdk:destroy` | PASS | +| `mise run //cdk:diff` | PASS | +| `mise run //cdk:synth` | PASS | +| `mise run //cdk:bootstrap` | PASS | +| `mise run //cli:build` | PASS | + +**CLI Commands (6/6 PASS)** + +| Command | Flags Verified | Result | +|---------|---------------|--------| +| `bgagent submit` | `--repo, --issue, --task, --pr, --review-pr, --max-turns, --max-budget, --wait, --idempotency-key, --output` | PASS | +| `bgagent list` | `--status, --limit, --output` | PASS | +| `bgagent status` | `` | PASS | +| `bgagent events` | `, --output` | PASS | +| `bgagent configure` | `--api-url, --region, --user-pool-id, --client-id` | PASS | +| `bgagent login` | `--username` | PASS | + +**Skill Cross-References (3/3 PASS)** + +| From | References | Result | +|------|-----------|--------| +| abca-status | setup | PASS | +| setup | onboard-repo | PASS | +| troubleshoot | onboard-repo | PASS | + +### Layer 4: Hook Validation — PASS + +| Check | Result | Notes | +|-------|--------|-------| +| Valid JSON structure | PASS | | +| Event: `SessionStart` | PASS | Supported in Claude Code | +| Hook type: `prompt` | PASS | Valid hook type | +| Skills listed match actual | PASS | All 7 skills referenced exist | +| Agents listed match actual | PASS | Both agents exist | +| No sensitive data | PASS | Context only, no secrets | + +--- + +## Issues Found + +### Issue 1: Incorrect path in agent-debugger.md (Bug) + +**Severity:** Medium +**Location:** `abca-plugin/agents/agent-debugger.md` +**Description:** The system prompt references `agent/prompts/` but the correct path is `agent/src/prompts/`. +**Impact:** The agent-debugger may fail to locate prompt files when debugging agent issues. +**Fix:** Update path references from `agent/prompts/` to `agent/src/prompts/`. + +--- + +## Overall Result + +| Layer | Result | Issues | +|-------|--------|--------| +| 1. Structural Validation | PASS | 0 | +| 2. Agent Configuration | PASS* | 1 (incorrect path) | +| 3. Content Integrity | PASS | 0 | +| 4. Hook Validation | PASS | 0 | + +**Overall: PASS with 1 medium-severity bug identified and fixed.** diff --git a/abca-plugin/agents/agent-debugger.md b/abca-plugin/agents/agent-debugger.md index 2055abc6..3c7ca07b 100644 --- a/abca-plugin/agents/agent-debugger.md +++ b/abca-plugin/agents/agent-debugger.md @@ -36,7 +36,7 @@ You are a debugging specialist for the ABCA agent runtime. You diagnose task exe - Task lifecycle: SUBMITTED -> HYDRATING -> RUNNING -> COMPLETED/FAILED - Agent runtime: Python code in `agent/src/` (pipeline.py, runner.py, config.py, hooks.py, policy.py) -- System prompts: `agent/prompts/` with base template and per-task-type variants +- System prompts: `agent/src/prompts/` with base template and per-task-type variants - Orchestrator: Lambda durable functions managing task state - Preflight checks: GitHub API validation before compute allocation @@ -65,7 +65,7 @@ You are a debugging specialist for the ABCA agent runtime. You diagnose task exe - `agent/src/runner.py` — Task runner loop - `agent/src/config.py` — Configuration loading - `agent/src/hooks.py` — Lifecycle hooks - - `agent/prompts/` — System prompt templates + - `agent/src/prompts/` — System prompt templates 5. **For local reproduction**, use: ```bash From 31bc2cff7e96ae92914c75edcbbf32c161a03fcb Mon Sep 17 00:00:00 2001 From: bgagent Date: Tue, 14 Apr 2026 14:07:05 -0700 Subject: [PATCH 06/20] docs(plugin): add README with testing strategy, slim TESTING.md to results Co-Authored-By: Claude Opus 4.6 (1M context) --- abca-plugin/README.md | 113 +++++++++++++++++++++++++++++++++++++++++ abca-plugin/TESTING.md | 57 ++------------------- 2 files changed, 118 insertions(+), 52 deletions(-) create mode 100644 abca-plugin/README.md diff --git a/abca-plugin/README.md b/abca-plugin/README.md new file mode 100644 index 00000000..80c4fef1 --- /dev/null +++ b/abca-plugin/README.md @@ -0,0 +1,113 @@ +# ABCA Plugin for Claude Code + +A Claude Code plugin that provides guided workflows for setting up, deploying, operating, and troubleshooting the ABCA (Autonomous Background Coding Agents on AWS) platform. + +## Installation + +```bash +claude --plugin-dir abca-plugin +``` + +Or add to your project's `.claude/settings.json`: + +```json +{ + "plugins": ["./abca-plugin"] +} +``` + +## What's Included + +### Skills (slash commands) + +| Skill | Trigger | Description | +|-------|---------|-------------| +| `/setup` | First-time setup, prerequisites | Walk through prerequisites, toolchain, and first deployment | +| `/deploy` | Deploy, diff, destroy | Deploy, diff, or destroy the CDK stack | +| `/onboard-repo` | Add a repository | Onboard a GitHub repo via Blueprint CDK construct | +| `/submit-task` | Submit a coding task | Submit tasks with prompt quality guidance and cost controls | +| `/troubleshoot` | Debug, errors, failures | Diagnose build, deployment, auth, and task execution issues | +| `/abca-status` | Status, health check | Check stack health, running tasks, and recent history | +| `/abca-submit` | Quick submit | Shortcut for rapid task submission | + +### Agents + +| Agent | Model | Description | +|-------|-------|-------------| +| `cdk-expert` | Sonnet | AWS CDK infrastructure expert for construct design, handler implementation, and stack modifications | +| `agent-debugger` | Sonnet | Read-only debugging specialist for task failures, preflight errors, and CloudWatch log analysis | + +### Hooks + +- **SessionStart** — Injects ABCA project context (directory structure, key commands, task types, available skills/agents) into every Claude Code session. + +## Plugin Structure + +``` +abca-plugin/ + plugin.json # Plugin manifest + agents/ + cdk-expert.md # CDK infrastructure agent + agent-debugger.md # Runtime debugging agent + hooks/ + hooks.json # SessionStart context injection + skills/ + setup/SKILL.md # First-time setup workflow + deploy/SKILL.md # CDK deployment management + onboard-repo/SKILL.md # Repository onboarding + submit-task/SKILL.md # Task submission workflow + troubleshoot/SKILL.md # Troubleshooting guide + abca-status/SKILL.md # Platform status checks + abca-submit/SKILL.md # Quick task submission +``` + +## Testing + +This plugin is markdown and configuration only (no executable code), so traditional unit tests don't apply. Instead, a **4-layer validation strategy** verifies correctness: + +| Layer | What it checks | +|-------|---------------| +| **1. Structural** | `plugin.json` fields, file discovery, JSON/YAML validity, no orphaned files | +| **2. Agent Config** | Frontmatter fields (`model`, `tools`, `description`), valid tool names, file path accuracy, capability alignment with examples | +| **3. Content Integrity** | All repo paths exist, all `mise run` commands are valid tasks, all `bgagent` CLI flags match actual help output, skill cross-references resolve, AWS CLI syntax is correct | +| **4. Hooks** | `hooks.json` structure, supported event names, skills/agents listed in hook content all exist, no sensitive data | + +### Running the tests + +From the repo root with Claude Code: + +``` +claude --plugin-dir abca-plugin +``` + +Then ask Claude to validate the plugin: + +``` +Validate the abca-plugin using the plugin-validator agent, then verify +all command references and file paths in the skills are accurate. +``` + +Or run the checks manually: + +```bash +# Layer 1: Structural — valid JSON +python3 -c "import json; json.load(open('abca-plugin/plugin.json')); print('plugin.json OK')" +python3 -c "import json; json.load(open('abca-plugin/hooks/hooks.json')); print('hooks.json OK')" + +# Layer 3: Content — mise tasks exist +MISE_EXPERIMENTAL=1 mise tasks --all 2>/dev/null | grep -E '(build|install|compile|test|deploy|destroy|diff|synth|bootstrap)' + +# Layer 3: Content — CLI flags match +cd cli && node lib/bin/bgagent.js submit --help && node lib/bin/bgagent.js list --help +``` + +Full test results are documented in [`TESTING.md`](./TESTING.md). + +## Development + +To modify the plugin: + +1. Edit the relevant `.md` file under `skills/`, `agents/`, or `hooks/` +2. Re-validate using the testing strategy above +3. Ensure any new file paths or commands you reference actually exist in the repo +4. Keep the `SessionStart` hook prompt in sync if you add/remove/rename skills or agents diff --git a/abca-plugin/TESTING.md b/abca-plugin/TESTING.md index 9d269c21..5b8bc1c2 100644 --- a/abca-plugin/TESTING.md +++ b/abca-plugin/TESTING.md @@ -1,58 +1,11 @@ -# ABCA Plugin — Testing Strategy & Results +# ABCA Plugin — Test Results -> Testing report for the Claude Code plugin at `abca-plugin/`. +> Test report for the Claude Code plugin at `abca-plugin/`. > Generated: 2026-04-14 +> +> For the testing strategy and how to run these checks, see [`README.md`](./README.md#testing). -## Testing Strategy - -Since this plugin is a **markdown/config-based Claude Code plugin** (no executable code — only SKILL.md files, agent profiles, hooks.json, and plugin.json), traditional unit tests don't apply. Instead, we use a **multi-layer validation approach**: - -### Layer 1: Structural Validation -Verify the plugin manifest, file organization, and component discovery. - -| Check | Description | -|-------|-------------| -| Manifest validity | `plugin.json` has required fields (`name`, `version`, `description`, `author`) | -| Component discovery | All agents, skills, and hooks are in correct directories | -| No orphaned files | Every file belongs to a recognized plugin component | -| Valid JSON | `plugin.json` and `hooks.json` parse without errors | -| Valid YAML frontmatter | All `.md` components have parseable frontmatter | - -### Layer 2: Agent Configuration Validation -Verify agent definitions are well-formed and reference valid resources. - -| Check | Description | -|-------|-------------| -| Required frontmatter | Each agent has `model`, `description`, `tools` | -| Valid model values | Model is `opus`, `sonnet`, or `haiku` | -| Valid tool names | All tools are recognized Claude Code tools | -| File path accuracy | Paths in system prompts exist in the repo | -| Capability alignment | Examples match declared tools (e.g., debug agent has no Edit/Write) | - -### Layer 3: Content Integrity Verification -Verify that all commands, paths, and cross-references in skill content are accurate. - -| Check | Description | -|-------|-------------| -| File path references | All referenced repo paths exist | -| Mise task references | All `mise run` commands map to valid tasks | -| CLI command accuracy | All `bgagent` commands/flags match the actual CLI | -| Skill cross-references | Skills referencing other skills point to ones that exist | -| AWS CLI syntax | AWS CLI commands use valid subcommands | - -### Layer 4: Hook Validation -Verify hook configuration is correct and content is accurate. - -| Check | Description | -|-------|-------------| -| JSON structure | `hooks.json` has valid structure | -| Event names | Hook events are supported by Claude Code | -| Content accuracy | Skills and agents listed in hook prompt all exist | -| No sensitive data | No credentials or secrets in hook prompts | - ---- - -## Test Results +## Results ### Layer 1: Structural Validation — PASS From bcd7d46b7e098dd63e8554d4fcdc70a5eeb349a7 Mon Sep 17 00:00:00 2001 From: bgagent Date: Tue, 14 Apr 2026 14:09:11 -0700 Subject: [PATCH 07/20] docs(plugin): remove standalone TESTING.md, strategy lives in README Co-Authored-By: Claude Opus 4.6 (1M context) --- abca-plugin/TESTING.md | 128 ----------------------------------------- 1 file changed, 128 deletions(-) delete mode 100644 abca-plugin/TESTING.md diff --git a/abca-plugin/TESTING.md b/abca-plugin/TESTING.md deleted file mode 100644 index 5b8bc1c2..00000000 --- a/abca-plugin/TESTING.md +++ /dev/null @@ -1,128 +0,0 @@ -# ABCA Plugin — Test Results - -> Test report for the Claude Code plugin at `abca-plugin/`. -> Generated: 2026-04-14 -> -> For the testing strategy and how to run these checks, see [`README.md`](./README.md#testing). - -## Results - -### Layer 1: Structural Validation — PASS - -| Check | Result | Notes | -|-------|--------|-------| -| `plugin.json` valid JSON | PASS | All required fields present | -| `name` field | PASS | `abca-getting-started` — valid kebab-case | -| `version` field | PASS | `1.0.0` — valid semver | -| `description` field | PASS | Present and descriptive | -| `author` field | PASS | `aws-samples` | -| Agent files discovered | PASS | 2 agents in `agents/` | -| Skill files discovered | PASS | 7 skills in `skills/*/SKILL.md` | -| Hook file discovered | PASS | `hooks/hooks.json` present | -| No orphaned files | PASS | Every file is part of a component | - -### Layer 2: Agent Configuration — PASS (1 issue found) - -**cdk-expert.md** — All checks PASS - -| Check | Result | -|-------|--------| -| Has `model`, `description`, `tools` | PASS | -| Model `sonnet` is valid | PASS | -| Tools `[Read, Grep, Glob, Bash, Edit, Write]` valid | PASS | -| File paths exist | PASS | -| 3 `` blocks present | PASS | - -**agent-debugger.md** — 1 FAIL - -| Check | Result | Notes | -|-------|--------|-------| -| Has `model`, `description`, `tools` | PASS | | -| Model `sonnet` is valid | PASS | | -| Tools `[Read, Grep, Glob, Bash]` valid | PASS | | -| No Edit/Write (read-only debugger) | PASS | | -| 3 `` blocks present | PASS | | -| File path `agent/prompts/` exists | **FAIL** | Should be `agent/src/prompts/` | - -### Layer 3: Content Integrity — PASS - -**File Paths (6/6 PASS)** - -| Path | Referenced In | Result | -|------|--------------|--------| -| `cli/lib/bin/bgagent.js` | abca-status, abca-submit, submit-task, troubleshoot | PASS | -| `cdk/src/stacks/agent.ts` | onboard-repo | PASS | -| `cdk/src/handlers/shared/types.ts` | troubleshoot | PASS | -| `cli/src/types.ts` | troubleshoot | PASS | -| `agent/run.sh` | troubleshoot | PASS | -| `cdk/cdk.out/` | deploy | PASS | - -**Mise Tasks (10/10 PASS)** - -| Command | Result | -|---------|--------| -| `mise run build` | PASS | -| `mise run install` | PASS | -| `mise run //cdk:compile` | PASS | -| `mise run //cdk:test` | PASS | -| `mise run //cdk:deploy` | PASS | -| `mise run //cdk:destroy` | PASS | -| `mise run //cdk:diff` | PASS | -| `mise run //cdk:synth` | PASS | -| `mise run //cdk:bootstrap` | PASS | -| `mise run //cli:build` | PASS | - -**CLI Commands (6/6 PASS)** - -| Command | Flags Verified | Result | -|---------|---------------|--------| -| `bgagent submit` | `--repo, --issue, --task, --pr, --review-pr, --max-turns, --max-budget, --wait, --idempotency-key, --output` | PASS | -| `bgagent list` | `--status, --limit, --output` | PASS | -| `bgagent status` | `` | PASS | -| `bgagent events` | `, --output` | PASS | -| `bgagent configure` | `--api-url, --region, --user-pool-id, --client-id` | PASS | -| `bgagent login` | `--username` | PASS | - -**Skill Cross-References (3/3 PASS)** - -| From | References | Result | -|------|-----------|--------| -| abca-status | setup | PASS | -| setup | onboard-repo | PASS | -| troubleshoot | onboard-repo | PASS | - -### Layer 4: Hook Validation — PASS - -| Check | Result | Notes | -|-------|--------|-------| -| Valid JSON structure | PASS | | -| Event: `SessionStart` | PASS | Supported in Claude Code | -| Hook type: `prompt` | PASS | Valid hook type | -| Skills listed match actual | PASS | All 7 skills referenced exist | -| Agents listed match actual | PASS | Both agents exist | -| No sensitive data | PASS | Context only, no secrets | - ---- - -## Issues Found - -### Issue 1: Incorrect path in agent-debugger.md (Bug) - -**Severity:** Medium -**Location:** `abca-plugin/agents/agent-debugger.md` -**Description:** The system prompt references `agent/prompts/` but the correct path is `agent/src/prompts/`. -**Impact:** The agent-debugger may fail to locate prompt files when debugging agent issues. -**Fix:** Update path references from `agent/prompts/` to `agent/src/prompts/`. - ---- - -## Overall Result - -| Layer | Result | Issues | -|-------|--------|--------| -| 1. Structural Validation | PASS | 0 | -| 2. Agent Configuration | PASS* | 1 (incorrect path) | -| 3. Content Integrity | PASS | 0 | -| 4. Hook Validation | PASS | 0 | - -**Overall: PASS with 1 medium-severity bug identified and fixed.** From 811c0ee124687b51879939de39f062c55b81fb80 Mon Sep 17 00:00:00 2001 From: bgagent Date: Tue, 14 Apr 2026 14:14:48 -0700 Subject: [PATCH 08/20] fix(plugin): remove broken TESTING.md reference from README Co-Authored-By: Claude Opus 4.6 (1M context) --- abca-plugin/README.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/abca-plugin/README.md b/abca-plugin/README.md index 80c4fef1..701e655d 100644 --- a/abca-plugin/README.md +++ b/abca-plugin/README.md @@ -101,8 +101,6 @@ MISE_EXPERIMENTAL=1 mise tasks --all 2>/dev/null | grep -E '(build|install|compi cd cli && node lib/bin/bgagent.js submit --help && node lib/bin/bgagent.js list --help ``` -Full test results are documented in [`TESTING.md`](./TESTING.md). - ## Development To modify the plugin: From dc6557dd73af1088e70ad09e6e8dec81d29fa7a9 Mon Sep 17 00:00:00 2001 From: bgagent Date: Tue, 14 Apr 2026 14:17:45 -0700 Subject: [PATCH 09/20] fix: hook --- abca-plugin/hooks/hooks.json | 9 ++------- cdk/src/stacks/agent.ts | 10 +++++++++- 2 files changed, 11 insertions(+), 8 deletions(-) diff --git a/abca-plugin/hooks/hooks.json b/abca-plugin/hooks/hooks.json index 29f9c4b7..977c2318 100644 --- a/abca-plugin/hooks/hooks.json +++ b/abca-plugin/hooks/hooks.json @@ -2,13 +2,8 @@ "hooks": { "SessionStart": [ { - "matcher": "", - "hooks": [ - { - "type": "prompt", - "prompt": "You are working in the ABCA (Autonomous Background Coding Agents on AWS) repository — a self-hosted platform for background coding agents.\n\nKey directories: cdk/src/ (CDK infra), agent/src/ (Python agent), cli/src/ (bgagent CLI), docs/ (documentation).\n\nEssential commands (require MISE_EXPERIMENTAL=1): mise run install, mise run build, mise //cdk:compile, mise //cdk:test, mise //cdk:deploy.\n\nCritical: types in cdk/src/handlers/shared/types.ts must stay in sync with cli/src/types.ts. Don't edit docs/src/content/docs/ directly — it's generated.\n\nTask types: new_task (create PR), pr_iteration (update PR), pr_review (review PR).\n\nAvailable plugin skills: /setup, /deploy, /onboard-repo, /submit-task, /troubleshoot, /abca-status, /abca-submit\nAvailable agents: cdk-expert, agent-debugger\n\nDocs: https://aws-samples.github.io/sample-autonomous-cloud-coding-agents/" - } - ] + "type": "prompt", + "prompt": "You are working in the ABCA (Autonomous Background Coding Agents on AWS) repository — a self-hosted platform for background coding agents.\n\nKey directories: cdk/src/ (CDK infra), agent/src/ (Python agent), cli/src/ (bgagent CLI), docs/ (documentation).\n\nEssential commands (require MISE_EXPERIMENTAL=1): mise run install, mise run build, mise //cdk:compile, mise //cdk:test, mise //cdk:deploy.\n\nCritical: types in cdk/src/handlers/shared/types.ts must stay in sync with cli/src/types.ts. Don't edit docs/src/content/docs/ directly — it's generated.\n\nTask types: new_task (create PR), pr_iteration (update PR), pr_review (review PR).\n\nAvailable plugin skills: /setup, /deploy, /onboard-repo, /submit-task, /troubleshoot, /abca-status, /abca-submit\nAvailable agents: cdk-expert, agent-debugger\n\nDocs: https://aws-samples.github.io/sample-autonomous-cloud-coding-agents/" } ] } diff --git a/cdk/src/stacks/agent.ts b/cdk/src/stacks/agent.ts index 7d166907..9e979d21 100644 --- a/cdk/src/stacks/agent.ts +++ b/cdk/src/stacks/agent.ts @@ -67,7 +67,15 @@ export class AgentStack extends Stack { repoTable: repoTable.table, }); - const blueprints = [agentPluginsBlueprint]; + const personalSiteBlueprint = new Blueprint(this, 'PersonalSiteBlueprint', { + repo: 'rsmets/personal-site', + repoTable: repoTable.table, + agent: { + modelId: 'anthropic.claude-opus-4-20250514-v1:0', + }, + }); + + const blueprints = [agentPluginsBlueprint, personalSiteBlueprint]; // The AwsCustomResource singleton Lambda used by Blueprint constructs NagSuppressions.addResourceSuppressionsByPath(this, [ From c29bb76e10b0f751e47c5a1d620296cb10c5fff5 Mon Sep 17 00:00:00 2001 From: bgagent Date: Tue, 14 Apr 2026 15:23:31 -0700 Subject: [PATCH 10/20] gitignore --- .gitignore | 100 +++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 78 insertions(+), 22 deletions(-) diff --git a/.gitignore b/.gitignore index 0317435f..d4e5bb9d 100644 --- a/.gitignore +++ b/.gitignore @@ -1,19 +1,36 @@ +# ────────────────────────────────────────────── +# Logs +# ────────────────────────────────────────────── logs *.log npm-debug.log* yarn-debug.log* yarn-error.log* lerna-debug.log* -report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json + +# ────────────────────────────────────────────── +# Runtime / process +# ────────────────────────────────────────────── pids *.pid *.seed *.pid.lock -lib-cov + +# ────────────────────────────────────────────── +# Coverage & test reports +# ────────────────────────────────────────────── coverage *.lcov .nyc_output -build/Release +lib-cov +report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json +/test-reports/ +junit.xml +/coverage/ + +# ────────────────────────────────────────────── +# Node / JS +# ────────────────────────────────────────────── node_modules/ jspm_packages/ *.tsbuildinfo @@ -21,37 +38,76 @@ jspm_packages/ *.tgz .yarn-integrity .cache -cdk.out/ -*.DS_STORE -!.node-version +.parcel-cache/ + +# ────────────────────────────────────────────── +# Python +# ────────────────────────────────────────────── *.pyc __pycache__/ -!.ort.yml +agent/.venv/ + +# ────────────────────────────────────────────── +# CDK / CloudFormation outputs +# ────────────────────────────────────────────── +cdk.out/ +/cdk/cdk.out*/ +.cdk.staging/ +cdk.context.json +/assets/ + +# ────────────────────────────────────────────── +# Build outputs (compiled TS → JS) +# ────────────────────────────────────────────── +/cdk/lib/ +/cli/lib/ +/dist/ +build/Release + +# ────────────────────────────────────────────── +# Docs build +# ────────────────────────────────────────────── +/docs/dist/ +local-docs/ + +# ────────────────────────────────────────────── +# IDE / editor +# ────────────────────────────────────────────── .idea .vscode -cdk.context.json -*.bkp +*.DS_STORE + +# ────────────────────────────────────────────── +# Security scan outputs +# ────────────────────────────────────────────── gitleaks-*.json agent/gitleaks-report.json + +# ────────────────────────────────────────────── +# Environment / secrets +# ────────────────────────────────────────────── +.env +.env.* .claude/settings.local.json -/test-reports/ -junit.xml -/coverage/ + +# ────────────────────────────────────────────── +# Misc +# ────────────────────────────────────────────── +*.bkp +Plans/ + +# ────────────────────────────────────────────── +# Explicit keeps (override ignores above) +# ────────────────────────────────────────────── +!.node-version +!.ort.yml !/.github/workflows/build.yml -!/.mergify.yml +!/.github/workflows/docs.yml !/.github/pull_request_template.md +!/.mergify.yml !/cdk/test/ !/cdk/tsconfig.json !/cdk/tsconfig.dev.json !/cdk/src/ -/cdk/lib -/dist/ !/cdk/.eslintrc.json -/assets/ !/cdk/cdk.json -/cdk/cdk.out/ -.cdk.staging/ -.parcel-cache/ -!/.github/workflows/docs.yml -local-docs/ -Plans/ From de7e8a66f06b36bbd21e990d8b233e8c41113dcc Mon Sep 17 00:00:00 2001 From: bgagent Date: Tue, 14 Apr 2026 15:48:16 -0700 Subject: [PATCH 11/20] opus --- cdk/src/stacks/agent.ts | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/cdk/src/stacks/agent.ts b/cdk/src/stacks/agent.ts index 9e979d21..44080411 100644 --- a/cdk/src/stacks/agent.ts +++ b/cdk/src/stacks/agent.ts @@ -206,6 +206,20 @@ export class AgentStack extends Stack { // Grant the runtime permissions to invoke the inference profile inferenceProfile.grantInvoke(runtime); + const model3 = new bedrock.BedrockFoundationModel('anthropic.claude-opus-4-20250514-v1:0', { + supportsAgents: true, + supportsCrossRegion: true, + }); + + model3.grantInvoke(runtime); + + const inferenceProfile3 = bedrock.CrossRegionInferenceProfile.fromConfig({ + geoRegion: bedrock.CrossRegionInferenceProfileRegion.US, + model: model3, + }); + + inferenceProfile3.grantInvoke(runtime); + const model2 = new bedrock.BedrockFoundationModel('anthropic.claude-haiku-4-5-20251001-v1:0', { supportsAgents: true, supportsCrossRegion: true, From 9172b249d7031ee240043383154a5c5fdf4c9e2e Mon Sep 17 00:00:00 2001 From: bgagent Date: Tue, 14 Apr 2026 15:53:50 -0700 Subject: [PATCH 12/20] chore: rm personal site from blueprint source --- cdk/src/stacks/agent.ts | 10 +--------- 1 file changed, 1 insertion(+), 9 deletions(-) diff --git a/cdk/src/stacks/agent.ts b/cdk/src/stacks/agent.ts index 44080411..da994015 100644 --- a/cdk/src/stacks/agent.ts +++ b/cdk/src/stacks/agent.ts @@ -67,15 +67,7 @@ export class AgentStack extends Stack { repoTable: repoTable.table, }); - const personalSiteBlueprint = new Blueprint(this, 'PersonalSiteBlueprint', { - repo: 'rsmets/personal-site', - repoTable: repoTable.table, - agent: { - modelId: 'anthropic.claude-opus-4-20250514-v1:0', - }, - }); - - const blueprints = [agentPluginsBlueprint, personalSiteBlueprint]; + const blueprints = [agentPluginsBlueprint]; // The AwsCustomResource singleton Lambda used by Blueprint constructs NagSuppressions.addResourceSuppressionsByPath(this, [ From 8e3ed6a02f0bee3de40e48d0d29fad71cba89e92 Mon Sep 17 00:00:00 2001 From: bgagent Date: Tue, 14 Apr 2026 16:33:06 -0700 Subject: [PATCH 13/20] feat: troubleshooting skill --- abca-plugin/skills/onboard-repo/SKILL.md | 32 +++++++++++++++++++++--- abca-plugin/skills/troubleshoot/SKILL.md | 18 +++++++++++-- 2 files changed, 45 insertions(+), 5 deletions(-) diff --git a/abca-plugin/skills/onboard-repo/SKILL.md b/abca-plugin/skills/onboard-repo/SKILL.md index eb298803..8c863f3e 100644 --- a/abca-plugin/skills/onboard-repo/SKILL.md +++ b/abca-plugin/skills/onboard-repo/SKILL.md @@ -16,7 +16,7 @@ You are guiding the user through onboarding a new GitHub repository to ABCA. Rep 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) +- **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 @@ -44,7 +44,7 @@ new Blueprint(this, 'MyRepoBlueprint', { repoTable: repoTable, // Optional overrides: // computeType: 'agentcore', - // modelId: 'anthropic.claude-sonnet-4-20250514-v1:0', + // modelId: 'us.anthropic.claude-sonnet-4-20250514-v1:0', // maxTurns: 100, // maxBudgetUsd: 50, // runtimeArn: runtime.runtimeArn, @@ -54,6 +54,30 @@ new Blueprint(this, 'MyRepoBlueprint', { Use a descriptive construct ID derived from the repo name. +### Model ID and IAM Permissions + +When specifying a non-default model via `agent.modelId`, two things are required: + +1. **Use the inference profile ID, not the raw model ID.** Bedrock does not support on-demand invocation of raw foundation model IDs for most models. Use the cross-region inference profile ID instead: + - 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` (on-demand works for Haiku) + +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); + ``` + ## Step 4: Deploy After adding the Blueprint, the stack must be redeployed: @@ -100,4 +124,6 @@ Task-level parameters override Blueprint defaults. If neither specifies a value, ## 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. +- **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`. diff --git a/abca-plugin/skills/troubleshoot/SKILL.md b/abca-plugin/skills/troubleshoot/SKILL.md index 1fc78210..ffa9cc1e 100644 --- a/abca-plugin/skills/troubleshoot/SKILL.md +++ b/abca-plugin/skills/troubleshoot/SKILL.md @@ -96,11 +96,25 @@ node lib/bin/bgagent.js events --output json - Check event `reason` and `detail` fields for specifics - Verify PAT: fine-grained token must include the target repository with Contents (read/write), Pull Requests (read/write), Issues (read) -**`task_failed`:** +**`task_failed` / task completes with 0 tokens and no PR:** - Agent encountered an error during execution -- Check CloudWatch logs for the session +- Check CloudWatch logs for the session: + ```bash + aws logs filter-log-events \ + --log-group-name "/aws/vendedlogs/bedrock-agentcore/runtime/APPLICATION_LOGS/jean_cloude" \ + --filter-pattern "" \ + --region us-west-2 --query 'events[*].message' --output text + ``` - Common: repo build/test commands not documented in CLAUDE.md +**403 "not authorized to perform bedrock:InvokeModelWithResponseStream":** +- The Blueprint specifies a model that the runtime IAM role doesn't have permissions for +- Fix: add `grantInvoke` for the model and its cross-region inference profile in `cdk/src/stacks/agent.ts`, then redeploy + +**400 "Invocation with on-demand throughput isn't supported":** +- The Blueprint `modelId` uses a raw foundation model ID (e.g. `anthropic.claude-opus-4-20250514-v1:0`) +- Fix: change to the inference profile ID (e.g. `us.anthropic.claude-opus-4-20250514-v1:0`), update DynamoDB via redeploy + **`task_timed_out`:** - 9-hour maximum exceeded - Consider reducing scope or increasing `max_turns` for complex tasks From eddb8626a95f7e4e5eff767b09335cd03fb23a72 Mon Sep 17 00:00:00 2001 From: bgagent Date: Tue, 14 Apr 2026 17:08:35 -0700 Subject: [PATCH 14/20] chore: true relative path --- abca-plugin/README.md | 2 +- abca-plugin/skills/abca-status/SKILL.md | 4 +-- abca-plugin/skills/abca-submit/SKILL.md | 2 +- abca-plugin/skills/setup/SKILL.md | 6 ++-- abca-plugin/skills/submit-task/SKILL.md | 10 +++---- abca-plugin/skills/troubleshoot/SKILL.md | 36 +++++++++++++++++++++--- 6 files changed, 44 insertions(+), 16 deletions(-) diff --git a/abca-plugin/README.md b/abca-plugin/README.md index 701e655d..d858ab73 100644 --- a/abca-plugin/README.md +++ b/abca-plugin/README.md @@ -98,7 +98,7 @@ python3 -c "import json; json.load(open('abca-plugin/hooks/hooks.json')); print( MISE_EXPERIMENTAL=1 mise tasks --all 2>/dev/null | grep -E '(build|install|compile|test|deploy|destroy|diff|synth|bootstrap)' # Layer 3: Content — CLI flags match -cd cli && node lib/bin/bgagent.js submit --help && node lib/bin/bgagent.js list --help +node cli/lib/bin/bgagent.js submit --help && node cli/lib/bin/bgagent.js list --help ``` ## Development diff --git a/abca-plugin/skills/abca-status/SKILL.md b/abca-plugin/skills/abca-status/SKILL.md index 0a702c50..b2158399 100644 --- a/abca-plugin/skills/abca-status/SKILL.md +++ b/abca-plugin/skills/abca-status/SKILL.md @@ -22,12 +22,12 @@ Run these in parallel where possible: 2. **Running tasks:** ```bash - cd cli && node lib/bin/bgagent.js list --status RUNNING,SUBMITTED,HYDRATING --output json 2>/dev/null || echo "CLI not configured" + node cli/lib/bin/bgagent.js list --status RUNNING,SUBMITTED,HYDRATING --output json 2>/dev/null || echo "CLI not configured" ``` 3. **Recent completed tasks:** ```bash - cd cli && node lib/bin/bgagent.js list --limit 5 --output json 2>/dev/null || echo "CLI not configured" + node cli/lib/bin/bgagent.js list --limit 5 --output json 2>/dev/null || echo "CLI not configured" ``` 4. **Local build health:** diff --git a/abca-plugin/skills/abca-submit/SKILL.md b/abca-plugin/skills/abca-submit/SKILL.md index 4bd131f5..723825d4 100644 --- a/abca-plugin/skills/abca-submit/SKILL.md +++ b/abca-plugin/skills/abca-submit/SKILL.md @@ -27,7 +27,7 @@ Parse the description to infer the type: ## Submit ```bash -cd cli && node lib/bin/bgagent.js submit \ +node cli/lib/bin/bgagent.js submit \ --repo $REPO \ $FLAGS \ --max-turns 100 \ diff --git a/abca-plugin/skills/setup/SKILL.md b/abca-plugin/skills/setup/SKILL.md index 21d92d5b..5bcbfc2b 100644 --- a/abca-plugin/skills/setup/SKILL.md +++ b/abca-plugin/skills/setup/SKILL.md @@ -84,11 +84,11 @@ Guide through: 2. Test the API: `curl -s -H "Authorization: $TOKEN" $API_URL/tasks` 3. Configure the CLI: ```bash - cd cli && mise run build - node lib/bin/bgagent.js configure \ + mise //cli:build + node cli/lib/bin/bgagent.js configure \ --api-url $API_URL --region $REGION \ --user-pool-id $USER_POOL_ID --client-id $APP_CLIENT_ID - node lib/bin/bgagent.js login --username user@example.com + node cli/lib/bin/bgagent.js login --username user@example.com ``` ## Completion diff --git a/abca-plugin/skills/submit-task/SKILL.md b/abca-plugin/skills/submit-task/SKILL.md index b0f38bcc..1bd03630 100644 --- a/abca-plugin/skills/submit-task/SKILL.md +++ b/abca-plugin/skills/submit-task/SKILL.md @@ -77,8 +77,8 @@ Recommend appropriate limits based on task complexity: **Via CLI (preferred):** ```bash -# From the cli/ directory after building -node lib/bin/bgagent.js submit \ +# From the repo root +node cli/lib/bin/bgagent.js submit \ --repo owner/repo \ --issue 42 \ --max-turns 100 \ @@ -118,9 +118,9 @@ curl -X POST "$API_URL/tasks" \ After submission, show how to check status: ```bash -node lib/bin/bgagent.js status -node lib/bin/bgagent.js events -node lib/bin/bgagent.js list --status RUNNING +node cli/lib/bin/bgagent.js status +node cli/lib/bin/bgagent.js events +node cli/lib/bin/bgagent.js list --status RUNNING ``` Task states: SUBMITTED -> HYDRATING -> RUNNING -> COMPLETED/FAILED/CANCELLED/TIMED_OUT diff --git a/abca-plugin/skills/troubleshoot/SKILL.md b/abca-plugin/skills/troubleshoot/SKILL.md index ffa9cc1e..27b18ddb 100644 --- a/abca-plugin/skills/troubleshoot/SKILL.md +++ b/abca-plugin/skills/troubleshoot/SKILL.md @@ -87,7 +87,7 @@ aws cognito-idp admin-get-user \ ```bash # Check task events for details -node lib/bin/bgagent.js events --output json +node cli/lib/bin/bgagent.js events --output json ``` **`preflight_failed`:** @@ -115,6 +115,34 @@ node lib/bin/bgagent.js events --output json - The Blueprint `modelId` uses a raw foundation model ID (e.g. `anthropic.claude-opus-4-20250514-v1:0`) - Fix: change to the inference profile ID (e.g. `us.anthropic.claude-opus-4-20250514-v1:0`), update DynamoDB via redeploy +**503 "Too many connections" / task completes with 0 tokens after long duration:** +- Bedrock is throttling model invocations. The agent retries for minutes then gives up. +- Symptoms: task runs for 10-15 minutes, completes with `COMPLETED` status but 0 tokens, 0 cost, no PR, `disk_delta: 0 B` +- Diagnosis: + 1. Check application logs for `"text": "API Error: 503 Too many connections"` + 2. **Check what model_id is actually being passed** — the DynamoDB record may have a stale model override: + ```bash + aws dynamodb get-item \ + --table-name \ + --key '{"repo": {"S": "owner/repo"}}' \ + --query 'Item.model_id' --output text + ``` +- Causes: + - **Stale model_id in DynamoDB** (most common) — the Blueprint `onUpdate` only sets fields present in props; removing a `modelId` prop does NOT remove the field from DynamoDB. The task keeps using the old model. + - Bedrock service-level throttling for the specific model (especially Opus 4 which has limited availability) + - Account quota limits reached +- Fix: + 1. **Check and fix the DynamoDB record first** — remove stale `model_id` if present: + ```bash + aws dynamodb update-item \ + --table-name \ + --key '{"repo": {"S": "owner/repo"}}' \ + --update-expression "REMOVE model_id" + ``` + 2. If model_id is correct, wait and retry — throttling is often transient + 3. Switch to a model with higher availability (Sonnet 4.6 > Opus 4 > Haiku) + 4. Request a Bedrock quota increase for `InvokeModel` RPM on your model + **`task_timed_out`:** - 9-hour maximum exceeded - Consider reducing scope or increasing `max_turns` for complex tasks @@ -149,11 +177,11 @@ aws cloudformation describe-stacks --stack-name backgroundagent-dev --query 'Sta aws cloudformation describe-stacks --stack-name backgroundagent-dev --query 'Stacks[0].Outputs' --output table # Task status -node lib/bin/bgagent.js status -node lib/bin/bgagent.js events --output json +node cli/lib/bin/bgagent.js status +node cli/lib/bin/bgagent.js events --output json # List running tasks -node lib/bin/bgagent.js list --status RUNNING +node cli/lib/bin/bgagent.js list --status RUNNING # Build health mise run build From 67e6f77ef2ccbd646d47869adfc6f629a6ec5b73 Mon Sep 17 00:00:00 2001 From: bgagent Date: Thu, 16 Apr 2026 09:07:21 -0700 Subject: [PATCH 15/20] chore: rm hooks --- abca-plugin/hooks/hooks.json | 10 ---------- 1 file changed, 10 deletions(-) delete mode 100644 abca-plugin/hooks/hooks.json diff --git a/abca-plugin/hooks/hooks.json b/abca-plugin/hooks/hooks.json deleted file mode 100644 index 977c2318..00000000 --- a/abca-plugin/hooks/hooks.json +++ /dev/null @@ -1,10 +0,0 @@ -{ - "hooks": { - "SessionStart": [ - { - "type": "prompt", - "prompt": "You are working in the ABCA (Autonomous Background Coding Agents on AWS) repository — a self-hosted platform for background coding agents.\n\nKey directories: cdk/src/ (CDK infra), agent/src/ (Python agent), cli/src/ (bgagent CLI), docs/ (documentation).\n\nEssential commands (require MISE_EXPERIMENTAL=1): mise run install, mise run build, mise //cdk:compile, mise //cdk:test, mise //cdk:deploy.\n\nCritical: types in cdk/src/handlers/shared/types.ts must stay in sync with cli/src/types.ts. Don't edit docs/src/content/docs/ directly — it's generated.\n\nTask types: new_task (create PR), pr_iteration (update PR), pr_review (review PR).\n\nAvailable plugin skills: /setup, /deploy, /onboard-repo, /submit-task, /troubleshoot, /abca-status, /abca-submit\nAvailable agents: cdk-expert, agent-debugger\n\nDocs: https://aws-samples.github.io/sample-autonomous-cloud-coding-agents/" - } - ] - } -} From 3a56f807e6a95902fdfd347697e754462eded86b Mon Sep 17 00:00:00 2001 From: bgagent Date: Thu, 16 Apr 2026 09:07:33 -0700 Subject: [PATCH 16/20] fix: error handling --- abca-plugin/skills/abca-status/SKILL.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/abca-plugin/skills/abca-status/SKILL.md b/abca-plugin/skills/abca-status/SKILL.md index b2158399..661017f5 100644 --- a/abca-plugin/skills/abca-status/SKILL.md +++ b/abca-plugin/skills/abca-status/SKILL.md @@ -17,17 +17,17 @@ Run these in parallel where possible: 1. **Stack status:** ```bash aws cloudformation describe-stacks --stack-name backgroundagent-dev \ - --query 'Stacks[0].{Status:StackStatus,Updated:LastUpdatedTime}' --output json 2>/dev/null || echo "Stack not found" + --query 'Stacks[0].{Status:StackStatus,Updated:LastUpdatedTime}' --output json 2>&1 || echo "Stack not found" ``` 2. **Running tasks:** ```bash - node cli/lib/bin/bgagent.js list --status RUNNING,SUBMITTED,HYDRATING --output json 2>/dev/null || echo "CLI not configured" + node cli/lib/bin/bgagent.js list --status RUNNING,SUBMITTED,HYDRATING --output json 2>&1 || echo "CLI not configured" ``` 3. **Recent completed tasks:** ```bash - node cli/lib/bin/bgagent.js list --limit 5 --output json 2>/dev/null || echo "CLI not configured" + node cli/lib/bin/bgagent.js list --limit 5 --output json 2>&1 || echo "CLI not configured" ``` 4. **Local build health:** From 28b92cea556032894109eefd38625628c4a31921 Mon Sep 17 00:00:00 2001 From: bgagent Date: Thu, 16 Apr 2026 09:12:26 -0700 Subject: [PATCH 17/20] refactor: moved plugin to docs dir --- README.md | 19 +++++---------- {abca-plugin => docs/abca-plugin}/README.md | 23 ++++++------------- .../abca-plugin}/agents/agent-debugger.md | 0 .../abca-plugin}/agents/cdk-expert.md | 0 {abca-plugin => docs/abca-plugin}/plugin.json | 0 .../abca-plugin}/skills/abca-status/SKILL.md | 0 .../abca-plugin}/skills/abca-submit/SKILL.md | 0 .../abca-plugin}/skills/deploy/SKILL.md | 0 .../abca-plugin}/skills/onboard-repo/SKILL.md | 0 .../abca-plugin}/skills/setup/SKILL.md | 0 .../abca-plugin}/skills/submit-task/SKILL.md | 0 .../abca-plugin}/skills/troubleshoot/SKILL.md | 0 docs/guides/DEVELOPER_GUIDE.md | 3 +++ 13 files changed, 16 insertions(+), 29 deletions(-) rename {abca-plugin => docs/abca-plugin}/README.md (79%) rename {abca-plugin => docs/abca-plugin}/agents/agent-debugger.md (100%) rename {abca-plugin => docs/abca-plugin}/agents/cdk-expert.md (100%) rename {abca-plugin => docs/abca-plugin}/plugin.json (100%) rename {abca-plugin => docs/abca-plugin}/skills/abca-status/SKILL.md (100%) rename {abca-plugin => docs/abca-plugin}/skills/abca-submit/SKILL.md (100%) rename {abca-plugin => docs/abca-plugin}/skills/deploy/SKILL.md (100%) rename {abca-plugin => docs/abca-plugin}/skills/onboard-repo/SKILL.md (100%) rename {abca-plugin => docs/abca-plugin}/skills/setup/SKILL.md (100%) rename {abca-plugin => docs/abca-plugin}/skills/submit-task/SKILL.md (100%) rename {abca-plugin => docs/abca-plugin}/skills/troubleshoot/SKILL.md (100%) diff --git a/README.md b/README.md index 6d917b87..6ba1a654 100644 --- a/README.md +++ b/README.md @@ -78,12 +78,12 @@ This repository ships a [Claude Code plugin](https://docs.anthropic.com/en/docs/ ```bash git clone https://github.com/aws-samples/sample-autonomous-cloud-coding-agents.git cd sample-autonomous-cloud-coding-agents -claude --plugin-dir abca-plugin +claude --plugin-dir docs/abca-plugin ``` -The `--plugin-dir` flag tells Claude Code to load the local plugin from the `abca-plugin/` directory. The plugin's skills, commands, agents, and hooks will be available immediately. +The `--plugin-dir` flag tells Claude Code to load the local plugin from the `docs/abca-plugin/` directory. The plugin's skills, commands, agents, and hooks will be available immediately. -> **Tip:** If you use Claude Code via VS Code or JetBrains, you can add `--plugin-dir abca-plugin` to the extension's CLI arguments setting. +> **Tip:** If you use Claude Code via VS Code or JetBrains, you can add `--plugin-dir docs/abca-plugin` to the extension's CLI arguments setting. #### What the plugin provides @@ -106,16 +106,12 @@ The `--plugin-dir` flag tells Claude Code to load the local plugin from the `abc | `cdk-expert` | CDK architecture, construct design, handler implementation, stack modifications | | `agent-debugger` | Task failure investigation, CloudWatch log analysis, agent runtime debugging | -**Hook** (runs automatically): - -A `SessionStart` hook injects ABCA project context (key directories, commands, conventions) into every Claude Code session. - #### Local plugin development If you're modifying the plugin itself, here's the file layout: ``` -abca-plugin/ +docs/abca-plugin/ plugin.json # Plugin manifest (name, version, description) skills/ setup/SKILL.md # First-time setup workflow @@ -128,17 +124,14 @@ abca-plugin/ agents/ cdk-expert.md # CDK infrastructure specialist agent-debugger.md # Task failure debugger - hooks/ - hooks.json # SessionStart hook configuration ``` **Key conventions:** -- All plugin components live inside `abca-plugin/` alongside the manifest +- The plugin lives under `docs/` to keep documentation and plugin content colocated - Skills live in subdirectories with a `SKILL.md` file (not flat `.md` files) - Agents are flat `.md` files with YAML frontmatter -- Hooks use JSON configuration in `hooks/hooks.json` -**After editing plugin files**, restart Claude Code with `claude --plugin-dir abca-plugin` to pick up changes. +**After editing plugin files**, restart Claude Code with `claude --plugin-dir docs/abca-plugin` to pick up changes. ### Manual installation and deployment diff --git a/abca-plugin/README.md b/docs/abca-plugin/README.md similarity index 79% rename from abca-plugin/README.md rename to docs/abca-plugin/README.md index d858ab73..31a9cb89 100644 --- a/abca-plugin/README.md +++ b/docs/abca-plugin/README.md @@ -5,14 +5,14 @@ A Claude Code plugin that provides guided workflows for setting up, deploying, o ## Installation ```bash -claude --plugin-dir abca-plugin +claude --plugin-dir docs/abca-plugin ``` Or add to your project's `.claude/settings.json`: ```json { - "plugins": ["./abca-plugin"] + "plugins": ["./docs/abca-plugin"] } ``` @@ -37,20 +37,14 @@ Or add to your project's `.claude/settings.json`: | `cdk-expert` | Sonnet | AWS CDK infrastructure expert for construct design, handler implementation, and stack modifications | | `agent-debugger` | Sonnet | Read-only debugging specialist for task failures, preflight errors, and CloudWatch log analysis | -### Hooks - -- **SessionStart** — Injects ABCA project context (directory structure, key commands, task types, available skills/agents) into every Claude Code session. - ## Plugin Structure ``` -abca-plugin/ +docs/abca-plugin/ plugin.json # Plugin manifest agents/ cdk-expert.md # CDK infrastructure agent agent-debugger.md # Runtime debugging agent - hooks/ - hooks.json # SessionStart context injection skills/ setup/SKILL.md # First-time setup workflow deploy/SKILL.md # CDK deployment management @@ -63,21 +57,20 @@ abca-plugin/ ## Testing -This plugin is markdown and configuration only (no executable code), so traditional unit tests don't apply. Instead, a **4-layer validation strategy** verifies correctness: +This plugin is markdown and configuration only (no executable code), so traditional unit tests don't apply. Instead, a **3-layer validation strategy** verifies correctness: | Layer | What it checks | |-------|---------------| | **1. Structural** | `plugin.json` fields, file discovery, JSON/YAML validity, no orphaned files | | **2. Agent Config** | Frontmatter fields (`model`, `tools`, `description`), valid tool names, file path accuracy, capability alignment with examples | | **3. Content Integrity** | All repo paths exist, all `mise run` commands are valid tasks, all `bgagent` CLI flags match actual help output, skill cross-references resolve, AWS CLI syntax is correct | -| **4. Hooks** | `hooks.json` structure, supported event names, skills/agents listed in hook content all exist, no sensitive data | ### Running the tests From the repo root with Claude Code: ``` -claude --plugin-dir abca-plugin +claude --plugin-dir docs/abca-plugin ``` Then ask Claude to validate the plugin: @@ -91,8 +84,7 @@ Or run the checks manually: ```bash # Layer 1: Structural — valid JSON -python3 -c "import json; json.load(open('abca-plugin/plugin.json')); print('plugin.json OK')" -python3 -c "import json; json.load(open('abca-plugin/hooks/hooks.json')); print('hooks.json OK')" +python3 -c "import json; json.load(open('docs/abca-plugin/plugin.json')); print('plugin.json OK')" # Layer 3: Content — mise tasks exist MISE_EXPERIMENTAL=1 mise tasks --all 2>/dev/null | grep -E '(build|install|compile|test|deploy|destroy|diff|synth|bootstrap)' @@ -105,7 +97,6 @@ node cli/lib/bin/bgagent.js submit --help && node cli/lib/bin/bgagent.js list -- To modify the plugin: -1. Edit the relevant `.md` file under `skills/`, `agents/`, or `hooks/` +1. Edit the relevant `.md` file under `skills/` or `agents/` 2. Re-validate using the testing strategy above 3. Ensure any new file paths or commands you reference actually exist in the repo -4. Keep the `SessionStart` hook prompt in sync if you add/remove/rename skills or agents diff --git a/abca-plugin/agents/agent-debugger.md b/docs/abca-plugin/agents/agent-debugger.md similarity index 100% rename from abca-plugin/agents/agent-debugger.md rename to docs/abca-plugin/agents/agent-debugger.md diff --git a/abca-plugin/agents/cdk-expert.md b/docs/abca-plugin/agents/cdk-expert.md similarity index 100% rename from abca-plugin/agents/cdk-expert.md rename to docs/abca-plugin/agents/cdk-expert.md diff --git a/abca-plugin/plugin.json b/docs/abca-plugin/plugin.json similarity index 100% rename from abca-plugin/plugin.json rename to docs/abca-plugin/plugin.json diff --git a/abca-plugin/skills/abca-status/SKILL.md b/docs/abca-plugin/skills/abca-status/SKILL.md similarity index 100% rename from abca-plugin/skills/abca-status/SKILL.md rename to docs/abca-plugin/skills/abca-status/SKILL.md diff --git a/abca-plugin/skills/abca-submit/SKILL.md b/docs/abca-plugin/skills/abca-submit/SKILL.md similarity index 100% rename from abca-plugin/skills/abca-submit/SKILL.md rename to docs/abca-plugin/skills/abca-submit/SKILL.md diff --git a/abca-plugin/skills/deploy/SKILL.md b/docs/abca-plugin/skills/deploy/SKILL.md similarity index 100% rename from abca-plugin/skills/deploy/SKILL.md rename to docs/abca-plugin/skills/deploy/SKILL.md diff --git a/abca-plugin/skills/onboard-repo/SKILL.md b/docs/abca-plugin/skills/onboard-repo/SKILL.md similarity index 100% rename from abca-plugin/skills/onboard-repo/SKILL.md rename to docs/abca-plugin/skills/onboard-repo/SKILL.md diff --git a/abca-plugin/skills/setup/SKILL.md b/docs/abca-plugin/skills/setup/SKILL.md similarity index 100% rename from abca-plugin/skills/setup/SKILL.md rename to docs/abca-plugin/skills/setup/SKILL.md diff --git a/abca-plugin/skills/submit-task/SKILL.md b/docs/abca-plugin/skills/submit-task/SKILL.md similarity index 100% rename from abca-plugin/skills/submit-task/SKILL.md rename to docs/abca-plugin/skills/submit-task/SKILL.md diff --git a/abca-plugin/skills/troubleshoot/SKILL.md b/docs/abca-plugin/skills/troubleshoot/SKILL.md similarity index 100% rename from abca-plugin/skills/troubleshoot/SKILL.md rename to docs/abca-plugin/skills/troubleshoot/SKILL.md diff --git a/docs/guides/DEVELOPER_GUIDE.md b/docs/guides/DEVELOPER_GUIDE.md index 2493f1ba..cbc52c34 100644 --- a/docs/guides/DEVELOPER_GUIDE.md +++ b/docs/guides/DEVELOPER_GUIDE.md @@ -10,6 +10,9 @@ The repository is organized around four main pieces: - **Infrastructure as code** in AWS CDK under `cdk/src/` — stacks, constructs, and handlers that define and deploy the platform on AWS. - **Documentation site** under `docs/` — source guides/design docs plus the generated Astro/Starlight documentation site. - **CLI package** under `cli/` — the `bgagent` command-line client used to authenticate, submit tasks, and inspect task status/events. +- **Claude Code plugin** under `docs/abca-plugin/` — a [Claude Code plugin](https://docs.anthropic.com/en/docs/claude-code/plugins) with guided skills and agents for setup, deployment, task submission, and troubleshooting. See the [plugin README](../abca-plugin/README.md) for details. + +> **Tip:** If you use Claude Code, run `claude --plugin-dir docs/abca-plugin` from the repo root. The plugin's `/setup` skill walks you through the entire setup process interactively. ## Where to make changes From 1eb310f2e5c96d69b3f253dd63d95ec159daab8a Mon Sep 17 00:00:00 2001 From: bgagent Date: Thu, 16 Apr 2026 09:15:52 -0700 Subject: [PATCH 18/20] feat: hook --- README.md | 7 +++++++ docs/abca-plugin/README.md | 6 ++++++ docs/abca-plugin/hooks/hooks.json | 10 ++++++++++ 3 files changed, 23 insertions(+) create mode 100644 docs/abca-plugin/hooks/hooks.json diff --git a/README.md b/README.md index 6ba1a654..61c12706 100644 --- a/README.md +++ b/README.md @@ -106,6 +106,10 @@ The `--plugin-dir` flag tells Claude Code to load the local plugin from the `doc | `cdk-expert` | CDK architecture, construct design, handler implementation, stack modifications | | `agent-debugger` | Task failure investigation, CloudWatch log analysis, agent runtime debugging | +**Hook** (runs automatically): + +A `SessionStart` hook advertises available skills and agents so Claude can proactively suggest them when your request matches. + #### Local plugin development If you're modifying the plugin itself, here's the file layout: @@ -124,12 +128,15 @@ docs/abca-plugin/ agents/ cdk-expert.md # CDK infrastructure specialist agent-debugger.md # Task failure debugger + hooks/ + hooks.json # SessionStart capability advertisement ``` **Key conventions:** - The plugin lives under `docs/` to keep documentation and plugin content colocated - Skills live in subdirectories with a `SKILL.md` file (not flat `.md` files) - Agents are flat `.md` files with YAML frontmatter +- The hook advertises plugin capabilities only (no project-specific content) **After editing plugin files**, restart Claude Code with `claude --plugin-dir docs/abca-plugin` to pick up changes. diff --git a/docs/abca-plugin/README.md b/docs/abca-plugin/README.md index 31a9cb89..d20eda9a 100644 --- a/docs/abca-plugin/README.md +++ b/docs/abca-plugin/README.md @@ -37,6 +37,10 @@ Or add to your project's `.claude/settings.json`: | `cdk-expert` | Sonnet | AWS CDK infrastructure expert for construct design, handler implementation, and stack modifications | | `agent-debugger` | Sonnet | Read-only debugging specialist for task failures, preflight errors, and CloudWatch log analysis | +### Hook + +- **SessionStart** — Advertises available skills and agents so Claude can proactively suggest them when your request matches. + ## Plugin Structure ``` @@ -45,6 +49,8 @@ docs/abca-plugin/ agents/ cdk-expert.md # CDK infrastructure agent agent-debugger.md # Runtime debugging agent + hooks/ + hooks.json # SessionStart capability advertisement skills/ setup/SKILL.md # First-time setup workflow deploy/SKILL.md # CDK deployment management diff --git a/docs/abca-plugin/hooks/hooks.json b/docs/abca-plugin/hooks/hooks.json new file mode 100644 index 00000000..340720a2 --- /dev/null +++ b/docs/abca-plugin/hooks/hooks.json @@ -0,0 +1,10 @@ +{ + "hooks": { + "SessionStart": [ + { + "type": "prompt", + "prompt": "The ABCA plugin is active. Available skills:\n- /setup — first-time setup walkthrough\n- /deploy — deploy, diff, or destroy the CDK stack\n- /onboard-repo — add a GitHub repository\n- /submit-task — submit a coding task with prompt coaching\n- /troubleshoot — diagnose deployment, auth, or task issues\n- /abca-status — quick platform health check\n- /abca-submit — shortcut for rapid task submission\n\nAvailable agents: cdk-expert (CDK infrastructure), agent-debugger (task failure investigation).\n\nSuggest relevant skills when the user's request matches." + } + ] + } +} From 623ade676832ae7728b9c7c4a5ac5493cbe5ba35 Mon Sep 17 00:00:00 2001 From: Ray Smets Date: Thu, 16 Apr 2026 09:24:25 -0700 Subject: [PATCH 19/20] fix: docs sync --- docs/src/content/docs/developer-guide/Introduction.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/src/content/docs/developer-guide/Introduction.md b/docs/src/content/docs/developer-guide/Introduction.md index b4b786a6..9410347b 100644 --- a/docs/src/content/docs/developer-guide/Introduction.md +++ b/docs/src/content/docs/developer-guide/Introduction.md @@ -13,4 +13,7 @@ The repository is organized around four main pieces: - **Agent runtime code** in Python under `agent/` — runtime entrypoint, task execution loop, memory writes, observability hooks, and local container tooling. - **Infrastructure as code** in AWS CDK under `cdk/src/` — stacks, constructs, and handlers that define and deploy the platform on AWS. - **Documentation site** under `docs/` — source guides/design docs plus the generated Astro/Starlight documentation site. -- **CLI package** under `cli/` — the `bgagent` command-line client used to authenticate, submit tasks, and inspect task status/events. \ No newline at end of file +- **CLI package** under `cli/` — the `bgagent` command-line client used to authenticate, submit tasks, and inspect task status/events. +- **Claude Code plugin** under `docs/abca-plugin/` — a [Claude Code plugin](https://docs.anthropic.com/en/docs/claude-code/plugins) with guided skills and agents for setup, deployment, task submission, and troubleshooting. See the [plugin README](/design/readme) for details. + +> **Tip:** If you use Claude Code, run `claude --plugin-dir docs/abca-plugin` from the repo root. The plugin's `/setup` skill walks you through the entire setup process interactively. \ No newline at end of file From 325edea679f563cb5332c64cdc22ca4fb29c7db2 Mon Sep 17 00:00:00 2001 From: Ray Smets Date: Thu, 16 Apr 2026 09:44:09 -0700 Subject: [PATCH 20/20] chore: removed redudant skills --- README.md | 10 ++--- docs/abca-plugin/README.md | 10 ++--- docs/abca-plugin/hooks/hooks.json | 2 +- docs/abca-plugin/skills/abca-submit/SKILL.md | 37 ------------------- .../skills/{abca-status => status}/SKILL.md | 2 +- docs/abca-plugin/skills/submit-task/SKILL.md | 10 ++++- 6 files changed, 19 insertions(+), 52 deletions(-) delete mode 100644 docs/abca-plugin/skills/abca-submit/SKILL.md rename docs/abca-plugin/skills/{abca-status => status}/SKILL.md (98%) diff --git a/README.md b/README.md index 61c12706..5fb92ebe 100644 --- a/README.md +++ b/README.md @@ -94,10 +94,9 @@ The `--plugin-dir` flag tells Claude Code to load the local plugin from the `doc | `setup` | "get started", "install", "first time setup" | Full guided setup: prerequisites, toolchain, deploy, smoke test | | `deploy` | "deploy", "cdk diff", "destroy" | Deploy, diff, or destroy the CDK stack with pre-checks | | `onboard-repo` | "add a repo", "onboard", 422 errors | Add a new GitHub repository via Blueprint construct | -| `submit-task` | "submit task", "run agent", "review PR" | Submit a coding task with prompt quality coaching | +| `submit-task` | "submit task", "run agent", "review PR", "quick submit" | Submit a coding task with prompt quality coaching (supports quick mode) | | `troubleshoot` | "debug", "error", "not working", "failed" | Diagnose deployment, auth, or task execution issues | -| `abca-status` | "status", "health check", "is ABCA running" | Quick platform health check: stack status, running tasks, build health | -| `abca-submit` | "submit task", "quick submit" | Shortcut for task submission with auto-detected task type | +| `status` | "status", "health check", "is ABCA running" | Platform health check: stack status, running tasks, build health | **Agents** (specialized subagents, spawned automatically or via the Agent tool): @@ -121,10 +120,9 @@ docs/abca-plugin/ setup/SKILL.md # First-time setup workflow deploy/SKILL.md # CDK deployment workflow onboard-repo/SKILL.md # Repository onboarding workflow - submit-task/SKILL.md # Task submission with prompt coaching + submit-task/SKILL.md # Task submission (guided + quick mode) troubleshoot/SKILL.md # Diagnostic workflow - abca-status/SKILL.md # Quick platform health check - abca-submit/SKILL.md # Quick task submission shortcut + status/SKILL.md # Platform health check agents/ cdk-expert.md # CDK infrastructure specialist agent-debugger.md # Task failure debugger diff --git a/docs/abca-plugin/README.md b/docs/abca-plugin/README.md index d20eda9a..8f47ee0c 100644 --- a/docs/abca-plugin/README.md +++ b/docs/abca-plugin/README.md @@ -25,10 +25,9 @@ Or add to your project's `.claude/settings.json`: | `/setup` | First-time setup, prerequisites | Walk through prerequisites, toolchain, and first deployment | | `/deploy` | Deploy, diff, destroy | Deploy, diff, or destroy the CDK stack | | `/onboard-repo` | Add a repository | Onboard a GitHub repo via Blueprint CDK construct | -| `/submit-task` | Submit a coding task | Submit tasks with prompt quality guidance and cost controls | +| `/submit-task` | Submit a coding task | Submit tasks with prompt quality guidance and cost controls (supports quick mode) | | `/troubleshoot` | Debug, errors, failures | Diagnose build, deployment, auth, and task execution issues | -| `/abca-status` | Status, health check | Check stack health, running tasks, and recent history | -| `/abca-submit` | Quick submit | Shortcut for rapid task submission | +| `/status` | Status, health check | Check stack health, running tasks, and recent history | ### Agents @@ -55,10 +54,9 @@ docs/abca-plugin/ setup/SKILL.md # First-time setup workflow deploy/SKILL.md # CDK deployment management onboard-repo/SKILL.md # Repository onboarding - submit-task/SKILL.md # Task submission workflow + submit-task/SKILL.md # Task submission workflow (guided + quick mode) troubleshoot/SKILL.md # Troubleshooting guide - abca-status/SKILL.md # Platform status checks - abca-submit/SKILL.md # Quick task submission + status/SKILL.md # Platform status checks ``` ## Testing diff --git a/docs/abca-plugin/hooks/hooks.json b/docs/abca-plugin/hooks/hooks.json index 340720a2..0e2bfdc9 100644 --- a/docs/abca-plugin/hooks/hooks.json +++ b/docs/abca-plugin/hooks/hooks.json @@ -3,7 +3,7 @@ "SessionStart": [ { "type": "prompt", - "prompt": "The ABCA plugin is active. Available skills:\n- /setup — first-time setup walkthrough\n- /deploy — deploy, diff, or destroy the CDK stack\n- /onboard-repo — add a GitHub repository\n- /submit-task — submit a coding task with prompt coaching\n- /troubleshoot — diagnose deployment, auth, or task issues\n- /abca-status — quick platform health check\n- /abca-submit — shortcut for rapid task submission\n\nAvailable agents: cdk-expert (CDK infrastructure), agent-debugger (task failure investigation).\n\nSuggest relevant skills when the user's request matches." + "prompt": "The ABCA plugin is active. Available skills:\n- /setup — first-time setup walkthrough\n- /deploy — deploy, diff, or destroy the CDK stack\n- /onboard-repo — add a GitHub repository\n- /submit-task — submit a coding task (guided or quick mode)\n- /troubleshoot — diagnose deployment, auth, or task issues\n- /status — platform health check (stack, tasks, build)\n\nAvailable agents: cdk-expert (CDK infrastructure), agent-debugger (task failure investigation).\n\nSuggest relevant skills when the user's request matches." } ] } diff --git a/docs/abca-plugin/skills/abca-submit/SKILL.md b/docs/abca-plugin/skills/abca-submit/SKILL.md deleted file mode 100644 index 723825d4..00000000 --- a/docs/abca-plugin/skills/abca-submit/SKILL.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -name: abca-submit -description: Quick task submission shortcut — submit a coding task with guided prompts. Use when the user says "submit task", "run agent on", "submit to ABCA", or "quick submit". -argument-hint: [description] -allowed-tools: - - Bash - - Read ---- - -# Quick Task Submission - -Submit a task to ABCA quickly. If arguments are missing, ask the user. - -## Collect Required Info - -If the repository is not provided, ask for the repository (owner/repo format). -If the description is not provided, ask what the agent should do. - -## Determine Task Type - -Parse the description to infer the type: -- If it looks like a PR number or mentions "review PR": use `--review-pr` -- If it mentions "iterate on PR" or "fix PR feedback": use `--pr` -- If it's an issue number (just a number): use `--issue` -- Otherwise: use `--task` with the text description - -## Submit - -```bash -node cli/lib/bin/bgagent.js submit \ - --repo $REPO \ - $FLAGS \ - --max-turns 100 \ - --wait -``` - -Show the task ID and status. If `--wait` is used, show the final outcome including PR URL if created. diff --git a/docs/abca-plugin/skills/abca-status/SKILL.md b/docs/abca-plugin/skills/status/SKILL.md similarity index 98% rename from docs/abca-plugin/skills/abca-status/SKILL.md rename to docs/abca-plugin/skills/status/SKILL.md index 661017f5..30777294 100644 --- a/docs/abca-plugin/skills/abca-status/SKILL.md +++ b/docs/abca-plugin/skills/status/SKILL.md @@ -1,5 +1,5 @@ --- -name: abca-status +name: status description: Check ABCA platform status — stack health, running tasks, and recent task history. Use when the user says "status", "health check", "is ABCA running", "check platform", or "what's the state". allowed-tools: - Bash diff --git a/docs/abca-plugin/skills/submit-task/SKILL.md b/docs/abca-plugin/skills/submit-task/SKILL.md index 1bd03630..505e8f87 100644 --- a/docs/abca-plugin/skills/submit-task/SKILL.md +++ b/docs/abca-plugin/skills/submit-task/SKILL.md @@ -4,13 +4,21 @@ description: >- Submit a coding task to the ABCA platform via CLI or REST API. Guides prompt quality, task type selection, and cost controls. Use when the user says "submit a task", "create a task", "run the agent", "send task to agent", "bgagent submit", - "new_task", "pr_iteration", "pr_review", "review a PR", or wants to automate coding work. + "new_task", "pr_iteration", "pr_review", "review a PR", "quick submit", + "submit to ABCA", or wants to automate coding work. +argument-hint: [description] --- # Submit a Coding Task You are helping the user submit a well-crafted coding task to the ABCA platform. Good prompts are critical — the agent works autonomously without asking clarifying questions. +**Quick mode:** If the user provided a repo and description inline (e.g. "submit task to owner/repo: fix the login bug"), auto-detect the task type from the description and skip to Step 5. Infer the type: +- PR number or "review PR" → `--review-pr` +- "iterate on PR" or "fix PR feedback" → `--pr` +- Just a number → `--issue` +- Otherwise → `--task` with the text description + ## Step 1: Determine Task Type Use AskUserQuestion to understand what the user wants: