diff --git a/AGENTS.md b/AGENTS.md index 3ebc3fad..1f4e872c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,21 +1,23 @@ - + # oh-my-claudecode Multi-agent orchestration system for Claude Code CLI, providing intelligent delegation, parallel execution, and IDE-like capabilities through LSP/AST integration. -**Version:** 3.7.7 +**Version:** 3.8.14 **Purpose:** Transform Claude Code into a conductor of specialized AI agents **Inspired by:** oh-my-zsh / oh-my-opencode ## Purpose oh-my-claudecode enhances Claude Code with: -- **32 specialized agents** across 8 domains with 3-tier model routing (Haiku/Sonnet/Opus) -- **LSP tools** for IDE-like code intelligence (hover, go-to-definition, references, diagnostics) -- **AST tools** for structural code search and transformation via ast-grep -- **Execution modes**: autopilot, ultrawork, ralph-loop, ultrapilot, swarm, pipeline, ecomode -- **Skills system** for reusable workflows and automation + +- **32 specialized agents** across multiple domains with 3-tier model routing (Haiku/Sonnet/Opus) +- **37 skills** for workflow automation and specialized behaviors +- **31 hooks** for event-driven execution modes and enhancements +- **15 custom tools** including 12 LSP, 2 AST, and Python REPL +- **Execution modes**: autopilot, ultrawork, ralph, ultrapilot, swarm, pipeline, ecomode +- **MCP integration** with plugin-scoped tool discovery and skill loading ## Key Files @@ -24,20 +26,24 @@ oh-my-claudecode enhances Claude Code with: | `package.json` | Project dependencies and npm scripts | | `tsconfig.json` | TypeScript configuration | | `CHANGELOG.md` | Version history and release notes | -| `CLAUDE.md` | Main orchestration instructions (loaded by Claude Code) | +| `docs/CLAUDE.md` | End-user orchestration instructions (installed to user projects) | | `src/index.ts` | Main entry point - exports `createSisyphusSession()` | +| `.mcp.json` | MCP server configuration for plugin discovery | +| `.claude-plugin/plugin.json` | Claude Code plugin manifest | ## Subdirectories -| Directory | Purpose | -|-----------|---------| -| `src/` | TypeScript source code - core library (see `src/AGENTS.md`) | -| `agents/` | Markdown prompt templates for 32 agents | -| `skills/` | 32 skill definitions for workflows | -| `scripts/` | Build scripts, utilities, and automation | -| `docs/` | User documentation and guides | -| `templates/` | Hook and rule templates | -| `benchmark/` | Performance testing framework | +| Directory | Purpose | Related AGENTS.md | +|-----------|---------|-------------------| +| `src/` | TypeScript source code - core library | `src/AGENTS.md` | +| `agents/` | Markdown prompt templates for 32 agents (see `agents/templates/` for guidelines) | - | +| `skills/` | 37 skill definitions for workflows | `skills/AGENTS.md` | +| `commands/` | 31 slash command definitions (mirrors skills) | - | +| `scripts/` | Build scripts, utilities, and automation | - | +| `docs/` | User documentation and guides | `docs/AGENTS.md` | +| `templates/` | Hook and rule templates (coding-style, testing, security, performance, git-workflow) | - | +| `benchmark/` | Performance testing framework | - | +| `bridge/` | Pre-bundled MCP server for plugin distribution | - | ## For AI Agents @@ -54,25 +60,93 @@ oh-my-claudecode enhances Claude Code with: | Docs | `writer` | haiku | | Security | `security-reviewer` / `security-reviewer-low` | opus/haiku | | Build errors | `build-fixer` / `build-fixer-low` | sonnet/haiku | + | Testing | `qa-tester` / `qa-tester-high` | sonnet/opus | + | Code review | `code-reviewer` / `code-reviewer-low` | opus/haiku | + | TDD | `tdd-guide` / `tdd-guide-low` | sonnet/haiku | + | Data analysis | `scientist` / `scientist-low` / `scientist-high` | sonnet/haiku/opus | -2. **LSP/AST Tools** (v3.7.5+): Use IDE-like tools for code intelligence: +2. **LSP/AST Tools**: Use IDE-like tools for code intelligence: - `lsp_hover` - Type info and documentation at position - `lsp_goto_definition` - Jump to symbol definition - `lsp_find_references` - Find all usages across codebase - `lsp_document_symbols` - Get file outline - `lsp_workspace_symbols` - Search symbols across workspace - `lsp_diagnostics` - Get errors/warnings for single file - - `lsp_diagnostics_directory` - **Project-wide type checking** (uses tsc or LSP) + - `lsp_diagnostics_directory` - Project-wide type checking (uses tsc or LSP) - `lsp_rename` - Preview refactoring across files - `lsp_code_actions` - Get available quick fixes - `ast_grep_search` - Structural code search with patterns - `ast_grep_replace` - AST-aware code transformation + - `python_repl` - Execute Python code for data analysis 3. **Model Routing**: Match model tier to task complexity: - **Haiku** (LOW): Simple lookups, trivial fixes, fast searches - **Sonnet** (MEDIUM): Standard implementation, moderate reasoning - **Opus** (HIGH): Complex reasoning, architecture, debugging +### Modification Checklist + +#### Cross-File Dependencies + +| If you modify... | Also check/update... | +|------------------|---------------------| +| `agents/*.md` | `src/agents/definitions.ts`, `src/agents/index.ts`, `docs/REFERENCE.md` | +| `skills/*/SKILL.md` | `commands/*.md` (mirror), `scripts/build-skill-bridge.mjs` | +| `commands/*.md` | `skills/*/SKILL.md` (mirror) | +| `src/hooks/*` | `src/hooks/index.ts`, `src/hooks/bridge.ts`, related skill/command | +| Agent prompt | Tiered variants (`-low`, `-medium`, `-high`) | +| Tool definition | `src/tools/index.ts`, `src/mcp/omc-tools-server.ts`, `docs/REFERENCE.md` | +| `src/hud/*` | `commands/hud.md`, `skills/hud/SKILL.md` | +| `src/mcp/*` | `docs/REFERENCE.md` (MCP Tools section) | +| Agent tool assignments | `docs/CLAUDE.md` (Agent Tool Matrix) | +| `templates/rules/*` | `src/hooks/rules-injector/` if pattern changes | +| New execution mode | `src/hooks/*/`, `skills/*/SKILL.md`, `commands/*.md` (all three) | + +#### Documentation Updates (docs/) + +| If you change... | Update this docs/ file | +|------------------|----------------------| +| Agent count or agent list | `docs/REFERENCE.md` (Agents section) | +| Skill count or skill list | `docs/REFERENCE.md` (Skills section) | +| Hook count or hook list | `docs/REFERENCE.md` (Hooks System section) | +| Magic keywords | `docs/REFERENCE.md` (Magic Keywords section) | +| Architecture or skill composition | `docs/ARCHITECTURE.md` | +| Internal API or feature | `docs/FEATURES.md` | +| Breaking changes | `docs/MIGRATION.md` | +| Tiered agent design | `docs/TIERED_AGENTS_V2.md` | +| Compatibility requirements | `docs/COMPATIBILITY.md` | +| CLAUDE.md content | `docs/CLAUDE.md` (end-user instructions) | + +#### Skills ↔ Commands Relationship + +- `skills/` contains skill implementations with full prompts +- `commands/` contains slash command definitions that invoke skills +- Both should be kept in sync for the same functionality + +#### AGENTS.md Update Requirements + +When you modify files in these locations, update the corresponding AGENTS.md: + +| If you change... | Update this AGENTS.md | +|------------------|----------------------| +| Root project structure, new features | `/AGENTS.md` (this file) | +| `src/**/*.ts` structure or new modules | `src/AGENTS.md` | +| `agents/*.md` files | `src/agents/AGENTS.md` (implementation details) | +| `skills/*/` directories | `skills/AGENTS.md` | +| `src/hooks/*/` directories | `src/hooks/AGENTS.md` | +| `src/tools/**/*.ts` | `src/tools/AGENTS.md` | +| `src/features/*/` modules | `src/features/AGENTS.md` | +| `src/tools/lsp/` | `src/tools/lsp/AGENTS.md` | +| `src/tools/diagnostics/` | `src/tools/diagnostics/AGENTS.md` | +| `src/agents/*.ts` | `src/agents/AGENTS.md` | + +#### What to Update + +- Update version number when releasing +- Update feature descriptions when functionality changes +- Update file/directory tables when structure changes +- Keep "Generated" date as original, update "Updated" date + ### Testing Requirements ```bash @@ -91,7 +165,7 @@ const session = createSisyphusSession(); // Agent registration import { getAgentDefinitions } from './agents/definitions'; -const agents = getAgentDefinitions(); // Returns all 32 agents +const agents = getAgentDefinitions(); // Tool access import { allCustomTools, lspTools, astTools } from './tools'; @@ -106,7 +180,7 @@ import { allCustomTools, lspTools, astTools } from './tools'; │ oh-my-claudecode (OMC) │ │ ┌─────────────┬─────────────┬─────────────┬─────────────┐ │ │ │ Skills │ Agents │ Tools │ Hooks │ │ -│ │ (32 skills) │ (32 agents) │(LSP/AST/REPL)│ (30+ hooks)│ │ +│ │ (37 skills) │ (32 agents) │(LSP/AST/REPL)│ (31 hooks) │ │ │ └─────────────┴─────────────┴─────────────┴─────────────┘ │ │ ┌─────────────────────────────────────────────────────────┐│ │ │ Features Layer ││ @@ -119,6 +193,7 @@ import { allCustomTools, lspTools, astTools } from './tools'; ## Agent Summary (32 Total) ### Base Agents (12) + | Agent | Model | Purpose | |-------|-------|---------| | architect | opus | Architecture, debugging, root cause analysis | @@ -134,10 +209,22 @@ import { allCustomTools, lspTools, astTools } from './tools'; | qa-tester | sonnet | Interactive CLI/service testing | | scientist | sonnet | Data analysis, hypothesis testing | -### Tiered Variants (20) -- `*-low` (Haiku): architect-low, executor-low, researcher-low, designer-low, scientist-low, explore (base), security-reviewer-low, build-fixer-low, tdd-guide-low, code-reviewer-low -- `*-medium` (Sonnet): architect-medium, explore-medium -- `*-high` (Opus): executor-high, designer-high, explore-high, qa-tester-high, scientist-high, security-reviewer, code-reviewer +### Specialized Agents (4) + +| Agent | Model | Purpose | +|-------|-------|---------| +| security-reviewer | opus | Security vulnerability detection and audits | +| build-fixer | sonnet | Build/type error resolution (multi-language) | +| tdd-guide | sonnet | Test-driven development workflow | +| code-reviewer | opus | Expert code review and quality assessment | + +### Tiered Variants (16) + +| Tier | Agents | +|------|--------| +| **LOW** (Haiku) | `architect-low`, `executor-low`, `researcher-low`, `designer-low`, `scientist-low`, `security-reviewer-low`, `build-fixer-low`, `tdd-guide-low`, `code-reviewer-low` (9) | +| **MEDIUM** (Sonnet) | `architect-medium`, `explore-medium` (2) | +| **HIGH** (Opus) | `executor-high`, `designer-high`, `explore-high`, `qa-tester-high`, `scientist-high` (5) | ## Execution Modes @@ -151,13 +238,14 @@ import { allCustomTools, lspTools, astTools } from './tools'; | pipeline | "pipeline" | Sequential agent chaining with data passing | | ecomode | "eco", "efficient", "budget" | Token-efficient parallel execution | -## Skills (32) +## Skills (37) Key skills: `autopilot`, `ultrawork`, `ralph`, `ultrapilot`, `plan`, `ralplan`, `deepsearch`, `deepinit`, `frontend-ui-ux`, `git-master`, `tdd`, `security-review`, `code-review`, `research`, `analyze`, `swarm`, `pipeline`, `ecomode`, `cancel`, `learner`, `note`, `hud`, `doctor`, `omc-setup`, `mcp-setup`, `build-fix`, `ultraqa` -## LSP/AST Tools (v3.7.5+) +## LSP/AST Tools + +### LSP Tools -### LSP Tools (12) ```typescript // IDE-like code intelligence via Language Server Protocol lsp_hover // Type info at position @@ -174,16 +262,21 @@ lsp_code_actions // Available refactorings/fixes lsp_code_action_resolve // Get action details ``` -**Supported Languages**: TypeScript, Python, Rust, Go, C/C++, Java, JSON, HTML, CSS, YAML +#### Supported Languages + +TypeScript, Python, Rust, Go, C/C++, Java, JSON, HTML, CSS, YAML + +### AST Tools -### AST Tools (2) ```typescript // Structural code search/transform via ast-grep ast_grep_search // Pattern matching with meta-variables ($NAME, $$$ARGS) ast_grep_replace // AST-aware code transformation (dry-run by default) ``` -**Supported Languages**: JavaScript, TypeScript, TSX, Python, Ruby, Go, Rust, Java, Kotlin, Swift, C, C++, C#, HTML, CSS, JSON, YAML +#### Supported Languages + +JavaScript, TypeScript, TSX, Python, Ruby, Go, Rust, Java, Kotlin, Swift, C, C++, C#, HTML, CSS, JSON, YAML ## State Files @@ -197,6 +290,7 @@ ast_grep_replace // AST-aware code transformation (dry-run by default) ## Dependencies ### Runtime + | Package | Purpose | |---------|---------| | `@anthropic-ai/claude-agent-sdk` | Claude Code integration | @@ -208,6 +302,7 @@ ast_grep_replace // AST-aware code transformation (dry-run by default) | `commander` | CLI parsing | ### Development + | Package | Purpose | |---------|---------| | `typescript` | Type system | @@ -226,9 +321,10 @@ npm run lint # ESLint npm run sync-metadata # Sync agent/skill metadata ``` -## Hook System (30+) +## Hook System (31) Key hooks in `src/hooks/`: + - `autopilot/` - Full autonomous execution - `ralph/` - Persistence until verified - `ultrawork/` - Parallel execution @@ -241,7 +337,7 @@ Key hooks in `src/hooks/`: ## Configuration -Settings in `~/.claude/settings.local.json` or `.omc-config.json`: +Settings in `~/.claude/.omc-config.json`: ```json { diff --git a/README.md b/README.md index 75a0a2d1..ab72feaa 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,3 @@ - - - - # oh-my-claudecode [![npm version](https://img.shields.io/npm/v/oh-my-claude-sisyphus?color=cb3837)](https://www.npmjs.com/package/oh-my-claude-sisyphus) @@ -16,8 +12,6 @@ [Get Started](#quick-start) • [Documentation](https://yeachan-heo.github.io/oh-my-claudecode-website) • [Migration Guide](docs/MIGRATION.md) - - --- ## Quick Start @@ -40,14 +34,12 @@ autopilot: build a REST API for managing tasks That's it. Everything else is automatic. -

