claude-code-kit 0.24.0

Cookiecutter-style scaffolder for an autonomous Claude Code SDLC configuration (no app code, no Docker). Asks ordered questions and installs CLAUDE.md + .claude/ (rules, the chosen profile's agents/skills, hooks, artifact templates) + optional .mcp.json; run /sdlc to drive spec → review → build → test → security → ship through profile-aware quality gates, working memory, and a self-improving learnings loop.

claude-kit

A Cookiecutter-style scaffolder for an autonomous SDLC (software-delivery lifecycle) inside Claude Code.

One command turns a one-line request into reviewed, tested, secured, shippable code — with a quality gate between every phase. No application code. No Docker. Configuration only.

✨ Features · 🚀 Quick start · 🧭 How it works · 🔁 The pipeline · 🧪 Example · 🌱 What we adopted · 🤖 Agents · 🧩 Catalog · 🛠️ CLI · 📖 Agent guide

---

What is this?

Claude Code is brilliant at single tasks — but a real change is never just one task. It's a spec, a plan, code, review, tests, a security pass, a PR. claude-kit turns that whole lifecycle into a pipeline of focused agents and installs it into Claude Code as configuration.

Instead of one assistant doing everything in a single pass, your request flows through specialists — a spec writer, a story planner, a developer, independent reviewers, testers, security scanners, a PR raiser — coordinated by an Orchestrator that runs independent work in parallel and refuses to advance until each phase's quality gate passes. You drive it all with one command: /sdlc <your task>.

It ships no application code and needs no Docker — only the rules, agents, skills, and gates that govern how the work gets done. Choose your stack, rigor, and team scope at init; everything else adapts.

Inspired by the autonomous-SDLC idea, rebuilt from the ground up for Claude Code, and kept small by a reuse-first policy — see what we adopted and from where.

---

Features

The whole product at a glance — one line each. Expand Feature details (below Quick start) for the full breakdown of any row.

Area	What you get
🔁 Pipeline & quality gates	Gate-enforced progression (zero open Critical/High/Medium to advance), per-profile gate sets, a fast-track for small changes, and an anti-sycophancy devils-advocate pass
🤖 Agent roster	28 tiered agents + per-database overlays + 6 org personas, led by an Orchestrator that never writes code
🔍 Self-verification & review	RARV green-Verify (real commands, not imagined), blind parallel review, and read-only risk classification
📐 Rules & skills	23 stack-agnostic core rules (incl. 8 agent-operation rules) + 51 context-activated skills
🧱 Stacks & overlays	Stack-agnostic core + 10 overlay rule sets (React · FastAPI · Go · Postgres · Mongo) wired to your exact commands, incl. a full React design system
🎚️ Profiles, scopes & org	3 rigor profiles · 3 scopes · 5 autonomy levels · 7 org packs + 10 policy rules
🧠 Memory & learning	Working memory across context compaction + a cost-aware learnings loop (capture_mode) so the same mistake isn't repeated
🛠️ Hooks & guards	17 event hooks — blocking safety guards vs. advisory warnings — that no-op gracefully without jq
📦 Distribution & lifecycle	Plugin and pip from one source, 9 ready MCP fragments, and edit-preserving upgrade
♻️ Reuse-first by design	Adopt-only-the-new reviews, opt-in LLM/AI security (OWASP LLM Top 10), a worked example + self-test matrix

---

Quick start

A) As a Claude Code plugin  (recommended)

Makes all agents, skills, commands, and hooks available inside Claude Code:

/plugin marketplace add ajyadav013/claude-kit
/plugin install claude-kit

Then, inside any project you want the pipeline to manage:

/claude-kit:init        # asks the ordered questions, lays down CLAUDE.md + .claude/
# ↻ restart Claude Code so the project's agents, skills & hooks load
/sdlc Add a CSV export button to the reports page

