diff --git a/.gitignore b/.gitignore index 3cea453..4d6f608 100644 --- a/.gitignore +++ b/.gitignore @@ -50,3 +50,4 @@ mcp-server/node_modules/ # Vitals provenance data .vitals/ +.worktrees/ diff --git a/CHANGELOG.md b/CHANGELOG.md index deb7b41..9d83032 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,23 +6,25 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ## [Unreleased] -- **Threat database updated to v2.8.0** (`examples/commands/resources/threat-db.yaml`): 7 new entries covering March 2026 threats. **New campaigns**: GhostClaw (malicious npm `@openclaw-ai/openclawai`, GhostLoader RAT with SOCKS5 proxy + clipboard monitor, 178 downloads) and Fake OpenClaw Installer (Stealth Packer + GhostSocks via malicious GitHub repos indexed by Bing AI). **New malicious packages**: `@openclaw-ai/openclawai` and `ambar-src` (~50K downloads, evasion techniques). **New CVE**: CVE-2026-24910 (Bun runtime v<1.3.5, lifecycle scripts bypass origin validation). **New attack techniques**: T017 Shadow MCP (employees deploying unvetted MCP servers without IT oversight) and T018 AI Search Result Poisoning (AI-generated search results recommending malicious repos). **New scanning tools**: Jozu Agent Guard (zero-trust AI runtime, non-bypassable policies, 2026-03-17) and MCP Sentinel (RSAC 2026, request/arg scanning for sensitive data). **New defensive resource**: Jozu Agent Guard Runtime. `minimum_safe_versions` updated with `bun: 1.3.5`. Sources: THN, Huntress, itbrew, helpnetsecurity, SC World. +## [3.37.1] - 2026-03-18 + +- **Threat database updated to v2.8.0** (`examples/commands/resources/threat-db.yaml`): 7 new entries covering March 2026 threats. **New campaigns**: GhostClaw (malicious npm `@openclaw-ai/openclawai`, GhostLoader RAT with SOCKS5 proxy + clipboard monitor, 178 downloads) and Fake OpenClaw Installer (Stealth Packer + GhostSocks via malicious GitHub repos indexed by Bing AI). **New malicious packages**: `@openclaw-ai/openclawai` and `ambar-src` (~50K downloads, evasion techniques). **New CVE**: CVE-2026-24910 (Bun runtime v<1.3.5, lifecycle scripts bypass origin validation). **New attack techniques**: T017 Shadow MCP (employees deploying unvetted MCP servers without IT oversight) and T018 AI Search Result Poisoning (AI-generated search results recommending malicious repos). **New scanning tools**: Jozu Agent Guard (zero-trust AI runtime, non-bypassable policies, 2026-03-17) and MCP Sentinel (RSAC 2026, request/arg scanning for sensitive data). `minimum_safe_versions` updated with `bun: 1.3.5`. - **Claude Code releases tracking updated to v2.1.78** (`machine-readable/claude-code-releases.yaml`, `guide/core/claude-code-releases.md`): StopFailure hook event, ${CLAUDE_PLUGIN_DATA} persistent plugin state, effort/maxTurns/disallowedTools frontmatter for plugin agents, streaming line-by-line, 3 security fixes (silent sandbox disable, MCP deny rules bypass, protected dirs writable in bypassPermissions mode). -- **Skill descriptions improved — 19 skills updated** (`examples/skills/`): cleaner, action-oriented descriptions with explicit "Use when" triggers across the full skill library. Selective merge from @popey (Tessl) PR #9 (`tessl skill review`): kept improved `description:` lines across all 19 skills while preserving full reference documentation in template skills (audit-agents-skills, ccboard, design-patterns). Skills updated: guide-recap, landing-page-generator, pr-triage, release-notes-generator, skill-creator, voice-refine, talk-pipeline (7 stages), audit-agents-skills, ccboard, cyber-defense-team, design-patterns, issue-triage, rtk-optimizer. +- **Skill descriptions improved — 19 skills updated** (`examples/skills/`): cleaner, action-oriented descriptions with explicit "Use when" triggers. Selective merge from @popey (Tessl) PR #9: kept improved `description:` lines while preserving full reference documentation in template skills. -- **Fix — MCP vs CLI token overhead claim updated** (`guide/ecosystem/mcp-vs-cli.md`): corrected outdated token cost figures following v2.1.7 MCP Tool Search (lazy loading). The pre-v2.1.7 claim of "500-2,000 tokens per server" described eager loading, no longer the default. Updated: "Token cost of MCP schemas" section rewritten with lazy loading mechanics and measured 85% reduction benchmark (55K → 8.7K for 5-server setup); "Schema token cost" weakness nuanced; "Zero context overhead" CLI strength nuanced; guidance table "Tight context budget" row updated. Credit: Antoine Salesse for flagging the inconsistency with `architecture.md` §MCP Tool Search. +- **Fix — MCP vs CLI token overhead claim updated** (`guide/ecosystem/mcp-vs-cli.md`): corrected outdated token cost figures following v2.1.7 MCP Tool Search (lazy loading). "Token cost of MCP schemas" section rewritten with lazy loading mechanics and measured 85% reduction benchmark (55K → 8.7K for 5-server setup). Credit: Antoine Salesse. -- **Resource Evaluation #081 — Rippletide Code** (`docs/resource-evaluations/081-rippletide-code-rule-enforcement.md`): hook-native runtime rule enforcement for Claude Code (score 3/5, integrate with caveats). Addresses the documented CLAUDE.md degradation problem: rules ignored after 40+ entries, lost after context compaction. Architecture: Context Graph stored outside LLM context window + PreToolUse hooks block violations before execution. Distinct product from eval 072 (MCP/eval SaaS). Free beta (`npx rippletide-code`, no signup). Integration plan: (1) document the enforcement pattern in ultimate-guide.md CLAUDE.md limitations section, (2) add "Rule enforcement" gap to third-party-tools.md Known Gaps table, (3) add Rippletide entry in new Rule Enforcement section. Multiple claims unverified (compaction-resistance, "50% of issues", "<5s build") — treat as company claims. Watch trigger for 4/5: public GitHub repo >100 stars OR independent practitioner write-up from production. +- **Resource Evaluation #081 — Rippletide Code** (`docs/resource-evaluations/081-rippletide-code-rule-enforcement.md`): hook-native runtime rule enforcement for Claude Code (score 3/5, integrate with caveats). Addresses the CLAUDE.md degradation problem: rules ignored after 40+ entries, lost after context compaction. -- **New self-assessment section — Agent Adoption Curve** (`guide/roles/learning-with-ai.md`): 7-level maturity scale (0-6) for developers to self-locate on the Claude Code sophistication spectrum. Covers from "never used AI tools" (Level 0) to "orchestrating agent graphs" (Level 6), with 4 quick diagnostic questions and routing to relevant guide sections by level. Adapted from Nicolas Martignole (Back Market) maturity framework (March 2026). Inserted before the 30-Day Progression Plan as a prerequisite self-placement tool. +- **New self-assessment section — Agent Adoption Curve** (`guide/roles/learning-with-ai.md`): 7-level maturity scale (0-6) for developers to self-locate on the Claude Code sophistication spectrum, adapted from Nicolas Martignole (Back Market) maturity framework. -- **New guide section §5.5 — Registry-based Discovery: ctx7 CLI** (`guide/ultimate-guide.md`): Context7's CLI companion (`npx ctx7`) for automated skill discovery and MCP setup. Documents `ctx7 skills suggest` (dependency-aware skill recommendations), `ctx7 skills install owner/repo`, `ctx7 setup --claude` wizard, and `ctx7 docs` terminal lookup. Clarifies agentskills.io (open spec) vs context7.com/skills (registry) relationship. Cross-reference note added to `guide/ecosystem/mcp-servers-ecosystem.md` Context7 section. Resource evaluation: `docs/resource-evaluations/2026-03-17-context7-cli.md` (score 4/5). +- **New guide section §5.5 — Registry-based Discovery: ctx7 CLI** (`guide/ultimate-guide.md`): Context7's CLI companion (`npx ctx7`) for automated skill discovery and MCP setup. Resource evaluation: `docs/resource-evaluations/2026-03-17-context7-cli.md` (score 4/5). -- **Resource Evaluations #079 + #080 + ecosystem landscape** (`docs/resource-evaluations/079-fabro-workflow-orchestration.md`, `080-goose-block-coding-agent.md`): two evaluations + Perplexity competitive landscape analysis. **Fabro** (3/5, Watch): graph-based workflow orchestrator for coding agents (MIT, Rust single binary, 28 stars / 4 days old). Differentiators: DOT graph pipeline as diffable text (distinct from Ruflo/Pipelex/Athena Flow), Git checkpointing per stage (code + metadata committed to a branch after each step — no equivalent found in landscape), native `claude` CLI integration. Feature set unverified at evaluation. Re-eval trigger: >200 stars or practitioner write-up. Added to `watch-list.md`. **Goose by Block** (4/5, update): already documented in §11.1 but with stale data. Updated `guide/ecosystem/ai-ecosystem.md` §11.1: stats refreshed (15.4k → 33k stars, Jan → Mar 2026); MCP count inconsistency resolved ("3,000+" → "Thousands of"); added **Recipes** section (Goose's versionable multi-step workflows — closest analogy to Claude Code skills + commands combined); added **Subagent orchestration** section (heterogeneous agent teams with per-role model assignment, cross-reference §9). Competitive landscape (Perplexity): LangGraph closest graph-based equivalent (34k stars, Python, general purpose — no Git checkpointing); AutoGen (47.9k), CrewAI (34.7k), OpenHands (48k) also mapped. Fabro's Git-checkpointing-per-stage has no equivalent across all surveyed tools. +- **Resource Evaluations #079 + #080** (`docs/resource-evaluations/`): Fabro workflow orchestration (3/5, Watch) and Goose by Block update (4/5) with stats refresh (15.4k → 33k stars), Recipes section, and subagent orchestration documentation. -- **Doc audit — stats sync**: corrected stale counts across guide + landing. Templates: 204/216/217/218/222/232 → unified to 217 (per `check-landing-sync.sh` logic). Guide lines: "22K" → "23K+" (actual: 23,422). Quiz: reference.yaml `quiz_count` and llms*.txt had 311 → corrected to 271 (actual count). Version in llms.txt / llms-full.txt / machine-readable/llms.txt bumped 3.36.0 → 3.37.0. Landing updated: FeaturesGrid, GuideComparison, WhyGuide, McpDemo, cheatsheet page, index.astro, compare page, and guide content files (00-introduction, index, 09-advanced-patterns, 12-appendices). +- **Doc audit — stats sync**: corrected stale counts. Templates unified to 217. Guide lines: "22K" → "23K+". Quiz: 311 → 271. ## [3.37.0] - 2026-03-17 diff --git a/README.md b/README.md index cdfe748..ebd72d1 100644 --- a/README.md +++ b/README.md @@ -6,9 +6,9 @@

