claude-code-kit 0.58.1__tar.gz → 0.58.2__tar.gz

{claude_code_kit-0.58.1 → claude_code_kit-0.58.2}/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
       "name": "claude-kit",
       "source": "./",
       "description": "Cookiecutter-style scaffolder for an autonomous Claude Code SDLC config (no app code, no Docker): install CLAUDE.md + .claude/ (rules, the profile's agents/skills, hooks, artifact templates) + optional .mcp.json, then run /sdlc to drive spec → review → build → test → security → ship through profile-aware quality gates, working memory, and a self-improving learnings loop.",
-      "version": "0.58.1",
+      "version": "0.58.2",
       "license": "MIT",
       "keywords": ["sdlc", "agents", "orchestration", "quality-gates", "workflow", "scaffold", "cookiecutter"]
     }

{claude_code_kit-0.58.1 → claude_code_kit-0.58.2}/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-kit",
-  "version": "0.58.1",
+  "version": "0.58.2",
   "description": "Cookiecutter-style scaffolder for an autonomous Claude Code SDLC config (no app code, no Docker). `claude-kit init` asks ordered questions and installs CLAUDE.md + .claude/ (rules, the 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 with working memory and a self-improving learnings loop.",
   "author": {
     "name": "Arjunsingh Yadav",

{claude_code_kit-0.58.1 → claude_code_kit-0.58.2}/CHANGELOG.md

@@ -4,6 +4,75 @@ All notable changes to claude-kit are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/), and the project uses
 [semantic versioning](https://semver.org/).
 
+## [0.58.2] — 2026-07-08
+
+**The advisory hook layer is now actually visible, and the scaffolded docs stop advertising
+things the install doesn't have.** A third multi-agent review round (17 agents; every finding
+re-verified against the official Claude Code hooks reference + changelog before any code) found
+one genuinely new defect class the previous rounds missed: six advisory hooks "warned" on exit-0
+**stderr**, which on PreToolUse/PostToolUse goes to the debug log only — the model never saw a
+single warning. 9 findings, all implemented; 0 new agents/skills/rules; resolver untouched.
+
+### Fixed
+
+- **Advisory hooks now reach the model** — `warn-large-edits`, `warn-sensitive-files`,
+  `warn-llm-io`, `warn-shared-modules`, `warn-missing-tests`, and `validate-frontmatter` emit
+  `hookSpecificOutput.additionalContext` JSON on stdout (the documented visible channel; the
+  warning text is unchanged). On Claude Code versions predating the field it is ignored — the
+  scripts degrade to exactly the old behavior, never an error.
+- **`capture-learnings.sh` end mode fits the SessionEnd budget** — the transcript scan + capture
+  spawn now detaches into the background after marking the session done, so the hook returns in
+  milliseconds instead of racing the 1.5 s SessionEnd default; the registry also grows per-hook
+  `timeout` support (the capture entry declares 30 s) for scaffolded installs.
+- **`type-check.sh` no longer fabricates type errors on machines without the toolchain** — the
+  tsc branch requires a local `node_modules/.bin/tsc`; a missing toolchain is a silent skip.
+- **`guard-destructive-git.sh` rule 3 is per-segment and staged-restore-aware** —
+  `git restore --staged .` (index-only, non-destructive) is exempted, `--worktree`/`-W`
+  variants still block, `-s` (= `--source`) gets no exemption, and a safe unstage in a compound
+  command can no longer mask a destructive discard in a later segment.
+- **`prompts.from_config` defaults are lane-aware** — a config that names a backend language but
+  no framework (`backend: go`, `backend: {language: go}`) now gets that lane's catalog default
+  (`net-http`), and `frontend: none` gets language `none` — matching the interactive flow instead
+  of silently inheriting the global default's `fastapi`/`typescript`. Data-driven lookup via
+  `catalog.list_options`; `resolve()` unchanged.
+- **`mode:` → `permissionMode:` in all six org personas + the acceptance-reviewer gains
+  `permissionMode: plan`** — `mode:` is not a Claude Code frontmatter key and was silently
+  ignored, leaving the personas without the read-only confinement their prompts promised. A new
+  payload-wide frontmatter test (`test_agent_frontmatter.py`) pins the whole class shut.
+- **The acceptance-reviewer joins the scribe pattern** — it returns the acceptance report in its
+  handoff and the Orchestrator persists it (orchestrator Stage 5.6 + `quality-gates.md` now say
+  so explicitly), closing the last read-only-agent-writes-files contradiction from 0.58.1.
+
+### Changed
+
+- **Scaffolded `CLAUDE.md` is profile-honest** — a new profile-gating paragraph states that
+  phases whose reviewer agents aren't installed are `SKIPPED (not in profile)` and never counted
+  as PASS, and the Roles list is scoped to "where your profile installs them". A lean install no
+  longer reads a charter mandating ~12 agents it doesn't have.
+- **Scaffolded `README.claude-sdlc.md` advertises only commands that exist** — all 11 phantom
+  slash commands swept to the real payload skills that own each behavior (e.g.
+  `/refactor-safely` → `/code-simplification`, `/write-tests` → `/test-driven-development`,
+  `/security-review` → `/security-verification`); the five org-only playbooks, the org personas,
+  their capability-matrix rows, and the org examples render only in organization scope; the
+  `.claude/org-packs/README.md` governance pointer renders only when packs were generated. A new
+  drift test renders both scopes and fails CI on any advertised command with no payload skill.
+- **Docs honesty on plugin confinement** — `docs/agents.md` + README now state that
+  `permissionMode` binds only for scaffolded `.claude/agents/` installs; plugin-loaded agents
+  ignore it (their prompts still forbid writes).
+
+### Not adopted (deliberately)
+
+- **The "lint-fix nudges on clean files" sub-claim** — refuted first-hand: the hook exits
+  silently when the linter makes no changes; no fix needed.
+- **The "capture-learnings double-capture" sub-claim** — the existing `mkdir`-based done-marker
+  lock already bounds concurrent end-mode runs to one capture; the detach fix preserves it.
+- **Creating 11 new skills to back the phantom commands** — the commands were renamed to existing
+  skills instead; growing the skill surface is a positioning decision the owner makes, not a
+  drive-by fix.
+- **A fully Jinja-rendered, profile-aware roles table in scaffolded `CLAUDE.md`** — the
+  one-paragraph gating statement fixes the dishonesty at a fraction of the template complexity;
+  the rendered-variant idea stays on the shelf as an optional follow-up.
+
 ## [0.58.1] — 2026-07-07
 
 **Pipeline agents can now actually persist what their prompts mandate.** An industry-review pass
