Skip to content

Commit 601766f

Browse files
krokokokrokoko
authored
Merge branch 'main' into feat/26-harden-memory-inputs
2 parents ffd36bd + 7cef47c commit 601766f

18 files changed

Lines changed: 1141 additions & 26 deletions

File tree

‎.gitignore‎

Lines changed: 78 additions & 21 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎LEGAL_DISCLAIMER.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
2+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
3+
FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
4+
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
5+
IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
6+
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

‎README.md‎

Lines changed: 70 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -69,7 +69,76 @@ See the full [ROADMAP](./docs/guides/ROADMAP.md) for details on each iteration.
6969

7070
## Getting started
7171

72-
### Installation and deployment
72+
### Claude Code plugin (recommended)
73+
74+
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.
75+
76+
#### Installing the plugin
77+
78+
```bash
79+
git clone https://github.com/aws-samples/sample-autonomous-cloud-coding-agents.git
80+
cd sample-autonomous-cloud-coding-agents
81+
claude --plugin-dir docs/abca-plugin
82+
```
83+
84+
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.
85+
86+
> **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.
87+
88+
#### What the plugin provides
89+
90+
**Skills** (guided multi-step workflows — Claude activates these automatically based on your request):
91+
92+
| Skill | Triggers on | What it does |
93+
|-------|------------|--------------|
94+
| `setup` | "get started", "install", "first time setup" | Full guided setup: prerequisites, toolchain, deploy, smoke test |
95+
| `deploy` | "deploy", "cdk diff", "destroy" | Deploy, diff, or destroy the CDK stack with pre-checks |
96+
| `onboard-repo` | "add a repo", "onboard", 422 errors | Add a new GitHub repository via Blueprint construct |
97+
| `submit-task` | "submit task", "run agent", "review PR", "quick submit" | Submit a coding task with prompt quality coaching (supports quick mode) |
98+
| `troubleshoot` | "debug", "error", "not working", "failed" | Diagnose deployment, auth, or task execution issues |
99+
| `status` | "status", "health check", "is ABCA running" | Platform health check: stack status, running tasks, build health |
100+
101+
**Agents** (specialized subagents, spawned automatically or via the Agent tool):
102+
103+
| Agent | When it's used |
104+
|-------|---------------|
105+
| `cdk-expert` | CDK architecture, construct design, handler implementation, stack modifications |
106+
| `agent-debugger` | Task failure investigation, CloudWatch log analysis, agent runtime debugging |
107+
108+
**Hook** (runs automatically):
109+
110+
A `SessionStart` hook advertises available skills and agents so Claude can proactively suggest them when your request matches.
111+
112+
#### Local plugin development
113+
114+
If you're modifying the plugin itself, here's the file layout:
115+
116+
```
117+
docs/abca-plugin/
118+
plugin.json # Plugin manifest (name, version, description)
119+
skills/
120+
setup/SKILL.md # First-time setup workflow
121+
deploy/SKILL.md # CDK deployment workflow
122+
onboard-repo/SKILL.md # Repository onboarding workflow
123+
submit-task/SKILL.md # Task submission (guided + quick mode)
124+
troubleshoot/SKILL.md # Diagnostic workflow
125+
status/SKILL.md # Platform health check
126+
agents/
127+
cdk-expert.md # CDK infrastructure specialist
128+
agent-debugger.md # Task failure debugger
129+
hooks/
130+
hooks.json # SessionStart capability advertisement
131+
```
132+
133+
**Key conventions:**
134+
- The plugin lives under `docs/` to keep documentation and plugin content colocated
135+
- Skills live in subdirectories with a `SKILL.md` file (not flat `.md` files)
136+
- Agents are flat `.md` files with YAML frontmatter
137+
- The hook advertises plugin capabilities only (no project-specific content)
138+
139+
**After editing plugin files**, restart Claude Code with `claude --plugin-dir docs/abca-plugin` to pick up changes.
140+
141+
### Manual installation and deployment
73142

74143
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).
75144

‎agent/uv.lock‎