/claude-kit:init requires the Python CLI (pipx install claude-code-kit, or pip install claude-code-kit) — it's what resolves your stack/profile/MCP catalog and records init-options.json for safe upgrade/diff. If the CLI isn't on PATH the command stops and tells you to install it rather than doing a partial install. (A degraded, no-resolution shell scaffolder is available only by explicitly setting CLAUDE_KIT_BASIC=1; upgrade/diff won't work against it.)

/sdlc is a project skill installed by init, so it becomes available after the restart. The plugin also exposes /claude-kit:sdlc <task>, which works immediately (no restart needed).

Updating the plugin to a newer release later (the plugin is cached, so a plain /reload-plugins won't fetch new code — refresh the marketplace snapshot first):

/plugin marketplace update claude-kit   # refresh the marketplace snapshot from the repo
/plugin update claude-kit@claude-kit    # install the newer version into the cache
/reload-plugins                         # load it into the running session

B) As a pip package  (CI, onboarding, non-plugin workflows)

A CLI (claude-kit, aliases ckit / claude-sdlc) that scaffolds the same config into any repo:

pip install claude-code-kit
# or, for the bleeding edge straight from the repo:
#   pip install "git+https://github.com/ajyadav013/claude-kit.git"

claude-kit init                 # interactive: prompts for stack, profile, MCP
claude-kit init --defaults      # non-interactive: React + Python/FastAPI + Postgres + standard

Prerequisites: Claude Code; Python ≥ 3.9 for the CLI; jq to enable the shell hooks (they no-op without it); Node / npx only if you enable an MCP (Model Context Protocol) server.

Windows: the config (agents · skills · rules) and the claude-kit CLI work natively. The shell hooks (guard-*, warn-*) need a POSIX shell + jq, so run inside WSL or Git Bash to enable them — claude-kit doctor detects Windows and tells you which case you're in. Without a POSIX shell the hooks silently no-op (the kit still functions; you just lose the deterministic guards).

What the init flow asks & what lands on disk

claude-kit init asks an ordered set of questions (all with sensible defaults), then writes the config — nothing else:

1. Target path (default: current dir; if .claude/ exists → merge / overwrite / backup / abort)
2. Frontend framework (default: React) → frontend language (default: TypeScript)
3. Backend language (default: Python) → backend framework (default: FastAPI)
4. Database (PostgreSQL · MongoDB)
5. SDLC profile (lean · standard · enterprise)
6. Optional MCP integrations (GitHub · Jira/Linear · Postgres/Mongo · Playwright · Docs) — a project-root .mcp.json is written only if you select any (env placeholders, never secrets)

Non-interactive equivalents: --defaults, or --config init.yaml (flat or nested YAML). What lands:

CLAUDE.md                      # "Project-specific rules" filled from your stack's commands
README.claude-sdlc.md
.claude/
  settings.json                # assembled from the profile's hooks
  rules/                        # stack-agnostic core + selected overlay rules
  agents/                       # the profile's agent subset + DB overlay agents
  skills/  (incl. sdlc/)        # the profile's skill subset; sdlc/ is the /sdlc entrypoint
  hooks/                        # the profile's hook scripts
  templates/                    # artifact templates (spec, ADR, test-plan, …)
  config/                       # init-options.json (checksums) + stack snapshot
  state/  tmp/                  # gitignored runtime
.mcp.json                       # only if MCP servers were selected

---

Feature details

Each area from the Features table, expanded — the README stays short; open only what you need.

🔁 Pipeline & quality gates

• Gate-enforced progression — every phase ends in a quality gate that passes only with zero open Critical/High/Medium findings; no silent advancement (see the pipeline).
• Profile-scoped gates — lean runs code-review · build-green; standard adds spec / EM / coverage / security / contract; enterprise adds pipeline-green · observability-ready · acceptance.
• Fast-track mode — changes under 5 files collapse to Developer → Code Reviewer → Tester → PR, skipping the heavyweight stages.
• Anti-sycophancy guard — a unanimous PASS is treated as suspicious and triggers an adversarial devils-advocate pass before the gate may close.

🤖 The agent roster

• 28 specialized agents in agents/, each tagged with a tier (orchestrator · stage-lead · specialist · review) and installed per profile.
• An Orchestrator that never writes code — it decomposes work, runs independent lanes in parallel, and blocks each phase on its gate.
• Database overlay agents layer in per database — PostgreSQL adds postgres-specialist · migration-specialist · db-performance-reviewer; MongoDB adds mongodb-specialist · migration-specialist.
• 6 organization personas (pm-copilot · founder-prototype-agent · support-ticket-engineer · data-workflow-agent · internal-tools-builder · staff-pm-reviewer) unlock in org scope so non-engineers can drive work safely.

🔍 Self-verification & review

• RARV self-check — every agent runs Reason → Act → Reflect → Verify and must show a green Verify (real commands run, not imagined) before handing off.
• Blind parallel review — independent reviewers judge a work stream separately, and a merge-reviewer reconciles parallel lanes at every join point.
• Risk-classified work — a read-only risk-classifier labels each task low/medium/high/restricted and names the gates it requires (enterprise + org).

📐 Rules & skills

• 23 stack-agnostic core rules in rules/ — mandatory-workflow, quality-gates, rarv-cycle, continuity, plus eight agent-operation rules and autonomy-levels + risk-classification (see docs/agentic-patterns.md).
• 51 on-demand skills in skills/ — spec-driven dev, planning, TDD, debugging, code review, threat modeling, and more — activated by context and led by the sdlc entrypoint.
• Profile-subset install — each profile installs a strict subset of agents, skills, hooks, and rules (lean ⊂ standard ⊂ enterprise), from fast track to full audit.

🧱 Stacks & overlays

• Stack-agnostic core — the pipeline assumes no language or framework; it never writes your app code and never needs Docker.
• 10 stack overlay rules layer matching guidance on top — React, FastAPI, Go/net-http, PostgreSQL, MongoDB — wired to your exact lint/test/build commands.
• A full React design system — picking React installs design tokens, UX patterns, and mobile/Capacitor guidelines that the UI skills and ui-designer agent read.

🎚️ Profiles, scopes & the org layer

• 3 rigor profiles — lean ⊊ standard ⊊ enterprise decide how many agents, skills, hooks, and gates are active.
• 3 usage scopes — individual / team (default) / organization, with a vibe-coding layer in org scope.
• 5 autonomy levels — from Advisory (plan & review only) through Autonomous (PR) to Enterprise-controlled, each adding deterministic guardrail hooks.
• 7 capability packs + 10 org policy rules under templates/org/ (secrets, PII, compliance, production-data) install only in organization scope (see docs/org-capabilities.md).

🧠 Memory & continuous learning

• Working memory across sessions — CONTINUITY.md survives context compaction so the pipeline never loses its place.
• A learnings loop — agent-memory/ captures fixes from your corrections and, in a non-blocking background job, from what Claude changed, so the same mistake isn't made twice.
• Cost-aware capture — how aggressively learnings are captured (capture_mode: off · on clean exit · + catch-up · per task) is a choice at init.

🛠️ Hooks & deterministic guards

• 17 event hook scripts in hooks/ enforce the pipeline outside the model — guard-secrets, guard-destructive-git, lint-fix, type-check, and validate-settings run deterministically.
• Advisory, never-blocking warnings — warn-llm-io, warn-large-edits, warn-missing-tests, and warn-sensitive-files flag risk without halting work.
• Graceful degradation — hooks need a POSIX shell + jq and silently no-op when absent, so the kit still functions everywhere.

📦 Distribution & lifecycle

• Two channels, one source — a first-class Claude Code plugin and a pip scaffolder (claude-kit / ckit / claude-sdlc) generate identical config.
• Catalog-driven extensibility — adding a stack, framework, database, profile, MCP server, or org pack is a catalog/ YAML edit, never a code change; 9 MCP server fragments ship ready.
• MCP servers are third-party — each fragment runs an external package or hosted endpoint that claude-kit references but does not vendor or audit; the npx commands are pinned to an exact version (not @latest) for reproducible, supply-chain-aware installs. Review a server's source and license before enabling it, and bump pins deliberately. See SECURITY.md.
• Safe, edit-preserving upgrades — upgrade refreshes kit/overlay files via per-file owner + checksum, never clobbers your edits, backs up changes, and restores deleted files (diff previews first).

♻️ Reuse-first by design

• Adopt only the genuinely-new — each external review fetches the real source, adversarially maps it against existing files, and ships only the non-duplicative gaps (see what we adopted).
• Opt-in LLM/AI security — security-and-hardening covers the OWASP LLM Top 10 (input/output guardrails, PII vault) as bypassable guidance, distinct from the mandatory appsec gate.
• A worked example + self-test matrix — examples/ shows an end-to-end run, and a profile×stack×scope test matrix backs the stack-agnostic claim.

---

How it works

flowchart LR
    subgraph SRC["claude-kit — single source of truth"]
        direction TB
        A["agents/"]
        S["skills/"]
        C["commands/"]
        H["hooks/"]
        R["rules/"]
        T["templates/"]
        K["catalog/<br/>(stacks · profiles · mcp · org)"]
    end
    SRC -->|"pip install + claude-kit init"| PROJ["Your project<br/>CLAUDE.md + .claude/"]
    SRC -->|"/plugin install"| CC["Claude Code<br/>(agents · skills · commands · hooks)"]
    CC -->|"/claude-kit:init"| PROJ
    PROJ --> RUN(["/sdlc — autonomous SDLC active"])

Three ideas do the heavy lifting:

1. Quality gates with a shared severity model. Every finding is classified Critical / High / Medium / Low / Cosmetic. A gate passes only with zero Critical/High/Medium open. No silent advancement.
2. RARV self-check. Every agent runs Reason → Act → Reflect → Verify and must show a green Verify (real commands run, not imagined) before handing off.
3. Blind review + Devil's Advocate. Parallel reviewers judge independently; a unanimous PASS is treated as suspicious and triggers an adversarial devils-advocate pass before the gate may close — an explicit guard against agents rubber-stamping each other.

See docs/architecture.md for the full diagrams.

---

The pipeline

/sdlc reads the profile you chose and runs only that profile's gates:

flowchart TD
    REQ(["/sdlc request"]) --> CLS{"Classify"}
    CLS -->|"feature"| SPEC["Spec & Dev Docs"]
    SPEC --> EM{{"Gate: EM approved"}}
    EM -->|"pass"| STORY["Story breakdown + coverage gate<br/>story-planner"]
    STORY --> LANES["Parallel lanes:<br/>Senior Dev → Architect → Developer → Code Review"]
    LANES --> MR{{"Gate: Merge Reviewer"}}
    MR --> TEST["Unit · E2E · Integration + Senior verification"]
    TEST --> TCG{{"Gate: Test coverage<br/>+ Devil's Advocate"}}
    TCG --> SEC{{"Gate: Security Clear"}}
    SEC --> OPS{{"Gates: Pipeline Green ·<br/>Observability Ready · Acceptance"}}
    OPS --> PR["PR Raiser"] --> HUMAN(["Human review + deploy"])
    CLS -->|"fast-track (<5 files)"| FT["Developer → Review → Test → PR"] --> HUMAN

Profile	Gates that run
lean	code-review · build-green
standard	spec-complete · em-approved · code-review · build-green · test-coverage · security-clear · contract-clear*
enterprise	standard + pipeline-green · observability-ready · acceptance

* contract-clear (API breaking-change diff) self-skips when the stack exposes no API surface, so it is inert for non-API projects. Organization scope at regulated strictness adds accessibility-clear (WCAG-AA on changed UI). A fast-track mode collapses small changes (< 5 files) to Developer → Code Reviewer → Tester → PR.

See examples/ for a synthetic end-to-end walkthrough — request → spec → story breakdown → gate verdicts (with one defect-loop cycle) → sample PR diff.

---

Influences & what we adopted

claude-kit is built reuse-first. We periodically review excellent open-source projects and adopt only the genuinely-new ideas — never duplicating what the kit already does (near-duplicates would dilute Claude's ability to auto-select the right skill). Each adoption follows the same method: fetch the real source → adversarially map it against the kit's existing files → ship only the non-duplicative gaps, minimally and catalog-wired.

Source	What we learned	What we shipped	Since
Agentic Design Patterns — A. Gulli (coverage map)	Reasoning, guardrails, resilience, human-in-the-loop, evals, and tool design as first-class agent disciplines	8 agent-operation rules + docs/agentic-patterns.md	0.4.0
ponytail	YAGNI / anti-over-engineering as an explicit recurring pass; deferral-debt tracking; surfacing the active autonomy level	over-engineering-review & simplification-debt skills, the load-autonomy hook, median-of-N in evals	0.8.0
GitHub spec-kit	Spec → tasks → analyze coverage gate; tasks → tracker issues; stable requirement IDs + assumptions in specs	Wired the (previously orphaned) story-planner as the coverage gate (1f), a tracker-agnostic task-tracker-sync skill, and enriched the feature-spec template	0.9.0
protectai/llm-guard	Input→model→output guardrails for LLM features — prompt injection, PII vault, treating model output as untrusted	Opt-in "LLM / AI Feature Security" guidance in security-and-hardening + the advisory warn-llm-io hook (warns, never blocks)	0.10.0
Improvement brief (external self-review)	API backward-compat as a gate; load-against-SLO as a release criterion; supply-chain maintenance cadence; pipeline resumability, clean abort, and worktree lifecycle; pipeline cost/concurrency/cross-platform transparency	The enterprise contract-clear gate (owned by merge-reviewer) + api-change-report template; a load-vs-SLO criterion in Observability Ready; dependency Cadence Mode; /sdlc resume-vs-restart, /claude-kit:abort, worktree teardown; cost/concurrency/Windows notes — 9 surgical extensions, 0 new agents/skills/rules	0.12.0
Improvement brief #2 (external self-review)	The covered-vs-gated distinction (a skill ≠ a gate); enforce API breaking-changes by default; expand/contract migration safety; back the stack-agnostic claim with a compiled backend; WCAG as a regulated gate; reconcile the PyPI story; ship a worked example + a self-test matrix	docs/coverage-audit.md; contract-clear promoted to standard; a live Go/net-http backend; the accessibility-clear regulated gate; explicit migration-drop rules; a synthetic examples/ run; an eval-harness template; a profile×stack×scope self-test matrix — 2 gates wired + 1 stack, 0 new agents/skills/rules	0.13.0

Each adoption is detailed in the CHANGELOG — including, for every review, what we deliberately did not add because the kit already covered it.

The latest three reviews, in a bit more depth

🪶 ponytail → minimalism layer (0.8.0). Most of ponytail's philosophy (YAGNI, stdlib-first, surgical diffs) was already enforced by CLAUDE.md "Simplicity First" + code-simplification, so we added only the missing mechanisms: over-engineering-review (a complexity-only, report-only delete-list), simplification-debt (harvests TODO/FIXME/inline shortcut: markers into a ledger and flags ones that name no upgrade path), and the load-autonomy SessionStart hook (surfaces the active autonomy level each session).

🧭 GitHub spec-kit → coverage gate + tracker sync (0.9.0). The headline was reuse: the kit already had a story-planner agent that verifies every acceptance criterion maps to a story, but it was never wired into the pipeline. We made it stage 1f (between EM approval and the developer), so implementation can't start until coverage is proven. We also added task-tracker-sync (mirrors a plan into GitHub / Linear / Jira issues, dependencies preserved) and gave the feature-spec template stable requirement IDs + an Assumptions section. We skipped spec-kit's /constitution, /clarify, and /checklist — all already covered.

🛡️ protectai/llm-guard → opt-in LLM security (0.10.0). The kit secured the agent itself and traditional web appsec, but nothing covered the LLM features you build into your product (the OWASP LLM Top 10). Per request, the new layer is opt-in, bypassable, and states the risk of bypassing: an "LLM / AI Feature Security" section in security-and-hardening (input/output guardrails, PII vault, untrusted-output handling, a security-implications-of-bypassing table) plus a non-blocking warn-llm-io hook. We deliberately did not add a new rule or fold it into the mandatory security gate — that would have made it mandatory.

How claude-kit compares (positioning)

claude-kit is a config-only, stack-agnostic SDLC scaffolder — it installs a governed pipeline (agents · skills · rules · gates · hooks) into your project's .claude/ and then gets out of the way. It is not a runtime, an orchestration engine, or a code library. That framing is the difference:

Project	What it is	How claude-kit differs
wshobson/agents & similar agent collections	Large libraries of individual subagent prompts you pick from	claude-kit ships a smaller, opinionated set wired into a sequenced pipeline with owned quality gates — agents aren't a menu, they're stages that hand off and block on each other. Adopt-by-reuse, not by accumulation.
GitHub spec-kit	A spec-driven workflow (constitution → spec → tasks → analyze)	claude-kit absorbed spec-kit's coverage-gate idea (the story-planner 1f gate + task-tracker-sync) into a broader lifecycle that also covers review, security, build, test, release, and observability gates. Complementary, wider scope.
claude-flow / multi-agent runtimes	Runtime orchestrators that execute swarms of agents	claude-kit produces portable configuration, not a running process — the orchestration is described in rules the host (Claude Code) executes. No daemon, no lock-in, no app code.
dotfiles / CLAUDE.md starters	A single rules file or settings snippet	claude-kit is a catalog-driven generator: it resolves your stack/profile/scope into the right subset of 23 rules, 28 agents, 51 skills, gates, and hooks, and keeps them upgradeable (claude-kit upgrade preserves your edits via owner + checksum).

Choose claude-kit when you want a consistent, reviewable, gate-enforced autonomous-SDLC setup that's the same across every repo and stack, installs in seconds, ships nothing you have to run, and evolves reuse-first rather than by piling on near-duplicate agents.

---

The agents

28 specialized roles in agents/, each tagged with a tier (orchestrator · stage-lead · specialist · review) and installed per profile — plus per-database overlay agents and, in organization scope, persona agents. The agent guide explains how to drive them.

See the full roster (28 + overlays + personas)

Agent	Role
orchestrator	Pipeline controller — decomposes, delegates, runs lanes in parallel, gates progression (never writes code)
spec-doc-writer	Turns requirements into a spec + developer documentation in one pass
story-planner	Decomposes an approved spec into ordered, parallelizable stories; verifies every acceptance criterion maps to a story (workflow gate 1f)
ui-designer	Drafts and self-reviews UI/UX design specs
senior-backend-dev · senior-frontend-dev	Senior review of a work stream's spec (the two-lane example)
technical-architect	Cross-system architecture, scalability, integration review
em-reviewer	Engineering-manager strategic & completeness review
merge-reviewer	Verifies consistency between parallel lanes at join points
developer	Writes production code from an approved spec, in an isolated worktree
sdlc-code-reviewer	Reviews code for bugs, security, performance, spec compliance
unit-tester · e2e-tester	Author unit and end-to-end test suites
tester · senior-tester	Integration testing and independent verification of coverage
auditor	Read-only audit for accessibility, performance, responsiveness, console errors
devils-advocate	Anti-sycophancy adversarial reviewer (runs on a unanimous PASS)
acceptance-reviewer	Verifies delivery against acceptance criteria before the human gate
risk-classifier	Read-only — classifies work low/medium/high/restricted and names the required gates (enterprise + org)
security-reviewer	Security stage coordinator — owns the Security Clear gate
secret-scanner · dependency-scanner · owasp-reviewer · policy-validator	The four parallel security sub-scanners
devops-engineer	CI/build/release, env, migrations, runbook — container-optional; owns Pipeline Green
observability-engineer	SLOs, health/readiness, structured logging, alerts — owns Observability Ready
incident-responder	Production-incident triage, mitigation, and postmortem (enterprise scope)
pr-raiser	Final checks, commit hygiene, and PR creation
DB overlays	installed for the selected database — PostgreSQL → postgres-specialist · migration-specialist · db-performance-reviewer; MongoDB → mongodb-specialist · migration-specialist
Org personas	pm-copilot · founder-prototype-agent · support-ticket-engineer · data-workflow-agent · internal-tools-builder · staff-pm-reviewer (organization scope only)

---

Rules & skills

Rules (rules/) are the 23 stack-agnostic contracts every agent obeys — the mandatory-workflow pipeline, quality-gates, rarv-cycle, continuity, documentation, testing, the eight agent-operation rules (reasoning-techniques, agent-guardrails, agent-resilience, goal-setting-and-monitoring, human-in-the-loop, model-tiers, evals, tool-design — see docs/agentic-patterns.md), and autonomy-levels + risk-classification (see docs/org-capabilities.md). Stack overlay rules (fastapi-patterns, react-patterns, postgres-patterns, …) and, in organization scope, org policy rules (secrets-policy, pii-policy, compliance-policy, …) layer on top.

Skills (skills/) are on-demand capabilities Claude activates by context — led by the sdlc entrypoint. Highlights, including this session's additions:

Skill	What it does
spec-driven-development · planning-and-task-breakdown	Spec first, then a verifiable task breakdown
task-tracker-sync	Mirror a plan/story breakdown into GitHub / Linear / Jira issues (tracker-agnostic, idempotent)
security-and-hardening	Traditional appsec + opt-in LLM / AI Feature Security (OWASP LLM Top 10, with a bypass + implications)
threat-model	Design-time STRIDE — now with an LLM/AI branch
over-engineering-review · simplification-debt	Keep the code lean: a complexity-only delete-list, and a deferral-debt ledger
test-driven-development · debugging-and-error-recovery · code-review-and-quality	The build / fix / review staples
remember	The self-improving learnings loop into agent-memory/

Each profile installs a subset (lean ⊂ standard ⊂ enterprise).

---

Catalog & extensibility

Everything selectable lives in catalog/ as data — adding a stack, framework, database, profile, or MCP server is a YAML edit plus a templates/stacks/<dir>/ folder, never a code change.

The four catalog files

• catalog/stacks.yaml — frontend frameworks, backend languages → frameworks, and databases. Live today: React · Python/FastAPI · Go/net-http · PostgreSQL/MongoDB. Vue/Svelte/Django/Express are listed as planned (offered by list-options, not yet selectable).
• catalog/profiles.yaml — what each profile activates (inherit: composes; all = everything).
• catalog/mcp.yaml — ready .mcp.json fragments per server, with ${ENV} placeholders.
• catalog/org.yaml — the organization layer: scopes, teams, the autonomy model, review strictness, and the 7 capability packs. Scope-gated content under templates/org/ installs only when scope == organization. See docs/org-capabilities.md.

A third install dimension joins profile (a subset) and stack (an overlay): org (scope-gated). resolve() stays branch-free — adding a pack, team, autonomy level, or org rule is a catalog/org.yaml edit plus content under templates/org/, never a code change. Run claude-kit list-options to see everything available.

---

CLI reference

All commands (claude-kit · aliases ckit · claude-sdlc)

Command	Description
init [path] [--defaults] [--config FILE] [--force]	Scaffold CLAUDE.md + .claude/ (interactive or non-interactive)
validate [path] [--strict]	Structurally validate an installed config; --strict adds hooks→script, .mcp.json-shape, snapshot, and catalog-integrity checks
doctor [path] [--mcp]	Strict validate + environment/health checks; --mcp checks MCP commands, ${ENV} vars, and lockfile drift
diff [path]	Preview what an upgrade would change (no writes)
upgrade [path] [--force]	Refresh kit/overlay files; protect your edits; prune orphans
pipeline validate · status · close-gate · abort	Inspect/mutate the /sdlc state files (gate/lane/evidence coherence); does not run the pipeline
list-options	List available frontend/backend/database/profile/MCP options
status [path]	Show what's installed, the selection, and working memory
version	Print the version
package-org-pack · install-org-pack	Package / install an organization capability pack (org scope)

Plugin slash commands: /claude-kit:init, /claude-kit:sdlc <task>, /claude-kit:status; and the /sdlc skill inside any scaffolded project.

When MCP servers are selected, init also writes a derived .mcp.lock.json pinning each server's resolved package version — inspect it (or run doctor --mcp) to see exactly what would run.

Safe upgrades — how your edits are protected

Every install records per-file checksums and an owner (kit / overlay / user-editable) in .claude/config/init-options.json. upgrade refreshes kit and overlay files to the latest version, never clobbers your edits (a user-modified file is kept and the new version dropped beside it as a .claude-kit sidecar), backs up anything it changes or removes, and restores files you deleted. Run diff first to preview.

Troubleshooting

Run claude-kit doctor first — it checks your environment (git, jq, hook scripts) and prints fix hints.

Symptom	Likely cause	Fix
/sdlc, agents, or skills "not found" right after init	Claude Code hasn't loaded the new project config yet	Restart Claude Code — or use /claude-kit:sdlc <task> (works without a restart)
Guard / quality hooks seem to do nothing	jq isn't installed (the hooks parse tool input with it)	Install jq; without it the hooks degrade to no-ops by design
Hooks do nothing on Windows	No POSIX shell — .sh hooks can't run under cmd/PowerShell	Run claude-kit inside WSL or Git Bash (with jq); claude-kit doctor confirms. Config + CLI work natively regardless
A selected MCP server won't start	node / npx missing (most MCP servers launch via npx)	Install Node.js, or remove the server from .mcp.json
pip install claude-code-kit fails	Outdated pip, or you want an unreleased change	Upgrade pip (pip install -U pip); for unreleased changes use pip install "git+https://github.com/ajyadav013/claude-kit.git"
validate reports missing files	Partial or outdated install	Re-run claude-kit init (choose merge), or claude-kit upgrade

---

Project structure

Repository layout

claude-kit/
├── .claude-plugin/        plugin.json + marketplace.json
├── agents/                28 SDLC agents          rules/        23 engineering rules
├── skills/                on-demand skills        templates/    CLAUDE.md, settings, artifacts, memory seeds
├── commands/              /claude-kit:* commands  hooks/        hooks.json + scripts/
├── catalog/         stacks·profiles·mcp·org       templates/stacks/  per-stack overlay rules + agents
│                                                  templates/org/     org packs · personas · policies (scope-gated)
├── scripts/init.sh        thin fallback scaffolder  src/claude_kit/  the pip CLI (Typer + Jinja2 + PyYAML)
├── docs/architecture.md   diagrams                pyproject.toml   packaging

See docs/architecture.md for the full picture and CLAUDE.md for how to develop the kit itself.

---

Contributing

Issues and PRs welcome — see CONTRIBUTING.md. To dogfood a local checkout:

# As a plugin:  /plugin marketplace add .   then   /plugin install claude-kit
# As the CLI:   pip install -e '.[dev]'   then   claude-kit init /tmp/demo --defaults   &&   pytest

License

MIT © Arjunsingh Yadav