Florian BRUNIAUX
b65630641b
refactor(guide): restructure guide/ into thematic subdirectories
...
Reorganize 22 guide files from a flat directory into 5 thematic subdirs:
- core/ (architecture, methodologies, known-issues, claude-code-releases, visual-reference)
- security/ (security-hardening, sandbox-isolation, sandbox-native, production-safety, data-privacy)
- ecosystem/ (ai-ecosystem, mcp-servers-ecosystem, third-party-tools, remarkable-ai)
- roles/ (ai-roles, adoption-approaches, learning-with-ai, agent-evaluation)
- ops/ (devops-sre, observability, ai-traceability)
All internal links updated across ~50 files (ultimate-guide.md, workflows/,
diagrams/, README.md, docs/, tools/, examples/, machine-readable/).
Also: merge search-tools-cheatsheet.md into cheatsheet.md, rewrite guide/README.md
with H2 grouped sections, update CLAUDE.md repository structure.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-03-10 08:35:13 +01:00
Florian BRUNIAUX
4a0a0bf30e
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>
2026-02-26 18:21:28 +01:00
Florian BRUNIAUX
191ff42741
release: v3.23.4 - Agent Anti-Patterns & Scope-Focused Refactoring
...
Major conceptual refactoring based on Dex Horty's principle:
"Subagents are not for anthropomorphizing roles, they are for controlling context"
### Added (1 new section)
- Agent Anti-Patterns section (§9.17, line 3662)
- Wrong vs Right table (anthropomorphizing vs context control)
- When to use agents (context isolation, parallel processing, scope limitation)
- When NOT to use agents (fake teams, roleplaying, mimicking org structure)
### Changed (18 files, 200+ lines)
- Section rename: "Split-Role Sub-Agents" → "Scope-Focused Agents"
- Agent definitions: "Specialized role" → "Context isolation tool"
- 8 custom agent examples refactored (guide + examples/agents/)
- 10+ prompt examples with explicit scope boundaries
- 4 workflow files updated (agent-teams, TDD, iterative refinement)
- Terminology replacements:
* "Specialized agents" → "Scope-focused agents"
* "Expert personas" → "Context boundaries"
* "Multi-domain expertise" → "Multi-scope analysis"
### Fixed
- Methodologies: Clarification note for BMAD role-based naming
Breaking change: Conceptual shift from role-based to scope-based agent usage.
All examples now demonstrate context isolation instead of persona simulation.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-02-09 10:29:59 +01:00
