Scaffold for legible, reviewable AI-assisted development. Claude generates. Your team decides. MCP-native — read CDK governance state from Claude Desktop, ChatGPT, Cursor, VS Code.
Claude Code is a powerful CLI that reads, writes, and reasons about your entire codebase. Without shared process, it makes autonomous decisions that are hard to track and harder to review.
claude-dev-kit scaffolds a structured, reviewable development process on top of Claude Code. It enforces one non-negotiable rule mechanically: Claude cannot declare a task complete until your tests pass. Everything else scales with your needs.
Since v1.17.0, CDK ships an MCP server alongside the CLI. Any MCP-aware client can read your project's doctor report, team-settings policy, last arch-audit, and skill inventory without anyone running the CDK CLI. See MCP server.
npx mg-claude-dev-kit initThe wizard detects your project state and guides you through setup. Three paths available:
| Path | Use when |
|---|---|
| Existing project | Add structure to a project that already has code |
| New project | Starting from scratch |
| From existing docs | Share repos or docs - Claude reads them and populates everything |
After init, open Claude Code and start working. The scaffold is active immediately.
| Tier | Pipeline | Best for |
|---|---|---|
| 0 - Discovery | Stop hook only | First exploration - zero process |
| S - Fast Lane | 4 steps, scope-confirm | Single dev, low risk, quick fixes |
| M - Standard | 8 phases, 2 STOP gates | Feature blocks, 1-2 collaborators |
| L - Full | 14 phases, 4 STOP gates | Team projects, complex domain changes |
Start at Tier 0. Move up when you need more structure: npx mg-claude-dev-kit upgrade --tier=m
Executable multi-step programs that run inside Claude Code. Not prompt instructions - structured audit workflows with model routing (haiku for mechanical checks, sonnet for analysis).
| Skill | Tiers | Purpose |
|---|---|---|
/arch-audit |
S M L | Governance files vs Anthropic docs. Auto-fixes deprecations. |
/security-audit |
S M L | Auth, input validation, RLS, CVE scan. 3-path: WEB / NATIVE / HYBRID. MCP-aware (v1.20+): Step 3c queries mcp-nvd server for live CVE data with local audit fallback. |
/perf-audit |
S M L | Bundle size, serial awaits, query efficiency. 8-stack patterns. |
/skill-dev |
S M L | Coupling, duplication, dead code, debt-density. Step 3b (v1.22+): hotspot priority via churn × debt — top-10 ranked by 4-quadrant matrix using git log --since="6.months.ago". |
/simplify |
S M L | Early returns, nesting, dead code. Applies changes directly. |
/commit |
S M L | Conventional Commits - auto-detects type, scope, description. |
/api-design |
M L | URL naming, HTTP verbs, response envelope, pagination. |
/skill-db |
M L | Schema normalization, indexes, N+1 queries, RLS. |
/migration-audit |
M L | Stack-aware migration safety: data loss, rollback, lock-heavy DDL. Prisma/Drizzle/Supabase/SQL. |
/visual-audit |
M L | Typography, spacing, hierarchy, dark-mode, micro-polish. |
/ux-audit |
M L | ISO 9241-11, Nielsen heuristics, user confidence. |
/responsive-audit |
M L | Layout at 320-1024px, tap targets, WCAG. |
/ui-audit |
M L | Design token compliance, component adoption, empty states. |
/accessibility-audit |
M L | axe-core WCAG 2.2, APCA contrast, static a11y (aria, tabindex, focus, labels). |
/test-audit |
M L | Coverage (lcov/Istanbul/Cobertura/go/tarpaulin/xcresult), pyramid shape, anti-patterns (.only, skipped, empty, no-assertion, sleeps). |
/doc-audit |
M L | Doc drift: link resolution, code-block syntax (json/yaml/toml), CDK placeholder residuals, slash-command name match, skill-count consistency, ADR freshness, stack-sync (Next.js/Django/Swift). |
/api-contract-audit |
M L | OpenAPI contract drift (endpoints, schemas, status), breaking-change detection vs previous spec, versioning consistency, security scheme alignment, Richardson Maturity L0-L3 scoring. Auto-gen for FastAPI / NestJS / Express+swagger-jsdoc / Next.js route handlers / Django REST. |
/infra-audit |
M L | Infrastructure security across GitHub Actions (pwn-request, secret logging, pinning, permissions), Dockerfile (root, latest tag, URL add), K8s (runAsNonRoot, privileged, hostNetwork), Terraform (IAM wildcards, state in git), GitLab CI. Stack-agnostic. |
/compliance-audit |
M L | GDPR profile: data-subject rights (delete, export, rectify), consent, lawful basis, PII identification, encryption-at-rest on special-category, logging hygiene, retention, sub-processors. SOC 2 / HIPAA scaffolded for v1.15+. |
/dependency-audit |
M L | Outdated package audit: Tier A (safe batch) / B (non-core major) / C (core/breaking-risk) classification, changelog summary for Tier B/C, codebase impact grep, runtime LTS status. Stack-aware (node-ts/python/swift); agnostic fallback for other stacks. Audit-only in v1; mutating apply-tier-a deferred to Q4. MCP-aware (v1.20+): Step 2 queries package-registry-mcp for multi-ecosystem package metadata with WebFetch fallback. |
/pr-review |
M L | Autonomous local PR review via gh CLI: spawns review subagent on the diff, classifies findings (Critical / Major / Minor) using universal + stack-specific severity criteria, posts review as PR comment for audit trail. Configurable via team-settings.json prReviewSeverity. Read-only. --deep escalates to opus for sensitive changes. Also exposed as cdk_pr_review MCP tool. |
/skill-review |
M L | Quality review pipeline for skill portfolios. Spec compliance, cross-tier coherence, behavioral fixtures. |
Skills are conditionally installed based on your project: hasApi, hasDatabase, hasFrontend, hasDesignSystem.
Node.js/TS, Node.js/JS, Python, Go, Swift, Kotlin, Rust, .NET, Ruby, Java - plus generic fallback. Security rules, permissions, and CLAUDE.md fields adapt automatically.
The mg-claude-dev-kit package ships an MCP server (claude-dev-kit-mcp binary) alongside the CLI, version-locked, single npm install -g. Any MCP-aware client (Claude Desktop, ChatGPT desktop, Cursor, VS Code, Copilot Studio) can query CDK governance state without the CDK CLI running. Five read-only tools cover doctor report, team-settings, last arch-audit, skill inventory, and package metadata. Full reference in the MCP server section below.
Install individual components without a full scaffold:
npx mg-claude-dev-kit add skill security-audit # install one skill
npx mg-claude-dev-kit add rule git # install one rule
npx mg-claude-dev-kit add rule security --stack swift # stack-specific variantCustom skills (custom-* prefix) are preserved across upgrades. See Custom Skills Guide.
your-project/
├── CLAUDE.md # Project context (<200 lines)
├── .claude/
│ ├── settings.json # Permissions + Stop hook (mechanical enforcement)
│ ├── team-settings.json # Team policy: minTier / allowed / blocked / required (v1.16+)
│ ├── rules/
│ │ ├── pipeline.md # Development workflow (tier-appropriate)
│ │ ├── security.md # Stack-aware: web / apple / android / systems
│ │ ├── git.md # Commit format, branch rules
│ │ └── output-style.md # Communication rules
│ ├── skills/ # Audit skills (conditional per project)
│ ├── session/ # Session recovery (gitignored)
│ └── .mcp.json # Wire claude-dev-kit-mcp into MCP-aware clients (v1.17+)
├── docs/ # Requirements, specs, backlog (M/L)
├── .github/ # PR template, CODEOWNERS
└── .pre-commit-config.yaml # Secret scanning
The Stop hook in settings.json is the core enforcement mechanism. It blocks Claude from completing any task until tests pass. Present in every tier, including Discovery.
npx mg-claude-dev-kit init # scaffold wizard
npx mg-claude-dev-kit init --dry-run # preview without writing
npx mg-claude-dev-kit init --answers file.json # skip prompts (CI/automation)
npx mg-claude-dev-kit doctor # validate setup (28 checks)
npx mg-claude-dev-kit doctor --report # JSON output for CI
npx mg-claude-dev-kit doctor --ci # silent, exit 1 on failure
npx mg-claude-dev-kit upgrade # update template files
npx mg-claude-dev-kit upgrade --tier=m # promote to higher tier
npx mg-claude-dev-kit upgrade --anthropic # show diff for Anthropic-influenced files (dry-run)
npx mg-claude-dev-kit upgrade --anthropic --apply # write the diff (with .bak backup)
npx mg-claude-dev-kit add skill <name> # install one skill
npx mg-claude-dev-kit add rule <name> # install one rule
npx mg-claude-dev-kit new skill # create a custom skill (wizard)
claude-dev-kit-mcp # MCP server (stdio); wire from .mcp.jsonclaude-dev-kit-mcp is a Model Context Protocol server that exposes CDK governance signals to any MCP-aware client (Claude Desktop, ChatGPT desktop, Cursor, VS Code, Copilot Studio). The CLI and MCP server ship in the same npm package, version-locked.
Wire it up by adding to .mcp.json (project-scoped) or ~/.claude/.mcp.json (user-scoped):
{
"mcpServers": {
"cdk": { "command": "claude-dev-kit-mcp" }
}
}Read-only tools exposed:
| Tool | Returns |
|---|---|
cdk_doctor_report |
doctor --report JSON (28 checks) |
cdk_team_settings |
parsed .claude/team-settings.json |
cdk_arch_audit_status |
last arch-audit run timestamp + age |
cdk_skill_inventory |
installed skills + frontmatter snapshot |
cdk_package_meta |
CDK package name, version, CLI path, cwd |
cdk_pr_review |
reads existing /pr-review skill comments on a GitHub PR (verdict, severity counts). Read-only — to generate a fresh review, invoke the /pr-review CDK skill. |
The server resolves the project root from $CDK_PROJECT_ROOT if set, otherwise from process.cwd(). No mutating tools in v1.17.0 by design.
Stop hook (every tier) - Claude cannot declare done until tests pass:
"Stop": [{ "hooks": [{ "type": "command",
"command": "npm test || echo '{\"decision\": \"block\", \"reason\": \"Tests must pass.\"}'"
}] }]STOP gates (Tier M/L) - Requirements reviewed before implementation. Spec-first or scope-confirm mode auto-selected per block.
Audit logging - Every tool use appended to ~/.claude/audit/project.jsonl.
AI attribution - Every Claude-assisted commit tagged with Co-authored-by.
Weekly arch-audit - SessionStart hook checks if /arch-audit ran in the last 7 days.
CODEOWNERS - Changes to .claude/ require tech lead review.
node packages/cli/test/integration/run.js # 1129 integration checks
node --test packages/cli/test/unit/*.test.js # 373 unit testsCovers: file structure per tier, Stop hook presence, pipeline gate counts, placeholder resolution, skill pruning, security variant selection, native stack adaptation, rubric scoring, cross-stack content invariants (10 stacks), golden-file assertions (Swift, Node-TS, Python), full CLI execution via --answers fixtures.
- Node.js >= 22
- Claude Code CLI
- Git
| Document | Audience | Content |
|---|---|---|
| Operational Guide | Teams adopting CDK | Full reference: installation, tiers, workflow, governance, FAQ |
| Custom Skills Guide | Developers extending CDK | SKILL.md format, frontmatter schema, authoring patterns |
| Product Brief | Stakeholders | Strategic positioning, target users, scope |
| Quality Rubric | Teams evaluating workspaces | 8-dimension scoring (D1-D8, 0-100%) |
See GitHub Milestones for the 12-month plan.
Current: v1.22.0 ships the /skill-dev v2 hotspot enhancement — the differentiating piece of the closed /debt-triage sub-track (Issue #97 sub-track 2), folded into /skill-dev per the 2026-04-28 cross-LLM verdict. New Step 3b "Hotspot priority (churn × debt)" intersects per-file debt count with git log --since="6.months.ago" --numstat churn data, ranks files into a 4-quadrant matrix (Q1 hot mess / Q2 stable rot / Q3 flaky frontier / Q4 cold corner), and renders a top-10 hotspot table in the audit report. The hotspot section does NOT change which findings get added to the backlog (Step 4 still applies the same severity rules) — it re-orders backlog work by leverage. Stack-agnostic; gracefully skips on non-Git projects or projects with insufficient signal. Integration: 1129 checks (+15 from scenarioSkillDevHotspot). The v1.21.0 PreToolUse runtime enforcement remains in place; v1.20.0 MCP-aware audit skills (/security-audit + /dependency-audit) remain pinned to mcp-nvd and package-registry-mcp.
Next: /arch-audit MCP-aware once the upstream Anthropic spec MCP server lands. /privacy-audit re-eval (Issue #97 sub-track 3) when AST tracing matures or demand signal materializes. Q2 #3 VitePress docs site (ICE 432) stays on hold.
See CONTRIBUTING.md for development setup, project structure, and PR guidelines.
To report a security issue, see SECURITY.md.