claude-dev-kit
An open-source Claude Code plugin by The Agile Monkeys: a stack-agnostic issue-to-PR workflow with enforced quality gates.
Give the coding-agent a user story ID from your tracker and it orchestrates the whole flow:
/work-story PROJ-1234
│
├─ issue-fetch → ticket summary + acceptance criteria + comments
├─ figma-fetch → design context (if the ticket links Figma)
├─ PLAN + user approval (mandatory gate)
├─ implement → follows the consuming repo's conventions & subagents
├─ coverage-check → touched files meet the project's bar (default ≥ 95%)
├─ e2e-generate → e2e tests (repo's framework) incl. edge cases
├─ security-reviewer → authorization / secrets / input / exposure pass (gate)
├─ pr-review → pr-fixer → self-review, then fix the blocking findings
├─ create-pr → branch + commit + PR with verification evidence
└─ issue-update → comment PR link on the ticket + move it to review
Install in one command:
npm create @theagilemonkeys/dev-kit
Interactive setup — tracker, Figma, telemetry consent, org — then it installs the plugin for you. Full options in Installing in Claude Code.
Stack-agnostic by design
The kit carries no assumptions about language, framework, or test runner. It reads everything stack-specific — build/test/lint/coverage commands, architecture conventions, and any implementer subagents — from the consuming repo's CLAUDE.md and .claude/, and detects conventions from the project when they aren't declared.
It ships baseline "iteration zero" profiles for common stacks in instructions/stacks/ — node, angular, react, vue, python, dotnet, java, go, ruby, php, rust — giving each one usable coverage/e2e/lint commands out of the box. Your CLAUDE.md always overrides them, and adding a stack is one markdown file (see CONTRIBUTING). These profiles are early and community-refined — treat an unlisted or unverified stack as "should work, help us confirm" rather than guaranteed.
It integrates with your tools through adapters, not hardcoded dependencies:
| Concern | Supported | How it's chosen |
|---|
| Issue tracker | Jira, Linear, GitHub Issues, Azure DevOps | Detected/asked once by dev-kit-setup, stored in .claude/dev-kit.json |
| PR host | GitHub (gh), Bitbucket (REST), GitLab (glab) | Detected from the origin remote, stored as prHost |
| Design (optional) | Figma | Activated when a ticket links a Figma URL |
Installing in Claude Code
The kit is a Claude Code plugin. Install it once per developer; it then loads in every session across every surface — the CLI, the desktop app, the VS Code / JetBrains extensions, and the web app (claude.ai/code).
Prerequisites: Claude Code (claude --version) and the GitHub CLI authenticated (gh auth status).
Install with npm (recommended)
npm create @theagilemonkeys/dev-kit
The wizard picks your issue tracker and whether you use Figma, shows exactly what anonymous telemetry would be collected and lets you opt in or out, sets your organisation label, writes .claude/dev-kit.json, and runs the plugin install for you. Then authorize your connectors (below) and you're done.
Manual install (what the wizard automates)
From a terminal — plugin management is CLI-only; the VS Code / JetBrains chat panels reject /plugin commands:
claude plugin marketplace add theam/claude-dev-kit
claude plugin install fullstack-dev-kit@claude-dev-kit
Installation is user-level and permanent — every future session (CLI or IDE extension) loads the kit automatically, no reinstall per session or project. Verify with claude plugin list, or type / in a session and search fullstack-dev-kit: (you should see work-story, launch-story, and the skills; agents show under /agents).
Authorize the connectors your team uses (one-time)
The plugin declares the tracker/design MCP servers (atlassian, linear, figma) — you don't add them by hand, you just authorize the ones you use. Three ways, pick whichever fits:
- In a Claude Code session (CLI, IDE panel, or the Desktop app's Code tab): run
/mcp, pick the server (e.g. atlassian), and complete the OAuth in the browser.
- From the terminal:
claude mcp login atlassian (and claude mcp list to check status — plugin-declared servers show ⏸ pending approval until first approved inside a session).
- Already connected in Claude Desktop? Import those connectors into Claude Code with
claude mcp add-from-claude-desktop (macOS/WSL).
| Tool | Connector | Authorize with |
|---|
| Jira | atlassian MCP | /mcp · claude mcp login atlassian |
| Linear | linear MCP | /mcp · claude mcp login linear |
| GitHub Issues | — (uses gh) | gh auth login |
| Azure DevOps | — (uses az) | az login |
| Figma (optional) | figma MCP | /mcp · claude mcp login figma |
Authorization is per developer, one-time — it persists across sessions. The kit then discovers the rest (Jira site, project key, field IDs) automatically on first use via dev-kit-setup.
When authorizing an MCP via OAuth, complete the browser flow immediately — the link is tied to a live local callback and expires with it. Don't reuse old tabs or restart the session mid-flow.
Enable auto-update
/plugin → Marketplaces tab → claude-dev-kit → Enable auto-update. New versions then arrive at session startup. To pull manually instead:
claude plugin marketplace update claude-dev-kit
Troubleshooting: if /work-story is unknown, the session started before the install — restart it (VS Code: Developer: Reload Window) and remember the namespace /fullstack-dev-kit:work-story. More cases in Troubleshooting below.
Team-wide install (optional — one config for everyone)
Instead of each developer running the two install commands, a consuming repo can commit the marketplace + plugin to its own .claude/settings.json. Teammates then get the kit when they open and trust the repo — in the CLI and the Desktop app's Code tab alike:
{
"extraKnownMarketplaces": {
"claude-dev-kit": {
"source": { "source": "github", "repo": "theam/claude-dev-kit" }
}
},
"enabledPlugins": {
"fullstack-dev-kit@claude-dev-kit": true
}
}
Pin to a release by adding "ref": "v0.5.0" (or a "sha") to source; omit it to always track the default branch. Requires the marketplace repo to be public (or teammates to have git access to it).
Heads-up: auto-load on folder-trust is the intended behavior, but a known Claude Code issue (#32606) means some setups still need a one-time manual claude plugin install fullstack-dev-kit@claude-dev-kit. Test with one teammate before rolling out to everyone.
First use — zero config
There is nothing to configure by hand. On first use in a repo, just ask for a ticket:
fetch PROJ-1234
The kit runs dev-kit-setup: it detects your tracker, discovers what it can (site/project/team/fields), asks only genuine choices, and persists the result to .claude/dev-kit.json — no secrets, safe to commit, so one setup serves the whole team. If that works, everything works.
Day-to-day usage
| You want to… | Type |
|---|
| Work a story end to end (current window) | /fullstack-dev-kit:work-story PROJ-1234 |
| Prepare a story worktree + new VS Code window | /fullstack-dev-kit:launch-story PROJ-1234 |
| Unattended run (no plan gate — pipelines only) | append --auto-approve |
| Review a PR or your current diff | /fullstack-dev-kit:pr-review #42 |
| Fix the findings on an existing PR | /fullstack-dev-kit:fix-pr #42 |
| Anything else | plain language — e.g. "use the pr-reviewer agent on PR #42" |
Notes:
- Plugin commands and skills are namespaced under
/fullstack-dev-kit: (type / and search). Agents never appear in that list — invoke them in plain language or let the orchestrator delegate to them (/agents shows them).
work-story presents its implementation plan in the chat and waits for your explicit approval before writing any code.- Reviews report in the conversation; nothing is approved or commented on the tracker/GitHub without your confirmation.
Try it without a ticket
You don't need a tracker (or a ticket) to use the kit — the ticket integration is a convenience for auto-reading acceptance criteria and updating status, not a requirement. The fastest ways to try it in ~30 seconds, no tracker/MCP setup:
- Review your current work:
/fullstack-dev-kit:pr-review on your working diff (or pr-review #42 on a PR).
- Drive the orchestrator from a description: in plain language, e.g. "use the coding-agent to add a
--dry-run flag to the export command" — it plans (you approve), implements, runs the applicable gates, and opens the PR, skipping the fetch/update-ticket steps.
- Use a single skill:
coverage-check, e2e-generate, or the security-reviewer agent on the change you have in progress.
Full /work-story <TICKET> flow is ticket-first (it fetches the story and moves it to review); everything else works ticketless. Teams with no tracker can set tracker: none in dev-kit-setup.
What's inside
| Component | Type | Purpose |
|---|
coding-agent | agent | Orchestrator: story ID → PR → updated ticket, with plan-approval gate |
pr-reviewer | agent | High-signal diff review: correctness, contract drift, security, tests |
pr-fixer | agent | Resolves review/CI findings, re-verifies gates, pushes |
security-reviewer | agent | Focused security pass: auth, secrets, input, exposure (gate) |
coverage-guardian | agent | Finds files under 95% and writes the missing tests |
e2e-author | agent | E2e tests in the repo's framework, with realistic edge cases |
dev-kit-setup | skill | First-use bootstrap: detects the tracker, writes .claude/dev-kit.json |
issue-fetch | skill | Ticket + acceptance criteria + comments (Jira/Linear/GitHub/Azure) |
issue-update | skill | Comment PR + evidence on the ticket, transition to review |
figma-fetch | skill | Frame hierarchy + text content from a Figma URL |
coverage-check | skill | Runs the repo's coverage command, enforces the project's coverage bar (default 95%) when it has one |
e2e-generate | skill | Playbook for creating/updating e2e tests |
create-pr | skill | Branch, commit, and PR — only after all gates pass |
pr-review | skill | Review playbook: findings by dimension, verdict, AC check |
fix-pr | skill | Playbook: findings → fixes → re-verified gates → push |
instructions/ | rules | Always-on, language-agnostic: secure coding, testing standards |
/work-story | command | Entry point: /work-story PROJ-1234 |
|
Quality gates
Always apply (regardless of stack or test setup):
- No code before the plan is approved (unless
--auto-approve for pipelines).
- Security pass (
security-reviewer) with no blocking findings.
- PR body carries the verification evidence; the ticket gets the PR link and moves to review.
Adaptive — enforce the project's own standard, detected each run (the kit never imposes tests or scaffolds a framework on a project that doesn't use one):
- If the project has tests/coverage: touched files meet its bar (default ≥ 95%) and don't regress; suites pass; lint clean.
- User-facing changes get e2e when the project already does e2e.
- No test/e2e/lint setup → the kit recommends it and says so in the PR — it doesn't block. Teams wanting a hard bar set a
gates policy (auto (default) · required · off) in .claude/dev-kit.json.
- Accessibility (frontend only): when a change touches user-facing UI in a frontend stack, the review automatically covers the a11y basics (alt text, labels, accessible names, keyboard/focus, contrast, correct ARIA) — using the repo's own a11y tooling if it has any, never scaffolding one. It's automatic and non-blocking by default, costs nothing on backend/non-UI changes, and needs no setup. To change it, set
"a11y" in .claude/dev-kit.json to auto (default) · required (make it a blocking gate) · off (never run) — edit it by hand, or just ask the kit to do it (e.g. "make accessibility a required gate") and it updates the file for you.
Either way, a skipped gate is reported, never hidden.
Relationship to project repos
Each consuming repo keeps its own .claude/ with project-specific rules: build/test/lint/coverage commands, architecture conventions, and stack subagents (e.g. backend-implementer / frontend-implementer). The kit reads the consuming repo's CLAUDE.md for those conventions and its own .claude/dev-kit.json (auto-generated on first use) for tracker specifics.
Parallel stories — one worktree per story
/work-story works in the current directory. To work several stories at once, use /launch-story PROJ-1234 per story: it creates a dedicated git worktree, opens a new VS Code window on it, and hands you the work-story command to paste there.
Caveat: stories whose e2e gates boot dev servers on fixed ports can collide if run at the exact same time — stagger them, or parameterize ports in the consuming repo.
Extending the kit
Adding a tracker, PR host, or design tool is an adapter, not a rewrite — see CONTRIBUTING.md for the worked example.
Telemetry (anonymous, opt-in, OFF by default)
The kit can share anonymous token counts so the maintainers can show aggregate impact. It is off by default; you opt in via the setup wizard (npm create @theagilemonkeys/dev-kit). Clients ship no API key and never call analytics directly — they POST to a relay that re-enforces a machine-readable contract and strips your IP before forwarding to PostHog. Events are anonymous (a random install_id); never prompts, code, file names, ticket contents, emails, or org-instance data — and only sessions where the kit actually ran. Kill switch: DEVKIT_TELEMETRY=0. Runs in the CLI, IDE extensions, and the Desktop app's Code tab (needs Node on PATH). Full details and the exact payload: TELEMETRY.md.
Troubleshooting
| Symptom | Cause / fix |
|---|
/plugin isn't available in this environment | You're in the VS Code chat panel — run plugin commands from a terminal with claude plugin … |
Unknown command: /work-story | Session started before the install/update — restart it (VS Code: Developer: Reload Window); remember the namespace /fullstack-dev-kit:work-story |
OAuth callback lands on a dead localhost:<port> | The link expired (session restarted mid-flow) — run /mcp again and complete the fresh link immediately |
| Update pulled but behavior unchanged | claude plugin install fullstack-dev-kit@claude-dev-kit to force the new version, then restart the session |
License
Apache 2.0 © The Agile Monkeys. See NOTICE.
Headless/CI runs can't do MCP OAuth. If automated pipeline runs become a requirement, a REST + token fallback can be added to the tracker adapters.