@@ -18,6 +87,22 @@ the standard core (they now arrive via the selected stack's lane instead) — no
 
 ### Added
 
+- **README rebuilt as a pitch with pointers — 902 → 306 lines** (owner-requested simplification;
+  a two-agent docs review — first-impression critic + information architect — ranked the damage
+  first). Nothing was deleted from the project: the 24-row adoption-history table + the three
+  org-review deep dives moved to new `docs/influences.md`; install depth (all 8 init questions,
+  `init.yaml`, Windows, plugin-update steps, what-lands tree, stacks/memory detail) to new
+  `docs/install.md`; the CLI table + safe-upgrade mechanics + troubleshooting to new
+  `docs/cli.md`; the 28-agent roster to `docs/agents.md` (which previously had only the by-phase
+  view). The 190-line "Feature details" section and the duplicate source-of-truth mermaid were
+  pure duplication of surviving sections / `docs/architecture.md` and were dropped; the hero was
+  rewritten in plain language (no "gate"/"verdict" jargon before definition); comparison-table
+  cells capped near two lines. All honest-claims content survives in place (Skip-it-if, the
+  three trust caveats, export fidelity, the enterprise `skills: all` admission, the real-run
+  evidence — now promoted into Quick start). `check_docs_consistency.py`'s `_ANCHORS` was edited
+  in lockstep: every component count stays pinned ≥1× in the README, the roster/overlay anchors
+  re-point to `docs/agents.md` / `docs/install.md`, and the redundant duplicate pins (the same
+  number 3–4× in one file) went away with the duplicated prose.
 - **CI/issue-triggered runs get a design contract instead of a vendor YAML** (round-2 R18, the
   landscape item; every claim verified against the GitHub API first: spec-kit 0.12.4 (2026-07-02)
   shipped the label-driven `bug-fix` (#3258) and `bug-test` (#3257) agentic workflows and 0.12.2

claude_code_kit-0.58.2/PKG-INFO

@@ -0,0 +1,341 @@
+Metadata-Version: 2.4
+Name: claude-code-kit
+Version: 0.58.2
+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: jsonschema>=4.0; 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'
+Provides-Extra: schema
+Requires-Dist: jsonschema>=4.0; extra == 'schema'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# claude-kit
+
+**Turn Claude Code into a disciplined engineering team: one command — `/sdlc <task>` — runs your
+request through spec → review → code → test → security → PR, with a quality gate between every
+phase.**
+
+The differentiator is trust: **no gate passes without real, cited command output**, so a green
+result means the checks actually ran. It installs as **configuration only** — no runtime, no
+application code, no Docker.
+
+<!-- DEMO PLACEHOLDER — a 60–90s terminal capture of a gated `/sdlc` run belongs here once recorded.
+     Shot list, timing, and which real assets to show: docs/launch/demo-script.md.
+     The recording replays the genuine run already in examples/real-run/ (the devils-advocate catching a
+     Medium bug a unanimous review missed, and the gate refusing to advance until it was fixed).
+     Until the GIF exists, that folder IS the evidence — linked from "How it works" and "The pipeline" below. -->
+
+[![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)
+
+⚡ [Quick start](#quick-start) · 🧭 [How it works](#how-it-works) · 🔁 [The pipeline](#the-pipeline) · ⚖️ [Compare](#how-claude-kit-compares) · 🔒 [Security](#security--trust-model) · 📚 [Docs](#docs--deeper-reference)
+
+</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.**
+
+Your request flows through specialists — a spec writer, 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**. Choose your stack, rigor,
+and team scope at `init`; everything else adapts.
+
+**Use claude-kit if** you drive real repository changes with Claude Code and want a repeatable
+spec → review → test → security → PR workflow whose quality gates won't advance on an unproven verdict.
+
+**Skip it if** you want a small prompt pack, don't want project config written into your repo, or need a
+standalone runtime/daemon. claude-kit is **configuration for Claude Code**, not a separate runtime — and
+its guard hooks are convenience guardrails (they need `jq` + a POSIX shell and no-op without them), **not
+a hardened security boundary**. See [Known limitations](docs/KNOWN_LIMITATIONS.md).
+
+---
+
+## Quick start
+
+The fastest path to a gated run — **no CLI install, no `init`, no restart:**
+
+```text
+/plugin marketplace add ajyadav013/claude-kit
+/plugin install claude-kit
+/claude-kit:sdlc Add a /health endpoint that returns the build version
+```
+
+That's the whole loop in three lines: the standard pipeline runs immediately — spec → review →
+build → test, gate by gate — with every verdict backed by real output.
+
+**Proof it works:** [`examples/real-run/`](examples/real-run/) is a genuine captured run where the
+`devils-advocate` caught a Medium bug a unanimous review missed, and the gate refused to advance
+until it was fixed.
+
+When you want the pipeline tuned to *your* repo — your stack, commands, rigor profile, and the
+safety hooks — run `init`:
+
+<details open>
+<summary><b>A) As a Claude Code plugin&nbsp; (recommended)</b></summary>
+
+<br>
+
+```text
+/claude-kit:init        # Claude asks you the questions in chat, then runs the CLI non-interactively
+# ↻ restart Claude Code so the project's agents, skills & hooks load
+/sdlc Add a CSV export button to the reports page
+```
+
+> `/claude-kit:init` needs the Python CLI on PATH (`pipx install claude-code-kit`) — it resolves
+> your stack/profile and records checksums for safe `upgrade`. Details: [docs/install.md](docs/install.md).
+
+</details>
+
+<details>
+<summary><b>B) As a pip package&nbsp; (CI, onboarding, non-plugin workflows)</b></summary>
+
+<br>
+
+```bash
+pip install claude-code-kit             # note: the pip name is claude-code-kit, not claude-kit
+
+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` for the shell hooks (they no-op without it). **Windows** users: run inside WSL or Git Bash for
+> the hooks. Every install question, the `init.yaml` format, what lands on disk, and plugin-update
+> steps: **[docs/install.md](docs/install.md)**.
+
+---
+
+## What you get
+
+| Area | What you get |
+|------|--------------|
+| 🔁 **Pipeline & quality gates** | Gate-enforced progression — a phase advances only with zero open Critical/High/Medium findings — plus a fast-track for small changes and an anti-sycophancy `devils-advocate` pass |
+| 🤖 **Agent roster** | **28** tiered agents led by an Orchestrator that never writes code, plus per-database overlay agents and 6 org personas ([full roster](docs/agents.md)) |
+| 📐 **Rules & skills** | **25** stack-agnostic core rules + **104** context-activated skills (56 core + 48 stack-collection), pulled into context on demand |
+| 🧱 **Stacks & overlays** | A stack-agnostic core + **13** overlay rule files (React · FastAPI · Go · Postgres · Mongo) wired to your exact commands and path-scoped to load only when you touch matching files |
+| 🛠️ **Hooks & guards** | **18** event hooks — deterministic safety guards and advisory warnings — that no-op gracefully without `jq` |
+| 📦 **Distribution & lifecycle** | Plugin **and** pip from one source, **17** ready MCP fragments (version-pinned), edit-preserving `upgrade`, and a root `AGENTS.md` at init so non-Claude agents share the same standards |
+
+Profiles (`lean` · `standard` · `enterprise`), team scopes, autonomy levels, and org capability
+packs decide how much of this actually installs — see
+[Profiles & what lands in your project](#profiles--what-lands-in-your-project).
+
+---
+
+## How it works
+
+Four ideas do the heavy lifting:
+
+1. **Evidence or it didn't happen.** Every gate verdict — PASS or FAIL — must cite the command that
+   ran and its captured output. A verdict that's invented, assumed, or read off still-running work
+   is an **auto-Critical finding** — the same severity as a hardcoded secret
+   ([`quality-gates.md` §2.5](rules/quality-gates.md)).
+2. **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.
+3. **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.
+4. **Blind review + Devil's Advocate.** Parallel reviewers judge independently; a *unanimous* PASS
+   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, including how one source
+of truth ships as both a plugin and a pip package.
+
+---
+
+## 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.
+A **fast-track** mode collapses small changes (< 5 files) to Developer → Code Reviewer → Tester → PR;
+organization scope at `regulated` strictness adds `accessibility-clear` (WCAG-AA on changed UI).
+
+See the real captured run in [`examples/real-run/`](examples/real-run/) — a feature driven through
+every gate on a Go project, with the verbatim state file, agent verdicts, diff, and an asciicast —
+or the [synthetic walkthrough](examples/react-fastapi-postgres-feature/) of the default stack. To
+capture your own publishable run: [`docs/capture-a-real-run.md`](docs/capture-a-real-run.md).
+
+---
+
+## Profiles & what lands in your project
+
+The profile you pick decides how much lands in `.claude/`. Measured on a React + FastAPI +
+PostgreSQL project, individual scope:
+
+| Profile | Agents | Skills | Rules |
+|---------|-------:|-------:|------:|
+| `lean` | 8 | 15 | 36 |
+| `standard` (default) | 26 | 42 | 36 |
+| `enterprise` | 31 | 104 | 36 |
+
+- **Rules are profile-independent** — every profile installs the same 25 core rules + the selected
+  stack's overlays (11 for this stack = 36); rigor changes the *agents and gates*, not the rule set.
+- **Installs are stack-true** — every lane offers `none`, and a lane you don't have installs
+  nothing: a backend-only project gets no React rules, frontend skills, or npm commands.
+- **`enterprise` installs the whole skill collection** — including stacks you didn't select. That's
+  disk footprint, not always-resident context, but prefer `standard` for a tighter install. See
+  [`docs/skill-audit.md`](docs/skill-audit.md).
+
+Organization scope adds teams, 5 autonomy levels, review strictness, and capability packs — see
+[`docs/org-capabilities.md`](docs/org-capabilities.md).
+
+---
+
+## How claude-kit compares
+
+The closest alternative is just **using Claude Code's own subagents** — and that's the comparison
+that matters most: **native gives you the agents; claude-kit gives you the governance.**
+
+| Compared to… | What it is | What claude-kit adds |
+|---|---|---|
+| **Native Claude Code subagents / Agent Teams** | Spawn parallel agents on demand; you define workflow and verification yourself each time | A fixed, sequenced pipeline with owned gates, an evidence requirement for every verdict, the `devils-advocate` anti-rubber-stamp pass, and structured resume from the pipeline state file |
+| **[wshobson/agents](https://github.com/wshobson/agents)** & similar collections | Large libraries of individual subagent prompts you pick from | A smaller, opinionated set wired into a sequenced pipeline — agents are stages that hand off and block on each other, not a menu |
+| **[GitHub spec-kit](https://github.com/github/spec-kit)** | Spec-driven development as a platform: constitution → spec → tasks → analyze, plus label-driven CI stages | The same coverage-gate idea absorbed into a broader in-session lifecycle — review, security, build, test, release, and observability gates with enforced severity blocking. Complementary: their CI stages, this kit's gate depth ([details](docs/autonomous-operation.md)) |
+| **claude-flow / multi-agent runtimes** | Runtime orchestrators that *execute* swarms of agents | Portable configuration, not a running process — no daemon, no lock-in, no app code |
+| **dotfiles / `CLAUDE.md` starters** | A single rules file or settings snippet | A catalog-driven generator: resolves your stack/profile/scope into the right subset of 25 rules, 28 agents, 104 skills, gates, and hooks — kept upgradeable with your edits preserved |
+
+**Choose claude-kit when** you want a consistent, gate-enforced autonomous-SDLC setup that's the
+same across every repo and stack, installs in seconds, and ships nothing you have to run. It is
+**not** a runtime or a code library — it's the configuration that makes Claude Code's agents behave
+like a disciplined team.
+
+---
+
+## Use beyond Claude Code (export)
+
+`init` already emits a repo-root **`AGENTS.md`** so teammates on Cursor, VS Code, or Copilot get the
+kit's standards from day one. `claude-kit export` projects the full config into their native formats:
+
+```bash
+claude-kit export . -t cursor -t agents -t copilot
+```
+
+**Fidelity is honest:** rules, the project charter, and MCP servers port cleanly; the *enforced*
+gates and reviewer subagents are Claude-Code-only and travel as a single-agent checklist instead —
+every exported document says so. Full fidelity matrix: [`docs/cursor-export.md`](docs/cursor-export.md).
+
+---
+
+## Influences & reuse-first
+
+claude-kit evolves by reviewing excellent open-source projects and industry material, then adopting
+**only the genuinely-new ideas** — each review fetches the real source, adversarially maps it against
+the kit's existing files, and ships only the non-duplicative gaps (many reviews conclude with
+"0 new agents/skills/rules" on purpose). The full adoption history — from Agentic Design Patterns
+through the alibaba/microsoft/google/Meta/Netflix·aws·apple org reviews — lives in
+[`docs/influences.md`](docs/influences.md), with per-release detail in the [CHANGELOG](CHANGELOG.md).
+
+---
+
+## Security & trust model
+
+claude-kit installs **configuration only** — no application code, no Docker, nothing that runs as a
+service. Three honest caveats before you rely on it:
+
+- **The guard hooks are convenience, not a hardened boundary.** They raise the cost of a mistake but
+  don't sandbox the agent; they need a POSIX shell + `jq` and silently no-op without them. Seatbelts,
+  not walls.
+- **Most quality gates are agent protocols, not mechanical enforcement.** 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. Relatedly: the agents' `permissionMode` confinement
+  (read-only reviewers) binds only in **init-scaffolded** projects — plugin-loaded agents ignore
+  it, so run the pipeline from a scaffolded project when that confinement matters.
+- **MCP servers are third-party code.** Each fragment runs an external package — pinned to an exact
+  version, never `@latest` — 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** with **PEP 740 build attestations**.
+Report vulnerabilities privately — see [`SECURITY.md`](SECURITY.md).
+
+---
+
+## Docs & deeper reference
+
+| Doc | What's in it |
+|---|---|
+| [`docs/install.md`](docs/install.md) | Every install detail: prerequisites, Windows, plugin updates, all `init` questions, `init.yaml`, what lands on disk |
+| [`docs/cli.md`](docs/cli.md) | Full CLI command reference, safe-upgrade mechanics, troubleshooting |
+| [`docs/agents.md`](docs/agents.md) | How to drive the agents + the full 28-agent roster and per-run cost |
+| [`docs/architecture.md`](docs/architecture.md) | Diagrams: distribution, catalog resolution, the state machine — and how to extend via the catalog |
+| [`docs/influences.md`](docs/influences.md) | The reuse-first adoption history: what we learned, shipped, and deliberately skipped |
+| [`docs/autonomous-operation.md`](docs/autonomous-operation.md) | Unattended runs: permission modes × autonomy levels, headless mode, the bounded loop script, CI-trigger design |
+| [`docs/cursor-export.md`](docs/cursor-export.md) | Export fidelity matrix and `.mdc` mapping |
+| [`docs/org-capabilities.md`](docs/org-capabilities.md) | Organization scope: packs, personas, autonomy, review strictness |
+| [`docs/skill-audit.md`](docs/skill-audit.md) | Per-profile skill footprint and context economics |
+| [`docs/KNOWN_LIMITATIONS.md`](docs/KNOWN_LIMITATIONS.md) | What the kit deliberately does not claim |
+| [`examples/real-run/`](examples/real-run/) | The captured, gated real run (evidence, not marketing) |
+| [`CONTRIBUTING.md`](CONTRIBUTING.md) | Contributor workflow; [`CLAUDE.md`](CLAUDE.md) covers developing the kit itself |
+
+---
+
+## 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