Claude Code Kit

Drop-in starter templates that make Claude Code behave like a disciplined staff engineer instead of an eager intern.

The Problem

Out of the box, Claude Code is powerful but undisciplined. It will:

• Start coding before understanding the codebase
• Make sweeping changes across files you didn't ask it to touch
• Skip verification steps and ship broken code
• Forget lessons from previous mistakes
• Install dependencies and change architecture without asking

The Solution

This kit provides a CLAUDE.md instruction set and supporting templates that enforce a structured workflow:

Plan > Confirm > Implement > Verify — every single time.

Quick Start

npx @tansuasici/claude-code-kit init

Or with curl:

curl -fsSL https://raw.githubusercontent.com/tansuasici/claude-code-kit/main/install.sh | bash

Or as a Claude Code plugin:

/plugin marketplace add tansuasici/claude-code-kit
/plugin install claude-code-kit@claude-code-kit

Path	What you get	When to use
npx / curl	Full kit — CLAUDE.md, agent_docs, all skills, all hooks, agents, scripts, examples	Default. Best when you want the comprehensive discipline layer in your repo.
Plugin marketplace	Kit as a Claude Code plugin (skills + hooks namespaced under /claude-code-kit:*)	Lightweight discovery path; sits alongside other plugins. Does not seed CLAUDE.md / CODEBASE_MAP.md into your repo.

Then fill in CODEBASE_MAP.md with your project's details and start a Claude Code session.

Maintainers: see RELEASING.md for the release flow (npm token setup, 2FA mode requirement, EOTP recovery).

Installer options

