claude-code-kit 0.56.0__tar.gz → 0.58.0__tar.gz

{claude_code_kit-0.56.0 → claude_code_kit-0.58.0}/.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.56.0",
+      "version": "0.58.0",
       "license": "MIT",
       "keywords": ["sdlc", "agents", "orchestration", "quality-gates", "workflow", "scaffold", "cookiecutter"]
     }

{claude_code_kit-0.56.0 → claude_code_kit-0.58.0}/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-kit",
-  "version": "0.56.0",
+  "version": "0.58.0",
   "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.56.0 → claude_code_kit-0.58.0}/CHANGELOG.md

@@ -4,6 +4,100 @@ 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.0] — 2026-07-06
+
+**Wave orchestration — program-scale runs, explicit skill routing, and the inventory-approval
+pattern.** Adopts the program-management patterns from Ryan Carson's public writeup of a
+40-session orchestrated migration (one pure orchestrator, audit-first frozen manifest, risk-ordered
+waves, disjoint file boundaries, gate-runner sessions, propose-inventory/human-approves,
+stop-and-report escalation, docs-as-final-wave) into the `/sdlc` pipeline. Stack-agnostic,
+catalog untouched. **+1 core rule (24 → 25); 0 new agents/skills.**
+
+### Added
+
+- **`rules/wave-orchestration.md`** (new core rule, installed by every profile). Program mode for
+  migration-scale work: Wave 0 parallel read-only audits synthesized into **one frozen scope
+  manifest** committed to the repo (every unit gets a verdict + wave number; `UNKNOWN` = stop and
+  ask; no worker re-litigates scope); waves sequenced by **risk, not convenience** (irreversible
+  steps last, restore-point git tags); **disjoint file boundaries** stated in every parallel worker
+  prompt; **gate-runner workers** between waves (regression suite on an isolated branch, backup
+  audit + fresh snapshot before destructive waves); the **inventory pattern** for irreversible steps
+  (approve the list, not the idea); a pre-declared **escalation path** (workers stop and report,
+  never improvise); and a mandatory **knowledge-closeout wave** (docs/rules/skills/agent memory
+  updated to the new state of the world).
+- **`orchestrator` Mode E — Program / Wave Mode.** New classification (`program-scale`: > ~20
+  files / multiple subsystems, or any irreversible step) and the wave pipeline above, plus three new
+  orchestrator sections: **Skill Routing** (every spawn prompt names the skill(s) the worker must
+  load for its stage — spec → `spec-driven-development`, implementation → `incremental-implementation`
+  + lane overlays, closeout → `refresh-docs`/`remember`/`consolidate-learnings`, etc.; absent skills
+  drop silently), **Model Tiering** (cheap tier for audits/sweeps/scans, standard for build/review/
+  gates, top tier only for orchestration/hard reasoning, per `rules/model-tiers.md`), and an
+  **Escalation Protocol for Workers** (stop, report to the orchestrator, don't improvise; overrides
+  recorded in the manifest/CONTINUITY). Orchestrator rules 19–23 pin all of it.
+- **`rules/human-in-the-loop.md` — "approve the inventory, not the idea."** Destructive/irreversible
+  asks must be inventory-shaped: dry-run list + counts proposed, the human approves that exact list,
+  the agent executes exactly it and re-verifies counts; deviations stop and re-enter the protocol.
+
+### Changed
+
+- **`skills/sdlc/SKILL.md`** — classification now includes `program-scale` → Mode E;
+  `wave-orchestration.md` added to the load-the-contract list; new step 3 makes skill routing and
+  per-worker model tiering an explicit orchestrator instruction on every run.
+- **`rules/mandatory-workflow.md`** — the "Which Workflow?" table routes migration-scale /
+  irreversible work to `wave-orchestration.md` (units inside a wave still run the bug-fix or
+  feature workflow).
+- **`orchestrator` parallelism rules** — explicit **disjoint file boundaries are now mandatory for
+  every parallel spawn in every mode**, not just an early-intervention health signal.
+- Docs/counts: README, `CLAUDE.md`, `docs/architecture.md`, `docs/skill-audit.md` updated for the
+  25-rule core.
+
+## [0.57.0] — 2026-07-03
+
+**Adoption & hardening — release automation, honest docs, and a credibility pass.** No new
+capability and no change to the core promise: configuration-only SDLC scaffolding for Claude Code, no
+application code, no Docker, stack-agnostic core, catalog-driven. This release closes the gap between
+"published to PyPI" and "tagged/released on GitHub," adds an honest release + road-to-1.0 policy, audits
+the skill surface, and tightens the README so every claim is verifiable. **0 new agents/skills/rules;
+`catalog.resolve()` and `catalog/*.yaml` untouched.**
+
+### Added
+
+- **Automated git tag + GitHub Release on publish.** `publish.yml` gains a `github-release` job that,
+  after a successful PyPI publish, creates the `vX.Y.Z` tag and a GitHub Release whose body is that
+  version's `CHANGELOG.md` section. Idempotent (a re-run over an already-released version is a no-op) and
+  downstream of `publish` (a Release is only cut once the wheel is actually on PyPI).
+- **`scripts/backfill-releases.sh` (`--dry-run`).** One-off, idempotent backfill that retroactively
+  creates the tag + Release for past versions that shipped via merge-to-main before the automation
+  existed. Anchors each tag to the commit that introduced that version into `pyproject.toml` (git
+  pickaxe), and skips — with a warning — any version whose release commit can't be located.
+- **[`docs/RELEASE-POLICY.md`](docs/RELEASE-POLICY.md).** Versioning, latest-only support, the
+  five-place version bump + CHANGELOG, and the publish/tag/Release automation, in one place.
+- **[`docs/launch/road-to-1.0.md`](docs/launch/road-to-1.0.md).** An honest, verifiable list of what
+  stands between the current `4 - Beta` and 1.0 (stack coverage, enforcement honesty, hook portability,
+  evidence base, export fidelity, API stability). The Development Status classifier stays `4 - Beta`.
+- **[`docs/skill-audit.md`](docs/skill-audit.md).** Core-vs-collection classification, the per-profile
+  install footprint (agents/skills/rules + an on-disk token estimate), and the finding that the
+  `enterprise` profile's `skills: all` installs every collection skill regardless of the chosen stack.
+  Documents and recommends; changes no profile (skills load on demand, so this is selection, not
+  always-resident context).
+- **Launch-prep assets under `docs/launch/`** (owner checklists, not code): `github-about.md`,
+  `demo-script.md`, `directory-submission.md`, `awesome-prs.md`, `posts.md`, and `seed-issues.md`.
+
+### Changed
+
+- **README credibility pass.** Strengthened the anti-sycophancy / evidence framing and added a
+  "What loads into your context" per-profile table (agents/skills/rules), so the footprint is explicit
+  before install. Counts remain pinned by `scripts/check_docs_consistency.py`.
+
+### Not adopted (deliberately)
+
+- **No version-parity CI addition** — `scripts/check_docs_consistency.py::check_versions()` already
+  enforces parity across the four manifests, `SECURITY.md`, and the latest CHANGELOG heading.
+- **No `profiles.yaml` change** for the `skills: all` finding — flagged and recommended in the audit;
+  any opt-in must stay a catalog/config change with no `resolve()` branching (golden rule #6).
+- **Development Status stays `4 - Beta`** — the classifier is not flipped until the road-to-1.0 gaps
+  are met.
+
 ## [0.56.0] — 2026-07-01
 
 **`export` command — carry the config to Cursor / VS Code / GitHub Copilot.** A teammate who works in

claude_code_kit-0.58.0/CLAUDE.md

@@ -0,0 +1,166 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+# Developing claude-kit
+
+This repository **is** claude-kit — a Cookiecutter-style scaffolder that installs a stack-agnostic,
+autonomous-SDLC **configuration** (no application code, no Docker) into a Claude Code project. It is
+distributed two ways from one source of truth:
+
+1. **As a Claude Code plugin** — components are auto-discovered from the repo root.
+2. **As a pip package** — `claude-kit` (CLI: `claude-kit` / `ckit` / `claude-sdlc`) scaffolds the
+   same content into any project's `.claude/`, driven by the `catalog/` (stacks · profiles · MCP).
+
+> Note: the files in this repo are the **kit's payload**, not rules for this repo itself. The
+> generic engineering ruleset that gets installed into user projects lives in
+> `templates/CLAUDE.md`, **not** this file.
+
+## Core architecture
+
+The kit's central data flow is **Selection → catalog.resolve() → ResolvedPlan → scaffold.install_sdlc()**:
+
+1. **`Selection`** (`models.py`) — user choices (stack, profile, MCP servers, scope, autonomy, …)
+   collected interactively by `prompts.py` or passed via `--defaults`/`--config`.
+2. **`catalog.resolve()`** (`catalog.py`) — reads `catalog/stacks.yaml`, `profiles.yaml`,
+   `mcp.yaml`, `org.yaml` and resolves the Selection into a **`ResolvedPlan`**: which agents,
+   skills, hooks, overlay rules, overlay agents, gates, and MCP fragments to install. This
+   function must stay **branch-free** — no stack- or org-specific code paths.
+3. **`scaffold.install_sdlc()`** (`scaffold.py`) — takes the ResolvedPlan and writes files into
+   the target project: `CLAUDE.md`, `.claude/{rules,agents,skills,hooks,templates,config}`,
+   optional `.mcp.json` and org packs. Records per-file checksums + ownership in
+   `.claude/config/init-options.json` for safe upgrades.
+4. **`upgrader.upgrade()`** (`upgrader.py`) — compares the live install against the plan from the
+   current kit version, refreshes kit/overlay files whose checksums match, preserves user-edited
+   files (drops new versions as `.claude-kit` sidecars), and writes a transactional journal
+   (`upgrade-in-progress.json`) so an interrupted run can be safely resumed.
+5. **`export`** (`export.py`) — projects the same `ResolvedPlan` into Cursor (`.cursor/rules/*.mdc`),
+   a root `AGENTS.md`, or GitHub Copilot (`.github/copilot-instructions.md`) for non-Claude-Code editors.
+
+### key source modules
+
+| Module | Role |
+|--------|------|
+| `cli.py` | Typer app — all CLI commands (`init`, `validate`, `doctor`, `diff`, `export`, `upgrade`, `pipeline`, `list-options`, `status`). Experimental/planned commands are hidden unless `CLAUDE_KIT_EXPERIMENTAL=1`. |
+| `models.py` | Dataclass contracts: `Selection`, `ResolvedPlan`, `OrgPlan`, `InitOptions`, `FileRecord`, `UpgradeJournal`. The typed seam between prompts → resolver → installer → upgrader. |
+| `catalog.py` | The resolver — converts a `Selection` into a `ResolvedPlan` by reading the catalog YAML files. Must stay branch-free. |
+| `prompts.py` | Interactive `init` question flow (stack, profile, MCP, org scope, …). |
+| `scaffold.py` | Writes the resolved plan to disk. Also provides `payload_dir()` which locates the bundled payload (source checkout or wheel `_payload/`). |
+| `render.py` | Jinja2 rendering — `CLAUDE.md` and `README.claude-sdlc.md` templates. |
+| `hooks.py` | The `HOOK_REGISTRY` (all hook definitions + script mappings) plus `PLUGIN_HOOK_IDS`, `STARTER_HOOK_IDS`, and `PLUGIN_ONLY_HOOKS`. Contains the drift-test logic used by `gen_hooks.py --check`. |
+| `upgrader.py` | Safe, edit-preserving upgrade: checksum comparison, transactional journal, sidecar fallback for user-edited files. |
+| `validator.py` | Structural validation of an installed config (`validate` + `--strict` mode). |
+| `schemas.py` | JSON Schema definitions for catalog integrity checks (`validate --strict`). |
+| `pipeline.py` | Deterministic `/sdlc` state-file ops (validate, status, close-gate, abort) — inspects the state files, does **not** run the pipeline. |
+| `export.py` | Projection into Cursor / AGENTS.md / Copilot formats. |
+| `detect.py` | Stack detection from a target repo (heuristic-based; non-blocking). |
+| `report.py` | Human-readable reporting for `doctor` and `status` commands. |
+| `__init__.py` | The `__version__` string — one of the five places that must be bumped on release. |
+
+## Repository layout
+
+| Path | Purpose |
+|------|---------|
+| `.claude-plugin/plugin.json` | Plugin manifest (name, version, hooks path) |
+| `.claude-plugin/marketplace.json` | Marketplace entry so `/plugin marketplace add` works |
+| `agents/` | SDLC pipeline subagents (auto-discovered by the plugin); each carries a `tier:` field |
+| `skills/` | Agent skills (auto-discovered by the plugin); `skills/sdlc/` is the `/sdlc` entrypoint |
+| `commands/` | Slash commands: `/claude-kit:init`, `:sdlc`, `:status`, `:abort` (init prefers the pip CLI, falls back to `init.sh`; sdlc delegates to the `sdlc` skill; abort tears down an in-progress `/sdlc` run) |
+| `hooks/hooks.json` + `hooks/scripts/` | Event hooks (paths via `${CLAUDE_PLUGIN_ROOT}`) |
+| `rules/` | The 25-file stack-agnostic engineering rule set (scaffolded into `.claude/rules/`), including the agent-operation rules (reasoning, guardrails, resilience, goal-setting, human-in-the-loop, model-tiers, evals, tool-design — see `docs/agentic-patterns.md`), the program-scale `wave-orchestration` rule, the service-level `resilience-engineering` rule, and the org-core rules `autonomy-levels` + `risk-classification` (see `docs/org-capabilities.md`) |
+| `catalog/` | **Data-driven registry** — `stacks.yaml` · `profiles.yaml` · `mcp.yaml` · `org.yaml`. The only thing that decides what `resolve()` installs. Adding a stack/profile/server/pack is a data change here. |
+| `templates/` | `CLAUDE.md`, `CLAUDE.stack.md.tmpl`, `README.claude-sdlc.md.tmpl`, `CONTINUITY.template.md`, `settings.json`, `artifacts/`, `agent-memory/` seed |
+| `templates/stacks/<kind>/<id>/` | Per-stack **overlay** content: `rules/` (+ `agents/` for DB stacks). **No application code, no Docker** — the only place stack-specific content lives. |
+| `templates/org/` | **Org overlay** content (scope-gated, organization only): `skills/`, `agents/` (personas), `rules/` (policy/vibe), `packs/<pack>/{pack.yaml,README.md}`, `README.md`. Wired via `catalog/org.yaml`. The only place org-specific content lives. |
+| `scripts/init.sh` | Thin no-pip fallback scaffolder (copies the full payload; no catalog resolution) |
+| `src/claude_kit/` | The pip CLI (Typer): `cli.py`, `catalog.py` (resolver), `prompts.py`, `models.py`, `scaffold.py` (installer), `render.py` (Jinja2), `hooks.py`, `validator.py` (incl. `validate --strict` + `check_catalog`), `upgrader.py`, `pipeline.py` (deterministic `/sdlc` state-file ops) |
+| `tests/` | pytest suite (catalog, render, scaffold, validator, upgrader, CLI; incl. the profile×stack×scope self-test matrix) |
+| `examples/` | Synthetic end-to-end `/sdlc` worked example (repo reference; **not** bundled into the wheel) |
+| `docs/architecture.md` · `docs/agents.md` · `docs/coverage-audit.md` · `docs/eval-harness.md` | Architecture diagrams · agent guide · the GATED-vs-RULE-vs-SKILL enforcement audit · the with/without eval template |
+| `pyproject.toml` | Packaging (deps: typer/jinja2/pyyaml); `[tool.hatch...force-include]` bundles the payload into the wheel |
+
+**One source of truth:** `agents/ skills/ commands/ hooks/ rules/ templates/ catalog/` at the repo
+root are read directly by the plugin **and** bundled into the wheel (mapped to
+`claude_kit/_payload/`) for the pip CLI. Never duplicate this content.
+
+## Golden rules for changes here
+
+1. **Keep the core payload stack-agnostic.** No FastAPI/React/Python/TypeScript/Docker/etc.
+   specifics in `rules/`, `agents/`, or `skills/`. Use neutral phrasing ("the project's linter /
+   test runner / build"); the `devops-engineer` is **container-optional**, never Docker-required.
+   The backend/frontend split may appear only as the canonical example of two independent parallel
+   lanes. **All** stack-specific content (overlay rules like `fastapi-patterns.md`, DB overlay agents
+   like `postgres-specialist`, exact commands) lives **only** under `templates/stacks/<kind>/<id>/`
+   and is wired up via `catalog/stacks.yaml` — never leak it into the agnostic core, and never add
+   application code or Docker anywhere.
+2. **Reference rules by their canonical filename** under `.claude/rules/…` (that's where they
+   land in a user project). The current core rule set is the 25 files in `rules/` (org policy/vibe
+   rules under `templates/org/rules/` install only in organization scope).
+3. **Plugin components live at the repo root**, never inside `.claude-plugin/` (only the
+   manifest goes there).
+4. **Hook scripts use `${CLAUDE_PLUGIN_ROOT}`** for plugin context and degrade to no-ops when
+   a tool isn't present (stack detection, never hard failure).
+5. **Never hand-edit `hooks/hooks.json` or `templates/settings.json`.** These are generated by
+   `python scripts/gen_hooks.py` from the `HOOK_REGISTRY` in `src/claude_kit/hooks.py`. Adding a
+   hook means: add the script → register it in `hooks.py` → list it in the relevant profile(s) →
+   run `gen_hooks.py`. A drift test (`gen_hooks.py --check`) fails CI if the generated files
+   diverge from the registry.
+6. **Bump the version in all five places** together for a release — `pyproject.toml`,
+   `.claude-plugin/plugin.json`, the `.claude-plugin/marketplace.json` entry,
+   `src/claude_kit/__init__.py` (`__version__`), and `SECURITY.md` — and add a `CHANGELOG.md`
+   entry (including a "Not adopted (deliberately)" block). `check_docs_consistency.py` enforces
+   parity across all five + the latest CHANGELOG.md heading.
+7. **Extend via the catalog, not code.** A new framework/database/profile/MCP server is a
+   `catalog/*.yaml` edit plus a `templates/stacks/<dir>/` folder; a new org pack/team/autonomy level
+   is a `catalog/org.yaml` edit plus content under `templates/org/`. `catalog.resolve()` must not grow
+   stack- or org-specific branches (the org layer is the same scope-gated lookup/union as profiles/mcp).
+   Mark not-yet-shipped entries `status: planned`.
+8. **Keep the org layer scope-gated and reuse-first.** Org content installs **only** when
+   `scope == organization`; packs MAP roles to existing components (`existing: true`) and create only
+   genuinely-new content (`existing: false`) — never a competing duplicate of an existing
+   agent/skill/rule. Org rules/skills/agents are stack-agnostic too. See `docs/org-capabilities.md`.
+
+## Dogfooding / local testing
+
+- **Plugin:** `claude` → `/plugin marketplace add .` → `/plugin install claude-kit` (loads the
+  agents/skills/commands/hooks from this checkout).
+- **CLI:** `pip install -e '.[dev]'` then `claude-kit init /tmp/demo --defaults` (or interactive),
+  `claude-kit validate /tmp/demo`, `claude-kit diff /tmp/demo`, and inspect the result.
+- **Tests:** `pytest` runs the full suite. Run a single test with `pytest tests/test_catalog.py -k "test_name"`.
+  The suite calls library functions directly (no subprocess) for speed and determinism, using the
+  bundled payload resolved via `scaffold.payload_dir()`. Key invariants asserted: no-Docker,
+  profile-subset (`lean ⊂ standard ⊂ enterprise`), MCP-gating, upgrade-safety, and export parity.
+- **Lint & drift (all run in CI — keep them green locally):**
+  ```bash
+  ruff check src scripts tests && ruff format --check src scripts tests
+  mypy
+  shellcheck -S warning hooks/scripts/*.sh scripts/*.sh
+  python scripts/gen_hooks.py --check          # hooks.json + settings.json drift
+  python scripts/check_docs_consistency.py     # version parity + CHANGELOG heading
+  ```
+- **Stack-leakage guard:** `grep -rInE 'fastapi|sqlalchemy|alembic|docker' rules agents skills` — should
+  be clean (balanced multi-framework *example* lists are acceptable; a real leak is agnostic logic
+  branching on a specific stack).
+- **Build:** `python3 -m build && python3 -m twine check dist/*`.
+- **CI:** Tests + lint + drift checks run on every PR. Publishing to PyPI happens automatically on
+  merge to `main` via OIDC trusted publishing when the version is new (`.github/workflows/publish.yml`).
+
+### Test conventions
+
+- Tests mirror the `src/claude_kit/` module they exercise: `test_catalog.py` tests `catalog.py`, etc.
+- `tests/_helpers.py` provides reusable factory functions.
+- `tests/conftest.py` exposes a session-scoped `payload` fixture pointing at the bundled payload root.
+- The profile×stack×scope self-test matrix backs the stack-agnostic claim — every profile installs a
+  strict subset of the next (`lean ⊂ standard ⊂ enterprise`).
+
+### Releasing
+
+1. Bump the version in **all five** places (see golden rule #6 above).
+2. Add a `CHANGELOG.md` entry with a **"Not adopted (deliberately)"** block.
+3. Ensure `pytest` + all lint/drift checks are green.
+4. Build: `python3 -m build && python3 -m twine check dist/*`.
+5. Merge to `main` — CI auto-publishes to PyPI (OIDC trusted publishing). Manual `twine upload` is
+   the fallback.
+6. Tag the release and push so plugin users get the update.
+
+See `CONTRIBUTING.md` for the full contributor workflow.

{claude_code_kit-0.56.0 → claude_code_kit-0.58.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-code-kit
-Version: 0.56.0
+Version: 0.58.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
@@ -43,6 +43,12 @@ assumed, or partial-output "it works" is itself an auto-Critical finding — so
 checks actually ran. A Cookiecutter-style scaffolder, installed as **configuration only — 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)
@@ -100,7 +106,7 @@ Quick start) for the full breakdown of any row.
 | 🔁 **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** | **24** stack-agnostic core rules (incl. 8 agent-operation rules) + **104** context-activated skills (56 core + 48 stack-collection) |
+| 📐 **Rules & skills** | **25** stack-agnostic core rules (incl. 8 agent-operation rules) + **104** context-activated skills (56 core + 48 stack-collection) |
 | 🧱 **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 |
@@ -324,8 +330,8 @@ need.
 
 <br>
 
-- **24 stack-agnostic core rules** in [`rules/`](rules/) — `mandatory-workflow`, `quality-gates`,
-  `rarv-cycle`, `continuity`, plus eight agent-operation rules and `autonomy-levels` +
+- **25 stack-agnostic core rules** in [`rules/`](rules/) — `mandatory-workflow`, `quality-gates`,
+  `rarv-cycle`, `continuity`, `wave-orchestration`, plus eight agent-operation rules and `autonomy-levels` +
   `risk-classification` (see [`docs/agentic-patterns.md`](docs/agentic-patterns.md)).
 - **104 on-demand skills** in [`skills/`](skills/) (56 core + 48 stack-collection) — spec-driven dev, planning, TDD, debugging, code
   review, threat modeling, and more — activated by context and led by the `sdlc` entrypoint.
@@ -363,6 +369,26 @@ need.
   compliance, production-data) install only in organization scope (see
   [`docs/org-capabilities.md`](docs/org-capabilities.md)).
 
+**What loads into your context** — 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 | 14 | 35 |
+| `standard` (default) | 26 | 42 | 35 |
+| `enterprise` | 31 | 104 | 35 |
+
+- **Rules are profile-independent** — every profile installs the same 25 core rules + the selected
+  stack's overlays (11 for this stack = 35); rigor changes the *agents and gates*, not the rule set.
+- **Skills activate on demand** — they are installed and available, then pulled into context by task
+  relevance, not all held resident at once. The count is what's on disk, not a fixed context tax.
+- **Counts include stack overlays** — the numbers above already fold in the chosen stack (e.g. the
+  Postgres overlay adds 3 agents, which is why `enterprise` shows 31 against a 28-agent core roster). A
+  different stack shifts them by a few.
+- **`enterprise` installs the whole skill collection** (`skills: all`) — all 104 skills, including
+  collection skills for stacks you didn't select. That's disk/selection footprint, not always-resident
+  context, but if you want a tighter install prefer `standard`. See [`docs/skill-audit.md`](docs/skill-audit.md).
+
 </details>
 
 <details>
@@ -483,7 +509,7 @@ owned gates, and the rule that **no gate passes on an unproven verdict**.
 | **[wshobson/agents](https://github.com/wshobson/agents)** & similar agent collections | Large libraries of individual subagent prompts you pick from | 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) | The same coverage-gate idea (the `story-planner` 1f gate + `task-tracker-sync`) **absorbed 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 | **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 | A **catalog-driven generator**: resolves your stack/profile/scope into the right subset of 24 rules, 28 agents, 104 skills, gates, and hooks, kept **upgradeable** (`claude-kit upgrade` preserves your edits via owner + checksum). |
+| **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** (`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
@@ -686,7 +712,7 @@ rollback) in `security-and-hardening` (from `Netflix/repokid`).
 
 ## Rules & skills
 
-**Rules** ([`rules/`](rules/)) are the 24 stack-agnostic contracts every agent obeys — the
+**Rules** ([`rules/`](rules/)) are the 25 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`,
@@ -838,7 +864,7 @@ build attestations** for supply-chain provenance. Report vulnerabilities private
 ```
 claude-kit/
 ├── .claude-plugin/        plugin.json + marketplace.json
-├── agents/                28 SDLC agents          rules/        24 engineering rules
+├── agents/                28 SDLC agents          rules/        25 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

{claude_code_kit-0.56.0 → claude_code_kit-0.58.0}/README.md

@@ -10,6 +10,12 @@ assumed, or partial-output "it works" is itself an auto-Critical finding — so
 checks actually ran. A Cookiecutter-style scaffolder, installed as **configuration only — 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)
@@ -67,7 +73,7 @@ Quick start) for the full breakdown of any row.
 | 🔁 **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** | **24** stack-agnostic core rules (incl. 8 agent-operation rules) + **104** context-activated skills (56 core + 48 stack-collection) |
+| 📐 **Rules & skills** | **25** stack-agnostic core rules (incl. 8 agent-operation rules) + **104** context-activated skills (56 core + 48 stack-collection) |
 | 🧱 **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 |
@@ -291,8 +297,8 @@ need.
 
 <br>
 
-- **24 stack-agnostic core rules** in [`rules/`](rules/) — `mandatory-workflow`, `quality-gates`,
-  `rarv-cycle`, `continuity`, plus eight agent-operation rules and `autonomy-levels` +
+- **25 stack-agnostic core rules** in [`rules/`](rules/) — `mandatory-workflow`, `quality-gates`,
+  `rarv-cycle`, `continuity`, `wave-orchestration`, plus eight agent-operation rules and `autonomy-levels` +
   `risk-classification` (see [`docs/agentic-patterns.md`](docs/agentic-patterns.md)).
 - **104 on-demand skills** in [`skills/`](skills/) (56 core + 48 stack-collection) — spec-driven dev, planning, TDD, debugging, code
   review, threat modeling, and more — activated by context and led by the `sdlc` entrypoint.
@@ -330,6 +336,26 @@ need.
   compliance, production-data) install only in organization scope (see
   [`docs/org-capabilities.md`](docs/org-capabilities.md)).
 
+**What loads into your context** — 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 | 14 | 35 |
+| `standard` (default) | 26 | 42 | 35 |
+| `enterprise` | 31 | 104 | 35 |
+
+- **Rules are profile-independent** — every profile installs the same 25 core rules + the selected
+  stack's overlays (11 for this stack = 35); rigor changes the *agents and gates*, not the rule set.
+- **Skills activate on demand** — they are installed and available, then pulled into context by task
+  relevance, not all held resident at once. The count is what's on disk, not a fixed context tax.
+- **Counts include stack overlays** — the numbers above already fold in the chosen stack (e.g. the
+  Postgres overlay adds 3 agents, which is why `enterprise` shows 31 against a 28-agent core roster). A
+  different stack shifts them by a few.
+- **`enterprise` installs the whole skill collection** (`skills: all`) — all 104 skills, including
+  collection skills for stacks you didn't select. That's disk/selection footprint, not always-resident
+  context, but if you want a tighter install prefer `standard`. See [`docs/skill-audit.md`](docs/skill-audit.md).
+
 </details>
 
 <details>
@@ -450,7 +476,7 @@ owned gates, and the rule that **no gate passes on an unproven verdict**.
 | **[wshobson/agents](https://github.com/wshobson/agents)** & similar agent collections | Large libraries of individual subagent prompts you pick from | 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) | The same coverage-gate idea (the `story-planner` 1f gate + `task-tracker-sync`) **absorbed 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 | **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 | A **catalog-driven generator**: resolves your stack/profile/scope into the right subset of 24 rules, 28 agents, 104 skills, gates, and hooks, kept **upgradeable** (`claude-kit upgrade` preserves your edits via owner + checksum). |
+| **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** (`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
@@ -653,7 +679,7 @@ rollback) in `security-and-hardening` (from `Netflix/repokid`).
 
 ## Rules & skills
 
-**Rules** ([`rules/`](rules/)) are the 24 stack-agnostic contracts every agent obeys — the
+**Rules** ([`rules/`](rules/)) are the 25 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`,
@@ -805,7 +831,7 @@ build attestations** for supply-chain provenance. Report vulnerabilities private
 ```
 claude-kit/
 ├── .claude-plugin/        plugin.json + marketplace.json
-├── agents/                28 SDLC agents          rules/        24 engineering rules
+├── agents/                28 SDLC agents          rules/        25 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

{claude_code_kit-0.56.0 → claude_code_kit-0.58.0}/agents/orchestrator.md

@@ -177,6 +177,34 @@ If the PRD contains **multiple independent features**, decompose into separate p
 ### Mode D: Fast-Track (bug fixes, small changes)
 Minimal pipeline for changes touching < 5 files or bug fixes. Skips spec, design, review chain. Goes straight to: Developer → Code Reviewer → Tester → PR Raiser.
 
+### Mode E: Program / Wave Mode (migrations, repo-wide refactors, irreversible steps)
+For **program-scale** work — many files across multiple subsystems (> ~20 files or > 2 independent
+lanes), or ANY run containing an irreversible step (production data mutation, schema migration,
+deletion sweep, dependency prune). Governed by `.claude/rules/wave-orchestration.md`:
+
+```
+Wave 0: parallel read-only AUDIT workers (one disjoint slice each: routes, entry points,
+        schema, shared libs, scripts, docs, CI)
+   → synthesize ONE manifest committed to the repo (docs/specs/{program}_manifest.md):
+     every unit gets a verdict + wave number; unknowns marked UNKNOWN = stop and ask
+   → restore-point git tag
+Wave 1..N: risk-ordered execution waves (safest first, irreversible LAST)
+   — within a wave: parallel workers with explicitly DISJOINT file boundaries
+   — between waves: dedicated GATE-RUNNER workers (regression suite on an isolated
+     branch/worktree; backup audit + fresh snapshot before any destructive wave; git tag
+     per landed wave)
+   — irreversible steps: worker proposes a dry-run INVENTORY (exact units + counts),
+     human approves the list, worker executes exactly that list, counts re-verified
+Final wave: knowledge closeout — update CLAUDE.md/rules/skills/runbooks + agent memory
+            to describe the NEW state (refresh-docs, remember, consolidate-learnings)
+```
+
+Inside each manifest unit, workers still follow the normal pipeline stages for their scope (a
+unit that is feature-sized runs Mode A/D internally). You remain a pure orchestrator: hold the
+manifest, the wave state, and the scope rulings; write zero code. Scope surprises are absorbed by
+YOU as manifest overrides — workers stop and report, never improvise (see Escalation Protocol for
+Workers below).
+
 ---
 
 ## Execution Protocol
@@ -185,8 +213,10 @@ Minimal pipeline for changes touching < 5 files or bug fixes. Skips spec, design
 - Parse the incoming PRD or unstructured requirements.
 - Resolve ambiguities with the human before proceeding.
 - **Classify work type**: `backend-only`, `frontend-only`, or `full-stack`.
-- **Classify scope**: `fast-track` (< 5 files, bug fix), `single-feature`, or `multi-feature`.
-- Choose execution mode: **D** (fast-track), **A** (single-stack), **B** (full-stack parallel), or **C** (multi-feature).
+- **Classify scope**: `fast-track` (< 5 files, bug fix), `single-feature`, `multi-feature`, or
+  `program-scale` (> ~20 files / multiple subsystems, or any irreversible step — see
+  `.claude/rules/wave-orchestration.md`; use the `risk-classifier` agent when in doubt).
+- Choose execution mode: **D** (fast-track), **A** (single-stack), **B** (full-stack parallel), **C** (multi-feature), or **E** (program/wave).
 - Create pipeline state: `PIPELINE: Stage 0 - Mode {A|B|C} selected`.
 
 ### Stage 1-2: Spec & Doc Writer (combined)
@@ -448,6 +478,14 @@ If any tester or senior tester (across any testing lane) finds issues:
 - All Testers complete → then All Senior Testers start → then Merge Reviewer verifies test coverage
 - PR Raiser → after test coverage merge reviewer passes
 
+### Disjoint file boundaries (mandatory for EVERY parallel spawn):
+Every prompt you give a parallel worker MUST name the exact files/directories it may touch, and the
+boundaries of concurrently-running workers MUST be mutually disjoint. No two agents may have the
+same file in scope at the same time; a file in no boundary is out of scope for everyone. A worker
+needing a file outside its boundary stops and reports to you — it never edits it. This is what makes
+parallelism safe: no merge conflicts, no cross-lane coordination
+(`.claude/rules/wave-orchestration.md` §3).
+
 ### Spawning parallel agents:
 When forking, launch ALL agents in the parallel lanes simultaneously:
 ```
@@ -489,6 +527,53 @@ status`; never edit code yourself.
 
 ---
 
+## Skill Routing (every spawn names its skills)
+
+Workers do not discover skills by luck. **Every spawn prompt names the skill(s) the agent must
+load** for its stage — from the installed set (check `.claude/skills/`; the `using-agent-skills`
+decision tree is the fallback router). Baseline map:
+
+| Stage / worker | Instruct it to use |
+|----------------|--------------------|
+| Spec & dev docs | `spec-driven-development` · `interview-me` (if ambiguous) · `scope` |
+| Story planning | `planning-and-task-breakdown` |
+| Design (UI) | `ui-ux-design` · `component-design` |
+| Implementation | `incremental-implementation` · `context-engineering` · the stack overlay skills for the lane (e.g. API lane → `api-and-interface-design`; UI lane → `frontend-ui-engineering`) · `doubt-driven-development` when stakes are high/unfamiliar |
+| Code review | `code-review-and-quality` · `over-engineering-review` (when warranted) |
+| Testing | `test-driven-development` · `unit-test` · `browser-testing-with-devtools` (UI) · `test-plan-review` (senior) |
+| Security | `security-and-hardening` · `security-verification` · `threat-model` (new surface) |
+| Audit workers (Mode E Wave 0) | read-only exploration + `scope`; report format per the manifest |
+| Gate runners | `smoke-test` / `manual-test` / the project's regression suite |
+| Debugging / defect loop | `debugging-and-error-recovery` · `bug-hunt` |
+| PR / delivery | `git-workflow-and-versioning` · `shipping-and-launch` |
+| Knowledge closeout (Mode E final wave) | `refresh-docs` · `documentation-and-adrs` · `remember` · `consolidate-learnings` |
+
+Only route to skills that are actually installed (profiles install different subsets); when a listed
+skill is absent, drop it silently rather than blocking.
+
+## Model Tiering (match the model to the worker)
+
+Pick each spawned agent's model per `.claude/rules/model-tiers.md` — don't run everything on the top
+tier. Rule of thumb: read-only audits, mechanical sweeps, and scanners → cheap tier; implementation,
+review, and gate adjudication → standard tier; orchestration and genuinely hard architectural
+reasoning → top tier. In Mode E the audit wave should be the cheapest line item in the program.
+
+## Escalation Protocol for Workers
+
+State this in **every** worker prompt: *if reality disagrees with your instructions (or, in Mode E,
+with the manifest) — a dependency the plan missed, a file outside your boundary you seem to need, a
+verdict that looks wrong — STOP and report to the orchestrator. Do not improvise, do not expand your
+own scope, do not "fix it while you're there."*
+
+You absorb the surprise into the plan: re-route, re-scope a lane, demote a Mode E unit to a later
+wave, record the override (in the manifest for Mode E; in CONTINUITY.md always), or escalate to the
+human per `.claude/rules/human-in-the-loop.md`. Workers never make scope decisions. For irreversible
+steps, apply the **inventory pattern**: the worker proposes the exact list (dry-run counts), the
+human approves the list — not the idea — and the worker executes exactly that list
+(`.claude/rules/wave-orchestration.md` §5).
+
+---
+
 ## State Tracking
 
 ```
@@ -617,3 +702,8 @@ When an agent fails, follow this escalation:
 16. **Persist working memory.** Read/write `.claude/CONTINUITY.md` every turn and at every stage transition; recover from it after compaction. Mirror gate-precise state into `.claude/state/pipeline-snapshot.json` and resume from it by *reloading* (re-enter after `last_gate_passed`), never by re-running passed gates or re-applying committed edits.
 17. **Anti-sycophancy.** In standard+, the plan is critiqued by `devils-advocate` before approval is final (Stage PC); and a unanimous PASS at the test-coverage gate is not VERIFIED until `devils-advocate` returns CONFIRMED.
 18. **Operability gates.** For deployable/observable changes, run DevOps (Pipeline Green) and Observability (Observability Ready) before the PR Raiser.
+19. **Name the skills in every spawn.** Each worker prompt states which skill(s) to load for its stage (Skill Routing table); never assume a worker will find them itself.
+20. **Disjoint boundaries in every parallel spawn.** Every parallel worker prompt names its exact file boundary; concurrent boundaries never overlap.
+21. **Program-scale work goes through Mode E.** Audit-first frozen manifest, risk-ordered waves (irreversible last), gate-runner workers between waves, inventory approval for irreversible steps, knowledge closeout as the final wave (`.claude/rules/wave-orchestration.md`).
+22. **Workers propose; humans approve.** Merges to the mainline, data changes, schema migrations, and UNKNOWN scope rulings are human decisions on a precise proposed inventory — approve the list, not the idea.
+23. **Match the model to the worker** per `.claude/rules/model-tiers.md` — cheap tier for audits/sweeps/scans, standard for build/review/gates, top tier only for orchestration and hard reasoning.