Skip to content

Commit 31bc2cf

Browse files
bgagentclaude
bgagent
and
claude
committed
docs(plugin): add README with testing strategy, slim TESTING.md to results
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent bab8794 commit 31bc2cf

2 files changed

Lines changed: 118 additions & 52 deletions

File tree

‎abca-plugin/README.md‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
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 abca-plugin
9+
```
10+
11+
Or add to your project's `.claude/settings.json`:
12+
13+
```json
14+
{
15+
"plugins": ["./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 |
29+
| `/troubleshoot` | Debug, errors, failures | Diagnose build, deployment, auth, and task execution issues |
30+
| `/abca-status` | Status, health check | Check stack health, running tasks, and recent history |
31+
| `/abca-submit` | Quick submit | Shortcut for rapid task submission |
32+
33+
### Agents
34+
35+
| Agent | Model | Description |
36+
|-------|-------|-------------|
37+
| `cdk-expert` | Sonnet | AWS CDK infrastructure expert for construct design, handler implementation, and stack modifications |
38+
| `agent-debugger` | Sonnet | Read-only debugging specialist for task failures, preflight errors, and CloudWatch log analysis |
39+
40+
### Hooks
41+
42+
- **SessionStart** — Injects ABCA project context (directory structure, key commands, task types, available skills/agents) into every Claude Code session.
43+
44+
## Plugin Structure
45+
46+
```
47+
abca-plugin/
48+
plugin.json # Plugin manifest
49+
agents/
50+
cdk-expert.md # CDK infrastructure agent
51+
agent-debugger.md # Runtime debugging agent
52+
hooks/
53+
hooks.json # SessionStart context injection
54+
skills/
55+
setup/SKILL.md # First-time setup workflow
56+
deploy/SKILL.md # CDK deployment management
57+
onboard-repo/SKILL.md # Repository onboarding
58+
submit-task/SKILL.md # Task submission workflow
59+
troubleshoot/SKILL.md # Troubleshooting guide
60+
abca-status/SKILL.md # Platform status checks
61+
abca-submit/SKILL.md # Quick task submission
62+
```
63+
64+
## Testing
65+
66+
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:
67+
68+
| Layer | What it checks |
69+
|-------|---------------|
70+
| **1. Structural** | `plugin.json` fields, file discovery, JSON/YAML validity, no orphaned files |
71+
| **2. Agent Config** | Frontmatter fields (`model`, `tools`, `description`), valid tool names, file path accuracy, capability alignment with examples |
72+
| **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 |
73+
| **4. Hooks** | `hooks.json` structure, supported event names, skills/agents listed in hook content all exist, no sensitive data |
74+
75+
### Running the tests
76+
77+
From the repo root with Claude Code:
78+
79+
```
80+
claude --plugin-dir abca-plugin
81+
```
82+
83+
Then ask Claude to validate the plugin:
84+
85+
```
86+
Validate the abca-plugin using the plugin-validator agent, then verify
87+
all command references and file paths in the skills are accurate.
88+
```
89+
90+
Or run the checks manually:
91+
92+
```bash
93+
# Layer 1: Structural — valid JSON
94+
python3 -c "import json; json.load(open('abca-plugin/plugin.json')); print('plugin.json OK')"
95+
python3 -c "import json; json.load(open('abca-plugin/hooks/hooks.json')); print('hooks.json OK')"
96+
97+
# Layer 3: Content — mise tasks exist
98+
MISE_EXPERIMENTAL=1 mise tasks --all 2>/dev/null | grep -E '(build|install|compile|test|deploy|destroy|diff|synth|bootstrap)'
99+
100+
# Layer 3: Content — CLI flags match
101+
cd cli && node lib/bin/bgagent.js submit --help && node lib/bin/bgagent.js list --help
102+
```
103+
104+
Full test results are documented in [`TESTING.md`](./TESTING.md).
105+
106+
## Development
107+
108+
To modify the plugin:
109+
110+
1. Edit the relevant `.md` file under `skills/`, `agents/`, or `hooks/`
111+
2. Re-validate using the testing strategy above
112+
3. Ensure any new file paths or commands you reference actually exist in the repo
113+
4. Keep the `SessionStart` hook prompt in sync if you add/remove/rename skills or agents

‎abca-plugin/TESTING.md‎

Lines changed: 5 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -1,58 +1,11 @@
1-
# ABCA Plugin — Testing Strategy & Results
1+
# ABCA Plugin — Test Results
22

3-
> Testing report for the Claude Code plugin at `abca-plugin/`.
3+
> Test report for the Claude Code plugin at `abca-plugin/`.
44
> Generated: 2026-04-14
5+
>
6+
> For the testing strategy and how to run these checks, see [`README.md`](./README.md#testing).
57
6-
## Testing Strategy
7-
8-
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**:
9-
10-
### Layer 1: Structural Validation
11-
Verify the plugin manifest, file organization, and component discovery.
12-
13-
| Check | Description |
14-
|-------|-------------|
15-
| Manifest validity | `plugin.json` has required fields (`name`, `version`, `description`, `author`) |
16-
| Component discovery | All agents, skills, and hooks are in correct directories |
17-
| No orphaned files | Every file belongs to a recognized plugin component |
18-
| Valid JSON | `plugin.json` and `hooks.json` parse without errors |
19-
| Valid YAML frontmatter | All `.md` components have parseable frontmatter |
20-
21-
### Layer 2: Agent Configuration Validation
22-
Verify agent definitions are well-formed and reference valid resources.
23-
24-
| Check | Description |
25-
|-------|-------------|
26-
| Required frontmatter | Each agent has `model`, `description`, `tools` |
27-
| Valid model values | Model is `opus`, `sonnet`, or `haiku` |
28-
| Valid tool names | All tools are recognized Claude Code tools |
29-
| File path accuracy | Paths in system prompts exist in the repo |
30-
| Capability alignment | Examples match declared tools (e.g., debug agent has no Edit/Write) |
31-
32-
### Layer 3: Content Integrity Verification
33-
Verify that all commands, paths, and cross-references in skill content are accurate.
34-
35-
| Check | Description |
36-
|-------|-------------|
37-
| File path references | All referenced repo paths exist |
38-
| Mise task references | All `mise run` commands map to valid tasks |
39-
| CLI command accuracy | All `bgagent` commands/flags match the actual CLI |
40-
| Skill cross-references | Skills referencing other skills point to ones that exist |
41-
| AWS CLI syntax | AWS CLI commands use valid subcommands |
42-
43-
### Layer 4: Hook Validation
44-
Verify hook configuration is correct and content is accurate.
45-
46-
| Check | Description |
47-
|-------|-------------|
48-
| JSON structure | `hooks.json` has valid structure |
49-
| Event names | Hook events are supported by Claude Code |
50-
| Content accuracy | Skills and agents listed in hook prompt all exist |
51-
| No sensitive data | No credentials or secrets in hook prompts |
52-
53-
---
54-
55-
## Test Results
8+
## Results
569

5710
### Layer 1: Structural Validation — PASS
5811

0 commit comments

Comments
 (0)