Skip to content

Contributing

How to develop, test, and release the dev-team and security-assessment plugins. To use the plugins, see the README and the Getting Started tutorial.

Repository layout

.claude-plugin/marketplace.json    # marketplace catalog (the published plugin list)
plugins/dev-team/                  # the dev-team plugin source
plugins/security-assessment/       # the security companion plugin
docs/                              # repo-level documentation
evals/                            # eval fixtures and harnesses (not shipped)

Edit plugin components directly under plugins/<plugin>/ (agents, skills, hooks, knowledge, templates, docs). See plugins/dev-team/CLAUDE.md for the orchestration pipeline.

Local development

Two ways to run the plugins from your working tree.

Quick test install (committed state)

Register the local checkout as a marketplace, then install from it into a test project:

claude plugin marketplace add /path/to/agentic-dev-team
claude plugin install --scope project dev-team@bfinster
claude plugin install --scope project security-assessment@bfinster

Because the marketplace entries use a git-subdir source, this serves each plugin from its git ref — good for smoke-testing a release, but it does not reflect uncommitted edits.

To have Claude Code pick up local edits immediately, three paths must point at your local repo (/path/to/agentic-dev-team). Claude Code reads plugin commands from the marketplace directory at startup, so a stale clone there will shadow your changes:

  1. ~/.claude/plugins/installed_plugins.json — set the plugin's installPath to the local repo.
  2. ~/.claude/plugins/known_marketplaces.json — set installLocation to the local repo.
  3. ~/.claude/plugins/marketplaces/<marketplace-dir> — replace the cloned directory with a symlink to the local repo:
rm -rf ~/.claude/plugins/marketplaces/agentic-dev-team
ln -s /path/to/agentic-dev-team ~/.claude/plugins/marketplaces/agentic-dev-team

Also delete ~/.claude/plugins/cache/agentic-dev-team/ — it can regenerate from stale data. Restart Claude Code after changing these paths.

Skipping any of the three leaves a stale clone that silently shadows your edits — the failure mode is "my change isn't taking effect." If in doubt, check all three before debugging the plugin itself.

Testing

Agents and hooks (dev-team)

/agent-eval                                              # full eval suite
/agent-eval plugins/dev-team/agents/naming-review.md     # one agent
/agent-audit                                             # structural compliance

Run /agent-audit after any agent, skill, or hook change. Run /agent-eval after changing a review agent to check detection accuracy against the eval corpus.

Comparative-testing harness (security-assessment)

Regression-test the /security-assessment pipeline against a seeded fixture and reference baseline:

python3 evals/comparative/score.py \
  --reference evals/comparative/reference-baseline/2026-04-21 \
  --ours memory

See comparative testing for the scoring methodology.

Adding agents and skills

Scaffold a new agent (review or team) with the authoring command:

/agent-add <description or URL to a coding standard>

/agent-add scaffolds the file, checks for scope overlap with existing agents, runs /agent-audit, creates eval fixtures, and registers the agent. For the templates, schema, and registration steps, see:

  • Agents — team-agent and review-agent templates; add, remove, or customize agents
  • Skills & Commands — skill template; add a knowledge or user-invocable (slash-command) skill
  • the agent-skill-authoring skill — conventions, anti-patterns, and the agent-vs-skill philosophy

Every new or changed agent/skill/hook must pass /agent-audit.

Documentation diagrams

The docs use three diagram formats, each for a distinct purpose — match the convention when adding or editing a diagram:

  • Mermaid (```mermaid fences) — the default for flow, sequence, and architecture diagrams authored inline. It is text-based (diffs cleanly), renders on GitHub natively, and renders on the docs site (Material loads Mermaid.js via the pymdownx.superfences custom fence in mkdocs.yml). Reuse the shared %%{init ...}%% theme block from an existing diagram (e.g. plugins/dev-team/docs/model-routing.md) so diagrams look consistent.
  • SVG (plugins/dev-team/docs/diagrams/*.svg) — reserved for the polished, hand-tuned architecture diagrams that are laid out deliberately and tuned for dark mode. Don't auto-convert these to Mermaid; edit the SVG.
  • ASCII (plain ``` fences) — only for directory/file trees and short inline command flows, never for boxes-and-arrows diagrams (use Mermaid for those).

Releasing

Releases are managed by release-please. Push conventional commits to main:

  • feat: → minor version bump
  • fix: → patch version bump
  • feat!: or BREAKING CHANGE: → major version bump

A release PR is opened automatically; merging it creates a GitHub Release with a version tag. The marketplace catalog serves only tagged releases.