Metadata-Version: 2.4
Name: claude-code-kit
Version: 0.25.0
Summary: 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.
Project-URL: Homepage, https://github.com/ajyadav013/claude-kit
Project-URL: Repository, https://github.com/ajyadav013/claude-kit
Project-URL: Issues, https://github.com/ajyadav013/claude-kit/issues
Author: Arjunsingh Yadav
License-Expression: MIT
License-File: LICENSE
Keywords: agentic,agents,automation,claude,claude-code,code-review,cookiecutter,fastapi,generator,orchestration,react,scaffold,sdlc,testing
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.9
Requires-Dist: jinja2>=3.1
Requires-Dist: pyyaml>=6.0
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Requires-Dist: shellcheck-py>=0.10; extra == 'dev'
Requires-Dist: twine>=5.0; extra == 'dev'
Description-Content-Type: text/markdown

<div align="center">

# claude-kit

**A Cookiecutter-style scaffolder for an autonomous SDLC (software-delivery lifecycle) inside [Claude Code](https://www.claude.com/product/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.**

[![PyPI](https://img.shields.io/pypi/v/claude-code-kit.svg)](https://pypi.org/project/claude-code-kit/)
[![Python](https://img.shields.io/pypi/pyversions/claude-code-kit.svg)](https://pypi.org/project/claude-code-kit/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Built for Claude Code](https://img.shields.io/badge/built%20for-Claude%20Code-d97757.svg)](https://www.claude.com/product/claude-code)
[![CI](https://github.com/ajyadav013/claude-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/ajyadav013/claude-kit/actions/workflows/ci.yml)
[![Changelog](https://img.shields.io/badge/changelog-md-blue.svg)](CHANGELOG.md)

✨ [Features](#features) · 🚀 [Quick start](#quick-start) · 🧭 [How it works](#how-it-works) · 🔁 [The pipeline](#the-pipeline) · 🧪 [Example](examples/) · 🌱 [What we adopted](#influences--what-we-adopted) · 🤖 [Agents](#the-agents) · 🧩 [Catalog](#catalog--extensibility) · 🛠️ [CLI](#cli-reference) · 🔒 [Security](#security--trust-model) · 📖 [Agent guide](docs/agents.md)

</div>

---

## 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](#influences--what-we-adopted) and from where.

---

## Features

The whole product at a glance — one line each. Expand **[Feature details](#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

<details open>
<summary><b>A) As a Claude Code plugin&nbsp; (recommended)</b></summary>

<br>

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

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

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

```text
/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):

```text
/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
```

</details>

<details>
<summary><b>B) As a pip package&nbsp; (CI, onboarding, non-plugin workflows)</b></summary>

<br>

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

```bash
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
```

</details>

> **Prerequisites:** [Claude Code](https://www.claude.com/product/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).

<details>
<summary><b>What the init flow asks &amp; what lands on disk</b></summary>

<br>

`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
```

</details>

---

## Feature details

Each area from the [Features](#features) table, expanded — the README stays short; open only what you
need.

<details>
<summary><b>🔁 Pipeline & quality gates</b></summary>

<br>

- **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](#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.

</details>

<details>
<summary><b>🤖 The agent roster</b></summary>

<br>

- **28 specialized agents** in [`agents/`](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.

</details>

<details>
<summary><b>🔍 Self-verification & review</b></summary>

<br>

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

</details>

<details>
<summary><b>📐 Rules & skills</b></summary>

<br>

- **23 stack-agnostic core rules** in [`rules/`](rules/) — `mandatory-workflow`, `quality-gates`,
  `rarv-cycle`, `continuity`, plus eight agent-operation rules and `autonomy-levels` +
  `risk-classification` (see [`docs/agentic-patterns.md`](docs/agentic-patterns.md)).
- **51 on-demand skills** in [`skills/`](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.

</details>

<details>
<summary><b>🧱 Stacks & overlays</b></summary>

<br>

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

</details>

<details>
<summary><b>🎚️ Profiles, scopes & the org layer</b></summary>

<br>

- **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/`](templates/org/) (secrets, PII,
  compliance, production-data) install only in organization scope (see
  [`docs/org-capabilities.md`](docs/org-capabilities.md)).

</details>

<details>
<summary><b>🧠 Memory & continuous learning</b></summary>

<br>

- **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`.

</details>

<details>
<summary><b>🛠️ Hooks & deterministic guards</b></summary>

<br>

- **17 event hook scripts** in [`hooks/`](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.

</details>

<details>
<summary><b>📦 Distribution & lifecycle</b></summary>

<br>

- **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/`](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`](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).

</details>

<details>
<summary><b>♻️ Reuse-first by design</b></summary>

<br>

- **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](#influences--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/`](examples/) shows an end-to-end run, and a
  profile×stack×scope test matrix backs the stack-agnostic claim.

</details>

---

## How it works

```mermaid
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 **R**eason → **A**ct → **R**eflect → **V**erify 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`](docs/architecture.md) for the full diagrams.

---

## The pipeline

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

```mermaid
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/`](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](docs/agentic-patterns.md)) | Reasoning, guardrails, resilience, human-in-the-loop, evals, and tool design as first-class agent disciplines | 8 agent-operation rules + [`docs/agentic-patterns.md`](docs/agentic-patterns.md) | `0.4.0` |
| **[ponytail](https://github.com/DietrichGebert/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](https://github.com/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](https://github.com/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`](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/`](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](CHANGELOG.md) — including, for every review, what we
> deliberately **did not** add because the kit already covered it.

<details>
<summary><b>The latest three reviews, in a bit more depth</b></summary>

<br>

**🪶 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.

</details>

<details>
<summary><b>How claude-kit compares (positioning)</b></summary>

<br>

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](https://github.com/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](https://github.com/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.

</details>

---

## The agents

**28 specialized roles** in [`agents/`](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](docs/agents.md)** explains how to drive them.

<details>
<summary><b>See the full roster (28 + overlays + personas)</b></summary>

<br>

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

</details>

---

## Rules & skills

**Rules** ([`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`](docs/agentic-patterns.md)), and `autonomy-levels` +
`risk-classification` (see [`docs/org-capabilities.md`](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/`](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/`](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.

<details>
<summary><b>The four catalog files</b></summary>

<br>

- **`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`](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.

</details>

---

## CLI reference

<details>
<summary><b>All commands</b> (<code>claude-kit</code> · aliases <code>ckit</code> · <code>claude-sdlc</code>)</summary>

<br>

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

</details>

<details>
<summary><b>Safe upgrades</b> — how your edits are protected</summary>

<br>

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.

</details>

<details>
<summary><b>Troubleshooting</b></summary>

<br>

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` |

</details>

---

## Security & trust model

claude-kit installs **configuration only** — no application code, no Docker, nothing that runs as a
service. It never executes your code; it lays down rules, agents, skills, gates, and hook scripts that
**Claude Code** then follows. Three honest caveats are worth understanding before you rely on it:

- **The guard hooks are convenience, not a hardened boundary.** Scripts like `guard-secrets`,
  `guard-destructive-git`, and the `warn-*` advisories raise the cost of a mistake — they do **not**
  sandbox the agent or guarantee prevention. They need a POSIX shell + `jq` and **silently no-op**
  without them (e.g. on Windows outside WSL/Git Bash). Treat them as seatbelts, not walls.
- **Most quality gates are agent protocols, not mechanical enforcement.** The pipeline's gates
  (`spec-complete`, `code-review`, `security-clear`, …) are disciplines Claude is instructed to follow
  and self-verify; only the hook scripts are deterministic, host-enforced checks. A capable model can
  still be wrong or skip a step — keep a human in the loop for anything that matters.
- **MCP servers are third-party code.** Each fragment runs an external package (pinned to an exact
  version) or a hosted endpoint that claude-kit references but does **not** vendor or audit. Review a
  server's source and license before enabling it.

Releases are published to PyPI via OIDC **Trusted Publishing** (no long-lived API token) with **PEP 740
build attestations** for supply-chain provenance. Report vulnerabilities privately — see
[`SECURITY.md`](SECURITY.md) for the full scope and reporting process.

---

## Project structure

<details>
<summary><b>Repository layout</b></summary>

<br>

```
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`](docs/architecture.md) for the full picture and [`CLAUDE.md`](CLAUDE.md)
for how to develop the kit itself.

</details>

---

## Contributing

Issues and PRs welcome — see [`CONTRIBUTING.md`](CONTRIBUTING.md). To dogfood a local checkout:

```bash
# 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](LICENSE) © Arjunsingh Yadav