Lines changed: 3 additions & 3 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎cdk/src/stacks/agent.ts‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -198,6 +198,20 @@ export class AgentStack extends Stack {
198198
// Grant the runtime permissions to invoke the inference profile
199199
inferenceProfile.grantInvoke(runtime);
200200

201+
const model3 = new bedrock.BedrockFoundationModel('anthropic.claude-opus-4-20250514-v1:0', {
202+
supportsAgents: true,
203+
supportsCrossRegion: true,
204+
});
205+
206+
model3.grantInvoke(runtime);
207+
208+
const inferenceProfile3 = bedrock.CrossRegionInferenceProfile.fromConfig({
209+
geoRegion: bedrock.CrossRegionInferenceProfileRegion.US,
210+
model: model3,
211+
});
212+
213+
inferenceProfile3.grantInvoke(runtime);
214+
201215
const model2 = new bedrock.BedrockFoundationModel('anthropic.claude-haiku-4-5-20251001-v1:0', {
202216
supportsAgents: true,
203217
supportsCrossRegion: true,

‎docs/abca-plugin/README.md‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
# ABCA Plugin for Claude Code
2+
3+
A Claude Code plugin that provides guided workflows for setting up, deploying, operating, and troubleshooting the ABCA (Autonomous Background Coding Agents on AWS) platform.
4+
5+
## Installation
6+
7+
```bash
8+
claude --plugin-dir docs/abca-plugin
9+
```
10+
11+
Or add to your project's `.claude/settings.json`:
12+
13+
```json
14+
{
15+
"plugins": ["./docs/abca-plugin"]
16+
}
17+
```
18+
19+
## What's Included
20+
21+
### Skills (slash commands)
22+
23+
| Skill | Trigger | Description |
24+
|-------|---------|-------------|
25+
| `/setup` | First-time setup, prerequisites | Walk through prerequisites, toolchain, and first deployment |
26+
| `/deploy` | Deploy, diff, destroy | Deploy, diff, or destroy the CDK stack |
27+
| `/onboard-repo` | Add a repository | Onboard a GitHub repo via Blueprint CDK construct |
28+
| `/submit-task` | Submit a coding task | Submit tasks with prompt quality guidance and cost controls (supports quick mode) |
29+
| `/troubleshoot` | Debug, errors, failures | Diagnose build, deployment, auth, and task execution issues |
30+
| `/status` | Status, health check | Check stack health, running tasks, and recent history |
31+
32+
### Agents
33+
34+
| Agent | Model | Description |
35+
|-------|-------|-------------|
36+
| `cdk-expert` | Sonnet | AWS CDK infrastructure expert for construct design, handler implementation, and stack modifications |
37+
| `agent-debugger` | Sonnet | Read-only debugging specialist for task failures, preflight errors, and CloudWatch log analysis |
38+
39+
### Hook
40+
41+
- **SessionStart** — Advertises available skills and agents so Claude can proactively suggest them when your request matches.
42+
43+
## Plugin Structure
44+
45+
```
46+
docs/abca-plugin/
47+
plugin.json # Plugin manifest
48+
agents/
49+
cdk-expert.md # CDK infrastructure agent
50+
agent-debugger.md # Runtime debugging agent
51+
hooks/
52+
hooks.json # SessionStart capability advertisement
53+
skills/
54+
setup/SKILL.md # First-time setup workflow
55+
deploy/SKILL.md # CDK deployment management
56+
onboard-repo/SKILL.md # Repository onboarding
57+
submit-task/SKILL.md # Task submission workflow (guided + quick mode)
58+
troubleshoot/SKILL.md # Troubleshooting guide
59+
status/SKILL.md # Platform status checks
60+
```
61+
62+
## Testing
63+
64+
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:
65+
66+
| Layer | What it checks |
67+
|-------|---------------|
68+
| **1. Structural** | `plugin.json` fields, file discovery, JSON/YAML validity, no orphaned files |
69+
| **2. Agent Config** | Frontmatter fields (`model`, `tools`, `description`), valid tool names, file path accuracy, capability alignment with examples |
70+
| **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 |
71+
72+
### Running the tests
73+
74+
From the repo root with Claude Code:
75+
76+
```
77+
claude --plugin-dir docs/abca-plugin
78+
```
79+
80+
Then ask Claude to validate the plugin:
81+
82+
```
83+
Validate the abca-plugin using the plugin-validator agent, then verify
84+
all command references and file paths in the skills are accurate.
85+
```
86+
87+
Or run the checks manually:
88+
89+
```bash
90+
# Layer 1: Structural — valid JSON
91+
python3 -c "import json; json.load(open('docs/abca-plugin/plugin.json')); print('plugin.json OK')"
92+
93+
# Layer 3: Content — mise tasks exist
94+
MISE_EXPERIMENTAL=1 mise tasks --all 2>/dev/null | grep -E '(build|install|compile|test|deploy|destroy|diff|synth|bootstrap)'
95+
96+
# Layer 3: Content — CLI flags match
97+
node cli/lib/bin/bgagent.js submit --help && node cli/lib/bin/bgagent.js list --help
98+
```
99+
100+
## Development
101+
102+
To modify the plugin:
103+
104+
1. Edit the relevant `.md` file under `skills/` or `agents/`
105+
2. Re-validate using the testing strategy above
106+
3. Ensure any new file paths or commands you reference actually exist in the repo

0 commit comments

Comments
 (0)