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

README.md

@@ -69,7 +69,78 @@ 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 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.
+
+> **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
+
+**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 |
+| `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):
+
+| 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:
+
+```
+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 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
+  hooks/
+    hooks.json                   # SessionStart hook configuration
+```
+
+**Key conventions:**
+- All plugin components live inside `abca-plugin/` alongside the manifest
+- 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.
+
+### 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).
 

abca-plugin/README.md

@@ -0,0 +1,111 @@
+# 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
+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/`, `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