From 8f1dcecfa28973929db4bc9936d79bc9c9725c4f Mon Sep 17 00:00:00 2001 From: Florian BRUNIAUX Date: Mon, 9 Mar 2026 15:32:33 +0100 Subject: [PATCH] docs: update guide content, examples, tools, and reference files MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - guide/ultimate-guide.md — content updates - guide/workflows/README.md, guide/README.md — navigation improvements - guide/diagrams/ — diagram updates (context/sessions, config, MCP ecosystem) - guide/third-party-tools.md — additions - examples/README.md, hooks/README.md, scripts/README.md — examples updates - examples/skills/pr-triage/SKILL.md — expanded skill - machine-readable/reference.yaml — reference sync - tools/audit-prompt.md, tools/onboarding-prompt.md — tooling updates - docs/for-cto.md, docs/for-tech-leads.md, docs/resource-evaluations/README.md — doc updates - .gitignore — gitignore update Co-Authored-By: Claude Sonnet 4.6 --- .gitignore | 1 + docs/for-cto.md | 2 +- docs/for-tech-leads.md | 2 +- docs/resource-evaluations/README.md | 2 +- examples/README.md | 89 ++++++-- examples/hooks/README.md | 3 + examples/scripts/README.md | 6 + examples/skills/pr-triage/SKILL.md | 262 +++++++++++++++++++++- guide/README.md | 19 +- guide/diagrams/02-context-and-sessions.md | 25 ++- guide/diagrams/03-configuration-system.md | 31 ++- guide/diagrams/05-mcp-ecosystem.md | 8 +- guide/diagrams/README.md | 2 +- guide/third-party-tools.md | 35 ++- guide/ultimate-guide.md | 75 ++++++- guide/workflows/README.md | 48 +++- machine-readable/reference.yaml | 34 ++- tools/audit-prompt.md | 57 +++-- tools/onboarding-prompt.md | 42 ++-- 19 files changed, 639 insertions(+), 104 deletions(-) diff --git a/.gitignore b/.gitignore index ceb67db..3cea453 100644 --- a/.gitignore +++ b/.gitignore @@ -32,6 +32,7 @@ __pycache__/ # Personal notes & temp files to-ignore/ +docs/drafts/ .grepai/ whitepapers/ claudedocs/ diff --git a/docs/for-cto.md b/docs/for-cto.md index 3d8d1c5..24113b7 100644 --- a/docs/for-cto.md +++ b/docs/for-cto.md @@ -29,7 +29,7 @@ Full breakdown: WP06 — Privacy & GDPR Compliance *(whitepaper, coming soon)* ( ### Threat landscape -This is the only public resource tracking AI coding tool CVEs: **24 vulnerabilities and 655 malicious skills catalogued**. Key vectors relevant to enterprise: +This is the only public resource tracking AI coding tool vulnerabilities: **15 vulnerabilities and 655 malicious skills catalogued**. Key vectors relevant to enterprise: - Prompt injection via untrusted file content (e.g. malicious comments in dependencies) - Supply chain attacks via MCP servers (treat like npm packages) diff --git a/docs/for-tech-leads.md b/docs/for-tech-leads.md index 668cb22..af89c9c 100644 --- a/docs/for-tech-leads.md +++ b/docs/for-tech-leads.md @@ -66,7 +66,7 @@ See [Guide Ch.7.4 — Security Hooks](../guide/ultimate-guide.md#74-security-hoo ## Security posture overview -This guide maintains the **only public threat database for Claude Code**: 24 CVEs and 655 malicious skills catalogued. Key risks for teams: +This guide maintains the **only public threat database for Claude Code**: 15 vulnerabilities and 655 malicious skills catalogued. Key risks for teams: - **Prompt injection** via untrusted file content or MCP servers - **Overly permissive settings** — `allowedTools: ["*"]` in production diff --git a/docs/resource-evaluations/README.md b/docs/resource-evaluations/README.md index 207f944..e7f5951 100644 --- a/docs/resource-evaluations/README.md +++ b/docs/resource-evaluations/README.md @@ -77,4 +77,4 @@ Ressources surveillées mais pas encore intégrées : [watch-list.md](./watch-li --- -**Dernier update**: 2026-02-28 (72 évaluations) +**Dernier update**: 2026-03-09 (115 évaluations) diff --git a/examples/README.md b/examples/README.md index 08c59fd..c34a0f1 100644 --- a/examples/README.md +++ b/examples/README.md @@ -14,18 +14,21 @@ Annotated templates that teach you **why** patterns work, not just how to config | Folder | Description | Count | |--------|-------------|-------| -| [`agents/`](./agents/) | Custom AI personas for specialized tasks | 9 | -| [`commands/`](./commands/) | Slash commands (workflow automation) | 26 | -| [`hooks/`](./hooks/) | Event-driven security & automation scripts | 31 | -| [`skills/`](./skills/) | Reusable knowledge modules — [9 on SkillHub](https://skills.palebluedot.live/owner/FlorianBruniaux) | 15 | -| [`claude-md/`](./claude-md/) | CLAUDE.md configuration profiles | 6 | -| [`config/`](./config/) | Settings, MCP, git templates | 5 | +| [`agents/`](./agents/) | Custom AI personas for specialized tasks | 14 + 2 collections | +| [`commands/`](./commands/) | Slash commands (workflow automation) | 31 | +| [`hooks/`](./hooks/) | Event-driven security & automation scripts | 34 | +| [`skills/`](./skills/) | Reusable knowledge modules — [9 on SkillHub](https://skills.palebluedot.live/owner/FlorianBruniaux) | 17 | +| [`claude-md/`](./claude-md/) | CLAUDE.md configuration profiles | 7 | +| [`config/`](./config/) | Settings, MCP, git templates | 8 | | [`memory/`](./memory/) | CLAUDE.md memory file templates | 2 | -| [`scripts/`](./scripts/) | Diagnostic & utility scripts | 13 | +| [`rules/`](./rules/) | Behavioral rules for common review patterns | 5 | +| [`scripts/`](./scripts/) | Diagnostic & utility scripts | 16 | +| [`team-config/`](./team-config/) | Team onboarding templates | 3 | +| [`templates/`](./templates/) | Session and workflow templates | 1 | | [`github-actions/`](./github-actions/) | CI/CD workflows | 4 | | [`workflows/`](./workflows/) | Advanced development workflows | 3 | | [`plugins/`](./plugins/) | Community plugins (SE-CoVe, claude-mem) | 2 | -| [`integrations/`](./integrations/) | External tool integrations (Agent Vibes TTS) | 4 | +| [`integrations/`](./integrations/) | External tool integrations (Agent Vibes TTS) | 1 | | [`mcp-configs/`](./mcp-configs/) | MCP server configurations | 1 | | [`modes/`](./modes/) | Behavioral modes (SuperClaude) | 1 | | [`semantic-anchors/`](./semantic-anchors/) | Precise vocabulary for better LLM outputs | 1 | @@ -53,7 +56,7 @@ Annotated templates that teach you **why** patterns work, not just how to config ## Templates Index -### Agents (9) +### Agents (16) | File | Purpose | Model | |------|---------|-------| @@ -66,8 +69,15 @@ Annotated templates that teach you **why** patterns work, not just how to config | [planner.md](./agents/planner.md) | Strategic planning — read-only, before implementation | Opus | | [implementer.md](./agents/implementer.md) | Mechanical execution — bounded scope | Haiku | | [architecture-reviewer.md](./agents/architecture-reviewer.md) | Architecture & design review — read-only | Opus | +| [adr-writer.md](./agents/adr-writer.md) | Architecture Decision Record generator — read-only | Opus | +| [integration-reviewer.md](./agents/integration-reviewer.md) | Runtime integration validator — read-only | Sonnet | +| [plan-challenger.md](./agents/plan-challenger.md) | Adversarial plan review across 5 dimensions — read-only | Sonnet | +| [planning-coordinator.md](./agents/planning-coordinator.md) | Synthesis agent for dynamic research teams — read-only | Sonnet | +| [security-patcher.md](./agents/security-patcher.md) | Apply security patches from audit findings — proposes for review | Sonnet | +| [analytics-with-eval/](./agents/analytics-with-eval/) | Collection: analytics agent + evaluation hooks | — | +| [cyber-defense/](./agents/cyber-defense/) | Collection: anomaly detector, log ingestor, risk classifier, threat reporter | — | -### Skills (15) — [9 on SkillHub](https://skills.palebluedot.live/owner/FlorianBruniaux) +### Skills (17) — [9 on SkillHub](https://skills.palebluedot.live/owner/FlorianBruniaux) | File | Purpose | |------|---------| @@ -84,10 +94,12 @@ Annotated templates that teach you **why** patterns work, not just how to config | [ccboard/](./skills/ccboard/) | Comprehensive TUI/Web dashboard for Claude Code monitoring | | [guide-recap/](./skills/guide-recap/) | Transform CHANGELOG entries into social content (LinkedIn, Twitter/X, Slack) | | [release-notes-generator/](./skills/release-notes-generator/) | Generate release notes in 3 formats from git commits | -| [pr-triage/](./skills/pr-triage/) | 3-phase PR backlog management (audit, deep review, validated comments) | +| [pr-triage/](./skills/pr-triage/) | 4-phase PR backlog management (audit, deep review, validated comments, worktree setup) | | [issue-triage/](./skills/issue-triage/) | 3-phase issue backlog management (audit, deep analysis, validated actions) | +| [cyber-defense-team/](./skills/cyber-defense-team/) | Multi-agent cyber defense team orchestration | +| [talk-pipeline/](./skills/talk-pipeline/) | 6-stage pipeline: raw material to slides via Kimi | -### Commands (26) +### Commands (31) | File | Trigger | Purpose | |------|---------|---------| @@ -117,12 +129,17 @@ Annotated templates that teach you **why** patterns work, not just how to config | [learn/quiz.md](./commands/learn/quiz.md) | `/learn:quiz` | Self-testing for learning concepts | | [learn/teach.md](./commands/learn/teach.md) | `/learn:teach` | Step-by-step concept explanations | | [learn/alternatives.md](./commands/learn/alternatives.md) | `/learn:alternatives` | Compare different approaches | +| [audit-codebase.md](./commands/audit-codebase.md) | `/audit-codebase` | Codebase health audit scoring 7 categories | +| [plan-start.md](./commands/plan-start.md) | `/plan-start` | 5-phase planning: PRD analysis, design review, technical decisions, research team, metrics | +| [plan-execute.md](./commands/plan-execute.md) | `/plan-execute` | Execute validated plan: worktree isolation, TDD scaffolding, parallel agents, PR creation | +| [plan-validate.md](./commands/plan-validate.md) | `/plan-validate` | 2-layer plan validation: structural checks + specialist agents, auto-fix issues | +| [review-plan.md](./commands/review-plan.md) | `/review-plan` | Structured plan review across 4 axes before writing code | -### Hooks (31) +### Hooks (34) Security-first: 12 security hooks, 8 productivity hooks, 5 automation hooks, 5 monitoring hooks. -**Security Hooks** (12 bash): +**Security Hooks** (13 bash): | File | Event | Purpose | |------|-------|---------| @@ -138,8 +155,9 @@ Security-first: 12 security hooks, 8 productivity hooks, 5 automation hooks, 5 m | [claudemd-scanner.sh](./hooks/bash/claudemd-scanner.sh) | SessionStart | Detect CLAUDE.md injection attacks | | [output-secrets-scanner.sh](./hooks/bash/output-secrets-scanner.sh) | PostToolUse | Prevent API keys/tokens in Claude responses | | [pre-commit-secrets.sh](./hooks/bash/pre-commit-secrets.sh) | Git hook | Block secrets from entering commits | +| [security-gate.sh](./hooks/bash/security-gate.sh) | PreToolUse | Detect vulnerable code patterns before writing to source files | -**Productivity Hooks** (8): +**Productivity Hooks** (10): | File | Event | Purpose | |------|-------|---------| @@ -151,8 +169,10 @@ Security-first: 12 security hooks, 8 productivity hooks, 5 automation hooks, 5 m | [rtk-baseline.sh](./hooks/bash/rtk-baseline.sh) | SessionStart | Save RTK baseline for session savings tracking | | [setup-init.sh](./hooks/bash/setup-init.sh) | SessionStart | Initialize session environment | | [subagent-stop.sh](./hooks/bash/subagent-stop.sh) | Stop | Clean up sub-agent resources | +| [auto-rename-session.sh](./hooks/bash/auto-rename-session.sh) | SessionEnd | AI-powered session title generation (Haiku) | +| [velocity-governor.sh](./hooks/bash/velocity-governor.sh) | PreToolUse | Rate-limit tool calls to avoid API throttling | -**Monitoring Hooks** (5): +**Monitoring Hooks** (6): | File | Event | Purpose | |------|-------|---------| @@ -180,7 +200,7 @@ Security-first: 12 security hooks, 8 productivity hooks, 5 automation hooks, 5 m > **See [hooks/README.md](./hooks/README.md) for full documentation, configuration examples, and security hardening patterns** -### Config (5) +### Config (8) | File | Purpose | |------|---------| @@ -189,6 +209,9 @@ Security-first: 12 security hooks, 8 productivity hooks, 5 automation hooks, 5 m | [.gitignore-claude](./config/.gitignore-claude) | Git ignore patterns | | [CONTRIBUTING-ai-disclosure.md](./config/CONTRIBUTING-ai-disclosure.md) | AI disclosure template for CONTRIBUTING.md | | [PULL_REQUEST_TEMPLATE-ai.md](./config/PULL_REQUEST_TEMPLATE-ai.md) | PR template with AI attribution | +| [sandbox-native.json](./config/sandbox-native.json) | Native Claude Code sandbox configuration | +| [settings-personalization.json](./config/settings-personalization.json) | UI personalization: spinner verbs, custom tips carousel | +| [settings.local.json.example](./config/settings.local.json.example) | Local overrides example (gitignored) | ### Memory (2) @@ -197,7 +220,7 @@ Security-first: 12 security hooks, 8 productivity hooks, 5 automation hooks, 5 m | [CLAUDE.md.project-template](./memory/CLAUDE.md.project-template) | Team project memory | | [CLAUDE.md.personal-template](./memory/CLAUDE.md.personal-template) | Personal global memory | -### CLAUDE.md Configurations (6) +### CLAUDE.md Configurations (7) | File | Purpose | |------|---------| @@ -207,11 +230,12 @@ Security-first: 12 security hooks, 8 productivity hooks, 5 automation hooks, 5 m | [tts-enabled.md](./claude-md/tts-enabled.md) | Text-to-speech enabled configuration | | [rtk-optimized.md](./claude-md/rtk-optimized.md) | RTK token-optimized configuration | | [session-naming.md](./claude-md/session-naming.md) | Auto-rename sessions with descriptive titles for parallel work | +| [design-reference-file.md](./claude-md/design-reference-file.md) | Brand-book and UI kit context for consistent UI generation | > **See [guide/learning-with-ai.md](../guide/learning-with-ai.md) for learning mode documentation** > **See [guide/devops-sre.md](../guide/devops-sre.md) for DevOps/SRE guide** -### Scripts (13) +### Scripts (16) | File | Purpose | Output | |------|---------|--------| @@ -222,15 +246,42 @@ Security-first: 12 security hooks, 8 productivity hooks, 5 automation hooks, 5 m | [clean-reinstall-claude.ps1](./scripts/clean-reinstall-claude.ps1) | Clean reinstall procedure (Windows) | Human | | [session-stats.sh](./scripts/session-stats.sh) | Analyze session logs & costs | JSON / Human | | [session-search.sh](./scripts/session-search.sh) | Fast session search & resume | Human | +| [cc-sessions.py](./scripts/cc-sessions.py) | Advanced session search with incremental indexing | Human | | [fresh-context-loop.sh](./scripts/fresh-context-loop.sh) | Auto-restart sessions at context limits | Human | | [bridge.py](./scripts/bridge.py) | Plan bridging between sessions | JSON | +| [bridge-plan-schema.json](./scripts/bridge-plan-schema.json) | JSON Schema for bridge plan v1 format | — | | [migrate-arguments-syntax.sh](./scripts/migrate-arguments-syntax.sh) | Migrate v1 → v2 argument syntax (bash) | Human | | [migrate-arguments-syntax.ps1](./scripts/migrate-arguments-syntax.ps1) | Migrate v1 → v2 argument syntax (PowerShell) | Human | | [rtk-benchmark.sh](./scripts/rtk-benchmark.sh) | Benchmark RTK token savings | Human | | [sync-claude-config.sh](./scripts/sync-claude-config.sh) | Sync Claude config across machines | Human | +| [sonnetplan.sh](./scripts/sonnetplan.sh) | Alias to run Claude with Sonnet instead of Opus (cost optimization) | Human | > **See [scripts/README.md](./scripts/README.md) for detailed usage** +### Rules (5) + +| File | Purpose | +|------|---------| +| [architecture-review.md](./rules/architecture-review.md) | Rules for architecture review sessions | +| [code-quality-review.md](./rules/code-quality-review.md) | Rules for code quality review sessions | +| [first-principles.md](./rules/first-principles.md) | First-principles reasoning rules | +| [performance-review.md](./rules/performance-review.md) | Rules for performance review sessions | +| [test-review.md](./rules/test-review.md) | Rules for test review sessions | + +### Team Config (3) + +| File | Purpose | +|------|---------| +| [claude-skeleton.md](./team-config/claude-skeleton.md) | Minimal CLAUDE.md skeleton for new team members | +| [profile-template.yaml](./team-config/profile-template.yaml) | Profile assembly template for multi-tool teams | +| [sync-script.ts](./team-config/sync-script.ts) | Sync Claude config across team machines | + +### Templates (1) + +| File | Purpose | +|------|---------| +| [session-handoff-lorenz.md](./templates/session-handoff-lorenz.md) | Session handoff template for context continuity | + ### GitHub Actions (4) | File | Trigger | Purpose | diff --git a/examples/hooks/README.md b/examples/hooks/README.md index e79a0e3..7b033dd 100644 --- a/examples/hooks/README.md +++ b/examples/hooks/README.md @@ -41,6 +41,9 @@ Hooks are scripts that execute automatically on Claude Code events. They enable | [pre-commit-secrets.sh](./bash/pre-commit-secrets.sh) | Git hook | Block secrets from entering commits | Bash | | [pre-commit-evaluator.sh](./bash/pre-commit-evaluator.sh) | Git hook | LLM-as-a-Judge pre-commit validation | Bash | | [notification.sh](./bash/notification.sh) | Notification | Contextual macOS sound alerts | Bash (macOS) | +| [auto-rename-session.sh](./bash/auto-rename-session.sh) | SessionEnd | AI-powered session title generation via Haiku | Bash | +| [security-gate.sh](./bash/security-gate.sh) | PreToolUse | Detect vulnerable code patterns before writing to source files | Bash | +| [velocity-governor.sh](./bash/velocity-governor.sh) | PreToolUse | Rate-limit tool calls to avoid API throttling | Bash | | [security-check.ps1](./powershell/security-check.ps1) | PreToolUse | Block secrets in commands | PowerShell | | [auto-format.ps1](./powershell/auto-format.ps1) | PostToolUse | Auto-format after edits | PowerShell | diff --git a/examples/scripts/README.md b/examples/scripts/README.md index 26fedfb..e3b5f25 100644 --- a/examples/scripts/README.md +++ b/examples/scripts/README.md @@ -20,6 +20,12 @@ Utility scripts for Claude Code power users. | `cc-sessions.py` | Advanced session search with incremental indexing (Python) | | `session-stats.sh` | Statistics about Claude Code sessions | | `bridge.py` | Bridge: Claude Code → doobidoo → LM Studio | +| `bridge-plan-schema.json` | JSON Schema for bridge plan v1 format | +| `migrate-arguments-syntax.sh` | Migrate v1 → v2 slash command argument syntax (bash) | +| `migrate-arguments-syntax.ps1` | Migrate v1 → v2 slash command argument syntax (PowerShell) | +| `rtk-benchmark.sh` | Benchmark RTK token savings vs raw commands | +| `sync-claude-config.sh` | Sync Claude config files across machines | +| `sonnetplan.sh` | Run Claude with Sonnet replacing Opus (cost optimization alias) | --- diff --git a/examples/skills/pr-triage/SKILL.md b/examples/skills/pr-triage/SKILL.md index c5010aa..62fb645 100644 --- a/examples/skills/pr-triage/SKILL.md +++ b/examples/skills/pr-triage/SKILL.md @@ -1,15 +1,15 @@ --- name: pr-triage description: > - 3-phase PR backlog management: audit open PRs, deep review selected ones, draft and post - review comments with mandatory validation. Args: "all" to review all, PR numbers to focus - (e.g. "42 57"), "en"/"fr" for language, no arg = audit only in French. -tags: [github, pr, triage, review, maintainer, multi-agent] + 4-phase PR backlog management: audit open PRs, deep review selected ones, post validated + review comments, and optionally create local worktrees for hands-on review. Args: "all" + to review all, PR numbers to focus (e.g. "42 57"), "en"/"fr" for language, no arg = audit only. +tags: [github, pr, triage, review, maintainer, multi-agent, worktree] --- # PR Triage -3-phase workflow for maintainers: automated audit of all open PRs, opt-in deep review via parallel agents, and validated comment posting. +4-phase workflow for maintainers: automated audit of all open PRs, opt-in deep review via parallel agents, validated comment posting, and optional worktree setup for local review. ## When to Use This Skill @@ -158,6 +158,24 @@ _External — Problematic_: any of: 0 PRs → display `No open PRs.` and stop. +### Navigation Post-Phase 1 + +After displaying the triage table, ask via `AskUserQuestion`: + +``` +question: "What would you like to do next?" +header: "Next Step" +options: + - label: "Phase 2 — Deep review" + description: "Analyze selected PRs with code-reviewer agents and generate comment drafts" + - label: "Phase 4 — Create worktrees" + description: "Set up local worktrees for hands-on review (skips comment generation)" + - label: "Done" + description: "End the workflow here" +``` + +Note: Phase 3 (posting comments) is NOT offered here — it requires the drafts generated in Phase 2. If the user picks "Phase 4", Phase 2 → Phase 3 remains accessible afterward. + ### Automatic Copy After displaying the triage table, copy to clipboard using platform-appropriate command: @@ -352,6 +370,229 @@ Add your stack's checklist to the agent prompt in Phase 2. Examples by stack: --- +--- + +## Phase 4 — Worktree Setup (opt-in) + +Creates local git worktrees for each selected PR so you can run, test, or review code without switching branches. + +**Never triggered automatically** — only via Phase 1 navigation or explicit user request. + +### Step 4.1 — Cache check + PR list + +**Cache check**: before using data from Phase 1, verify it is less than 30 minutes old: + +```bash +CACHE_FILE="/tmp/pr-triage-prs.json" +CACHE_AGE=$(( $(date +%s) - $(stat -f %m "$CACHE_FILE" 2>/dev/null || echo 0) )) +if [ "$CACHE_AGE" -gt 1800 ]; then + echo "STALE_CACHE" +fi +``` + +If `STALE_CACHE` → re-run the Phase 1 data gathering before continuing. + +**Filter**: exclude Draft PRs and bot PRs (Dependabot, renovate, etc.): + +```bash +python3 -c " +import json +prs = json.load(open('/tmp/pr-triage-prs.json')) +filtered = [ + p for p in prs + if not p['isDraft'] + and not any(bot in p['author']['login'].lower() for bot in ['dependabot', 'renovate', 'snyk']) +] +import sys; json.dump(filtered, sys.stdout, indent=2) +" > /tmp/pr-triage-phase4.json +``` + +If 0 PRs after filtering → display `No reviewable PRs available for worktree (all are drafts or bots).` + end Phase 4. + +**Display grouped by author** (use display name if available, fallback to login): + +``` +## PRs available for worktree (non-draft) + +### Alice Martin (@alice) + [1] #123 — feat(auth): add OAuth2 support + Branch: feat/oauth2 | Size: M | CI: clean + +### Bob Chen (@bob) + [2] #456 — fix(api): handle empty response + Branch: fix/empty-response | Size: S | CI: dirty ⚠️ +``` + +### Step 4.2 — Selection + +Ask via `AskUserQuestion` (multiSelect): + +``` +question: "Which PRs do you want to create a worktree for?" +header: "Worktree Setup" +multiSelect: true +options: + - label: "All" + description: "Create worktrees for all {N} listed PRs" + - label: "[1] #{num} — {title} ({author})" + description: "Branch: {branch} | Size: {size} | CI: {ci}" + - label: "None" + description: "Cancel — return to menu" +``` + +If "None" → end Phase 4. + +### Step 4.3 — Sequential creation + +**Execution model**: Claude runs **one bash command per PR**, reads its output, updates its internal state (created / existing / failed), then moves to the next. Never a bash loop wrapping all PRs. + +For each selected PR, Claude sets variables explicitly then runs: + +```bash +PR_NUM="123" +BRANCH_NAME="feat/oauth2" +WORKTREE_NAME="${BRANCH_NAME//\//-}" +REPO_ROOT="$(cd "$(git rev-parse --git-common-dir)/.." && pwd)" +WORKTREE_DIR="$REPO_ROOT/.worktrees/$WORKTREE_NAME" + +# Already exists? +if [ -d "$WORKTREE_DIR" ]; then + echo "STATUS:EXISTING:$PR_NUM:$WORKTREE_DIR" + exit 0 +fi + +# .gitignore check (fail-fast) +if ! grep -qE "^\.worktrees/?$" "$REPO_ROOT/.gitignore" 2>/dev/null; then + echo "STATUS:GITIGNORE_MISSING:$PR_NUM" + exit 1 +fi + +# Fetch remote branch +if ! git fetch origin "$BRANCH_NAME" 2>/tmp/wt-fetch-$PR_NUM.log; then + echo "STATUS:FETCH_FAILED:$PR_NUM" + exit 1 +fi + +mkdir -p "$REPO_ROOT/.worktrees" + +# Create worktree (branch local exists or not) +if ! git branch --list "$BRANCH_NAME" | grep -q "$BRANCH_NAME"; then + git worktree add -b "$BRANCH_NAME" "$WORKTREE_DIR" "origin/$BRANCH_NAME" \ + 2>/tmp/wt-err-$PR_NUM.log +else + git worktree add "$WORKTREE_DIR" "$BRANCH_NAME" \ + 2>/tmp/wt-err-$PR_NUM.log +fi + +if [ $? -ne 0 ]; then + if grep -q "already checked out" /tmp/wt-err-$PR_NUM.log; then + echo "STATUS:ALREADY_CHECKED_OUT:$PR_NUM" + else + echo "STATUS:CREATE_FAILED:$PR_NUM" + fi + exit 1 +fi + +# Optional: symlink node_modules (Node.js projects — avoids reinstall) +[ -d "$REPO_ROOT/node_modules" ] && ln -sf "$REPO_ROOT/node_modules" "$WORKTREE_DIR/node_modules" + +# Copy project-specific files listed in .worktreeinclude (if present) +if [ -f "$REPO_ROOT/.worktreeinclude" ]; then + while IFS= read -r entry || [ -n "$entry" ]; do + [[ "$entry" =~ ^#.*$ || -z "$entry" ]] && continue + entry="$(echo "$entry" | xargs)" + [ -e "$REPO_ROOT/$entry" ] && { + mkdir -p "$(dirname "$WORKTREE_DIR/$entry")" + cp -R "$REPO_ROOT/$entry" "$WORKTREE_DIR/$entry" + } + done < "$REPO_ROOT/.worktreeinclude" +fi + +echo "STATUS:CREATED:$PR_NUM:$WORKTREE_DIR" +``` + +**Status handling** (Claude maintains internal state between PRs): + +| Status | Claude action | +|--------|--------------| +| `STATUS:CREATED:NUM:PATH` | Add to "created" list | +| `STATUS:EXISTING:NUM:PATH` | Add to "existing" list → offer pull in Step 4.4 | +| `STATUS:FETCH_FAILED:NUM` | Warn + continue to next PR | +| `STATUS:GITIGNORE_MISSING:NUM` | Fail-fast: show fix instructions + stop Phase 4 | +| `STATUS:ALREADY_CHECKED_OUT:NUM` | Warn: "Branch already checked out in another worktree. Run `git worktree list` to locate it." | +| `STATUS:CREATE_FAILED:NUM` | Warn + continue to next PR | + +**GITIGNORE_MISSING fix instructions**: +``` +.worktrees/ is not in .gitignore. Add it to avoid accidentally committing worktree files: + echo ".worktrees/" >> .gitignore +Then re-run Phase 4. +``` + +### Step 4.4 — Update existing worktrees + +If any `STATUS:EXISTING` collected, offer a single prompt: + +``` +Existing worktrees detected: + PR #123 — .worktrees/feat-oauth2 + PR #789 — .worktrees/fix-session-leak + +- [Pull all] git pull --ff-only in all existing worktrees +- [#123] Pull PR #123 only +- [Skip] Leave as-is +``` + +For each selected pull, Claude runs (one command per worktree): + +```bash +PR_NUM="123" +BRANCH_NAME="feat/oauth2" +WORKTREE_DIR="/abs/path/.worktrees/feat-oauth2" + +cd "$WORKTREE_DIR" && git pull origin "$BRANCH_NAME" --ff-only 2>/tmp/wt-pull-$PR_NUM.log +echo "PULL_STATUS:$?:$PR_NUM" +``` + +If `PULL_STATUS` ≠ 0: +``` +⚠️ PR #123 — --ff-only failed (branches have diverged) + Manual fix: cd .worktrees/feat-oauth2 && git pull --rebase +``` + +### Step 4.5 — Summary + +``` +## Worktrees ready + +| PR | Author | Branch | Path | Status | +|----|--------|--------|------|--------| +| #123 | Alice | feat/oauth2 | .worktrees/feat-oauth2 | Created | +| #456 | Bob | fix/empty-response | .worktrees/fix-empty-response | Created | +| #789 | Alice | fix/session-leak | .worktrees/fix-session-leak | Updated (pull) | +| #321 | Carol | feat/chat | .worktrees/feat-chat | Fetch failed ⚠️ | + +Note: if a PR modifies package.json, install dependencies manually: + cd .worktrees/ && npm install # or pnpm/yarn/bun + +Next steps: + cd .worktrees/ + claude +``` + +### `.worktreeinclude` convention + +Create a `.worktreeinclude` file at the repo root to list files Phase 4 copies into each new worktree. Useful for local config files not tracked in git: + +``` +# .worktreeinclude +.env.local +.env.test +config/local.json +``` + +--- + ## Edge Cases | Situation | Behavior | @@ -364,6 +605,11 @@ Add your stack's checklist to the agent prompt in Phase 2. Examples by stack: | Very large PR (>5000 additions) | Warn: "Partial review, diff truncated" | | Collaborators API 403/404 | Fallback to last 10 merged PR authors | | Parallel agents unavailable | Run sequential reviews, notify user | +| Phase 4: `.gitignore` missing `.worktrees/` | Fail-fast, show fix instructions, stop Phase 4 | +| Phase 4: branch already checked out | Warn with `git worktree list` hint, skip this PR | +| Phase 4: stale cache (>30min) | Re-fetch PR list before creating worktrees | +| Phase 4: PR modifies `package.json` | Warn in summary to run install manually | +| Phase 4: 0 non-draft PRs | Display message + end Phase 4 | --- @@ -384,9 +630,9 @@ Add your stack's checklist to the agent prompt in Phase 2. Examples by stack: |--|-------------|--------------| | **Scope** | Full PR backlog | Single PR | | **Use when** | Catching up after accumulation, periodic triage | Reviewing a specific incoming PR | -| **Phases** | 3 (audit + deep review + comments) | 1 (review only) | +| **Phases** | 4 (audit + deep review + comments + worktrees) | 1 (review only) | | **Agents** | Parallel sub-agents per PR | Single session | -| **Output** | Triage table + review reports + GitHub comments | Inline review | +| **Output** | Triage table + review reports + GitHub comments + local worktrees | Inline review | | **Validation** | AskUserQuestion before posting | Manual decision | -**Decision rule**: use `/pr-triage` for backlog triage (5+ PRs), `/review-pr` for focused review of a single PR. +**Decision rule**: use `/pr-triage` for backlog triage (5+ PRs), `/review-pr` for focused review of a single PR. Use Phase 4 when you want to run the code locally rather than just reading the diff. diff --git a/guide/README.md b/guide/README.md index 93b67ee..a5fbef9 100644 --- a/guide/README.md +++ b/guide/README.md @@ -19,7 +19,7 @@ Core documentation for mastering Claude Code. | [known-issues.md](./known-issues.md) | **Critical bugs tracker**: security issues, token consumption, verified community reports | 15 min | | [cheatsheet.md](./cheatsheet.md) | 1-page printable quick reference | 5 min | | [visual-reference.md](./visual-reference.md) | Visual cheatsheet — ASCII diagrams for key concepts | 5 min | -| [diagrams/](./diagrams/) | **Visual Diagrams Series**: 40 Mermaid interactive diagrams for model selection, agent lifecycle, security, multi-agent patterns | 15 min | +| [diagrams/](./diagrams/) | **Visual Diagrams Series**: 41 Mermaid interactive diagrams for model selection, agent lifecycle, security, multi-agent patterns | 15 min | | [architecture.md](./architecture.md) | How Claude Code works internally (master loop, tools, context) | 25 min | | [learning-with-ai.md](./learning-with-ai.md) | Guide for juniors on using AI without losing skills | 15 min | | [adoption-approaches.md](./adoption-approaches.md) | Implementation strategies for teams | 15 min | @@ -33,6 +33,11 @@ Core documentation for mastering Claude Code. | [sandbox-isolation.md](./sandbox-isolation.md) | Docker Sandboxes, cloud alternatives, safe autonomy workflows | 10 min | | [ai-ecosystem.md](./ai-ecosystem.md) | Complementary AI tools (Perplexity, Gemini, Kimi, NotebookLM, TTS) | 30 min | | [cowork.md](./cowork.md) | Claude Cowork: Summary (see [dedicated repo](https://github.com/FlorianBruniaux/claude-cowork-guide) for full docs) | 5 min | +| [ai-roles.md](./ai-roles.md) | AI roles mapping: when to use Claude Code vs Claude Desktop vs API | 10 min | +| [production-safety.md](./production-safety.md) | Production safety: guardrails, review gates, rollback strategies | 15 min | +| [remarkable-ai.md](./remarkable-ai.md) | Remarkable AI usage patterns and power-user techniques | 10 min | +| [sandbox-native.md](./sandbox-native.md) | Native Claude Code sandbox: configuration and security model | 10 min | +| [search-tools-cheatsheet.md](./search-tools-cheatsheet.md) | Search tools quick reference: rg, grepai, Serena, ast-grep | 5 min | | [workflows/](./workflows/) | Practical workflow guides for Claude Code | 30 min | ### Cowork Documentation @@ -60,6 +65,18 @@ Hands-on guides for effective development patterns: | [workflows/iterative-refinement.md](./workflows/iterative-refinement.md) | Iterative improvement loops | | [workflows/tts-setup.md](./workflows/tts-setup.md) | Add text-to-speech narration to Claude Code (18 min) | | [workflows/task-management.md](./workflows/task-management.md) | Multi-session task tracking, TodoWrite migration | +| [workflows/agent-teams.md](./workflows/agent-teams.md) | Orchestrating multi-agent teams for complex tasks | +| [workflows/agent-teams-quick-start.md](./workflows/agent-teams-quick-start.md) | Quick start guide for agent team patterns | +| [workflows/dual-instance-planning.md](./workflows/dual-instance-planning.md) | Dual-instance planning: Opus plans, Sonnet executes | +| [workflows/event-driven-agents.md](./workflows/event-driven-agents.md) | Event-driven agent coordination patterns | +| [workflows/plan-pipeline.md](./workflows/plan-pipeline.md) | End-to-end plan pipeline: start, validate, execute | +| [workflows/design-to-code.md](./workflows/design-to-code.md) | Convert Figma/wireframes to working code | +| [workflows/exploration-workflow.md](./workflows/exploration-workflow.md) | Systematically explore unfamiliar codebases | +| [workflows/pdf-generation.md](./workflows/pdf-generation.md) | Generate professional PDFs with Quarto/Typst | +| [workflows/search-tools-mastery.md](./workflows/search-tools-mastery.md) | Master rg, grepai, Serena, ast-grep combined workflows | +| [workflows/skeleton-projects.md](./workflows/skeleton-projects.md) | Use battle-tested repos as scaffolding for new projects | +| [workflows/talk-pipeline.md](./workflows/talk-pipeline.md) | 6-stage talk preparation: raw material to slides | +| [workflows/team-ai-instructions.md](./workflows/team-ai-instructions.md) | Scale CLAUDE.md across multi-developer teams | ## Recommended Reading Order diff --git a/guide/diagrams/02-context-and-sessions.md b/guide/diagrams/02-context-and-sessions.md index 84cc274..67fa750 100644 --- a/guide/diagrams/02-context-and-sessions.md +++ b/guide/diagrams/02-context-and-sessions.md @@ -87,42 +87,48 @@ flowchart LR --- -### Memory Hierarchy — 5 Types +### Memory Hierarchy — 6 Types -Claude Code has 5 distinct memory types with different scopes and persistence. Knowing which memory type to use for each piece of information is key to effective sessions. +Claude Code has 6 distinct memory types with different scopes and persistence. Knowing which memory type to use for each piece of information is key to effective sessions. ```mermaid flowchart TD A["🌍 Global CLAUDE.md
~/.claude/CLAUDE.md"] --> B["📁 Project CLAUDE.md
/project-root/CLAUDE.md"] B --> C["📂 Subdirectory CLAUDE.md
/src/CLAUDE.md, /tests/CLAUDE.md"] - C --> D["💬 In-Conversation Context
Messages + tool results this session"] + C --> AM["🧠 Auto-Memory Native
~/.claude/projects/*/memory/MEMORY.md
v2.1.59+"] + AM --> D["💬 In-Conversation Context
Messages + tool results this session"] D --> E["⚡ Ephemeral State
MCP server state, tool cache"] A1["Scope: ALL projects
Persists: Always
Use: Global prefs, API keys"] --> A B1["Scope: This project
Persists: Always
Use: Project conventions"] --> B C1["Scope: This directory
Persists: Always
Use: Module-specific rules"] --> C + AM1["Scope: Per project
Persists: Cross-session
Use: Auto-saved memories, /memory"] --> AM D1["Scope: This session
Persists: Session only
Use: Task context"] --> D E1["Scope: This session
Persists: Session only
Use: Computed results"] --> E style A fill:#E87E2F,color:#fff style B fill:#6DB3F2,color:#fff style C fill:#6DB3F2,color:#fff + style AM fill:#7BC47F,color:#333 style D fill:#F5E6D3,color:#333 style E fill:#B8B8B8,color:#333 style A1 fill:#B8B8B8,color:#333 style B1 fill:#B8B8B8,color:#333 style C1 fill:#B8B8B8,color:#333 + style AM1 fill:#B8B8B8,color:#333 style D1 fill:#B8B8B8,color:#333 style E1 fill:#B8B8B8,color:#333 click A href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#31-memory-files-claudemd" "Global CLAUDE.md" click B href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#31-memory-files-claudemd" "Project CLAUDE.md" click C href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#31-memory-files-claudemd" "Subdirectory CLAUDE.md" + click AM href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#31-memory-files-claudemd" "Auto-Memory Native" click D href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#22-context-management" "In-Conversation Context" click E href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/architecture.md#3-context-management-internals" "Ephemeral State" click A1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#31-memory-files-claudemd" "Global scope — always persists" click B1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#31-memory-files-claudemd" "Project scope — always persists" click C1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#31-memory-files-claudemd" "Directory scope — always persists" + click AM1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#31-memory-files-claudemd" "Cross-session auto-memory" click D1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#22-context-management" "Session scope only" click E1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/architecture.md#3-context-management-internals" "Session scope only" ``` @@ -131,21 +137,24 @@ flowchart TD ASCII version ``` -PERMANENT ──────────────────────── SESSION ONLY +PERMANENT ──────────────────────────────── SESSION ONLY -~/.claude/CLAUDE.md In-conversation context - │ │ -/project/CLAUDE.md Ephemeral MCP state +~/.claude/CLAUDE.md In-conversation context + │ │ +/project/CLAUDE.md Ephemeral MCP state │ /subdir/CLAUDE.md + │ +Auto-Memory (MEMORY.md) ← cross-session, per project Higher = broader scope, always persists Lower = narrower scope, survives restarts +Auto-Memory = persists cross-session, scoped per project ``` -> **Source**: [Memory System](../ultimate-guide.md#memory-system) — Line ~3160 & ~3986 +> **Source**: [Memory System](../ultimate-guide.md#memory-system) — Line ~3160 & ~3986 | Auto-Memory: v2.1.59+ (v3.30.0) --- diff --git a/guide/diagrams/03-configuration-system.md b/guide/diagrams/03-configuration-system.md index 6e8435a..12fc079 100644 --- a/guide/diagrams/03-configuration-system.md +++ b/guide/diagrams/03-configuration-system.md @@ -188,20 +188,29 @@ Hooks let you run custom code at key points in Claude Code's lifecycle — for s ```mermaid flowchart TD - A([User sends message]) --> B{PreToolUse Hook} + INIT([Session starts]) -.->|v2.1.69+| INST{InstructionsLoaded Hook} + INST -.-> A + + A([User sends message]) --> UPS{UserPromptSubmit Hook} + UPS -->|Exit 0: proceed| B{PreToolUse Hook} + UPS -->|Exit 2: feedback| A B -->|Exit 0: allow| C[Tool executes] - B -->|Exit 1: block| D([Tool blocked
Clause stops]) + B -->|Exit 1: block| D([Tool blocked
Claude stops]) C --> E{PostToolUse Hook} E --> F[Next tool or response] F --> G{More tool calls?} G -->|Yes| B G -->|No| H([Session ends]) - H --> I{Stop Hook} + H --> I{Stop / SessionEnd Hook} I --> J([Complete]) K{PreCompact Hook} -.->|Before /compact| L[/compact runs] L --> M{PostCompact Hook} + NOTE["Hook types:
bash (exit 0/1/2)
http (POST JSON → URL, v2.1.63+)"] -.-> B + + style INST fill:#6DB3F2,color:#fff + style UPS fill:#6DB3F2,color:#fff style B fill:#E87E2F,color:#fff style D fill:#E85D5D,color:#fff style E fill:#E87E2F,color:#fff @@ -210,8 +219,12 @@ flowchart TD style M fill:#6DB3F2,color:#fff style C fill:#7BC47F,color:#333 style J fill:#7BC47F,color:#333 + style NOTE fill:#F5E6D3,color:#333 + click INIT href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#71-the-event-system" "Session starts" + click INST href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#71-the-event-system" "InstructionsLoaded Hook — v2.1.69+" click A href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#71-the-event-system" "User sends message" + click UPS href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#71-the-event-system" "UserPromptSubmit Hook" click B href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#71-the-event-system" "PreToolUse Hook" click C href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/architecture.md#2-the-tool-arsenal" "Tool executes" click D href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#71-the-event-system" "Tool blocked" @@ -219,7 +232,7 @@ flowchart TD click F href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#71-the-event-system" "Next tool or response" click G href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#71-the-event-system" "More tool calls?" click H href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#71-the-event-system" "Session ends" - click I href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#71-the-event-system" "Stop Hook" + click I href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#71-the-event-system" "Stop / SessionEnd Hook" click J href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#72-creating-hooks" "Complete" click K href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#71-the-event-system" "PreCompact Hook" click L href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#71-the-event-system" "/compact runs" @@ -230,8 +243,12 @@ flowchart TD ASCII version ``` +Session starts + │ (InstructionsLoaded Hook — v2.1.69+) User message │ + UserPromptSubmit ──exit 2──► feedback to Claude (loop) + │ exit 0 PreToolUse ──exit 1──► BLOCKED │ exit 0 ▼ @@ -243,13 +260,15 @@ More tools? ──yes──► PreToolUse (loop) │ no Session ends │ - Stop Hook + Stop / SessionEnd Hook │ Complete Separately: PreCompact ──► /compact ──► PostCompact + +Hook types: bash (exit 0/1/2) | http POST JSON (v2.1.63+) ``` -> **Source**: [Hooks System](../ultimate-guide.md#hooks) — Line ~5350 +> **Source**: [Hooks System](../ultimate-guide.md#hooks) — Line ~5350 | UserPromptSubmit + HTTP hooks: v2.1.63+ | InstructionsLoaded: v2.1.69+ diff --git a/guide/diagrams/05-mcp-ecosystem.md b/guide/diagrams/05-mcp-ecosystem.md index f8c2b88..29b4448 100644 --- a/guide/diagrams/05-mcp-ecosystem.md +++ b/guide/diagrams/05-mcp-ecosystem.md @@ -25,6 +25,8 @@ flowchart TD O1["context7
Library documentation"] O2["sequential-thinking
Multi-step reasoning"] O3["playwright
Browser automation"] + O4["git-mcp
Local git operations"] + O5["github-mcp
GitHub platform"] end subgraph DEV["👨‍💻 Community: Dev Tools"] @@ -49,6 +51,8 @@ flowchart TD style O1 fill:#7BC47F,color:#333 style O2 fill:#7BC47F,color:#333 style O3 fill:#7BC47F,color:#333 + style O4 fill:#7BC47F,color:#333 + style O5 fill:#7BC47F,color:#333 style D1 fill:#6DB3F2,color:#fff style D2 fill:#6DB3F2,color:#fff style D3 fill:#6DB3F2,color:#fff @@ -63,6 +67,8 @@ flowchart TD click O1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#82-available-servers" "context7 — Library docs" click O2 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#82-available-servers" "sequential-thinking" click O3 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#82-available-servers" "playwright — Browser automation" + click O4 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#82-available-servers" "git-mcp — Local git operations" + click O5 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#82-available-servers" "github-mcp — GitHub platform" click D1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#82-available-servers" "semgrep — Security scanning" click D2 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#82-available-servers" "github — PR management" click D3 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#82-available-servers" "grepai — Semantic search" @@ -79,7 +85,7 @@ flowchart TD ``` Claude Code -├── Official: context7, sequential-thinking, playwright +├── Official: context7, sequential-thinking, playwright, git-mcp, github-mcp ├── Community Dev: semgrep, github, grepai, filesystem-enhanced ├── Community Ops: kubernetes, docker, aws └── Local/Custom: project MCPs, internal API wrappers diff --git a/guide/diagrams/README.md b/guide/diagrams/README.md index 836ac61..684b610 100644 --- a/guide/diagrams/README.md +++ b/guide/diagrams/README.md @@ -1,6 +1,6 @@ --- title: "Claude Code — Visual Diagrams" -description: "40 Mermaid interactive diagrams covering all major Claude Code concepts" +description: "41 Mermaid interactive diagrams covering all major Claude Code concepts" tags: [reference, architecture, diagrams, mermaid] --- diff --git a/guide/third-party-tools.md b/guide/third-party-tools.md index 3c85902..eb5052d 100644 --- a/guide/third-party-tools.md +++ b/guide/third-party-tools.md @@ -8,7 +8,7 @@ tags: [reference, integration, plugin] > Community tools for token tracking, session management, configuration, and alternative UIs. > -> **Last verified**: February 2026 +> **Last verified**: March 2026 ## Table of Contents @@ -510,6 +510,39 @@ First shipped workflow: autonomous E2E test builder (Playwright CI-ready output) --- +### Pipelex + MTHDS + +**GitHub**: [github.com/Pipelex/pipelex](https://github.com/Pipelex/pipelex) — 623 stars (Mars 2026) +**License**: MIT | **Language**: Python | **Standard**: [mthds.ai](https://mthds.ai) + +> **Architectural distinction**: Pipelex n'orchestre pas des agents Claude Code — il fournit un **DSL déclaratif** (fichiers `.mthds`) pour définir des AI methods réutilisables. Là où Ruflo gère des swarms d'agents, Pipelex gère des pipelines multi-LLM typés et git-versionables. + +Runtime Python pour le standard ouvert MTHDS. Une "AI method" est un workflow multi-étapes qui chaîne LLMs, OCR, et génération d'image — chaque étape typée et validée avant exécution. Les méthodes sont git-versionables, partageables via le hub communautaire [mthds.sh](https://mthds.sh), et peuvent être auto-générées par Claude Code. + +**Intégration Claude Code** (Path A recommandé) : +```bash +pip install pipelex +npm install -g mthds +``` +``` +# Dans Claude Code : +/plugin marketplace add mthds-ai/skills +/plugin install mthds@mthds-ai-skills +/exit # Relancer Claude Code + +# Générer une méthode : +/mthds-build Analyse des CVs → scorecard + questions d'entretien + +# Exécuter : +/mthds-run +``` + +**Cas d'usage** : workflows répétables à fort volume — traitement de documents, scoring de candidats, classification d'emails, analyse de contrats. Pas adapté à l'exploration créative open-ended où les agents natifs Claude Code restent plus appropriés. + +**Status** : Watch — 8 mois d'existence, standard MTHDS pas encore validé à grande échelle. Surveiller la traction d'ici Q3 2026. + +--- + ## Plugin Ecosystem Claude Code's plugin system supports community-built extensions. For detailed documentation: diff --git a/guide/ultimate-guide.md b/guide/ultimate-guide.md index c032c3d..4ac0b90 100644 --- a/guide/ultimate-guide.md +++ b/guide/ultimate-guide.md @@ -106,9 +106,35 @@ Context full → /compact or /clear --- +## Choose Your Path + +The guide has 11 chapters and 22,000+ lines. You don't need to read everything — here's what matters for your situation: + +| I am... | Read this | Skip this | Time | +|---------|-----------|-----------|------| +| **Developer, getting started** | Ch.1 → Ch.2 → Ch.3 | Ch.9, Ch.11, Appendix | 3h | +| **Developer, intermediate** | Ch.2.6 → Ch.4 → Ch.5 → Ch.7 | Ch.1, Ch.10 ref only | 4h | +| **Power user / senior** | Ch.9 (Advanced) → Ch.4-8 | Ch.1 Quick Start | 2h | +| **Tech Lead / EM** | Ch.3.5 → Ch.9.17 → Ch.9.20 → Ch.11 | Ch.5-6 detail | 1h30 | +| **Just need a reference** | [Ch.10.5 Cheatsheet](#105-cheatsheet) | Everything else | 5 min | + +--- + +## Top 5 sections by ROI + +If you only have time for 5 sections: + +1. **[2.6 Mental Model](#26-mental-model)** — Understand how Claude Code thinks (20 min) +2. **[3.1 CLAUDE.md](#31-memory-files-claudemd)** — Persistent memory that survives sessions (30 min) +3. **[9.1 The Trinity](#91-the-trinity)** — The core pattern for agentic work (20 min) +4. **[7.4 Security Hooks](#74-security-hooks)** — Automate guardrails you won't forget (30 min) +5. **[10.5 Cheatsheet](#105-cheatsheet)** — Daily reference, bookmark it (5 min) + +--- + ## Table of Contents -- [1. Quick Start (Day 1)](#1-quick-start-day-1) +- [1. Quick Start (Day 1)](#1-quick-start-day-1) `🟢 Beginner` `⏱ 45 min` - [1.1 Installation](#11-installation) - [1.2 First Workflow](#12-first-workflow) - [1.3 Essential Commands](#13-essential-commands) @@ -117,7 +143,7 @@ Context full → /compact or /clear - [1.6 Migrating from Other AI Coding Tools](#16-migrating-from-other-ai-coding-tools) - [1.7 Trust Calibration](#17-trust-calibration-when-and-how-much-to-verify) - [1.8 Eight Beginner Mistakes](#18-eight-beginner-mistakes-and-how-to-avoid-them) -- [2. Core Concepts](#2-core-concepts) +- [2. Core Concepts](#2-core-concepts) `🟡 Intermediate` `⏱ 60 min` - [2.1 The Interaction Loop](#21-the-interaction-loop) - [2.2 Context Management](#22-context-management) - [2.3 Plan Mode](#23-plan-mode) @@ -129,42 +155,42 @@ Context full → /compact or /clear - [2.9 Semantic Anchors](#29-semantic-anchors) - [2.10 Data Flow & Privacy](#210-data-flow--privacy) - [2.11 Under the Hood](#211-under-the-hood) -- [3. Memory & Settings](#3-memory--settings) +- [3. Memory & Settings](#3-memory--settings) `🟢 Beginner` `⏱ 30 min` - [3.1 Memory Files (CLAUDE.md)](#31-memory-files-claudemd) - [3.2 The .claude/ Folder Structure](#32-the-claude-folder-structure) - [3.3 Settings & Permissions](#33-settings--permissions) - [3.4 Precedence Rules](#34-precedence-rules) - [3.5 Team Configuration at Scale](#35-team-configuration-at-scale) -- [4. Agents](#4-agents) +- [4. Agents](#4-agents) `🟡 Intermediate` `⏱ 45 min` - [4.1 What Are Agents](#41-what-are-agents) - [4.2 Creating Custom Agents](#42-creating-custom-agents) - [4.3 Agent Template](#43-agent-template) - [4.4 Best Practices](#44-best-practices) - [4.5 Agent Examples](#45-agent-examples) -- [5. Skills](#5-skills) +- [5. Skills](#5-skills) `🟡 Intermediate` `⏱ 30 min` - [5.1 Understanding Skills](#51-understanding-skills) - [5.2 Creating Skills](#52-creating-skills) - [5.3 Skill Template](#53-skill-template) - [5.4 Skill Examples](#54-skill-examples) -- [6. Commands](#6-commands) +- [6. Commands](#6-commands) `🟡 Intermediate` `⏱ 30 min` - [6.1 Slash Commands](#61-slash-commands) - [6.2 Creating Custom Commands](#62-creating-custom-commands) - [6.3 Command Template](#63-command-template) - [6.4 Command Examples](#64-command-examples) -- [7. Hooks](#7-hooks) +- [7. Hooks](#7-hooks) `🟡 Intermediate` `⏱ 45 min` - [7.1 The Event System](#71-the-event-system) - [7.2 Creating Hooks](#72-creating-hooks) - [7.3 Hook Templates](#73-hook-templates) - [7.4 Security Hooks](#74-security-hooks) - [7.5 Hook Examples](#75-hook-examples) -- [8. MCP Servers](#8-mcp-servers) +- [8. MCP Servers](#8-mcp-servers) `🟡 Intermediate` `⏱ 40 min` - [8.1 What is MCP](#81-what-is-mcp) - [8.2 Available Servers](#82-available-servers) - [8.3 Configuration](#83-configuration) - [8.4 Server Selection Guide](#84-server-selection-guide) - [8.5 Plugin System](#85-plugin-system) - [8.6 MCP Security](#86-mcp-security) -- [9. Advanced Patterns](#9-advanced-patterns) +- [9. Advanced Patterns](#9-advanced-patterns) `🔴 Advanced` `⏱ 3h` - [9.1 The Trinity](#91-the-trinity) - [9.2 Composition Patterns](#92-composition-patterns) - [9.3 CI/CD Integration](#93-cicd-integration) @@ -187,14 +213,14 @@ Context full → /compact or /clear - [9.20 Agent Teams (Multi-Agent Coordination)](#920-agent-teams-multi-agent-coordination) - [9.21 Legacy Codebase Modernization](#921-legacy-codebase-modernization) - [9.22 Remote Control (Mobile Access)](#922-remote-control-mobile-access) -- [10. Reference](#10-reference) +- [10. Reference](#10-reference) `🟢 All levels` `⏱ As needed` - [10.1 Commands Table](#101-commands-table) - [10.2 Keyboard Shortcuts](#102-keyboard-shortcuts) - [10.3 Configuration Reference](#103-configuration-reference) - [10.4 Troubleshooting](#104-troubleshooting) - [10.5 Cheatsheet](#105-cheatsheet) - [10.6 Daily Workflow & Checklists](#106-daily-workflow--checklists) -- [11. AI Ecosystem: Complementary Tools](#11-ai-ecosystem-complementary-tools) +- [11. AI Ecosystem: Complementary Tools](#11-ai-ecosystem-complementary-tools) `🟡 Intermediate` `⏱ 20 min` - [11.1 Why Complementarity Matters](#111-why-complementarity-matters) - [11.2 Tool Matrix](#112-tool-matrix) - [11.3 Practical Workflows](#113-practical-workflows) @@ -218,6 +244,8 @@ _Quick jump:_ [Installation](#11-installation) · [First Workflow](#12-first-wor **Goal**: Go from zero to productive +> **Already using Claude Code?** Skip to [1.6 Migration guide](#16-migrating-from-other-ai-coding-tools) or go directly to [Ch.2 Core Concepts](#2-core-concepts). + ## 1.1 Installation Choose your preferred installation method based on your operating system: @@ -1467,6 +1495,8 @@ _Quick jump:_ [The Interaction Loop](#21-the-interaction-loop) · [Context Manag --- +> **Experienced with Claude Code?** Jump to [2.6 Mental Model](#26-mental-model) — the highest-ROI section in this chapter. + ## 📌 Section 2 TL;DR (2 minutes) **What you'll learn**: The mental model and critical workflows for Claude Code mastery. @@ -9205,6 +9235,8 @@ Security hooks are critical for protecting your system. > **Advanced patterns**: For comprehensive security including Unicode injection detection, MCP config integrity verification, and CVE-specific mitigations, see [Security Hardening Guide](./security-hardening.md). > **Claude Code Security (research preview)**: Anthropic offers a dedicated codebase vulnerability scanner that traces data flows across files, challenges findings internally before surfacing them (adversarial validation), and generates patch suggestions. Separate from the Security Auditor Agent above — waitlist access only. See [Security Hardening Guide → Claude Code as Security Scanner](./security-hardening.md#claude-code-as-security-scanner-research-preview). +> +> **Validated at scale**: In a March 2026 partnership with Mozilla, Claude Opus 4.6 scanned ~6,000 C++ files in Firefox's JS engine in two weeks, surfacing 22 confirmed vulnerabilities (14 high severity) — roughly one fifth of all high-severity Firefox CVEs fixed in 2025. Demonstrates the model's practical depth for production security work, well beyond surface-level linting. ### Recommended Security Rules @@ -12718,6 +12750,10 @@ _Quick jump:_ [The Trinity](#91-the-trinity) · [Composition Patterns](#92-compo --- +> **Prerequisite**: Read [4.1 What Are Agents](#41-what-are-agents) and [3.1 CLAUDE.md](#31-memory-files-claudemd) before diving into 9.17-9.20. + +> **New to Claude Code?** Start with Ch.1-3 first. Chapter 9 makes most sense after 1-2 months of daily use. + ## 📌 Section 9 TL;DR (3 minutes) **What you'll learn**: Production-grade workflows that combine multiple Claude Code features. @@ -20716,6 +20752,7 @@ _Quick jump:_ [Commands Table](#101-commands-table) · [Keyboard Shortcuts](#102 | `/init` | Generate starter CLAUDE.md based on project structure | Config | | `/login` | Log in to Claude account | Auth | | `/logout` | Log out and re-authenticate | Auth | +| `/loop [interval] [prompt]` | Run a prompt or slash command on a recurring interval (e.g. `/loop 5m check the deploy`) — v2.1.71+ | Automation | | `/mcp` | Manage Model Context Protocol servers | Config | | `/memory` | View and edit auto-memory (context Claude automatically saved across sessions via MEMORY.md) — v2.1.59+ | Config | | `/mobile` | Show App Store and Google Play download links | Info | @@ -20774,6 +20811,22 @@ _Quick jump:_ [Commands Table](#101-commands-table) · [Keyboard Shortcuts](#102 | `Alt+T` (`Option+T` on macOS) | Toggle thinking mode on/off | | `Ctrl+O` | View thinking blocks | +### Voice Input + +| Shortcut | Action | +|----------|--------| +| `Space` (hold) | Push-to-talk — hold to speak, release to send (default binding) | + +**Rebinding**: The `voice:pushToTalk` binding is configurable in `~/.claude/keybindings.json` (v2.1.71+). Add a custom binding if Space conflicts with your workflow: + +```json +{ + "voice:pushToTalk": "ctrl+space" +} +``` + +Toggle voice on/off with `/voice`. The push-to-talk binding only activates when voice mode is active. + ### Agent Teams Navigation | Shortcut | Action | diff --git a/guide/workflows/README.md b/guide/workflows/README.md index c5337a2..7aef374 100644 --- a/guide/workflows/README.md +++ b/guide/workflows/README.md @@ -113,6 +113,46 @@ Systematically explore and understand unfamiliar codebases. --- +## Multi-Agent & Advanced + +### [Agent Teams](./agent-teams.md) + +Orchestrate multiple specialized agents working in parallel on complex tasks. + +**When to use**: Tasks that benefit from parallelism, specialized expertise, or independent verification + +### [Agent Teams Quick Start](./agent-teams-quick-start.md) + +Fast-track guide to setting up your first agent team in under 30 minutes. + +**When to use**: New to multi-agent patterns, want to experiment before committing to full setup + +### [Dual-Instance Planning](./dual-instance-planning.md) + +Run Opus for planning and Sonnet for execution in two coordinated Claude Code instances. + +**When to use**: Complex features needing deep reasoning for architecture, cost-effective execution + +### [Event-Driven Agents](./event-driven-agents.md) + +Coordinate agents through hook events rather than direct orchestration. + +**When to use**: Reactive workflows, hook-triggered automation, loosely-coupled agent pipelines + +### [Plan Pipeline](./plan-pipeline.md) + +Full end-to-end plan pipeline: /plan-start, /plan-validate, /plan-execute as a coherent workflow. + +**When to use**: Any significant feature where planning rigor pays off before writing code + +### [Task Management](./task-management.md) + +Multi-session task tracking with TodoWrite, tasks API, and context persistence across sessions. + +**When to use**: Long-running tasks spanning multiple sessions, team coordination, complex backlogs + +--- + ## Quick Selection Guide | Your Situation | Recommended Workflow | @@ -128,6 +168,12 @@ Systematically explore and understand unfamiliar codebases. | **Documentation** | [PDF Generation](./pdf-generation.md) | | **Conference talk from raw material** | [Talk Preparation Pipeline](./talk-pipeline.md) | | **Audio feedback** | [TTS Setup](./tts-setup.md) | +| **Multi-agent tasks** | [Agent Teams](./agent-teams.md) | +| **First agent team** | [Agent Teams Quick Start](./agent-teams-quick-start.md) | +| **Cost-optimized planning** | [Dual-Instance Planning](./dual-instance-planning.md) | +| **Hook-driven automation** | [Event-Driven Agents](./event-driven-agents.md) | +| **Full plan workflow** | [Plan Pipeline](./plan-pipeline.md) | +| **Multi-session tracking** | [Task Management](./task-management.md) | --- @@ -146,4 +192,4 @@ New workflow ideas? Open an issue or PR in the main repository. --- -**Last updated**: February 2026 +**Last updated**: March 2026 diff --git a/machine-readable/reference.yaml b/machine-readable/reference.yaml index 5551377..ab7608f 100644 --- a/machine-readable/reference.yaml +++ b/machine-readable/reference.yaml @@ -168,6 +168,7 @@ deep_dive: trust_calibration_maintainability_nuance: "guide/ultimate-guide.md:1097" # Nuance: defect rates ≠ maintenance burden (Borg et al. 2025) session_naming_template: "examples/claude-md/session-naming.md" session_naming_guide: "guide/ultimate-guide.md:815" + session_auto_rename: 859 learning_mode_template: "examples/claude-md/learning-mode.md" learn_quiz_command: "examples/commands/learn/quiz.md" learn_teach_command: "examples/commands/learn/teach.md" @@ -451,6 +452,8 @@ deep_dive: agent_template: 5636 agent_examples: 5836 skills: 6246 + skills_taxonomy: 6718 + skills_evals: 6954 skill_template: 6384 skill_examples: 6452 design_patterns_skill: 6630 @@ -964,10 +967,10 @@ deep_dive: myths_tasks_api_autonomous: 20965 myths_100x_faster: 20997 myths_reliable_sources: 20983 - # Quiz System (264 questions, 15 categories) + # Quiz System (271 questions, 15 categories) quiz_overview: "quiz/README.md" quiz_file: "quiz/questions.json" - quiz_count: 264 + quiz_count: 271 quiz_categories: 15 quiz_beginner: "quiz/categories/basics,commands,shortcuts,reference" quiz_beginner_count: 60 @@ -1346,7 +1349,7 @@ rules: ecosystem: this_guide: focus: "Education - Learn & master" - unique: ["architecture docs", "TDD/SDD methodologies", "264-question quiz", "YAML index", "MCP server"] + unique: ["architecture docs", "TDD/SDD methodologies", "271-question quiz", "YAML index", "MCP server"] mcp_server: npm: "claude-code-ultimate-guide-mcp" install: "npx -y claude-code-ultimate-guide-mcp" @@ -1470,7 +1473,7 @@ ecosystem: local: "/Users/florianbruniaux/Sites/perso/claude-code-ultimate-guide-landing/" purpose: "Marketing site for Claude Code guide" audience: "Developers discovering the guide" - features: ["badges (version, templates, lines)", "quiz (264 questions)", "FAQ", "cross-links to Cowork"] + features: ["badges (version, templates, lines)", "quiz (271 questions)", "FAQ", "cross-links to Cowork"] sync_with: "Guide Code (version, templates count, guide lines)" cowork_landing: local: "/Users/florianbruniaux/Sites/perso/claude-cowork-guide-landing/" @@ -1494,10 +1497,13 @@ ecosystem: # ONBOARDING MATRIX METADATA # ════════════════════════════════════════════════════════════════ onboarding_matrix_meta: - version: "2.0.0" - last_updated: "2026-02-05" + version: "2.1.0" + last_updated: "2026-03-09" aligned_with_guide: "3.32.2" changelog: + - version: "2.1.0" + date: "2026-03-09" + changes: "Quiz count 264→271, skills_taxonomy/skills_evals/session_auto_rename deep_dive keys, plan_pipeline adaptive triggers in build_agents+learn_everything, v3.21-3.32 version refs updated" - version: "2.0.0" date: "2026-02-05" changes: "Adaptive architecture (core+adaptive topics), v3.21-3.22 coverage (git_mcp, sandbox_native, config_hierarchy, mcp_secrets, dual_instance), security-first (sandbox in beginner_5min), time budgets validated, learn_security goal added" @@ -1516,7 +1522,7 @@ onboarding_matrix_meta: # ════════════════════════════════════════════════════════════════ onboarding_matrix: # Adaptive architecture: Each profile has core (always) + adaptive (context-based) topics - # Adaptive triggers: keywords in user messages → relevant v3.21-3.22 topics + # Adaptive triggers: keywords in user messages → relevant v3.21-3.32 topics # Time budgets: Validated (6-8 min/topic average, respects topics_max limits) get_started: @@ -1568,7 +1574,7 @@ onboarding_matrix: - default: batch_operations time_budget: "30 min" topics_max: 4 - note: "Adaptive: picks up to 2 from adaptive based on user context (v3.21-3.22)" + note: "Adaptive: picks up to 2 from adaptive based on user context (v3.21-3.32)" power_60min: core: [context_triage, cost_optimization, config_hierarchy] @@ -1579,10 +1585,12 @@ onboarding_matrix: topics: [mcp_secrets_management] - trigger: "security|sandbox|isolation" topics: [sandbox_native_guide] + - trigger: "plan|pipeline" + topics: [plan_pipeline_workflow] - default: [batch_operations, rtk_guide] time_budget: "60 min" topics_max: 7 - note: "Comprehensive optimization with all v3.21-3.22 topics" + note: "Comprehensive optimization with all v3.21-3.32 topics" build_agents: intermediate_30min: @@ -1606,6 +1614,8 @@ onboarding_matrix: topics: [dual_instance_planning] - trigger: "validation|checklist|production|deploy" topics: [agent_validation_checklist] + - trigger: "plan|pipeline|validate|execute" + topics: [plan_pipeline_workflow] - default: agent_validation_checklist time_budget: "60 min" topics_max: 6 @@ -1651,17 +1661,19 @@ onboarding_matrix: core: [plan_mode, agents, skills, config_hierarchy, git_mcp_guide, hooks, mcp_servers] time_budget: "120 min" topics_max: 7 - note: "Agents + v3.21-3.22 topics (config/git)" + note: "Agents + v3.21-3.32 topics (config/git)" power_120min: core: [architecture, dual_instance_planning, mcp_secrets_management, cost_optimization, cicd] adaptive: - trigger: "security" topics: [security_hardening, sandbox_native_guide] + - trigger: "plan|pipeline|validate|execute" + topics: [plan_pipeline_workflow] - default: [rtk_guide, bridge_guide] time_budget: "120 min" topics_max: 9 - note: "Advanced patterns + all v3.21-3.22 features" + note: "Advanced patterns + all v3.21-3.32 features" # ════════════════════════════════════════════════════════════════ # ONBOARDING QUESTIONS - Structure for interactive profiling diff --git a/tools/audit-prompt.md b/tools/audit-prompt.md index c551b66..a62e1a7 100644 --- a/tools/audit-prompt.md +++ b/tools/audit-prompt.md @@ -53,7 +53,7 @@ cd your-project-directory claude ``` -> **Note**: With Opus 4.5, thinking mode is enabled by default at maximum depth. Use Alt+T to toggle if needed. +> **Note**: With Opus 4.6, thinking mode is enabled by default at maximum depth. Use Alt+T to toggle if needed. ### Step 3: Paste and Execute @@ -308,7 +308,7 @@ For each category, evaluate against these criteria based on Phase 1 scan results - [ ] Other relevant MCPs for the project needs **Thinking Mode & Trinity (Guide Section 9.1)** -- [ ] Understanding of thinking mode (enabled by default in Opus 4.5, Alt+T to toggle) +- [ ] Understanding of thinking mode (enabled by default in Opus 4.6, Alt+T to toggle) - [ ] Trinity pattern documented for complex workflows **CI/CD Integration (Guide Section 9.3)** @@ -345,6 +345,26 @@ For each category, evaluate against these criteria based on Phase 1 scan results - [ ] Finding domain experts via git history - [ ] Understanding code evolution patterns +**Rules Templates (Guide Section 3.2)** +- [ ] `.claude/rules/` directory exists with auto-loaded rule files +- [ ] Rules cover relevant domains (architecture, code quality, testing) +- [ ] Rules are concise and actionable (not duplicating CLAUDE.md content) + +**Sandbox & Permissions (Guide Section 1.4)** +- [ ] Understanding of sandbox modes (Docker container vs native process-level) +- [ ] Permission modes configured appropriately for the project +- [ ] Sensitive file patterns blocked via `permissions.deny` (`.env*`, `*.pem`, `credentials*`) + +**Security Commands (Guide: security-hardening.md)** +- [ ] `/security-check` available for quick config scans (~30s) +- [ ] `/security-audit` available for comprehensive audits (2-5min, scored /100) +- [ ] Awareness of threat database (`threat-db.yaml`) for known attack patterns + +**Plan-Validate-Execute Pipeline (Guide: workflows/plan-pipeline.md)** +- [ ] Awareness of pipeline workflow for complex features (power users) +- [ ] `/plan-start`, `/plan-validate`, `/plan-execute` commands installed if applicable +- [ ] ADR learning loop understood for accumulating architectural decisions + #### 2.2 Calculate Health Score **Formula**: `Score = (earned_points / max_points) × 100` @@ -395,20 +415,23 @@ For each ❌ or ⚠️ item, provide: Instead of reading the entire guide, use these line ranges for targeted extraction: ```bash -# Memory Files best practices -sed -n '2184,2314p' guide/ultimate-guide.md +# Line numbers from reference.yaml (deep_dive keys) — verify with: +# grep "memory_files\|hooks\|mcp_servers\|context_management\|plan_mode" machine-readable/reference.yaml -# Hooks section -sed -n '3962,4528p' guide/ultimate-guide.md +# Memory Files best practices (deep_dive: memory_files) +sed -n '3054,3254p' guide/ultimate-guide.md -# MCP Servers section -sed -n '4529,5076p' guide/ultimate-guide.md +# Hooks section (deep_dive: hooks) +sed -n '8300,8800p' guide/ultimate-guide.md -# Context Management -sed -n '910,1423p' guide/ultimate-guide.md +# MCP Servers section (deep_dive: mcp_servers) +sed -n '9500,10000p' guide/ultimate-guide.md -# Plan Mode -sed -n '1424,1601p' guide/ultimate-guide.md +# Context Management (deep_dive: context_management) +sed -n '1000,1500p' guide/ultimate-guide.md + +# Plan Mode (deep_dive: plan_mode) +sed -n '1500,1700p' guide/ultimate-guide.md ``` **Suggested Templates**: @@ -509,12 +532,16 @@ Here's an example of what the audit report looks like: | **PreToolUse** | Hook that runs BEFORE Claude executes a tool - great for security checks | | **PostToolUse** | Hook that runs AFTER Claude executes a tool - great for formatting | | **Plan Mode** | Read-only exploration mode for safe analysis before making changes | -| **Thinking Mode** | Extended thinking (Opus 4.5: ON by default). Toggle with Alt+T, configure in /config | +| **Thinking Mode** | Extended thinking (Opus 4.6: ON by default). Toggle with Alt+T, configure in /config | | **Trinity Pattern** | Combining Plan Mode + Extended Thinking + MCP for complex tasks | | **Verify Gate** | CI/CD pattern: build → lint → test → typecheck before merge | -| **Context Zones** | Green (0-50%), Yellow (50-70%), Red (70%+) - context usage thresholds | +| **Context Zones** | < 70% optimal, 75% auto-compact trigger, 85% handoff recommended, 95% force handoff | | **Data Retention** | Anthropic stores conversations: 5 years (default), 30 days (opt-out), 0 days (Enterprise ZDR) | | **permissions.deny** | Settings to block Claude from reading sensitive files like `.env`, credentials | +| **Rules** | Auto-loaded `.claude/rules/*.md` files providing contextual instructions every session | +| **Permission Modes** | Trust levels for Claude's tool access: default deny, allowlist, or prompt-on-use | +| **Sandbox** | OS-level isolation (Docker container or native process-level). Toggle with `/sandbox` | +| **Plugins** | Community extensions installable via `/install-plugin owner/repo` | ### Priority Levels Explained @@ -585,4 +612,4 @@ Here's an example of what the audit report looks like: --- -*Last updated: January 2026 | Version 2.9 - Fixed MCP detection (now checks ~/.claude.json)* +*Last updated: March 2026 | Version 3.0 - Updated for guide v3.32.2 (Opus 4.6, new checklist categories, glossary, context zones)* diff --git a/tools/onboarding-prompt.md b/tools/onboarding-prompt.md index 053a914..f77d065 100644 --- a/tools/onboarding-prompt.md +++ b/tools/onboarding-prompt.md @@ -28,10 +28,10 @@ This prompt instructs Claude to become your personal onboarding coach by: | Goal | What You'll Get | |------|-----------------| -| **Get started** | Golden Rules + essential commands + first workflow | -| **Optimize** | Context management + Plan Mode + cost optimization | -| **Build agents** | Agent/Skill/Command templates + hooks | -| **Learn security** | Threat landscape + MCP vetting + scanning tools + hardening | +| **Get started** | Golden Rules + sandbox modes + essential commands + first workflow | +| **Optimize** | Context management + Plan Mode + cost optimization + Plan-Validate-Execute pipeline | +| **Build agents** | Agent/Skill/Command templates + Skills 2.0 taxonomy + hooks | +| **Learn security** | Sandbox modes + permission hardening + MCP vetting + scanning tools + threat DB | | **Fix a problem** | Direct jump to troubleshooting | | **Learn everything** | Complete guided tour | @@ -108,16 +108,21 @@ https://raw.githubusercontent.com/FlorianBruniaux/claude-code-ultimate-guide/mai **Adaptive topic selection (when reference.yaml loads successfully):** -The onboarding matrix uses **adaptive architecture** (v2.0.0, guide v3.23.0+): +The onboarding matrix uses **adaptive architecture** (v2.1.0, guide v3.32.2+): - Each profile has **core topics** (always shown) + **adaptive topics** (context-based) -- Claude analyzes user's initial messages for trigger keywords to surface relevant v3.21-3.22 content +- Claude analyzes user's initial messages for trigger keywords to surface relevant v3.21-3.32 content - Keyword examples: - "team", "sync", "backup", "multi-machine" → `config_hierarchy` (backup/sync strategies) - "git", "version control", "commits" → `git_mcp_guide` (official Git MCP server) - "secrets", "API keys", "credentials" → `mcp_secrets_management` (secrets handling) - "quality", "review", "planner", "dual" → `dual_instance_planning` (planner/implementer pattern) - "security", "sandbox", "isolation" → `sandbox_native_guide` or `security_hardening` -- Ensures v3.21-3.22 features surface based on **relevance**, not just chronology + - "permission", "allow", "deny" → `permission_modes` + - "memory", "persist", "session" → `memory_files` + - "template", "structure", "format" → `skill_template` + - "validation", "checklist", "deploy" → `agent_validation_checklist` + - "plan", "pipeline" → `plan_pipeline_workflow` (Plan-Validate-Execute) +- Ensures v3.21-3.32 features surface based on **relevance**, not just chronology - Respects time budgets (max 4-7 topics per profile, validated 6-8 min/topic) **Fallback if fetch fails:** @@ -127,7 +132,7 @@ If you cannot fetch the reference.yaml: - `get_started`: rules → sandbox_native_guide → commands - `optimize`: context_management → plan_mode → cost_optimization - `build_agents`: agents → skills → hooks - - `learn_security`: sandbox_native_guide → mcp_secrets_management → security_hardening + - `learn_security`: sandbox_native_guide → permission_modes → mcp_secrets_management → security_hardening - `fix_problem`: troubleshooting checklist 3. Continue with Phase 1.5 questions as normal. @@ -156,6 +161,7 @@ Based on the goal from Phase 0, ask ONLY the necessary additional questions: - ⏱️ 15-30 min - 🎯 30-60 min - 📚 1+ hour +- 📖 2+ hours **Style question** (if time >= 15min) - Use AskUserQuestion with options: - 📖 Explanations (tell me why) @@ -247,13 +253,13 @@ Based on time spent and topics covered: - `fix_problem` → "Run `claude doctor` if issues persist" 3. **Next steps**: Point to relevant resources with clickable URLs: - - **Quiz (RECOMMENDED)** - Validate what you learned (274 questions total, 15 categories): - - Beginner (5min/15min/30min profiles): [Quiz - Basics (60 questions, ~15 min)](https://github.com/FlorianBruniaux/claude-code-ultimate-guide/tree/main/quiz#beginner-categories) - Categories: basics, commands, shortcuts, reference - - Intermediate (15min/30min profiles): [Quiz - Workflows (100 questions, ~25 min)](https://github.com/FlorianBruniaux/claude-code-ultimate-guide/tree/main/quiz#intermediate-categories) - Categories: workflows, context, agents, hooks - - Advanced/Power (30min/60min/120min profiles): [Quiz - Production (97 questions, ~30 min)](https://github.com/FlorianBruniaux/claude-code-ultimate-guide/tree/main/quiz#advanced-categories) - Categories: MCP, production, advanced, learning, ecosystem - - Security-focused: [Quiz - Security Hardening (30 questions)](https://github.com/FlorianBruniaux/claude-code-ultimate-guide-landing/tree/main/questions/13-security-hardening) - Attack techniques, CVEs, campaigns, scanning tools + - **Quiz (RECOMMENDED)** - Validate what you learned (271 questions, 15 categories): + - Beginner (5min/15min/30min profiles): [Quiz - Basics](https://github.com/FlorianBruniaux/claude-code-ultimate-guide/tree/main/quiz#beginner-categories) - Categories: basics, commands, shortcuts, reference + - Intermediate (15min/30min profiles): [Quiz - Workflows](https://github.com/FlorianBruniaux/claude-code-ultimate-guide/tree/main/quiz#intermediate-categories) - Categories: workflows, context, agents, hooks + - Advanced/Power (30min/60min/120min profiles): [Quiz - Production](https://github.com/FlorianBruniaux/claude-code-ultimate-guide/tree/main/quiz#advanced-categories) - Categories: MCP, production, advanced, learning, ecosystem + - Security-focused: [Quiz - Security Hardening](https://github.com/FlorianBruniaux/claude-code-ultimate-guide-landing/tree/main/questions/13-security-hardening) - Attack techniques, CVEs, campaigns, scanning tools - Cheat sheet: [Printable cheatsheet](https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/cheatsheet.md) - - Full guide: [Ultimate Guide (11K+ lines)](https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md) + - Full guide: [Ultimate Guide (22K+ lines)](https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md) 4. **Section-specific links**: When referencing specific sections, use GitHub line anchors: - Format: `https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#L{line_number}` @@ -301,14 +307,14 @@ Begin by asking about preferred language. 2. Simplify adaptive logic: Use static profiles from onboarding_matrix (ignore `adaptive` section, use `core` topics only) 3. Manually paste reference.yaml content if WebFetch fails (or use fallback roadmap) -**Localization status (v3.23.0):** +**Localization status (v3.32.2):** - Core guide content: **English only** -- v3.21-3.22 topics: **English only** (dual_instance, git_mcp, sandbox_native, config_hierarchy, mcp_secrets) +- v3.21-3.32 topics: **English only** (dual_instance, git_mcp, sandbox_native, config_hierarchy, mcp_secrets, plan_pipeline) - French/Spanish onboarding: Claude translates on-the-fly from English sections - **Limitation**: Translations not verified by native speakers, may have inaccuracies or awkward phrasing -- Quiz: English only (274 questions) +- Quiz: English only (271 questions) -**If translation quality is critical**: Recommend English onboarding for best accuracy, especially for technical v3.21-3.22 content. +**If translation quality is critical**: Recommend English onboarding for best accuracy, especially for technical v3.21-3.32 content. ``` ---