docs: comprehensively optimize CLAUDE.md for agent effectiveness (#38)
* docs: condense CLAUDE.md for token efficiency
Reduced CLAUDE.md from 223 to 169 lines (24% reduction).
Changes:
- Removed verbose sections (reference implementation table, redundant explanations)
- Added "Key Files" section highlighting types.ts and plugin examples upfront
- Condensed tech stack, conventions, and commands into scannable format
- Kept critical content: plugin pattern, shell security, common mistakes
Agents spawned by the orchestrator don't need special documentation - they
just read the repo's existing CLAUDE.md. The orchestrator is transparent.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
* docs: comprehensively optimize CLAUDE.md and add package READMEs
Major improvements to agent effectiveness on this codebase:
## Enhanced CLAUDE.md (169 → 444 lines)
**New sections:**
- Quick Start — get oriented fast (links to common tasks)
- Looking for X? — quick reference table for finding code
- Monorepo Tools — pnpm workspace commands (filter, watch mode, scoped builds)
- Common Tasks — step-by-step guides (add plugin, add Session field, add event type)
- Plugin Development — pattern explanation + examples (notifier-desktop, agent-claude-code)
- Architecture Deep Dive — data flow diagram + state machine + key abstractions
**Improved sections:**
- Commands — added watch mode, filtering, scoped operations
- Shell Security — added exploit example showing actual injection
- Common Mistakes — added 5 code examples (BAD vs GOOD with explanations)
- Design Decisions — added "Why" for each decision
## New Package READMEs (Progressive Disclosure)
**packages/core/README.md:**
- Explains core services (SessionManager, LifecycleManager, PluginRegistry)
- Key files guide (types.ts, session-manager.ts, lifecycle-manager.ts)
- Common tasks specific to core
- Architecture notes (why flat metadata, why polling, why plugin slots)
**packages/plugins/runtime-tmux/README.md:**
- How the plugin works (creating sessions, sending messages, getting output)
- Security considerations (session ID validation)
- Common issues (tmux not installed, detached sessions persist)
- Limitations (macOS/Linux only, no resource limits)
- Architecture notes (why tmux over raw processes)
## Impact
Agents working on this codebase now have:
1. **Faster discovery** — "Looking for X?" table + Quick Start links
2. **Actionable guides** — step-by-step for common tasks
3. **Concrete examples** — code showing actual mistakes and fixes
4. **Progressive disclosure** — package READMEs for deep dives
5. **Monorepo fluency** — pnpm workspace commands documented
6. **Architecture understanding** — data flow + state machine + "why" explanations
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
8db5f2b161