diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 0b387f1..27d414c 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -103,6 +103,31 @@ Say "setup omc" or run `/oh-my-claudecode:omc-setup`. +## Mandatory Codebase Discovery Preflight + +For any task that requires finding files, symbols, classes, modules, call chains, +cross-file relationships, or unknown implementation locations, the first discovery +step MUST be Codebase Memory. + +Required sequence: + +1. If Codebase Memory tools are not currently visible, resolve them first: + `ToolSearch("select:mcp__codebase-memory__index_status")`. +2. Call `mcp__codebase-memory__index_status`. +3. If the project is indexed, use: + - `mcp__codebase-memory__search_graph` for symbols/classes/modules/files; + - `mcp__codebase-memory__trace_path` for call chains/dependencies; + - `mcp__codebase-memory__get_architecture` for module structure; + - `mcp__codebase-memory__get_code_snippet` for targeted code. +4. If the project is not indexed or path is ambiguous, use + `mcp__codebase-memory__list_projects` and/or `mcp__codebase-memory__index_repository`. +5. Only if Codebase Memory is unavailable or fails after retry, fall back to + Glob/Grep/Read/LSP. + +Do not start first-pass codebase discovery with `git status`, Bash, Glob, Grep, +or Read. `git status` is allowed for worktree safety before edits/staging, but it +does not satisfy discovery preflight and must not replace Codebase Memory. + ## Specific Overrides - "Delegate" → always route via `~/.claude/rules/delegation.md` routing table; never decide ad-hoc. diff --git a/.claude/agents/architect.md b/.claude/agents/architect.md index 1bcbb88..3b04dbd 100644 --- a/.claude/agents/architect.md +++ b/.claude/agents/architect.md @@ -24,7 +24,10 @@ You are Architect. Analyze code, diagnose bugs, and provide actionable architect ## Investigation Protocol -1) Gather context first (MANDATORY): Glob project structure, Grep/Read relevant implementations, check manifests, find tests. Execute in parallel. +1) Gather context first (MANDATORY): + for non-trivial codebase questions, run Codebase Memory preflight before Glob/Grep/Read: + `index_status` → `search_graph` / `trace_path` / `get_architecture` → targeted Read/LSP. + Use Glob/Grep only as fallback or precision confirmation. 2) For debugging: Read error messages completely. Check recent changes (git log/blame). Find working examples. Compare broken vs working. 3) Form hypothesis and document BEFORE looking deeper. 4) Cross-reference hypothesis against actual code. Cite file:line for every claim. @@ -35,6 +38,12 @@ You are Architect. Analyze code, diagnose bugs, and provide actionable architect ## Tool Usage +- **Codebase Memory — primary for codebase discovery**: + `mcp__codebase-memory__index_status`, + `mcp__codebase-memory__search_graph`, + `mcp__codebase-memory__trace_path`, + `mcp__codebase-memory__get_architecture`, + `mcp__codebase-memory__get_code_snippet` - **Core**: Glob, Grep, Read, Bash (git blame/log) - **Context-mode**: ctx_search, ctx_execute, ctx_execute_file, ctx_batch_execute, ctx_fetch_and_index - **LSP**: lsp_diagnostics, lsp_diagnostics_directory, lsp_hover, lsp_goto_definition, lsp_find_references, lsp_document_symbols, lsp_workspace_symbols, lsp_code_actions, lsp_rename, lsp_servers diff --git a/.claude/agents/debugger.md b/.claude/agents/debugger.md index 7f52179..e3762d9 100644 --- a/.claude/agents/debugger.md +++ b/.claude/agents/debugger.md @@ -37,6 +37,7 @@ You are Debugger. Trace bugs to their root cause and recommend minimal fixes. Ge ## Tool Usage +- **Codebase Memory**: use `index_status` → `search_graph` / `trace_path` / `get_code_snippet` before Grep/Read when tracing call chains or cross-file dependencies in unfamiliar code. - **Core**: Read, Grep, Bash (git blame/log, build commands), Edit (minimal fixes only) - **Context-mode**: ctx_search, ctx_execute, ctx_execute_file, ctx_batch_execute, ctx_fetch_and_index - **LSP**: lsp_diagnostics, lsp_diagnostics_directory (preferred over CLI for TypeScript), lsp_hover, lsp_goto_definition, lsp_find_references, lsp_document_symbols, lsp_workspace_symbols diff --git a/.claude/agents/explore.md b/.claude/agents/explore.md index e2baee2..a4a348a 100644 --- a/.claude/agents/explore.md +++ b/.claude/agents/explore.md @@ -8,13 +8,28 @@ disallowedTools: Write, Edit You are Explorer. Find files, code patterns, and relationships in the codebase and return actionable results. Answer "where is X?", "which files contain Y?", "how does Z connect to W?" Not responsible for modifying code, implementing features, or external documentation search. Route external docs/literature requests to document-specialist. +## Codebase Discovery Protocol + +For non-trivial repository investigation, architecture questions, cross-file relationships, +call chains, refactors, or unknown implementation locations: + +1. First check `mcp__codebase-memory__index_status`. +2. If the project is not indexed, stale, or path is ambiguous, use + `mcp__codebase-memory__list_projects` and/or `mcp__codebase-memory__index_repository`. +3. Use `mcp__codebase-memory__search_graph` for symbols, classes, modules, and files. +4. Use `mcp__codebase-memory__trace_path` for call chains and dependency flow. +5. Use `mcp__codebase-memory__get_code_snippet` for targeted code snippets. +6. Use Glob/Grep/Read only after Codebase Memory, or as fallback if Codebase Memory is unavailable. + +Do not start non-trivial codebase discovery with Glob or Grep. + ## Constraints - Read-only: cannot create, modify, or delete files - Always use absolute paths (starting with /) - Return results as message text, never store in files - For symbol usage lookups requiring lsp_find_references, escalate to explore-high -- Launch 3+ parallel searches on first action, broad-to-narrow strategy +- For non-trivial codebase discovery, first run Codebase Memory preflight; then launch parallel searches if additional confirmation is needed. - Cross-validate across multiple tools (Grep vs Glob vs ast_grep_search) - Cap exploratory depth: stop after 2 rounds of diminishing returns - Medium effort: 3-5 parallel searches; thorough: 5-10; quick lookups: 1-2 @@ -28,6 +43,15 @@ You are Explorer. Find files, code patterns, and relationships in the codebase a ## Tools +- **Codebase Memory — primary for codebase discovery**: + `mcp__codebase-memory__index_status`, + `mcp__codebase-memory__list_projects`, + `mcp__codebase-memory__index_repository`, + `mcp__codebase-memory__search_graph`, + `mcp__codebase-memory__trace_path`, + `mcp__codebase-memory__get_code_snippet`, + `mcp__codebase-memory__get_architecture`, + `mcp__codebase-memory__search_code` - **Core**: Glob (file structure), Grep (text patterns), Read (targeted with offset/limit) - **Context-mode**: ctx_search, ctx_batch_execute, ctx_execute, ctx_execute_file, ctx_fetch_and_index - **LSP**: lsp_document_symbols, lsp_workspace_symbols, lsp_hover, lsp_goto_definition, lsp_find_references, lsp_diagnostics diff --git a/.claude/agents/tracer.md b/.claude/agents/tracer.md index d72f2f4..ccbbc72 100644 --- a/.claude/agents/tracer.md +++ b/.claude/agents/tracer.md @@ -57,6 +57,7 @@ You are not responsible for implementation, generic code review, generic summari - [Confirmation Bias](software-laws.md#confirmation-bias): actively seek disconfirming evidence for the leading hypothesis. Collect evidence against, not just for. ## Tools +**Codebase Memory**: use `index_status` → `search_graph` / `trace_path` / `get_code_snippet` before Grep/Read when tracing call chains or cross-file dependencies in unfamiliar code. **Core**: Read, Grep, Glob, Bash (focused evidence gathering) **Context-mode**: ctx_search, ctx_execute, ctx_batch_execute, ctx_execute_file, ctx_fetch_and_index **LSP**: lsp_diagnostics, lsp_diagnostics_directory, lsp_hover, lsp_goto_definition, lsp_find_references, lsp_document_symbols diff --git a/.claude/rules/delegation.md b/.claude/rules/delegation.md index b2b4bdc..74fe990 100644 --- a/.claude/rules/delegation.md +++ b/.claude/rules/delegation.md @@ -75,7 +75,7 @@ TaskCreate = conversation tracking only, NOT delegation. | Category | Agents | Primary | Fallback | |----------|--------|---------|----------| -| Analysis | explore, analyst, tracer, scientist | ctx_*, python_repl, Grep/Glob, session_search | Bash, DDG | +| Analysis / Architecture | explore, analyst, tracer, architect, scientist | Codebase Memory (`mcp__codebase-memory__*`), ctx_*, python_repl, Grep/Glob, session_search | Bash, DDG | | Implementation | executor, verifier, debugger, test-engineer | Edit/Write, LSP, ast_grep, ctx_execute, Bash (tests) | Bash, Grep, python_repl | | Review & Security | code-reviewer, security-reviewer | LSP, ast_grep_search, Grep, ctx_execute_file | Read, Bash | | Specialist | document-specialist, architect, writer, git-master | context7, GitHub, LSP, ctx_execute_file, Read | DDG, Fetch, gh CLI | diff --git a/.claude/rules/tool-priority.md b/.claude/rules/tool-priority.md index a971803..35b66bc 100644 --- a/.claude/rules/tool-priority.md +++ b/.claude/rules/tool-priority.md @@ -106,6 +106,19 @@ LSP, OMC State/Notepad, and AST tools listed as `lsp_*`, `state_*`, `notepad_*`, ## Codebase Memory Usage Policy +This policy applies to the orchestrator and to every subagent that performs codebase discovery. +Subagents must not assume the orchestrator has already completed discovery unless the prompt +explicitly provides the relevant Codebase Memory results, qualified names, or file paths. + +If the orchestrator delegates discovery to a subagent, the delegation prompt must either: +1. include explicit Codebase Memory preflight instructions, or +2. provide already verified Codebase Memory results and tell the subagent to continue from them. + +The first observable discovery tool call must be Codebase Memory, not Bash, Glob, +Grep, Read, or LSP. Planning text is not enough: if the reasoning says Codebase +Memory will be used, the next discovery action must actually call Codebase Memory +or explicitly report that the tool is unavailable. + Use Codebase Memory before Grep/Read/LSP when the task asks to: - find where behavior is implemented; - understand module architecture; diff --git a/AGENTS.md b/AGENTS.md index 29ccaee..b40befa 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -11,6 +11,17 @@ itself rather than on generic product or application architecture. - Use Conventional Commits: `type(scope): summary`. - Commit headers must be in English and include a descriptive body. +## Codebase Discovery + +For non-trivial codebase investigation, architecture questions, cross-file edits, +refactors, call chains, or unknown implementation locations, use Codebase Memory +before Grep/Glob/Read/LSP. + +Preferred sequence: +`index_status` → `search_graph` / `trace_path` / `get_code_snippet` → targeted Read/LSP. + +Grep/Glob are fallback or precision-confirmation tools, not first-pass architecture discovery. + ## Public Entry Headers Use the project umbrella headers instead of recreating include order manually: