feat(plugin): add Claude Code plugin with guided skills, agents, and hooks (#30)

* wip

* wip2

* name

* chore: gitignore Plans/ and remove from tracking

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* test(plugin): add testing strategy and fix agent-debugger path bug

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) <noreply@anthropic.com>

* docs(plugin): add README with testing strategy, slim TESTING.md to results

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* docs(plugin): remove standalone TESTING.md, strategy lives in README

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix(plugin): remove broken TESTING.md reference from README

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: hook

* gitignore

* opus

* chore: rm personal site from blueprint source

* feat: troubleshooting skill

* chore: true relative path

* chore: rm hooks

* fix: error handling

* refactor: moved plugin to docs dir

* feat: hook

* fix: docs sync

* chore: removed redudant skills

---------

Co-authored-by: bgagent <bgagent@noreply.github.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: Alain Krok <alkrok@amazon.com>

Author: 4 people

.gitignore

@@ -69,7 +69,76 @@ 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.
+
+#### Installing the plugin
+
+```bash
+git clone https://github.com/aws-samples/sample-autonomous-cloud-coding-agents.git
+cd sample-autonomous-cloud-coding-agents
+claude --plugin-dir docs/abca-plugin
+```
+
+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 docs/abca-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", "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 |
+| `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):
+
+| 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 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:
+
+```
+docs/abca-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 (guided + quick mode)
+    troubleshoot/SKILL.md        # Diagnostic workflow
+    status/SKILL.md              # Platform health check
+  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.
+
+### 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).
 

README.md

@@ -198,6 +198,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,

cdk/src/stacks/agent.ts

@@ -0,0 +1,106 @@
+# 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 docs/abca-plugin
+```
+
+Or add to your project's `.claude/settings.json`:
+
+```json
+{
+  "plugins": ["./docs/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 (supports quick mode) |
+| `/troubleshoot` | Debug, errors, failures | Diagnose build, deployment, auth, and task execution issues |
+| `/status` | Status, health check | Check stack health, running tasks, and recent history |
+
+### 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 |
+
+### Hook
+
+- **SessionStart** — Advertises available skills and agents so Claude can proactively suggest them when your request matches.
+
+## Plugin Structure
+
+```
+docs/abca-plugin/
+  plugin.json              # Plugin manifest
+  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
+    onboard-repo/SKILL.md  # Repository onboarding
+    submit-task/SKILL.md   # Task submission workflow (guided + quick mode)
+    troubleshoot/SKILL.md  # Troubleshooting guide
+    status/SKILL.md        # Platform status checks
+```
+
+## Testing
+
+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 |
+
+### Running the tests
+
+From the repo root with Claude Code:
+
+```
+claude --plugin-dir docs/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('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)'
+
+# Layer 3: Content — CLI flags match
+node cli/lib/bin/bgagent.js submit --help && node cli/lib/bin/bgagent.js list --help
+```
+
+## Development
+
+To modify the plugin:
+
+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