claude-code-kit 0.66.0__tar.gz → 0.67.0__tar.gz

{claude_code_kit-0.66.0 → claude_code_kit-0.67.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.66.0",
+      "version": "0.67.0",
       "license": "MIT",
       "keywords": ["sdlc", "agents", "orchestration", "quality-gates", "workflow", "scaffold", "cookiecutter"]
     }

{claude_code_kit-0.66.0 → claude_code_kit-0.67.0}/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-kit",
-  "version": "0.66.0",
+  "version": "0.67.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.66.0 → claude_code_kit-0.67.0}/CHANGELOG.md

@@ -4,6 +4,88 @@ 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.67.0] — 2026-07-24
+
+**System-design absorption pass from
+[Technical-Engineering-Articles](https://github.com/harshit3011/Technical-Engineering-Articles)
+(user-named source; MIT list-repo indexing 46 public X threads by
+[@Harry_The_Nerd](https://x.com/Harry_The_Nerd) — thread content © the author; ideas absorbed in
+our own words, zero verbatim text, attribution in every digest and `docs/influences.md`).**
+All 46 threads fetched (logged-out browser render, no login walls); a 92-agent digest→verify
+pipeline classified 614 candidate patterns against the live kit (236 absent / 159 partial /
+170 covered / 49 not-absorbable) with a 3-claim fidelity spot-check per digest (46/46 passed 3/3),
+then a global adversarial refute deduplicated the composite-app repeats and enforced the caps:
+**exactly 2 new skills, exactly 6 extensions, everything else digest-only.**
+
+### Added
+- **`system-design-patterns` collection skill** — system-scale building blocks: back-of-envelope
+  estimation & read/write asymmetry, rate-limiting algorithms, load balancing, CDN/edge, the
+  caching hierarchy (L1/L2/L3, precompute, selective), URL shortening & unique-ID generation,
+  notification and news-feed fan-out, autocomplete/typeahead, chat/real-time sync, data-modeling
+  building blocks (metadata/blob split, expiring holds, calendar inventory), microservice boundary
+  criteria (four-part acceptance test, distributed-monolith diagnostic, Conway's Law), and a
+  composite-application pattern map. 24 attributed `htn-` digests in `references/`.
+- **`distributed-systems-patterns` collection skill** — distributing state: consistent hashing,
+  partitioning/sharding (and the cache → replicas → shard-last ladder), replication & quorum
+  (N/W/R), distributed KV-store anatomy (hinted handoff, read repair, anti-entropy, vector
+  clocks), distributed cache design, failure detection/gossip, and B-tree vs LSM storage engines.
+  CAP/PACELC and clocks stay cross-linked to the always-loaded `resilience-engineering` rule —
+  never duplicated. 6 attributed `htn-` digests in `references/`.
+- **[`docs/system-design-threads.md`](docs/system-design-threads.md)** — the 46-row coverage map:
+  every thread's fetch status, digest location, and kit outcome (including the 3 deliberately
+  not absorbed).
+- **Six capped SKILL.md extensions** (each independently gap-verified against the live kit):
+  - `gcs-file-storage-patterns` — *Direct-to-storage uploads (presigned PUT)*: seven independent
+    designs converge on client → presigned PUT → bucket with async post-processing; the skill's
+    existing examples routed upload bytes through the API tier.
+  - `redis-caching-patterns` — *Beyond-cache Redis*: purpose-fit native structures, MULTI/EXEC +
+    WATCH + Lua atomicity, eviction-policy selection (LRU vs LFU), RDB/AOF persistence trade-offs.
+  - `kafka-config-driven` — *Event-backbone design*: partition-key choice as the ordering
+    contract, handler-level DLQ + replay (building on the skill's pinned no-consumer-layer-DLQ
+    convention), saga orchestration with compensating actions.
+  - `python-dao-and-database` — *Concurrency control*: optimistic locking (version column),
+    MVCC as the mental model, deadlock discipline (lock ordering, timeouts, retry-the-victim);
+    cross-references the existing isolation-level reference instead of duplicating it.
+  - `api-and-interface-design` — *HTTP caching & payload efficiency*: Cache-Control vocabulary,
+    ETag/If-None-Match conditional requests, Retry-After, compression negotiation, sparse
+    fieldsets (previously zero hits for any of these across the kit).
+  - `auth-and-rbac` — *Choosing an authorization model & OAuth 2.0 delegation*: RBAC vs ABAC vs
+    ACL as a decision with migration signals, and authorization-code delegation (PKCE, what to
+    store) distinct from the skill's existing in-app JWT/session mechanics.
+- **13 further digests** filed in the `references/` of already-covering skills with zero SKILL.md
+  changes (`design-patterns-and-conventions` ×3, `auth-and-rbac` ×2, `api-and-interface-design`
+  ×2, plus `performance-optimization`, `observability-and-logging`, `async-python-patterns`, and
+  the extension digests above), preserving the covered-vs-extended distinction.
+
+### Changed
+- `rules/design-patterns.md` gains a two-line pointer to the two new skills (the only
+  always-loaded touch; reaches `technical-architect`, which mandatory-reads that rule).
+- Count anchors: **107 skills (57 core + 50 stack-collection)** in `README.md`,
+  `docs/stack-skills/README.md` (+2 catalog rows), and `docs/skill-audit.md`.
+- `docs/skill-audit.md` also corrects **pre-existing count drift** (it still said
+  104 = 56 + 48 while the tree held 105 = 57 + 48 since 0.58.x) — deliberate drift correction,
+  with the dated 2026-07 lane-mapping measurement left intact as a historical record.
+
+### Not adopted (deliberately)
+- **AWS SAA-C03 exam thread** — cloud-certification prep; no SDLC substance for a stack-agnostic
+  configuration kit. Coverage-map row only.
+- **Claude CCA-F exam thread** — exam prep; the platform facts it teaches (model tiers, batch
+  API, context discipline) are already covered by `anthropic-vertex-integration`,
+  `model-tiers`, and `context-engineering`. Coverage-map row only.
+- **Writing-advice thread** — personal craft guidance, out of kit scope. Coverage-map row only.
+- **A third new skill** (e.g. "search & discovery" or "marketplace patterns") — the remaining
+  absent patterns (geo/proximity, layered search funnels, escrow payouts, double-blind reviews)
+  are carried by the composite-app digests and pattern map; a skill each would dilute
+  auto-selection for content that arises only inside those composites.
+- **57 of the 63 proposed extensions** — killed by the global refute to honor the ≤6 cap; every
+  kill either deduplicated a composite-app repeat (absorbed once into the new skills), landed as
+  digest-only references (CORS mechanics, State-pattern LLD, GIL threads-vs-processes,
+  notification delivery-log, engine-sympathetic JavaScript, batch-API/temporal-anchoring), or
+  would have duplicated the always-loaded `resilience-engineering` rule (backpressure, CAP,
+  retries — already covered there).
+- **Raw thread captures** — never committed; the gitignored harvest scratch is deleted before
+  commit and digests carry a structural fidelity check instead of quotes.
+
 ## [0.66.0] — 2026-07-23
 
 **Memory-subsystem absorption pass from [basic-memory](https://github.com/basicmachines-co/basic-memory)

{claude_code_kit-0.66.0 → claude_code_kit-0.67.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-code-kit
-Version: 0.66.0
+Version: 0.67.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
@@ -146,7 +146,7 @@ claude-kit init --defaults      # non-interactive: React + Python/FastAPI + Post
 |------|--------------|
 | 🔁 **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 + **105** context-activated skills (57 core + 48 stack-collection), pulled into context on demand |
+| 📐 **Rules & skills** | **25** stack-agnostic core rules + **107** context-activated skills (57 core + 50 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, **24** ready MCP fragments (version-pinned), edit-preserving `upgrade`, and a root `AGENTS.md` at init so non-Claude agents share the same standards |
@@ -225,7 +225,7 @@ PostgreSQL project, individual scope:
 |---------|-------:|-------:|------:|
 | `lean` | 8 | 15 | 36 |
 | `standard` (default) | 26 | 43 | 36 |
-| `enterprise` | 31 | 105 | 36 |
+| `enterprise` | 31 | 107 | 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.
@@ -251,7 +251,7 @@ that matters most: **native gives you the agents; claude-kit gives you the gover
 | **[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, 105 skills, gates, and hooks — kept upgradeable with your edits preserved |
+| **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, 107 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

{claude_code_kit-0.66.0 → claude_code_kit-0.67.0}/README.md

@@ -113,7 +113,7 @@ claude-kit init --defaults      # non-interactive: React + Python/FastAPI + Post
 |------|--------------|
 | 🔁 **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 + **105** context-activated skills (57 core + 48 stack-collection), pulled into context on demand |
+| 📐 **Rules & skills** | **25** stack-agnostic core rules + **107** context-activated skills (57 core + 50 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, **24** ready MCP fragments (version-pinned), edit-preserving `upgrade`, and a root `AGENTS.md` at init so non-Claude agents share the same standards |
@@ -192,7 +192,7 @@ PostgreSQL project, individual scope:
 |---------|-------:|-------:|------:|
 | `lean` | 8 | 15 | 36 |
 | `standard` (default) | 26 | 43 | 36 |
-| `enterprise` | 31 | 105 | 36 |
+| `enterprise` | 31 | 107 | 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.
@@ -218,7 +218,7 @@ that matters most: **native gives you the agents; claude-kit gives you the gover
 | **[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, 105 skills, gates, and hooks — kept upgradeable with your edits preserved |
+| **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, 107 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

{claude_code_kit-0.66.0 → claude_code_kit-0.67.0}/docs/influences.md

@@ -35,6 +35,7 @@ non-duplicative gaps**, minimally and catalog-wired.
 | **Curated engineering-writing sweep** (a Medium "senior-engineer patterns" prompt → the freely-readable canon: Google SRE Book · AWS Builders' Library · Google API Design Guide & Eng Practices · Martin Fowler · Brendan Gregg · Dan McKinley · Sandi Metz · Stripe/Google idempotency & LRO · Dean/Norvig latency numbers) | Design-time CAP/PACELC + static-stability fallback sizing; error budgets as a release throttle; order-of-magnitude latency table; off-CPU/Amdahl/USL scalability; innovation-token budgeting; the wrong-abstraction cost; Parallel Change (expand→migrate→contract); cursor vs offset pagination; cache-stampede (single-flight + XFetch); DTO/storage decoupling + Idempotency-Key + long-running-operation API shapes; consumer-driven contract testing; "if you can't understand it, that's the finding" | Prose extensions to `resilience-engineering` & `devops-observability` rules + 9 skills (`_references/performance-checklist`, `load-testing`, `library-review`, `over-engineering-review`, `deprecation-and-migration`, `api-pagination-filtering-sorting`, `redis-caching-patterns`, `api-and-interface-design`, `testing-conventions`, `code-review-and-quality`, `notifications-and-messaging`) — **0 new agents/skills/rules; component counts unchanged** | `0.64.0` |
 | **866-repo AI/Claude/MCP scan** (catalog-additive angle — after five null *prose* passes, targeting the one adoption path with zero always-loaded-context cost: an opt-in `catalog/mcp.yaml` entry) | The metrics/dashboards/alerts side of observability the catalog lacked (`sentry` covers errors only) — maps to the `observability-engineer` + `incident-responder` agents' documented jobs, mirroring the `sentry`/`chrome-devtools` precedent | The **`grafana` MCP fragment** (official [grafana/mcp-grafana](https://github.com/grafana/mcp-grafana), Apache-2.0, read-only via `--disable-write`, pinned, referenced-not-bundled) — **0 new agents/skills/rules; 1 new catalog entry** (deliberately skipped: Figma — no agent consumer; the maintained Go `github-mcp-server` — deferred to its own change; Notion/Cloudflare — no agent / vendor sprawl; code-intel servers — already covered by serena+semble+repowise) | `0.65.0` |
 | **[basic-memory](https://github.com/basicmachines-co/basic-memory)** (AGPL-3.0 — *ideas absorbed in our own words, zero code/prose copied*; 36 candidate disciplines → 8 survived a 118-agent verify/refute pass → 5 adopted) | A checkpoint is a **resume cursor**: repo/PR identity proven by commands (never conversation memory) and dead-ends recorded so the next session doesn't re-suggest them; memory entries as a **connected store**, not islands; shape conformance as **advisory, never capture-blocking**; promotion to shared config as a **deliberate, confirmed gesture** | The canonical learning shape (fixed the `rules/agent-memory.md` format drift; all four capture paths now agree) + optional reciprocal `## Related` links (union/repoint on consolidation); `git`/`pr` **identity anchors** in `pipeline-snapshot` + a `Repo State` CONTINUITY section + verify-identity-on-resume; the `Attempted & Ruled Out` CONTINUITY section; an advisory shape-check in `consolidate-learnings`; the Promote step now **proposes before writing** (HITL scope-expansion row) with provenance — **0 new agents/skills/rules/hooks** | `0.66.0` |
+| **[Technical-Engineering-Articles](https://github.com/harshit3011/Technical-Engineering-Articles)** (MIT list-repo indexing **46 public X threads by [@Harry_The_Nerd](https://x.com/Harry_The_Nerd)** — thread content © the author, *ideas absorbed in our own words, zero verbatim text*; 46/46 fetched → 614 candidate patterns through a 92-agent digest+verify pass with 3/3 fidelity spot-checks on every digest → global adversarial refute enforced the caps) | System-scale building blocks the kit never taught — rate-limiting algorithms, load balancing, fan-out, unique-ID generation, back-of-envelope estimation, microservice boundary criteria — and state-distribution mechanics (consistent hashing, quorum N/W/R, KV-store anatomy, storage engines); plus six confirmed gaps in existing skills, most notably that upload guidance routed bytes **through the API tier** while seven independent designs converge on presigned direct-to-storage | **2 new collection skills** (`system-design-patterns` · `distributed-systems-patterns`) + **6 capped SKILL.md extensions** (presigned uploads · beyond-cache Redis · event-backbone Kafka · DB concurrency control · HTTP caching & payload efficiency · authz models + OAuth delegation), 43 attributed `htn-` digests in owning skills' `references/`, and the 46-row [`docs/system-design-threads.md`](system-design-threads.md) coverage map (3 threads deliberately not absorbed) | `0.67.0` |
 
 > Each adoption is detailed in the [CHANGELOG](../CHANGELOG.md) — including, for every review, what we
 > deliberately **did not** add because the kit already covered it.

{claude_code_kit-0.66.0 → claude_code_kit-0.67.0}/docs/skill-audit.md

@@ -4,9 +4,9 @@
 
 This document analyzes claude-kit's skill inventory — classification, sizing, per-profile footprint, and overlap — to inform future configuration decisions. It proposes no changes to `catalog/profiles.yaml`.
 
-**Date:** 2026-07-03
+**Date:** 2026-07-03 (count anchors refreshed 2026-07-24 at 0.67.0)
 **Version audited:** 0.57.0
-**Total skills on disk:** 104 (56 core + 48 stack-collection)
+**Total skills on disk:** 107 (57 core + 50 stack-collection)
 
 ---
 
@@ -19,8 +19,8 @@ Skills are classified by the presence of a `README.md` file in their directory:
 
 This classification is exactly how `scripts/check_docs_consistency.py::_count_skills()` counts them. That function walks `skills/`, skips any entry that is not a directory or whose name starts with `_` (so the shared `_references/` support directory is not counted as a skill), and splits the rest on README presence. The expected split is pinned as anchors that CI checks against the docs:
 
-- 56 core skills (no `README.md`).
-- 48 stack-collection skills (with `README.md`).
+- 57 core skills (no `README.md`).
+- 50 stack-collection skills (with `README.md`).
 
 Per-profile counts were measured on a `react + fastapi + postgres` project initialized with `--scope individual` for each profile (lean, standard, enterprise), by counting the files actually written under `.claude/`.
 
@@ -32,11 +32,11 @@ Token estimates are approximate, calculated as `total_bytes / 4`.
 
 | Category | Count | Description |
 |----------|-------|-------------|
-| **Core skills** | 56 | Stack-agnostic capabilities (e.g., `sdlc`, `code-review-and-quality`, `test-driven-development`, `planning-and-task-breakdown`, `debugging-and-error-recovery`) |
-| **Stack-collection skills** | 48 | Stack or domain-specific skills (e.g., `fastapi-service-patterns`, `react-hook-form-zod-patterns`, `alembic-migrations`, `kubectl-operations`) |
-| **Total** | **104** | Full on-disk inventory (excludes the shared `_references/` support directory) |
+| **Core skills** | 57 | Stack-agnostic capabilities (e.g., `sdlc`, `code-review-and-quality`, `test-driven-development`, `planning-and-task-breakdown`, `debugging-and-error-recovery`) |
+| **Stack-collection skills** | 50 | Stack or domain-specific skills (e.g., `fastapi-service-patterns`, `react-hook-form-zod-patterns`, `system-design-patterns`, `kubectl-operations`) |
+| **Total** | **107** | Full on-disk inventory (excludes the shared `_references/` support directory) |
 
-The 48 collection skills are stack/domain add-ons. Note that `postgres-specialist`, `migration-specialist`, and `db-performance-reviewer` are DB-overlay **agents** (under `templates/stacks/db/postgres/agents/`), not skills — they are counted in the agent footprint below, not here.
+The 50 collection skills are stack/domain add-ons. Note that `postgres-specialist`, `migration-specialist`, and `db-performance-reviewer` are DB-overlay **agents** (under `templates/stacks/db/postgres/agents/`), not skills — they are counted in the agent footprint below, not here.
 
 ---
 
@@ -48,11 +48,11 @@ Measured on a `react + fastapi + postgres` project with `--scope individual`:
 |---------|--------|--------|-------|-------------------------------|
 | **lean** | 8 | 15 | 36 | ~46K |
 | **standard** | 26 | 42 | 36 | ~121K |
-| **enterprise** | 31 | 104 | 36 | ~895K |
+| **enterprise** | 31 | 107 | 36 | ~895K+ |
 
 **Notes:**
 
-- Skill counts are skill *directories* (those containing a `SKILL.md`) — matching `_count_skills()` and the README's "What loads into your context" table. A raw `ls .claude/skills | wc -l` reads one higher (16 / 43 / 105) because each install also copies the shared `_references/` support directory, which is **not** a skill; `_count_skills()` deliberately excludes it. This is a counting convention, not duplicated content.
+- Skill counts are skill *directories* (those containing a `SKILL.md`) — matching `_count_skills()` and the README's "What loads into your context" table. A raw `ls .claude/skills | wc -l` reads one higher (16 / 43 / 108) because each install also copies the shared `_references/` support directory, which is **not** a skill; `_count_skills()` deliberately excludes it. This is a counting convention, not duplicated content.
 - Since the stack-true reclassification (0.58.1), the six frontend-specific skills (`frontend-ui-engineering`, `component-design`, `ui-ux-design`, `unit-test`, `api-integration`, `manual-test`) ride the React entry in `catalog/stacks.yaml` rather than the standard profile — a backend-only (`frontend: none`) standard install is six skills lighter. Lean gained one on the default stack (the react union now includes `manual-test` and `api-integration`; `api-integration` left the fastapi entry): 14 → 15.
 - Agent counts exceed the raw profile agent list because the PostgreSQL DB overlay unions in 3 additional agents (`postgres-specialist`, `migration-specialist`, `db-performance-reviewer`).
 - Rules are profile-independent: 25 core rules + 11 selected stack-overlay rules = 36 for all three profiles.
@@ -62,12 +62,12 @@ Measured on a `react + fastapi + postgres` project with `--scope individual`:
 
 ## Finding: Enterprise Over-Install of Stack-Collection Skills
 
-The enterprise profile uses `skills: all` in `catalog/profiles.yaml`, which installs **every skill in the payload** — including all 48 stack-collection skills, regardless of whether the project selected those stacks.
+The enterprise profile uses `skills: all` in `catalog/profiles.yaml`, which installs **every skill in the payload** — including all 50 stack-collection skills, regardless of whether the project selected those stacks.
 
 **Impact:**
 
 - A `react + fastapi + postgres` project receives skills for stacks and domains it did not select (e.g., MongoDB, Kafka, Temporal, Kubernetes, GCP, and the planned Vue/Svelte/Django/Node collections' analogues) — roughly **895K tokens on disk** vs. standard's **~121K**.
-- That is about **7× the on-disk skill footprint** of the standard profile. By skill count the ratio is smaller (104 vs 42, ~2.5×); the 7× gap is driven by size — collection skills carry a `README.md` plus more content per directory. Most of these files are irrelevant to the chosen stack.
+- That is about **7× the on-disk skill footprint** of the standard profile. By skill count the ratio is smaller (107 vs 42, ~2.5×); the 7× gap is driven by size — collection skills carry a `README.md` plus more content per directory. Most of these files are irrelevant to the chosen stack.
 
 **Important nuance (do not overstate):** Skills are **on-demand** (activated by context/user request), so this is **disk/selection bloat**, not always-resident context bloat. The harness does not load all skill files into every prompt. What it does do is:
 
@@ -133,13 +133,15 @@ Potential approaches — all MUST stay `catalog/*.yaml` / config changes with NO
 
 **Next steps (if pursued):**
 
-1. Measure the actual selection-time overhead of a 104-skill vs 42-skill install (do not assume it).
+1. Measure the actual selection-time overhead of a 107-skill vs 42-skill install (do not assume it).
 2. Prototype a `stack-relevant` mapping as pure data in `stacks.yaml`, resolved by the existing lookup.
 3. Add the variant to `catalog/profiles.yaml` and measure the resulting footprint against the numbers above.
 
 ### Measured: the stack→skill mapping (2026-07) — and why `stack-relevant` is deferred
 
-The mapping step above was carried out. Classifying all 48 collection skills against the lanes a
+The mapping step above was carried out when the collection held 48 skills (the two
+system-design skills added at 0.67.0 are likewise lane-orthogonal and would not change the
+decision below). Classifying all 48 collection skills against the lanes a
 user can actually select today (frontend `react|none` · backend `python/fastapi | go/net-http |
 none` · database `postgres | mongodb | none`; Node/Express, Django, Vue, Svelte are `status:
 planned`):
@@ -174,7 +176,7 @@ for whoever picks this up.
 
 ## Conclusion
 
-- **Total skill inventory:** 104 (56 core + 48 stack-collection).
+- **Total skill inventory:** 107 (57 core + 50 stack-collection).
 - **Enterprise over-install:** ~7× the on-disk skill footprint (~895K vs ~121K tokens) because `skills: all` installs cross-stack collection skills.
 - **Risk level:** low for resident context (on-demand activation), but disk/selection bloat is measurable.
 - **Action taken:** document the trade-off. Optionally evaluate a stack-relevant filter as a config-level change (no `resolve()` branching).

{claude_code_kit-0.66.0 → claude_code_kit-0.67.0}/docs/stack-skills/README.md

@@ -1,6 +1,6 @@
 # Production Engineering Skills Collection
 
-These forty-eight Claude Code skills encode production-proven engineering conventions derived from real-world Python/FastAPI, Node/Express, and React services. Each skill was extracted from analyzing patterns across multiple production backend and frontend services, capturing canonical patterns for FastAPI microservices, async Python, Kafka/Temporal integration, multi-tenancy, database access, layered configuration, Redis caching, GCS file handling, LLM integration (Vertex AI / Langfuse), Node/Express services, React frontends (state, data-fetching, forms, design systems, testing), observability (including Grafana dashboards & unified alerting), authentication, containerization (with granular Dockerfile/compose deep-dives), testing, data pipelines, security scanning (OWASP ZAP VAPT/DAST and autonomous AI pentesting), security architecture (edge-to-service signed-identity trust boundary, Kubernetes workload hardening), scheduled & recurring jobs (Kubernetes CronJob + Temporal Schedule), kubectl day-2 operations, and modernization strategies. Use them to align new projects with established patterns, audit existing services, or onboard engineers to modern Python, Node, and React development practices.
+These fifty Claude Code skills encode production-proven engineering conventions derived from real-world Python/FastAPI, Node/Express, and React services, plus system-design pattern references synthesized from public engineering write-ups. Each skill was extracted from analyzing patterns across multiple production backend and frontend services, capturing canonical patterns for FastAPI microservices, async Python, Kafka/Temporal integration, multi-tenancy, database access, layered configuration, Redis caching, GCS file handling, LLM integration (Vertex AI / Langfuse), Node/Express services, React frontends (state, data-fetching, forms, design systems, testing), observability (including Grafana dashboards & unified alerting), authentication, containerization (with granular Dockerfile/compose deep-dives), testing, data pipelines, security scanning (OWASP ZAP VAPT/DAST and autonomous AI pentesting), security architecture (edge-to-service signed-identity trust boundary, Kubernetes workload hardening), scheduled & recurring jobs (Kubernetes CronJob + Temporal Schedule), kubectl day-2 operations, modernization strategies, and system/distributed-systems design building blocks (rate limiting, fan-out, consistent hashing, replication). Use them to align new projects with established patterns, audit existing services, or onboard engineers to modern Python, Node, and React development practices.
 
 > **Where these live in this repo:** the skill folders are under [`skills/`](../../skills/) (auto-discovered by the claude-kit plugin). The links below point there.
 
@@ -18,6 +18,8 @@ These forty-eight Claude Code skills encode production-proven engineering conven
 | **temporal-developer** | Temporal *fundamentals* (language-agnostic; complement to temporal-config-driven) — durable execution, why workflows must be deterministic (history replay), signals/queries/updates, safe versioning of running workflows (patching/worker versioning), testing (time-skipping/replay), gotchas, the `temporal` CLI dev loop, + Python/Go/TS starters; re-derived from the MIT temporalio/skill-temporal-developer | [SKILL.md](../../skills/temporal-developer/SKILL.md) |
 | **frontend-repo-architecture** | React + Vite + TypeScript frontend structure — three organizational models (module-scoped, feature-sliced, GraphQL-based), API layer strategies, hand-written types, state management | [SKILL.md](../../skills/frontend-repo-architecture/SKILL.md) |
 | **design-patterns-and-conventions** | Design conventions across repos — naming (classes/files/routes), error handling (ResponseData envelope), config hierarchy, logging structured-log patterns, code organization | [SKILL.md](../../skills/design-patterns-and-conventions/SKILL.md) |
+| **system-design-patterns** | System-scale building blocks — back-of-envelope estimation, rate-limiting algorithms, load balancing, CDN/edge, caching hierarchy, URL shortening & unique ID generation, notification/news-feed fan-out, autocomplete, chat/real-time, microservice boundaries, and a composite-application pattern map; synthesized (own words, attributed) from 24 public system-design threads by @Harry_The_Nerd | [SKILL.md](../../skills/system-design-patterns/SKILL.md) |
+| **distributed-systems-patterns** | Distributing state — consistent hashing, partitioning/sharding, replication & quorum (N/W/R), distributed KV-store anatomy (hinted handoff, anti-entropy, vector clocks), distributed cache design, failure detection/gossip, B-tree vs LSM storage engines; CAP/clocks stay cross-linked to the always-loaded `resilience-engineering` rule | [SKILL.md](../../skills/distributed-systems-patterns/SKILL.md) |
 | **multi-tenancy-patterns** | Multi-tenant isolation strategies — tenant resolution (header/JWT/session), Postgres RLS, multi-pool databases, lazy connectors, data-layer org_id tenancy | [SKILL.md](../../skills/multi-tenancy-patterns/SKILL.md) |
 | **observability-and-logging** | Structured logging, OpenTelemetry tracing, Sentry error tracking, Prometheus metrics, NewRelic, request/correlation IDs, /health and /readiness endpoints | [SKILL.md](../../skills/observability-and-logging/SKILL.md) |
 | **otel-tracing** | Vendor-neutral distributed tracing *pipeline + backend* (language-agnostic; complement to observability-and-logging) — the OTel trace data model, the standard OTLP env-var contract, the OTLP→Collector→Tempo path, head-plus-tail sampling (loadbalancing exporter, `tail_sampling`), W3C context propagation across async/queue boundaries, the Grafana Tempo backend (distributor/ingester/querier/compactor, retention/compaction, OTLP ports/paths), TraceQL, the metrics-generator (span metrics + service graphs), and trace↔logs↔metrics correlation (exemplars); re-derived from public OpenTelemetry, W3C Trace Context, and Grafana Tempo docs | [SKILL.md](../../skills/otel-tracing/SKILL.md) |

claude_code_kit-0.67.0/docs/system-design-threads.md

@@ -0,0 +1,61 @@
+# System-design thread coverage map
+
+Source: [Technical-Engineering-Articles](https://github.com/harshit3011/Technical-Engineering-Articles)
+(MIT list-repo) — 46 public X long-form articles by Harshit Khosla
+([@Harry_The_Nerd](https://x.com/Harry_The_Nerd)). All 46 fetched 2026-07-23/24 via logged-out
+browser render. Article content remains © the author; every shipped digest is an own-words summary
+with attribution and no verbatim text (see `docs/influences.md`). Digests are named
+`htn-<slug>.md` and live in the owning skill's `references/` directory.
+
+Absorbed in 0.67.0 as: two new collection skills (`system-design-patterns`,
+`distributed-systems-patterns`), six SKILL.md extensions (capped deliberately), and 43 shipped
+digests. Three threads were deliberately not absorbed (rows marked below).
+
+| # | Thread | Category | Fetched | Digest | Kit outcome |
+|---|--------|----------|---------|--------|-------------|
+| 1 | [Design Bit.ly and Pastebin](https://x.com/Harry_The_Nerd/status/2044672371546877964) | HLD | yes | `skills/system-design-patterns/references/htn-design-bit-ly-and-pastebin.md` | new-skill section / composite row in `system-design-patterns` |
+| 2 | [Design A Notification System](https://x.com/Harry_The_Nerd/status/2044839667267494292) | HLD | yes | `skills/system-design-patterns/references/htn-design-a-notification-system.md` | new-skill section / composite row in `system-design-patterns` |
+| 3 | [Design A Rate Limiter](https://x.com/Harry_The_Nerd/status/2045533839649624096) | HLD | yes | `skills/system-design-patterns/references/htn-design-a-rate-limiter.md` | new-skill section / composite row in `system-design-patterns` |
+| 4 | [Design Autocomplete For Search Engines](https://x.com/Harry_The_Nerd/status/2045906641967833171) | HLD | yes | `skills/system-design-patterns/references/htn-design-autocomplete-for-search-engines.md` | new-skill section / composite row in `system-design-patterns` |
+| 5 | [Design a Load Balancer](https://x.com/Harry_The_Nerd/status/2046465659551576395) | HLD | yes | `skills/system-design-patterns/references/htn-design-a-load-balancer.md` | new-skill section / composite row in `system-design-patterns` |
+| 6 | [Design a Content Delivery Network](https://x.com/Harry_The_Nerd/status/2046578404758295032) | HLD | yes | `skills/system-design-patterns/references/htn-design-a-content-delivery-network.md` | new-skill section / composite row in `system-design-patterns` |
+| 7 | [Design a Distributed Key-Value store](https://x.com/Harry_The_Nerd/status/2047329176982827353) | HLD | yes | `skills/distributed-systems-patterns/references/htn-design-a-distributed-key-value-store.md` | new-skill section in `distributed-systems-patterns` |
+| 8 | [Design A Distributed Cache](https://x.com/Harry_The_Nerd/status/2048052028174463278) | HLD | yes | `skills/distributed-systems-patterns/references/htn-design-a-distributed-cache.md` | new-skill section in `distributed-systems-patterns` |
+| 9 | [Design an Authentication System](https://x.com/Harry_The_Nerd/status/2048758919770816850) | HLD | yes | `skills/auth-and-rbac/references/htn-design-an-authentication-system.md` | feeds `auth-and-rbac` extension (authz models & OAuth) |
+| 10 | [HTTP & Routing](https://x.com/Harry_The_Nerd/status/2053366145995178087) | Backend Engineering | yes | `skills/api-and-interface-design/references/htn-http-routing.md` | feeds `api-and-interface-design` extension (HTTP caching) |
+| 11 | [Serialization, Deserialization, Authentication and Authorization](https://x.com/Harry_The_Nerd/status/2053487726033559704) | Backend Engineering | yes | `skills/auth-and-rbac/references/htn-serialization-deserialization-authentication-and-authorizati.md` | feeds `auth-and-rbac` extension (authz models & OAuth) |
+| 12 | [Validation, Transformation, Controllers, Middlewares](https://x.com/Harry_The_Nerd/status/2053882356071911853) | Backend Engineering | yes | `skills/design-patterns-and-conventions/references/htn-validation-transformation-controllers-middlewares.md` | digest only (already covered by the owning skill) |
+| 13 | [Rest API Design](https://x.com/Harry_The_Nerd/status/2054882198604628305) | Backend Engineering | yes | `skills/api-and-interface-design/references/htn-rest-api-design.md` | feeds `api-and-interface-design` extension (HTTP caching) |
+| 14 | [LLD Concepts](https://x.com/Harry_The_Nerd/status/2055635966568620167) | LLD | yes | `skills/design-patterns-and-conventions/references/htn-lld-concepts.md` | digest only (already covered by the owning skill) |
+| 15 | [Design a basic Music System](https://x.com/Harry_The_Nerd/status/2056620076246479055) | LLD | yes | `skills/system-design-patterns/references/htn-design-a-basic-music-system.md` | new-skill section / composite row in `system-design-patterns` |
+| 16 | [Tricky HLD Patterns for interviews](https://x.com/Harry_The_Nerd/status/2056739488114856226) | HLD | yes | `skills/distributed-systems-patterns/references/htn-tricky-hld-patterns-for-interviews.md` | new-skill section in `distributed-systems-patterns` |
+| 17 | [Design Consistent Hashing](https://x.com/Harry_The_Nerd/status/2057098732328648808) | HLD | yes | `skills/distributed-systems-patterns/references/htn-design-consistent-hashing.md` | new-skill section in `distributed-systems-patterns` |
+| 18 | [Design A Unique ID Generator in Distributed Systems](https://x.com/Harry_The_Nerd/status/2057461354114728238) | HLD | yes | `skills/system-design-patterns/references/htn-design-a-unique-id-generator-in-distributed-systems.md` | new-skill section / composite row in `system-design-patterns` |
+| 19 | [Design a Parking Lot](https://x.com/Harry_The_Nerd/status/2057821348450402614) | LLD | yes | `skills/system-design-patterns/references/htn-design-a-parking-lot.md` | new-skill section / composite row in `system-design-patterns` |
+| 20 | [Design A News-Feed System](https://x.com/Harry_The_Nerd/status/2058553384735842654) | HLD | yes | `skills/system-design-patterns/references/htn-design-a-news-feed-system.md` | new-skill section (news-feed fan-out) + feeds `kafka-config-driven` (partition keys) |
+| 21 | [Design Youtube](https://x.com/Harry_The_Nerd/status/2060001018134553006) | LLD | yes | `skills/system-design-patterns/references/htn-design-youtube-lld.md` | new-skill section / composite row in `system-design-patterns` |
+| 22 | [Design a Vending Machine](https://x.com/Harry_The_Nerd/status/2060348729929175403) | LLD | yes | `skills/design-patterns-and-conventions/references/htn-design-a-vending-machine.md` | digest only (already covered by the owning skill) |
+| 23 | [A Complete Guide to Redis](https://x.com/Harry_The_Nerd/status/2061076806552392055) | Engineering Articles | yes | `skills/redis-caching-patterns/references/htn-a-complete-guide-to-redis.md` | extends `redis-caching-patterns` (beyond-cache Redis) |
+| 24 | [Design A Chat System](https://x.com/Harry_The_Nerd/status/2061445321910284589) | HLD | yes | `skills/system-design-patterns/references/htn-design-a-chat-system.md` | new-skill section / composite row in `system-design-patterns` |
+| 25 | [Apache Kafka: Crash Course](https://x.com/Harry_The_Nerd/status/2062165677033820383) | Engineering Articles | yes | `skills/kafka-config-driven/references/htn-apache-kafka-crash-course.md` | extends `kafka-config-driven` (event-backbone design) |
+| 26 | [Design Youtube](https://x.com/Harry_The_Nerd/status/2062909779576791167) | HLD | yes | `skills/system-design-patterns/references/htn-design-youtube-hld.md` | composite row + feeds `gcs-file-storage-patterns` extension (presigned uploads) |
+| 27 | [Design Spotify](https://x.com/Harry_The_Nerd/status/2063952850531897396) | HLD | yes | `skills/system-design-patterns/references/htn-design-spotify.md` | new-skill section / composite row in `system-design-patterns` |
+| 28 | [Design Instagram](https://x.com/Harry_The_Nerd/status/2065074213665579192) | HLD | yes | `skills/system-design-patterns/references/htn-design-instagram.md` | composite row + feeds `gcs-file-storage-patterns` extension (presigned uploads) |
+| 29 | [Design Tinder](https://x.com/Harry_The_Nerd/status/2065790968448909572) | HLD | yes | `skills/system-design-patterns/references/htn-design-tinder.md` | composite row + feeds `gcs-file-storage-patterns` extension (presigned uploads) |
+| 30 | [AWS Certified Solutions Architect - Associate SAA-C03 Exam Tricks](https://x.com/Harry_The_Nerd/status/2066793644783513735) | Engineering Articles | yes | — | not absorbed — cloud-exam prep, no SDLC substance for a stack-agnostic kit |
+| 31 | [Design Reddit](https://x.com/Harry_The_Nerd/status/2067615247259811850) | HLD | yes | `skills/system-design-patterns/references/htn-design-reddit.md` | composite row + feeds `gcs-file-storage-patterns` extension (presigned uploads) |
+| 32 | [Design Twitter](https://x.com/Harry_The_Nerd/status/2068309801638195531) | HLD | yes | `skills/system-design-patterns/references/htn-design-twitter.md` | composite row + feeds `gcs-file-storage-patterns` extension (presigned uploads) |
+| 33 | [A Complete Guide For Claude Certified Architect Foundations (CCA-F) Exam](https://x.com/Harry_The_Nerd/status/2069050669487809004) | Engineering Articles | yes | — | not absorbed — exam prep (per plan); platform facts already covered by `anthropic-vertex-integration`/`context-engineering` |
+| 34 | [Netflix Recommendation System - Machine Learning System Design](https://x.com/Harry_The_Nerd/status/2069785739810705773) | Engineering Articles | yes | `skills/system-design-patterns/references/htn-netflix-recommendation-system-machine-learning-system-design.md` | new-skill section / composite row in `system-design-patterns` |
+| 35 | [Design Amazon](https://x.com/Harry_The_Nerd/status/2070543086258979132) | HLD | yes | `skills/system-design-patterns/references/htn-design-amazon.md` | composite row + feeds `kafka-config-driven` extension (sagas) |
+| 36 | [Design Netflix](https://x.com/Harry_The_Nerd/status/2071256571028648283) | HLD | yes | `skills/system-design-patterns/references/htn-design-netflix.md` | new-skill section / composite row in `system-design-patterns` |
+| 37 | [How To Get Started With Writing- Technical and Creative](https://x.com/Harry_The_Nerd/status/2072219094728978564) | Engineering Articles | yes | — | not absorbed — personal writing advice, out of kit scope |
+| 38 | [Databases in Depth Part-1](https://x.com/Harry_The_Nerd/status/2073772366094602241) | Backend Engineering | yes | `skills/distributed-systems-patterns/references/htn-databases-in-depth-part-1.md` | new-skill section in `distributed-systems-patterns` |
+| 39 | [How JavaScript Executes The Code - Behind The Scenes](https://x.com/Harry_The_Nerd/status/2075158256826335454) | Engineering Articles | yes | `skills/performance-optimization/references/htn-how-javascript-executes-the-code-behind-the-scenes.md` | digest only (already covered by the owning skill) |
+| 40 | [Databases in Depth Part-2](https://x.com/Harry_The_Nerd/status/2075942037732667812) | Backend Engineering | yes | `skills/python-dao-and-database/references/htn-databases-in-depth-part-2.md` | extends `python-dao-and-database` (concurrency control) |
+| 41 | [Databases in Depth Part-3](https://x.com/Harry_The_Nerd/status/2076649413435687097) | Backend Engineering | yes | `skills/distributed-systems-patterns/references/htn-databases-in-depth-part-3.md` | new-skill section in `distributed-systems-patterns` |
+| 42 | [Caching, Task Queues, Error Handling, Logging, Monitoring](https://x.com/Harry_The_Nerd/status/2077400118647750968) | Backend Engineering | yes | `skills/observability-and-logging/references/htn-caching-task-queues-error-handling-logging-monitoring.md` | digest only (already covered by the owning skill) |
+| 43 | [Security, Scaling & Performance, Concurrency & Parallelism](https://x.com/Harry_The_Nerd/status/2077722979882963122) | Backend Engineering | yes | `skills/system-design-patterns/references/htn-security-scaling-performance-concurrency-parallelism.md` | feeds `python-dao-and-database` + `api-and-interface-design` extensions |
+| 44 | [Python's Inner Working - Behind The Scenes](https://x.com/Harry_The_Nerd/status/2078116519029129646) | Engineering Articles | yes | `skills/async-python-patterns/references/htn-python-s-inner-working-behind-the-scenes.md` | digest only (already covered by the owning skill) |
+| 45 | [Design Airbnb](https://x.com/Harry_The_Nerd/status/2079561027788611975) | HLD | yes | `skills/system-design-patterns/references/htn-design-airbnb.md` | composite row + feeds `gcs-file-storage-patterns` + `kafka-config-driven` (saga) extensions |
+| 46 | [Mental Model for Microservices](http://x.com/Harry_The_Nerd/status/2080261902593065465) | Microservices | yes | `skills/system-design-patterns/references/htn-mental-model-for-microservices.md` | new-skill section / composite row in `system-design-patterns` |

{claude_code_kit-0.66.0 → claude_code_kit-0.67.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "claude-code-kit"
-version = "0.66.0"
+version = "0.67.0"
 description = "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."
 readme = "README.md"
 requires-python = ">=3.9"

{claude_code_kit-0.66.0 → claude_code_kit-0.67.0}/rules/design-patterns.md

@@ -420,3 +420,7 @@ export default api;
 | Constrained string values | Enum (backend) or union type (frontend) |
 | Multiple implementations | Strategy (interface/protocol) |
 | Cross-cutting render concern | Error Boundary |
+
+For system-scale design decisions — rate limiting, load balancing, fan-out, ID generation, service
+boundaries — see the `system-design-patterns` skill; for distributing state — consistent hashing,
+sharding, replication/quorum — see `distributed-systems-patterns`.

{claude_code_kit-0.66.0 → claude_code_kit-0.67.0}/skills/api-and-interface-design/SKILL.md

@@ -263,6 +263,61 @@ time out.
 > Per the Google API Design Guide's Long-Running Operations pattern (cloud.google.com/apis/design).
 > Stack-agnostic.
 
+### HTTP Caching & Payload Efficiency
+
+Every response declares a caching policy whether you write one or not — with no `Cache-Control`
+header, browsers and CDNs fall back to heuristics and *guess* how long your data stays valid.
+Choose the policy per endpoint, deliberately, as part of the contract:
+
+```
+Cache-Control: public, max-age=31536000   → shared reference data; CDNs may cache it
+Cache-Control: private, max-age=60        → per-user data; browser may cache, shared caches must not
+Cache-Control: no-store                   → sensitive payloads (auth, payment, PII) — never cached
+Cache-Control: max-age=30, stale-while-revalidate=300
+                                          → serve the stale copy instantly, refresh in the background
+```
+
+Default: `no-store` for anything authenticated or per-user until you decide otherwise; an explicit
+`max-age` for anything shareable. And if a body varies on a negotiated request header (encoding,
+language), list that header in **`Vary`** — omitting it is how a shared cache hands one client's
+compressed variant to a client that can't decode it.
+
+**Conditional requests skip the re-transfer.** Fingerprint each response with an **`ETag`**; the
+client echoes it back and an unchanged resource costs a tiny `304` instead of a full body
+(`Last-Modified` / `If-Modified-Since` is the coarser time-based equivalent):
+
+```
+GET /api/tasks/123
+If-None-Match: "a1b2c3"
+→ 304 Not Modified            // no body — the client's cached copy is still valid
+```
+
+The same fingerprint doubles as an **optimistic-concurrency token** on writes — require `If-Match`
+and reject a stale write with `412` instead of silently letting the last writer win:
+
+```
+PATCH /api/tasks/123
+If-Match: "a1b2c3"
+{ "title": "Updated title" }
+→ 412 Precondition Failed     // someone else changed it since the client read it
+```
+
+**`Retry-After` completes the rate-limit contract.** A bare `429` or `503` invites blind client
+retry loops; pairing it with `Retry-After: 30` turns them into scheduled backoff. If an endpoint
+can return `429`, it should say when to come back.
+
+**Payload size is a contract too.** Three bounds, cheapest first:
+
+- **Compression** — honor `Accept-Encoding` and compress JSON bodies (gzip works everywhere,
+  Brotli compresses further over HTTPS); large text payloads routinely shrink ~5–10×, nearly free.
+- **Sparse fieldsets** — give over-fetch-prone list endpoints a field-selection param
+  (`?fields=id,title,status`) so list views stop paying for detail-view payloads.
+- **Pagination caps** — the first payload bound of all: no list endpoint returns unbounded rows.
+  Query-param conventions live in `api-pagination-filtering-sorting`.
+
+> Per RFC 9110/9111 (HTTP semantics, caching, conditional requests). Stack-agnostic — these are
+> wire-level contracts that browsers, CDNs, and gateways enforce identically for any backend.
+
 ## Type-Safe Interface Patterns
 
 ### Use Discriminated Unions for Variants
@@ -352,3 +407,7 @@ After designing an API:
 - [ ] New fields are additive and optional (backward compatible)
 - [ ] Naming follows consistent conventions across all endpoints
 - [ ] API documentation or types are committed alongside the implementation
+
+## References
+
+- [htn-http-routing.md](references/htn-http-routing.md) · [htn-rest-api-design.md](references/htn-rest-api-design.md) — own-words digests of the HTTP/routing and REST API design source articles

claude_code_kit-0.67.0/skills/api-and-interface-design/references/htn-http-routing.md

@@ -0,0 +1,93 @@
+# Digest: HTTP & Routing
+
+- **Source:** https://x.com/Harry_The_Nerd/status/2053366145995178087
+- **Author:** Harshit Khosla (@Harry_The_Nerd)
+- **Category:** Backend Engineering (article #1 of the author's backend series)
+- **Fetched:** 2026-07-23/24 via logged-out browser render
+- **License note:** Content (c) the author; this digest is an own-words summary for internal engineering reference — no verbatim text.
+
+## Patterns
+
+### Three-part HTTP response anatomy
+Every response the server returns is built from the same three pieces: a status line (protocol version + numeric code + reason phrase), a header block of metadata that tells the client how to interpret what follows, and an optional body carrying the payload (JSON, HTML, binary, or nothing). Use this decomposition when debugging: the status line answers "did it work?", the headers answer "how should I treat it?", and only then does the body matter. Trade-off awareness: a body-less response is legitimate (e.g., 304), so client code must not assume content is always present.
+
+### Status-code families as a triage system
+Codes are bucketed by their first digit — 1xx informational, 2xx success, 3xx redirection, 4xx caller error, 5xx server fault — so the family alone tells you which side of the wire to blame before reading anything else. The article singles out the codes an engineer should reach for deliberately: 200 (success with data), 201 (resource created), 301 (permanent move; browsers cache it, so it is hard to undo), 304 (client's cached copy is still valid), 400 (malformed input), 401 (authentication missing) vs 403 (authenticated but not authorized — a distinction worth encoding correctly), 404 (no such resource), 429 (rate limited), 500 (unhandled server failure), 503 (server down or saturated). When to use: designing API error semantics and writing client retry logic (429/503 are retryable; 4xx generally are not).
+
+### Cache and security headers that do real work
+A small set of response headers carries most of the operational weight:
+- `Content-Type` declares the body format; without it the client cannot parse reliably.
+- `Cache-Control` sets caching policy — a max-age in seconds for shareable data, `no-store` for anything sensitive, `private` to keep copies out of shared caches/CDNs.
+- `Set-Cookie` with the three hardening flags: `HttpOnly` (script cannot read the cookie), `Secure` (transmitted only over HTTPS), `SameSite=Strict` (never attached to cross-site requests). Default to all three for session cookies.
+- `ETag` gives the response a content fingerprint; the client echoes it on the next request and an unchanged resource comes back as a tiny 304 instead of a full payload — a bandwidth optimization with almost no downside beyond server-side fingerprint computation.
+- `Retry-After` accompanies 429/503 to tell well-behaved clients exactly how long to back off, turning blind retry loops into scheduled ones.
+
+### CORS as a browser-enforced read gate
+When a page calls an origin other than its own (origin = scheme + host + port, so an api subdomain is already a different origin), the browser checks whether the responding server has allow-listed the calling origin via `Access-Control-Allow-Origin`. The threat it neutralizes: because browsers auto-attach cookies to requests toward the cookie's domain, a malicious page could fire an authenticated fetch at your bank and read the reply. CORS does not stop the request or the response — it stops the attacker's JavaScript from *reading* the response when the allow header is absent. Critical operational fact: this is purely a browser mechanism; curl, Postman, and server-side runtimes ignore it entirely, so CORS is user protection, never API access control. Don't mistake a permissive CORS policy for security, and don't expect CORS to defend against non-browser clients.
+
+### Simple vs. preflighted requests and preflight caching
+Browsers split cross-origin calls into two classes. Reads with plain headers (GET, HEAD, basic POST) fly immediately and only the response is policy-checked — safe, because an unreadable response does no harm. Mutating or exotic requests (PUT, DELETE, custom headers like Authorization) trigger an automatic OPTIONS probe first, announcing the intended method and headers; the real request goes out only if the server approves. Rationale: a destructive operation causes damage the moment it executes, so permission must be checked *before* firing, not after. Cost: preflights double round trips; mitigate with `Access-Control-Max-Age` (e.g., 86400 = a day) so the browser reuses one approval instead of re-asking per request.
+
+### Content negotiation across four axes
+Client and server agree on the shape of the payload before it is sent, along four dimensions, each an Accept-style request header answered by a Content-* response header:
+1. **Format** — `Accept` lists media types with q-weights (0–1 preference scores); the server picks the best supported match and confirms via `Content-Type`, or returns 406 if nothing overlaps.
+2. **Compression** — `Accept-Encoding` advertises supported codecs; the server answers with `Content-Encoding`. Rough numbers from the article: gzip cuts JSON around 77% and works everywhere; Brotli reaches roughly 82% but is HTTPS-only; Zstandard is newer and decodes faster at comparable ratios. Decompression is transparent to application code.
+3. **Language** — `Accept-Language` with q-weights lets one URL serve localized bodies, confirmed via `Content-Language`.
+4. **Charset** — effectively settled; always emit UTF-8.
+Use negotiation whenever one endpoint must serve heterogeneous clients; the trade-off is server-side branching complexity and the caching hazard handled by `Vary` (below).
+
+### Vary as the cache-correctness contract
+Any response whose body differs based on request headers must declare those headers in `Vary` (e.g., encoding and language). This instructs CDNs and intermediary caches to key stored copies on those header values. Omitting it is a classic production bug: a cache stores one client's compressed variant and hands it to a client that cannot decode it. Rule of thumb: whatever you negotiate on, you list in Vary. Cost: more cache keys means lower hit rates, so negotiate only on axes you actually serve differently.
+
+### Method + path as the routing key
+Routing maps the pair (HTTP method, URL path) onto a handler function. Because the method participates in the key, a GET and a POST at the same path are distinct routes with independent logic — the method carries intent (read vs. create vs. replace vs. delete), the path carries destination. This is the foundation for organizing handler code and for the REST convention of one resource path exposing several verbs.
+
+### Static vs. dynamic routes; path vs. query parameters
+Static routes are fixed strings; dynamic routes embed named placeholders (colon-prefixed in Express-style syntax) whose runtime segment values the framework extracts and hands to the handler. Complementing that, the article draws the parameter split: path parameters identify *which* resource (an ID embedded in the path), while query parameters — key/value pairs after the `?` — modify *how* the resource collection is handled: filtering, sorting, searching, pagination. Practical driver: GET requests carry no body, so the query string is their data channel. Design rule: identity in the path, behavior modifiers in the query.
+
+### Nested routes for resource hierarchy
+Parent-child resources can be expressed structurally in the URL (a posts collection scoped under a specific user's ID). Benefit: the route itself documents the relationship and handlers receive both parent and child identifiers. Trade-off: deep nesting couples client URLs to your data model; keep hierarchies shallow.
+
+### Versioning and deprecation lifecycle
+APIs evolve without breaking existing consumers by running multiple versions side by side — commonly a version segment in the path (v1, v2), alternatively a header or query parameter. Retirement is a signaled process, not a surprise: the `Deprecation` and `Sunset` HTTP headers announce that a version is obsolete and when it will disappear, giving clients a migration window before removal.
+
+### Catch-all routes as the fallback layer
+A wildcard route (Express/React Router `*`, Next.js bracket-spread segments) matches anything no explicit route claimed. Standard uses: serving 404 pages, handling arbitrarily deep dynamic paths, and the SPA pattern of routing every unknown path to the app shell so client-side routing can take over. Keep it registered last so it never shadows real routes.
+
+## Not absorbed
+
+- **Series announcement intro** — the author launching his backend + system design series and hoping readers enjoy it; personal framing, no engineering content.
+- **"What the heck is your backend?" section** — a beginner-level definition of frontend vs. backend; audience-orientation prose rather than a pattern.
+- **The nightclub/bouncer analogy for CORS** — pedagogical device; the underlying mechanism is captured in the CORS pattern above.
+- **Conversational asides in the status-code list** (jokey glosses on 401/429 etc.) — tone, not substance; the codes themselves are absorbed.
+- **Closing sign-off and engagement counts** (views/likes/reposts) — platform chrome.
+
+## Fidelity check
+
+**Post count in capture:** 1 (a single long-form article post; the JSON reports postCount 1 and contains no `---AUTHOR-POST-BREAK---` separators).
+
+**Article outline as the author structured it:**
+1. Series intro
+2. What the heck is your backend?
+3. What is HTTP?
+4. HTTP Responses (status line / headers / body)
+5. Status Codes
+6. The Headers That Matter
+7. CORS: Cross-Origin Resource Sharing (nightclub analogy; Why CORS Exists; Simple vs Preflighted Requests)
+8. Content Negotiation and Compression (The Core Idea; The Four Things They Negotiate On; Vary; A Full Real-World Exchange)
+9. Routing (What is Routing; Types of Routes; Path Parameters vs. Query Parameters; Nested Routing; Route Versioning and Deprecation; Catch-All Routes)
+10. Sign-off
+
+**Pattern-to-section citations:**
+- Three-part HTTP response anatomy → section 4, "HTTP Responses"
+- Status-code families as a triage system → section 5, "Status Codes"
+- Cache and security headers that do real work → section 6, "The Headers That Matter"
+- CORS as a browser-enforced read gate → section 7, "CORS" + "Why CORS Exists" (browser-only caveat from the end of the CORS section)
+- Simple vs. preflighted requests and preflight caching → section 7, "Simple vs Preflighted Requests"
+- Content negotiation across four axes → section 8, "The Four Things They Negotiate On"
+- Vary as the cache-correctness contract → section 8, the Vary passage and "A Full Real-World Exchange"
+- Method + path as the routing key → section 9, "What is Routing?"
+- Static vs. dynamic routes; path vs. query parameters → section 9, "Types of Routes" + "Path Parameters vs. Query Parameters"
+- Nested routes for resource hierarchy → section 9, "Nested Routing"
+- Versioning and deprecation lifecycle → section 9, "Route Versioning and Deprecation"
+- Catch-all routes as the fallback layer → section 9, "Catch-All Routes"