Flag	Description
--template nextjs	Use a stack-specific template (nextjs, node-api, python-fastapi, go, rust, django, dotnet). Auto-detected if omitted.
--profile minimal	Hooks only, no CLAUDE.md or docs
--profile strict	All hooks enabled — the 5 opt-in ones too (auto-lint, auto-format, skill-compliance, skill-extract-reminder, notify-waiting)
--upgrade	Update kit-managed files. Ones you edited are kept and reported (the kit's copy lands next to them as <file>.kit-new, never over an earlier one — then .kit-new.1, …); project files are never touched. Needs sha256sum, shasum or python3
--diff	Preview exactly what --upgrade would do (it runs the upgrade on a scratch copy that follows symlinks): files to update, add, keep and resolve, kit paths that are symlinks --upgrade would write through, plus what an upgrade can't fix — stale kit files, kit hooks missing from .claude/settings.json, registrations of scripts that don't exist. Read-only
--gitignore	Add kit files to .gitignore (keep kit local, don't push to repo)
--wiki	Add knowledge wiki module (personal knowledge base)
--html	Add HTML artifacts module (specs, reports, PR writeups as HTML — see ARTIFACTS.md)
--version v1.0.0	Install a specific version instead of latest

Uninstall

curl -fsSL https://raw.githubusercontent.com/tansuasici/claude-code-kit/main/uninstall.sh | bash

Flag	Description
--dry-run	Show what would be removed without deleting
--keep-tasks	Preserve tasks/ directory (lessons, decisions, handoffs)
--keep-project	Preserve project overlay files (CLAUDE.project.md, agent_docs/project/, etc.)
--force	Remove without confirmation

Examples:

# Install with npx
npx @tansuasici/claude-code-kit init --template nextjs
npx @tansuasici/claude-code-kit init --profile strict
npx @tansuasici/claude-code-kit init --wiki
npx @tansuasici/claude-code-kit init --html
npx @tansuasici/claude-code-kit init --upgrade

# Or with curl
curl -fsSL .../install.sh | bash -s -- --template nextjs
curl -fsSL .../install.sh | bash -s -- --gitignore
curl -fsSL .../install.sh | bash -s -- --upgrade
curl -fsSL .../install.sh | bash -s -- --diff
curl -fsSL .../install.sh | bash -s -- --version v1.0.0

npx CLI commands

npx @tansuasici/claude-code-kit init              # Install kit
npx @tansuasici/claude-code-kit doctor            # Check installation health
npx @tansuasici/claude-code-kit skills            # List available /skill commands
npx @tansuasici/claude-code-kit convert all       # Export to Cursor/Windsurf/Aider/AGENTS.md + .agents/skills
npx @tansuasici/claude-code-kit convert codex     # Codex: AGENTS.md rules + .agents/skills
npx @tansuasici/claude-code-kit generate agents-md  # Generate AGENTS.md only
npx @tansuasici/claude-code-kit --version         # Show version

Manual install

git clone --depth 1 https://github.com/tansuasici/claude-code-kit.git /tmp/cck
cp /tmp/cck/CLAUDE.md /tmp/cck/CLAUDE.project.md /tmp/cck/scaffold/CODEBASE_MAP.md .
cp -r /tmp/cck/agent_docs /tmp/cck/scaffold/tasks /tmp/cck/scripts /tmp/cck/.claude .
rm -rf /tmp/cck

Copy from scaffold/, not the repo root: the kit dogfoods itself, so its own CODEBASE_MAP.md describes ClaudeCodeKit and its own tasks/ holds this project's board, ADRs and lessons.

What CLAUDE.md Enforces

Rule	What it does
Tiered Session Boot	Loads context in 3 tiers (always → if continuing → on demand) to minimize token overhead
Plan First	Writes a plan for multi-file changes, waits for your confirmation
Scope Discipline	Touches only what's needed, logs unrelated issues in "Not Now"
Protected Changes	Stops for approval on deps, schema, auth, API, and build changes
Verification	Typecheck, lint, test, smoke test — in that order, every time
Self-Improvement	Logs corrections to tasks/lessons/ (one file per lesson) and reviews _index.md Top Rules each session

Before / After

Without the kit

You: "Add a search feature to the users page"

Claude: *immediately starts coding*
  - Installs 3 new packages without asking
  - Refactors the entire users module "while it's here"
  - Breaks the build because it didn't typecheck
  - Doesn't test anything
  - You spend 30 minutes reviewing and reverting unrelated changes

With the kit

You: "Add a search feature to the users page"

Claude: "Let me restate: add search functionality to the users page.
I've read CODEBASE_MAP.md — the users page is at app/(dashboard)/users/page.tsx,
data comes from src/services/user.service.ts.

This touches 3+ files, so here's my plan:"

  ## Task: Add search to users page
  ### Approach
  1. Add search param handling in users/page.tsx
  2. Add `searchUsers()` to user.service.ts
  3. Add search input component
  ### Files to Touch
  - app/(dashboard)/users/page.tsx
  - src/services/user.service.ts
  - components/features/user-search.tsx (new)

  "Should I proceed with this plan?"

You: "Yes"

Claude: *implements, then runs:*
  1. tsc --noEmit ✓
  2. eslint ✓
  3. npm test ✓
  4. Opens the page, verifies search works ✓

  "Done. All verification passed."

Hooks

Hooks are shell scripts that run automatically — unlike CLAUDE.md rules (advisory), hooks are deterministic. The kit ships 28 hooks; the standard profile wires up 23, and 5 are opt-in (they can be slow, noisy, or conflict with project configs).

Guardrails — block on violation (PreToolUse / Stop):

Hook	Event	What it does
protect-files	PreToolUse	Blocks edits to .env, credentials, private keys, lock files
protect-changes	PreToolUse	Blocks edits to dependency manifests, migrations, and auth logic. Build configs block only under the strict profile (CCK_PROTECT_BUILD_CONFIGS=1); UI under components/ is exempt
branch-protect	PreToolUse	Blocks push to main/master and force pushes
block-dangerous-commands	PreToolUse	Blocks rm -rf /, git reset --hard, DROP TABLE, etc.
conventional-commit	PreToolUse	Enforces feat:, fix:, refactor: commit message format
mcp-gate	PreToolUse	Blocks MCP tool calls (mcp__*) whose server isn't on .claude/mcp-allowlist.txt; inert until you create that file. Reminds once/session that MCP output is untrusted input
quality-gate	PostToolUse	Runs typecheck / lint / syntax-check after an edit; records the verdict
stop-gate	Stop	Blocks completion when the last quality gate failed (bypass: SKIP_QUALITY_GATE=1)
test-first	PostToolUse	Flags a source file edited with no test behind it — once per file, via context, never blocking
test-first-gate	Stop	Blocks completion while a flagged file still has no test — only under the strict profile (CCK_TEST_FIRST=strict; bypass: SKIP_TEST_FIRST=1)

Context & observability — inject or warn, never block:

Hook	Event	What it does
session-start	SessionStart	New session: injects Tier-1 pointers, top rules, active task, branch + dirty-tree status, resets session state. After a compaction (source=compact): re-injects the working anchors without resetting state
prompt-router	UserPromptSubmit	Injects a reminder when a prompt touches a sensitive inflection (auth, deps, schema)
glob-guidance	PreToolUse	One-shot nudge when editing a cross-cutting path (test files, migrations anywhere in the tree) — guidance a single-directory CLAUDE.md can't carry
secret-scan	PostToolUse	Warns if API keys, tokens, or passwords are found
unicode-scan	PostToolUse	Detects invisible Unicode (Glassworm supply-chain attack defense)
loop-detect	PostToolUse	Detects edit loops — warns at 4, signals at 6 edits to the same file
bash-budget	PostToolUse	Warns once when cumulative Bash output crosses a token threshold
read-budget	PostToolUse	Warns once when cumulative file-read output crosses a token threshold (tiered-loading nudge)
tool-failure-observe	PostToolUseFailure	Counts failed tool calls per session (by tool) for the scorecard — high counts signal thrashing
stop-failure-observe	StopFailure	Records turns that ended on an API error (rate-limit/auth/server) so the scorecard can tell infra failures from skipped work
subagent-pre / subagent-post	PreToolUse / PostToolUse	Log sub-agent (Task) invocations and fold their handoff summaries
session-end	SessionEnd	Writes a session audit line + scorecard inputs
journal-fold	SessionEnd	Folds /note journal findings into the session handoff
task-complete-notify	Stop	Desktop notification + sound when Claude finishes

Opt-in — not enabled by default:

Hook	Event	What it does
auto-lint	PostToolUse	Runs linter after edits
auto-format	PostToolUse	Runs formatter after edits
skill-compliance	PostToolUse	Checks edited files against active skill checklists
skill-extract-reminder	UserPromptSubmit	Reminds to extract discoveries as skills
notify-waiting	Notification	Out-of-terminal ping when the agent is waiting (input/permission prompt) — local desktop notify + opt-in ntfy/Pushover push (off by default). Advisory, never blocks

See agent_docs/hooks.md for how to enable the opt-in hooks and write your own.

KitBench — hooks are tested

The hooks above aren't documentation, they're a contract. The kit ships bench/: a reproducible eval harness with 108 scenarios covering every blocking hook plus regression tests for past bugs (composer.lock slip-through, EXIT_CODE=$? after || true, .github/workflows/ci.yml basename-with-slash miss, word-boundary regex rejecting "authentication", stale quality-gate verdict blocking a fresh session). Run it any time with ./scripts/run-bench.sh; CI runs it on every PR.

KitBench
========================================
  s01-protect-files-blocks-env                      PASS
  s02-protect-files-blocks-composer-lock            PASS
  s03-protect-changes-blocks-package-json           PASS
  ...                                               PASS
========================================
  108/108 PASS  0 FAIL

Auto Mode

Claude Code's auto mode (claude --permission-mode auto, or Shift+Tab to it) auto-approves safe actions and stops only on the risky, irreversible ones — fewer prompts, without the blunt --dangerously-skip-permissions. The kit is the floor that makes it safe to turn on:

• The PreToolUse blocking hooks (protect-files, protect-changes, branch-protect, block-dangerous-commands) fire before the auto-mode classifier and hard-block on exit 2.
• The curated permissions.deny list (curl, wget, npm publish, cat .env*, …) resolves before the classifier and can't be overridden by it.

The classifier can only further restrict — never un-block — what the kit denies. A repo can't grant itself auto mode (defaultMode: "auto" is ignored in project settings), so you opt in at the user level:

claude --permission-mode auto

The same floor makes an unattended /loop (scheduled, in-session autonomy) safe: session-start re-fires each iteration to re-anchor the plan, and the deny hooks + stop-gate still hold on every action. The kit ships no loop.md on purpose — it's an inherently project-specific prompt, and the built-in maintenance loop already covers the generic case.

For the full precedence model, the strict posture (deny floor + disableBypassPermissionsMode), the /loop autonomy notes, the escalation points (when to stop and ask the human), and the classifier-tuning knobs, see agent_docs/auto-mode.md.

Agents

Built-in agents for code review, planning, and maintenance:

Agent	What it does
code-reviewer	Reviews for correctness, quality, and best practices
security-reviewer	Scans code for vulnerabilities and security issues
qa-reviewer	Evidence-based QA verification
planner	Creates implementation plans with 3-lens review and failure modes
dead-code-remover	Removes verified unused code through static reference analysis
devils-advocate	Adversarial reviewer — tries to falsify a change (assumptions, breaking inputs, quiet reinterpretations); optional lens in /review-pipeline
wiki-maintainer	Knowledge wiki maintenance — ingest, cross-reference, health checks (requires --wiki)

Skills

User-invocable audit and guide skills — run with /skill-name:

Skill	What it does
/code-quality-audit	Audits code smells, error handling, and maintainability
/performance-audit	Identifies bottlenecks in startup, rendering, memory, and I/O
/architecture-review	Reviews SOLID compliance, module boundaries, and dependencies
/deepening-review	Depth/seam paradigm — surfaces shallow modules and grills the chosen one interactively
/interface-design	Design It Twice — parallel sub-agents produce competing interfaces, then compare
/testing-audit	Audits test coverage, quality, and testing strategy
/dead-code-audit	Detects unused functions, dead imports, and orphan files
/refactoring-guide	Fowler-based refactoring recommendations with execution plans
/accessibility-audit	WCAG 2.1 AA compliance audit for UI code
/dependency-audit	Checks dependencies for vulnerabilities, licenses, and bloat
/documentation-audit	Audits inline docs, API docs, and README quality
/project-health-report	Comprehensive multi-dimensional project health report
/ship	Full deployment pipeline — tests, coverage, CHANGELOG, bisectable commits, PR
/retro	Weekly retrospective with session analytics and LOC metrics
/office-hours	Pre-coding product validation — clarify what and why before coding
/debug	Systematic root-cause debugging with evidence-before-fix enforcement
/design-review	UI design consistency, AI slop detection, and responsive behavior
/ui-component-builder	Builds production-ready UI components with accessibility, states, and responsive behavior — not retrofitted polish
/skill-extractor	Extracts non-obvious knowledge into reusable skills (supports mode:headless)
/skill-generator	Generates project-specific coding skills from tech stack analysis
/shape-spec	Creates timestamped feature spec folders for multi-session planning
/review-pipeline	Runs multiple audits in parallel over a PR-scope diff, dedupes findings, and saves a confidence-gated report (supports mode:headless)
/feature-cycle	End-to-end orchestrator — chains shape-spec → planner → implement → verify → /review-pipeline → /ship from a local spec, halting on any gate failure (supports mode:headless)
/lesson-refresh	Periodic refresh of tasks/lessons/ — keep / update / promote / encode / archive verdicts (supports mode:headless)
/pulse	Time-windowed outcome report saved to tasks/pulses/ — what shipped, broke, was learned, is open (supports mode:headless)
/note	Appends a timestamped finding/decision/summary to the session journal — across-compaction memory, folded into handoff at session end
/constitution	Authors golden-principles.yaml from a 5-question intake or codebase inference — the rules /quality-audit checks against (supports mode:headless)
/quality-audit	Audits code against the project's golden-principles.yaml and updates docs/QUALITY_SCORE.md (supports mode:headless)
/scorecard	Per-session scorecard from hook telemetry — quality-gate pass rate, blocks fired, bash budget (supports mode:headless)
/harness-init	Scaffolds the harness docs pattern (docs/ARCHITECTURE.md, design docs, references) without overwriting existing files (supports mode:headless)
/references-sync	Populates docs/references/<package>-llms.txt so the agent reads curated library docs on demand (supports mode:headless)
/doc-gardening	Prunes stale docs, fixes drift, and refreshes cross-references (supports mode:headless)
/web-read	Extracts clean markdown from a URL via the Defuddle CLI to cut tokens vs WebFetch — falls back to WebFetch if the CLI isn't installed
/capabilities	One-shot briefing of everything the kit makes available here — skills, agents, active hooks, enabled modules — read live from disk
/verification-status	Renders the per-task verification ledger (auto-gates) and records the manual smoke-test + silent-failure checks CLAUDE.md mandates
/wiki-ingest	Ingest source into knowledge wiki — summarize, cross-reference, update index (requires --wiki)
/wiki-lint	Health-check the knowledge wiki — contradictions, orphans, stale content (requires --wiki)
/wiki-briefing	Morning briefing from the wiki — recent activity, new sources, open items (requires --wiki)

Stack Templates

Each template includes a customized CLAUDE.md with stack-specific rules and a pre-filled CODEBASE_MAP.md:

Template	Stack	Includes
nextjs	Next.js 16, App Router, Prisma, Tailwind	Server/Client Component rules, build verification
node-api	Express, TypeScript, Knex.js	Layered architecture, API design conventions
python-fastapi	FastAPI, SQLAlchemy 2.0, Pydantic v2	Async patterns, dependency injection, Alembic
go	Go modules, stdlib-first	Error wrapping, context propagation, -race tests, small interfaces
rust	Cargo, edition-pinned	Result/? (no unwrap), clippy -D warnings, unsafe gating
django	Django (+ DRF), ORM	Fat models, migration discipline, N+1 avoidance, settings-via-env
dotnet	C# / .NET, ASP.NET Core, EF Core	Nullable reference types, async + CancellationToken, IOptions config, EF migration discipline

Auto-detected from your project files (next.config.*, go.mod, Cargo.toml, *.sln / *.csproj / global.json, manage.py, requirements.txt, package.json) when --template is omitted.

Scripts

Installed into your project's scripts/:

Script	What it does
./scripts/doctor.sh	Checks installation health (missing files, broken hooks, invalid settings, commands.json schema) and runs a behavioral self-test of the installed hooks in a scratch project: broken code blocks completion, the verdict survives a compaction, a fix lifts the block, worktrees stay isolated
./scripts/validate.sh	Checks CODEBASE_MAP.md for unfilled placeholders
./scripts/statusline.sh	Terminal status line showing model, branch, context %, cost
./scripts/convert.sh	Exports the kit to Cursor, Windsurf, Aider, AGENTS.md, and .agents/skills (Codex/Zed/Amp); convert.sh codex bundles AGENTS.md + skills; convert.sh import pulls other tools' rules in for review
./scripts/gen-agents-md.sh	Generates cross-tool AGENTS.md from project sources
./scripts/validate-skills.sh	Validates skill directory structure
./scripts/migrate-lessons.sh	One-time migration from legacy tasks/lessons.md to per-file tasks/lessons/ structure
./scripts/lesson-resurface.sh	Backs /lesson-resurface — returns dormant-lesson pointers matched by topic
./scripts/lesson-graph.sh	Generates the tasks/lessons/_index.md auto-sections from applies_to tags
./scripts/note.sh	Backs /note — appends a validated, timestamped line to the session journal

Status line setup

Add to .claude/settings.json:

{
  "statusLine": {
    "command": "./scripts/statusline.sh"
  }
}

sonnet-4.5 | feat/search | ████████░░ 78% | $1.24

Features

AGENTS.md Export — Generate a cross-tool AGENTS.md file from your project configuration. Compatible with GitHub Copilot, OpenAI Codex, Cursor, Google Jules, and Aider. Source of truth remains CLAUDE.md — AGENTS.md is a one-way derived output.

Cross-tool Skills Export — convert.sh skills mirrors the kit's skills into .agents/skills/<name>/SKILL.md, the shared Agent Skills location that Codex, Zed, and Amp all read (the Claude-only user-invocable key is stripped). convert.sh codex exports the discipline (as AGENTS.md rules) plus those skills in one step.

One-time Rules Import — adopting the kit on a project that already has Cursor/Windsurf/Copilot/Aider/AGENTS.md rules? convert.sh import collects them into tasks/imported-rules.md (frontmatter stripped, the kit's own generated exports skipped) for you to review and curate into CLAUDE.project.md. It never auto-edits your overlay. The kit's deterministic hooks do not port to Codex — its repo-local hooks are unreliable (openai/codex#17532) and the kit's hooks parse Claude Code's hook-JSON schema — so the discipline reaches Codex as rules, but the automatic enforcement stays Claude-Code-only.

Tiered Session Boot — Context loads in 3 tiers to minimize token overhead: Tier 1 (always: project map + overlay), Tier 2 (if continuing: handoff + todo), Tier 3 (on demand: lessons top rules, decisions). Reduces startup token cost ~40-50%.

npx Distribution — Install and manage the kit with npx @tansuasici/claude-code-kit init. Supports init, upgrade, doctor, convert, and generate commands.

Session Handoff — Long sessions lose context. Before ending, Claude generates tasks/handoff-[date].md. The next session reads it and resumes where you left off.

Skill Extraction — Claude discovers non-obvious things during sessions (framework quirks, workarounds, config gotchas). The skill system captures these as .claude/skills/<name>/SKILL.md files that load automatically via semantic matching. Run /skill-extractor to review.

Architecture Decision Records — When Claude presents options and you pick one, the reasoning gets recorded in tasks/decisions.md as ADRs with context, options, and consequences.

DESIGN.md — Optional design system template for UI projects. Captures colors, typography, spacing, component styles in a format agents read natively. The /design-review skill checks implementation against it.

Knowledge Wiki — Optional knowledge wiki module (install with --wiki). Based on Andrej Karpathy's LLM Wiki pattern: Claude incrementally builds and maintains a persistent, interlinked wiki from raw sources. Three operations: /wiki-ingest processes new sources into the wiki, /wiki-lint health-checks for contradictions and orphans, /wiki-briefing gives you a daily summary. The wiki compounds — every source you add makes it smarter.

HTML Artifacts — Optional module (install with --html). Based on the Claude Code team's pattern of preferring HTML output over markdown for specs, plans, PR writeups, reports, and design prototypes — richer information (SVG, tables, code, interactions), easier to share (upload + link), and easier to read for anyone outside your terminal. The kit ships ARTIFACTS.md (conventions) and a design-system.html reference so every generated artifact stays on-brand. Deliberately ships without a /html skill — the original recommendation is to just prompt for HTML, not to over-structure it.

Product Context — Optional templates in agent_docs/project/ (mission.md, tech-stack.md, roadmap.md) give agents product awareness beyond code conventions.

Permissions — .claude/settings.json includes curated allow/deny lists. Allowed: test runners, linters, git reads. Denied: curl, wget, .env reads, npm publish. Review and customize for your project.

Project Overlay — Separate kit-managed files from project-specific customizations. CLAUDE.project.md, agent_docs/project/, and .claude/hooks/project/ are never touched by kit upgrades, so your project rules survive --upgrade cleanly.

What's Inside

Full directory structure

claude-code-kit/
  CLAUDE.md                        # Core agent instructions (kit-managed)
  CLAUDE.project.md                # Project-specific overlay (yours, never overwritten)
  CODEBASE_MAP.md                  # Project mapping template
  AGENTS.md                        # Cross-tool standard (generated by gen-agents-md.sh)
  package.json                     # npm package definition (for npx distribution)
  .kit-manifest                    # Tracks kit-managed files (auto-regenerated by scripts/sync-manifest.sh; CI fails if stale)
  install.sh                       # One-line setup script
  uninstall.sh                     # Clean removal script
  bin/
    claude-code-kit.js             # Node.js entry point for npx
    cli.sh                         # Shell CLI implementation
  agent_docs/                      # Agent behavior guides
    workflow.md                    #   Planning templates & task lifecycle
    debugging.md                   #   4-step debugging protocol
    testing.md                     #   Test strategy & patterns
    conventions.md                 #   Naming, structure, git hygiene
    subagents.md                   #   When & how to use subagents
    hooks.md                       #   Hooks guide & how to write your own
    skills.md                      #   Skill extraction guide
    contracts.md                   #   Task contract system
    prompting.md                   #   Bias awareness & neutral prompting
    architecture-language.md       #   Vocabulary for /deepening-review and /interface-design
    project/                       #   Project-specific docs (yours)
  tasks/                           # Session state & tracking
    todo.md, decisions.md, handoff.md
    lessons/                       #   Per-file lessons (YAML frontmatter)
      _index.md                    #     Top Rules + per-lesson links
      _TEMPLATE.md                 #     Template for new lessons
      <YYYY-MM-DD>-<slug>.md       #     One file per lesson
  scripts/                         # Utility scripts
    doctor.sh, validate.sh, statusline.sh, convert.sh, validate-skills.sh, build-skills.sh, gen-skill-docs.sh, gen-agents-md.sh
  # --- Optional: Knowledge Wiki (--wiki) ---
  WIKI.md                          # Wiki schema & conventions
  raw-sources/                     # Immutable source documents (yours)
  wiki/                            # Claude-maintained knowledge base
    index.md, log.md               # Navigation & activity log
    summaries/, entities/, concepts/ # Wiki page directories
  # --- Optional: HTML Artifacts (--html) ---
  ARTIFACTS.md                     # HTML artifact conventions & schema
  artifacts/                       # Generated HTML artifacts
    design-system.html             # Reference tokens — every artifact mirrors these
    index.html                     # Catalog of all artifacts
  .claude/
    settings.json                  # Hook configs & permissions
    agents/                        # code-reviewer, security-reviewer, planner, qa-reviewer, dead-code-remover, wiki-maintainer
    hooks/                         # 30 deterministic hook scripts (lib/ shared helpers)
      project/                     # Project-specific hooks (yours)
    skills/                        # Reusable knowledge & audit skills
      _shared/blocks/              # Shared template blocks (preamble, scope, etc.)
      _templates/                  # .tmpl skill templates (source of truth)
      skill-extractor/             # Meta-skill for knowledge extraction
      skill-generator/             # Meta-skill for generating project skills
      code-quality-audit/          # Code smells & error handling audit
      performance-audit/           # Bottleneck & rendering analysis
      architecture-review/         # SOLID & module boundary review
      deepening-review/            # Depth/seam paradigm — interactive candidate grilling
      interface-design/            # Design It Twice — parallel competing interfaces
      testing-audit/               # Test coverage & quality audit
      dead-code-audit/             # Unused code detection
      refactoring-guide/           # Fowler-based refactoring plans
      accessibility-audit/         # WCAG 2.1 AA compliance
      dependency-audit/            # Vulnerability & license checks
      documentation-audit/         # Doc quality & sync audit
      doc-gardening/               # Docs↔code drift detection
      project-health-report/       # Comprehensive health report
      review-pipeline/             # Parallel multi-audit review (PR-scope)
      quality-audit/               # golden-principles.yaml drift audit
      constitution/                # Author/extend golden-principles.yaml
      references-sync/             # Sync llms.txt-style dependency refs
      harness-init/                # Scaffold docs/ harness structure
      feature-cycle/               # End-to-end lifecycle orchestrator
      lesson-refresh/              # Periodic tasks/lessons/ refresh
      lesson-resurface/            # Surface dormant lessons by topic
      pulse/                       # Time-windowed outcome report
      scorecard/                   # Session-telemetry scorecard
      note/                        # Session-journal note (across compaction)
      ship/                        # Deployment pipeline
      retro/                       # Sprint retrospective & analytics
      office-hours/                # Pre-coding product validation
      debug/                       # Root-cause debugging
      design-review/               # UI design consistency review
      ui-component-builder/        # Production-ready UI component generator
      shape-spec/                  # Feature spec folder creation
      wiki-ingest/                 # Wiki source ingestion (--wiki)
      wiki-lint/                   # Wiki health checks (--wiki)
      wiki-briefing/               # Wiki daily briefing (--wiki)
  examples/
    nextjs/                        # Next.js 16 + App Router template
    node-api/                      # Express + TypeScript template
    python-fastapi/                # FastAPI + SQLAlchemy template
    django/                        # Django (+ DRF) template
    go/                            # Go modules template
    rust/                          # Cargo template
    dotnet/                        # C# / ASP.NET Core + EF Core template

Project Overlay

The kit separates kit-managed files (updated by --upgrade) from project-specific files (never touched):

Layer	Files	Managed by
Kit base	CLAUDE.md, agent_docs/*.md, .claude/hooks/*.sh	install.sh --upgrade
Project overlay	CLAUDE.project.md, agent_docs/project/, .claude/hooks/project/	You

Project rules in CLAUDE.project.md override kit defaults. Add project-specific docs (offline-first patterns, SignalR conventions, etc.) to agent_docs/project/ and project-specific hooks to .claude/hooks/project/.

The .kit-manifest file tracks which files are kit-managed, so upgrades know what to update and what to skip. .kit-baseline records the hash of what the kit last installed at each path: --upgrade updates a file you haven't touched, keeps one you edited, and when the kit also changed it writes the new version as <file>.kit-new for you to merge. Installs from before .kit-baseline existed can't tell an edit from an older kit file, so their first upgrade replaces changed files and keeps the previous copies in .kit-backup/<timestamp>/. A file at a kit path that .kit-baseline doesn't list takes the same route: an older install, a module added since and a file of your own can't be told apart, so the kit's version lands and your copy goes to .kit-backup/<timestamp>/, named in the log. CLAUDE.md stays on the template it came from — the one .kit-baseline records, else the one its first line names, and only when it carries the kit's own sections. A CLAUDE.md of your own (one written by /init, say) is left alone and reported; so is one whose template can't be told. Pass --template to replace it with a stack template.

Customization

This kit is a starting point. You should:

1. Fill in CODEBASE_MAP.md — the more detail, the better Claude performs
2. Customize CLAUDE.project.md — add project-specific rules, constraints, and patterns
3. Add project docs — put stack-specific guides in agent_docs/project/
4. Track lessons — tasks/lessons/ compounds over time (one file per lesson, with YAML frontmatter and a Top Rules index), making Claude smarter per-project

Contributing

PRs welcome. If you've built a template for a stack we don't cover yet, open a PR.

Before opening a PR, run the same checks CI does. Each npm script is a thin alias to a scripts/*.sh file (so local and CI can't drift):

Command	What it runs
npm test	run-bench.sh (KitBench hook scenarios) + test-install.sh (install → upgrade → uninstall smoke test)
npm run bench	KitBench only
npm run test:install	Install/upgrade/uninstall smoke test only
npm run check	All drift/consistency gates: manifest, strict settings, AGENTS.md, skills
npm run lint:skills	Skill structure validation
npm run check:manifest	.kit-manifest is in sync with the tree
npm run check:strict-settings	.claude/settings.strict.json = settings.json + the strict delta
npm run check:agents-md	AGENTS.md is regenerated from CLAUDE.md

The kit's own maintenance scripts stay in this repo — install.sh doesn't copy them into projects, and --upgrade points out copies an earlier install left behind:

Script	What it does
./scripts/run-bench.sh	Runs KitBench — every hook scenario in bench/scenarios/ (CI runs this on each PR)
./scripts/test-install.sh	Smoke-tests install → upgrade → uninstall on a throwaway project (CI runs this on ubuntu + macOS)
./scripts/test-cli.sh	Smoke-tests bin/cli.sh subcommands — the npx entry point (CI runs this on ubuntu + macOS)
./scripts/sync-manifest.sh	Regenerates .kit-manifest; --check fails CI when it's stale
./scripts/gen-strict-settings.sh	Regenerates .claude/settings.strict.json from settings.json + the strict delta; --check fails CI when it's stale
./scripts/check-counts.sh	Asserts the skill/hook/agent/scenario totals match the declared counts
./scripts/check-scaffold.sh	Asserts scaffold/tasks/ carries no kit-internal state
./scripts/build-skills.sh	Builds SKILL.md from .tmpl templates + shared blocks
./scripts/gen-skill-docs.sh	Generates web MDX docs from SKILL.md files

License

MIT