# Code Search

> Mandatory workflow for exploring the codebase and gathering context for the Orchestrator.

- Skill: `mokhtarabadi/code-search` (Agent Skill)
- Install (CLI): `npx skillmds@latest add mokhtarabadi/code-search`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mokhtarabadi/code-search/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: mokhtarabadi (https://skillmd.com/u/mokhtarabadi)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mokhtarabadi/code-search

---


# Code Search & Discovery Strategy

You are the Executor. Your job is to extract codebase context so the Manager can upload it to the Orchestrator.

**CRITICAL GUARDRAIL:** You MUST NOT read, analyze, or process the generated reports yourself. You are strictly a data gatherer in this phase.

## Discovery Workflow

1. **Map the Structure:** Call the `custom_context_get_directory_tree` MCP tool on the target directory (e.g., `.`, `src/`, `packages/`).

1.5. **Persist the Tree (Recommended):** Call `custom_context_create_tree_report` (default `target_path="."` = whole project; pass any sub-path to scope it) to save a `.gitignore`-aware tree as `context-reports/tree_report_<timestamp>_<uuid>.md`. Use this whenever the Manager asks to "create a tree of the project".

2. **Prefer Signature Extraction Over Full Reads:** Before reading a single file body, you MUST call `custom_context_extract_signatures` on every file or directory you plan to explore. This tool uses **tree-sitter AST** (not regex) to extract structural signatures — classes, functions, methods, interfaces, enums, type aliases — across all major languages. Signature extraction costs a fraction of the tokens compared to reading the full file, and is strictly preferred for initial exploration.

3. **Target Files:** Use the directory tree AND the extracted signatures together to identify exactly which files contain the logic relevant to the Manager's request. The signatures give you a structural map of each file's exports without loading its body.

4. **Compile Report (Only When Necessary):** Call `custom_context_read_source_files` ONLY when you have already narrowed the exploration to specific files and need their full bodies for detailed analysis. For broad exploration, signatures alone are sufficient.

5. **Halt and Handover:** Once the `custom_context_read_source_files` tool returns the generated file path, **STOP**. Do NOT use your `read` tool to open the report.

6. **Output Message:** Output the following exact message to the Manager:
   > "✅ Discovery complete. I have compiled the context report here: `[INSERT_FILE_PATH]`.
   > **Manager:** Please upload this file to the Orchestrator for review."

---

### Vertical Slicing Strategy

When the Orchestrator requests context for a **specific feature module** (e.g., `packages/billing/`, `src/features/auth/`, `apps/web/app/dashboard/`), follow this strategy instead of scanning the entire repository:

1. **Target the Slice:** Run `custom_context_get_directory_tree` on the specific feature directory only — not the whole repo.
2. **Extract Signatures:** Run `custom_context_extract_signatures` on all files within that slice to map its structural surface without full body reads.
3. **Core SOP Files (Mandatory):** Regardless of the slice, **always** append the full text of `AGENTS.md`, `DESIGN.md`, and `docs/*.md` to the final context report. This ensures the Orchestrator Brain is always grounded in the project's global rules and design system.
4. **Dependency Trace:** If the slice imports from other local modules (e.g., shared `lib/` or `core/` packages), trace and include signatures for those dependencies too.
5. **Compile:** Call `custom_context_read_source_files` only for the slice's key files and the mandatory Core SOP files.

**Why this matters:** Full-repo scans waste tokens and dilute signal. Vertical Slicing focuses the Brain on the exact feature boundaries that matter, while the mandatory Core SOP injection guarantees structural alignment with the project's architecture.

---

## Signature Extraction (`custom_context_extract_signatures`) — Details

### Why Prefer Signatures Over Full File Reads?

| Approach                           | Token Cost                          | Structural Accuracy                         | Speed                  |
| ---------------------------------- | ----------------------------------- | ------------------------------------------- | ---------------------- |
| `extract_signatures` (tree-sitter) | **Very low** — only signature lines | **High** — AST-parsed, no regex blind spots | Instant                |
| `read_source_files` (full body)    | **High** — entire file bodies       | N/A (full content)                          | Slower for large files |

For repositories with many files, extracting signatures first lets you decide which 2–3 files genuinely need full reading. This directly prevents context bloat in the Orchestrator session.

### Languages Supported (Tree-Sitter AST)

| Language       | Signatures Detected                                                                |
| -------------- | ---------------------------------------------------------------------------------- |
| **Python**     | `def`, `class`                                                                     |
| **JavaScript** | `function`, `class`, `method`, `arrow function`, `generator`                       |
| **TypeScript** | `function`, `class`, `interface`, `type alias`, `enum`, `method`, `arrow function` |
| **Java**       | `method`, `class`, `interface`, `enum`, `record`                                   |
| **Kotlin**     | `fun`, `class`                                                                     |
| **Go**         | `func`, `method`, `type struct`                                                    |
| **Rust**       | `fn`, `struct`, `enum`, `trait`, `type alias`, `impl`                              |

For languages not listed above, the tool gracefully falls back to regex-based extraction (class/function/def/interface patterns).

**Regex Fallback Languages:** Swift, Ruby, PHP, and C# are mapped in the extension table but do NOT have tree-sitter queries configured in the MCP server. They use regex-based extraction which is less accurate. Tree-sitter support for these languages is planned for a future release.

### What Signatures Include

- **Function/method signatures:** name, parameters (including type annotations), return type, decorators if on the same line
- **Class definitions:** name, parent class/interface if on the same line
- **Interface/trait definitions:** name
- **Type aliases:** name, type expression
- **Enum definitions:** name
- **Record/struct definitions:** name
- **Multi-line parameter lists:** correctly captured until the closing `)` or opening `{`

### What Signatures Exclude (Intentionally)

- **Function/class bodies** — the body is cut off at the opening `{` or `:` to minimize token usage
- **Decorators on separate lines** — only the decorated definition line is captured
- **Comments and docstrings** — structural intent only
- **Imports and module-level variables** — these are not structural signatures

### Example Usage

```json
// Extract signatures from a single file — result is saved to context-reports/signatures_report_<timestamp>_<uuid>.md
custom_context_extract_signatures({ "file_path": "src/services/user_service.py" })
// Returns: "✅ Success: Signatures extracted from `src/services/user_service.py`.
//          📁 Generated Report: `context-reports/signatures_report_20260821_104224_cc209479.md`"

// The generated report contains the extracted signatures, e.g.:
// ### Signatures in src/services/user_service.py
// class UserService:
// def get_user_by_id(id: int) -> User:
// def create_user(data: CreateUserDTO) -> User:
```