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

[rsmets]

Summary

Adds a Claude Code plugin (docs/abca-plugin/) that gives developers guided workflows for setting up, deploying, operating, and troubleshooting the ABCA platform, directly from their IDE or terminal.

In response to Issue #17.

• 6 skills: setup, deploy, onboard-repo, submit-task, troubleshoot, status
• 2 agents: cdk-expert (infrastructure work), agent-debugger (task failure investigation)
• 1 hook: SessionStart advertises available skills and agents for discoverability

How to use

claude --plugin-dir docs/abca-plugin

Area

• docs — guides or design sources (docs/guides/, docs/design/)
• tooling — root mise.toml, scripts, CI workflows

Changes

• Created docs/abca-plugin/ directory with plugin.json manifest (colocated with docs for content coupling)
• Added 6 skills as SKILL.md files with trigger descriptions and step-by-step workflows
• Added 2 agents with model/color/example frontmatter per plugin spec
• Added SessionStart hook for plugin capability advertisement (no project-specific content)
• Added README.md with plugin docs, structure, and testing strategy
• Updated root README.md with plugin installation, usage, and development docs
• Updated docs/guides/DEVELOPER_GUIDE.md to reference the plugin
• Fixed 2>/dev/null → 2>&1 in status skill to surface real errors
• Added Opus as a model option to the agent cdk stack source

Testing

46 checks executed, 45 passed, 1 failed (fixed in bab8794).

Testing strategy and how to reproduce: docs/abca-plugin/README.md#testing

Acknowledgment

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of the project license.

[krokoko]

@rsmets are you still testing this ? Or we can switch it to ready for review ?

[rsmets]

@rsmets are you still testing this ? Or we can switch it to ready for review ?

I am still testing... I used it to get myself setup yesterday then had to switch gears. Now testing the post setup semantic interface.

[rsmets]

@krokoko thanks for keeping this branch's trunk up to date with main👍🏼

[rsmets]

Plugin Testing Results

Ran a 4-layer validation (structural, agent config, content integrity, hooks) across all plugin components.

46 checks executed, 45 passed, 1 failed (fixed in bab8794).

Testing strategy: abca-plugin/README.md#testing

Layer 1: Structural Validation — PASS (9/9)

Check	Result
plugin.json valid JSON	PASS
name field (kebab-case)	PASS
version field (semver)	PASS
description field	PASS
author field	PASS
Agent files discovered (2)	PASS
Skill files discovered (7)	PASS
Hook file discovered	PASS
No orphaned files	PASS

Layer 2: Agent Configuration — PASS (1 bug found and fixed)

cdk-expert.md — All PASS

agent-debugger.md — 1 issue:

• agent/prompts/ referenced but correct path is agent/src/prompts/ — fixed in bab8794

Layer 3: Content Integrity — PASS (25/25)

• 6/6 file paths exist (cli/lib/bin/bgagent.js, cdk/src/stacks/agent.ts, etc.)
• 10/10 mise tasks are valid (build, install, //cdk:compile, //cdk:test, etc.)
• 6/6 CLI commands verified against actual bgagent --help output
• 3/3 skill cross-references resolve to existing skills

Layer 4: Hook Validation — PASS (6/6)

Check	Result
Valid JSON structure	PASS
SessionStart event supported	PASS
Hook type prompt valid	PASS
All 7 skills listed exist	PASS
Both agents listed exist	PASS
No sensitive data	PASS

[krokoko]

Np thanks ! Just wanted to check in case you were waiting for me on an approval :)

[rsmets]

@krokoko I believe that this PR is now ready for review (and merge). Feel free to edit as you see fit.

[rsmets]

@krokoko I am actually running into 503 bedrock errors submitting a task in a fresh AWS account. I feel like this maybe model quota related (I was using Opus). I added some of this info to the troubleshooting skill but unclear if that is really the root cause.

{
            "logStreamName": "trajectory/01KP75W2MKNBH82R5FYYDPQ6PY",
            "timestamp": 1776210863759,
            "message": "{\"event\": \"TRAJECTORY_TURN\", \"task_id\": \"01KP75W2MKNBH82R5FYYDPQ6PY\", \"turn\": 1, \"model\": \"<synthetic>\", \"thinking\": \"\", \"text\": \"API Error: 503 Too many connections, please wait before trying again.\", \"tool_calls\": [], \"tool_results\": []}",
            "ingestionTime": 1776210863766, "eventId": "39610825891551450069986979437098283030052058757434966016"
},

[rsmets]

Well good news... I got it up and running and interfacing with strictly through a semantic Claude code interface with the help of the plugin 👍🏼

i.e rsmets/personal-site#7

[rsmets]

FWIW the way I author my PRs squashing my commits in the merge is the way to go IMO.

[krokoko]

Looking at it now

[krokoko]

One question or thought for later: we will need a way to sync all this content as we make changes
Now we have documentation in code, under docs, and in the plugin
Probably have one source of truth which vends content in the different folders to ensure correctness and freshness

[krokoko]

The plugin content is well-crafted with genuinely useful guided workflows, and the .gitignore rewrite is a net improvement. Thanks !

[rsmets]

One question or thought for later: we will need a way to sync all this content as we make changes Now we have documentation in code, under docs, and in the plugin Probably have one source of truth which vends content in the different folders to ensure correctness and freshness

Yeah I agree that there is a bit fragmentation. I think the cleanest move is to relocate the plugin under docs/ so there's a clearer coupling between the documentation and the plugin's guided workflows. That way changes to docs naturally surface the plugin as needing updates too. Happy to track that as a follow-up issue.