docs: complete factual audit pass 2 — 90+ corrections
Second 10-agent parallel audit covering all remaining sections:
ultimate-guide.md (ch1-ch11), workflows/ (17 files), quiz/ (12 files),
examples/agents+skills+commands. Source of truth: official Anthropic docs.
Key corrections:
Hook system (+8 missing events):
- Complete 17-event list: PermissionRequest, PostToolUseFailure, SubagentStart,
TeammateIdle, TaskCompleted, WorktreeCreate, WorktreeRemove, SessionEnd
- SessionStart confirmed valid (previous audit wrongly doubted it)
- Hook output format: hookSpecificOutput.permissionDecision (not {"decision":"block"})
- Missing common input fields added: transcript_path, cwd, permission_mode
Agent YAML frontmatter (13 valid fields restored/added):
- Restored: disallowedTools, memory, background, isolation, skills, permissionMode, hooks
- Added new: maxTurns, mcpServers
- Fixed: tools format is comma-separated (not space-separated)
Plan Mode (12 occurrences fixed):
- Ctrl+G = "open plan in text editor" (NOT "enter plan mode")
- Plan Mode = Shift+Tab × 2 (Normal → acceptEdits → plan)
Commands table (10.1) + built-in commands (6.1):
- Added 18+ missing commands: /copy, /doctor, /hooks, /memory, /model,
/config, /permissions, /remote-control, /rename, /resume, /sandbox, etc.
Workflow files:
- agent-teams.md: removed fake --experimental-agent-teams flag
- hooks.yaml + post_edit event → settings.json + PostToolUse (2 files)
- TodoWrite → TaskCreate/TaskUpdate (3 files)
- task-management.md: removed fake "failed" task status
Quiz / examples:
- 01-010: Esc stops mid-action (not Ctrl+C)
- refactoring-specialist.md: removed MultiEdit (not a valid tool)
- ast-grep-patterns.md: name field (not title)
- validate-changes.md, diagnose.md: field name fixes
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Florian BRUNIAUX
parent
8cb9f9efa6
commit
4a0a0bf30e
22 changed files with 365 additions and 322 deletions
|
|
@ -99,7 +99,7 @@ of agents to work in parallel on complex tasks using:
|
|||
3. Claude presents consolidated findings (convergence + unique insights)
|
||||
|
||||
**Navigation**:
|
||||
- `Shift+Up/Down`: See individual agent outputs
|
||||
- `Shift+Down`: Cycle through teammate outputs (in-process mode)
|
||||
- Main view: Consolidated synthesis
|
||||
|
||||
**Duration**: 1-2 min for simple 2-agent task.
|
||||
|
|
@ -370,7 +370,7 @@ claude
|
|||
> [FILES/DIRECTORIES TO ANALYZE]
|
||||
|
||||
# 4. Observe (optional)
|
||||
# Shift+Up/Down to see individual agent outputs
|
||||
# Shift+Down to cycle through teammate outputs (in-process mode)
|
||||
|
||||
# 5. Synthesis
|
||||
# Claude presents consolidated findings automatically
|
||||
|
|
|
|||
|
|
@ -214,17 +214,18 @@ Team Lead: "Review this PR for security issues"
|
|||
### Navigation Between Agents
|
||||
|
||||
**Built-in navigation**:
|
||||
- **Shift+Up/Down**: Switch between sub-agents in Claude Code interface
|
||||
- **tmux**: Use tmux commands if running in tmux session
|
||||
- **Shift+Down**: Cycle through teammates in in-process mode
|
||||
- **tmux/iTerm2**: Split pane mode with `teammateMode: "tmux"` (requires tmux or iTerm2 with `it2` CLI)
|
||||
- **Direct takeover**: You can take control of any agent's work when needed
|
||||
|
||||
**Example**:
|
||||
```bash
|
||||
# Terminal 1: Team lead
|
||||
claude --experimental-agent-teams
|
||||
# Terminal 1: Team lead (with env var set)
|
||||
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
|
||||
claude
|
||||
|
||||
# Claude spawns teammates automatically
|
||||
# You can navigate with Shift+Up/Down to inspect each agent
|
||||
# You can navigate with Shift+Down to cycle through teammates (in-process mode)
|
||||
```
|
||||
|
||||
### Context Management
|
||||
|
|
@ -286,8 +287,8 @@ source ~/.bashrc
|
|||
|
||||
```json
|
||||
{
|
||||
"experimental": {
|
||||
"agentTeams": true
|
||||
"env": {
|
||||
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
|
@ -311,9 +312,10 @@ source ~/.bashrc
|
|||
Claude should confirm:
|
||||
> "Yes, agent teams are enabled (experimental feature). I can spawn multiple agents to work in parallel when appropriate."
|
||||
|
||||
**Alternative verification** (check settings):
|
||||
**Alternative verification** (check env var):
|
||||
```bash
|
||||
cat ~/.claude/settings.json | grep agentTeams
|
||||
echo $CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS
|
||||
# Should output: 1
|
||||
```
|
||||
|
||||
### Multi-Terminal Setup
|
||||
|
|
@ -323,15 +325,15 @@ cat ~/.claude/settings.json | grep agentTeams
|
|||
```bash
|
||||
# Terminal 1: Research + bugfix
|
||||
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
|
||||
claude --session research-bugfix
|
||||
claude
|
||||
|
||||
# Terminal 2: Business ops
|
||||
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
|
||||
claude --session business-ops
|
||||
claude
|
||||
|
||||
# Terminal 3: Infrastructure
|
||||
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
|
||||
claude --session infra-setup
|
||||
claude
|
||||
```
|
||||
|
||||
**Benefits**:
|
||||
|
|
@ -772,7 +774,7 @@ With messaging (built-in):
|
|||
Mitigation:
|
||||
- Agents can message each other via mailbox system
|
||||
- Team lead synthesizes findings after all agents complete
|
||||
- Human can interrupt and redirect agents mid-workflow (Shift+Up/Down)
|
||||
- Human can interrupt and redirect agents mid-workflow (Shift+Down to cycle teammates)
|
||||
- Design tasks with minimal inter-agent dependencies
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -103,7 +103,7 @@ claude
|
|||
You are Claude Zero (Planner).
|
||||
|
||||
Your role:
|
||||
- Explore codebase using /plan mode
|
||||
- Explore codebase using Plan Mode (Shift+Tab twice)
|
||||
- Interview user about requirements
|
||||
- Write detailed plans to .claude/plans/Review/
|
||||
- Review implementations after Claude One completes them
|
||||
|
|
@ -150,7 +150,7 @@ Claude One confirms: "Understood. I am Claude One (Implementer). I execute appro
|
|||
|
||||
**You** (to Claude Zero):
|
||||
```
|
||||
/plan
|
||||
# Enter Plan Mode (Shift+Tab twice), then:
|
||||
|
||||
Implement JWT authentication for the API:
|
||||
- Access tokens (15min expiry)
|
||||
|
|
@ -161,7 +161,7 @@ Implement JWT authentication for the API:
|
|||
|
||||
#### Step 1.2: Claude Zero Explores
|
||||
|
||||
Claude Zero (in `/plan` mode):
|
||||
Claude Zero (in Plan Mode):
|
||||
- Reads existing auth code
|
||||
- Searches for auth patterns in codebase
|
||||
- Identifies dependencies (libraries, env vars)
|
||||
|
|
@ -660,7 +660,7 @@ Do not edit code. Write plan to .claude/plans/Review/
|
|||
# .claude/CLAUDE.md
|
||||
|
||||
## If you are Claude Zero (Planner):
|
||||
- Use /plan mode for all exploration
|
||||
- Use Plan Mode (Shift+Tab twice) for all exploration
|
||||
- Save all plans to .claude/plans/Review/[feature].md
|
||||
- NEVER edit code
|
||||
- NEVER commit changes
|
||||
|
|
|
|||
|
|
@ -157,12 +157,12 @@ Show your reasoning for each phase.
|
|||
|
||||
## Integration with Claude Code
|
||||
|
||||
### With /plan Mode
|
||||
### With Plan Mode
|
||||
|
||||
Exploration happens **before** `/plan`:
|
||||
Exploration happens **before** entering Plan Mode:
|
||||
|
||||
```
|
||||
# Step 1: Explore (no /plan yet)
|
||||
# Step 1: Explore (not in Plan Mode yet)
|
||||
I need to add caching to the API. What are my options?
|
||||
|
||||
# Claude responds with 4 approaches
|
||||
|
|
@ -170,8 +170,7 @@ I need to add caching to the API. What are my options?
|
|||
# Step 2: Choose
|
||||
Let's go with approach C (edge caching with Cloudflare).
|
||||
|
||||
# Step 3: Plan
|
||||
/plan
|
||||
# Step 3: Plan (press Shift+Tab twice to enter Plan Mode)
|
||||
Implement edge caching using Cloudflare Workers.
|
||||
Follow the patterns in our existing middleware.
|
||||
```
|
||||
|
|
@ -192,16 +191,16 @@ Use quantified comparison (1-10 scale) for:
|
|||
- Time to implement
|
||||
```
|
||||
|
||||
### With TodoWrite
|
||||
### With Task Tool
|
||||
|
||||
Track exploration as a task:
|
||||
Track exploration as tasks:
|
||||
|
||||
```
|
||||
TodoWrite:
|
||||
- [x] Explore caching approaches (4 options analyzed)
|
||||
- [x] Choose approach: edge caching with Cloudflare
|
||||
- [ ] Implement cache invalidation
|
||||
- [ ] Add cache headers to responses
|
||||
TaskCreate: "Explore caching approaches"
|
||||
TaskCreate: "Choose approach based on analysis"
|
||||
TaskCreate: "Implement cache invalidation"
|
||||
TaskCreate: "Add cache headers to responses"
|
||||
# Mark completed as you progress with TaskUpdate
|
||||
```
|
||||
|
||||
---
|
||||
|
|
|
|||
|
|
@ -148,30 +148,21 @@ Stop early if improvement < 5% between iterations.
|
|||
|
||||
## Integration with Claude Code
|
||||
|
||||
### With TodoWrite
|
||||
### With Task Tool
|
||||
|
||||
Track refinement iterations:
|
||||
Track refinement iterations using `TaskCreate` and `TaskUpdate`:
|
||||
|
||||
```
|
||||
TodoWrite:
|
||||
- [x] Initial implementation
|
||||
- [x] Fix: handle empty arrays
|
||||
- [x] Fix: add input validation
|
||||
- [ ] Optimization: memoize expensive calculations
|
||||
TaskCreate: "Implement initial version"
|
||||
TaskCreate: "Fix: handle empty arrays"
|
||||
TaskCreate: "Fix: add input validation"
|
||||
TaskCreate: "Optimization: memoize expensive calculations"
|
||||
# Mark completed as you progress with TaskUpdate
|
||||
```
|
||||
|
||||
### With Hooks
|
||||
|
||||
Auto-validate after each change:
|
||||
|
||||
```yaml
|
||||
# .claude/hooks.yaml
|
||||
post_edit:
|
||||
- command: "npm run lint && npm test"
|
||||
on_failure: "report"
|
||||
```
|
||||
|
||||
Claude sees failures and can self-correct.
|
||||
Auto-validate after each change using Claude Code hooks (configured via `/hooks` command or `settings.json`). For example, a `PostToolUse` hook on the `Edit` tool can run linting and tests automatically. Claude sees failures and can self-correct.
|
||||
|
||||
### With /compact
|
||||
|
||||
|
|
|
|||
|
|
@ -332,7 +332,7 @@ Create a Quarto extension for our company's document style:
|
|||
|
||||
For complex documents:
|
||||
```
|
||||
/plan
|
||||
[Press Shift+Tab to enter Plan Mode]
|
||||
|
||||
I need to create a series of 5 technical whitepapers.
|
||||
Plan the structure:
|
||||
|
|
@ -344,13 +344,20 @@ Plan the structure:
|
|||
|
||||
### With Hooks
|
||||
|
||||
Auto-generate PDF on save:
|
||||
Auto-generate PDF after edits using a PostToolUse hook:
|
||||
|
||||
```yaml
|
||||
# .claude/hooks.yaml
|
||||
post_edit:
|
||||
- pattern: "**/*.qmd"
|
||||
command: "quarto render $FILE"
|
||||
```json
|
||||
// In .claude/settings.json
|
||||
{
|
||||
"hooks": {
|
||||
"PostToolUse": [
|
||||
{
|
||||
"matcher": "Edit|Write",
|
||||
"command": "if echo \"$TOOL_INPUT\" | grep -q '.qmd'; then quarto render \"$FILE\"; fi"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
|
|
|||
|
|
@ -28,7 +28,7 @@ Use `/plan` mode for anything non-trivial. Claude explores the codebase (read-on
|
|||
## TL;DR
|
||||
|
||||
```
|
||||
1. /plan (or ask complex question)
|
||||
1. Enter Plan Mode (Shift+Tab twice) or ask complex question
|
||||
2. Claude explores codebase (read-only)
|
||||
3. Claude writes plan to .claude/plans/
|
||||
4. You review and approve
|
||||
|
|
@ -41,9 +41,10 @@ Use `/plan` mode for anything non-trivial. Claude explores the codebase (read-on
|
|||
|
||||
### Step 1: Enter Plan Mode
|
||||
|
||||
Either use the slash command:
|
||||
Toggle Plan Mode with `Shift+Tab` (press twice to cycle Normal → Auto-Accept → Plan):
|
||||
```
|
||||
/plan
|
||||
# Press Shift+Tab twice to enter Plan Mode
|
||||
# (Plan Mode indicator appears in the UI)
|
||||
```
|
||||
|
||||
Or ask a complex question that triggers plan mode automatically:
|
||||
|
|
@ -177,7 +178,7 @@ Plans are stored in `.claude/plans/` with auto-generated names.
|
|||
### Plan + TDD
|
||||
|
||||
```
|
||||
/plan
|
||||
# Enter Plan Mode (Shift+Tab twice), then:
|
||||
|
||||
I need to implement a rate limiter.
|
||||
Plan the test cases first, then the implementation.
|
||||
|
|
@ -188,18 +189,18 @@ Claude plans both tests and implementation in proper TDD order.
|
|||
### Plan + Spec-First
|
||||
|
||||
```
|
||||
/plan
|
||||
# Enter Plan Mode (Shift+Tab twice), then:
|
||||
|
||||
Review the Payment Processing spec in CLAUDE.md.
|
||||
Create an implementation plan that satisfies all acceptance criteria.
|
||||
```
|
||||
|
||||
### Plan + TodoWrite
|
||||
### Plan + Task Tool
|
||||
|
||||
After plan approval, Claude can break down into todos:
|
||||
After plan approval, Claude can break down into tasks:
|
||||
|
||||
```
|
||||
Approved. Create a todo list from this plan and start implementing.
|
||||
Approved. Create tasks from this plan and start implementing.
|
||||
```
|
||||
|
||||
---
|
||||
|
|
@ -209,12 +210,10 @@ Approved. Create a todo list from this plan and start implementing.
|
|||
### Be Specific About Scope
|
||||
|
||||
```
|
||||
# Too vague
|
||||
/plan
|
||||
# Too vague (after entering Plan Mode via Shift+Tab twice)
|
||||
Improve the API
|
||||
|
||||
# Better
|
||||
/plan
|
||||
Add pagination to the /users endpoint with cursor-based navigation.
|
||||
Maintain backwards compatibility with existing clients.
|
||||
```
|
||||
|
|
@ -231,7 +230,7 @@ The plan looks good but:
|
|||
### Use for Architecture Decisions
|
||||
|
||||
```
|
||||
/plan
|
||||
# Enter Plan Mode (Shift+Tab twice), then:
|
||||
|
||||
I'm considering two approaches for state management:
|
||||
A) Redux Toolkit
|
||||
|
|
@ -254,11 +253,11 @@ Plans in `.claude/plans/` serve as decision documentation:
|
|||
> **Source**: Boris Tane, Engineering Lead @ Cloudflare — ["How I use Claude Code"](https://boristane.com/blog/how-i-use-claude-code/) (Feb 2026). 9 months of production usage.
|
||||
> **Confidence**: Tier 2 — Practitioner-validated pattern, not official Anthropic documentation.
|
||||
|
||||
When `/plan` isn't enough — iterative human/agent planning before any code is written.
|
||||
When Plan Mode isn't enough, iterative human/agent planning before any code is written.
|
||||
|
||||
### Why Custom Plans Over /plan
|
||||
|
||||
| Factor | /plan (native) | Custom .md plan |
|
||||
| Factor | Plan Mode (native) | Custom .md plan |
|
||||
|--------|----------------|-----------------|
|
||||
| **Persistence** | Lost on context compaction | Survives compaction, shareable |
|
||||
| **Review surface** | Chat-based, linear | Structured file, diffs |
|
||||
|
|
@ -266,7 +265,7 @@ When `/plan` isn't enough — iterative human/agent planning before any code is
|
|||
| **Shared state** | Per-session | "Shared mutable state" between human and agent |
|
||||
| **Best for** | Standard features, <30 min tasks | Complex features, architectural decisions |
|
||||
|
||||
**Decision rule**: Use `/plan` for known scope. Use custom `.md` plans when you expect misunderstandings or want explicit sign-off on approach before a single line of code.
|
||||
**Decision rule**: Use Plan Mode (Shift+Tab twice) for known scope. Use custom `.md` plans when you expect misunderstandings or want explicit sign-off on approach before a single line of code.
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -121,7 +121,7 @@ Follow the skeleton's existing patterns for:
|
|||
- Test structure (match the example test pattern)
|
||||
- Error handling (match the existing error pattern)
|
||||
|
||||
Create a TodoWrite plan before starting implementation.
|
||||
Create a task plan before starting implementation.
|
||||
```
|
||||
|
||||
**Step 7: Validate skeleton integrity**
|
||||
|
|
|
|||
|
|
@ -284,10 +284,10 @@ openspec init
|
|||
/openspec:archive add-dark-mode # Merge to specs
|
||||
```
|
||||
|
||||
### With /plan Mode
|
||||
### With Plan Mode
|
||||
|
||||
```
|
||||
/plan
|
||||
[Press Shift+Tab to enter Plan Mode]
|
||||
|
||||
I need to implement the Payment Processing feature.
|
||||
Review the spec in CLAUDE.md and create an implementation plan.
|
||||
|
|
@ -501,14 +501,15 @@ Traditional specs use binary constraints (MUST/MUST NOT), but operational work r
|
|||
|
||||
### Mapping to Claude Code Permissions
|
||||
|
||||
**Always → Auto-accept Mode** (Shift+Tab):
|
||||
**Always → Permission Allowlist**:
|
||||
```json
|
||||
// In .claude/settings.json
|
||||
{
|
||||
"allowedPrompts": {
|
||||
"Bash": [
|
||||
"run tests",
|
||||
"format code",
|
||||
"check types"
|
||||
"permissions": {
|
||||
"allow": [
|
||||
"Bash(npm test*)",
|
||||
"Bash(npx prettier*)",
|
||||
"Bash(npx tsc*)"
|
||||
]
|
||||
}
|
||||
}
|
||||
|
|
@ -520,11 +521,11 @@ Traditional specs use binary constraints (MUST/MUST NOT), but operational work r
|
|||
|
||||
**Never → Plan Mode + Hooks**:
|
||||
```bash
|
||||
# .claude/hooks/pre-tool-use.sh
|
||||
# Hook configured via settings.json (PreToolUse event)
|
||||
#!/bin/bash
|
||||
if [[ "$TOOL_USE_TOOL_NAME" == "Bash" ]] && [[ "$TOOL_USE_INPUT" =~ "git push origin main" ]]; then
|
||||
echo "ERROR: Direct push to main blocked. Use feature branches."
|
||||
exit 2 # Block the action
|
||||
if [[ "$TOOL_NAME" == "Bash" ]] && [[ "$INPUT" =~ "git push origin main" ]]; then
|
||||
echo "BLOCKED: Direct push to main blocked. Use feature branches."
|
||||
exit 2 # Send feedback to Claude (non-zero exit blocks the action)
|
||||
fi
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -35,7 +35,7 @@ Task management in Claude Code evolved significantly in v2.1.16 with the introdu
|
|||
| **Multi-session** | ❌ Lost on session end | ✅ Survives across sessions |
|
||||
| **Dependencies** | ❌ Manual ordering | ✅ Task blocking (A blocks B) |
|
||||
| **Coordination** | Single agent | ✅ Multi-agent with broadcast |
|
||||
| **Status tracking** | pending/in_progress/completed | pending/in_progress/completed/failed |
|
||||
| **Status tracking** | pending/in_progress/completed | pending/in_progress/completed |
|
||||
| **When to use** | Simple single-session todos | Complex multi-session projects |
|
||||
|
||||
**Migration flag** (v2.1.19+):
|
||||
|
|
@ -207,7 +207,7 @@ Tasks for 'auth-system-v2':
|
|||
# ✅ Task remains completed
|
||||
|
||||
# If tests fail:
|
||||
> "TaskUpdate task-refresh status=failed, add error details to metadata"
|
||||
> "TaskUpdate task-refresh status=in_progress, add error details to metadata and fix issues"
|
||||
```
|
||||
|
||||
---
|
||||
|
|
@ -373,7 +373,7 @@ Convert strategic plans into executable task hierarchies.
|
|||
```bash
|
||||
# Step 1: Enter plan mode
|
||||
claude
|
||||
> "Shift+Tab×2" # Enter plan mode
|
||||
> [Press Shift+Tab to enter Plan Mode]
|
||||
|
||||
# Step 2: Create architectural plan
|
||||
> "Design architecture for microservices migration:
|
||||
|
|
@ -659,7 +659,7 @@ TaskUpdate: {id: "login-feature", status: "completed"}
|
|||
# If tests pass:
|
||||
TaskUpdate: {id: "login-feature", status: "completed", metadata: {test_results: "pass"}}
|
||||
# If tests fail:
|
||||
TaskUpdate: {id: "login-feature", status: "failed", metadata: {test_results: "3 failures", error_log: "..."}}
|
||||
TaskUpdate: {id: "login-feature", status: "in_progress", metadata: {test_results: "3 failures", error_log: "..."}}
|
||||
```
|
||||
|
||||
---
|
||||
|
|
|
|||
|
|
@ -161,30 +161,35 @@ Claude creates todos:
|
|||
- [ ] REFACTOR: Clean up
|
||||
```
|
||||
|
||||
### With /plan Mode
|
||||
### With Plan Mode
|
||||
|
||||
Use planning for test strategy:
|
||||
|
||||
```
|
||||
/plan
|
||||
[Press Shift+Tab to enter Plan Mode]
|
||||
|
||||
I need to implement a shopping cart with TDD.
|
||||
Plan the test cases before we start writing any code.
|
||||
```
|
||||
|
||||
Claude will explore codebase, then propose test plan before any implementation.
|
||||
Claude will explore codebase in read-only mode, then propose test plan before any implementation.
|
||||
|
||||
### With Hooks
|
||||
|
||||
Auto-run tests on file changes:
|
||||
Auto-run tests after edits using a PostToolUse hook:
|
||||
|
||||
```yaml
|
||||
# .claude/hooks.yaml
|
||||
post_edit:
|
||||
- pattern: "**/*.test.ts"
|
||||
command: "npm test -- --testPathPattern=$FILE"
|
||||
- pattern: "**/*.ts"
|
||||
command: "npm test --watchAll=false"
|
||||
```json
|
||||
// In .claude/settings.json
|
||||
{
|
||||
"hooks": {
|
||||
"PostToolUse": [
|
||||
{
|
||||
"matcher": "Edit|Write",
|
||||
"command": "npm test --watchAll=false 2>&1 | head -20"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### With Sub-Agents
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue