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
6d847d24de
docs: add Profile-Based Module Assembly pattern (Section 3.5)
...
- Section 3.5 "Team Configuration at Scale" in ultimate-guide.md:
profiles YAML + shared modules + skeleton + assembler script;
59% context token reduction measured on 5-dev production team;
includes CI drift detection, 5-step replication guide, trade-offs
- New workflow: guide/workflows/team-ai-instructions.md (6 phases,
scaling thresholds, troubleshooting table)
- New templates: examples/team-config/ (profile-template.yaml,
claude-skeleton.md, sync-script.ts)
- reference.yaml: 9 new entries for team_ai_instructions_*
- README: templates count 161 → 164, date Feb 19 → Feb 20
- CHANGELOG [Unreleased]: resource evaluations (AGENTS.md ETH Zürich
4/5, Sylvain Chabaud 3/5), spec-first Task Granularity section,
methodologies ATDD expansion
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-02-20 15:04:29 +01:00
Florian BRUNIAUX
a5942f1c53
docs: add Addy Osmani spec-writing evaluation (4/5) + spec-first.md sections
...
Integration of "How to write a good spec for AI agents" by Addy Osmani:
Evaluation (docs/resource-evaluations/addy-osmani-good-spec.md):
- Score: 4/5 (High Value - Integrate within 1 week)
- Fills gaps: modular design, operational boundaries, command specs
- Fact-checked: credentials verified via Perplexity, all claims sourced
- Challenge phase: technical-writer agent corrected initial 3/5 → 4/5
Spec-First Workflow Updates (guide/workflows/spec-first.md):
- NEW: "Modular Spec Design" section (~50 lines, line 322)
Pattern: Split large specs into focused files (CLAUDE-[domain].md)
- NEW: "Operational Boundaries" section (~60 lines, line 372)
Three-tier system: Always/Ask First/Never → maps to Claude Code modes
- NEW: "Command Spec Template" section (~40 lines, line 432)
Executable command specs with expected outputs & error handling
- NEW: "Anti-Pattern: Monolithic CLAUDE.md" section (~30 lines, line 472)
Explains cognitive load problem (>200 lines = context pollution)
Reference Index (machine-readable/reference.yaml):
- 8 new entries: spec_first_workflow → spec_osmani_score
- Links to new spec-first.md sections with line numbers
- Source attribution: https://addyosmani.com/blog/good-spec/
Public Facing (README.md):
- Incremented resource evaluations count: 35 → 36
File growth: spec-first.md 327 → 507 lines (+180)
Source: Addy Osmani (former Chrome team, 14y), published Jan 13, 2026
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-02-01 21:30:34 +01:00