Stars - Last Update + Last Update Quiz - Templates + Templates Threat Database MCP Server

@@ -66,7 +66,7 @@ Both guides serve different needs. Choose based on your priority. | **Security hardening** | Only threat database (24 CVEs) | Basic patterns only | | **Test understanding** | 271-question quiz | Not available | | **Methodologies** (TDD/SDD/BDD) | Full workflow guides | Not covered | -| **Copy-paste ready** templates | 218 templates | 200+ templates | +| **Copy-paste ready** templates | 217 templates | 200+ templates | ### Ecosystem Positioning @@ -75,7 +75,7 @@ Both guides serve different needs. Choose based on your priority. ▲ │ │ ★ This Guide - │ Security + Methodologies + 22K lines + │ Security + Methodologies + 23K+ lines │ │ [Everything-You-Need-to-Know] │ SDLC/BMAD beginner @@ -92,7 +92,7 @@ Both guides serve different needs. Choose based on your priority. **4 unique gaps no competitor covers:** 1. **Security-First** — 24 CVEs + 655 malicious skills tracked (no competitor has this depth) 2. **Methodology Workflows** — TDD/SDD/BDD comparison + step-by-step guides -3. **Comprehensive Reference** — 22K lines across 16 specialized guides (24× more reference material than everything-cc) +3. **Comprehensive Reference** — 23K+ lines across 16 specialized guides (24× more reference material than everything-cc) 4. **Educational Progression** — 271-question quiz, beginner → expert path **Recommended workflow:** @@ -150,7 +150,7 @@ claude "Use the claude-code-guide MCP server. Activate the claude-code-expert pr graph LR root[📦 Repository
Root] - root --> guide[📖 guide/
22K lines] + root --> guide[📖 guide/
23K+ lines] root --> examples[📋 examples/
218 templates] root --> quiz[🧠 quiz/
271 questions] root --> tools[🔧 tools/
utils] @@ -240,7 +240,7 @@ graph LR [Browse all 41 diagrams →](./guide/diagrams/) -**What this means for you**: Understand the master loop before reading 22K lines, see multi-agent topologies at a glance, share visual security threat models with your team. +**What this means for you**: Understand the master loop before reading 23K+ lines, see multi-agent topologies at a glance, share visual security threat models with your team. --- @@ -543,31 +543,33 @@ security_gate_hook: "examples/hooks/bash/security-gate.sh" # file path ref ## 📄 Whitepapers (FR + EN) -A series of 11 focused whitepapers covering Claude Code in depth. Each covers a specific topic and is available in both **French and English**. +11 focused whitepapers covering Claude Code in depth — PDF + EPUB, available in French and English. 472 pages total. > **Coming soon** — currently in private access. Public release planned. -- **00** — *De Zéro à Productif / From Zero to Productive* — Foundations, first steps -- **01** — *Prompts qui Marchent / Prompts That Work* — Prompting method, context, hooks -- **02** — *Personnaliser Claude / Customizing Claude* — CLAUDE.md, custom agents, skills -- **03** — *Sécurité en Production / Security in Production* — 17 security hooks, threat DB, permissions -- **04** — *L'Architecture Démystifiée / Architecture Demystified* — Agent loop, context, token pricing -- **05** — *Déployer en Équipe / Team Deployment* — CI/CD, observability, 50+ devs adoption -- **06** — *Privacy & Compliance* — Anthropic data, ZDR, retention policies -- **07** — *Guide de Référence / Reference Guide* — Complete synthesis + advanced workflows -- **08** — *Agent Teams* — Multi-agent orchestration and coordination -- **09** — *Apprendre avec l'IA / Learning with AI* — UVAL protocol, comprehension debt, 30-day plan -- **10** — *Budget IA / AI Budget* — Token costs, model selection, cost optimization +| # | FR | EN | Pages | +|---|----|----|-------| +| **00** | *De Zéro à Productif* | *From Zero to Productive* | 20 | +| **01** | *Prompts qui Marchent* | *Prompts That Work* | 40 | +| **02** | *Personnaliser Claude* | *Customizing Claude* | 47 | +| **03** | *Sécurité en Production* | *Security in Production* | 48 | +| **04** | *L'Architecture Démystifiée* | *Architecture Demystified* | 40 | +| **05** | *Déployer en Équipe* | *Team Deployment* | 43 | +| **06** | *Privacy & Compliance* | *Privacy & Compliance* | 29 | +| **07** | *Guide de Référence* | *Reference Guide* | 87 | +| **08** | *Agent Teams* | *Agent Teams* | 42 | +| **09** | *Apprendre avec l'IA* | *Learning with AI* — UVAL protocol, comprehension debt | 49 | +| **10** | *Convaincre son Employeur* | *Making the Case for AI* — ROI dossier for CEO/CTO/CFO | 27 | -## 🗂️ Recap Cards (FR + EN) +## 🗂️ Recap Cards (FR, EN coming) -57 single-page A4 reference cards — printable, one concept per card. Organized in 3 series: +57 single-page A4 reference cards — printable, one concept per card. Available in French; English version in progress. -> **Coming soon** — currently in private access. Public release planned alongside the whitepapers. Available in French and English. +> **Browse online**: [cc.bruniaux.com/cheatsheets/](https://cc.bruniaux.com/cheatsheets/) - **Technique (22 cards)** — Commands, permissions, configuration, MCP, models, context window -- **Méthodologie / Methodology (22 cards)** — Daily workflow, agents, hooks, CI/CD, multi-agent, debug -- **Conception / Design (13 cards)** — Mental models, prompting, security by design, cost patterns +- **Méthodologie (22 cards)** — Daily workflow, agents, hooks, CI/CD, multi-agent, debug +- **Conception (13 cards)** — Mental models, prompting, security by design, cost patterns --- @@ -729,7 +731,7 @@ Use this guide critically. Experiment. Share what works for you. | File | Purpose | Time | |------|---------|------| -| **[Ultimate Guide](./guide/ultimate-guide.md)** | Complete reference (20K+ lines), 10 sections | 30-40h (full) • Most consult sections | +| **[Ultimate Guide](./guide/ultimate-guide.md)** | Complete reference (23K+ lines), 10 sections | 30-40h (full) • Most consult sections | | **[Cheat Sheet](./guide/cheatsheet.md)** | 1-page printable reference | 5 min | | **[Visual Reference](./guide/core/visual-reference.md)** | 20 ASCII diagrams for key concepts | 5 min | | **[Architecture](./guide/core/architecture.md)** | How Claude Code works internally | 25 min | @@ -872,7 +874,7 @@ See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines. --- -*Version 3.37.0 | Updated daily · Mar 17, 2026 | Crafted with Claude* +*Version 3.37.1 | Updated daily · Mar 18, 2026 | Crafted with Claude*