claude-dev-kit

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.

Quick Start

npx mg-claude-dev-kit init

The wizard detects your project state and guides you through setup. Three paths available:

After init, open Claude Code and start working. The scaffold is active immediately.

What it does

Tiered pipelines matched to risk

Start at Tier 0. Move up when you need more structure: npx mg-claude-dev-kit upgrade --tier=m

22 audit skills

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).

Skills are conditionally installed based on your project: hasApi, hasDatabase, hasFrontend, hasDesignSystem.

11 tech stacks auto-detected

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.

MCP server (v1.17.0+)

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.

Incremental adoption

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 variant

Custom skills (custom-* prefix) are preserved across upgrades. See Custom Skills Guide.

Architecture

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.

CLI Commands

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.json

MCP server

claude-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:

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.

Process controls

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.

Testing

node packages/cli/test/integration/run.js    # 1085 integration checks
node --test packages/cli/test/unit/*.test.js   # 373 unit tests

Covers: 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.

Requirements

• Node.js >= 22
• Claude Code CLI
• Git

Documentation

Roadmap

See GitHub Milestones for the 12-month plan.

Current: v1.19.0 ships /pr-review (C2 from the 2026-04-26 cross-LLM review, Issue #122, ICE 267 cross-LLM). Autonomous local PR review via the gh CLI: the skill resolves a PR, fetches the diff, spawns a review subagent with universal + stack-specific severity criteria, posts the review as a PR comment for audit trail, and surfaces a merge decision (integrate / fix branch / proceed). Severity is configurable via the new prReviewSeverity section in team-settings.json; absent that, hard-coded universal defaults apply. The skill is read-only — never modifies code, never auto-merges. PATTERNS.md sibling adds stack-specific severity for node-ts / python / swift; other stacks fall back to the universal defaults. Per Mistral's cross-LLM push-back, the skill is also exposed from day one as the cdk_pr_review MCP tool, so any MCP-aware client can read the audit trail of a PR's review history without invoking the CDK CLI. Skill count moves from 21 to 22; MCP tools from 5 to 6. Integration: 1085 checks; unit: 373 tests (+8 for the new prReviewSeverity validation and helper).

Next: Q3 #4b MCP-aware audit skills (Issue #119, ICE 210), then a runtime-enforcement hook for team-settings.json (smoke-test review proposal, ICE ~240). Q3 #6 sub-tracks 2-3 (/debt-triage, /privacy-audit) re-score next. Q2 #3 VitePress docs site (ICE 432) stays on hold.

Contributing

See CONTRIBUTING.md for development setup, project structure, and PR guidelines.

To report a security issue, see SECURITY.md.

License

MIT