Your Claude Just Have been Steroided.

oh-my-claudecode

- --- ## Why oh-my-claudecode? @@ -70,17 +62,21 @@ Multiple strategies for different use cases - from fully autonomous builds to to | Mode | Speed | Use For | |------|-------|---------| | **Autopilot** | Fast | Full autonomous workflows | +| **Ultrawork** | Parallel | Maximum parallelism for any task | +| **Ralph** | Persistent | Tasks that must complete fully | | **Ultrapilot** | 3-5x faster | Multi-component systems | | **Ecomode** | Fast + 30-50% cheaper | Budget-conscious projects | | **Swarm** | Coordinated | Parallel independent tasks | | **Pipeline** | Sequential | Multi-stage processing | ### Intelligent Orchestration + - **32 specialized agents** for architecture, research, design, testing, data science - **Smart model routing** - Haiku for simple tasks, Opus for complex reasoning - **Automatic delegation** - Right agent for the job, every time ### Developer Experience + - **Magic keywords** - `ralph`, `ulw`, `eco`, `plan` for explicit control - **HUD statusline** - Real-time orchestration metrics in your status bar - **Skill learning** - Extract reusable patterns from your sessions @@ -101,6 +97,7 @@ Optional shortcuts for power users. Natural language works fine without them. | `ulw` | Maximum parallelism | `ulw fix all errors` | | `eco` | Token-efficient execution | `eco: migrate database` | | `plan` | Planning interview | `plan the API` | +| `ralplan` | Iterative planning consensus | `ralplan this feature` | **ralph includes ultrawork:** When you activate ralph mode, it automatically includes ultrawork's parallel execution. No need to combine keywords. @@ -162,15 +159,16 @@ If Oh-My-ClaudeCode helps your workflow, consider sponsoring: [![Sponsor on GitHub](https://img.shields.io/badge/Sponsor-❤️-red?style=for-the-badge&logo=github)](https://github.com/sponsors/Yeachan-Heo) -**Why sponsor?** +### Why sponsor? + - Keep development active - Priority support for sponsors - Influence roadmap & features - Help maintain free & open source -**Other ways to help:** +### Other ways to help + - ⭐ Star the repo - 🐛 Report bugs - 💡 Suggest features - 📝 Contribute code - diff --git a/agents/AGENTS.md b/agents/AGENTS.md deleted file mode 100644 index b4dca41f..00000000 --- a/agents/AGENTS.md +++ /dev/null @@ -1,144 +0,0 @@ - - - -# agents (Prompt Templates) - -Markdown prompt templates for all 32 agents in oh-my-claudecode. - -## Purpose - -This directory contains the prompt templates that define agent behavior. Each file is a markdown document with YAML frontmatter for metadata, loaded dynamically by `src/agents/definitions.ts`. - -## Key Files - -| File | Agent | Model | Purpose | -|------|-------|-------|---------| -| `architect.md` | architect | opus | Architecture, debugging, root cause analysis | -| `architect-medium.md` | architect-medium | sonnet | Moderate analysis tasks | -| `architect-low.md` | architect-low | haiku | Quick code questions | -| `executor.md` | executor | sonnet | Focused task implementation | -| `executor-high.md` | executor-high | opus | Complex multi-file changes | -| `executor-low.md` | executor-low | haiku | Simple single-file tasks | -| `explore.md` | explore | haiku | Fast codebase search | -| `explore-medium.md` | explore-medium | sonnet | Thorough search with reasoning | -| `explore-high.md` | explore-high | opus | Architectural discovery | -| `designer.md` | designer | sonnet | UI/UX, component design | -| `designer-high.md` | designer-high | opus | Complex UI architecture | -| `designer-low.md` | designer-low | haiku | Simple styling tweaks | -| `researcher.md` | researcher | sonnet | Documentation research | -| `researcher-low.md` | researcher-low | haiku | Quick doc lookups | -| `writer.md` | writer | haiku | Technical documentation | -| `vision.md` | vision | sonnet | Image/screenshot analysis | -| `critic.md` | critic | opus | Critical plan review | -| `analyst.md` | analyst | opus | Pre-planning requirements | -| `planner.md` | planner | opus | Strategic planning | -| `qa-tester.md` | qa-tester | sonnet | Interactive CLI testing | -| `qa-tester-high.md` | qa-tester-high | opus | Production-ready QA | -| `scientist.md` | scientist | sonnet | Data analysis | -| `scientist-high.md` | scientist-high | opus | Complex ML/research | -| `scientist-low.md` | scientist-low | haiku | Quick data inspection | -| `security-reviewer.md` | security-reviewer | opus | Security audits | -| `security-reviewer-low.md` | security-reviewer-low | haiku | Quick security scans | -| `build-fixer.md` | build-fixer | sonnet | Build error resolution | -| `build-fixer-low.md` | build-fixer-low | haiku | Simple type errors | -| `tdd-guide.md` | tdd-guide | sonnet | TDD workflow | -| `tdd-guide-low.md` | tdd-guide-low | haiku | Test suggestions | -| `code-reviewer.md` | code-reviewer | opus | Expert code review | -| `code-reviewer-low.md` | code-reviewer-low | haiku | Quick code checks | - -## For AI Agents - -### Working In This Directory - -#### Prompt Template Format - -Each file follows this structure: -```markdown ---- -name: agent-name -description: Brief description of what this agent does -model: opus | sonnet | haiku -tools: [Read, Glob, Grep, ...] ---- - -# Agent Name - -## Role -What this agent is and its expertise. - -## Instructions -Detailed instructions for how the agent should behave. - -## Constraints -What the agent should NOT do. - -## Output Format -How results should be formatted. -``` - -#### Creating a New Agent Prompt - -1. Create `new-agent.md` with YAML frontmatter -2. Define clear role, instructions, and constraints -3. Reference in `src/agents/definitions.ts` - -#### Tiered Variants - -For model routing, create variants with complexity-appropriate instructions: - -| Tier | File Suffix | Instructions Focus | -|------|-------------|-------------------| -| LOW (Haiku) | `-low.md` | Quick, simple tasks, minimal reasoning | -| MEDIUM (Sonnet) | Base file or `-medium.md` | Standard complexity | -| HIGH (Opus) | `-high.md` | Complex reasoning, deep analysis | - -### Common Patterns - -**Frontmatter parsing** (in `definitions.ts`): -```typescript -function loadAgentPrompt(agentName: string): string { - const content = readFileSync(`agents/${agentName}.md`, 'utf-8'); - const match = content.match(/^---[\s\S]*?---\s*([\s\S]*)$/); - return match ? match[1].trim() : content.trim(); -} -``` - -**Tool assignment by agent type:** -- Read-only: `[Read, Glob, Grep]` -- Analysis: `[Read, Glob, Grep, WebSearch, WebFetch]` -- Execution: `[Read, Glob, Grep, Edit, Write, Bash, TodoWrite]` -- Data: `[Read, Glob, Grep, Bash, python_repl]` - -### Testing Requirements - -Agent prompts are tested via integration tests that spawn agents and verify behavior. - -## Dependencies - -### Internal -- Loaded by `src/agents/definitions.ts` -- Referenced by skill definitions in `skills/` - -### External -None - pure markdown files. - -## Agent Categories - -| Category | Agents | Common Tools | -|----------|--------|--------------| -| Analysis | architect, architect-medium, architect-low | Read, Glob, Grep, lsp_diagnostics | -| Execution | executor, executor-low, executor-high | Read, Glob, Grep, Edit, Write, Bash, lsp_diagnostics | -| Search | explore, explore-medium, explore-high | Read, Glob, Grep, ast_grep_search, lsp_document_symbols, lsp_workspace_symbols | -| Research | researcher, researcher-low | WebSearch, WebFetch | -| Frontend | designer, designer-low, designer-high | Edit, Write, Bash | -| Docs | writer | Edit, Write | -| Visual | vision | Read, Glob, Grep | -| Planning | planner, analyst, critic | Read, Glob, Grep | -| Testing | qa-tester, qa-tester-high | Bash, Read, Grep, Glob, TodoWrite, lsp_diagnostics | -| Security | security-reviewer, security-reviewer-low | Read, Grep, Bash | -| Build | build-fixer, build-fixer-low | Read, Glob, Grep, Edit, Write, Bash, lsp_diagnostics, lsp_diagnostics_directory | -| TDD | tdd-guide, tdd-guide-low | Read, Grep, Glob, Bash, lsp_diagnostics | -| Review | code-reviewer, code-reviewer-low | Read, Grep, Glob, Bash, lsp_diagnostics | -| Data | scientist, scientist-low, scientist-high | Read, Glob, Grep, Bash, python_repl | - - diff --git a/docs/AGENTS.md b/docs/AGENTS.md new file mode 100644 index 00000000..2e675546 --- /dev/null +++ b/docs/AGENTS.md @@ -0,0 +1,100 @@ + + + +# docs + +User documentation and technical guides for oh-my-claudecode. + +## Purpose + +This directory contains documentation for end-users and developers: + +- **End-user guides**: How to use oh-my-claudecode features +- **Technical reference**: Architecture, compatibility, migration +- **Design documents**: Feature design specifications + +## Key Files + +| File | Description | +|------|-------------| +| `CLAUDE.md` | End-user orchestration instructions (installed to user projects) | +| `FEATURES.md` | Developer API reference for internal features | +| `REFERENCE.md` | API reference and configuration options | +| `ARCHITECTURE.md` | System architecture overview | +| `MIGRATION.md` | Version migration guides | +| `COMPATIBILITY.md` | Compatibility matrix and requirements | +| `TIERED_AGENTS_V2.md` | Model routing and tiered agent design | +| `DELEGATION-ENFORCER.md` | Delegation protocol documentation | +| `SYNC-SYSTEM.md` | State synchronization system | +| `ANALYTICS-SYSTEM.md` | Analytics collection documentation | +| `LOCAL_PLUGIN_INSTALL.md` | Plugin installation guide | + +## Subdirectories + +| Directory | Purpose | +|-----------|---------| +| `design/` | Feature design specifications | + +## For AI Agents + +### Working In This Directory + +1. **End-User Focus**: CLAUDE.md is installed to user projects - write for end-users, not developers +2. **Keep Links Accessible**: Use raw GitHub URLs for links in CLAUDE.md (agents can't navigate GitHub UI) +3. **Version Consistency**: Update version numbers across all docs when releasing + +### When to Update Each File + +| Trigger | File to Update | +|---------|---------------| +| Agent count or list changes | `REFERENCE.md` (Agents section) | +| Skill count or list changes | `REFERENCE.md` (Skills section) | +| Hook count or list changes | `REFERENCE.md` (Hooks System section) | +| Magic keywords change | `REFERENCE.md` (Magic Keywords section) | +| Agent tool assignments change | `CLAUDE.md` (Agent Tool Matrix) | +| Skill composition or architecture changes | `ARCHITECTURE.md` | +| New internal API or feature | `FEATURES.md` | +| Breaking changes or migrations | `MIGRATION.md` | +| Tiered agent design updates | `TIERED_AGENTS_V2.md` | +| Platform or version support changes | `COMPATIBILITY.md` | +| End-user instructions change | `CLAUDE.md` | +| Major user-facing features | `../README.md` | + +### Testing Requirements + +- Verify markdown renders correctly +- Check all internal links resolve +- Validate code examples in documentation + +### Common Patterns + +#### Linking to Raw Content + +Use raw GitHub URLs for external accessibility: + +[Migration Guide](https://raw.githubusercontent.com/Yeachan-Heo/oh-my-claudecode/main/docs/MIGRATION.md) + +#### Version References + +Use consistent version heading format with blank line after heading: + +```markdown +## v3.8.14 Changes + +- Feature A +- Feature B +``` + +## Dependencies + +### Internal + +- References agents from `agents/` +- References skills from `skills/` +- References tools from `src/tools/` + +### External + +None - pure markdown files. + + diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 17954c0a..5297d2f1 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -62,7 +62,7 @@ Skills: ultrawork + default + git-master | MEDIUM | Sonnet | Standard implementations | | HIGH | Opus | Complex reasoning, architecture | -See [FEATURES.md](./FEATURES.md) for the complete agent roster. +See [REFERENCE.md](./REFERENCE.md) for the complete agent roster. ### Delegation @@ -118,13 +118,16 @@ Legacy locations are auto-migrated on read. ## Hooks -oh-my-claudecode uses Claude Code's hooks system for lifecycle events: +oh-my-claudecode includes 31 hooks in `src/hooks/` for lifecycle events: -- **conversationStart**: Initialize OMC, check for active modes -- **beforeRequest**: Task delegation, skill routing -- **afterResponse**: State updates, verification checks +| Event | Purpose | +|-------|---------| +| `UserPromptSubmit` | Keyword detection, mode activation | +| `Stop` | Continuation enforcement, session end | +| `PreToolUse` | Permission validation | +| `PostToolUse` | Error recovery, rules injection | -Hooks are defined in `.claude/hooks/` and managed through the plugin system. +See [REFERENCE.md](./REFERENCE.md) for the complete hooks list. ## Verification Protocol @@ -143,6 +146,7 @@ Evidence must be fresh (within 5 minutes) and include actual command output. ## For More Details -- **API Reference**: See [FEATURES.md](./FEATURES.md) +- **Complete Reference**: See [REFERENCE.md](./REFERENCE.md) +- **Internal API**: See [FEATURES.md](./FEATURES.md) - **User Guide**: See [README.md](../README.md) - **Skills Reference**: See CLAUDE.md in your project diff --git a/docs/CLAUDE.md b/docs/CLAUDE.md index b1e5de15..b66ec4a7 100644 --- a/docs/CLAUDE.md +++ b/docs/CLAUDE.md @@ -366,8 +366,6 @@ Always use `oh-my-claudecode:` prefix when calling via Task tool. ### MCP Tools & Agent Capabilities -*Source of truth: `src/agents/definitions.ts`* - #### Tool Inventory | Tool | Category | Purpose | Assigned to Agents? | @@ -717,4 +715,4 @@ Say "setup omc" or run `/oh-my-claudecode:omc-setup` to configure. After that, e ## Migration -For migration guides from earlier versions, see [MIGRATION.md](./MIGRATION.md). +For migration guides from earlier versions, see the [Migration Guide](https://raw.githubusercontent.com/Yeachan-Heo/oh-my-claudecode/main/docs/MIGRATION.md). diff --git a/docs/DELEGATION-ENFORCER.md b/docs/DELEGATION-ENFORCER.md index e5895914..d478617a 100644 --- a/docs/DELEGATION-ENFORCER.md +++ b/docs/DELEGATION-ENFORCER.md @@ -277,6 +277,5 @@ No migration needed! The enforcer is backward compatible: ## Related -- [Model Routing](./MODEL-ROUTING.md) - Intelligent task complexity analysis - [Agent Definitions](./AGENTS.md) - Complete agent reference -- [Delegation Categories](./DELEGATION-CATEGORIES.md) - Semantic task grouping +- [Features Reference](./FEATURES.md) - Model routing and delegation categories diff --git a/docs/MIGRATION.md b/docs/MIGRATION.md index 51216419..20da0348 100644 --- a/docs/MIGRATION.md +++ b/docs/MIGRATION.md @@ -7,7 +7,7 @@ This guide covers all migration paths for oh-my-claudecode. Find your current ve ## Table of Contents - [v3.5.3 → v3.5.5: Test Fixes & Cleanup](#v353--v355-test-fixes--cleanup) -- [v3.5.2 → v3.5.3: Skill Consolidation](#v35--v36-skill-consolidation) +- [v3.5.2 → v3.5.3: Skill Consolidation](#v352--v353-skill-consolidation) - [v2.x → v3.0: Package Rename & Auto-Activation](#v2x--v30-package-rename--auto-activation) - [v3.0 → v3.1: Notepad Wisdom & Enhanced Features](#v30--v31-notepad-wisdom--enhanced-features) - [v3.x → v4.0: Major Architecture Overhaul](#v3x--v40-major-architecture-overhaul) diff --git a/docs/REFERENCE.md b/docs/REFERENCE.md index 3666638a..d6d1679b 100644 --- a/docs/REFERENCE.md +++ b/docs/REFERENCE.md @@ -227,6 +227,9 @@ Always use `oh-my-claudecode:` prefix when calling via Task tool. | `git-master` | Git expert for atomic commits and history | (silent activation) | | `tdd` | TDD enforcement: test-first development | `/oh-my-claudecode:tdd` | | `learner` | Extract reusable skill from session | `/oh-my-claudecode:learner` | +| `build-fix` | Fix build and TypeScript errors | `/oh-my-claudecode:build-fix` | +| `code-review` | Comprehensive code review | `/oh-my-claudecode:code-review` | +| `security-review` | Security vulnerability detection | `/oh-my-claudecode:security-review` | ### Utility Skills @@ -286,7 +289,20 @@ All skills are available as slash commands with the prefix `/oh-my-claudecode:`. ## Hooks System -Oh-my-claudecode includes 19 lifecycle hooks that enhance Claude Code's behavior. +Oh-my-claudecode includes 31 lifecycle hooks that enhance Claude Code's behavior. + +### Execution Mode Hooks + +| Hook | Description | +|------|-------------| +| `autopilot` | Full autonomous execution from idea to working code | +| `ultrawork` | Maximum parallel agent execution | +| `ralph` | Persistence until verified complete | +| `ultrapilot` | Parallel autopilot with file ownership | +| `ultraqa` | QA cycling until goal met | +| `swarm` | Coordinated multi-agent with SQLite task claiming | +| `mode-registry` | Tracks active execution mode (incl. ecomode) | +| `persistent-mode` | Maintains mode state across sessions | ### Core Hooks @@ -295,18 +311,18 @@ Oh-my-claudecode includes 19 lifecycle hooks that enhance Claude Code's behavior | `rules-injector` | Dynamic rules injection with YAML frontmatter parsing | | `omc-orchestrator` | Enforces orchestrator behavior and delegation | | `auto-slash-command` | Automatic slash command detection and execution | -| `keyword-detector` | Magic keyword detection (ultrawork, search, analyze) | -| `ralph-loop` | Self-referential development loop management | +| `keyword-detector` | Magic keyword detection (ultrawork, ralph, etc.) | | `todo-continuation` | Ensures todo list completion | -| `notepad` | Compaction-resilient memory system with three-tier storage | +| `notepad` | Compaction-resilient memory system | +| `learner` | Skill extraction from conversations | ### Context & Recovery | Hook | Description | |------|-------------| -| `context-window-limit-recovery` | Token limit error handling and recovery | +| `recovery` | Edit error, session, and context window recovery | | `preemptive-compaction` | Context usage monitoring to prevent limits | -| `session-recovery` | Session state recovery on crashes | +| `pre-compact` | Pre-compaction processing | | `directory-readme-injector` | README context injection | ### Quality & Validation @@ -316,16 +332,20 @@ Oh-my-claudecode includes 19 lifecycle hooks that enhance Claude Code's behavior | `comment-checker` | BDD detection and directive filtering | | `thinking-block-validator` | Extended thinking validation | | `empty-message-sanitizer` | Empty message handling | -| `edit-error-recovery` | Automatic recovery from edit errors | -| `post-tool-use` | Remember tag auto-capture to notepad system | +| `permission-handler` | Permission requests and validation | +| `think-mode` | Extended thinking detection | -### Environment & Notifications +### Coordination & Environment | Hook | Description | |------|-------------| +| `subagent-tracker` | Tracks spawned sub-agents | +| `session-end` | Session termination handling | | `non-interactive-env` | CI/non-interactive environment handling | | `agent-usage-reminder` | Reminder to use specialized agents | | `background-notification` | Background task completion notifications | +| `plugin-patterns` | Plugin pattern detection | +| `setup` | Initial setup and configuration | --- diff --git a/docs/SYNC-SYSTEM.md b/docs/SYNC-SYSTEM.md index f616f2a4..f0e5a67f 100644 --- a/docs/SYNC-SYSTEM.md +++ b/docs/SYNC-SYSTEM.md @@ -523,6 +523,4 @@ Potential improvements: ## Related -- [Release Workflow](./RELEASE-WORKFLOW.md) -- [Version Management](./VERSIONING.md) - [CI/CD Pipeline](../.github/workflows/) diff --git a/skills/AGENTS.md b/skills/AGENTS.md index 45095386..b5634df0 100644 --- a/skills/AGENTS.md +++ b/skills/AGENTS.md @@ -1,9 +1,9 @@ - + # skills -32 skill definitions for workflow automation and specialized behaviors. +37 skill definitions for workflow automation and specialized behaviors. ## Purpose @@ -15,62 +15,71 @@ Skills are reusable workflow templates that can be invoked via `/oh-my-claudecod ## Key Files ### Execution Mode Skills + | File | Skill | Purpose | -|------|-------|---------| -| `autopilot.md` | autopilot | Full autonomous execution from idea to working code | -| `ultrawork.md` | ultrawork | Maximum parallel agent execution | -| `ralph.md` | ralph | Persistence until verified complete | -| `ultrapilot.md` | ultrapilot | Parallel autopilot with file ownership | -| `swarm.md` | swarm | N coordinated agents with task claiming | -| `pipeline.md` | pipeline | Sequential agent chaining | -| `ecomode.md` | ecomode | Token-efficient parallel execution | -| `ultraqa.md` | ultraqa | QA cycling until goal met | +|-----------|-------|---------| +| `autopilot/SKILL.md` | autopilot | Full autonomous execution from idea to working code | +| `ultrawork/SKILL.md` | ultrawork | Maximum parallel agent execution | +| `ralph/SKILL.md` | ralph | Persistence until verified complete | +| `ultrapilot/SKILL.md` | ultrapilot | Parallel autopilot with file ownership | +| `swarm/SKILL.md` | swarm | N coordinated agents with task claiming | +| `pipeline/SKILL.md` | pipeline | Sequential agent chaining | +| `ecomode/SKILL.md` | ecomode | Token-efficient parallel execution | +| `ultraqa/SKILL.md` | ultraqa | QA cycling until goal met | ### Planning Skills + | File | Skill | Purpose | -|------|-------|---------| -| `plan.md` | plan | Strategic planning with interview workflow | -| `ralplan.md` | ralplan | Iterative planning (Planner+Architect+Critic) | -| `review.md` | review | Review plan with Critic | -| `analyze.md` | analyze | Deep analysis and investigation | -| `ralph-init.md` | ralph-init | Initialize PRD for structured ralph | +|-----------|-------|---------| +| `plan/SKILL.md` | plan | Strategic planning with interview workflow | +| `ralplan/SKILL.md` | ralplan | Iterative planning (Planner+Architect+Critic) | +| `review/SKILL.md` | review | Review plan with Critic | +| `analyze/SKILL.md` | analyze | Deep analysis and investigation | +| `ralph-init/SKILL.md` | ralph-init | Initialize PRD for structured ralph | ### Code Quality Skills + | File | Skill | Purpose | -|------|-------|---------| -| `code-review.md` | code-review | Comprehensive code review | -| `security-review.md` | security-review | Security vulnerability detection | -| `tdd.md` | tdd | Test-driven development workflow | -| `build-fix.md` | build-fix | Fix build and TypeScript errors | +|-----------|-------|---------| +| `code-review/SKILL.md` | code-review | Comprehensive code review | +| `security-review/SKILL.md` | security-review | Security vulnerability detection | +| `tdd/SKILL.md` | tdd | Test-driven development workflow | +| `build-fix/SKILL.md` | build-fix | Fix build and TypeScript errors | ### Exploration Skills + | File | Skill | Purpose | -|------|-------|---------| -| `deepsearch.md` | deepsearch | Thorough codebase search | -| `deepinit.md` | deepinit | Generate hierarchical AGENTS.md | -| `research.md` | research | Parallel scientist orchestration | +|-----------|-------|---------| +| `deepsearch/SKILL.md` | deepsearch | Thorough codebase search | +| `deepinit/SKILL.md` | deepinit | Generate hierarchical AGENTS.md | +| `research/SKILL.md` | research | Parallel scientist orchestration | ### Utility Skills + | File | Skill | Purpose | -|------|-------|---------| -| `learner.md` | learner | Extract reusable skill from session | -| `note.md` | note | Save notes for compaction resilience | -| `cancel.md` | cancel | Cancel any active OMC mode | -| `hud.md` | hud | Configure HUD display | -| `doctor.md` | doctor | Diagnose installation issues | -| `omc-setup.md` | omc-setup | One-time setup wizard | -| `mcp-setup.md` | mcp-setup | Configure MCP servers | -| `help.md` | help | Usage guide | +|-----------|-------|---------| +| `orchestrate/SKILL.md` | orchestrate | Core multi-agent orchestration (always active) | +| `learner/SKILL.md` | learner | Extract reusable skill from session | +| `note/SKILL.md` | note | Save notes for compaction resilience | +| `cancel/SKILL.md` | cancel | Cancel any active OMC mode | +| `hud/SKILL.md` | hud | Configure HUD display | +| `doctor/SKILL.md` | doctor | Diagnose installation issues | +| `omc-setup/SKILL.md` | omc-setup | One-time setup wizard | +| `mcp-setup/SKILL.md` | mcp-setup | Configure MCP servers | +| `help/SKILL.md` | help | Usage guide | +| `learn-about-omc/SKILL.md` | learn-about-omc | Usage pattern analysis | +| `skill/SKILL.md` | skill | Manage local skills | ### Domain Skills + | File | Skill | Purpose | -|------|-------|---------| -| `frontend-ui-ux.md` | frontend-ui-ux | Designer-developer aesthetic | -| `git-master.md` | git-master | Git expertise, atomic commits | -| `project-session-manager.md` | psm | Isolated dev environments | -| `writer-memory.md` | writer-memory | Agentic memory for writers | -| `release.md` | release | Automated release workflow | -| `local-skills-setup.md` | local-skills-setup | Manage local skills | +|-----------|-------|---------| +| `frontend-ui-ux/SKILL.md` | frontend-ui-ux | Designer-developer aesthetic | +| `git-master/SKILL.md` | git-master | Git expertise, atomic commits | +| `project-session-manager/SKILL.md` | psm | Isolated dev environments | +| `writer-memory/SKILL.md` | writer-memory | Agentic memory for writers | +| `release/SKILL.md` | release | Automated release workflow | +| `local-skills-setup/SKILL.md` | local-skills-setup | Manage local skills | ## For AI Agents @@ -121,10 +130,13 @@ Any configurable options. #### Creating a New Skill -1. Create `new-skill.md` with YAML frontmatter +1. Create `new-skill/SKILL.md` directory and file with YAML frontmatter 2. Define purpose, workflow, and usage 3. Add to skill registry (auto-detected from frontmatter) 4. Optionally add activation triggers +5. Create corresponding `commands/new-skill.md` file (mirror) +6. Update `docs/REFERENCE.md` (Skills section, count) +7. If execution mode skill, also create `src/hooks/new-skill/` hook ### Common Patterns @@ -148,7 +160,10 @@ Any configurable options. ### Testing Requirements -Skills are tested via integration tests that invoke skills and verify behavior. +- Skills are verified via integration tests +- Test skill invocation with `/oh-my-claudecode:skill-name` +- Verify trigger keywords activate correct skill +- For git-related skills, follow `templates/rules/git-workflow.md` ## Dependencies diff --git a/src/AGENTS.md b/src/AGENTS.md index 5f9fb7fa..caeba2b2 100644 --- a/src/AGENTS.md +++ b/src/AGENTS.md @@ -1,5 +1,5 @@ - + # src @@ -8,9 +8,10 @@ TypeScript source code for oh-my-claudecode - the core library that powers multi ## Purpose This directory contains all TypeScript source code organized into modules: + - **agents/** - 32 specialized AI agent definitions with tiered variants -- **tools/** - LSP/AST/REPL tools for IDE-like capabilities -- **hooks/** - 30+ event-driven behaviors for execution modes +- **tools/** - 15 LSP/AST/REPL tools for IDE-like capabilities +- **hooks/** - 31 event-driven behaviors for execution modes - **features/** - Core features (model routing, state management, verification) - **config/** - Configuration loading and validation - **commands/** - Command expansion utilities @@ -28,8 +29,8 @@ This directory contains all TypeScript source code organized into modules: | Directory | Purpose | |-----------|---------| | `agents/` | 32 agent definitions with prompts and tools (see `agents/AGENTS.md`) | -| `tools/` | LSP, AST, and Python REPL tools (see `tools/AGENTS.md`) | -| `hooks/` | 30+ hooks for execution modes (see `hooks/AGENTS.md`) | +| `tools/` | 15 LSP, AST, and Python REPL tools (see `tools/AGENTS.md`) | +| `hooks/` | 31 hooks for execution modes (see `hooks/AGENTS.md`) | | `features/` | Core features like model routing, state (see `features/AGENTS.md`) | | `config/` | Configuration loading (`loader.ts`) | | `commands/` | Command expansion utilities | @@ -58,11 +59,12 @@ This directory contains all TypeScript source code organized into modules: ``` 3. **Tool Registration**: Custom tools are registered in `tools/index.ts`: + ```typescript export const allCustomTools = [ ...lspTools, // 12 LSP tools ...astTools, // 2 AST tools - pythonReplTool // 1 REPL tool + pythonReplTool // 1 REPL tool (15 total) ]; ``` @@ -72,39 +74,55 @@ This directory contains all TypeScript source code organized into modules: return { architect: architectAgent, executor: executorAgent, - // ... 30 more agents + // ... all 32 agents }; } ``` ### Testing Requirements -```bash -# From project root -npm test # Run all tests -npm run test:run # Run once without watch -npm run test:coverage # With coverage report -``` - -Test files are in `__tests__/` with pattern `*.test.ts`. +- Test files are in `__tests__/` with pattern `*.test.ts` +- Run `npm test -- --grep "module-name"` for specific modules +- Verify type safety with `npm run build` after changes +- Use `lsp_diagnostics_directory` tool for project-wide type checking ### Common Patterns -**Creating a new agent:** +#### Creating a New Agent + 1. Add agent file in `agents/` (e.g., `new-agent.ts`) 2. Export from `agents/index.ts` 3. Add to `getAgentDefinitions()` in `agents/definitions.ts` 4. Create prompt template in `/agents/new-agent.md` +5. Update `docs/REFERENCE.md` (Agents section) with new agent + +#### Adding a New Hook -**Adding a new hook:** 1. Create directory in `hooks/` (e.g., `new-hook/`) 2. Add `index.ts`, `types.ts`, `constants.ts` 3. Export from `hooks/index.ts` +4. Update `docs/REFERENCE.md` (Hooks System section) with new hook + +#### Adding a New Tool -**Adding a new tool:** 1. Create tool definition with Zod schema 2. Add to appropriate tools file (`lsp-tools.ts`, `ast-tools.ts`) 3. Export from `tools/index.ts` +4. Update `docs/REFERENCE.md` if user-facing tool + +#### Adding a New Feature + +1. Create feature directory in `features/` +2. Export from `features/index.ts` +3. Update `docs/FEATURES.md` with API documentation + +#### TypeScript Conventions + +- Use strict mode (`noImplicitAny`, `strictNullChecks`) +- Prefer interfaces over type aliases for public APIs +- Use barrel exports (`index.ts`) for each module +- File size: 200-400 lines typical, 800 max +- Use Zod for runtime input validation (see `templates/rules/coding-style.md`) ## Dependencies @@ -114,13 +132,8 @@ Test files are in `__tests__/` with pattern `*.test.ts`. - Loads skills from `/skills/*.md` ### External -| Package | Used In | Purpose | -|---------|---------|---------| -| `zod` | tools, features | Runtime type validation | -| `@ast-grep/napi` | tools/ast-tools.ts | AST parsing and searching | -| `vscode-languageserver-protocol` | tools/lsp/ | LSP types | -| `better-sqlite3` | hooks/swarm/ | Task coordination DB | -| `chalk` | cli/, hud/ | Terminal colors | + +Key packages by module: `zod` (tools, features), `@ast-grep/napi` (tools/ast), `vscode-languageserver-protocol` (tools/lsp), `better-sqlite3` (hooks/swarm), `chalk` (cli, hud). See root AGENTS.md for full dependency list. ## Module Dependency Graph diff --git a/src/agents/AGENTS.md b/src/agents/AGENTS.md index b95b9378..e100eaa9 100644 --- a/src/agents/AGENTS.md +++ b/src/agents/AGENTS.md @@ -1,5 +1,5 @@ - + # agents @@ -8,8 +8,10 @@ ## Purpose This directory defines all agents available in oh-my-claudecode: + - **12 base agents** with default model assignments -- **20 tiered variants** (LOW/MEDIUM/HIGH) for smart routing +- **4 specialized agents** (security-reviewer, build-fixer, tdd-guide, code-reviewer) +- **16 tiered variants** (LOW/MEDIUM/HIGH) for smart routing - Prompts loaded dynamically from `/agents/*.md` files - Tools assigned based on agent specialization @@ -165,9 +167,38 @@ export const newAgentHigh: AgentConfig = { }; ``` +### Modification Checklist + +#### When Adding a New Agent + +1. Create agent file (`src/agents/new-agent.ts`) +2. Create prompt template (`agents/new-agent.md`) +3. Add to `definitions.ts` (import + registry) +4. Export from `index.ts` +5. Update `docs/REFERENCE.md` (Agents section, count) +6. Update `docs/CLAUDE.md` (Agent Selection Guide) +7. Update root `/AGENTS.md` (Agent Summary if applicable) + +#### When Modifying an Agent + +1. Update agent file (`src/agents/*.ts`) if changing tools/model +2. Update prompt template (`agents/*.md`) if changing behavior +3. Update tiered variants (`-low`, `-medium`, `-high`) if applicable +4. Update `docs/REFERENCE.md` if changing agent description/capabilities +5. Update `docs/CLAUDE.md` (Agent Tool Matrix) if changing tool assignments + +#### When Removing an Agent + +1. Remove agent file from `src/agents/` +2. Remove prompt template from `agents/` +3. Remove from `definitions.ts` and `index.ts` +4. Update agent counts in all documentation +5. Check for skill/hook references to the removed agent + ### Testing Requirements Agents are tested via integration tests: + ```bash npm test -- --grep "agent" ``` diff --git a/src/features/AGENTS.md b/src/features/AGENTS.md index 0a657107..5b95e106 100644 --- a/src/features/AGENTS.md +++ b/src/features/AGENTS.md @@ -1,5 +1,5 @@ - + # features @@ -127,9 +127,25 @@ const config = getCategoryConfig(category); // { tier: 'HIGH', temperature: 0.3, thinking: 'max' } ``` +### Modification Checklist + +#### When Adding a New Feature + +1. Create feature directory with `index.ts`, `types.ts`, `constants.ts` +2. Export from `features/index.ts` +3. Update `docs/FEATURES.md` with API documentation +4. Update `docs/AGENTS.md` if architecture changes + +#### When Modifying State File Paths + +1. Update `state-manager/` for path standardization +2. Consider migration logic for existing state files +3. Document new paths in feature's README or AGENTS.md + ### Common Patterns -**Feature module structure:** +#### Feature Module Structure + ``` feature-name/ ├── index.ts # Main exports diff --git a/src/hooks/AGENTS.md b/src/hooks/AGENTS.md index d53229e0..7622ec70 100644 --- a/src/hooks/AGENTS.md +++ b/src/hooks/AGENTS.md @@ -1,14 +1,14 @@ - + # hooks -30+ event-driven hooks that power execution modes and behaviors. +31 event-driven hooks that power execution modes and behaviors. ## Purpose Hooks intercept Claude Code events to enable: -- **Execution modes**: autopilot, ultrawork, ralph, ultrapilot, swarm, pipeline +- **Execution modes**: autopilot, ultrawork, ralph, ultrapilot, swarm, pipeline (ecomode via mode-registry) - **Validation**: thinking blocks, empty messages, comments - **Recovery**: edit errors, session recovery, context window - **Enhancement**: rules injection, directory READMEs, notepad @@ -19,6 +19,7 @@ Hooks intercept Claude Code events to enable: | File | Description | |------|-------------| | `index.ts` | Re-exports all hooks | +| `bridge.ts` | Shell script entry point - `processHook()` routes events to handlers | ## Subdirectories @@ -32,7 +33,8 @@ Hooks intercept Claude Code events to enable: | `ultrapilot/` | Parallel autopilot with file ownership | "ultrapilot" | | `swarm/` | N coordinated agents with task claiming | "swarm N agents" | | `ultraqa/` | QA cycling until goal met | test failures | -| `mode-registry/` | Tracks active execution mode | internal | +| `mode-registry/` | Tracks active execution mode (incl. ecomode) | internal | +| `persistent-mode/` | Maintains mode state across sessions | internal | ### Validation Hooks @@ -41,6 +43,7 @@ Hooks intercept Claude Code events to enable: | `thinking-block-validator/` | Validates thinking blocks in responses | | `empty-message-sanitizer/` | Handles empty/whitespace messages | | `comment-checker/` | Checks code comment quality | +| `permission-handler/` | Handles permission requests and validation | ### Recovery Hooks @@ -48,6 +51,7 @@ Hooks intercept Claude Code events to enable: |-----------|---------| | `recovery/` | Edit error recovery, session recovery | | `preemptive-compaction/` | Prevents context overflow | +| `pre-compact/` | Pre-compaction processing | ### Enhancement Hooks @@ -67,6 +71,7 @@ Hooks intercept Claude Code events to enable: | `think-mode/` | Extended thinking detection | | `auto-slash-command/` | Slash command expansion | | `non-interactive-env/` | Non-interactive environment detection | +| `plugin-patterns/` | Plugin pattern detection | ### Coordination Hooks @@ -74,6 +79,15 @@ Hooks intercept Claude Code events to enable: |-----------|---------| | `todo-continuation/` | Enforces task completion | | `omc-orchestrator/` | Orchestrator behavior | +| `subagent-tracker/` | Tracks spawned sub-agents | +| `session-end/` | Session termination handling | +| `background-notification/` | Background task notifications | + +### Setup Hooks + +| Directory | Purpose | +|-----------|---------| +| `setup/` | Initial setup and configuration | ## For AI Agents @@ -90,6 +104,14 @@ hook-name/ └── *.ts # Supporting modules ``` +#### When Adding a New Hook + +1. Create hook directory with `index.ts`, `types.ts`, `constants.ts` +2. Export from `index.ts` (hook re-exports) +3. Register handler in `bridge.ts` if needed +4. Update `docs/REFERENCE.md` (Hooks System section) with new hook entry +5. If execution mode hook, also create `skills/*/SKILL.md` and `commands/*.md` + #### Hook Implementation ```typescript @@ -145,7 +167,8 @@ export function createHook(config: HookConfig) { ### Common Patterns -**State management:** +#### State Management + ```typescript import { readState, writeState } from '../features/state-manager'; @@ -154,7 +177,8 @@ state.phase = 'executing'; writeState('autopilot-state', state); ``` -**Event handling:** +#### Event Handling + ```typescript // UserPromptSubmit - Before prompt is sent // Stop - Before session ends @@ -164,13 +188,10 @@ writeState('autopilot-state', state); ### Testing Requirements -```bash -# Test specific hook -npm test -- --grep "autopilot" - -# Test all hooks -npm test -- --grep "hooks" -``` +- Test specific hooks with `npm test -- --grep "hook-name"` +- Test execution modes end-to-end with skill invocation +- Verify state persistence in `.omc/state/` +- For security hooks, follow `templates/rules/security.md` checklist ## Dependencies diff --git a/src/tools/AGENTS.md b/src/tools/AGENTS.md index 2b3565bd..e0915a2d 100644 --- a/src/tools/AGENTS.md +++ b/src/tools/AGENTS.md @@ -1,5 +1,5 @@ - + # tools @@ -127,6 +127,17 @@ The `lsp_diagnostics_directory` tool supports two strategies: **Recommendation**: Use `strategy: "auto"` (default) - it prefers `tsc` when available. +### Modification Checklist + +#### When Adding a New Tool + +1. Define tool in appropriate file (`lsp-tools.ts`, `ast-tools.ts`, or new file) +2. Export from `index.ts` (add to `allCustomTools`) +3. Update `src/mcp/omc-tools-server.ts` if exposed via MCP +4. Update `docs/REFERENCE.md` (MCP Tools section) +5. Update agent tool assignments in `src/agents/definitions.ts` if needed +6. Update `docs/CLAUDE.md` (Agent Tool Matrix) if assigned to agents + ### Testing Requirements ```bash