23blocks-os/docs-search

AI Maestro Documentation Search

CRITICAL: AUTOMATIC BEHAVIOR - READ THIS FIRST

THIS IS NOT OPTIONAL. THIS IS YOUR DEFAULT BEHAVIOR.

When the user gives you ANY instruction or task, you MUST FIRST search documentation for:

• Function signatures - What are the parameters and return types?
• Class documentation - What methods and properties exist?
• API documentation - How should this endpoint work?
• Code comments - What did the author intend?

DO NOT:

• Start implementing before checking documentation
• Assume you know the function signature without checking
• Skip doc search because "it's a simple task"
• Wait for the user to ask you to check docs

ALWAYS:

• Search docs IMMEDIATELY when you receive a task
• Search for terms and concepts the user mentions
• Check documentation before calling unfamiliar functions
• Look for patterns before creating new components

The Rule: Receive Instruction → Search Docs → Then Proceed

1. User asks you to do something
2. IMMEDIATELY search docs for relevant context
3. NOW you know the correct signatures and patterns
4. NOW you can implement correctly the first time

Example - User asks to modify a service:

# IMMEDIATELY run:
docs-search.sh "PaymentService"
docs-find-by-type.sh class

Example - User mentions a function:

# IMMEDIATELY run:
docs-search.sh "validateUser"
docs-search.sh --keyword "authenticate"

---

Available Commands

All commands auto-detect your agent ID from the tmux session.

Search Commands

| Command | Description | |---------|-------------| | docs-search.sh <query> | Semantic search through documentation | | docs-search.sh --keyword <term> | Keyword/exact match search | | docs-find-by-type.sh <type> | Find docs by type (function, class, module, etc.) | | docs-get.sh <doc-id> | Get full document with all sections | | docs-list.sh | List all indexed documents | | docs-stats.sh | Get documentation index statistics |

Indexing Commands

| Command | Description | |---------|-------------| | docs-index.sh [project-path] | Full index documentation from project | | docs-index-delta.sh [project-path] | Delta index - only index new and modified files |

What to Search Based on User Instruction

| User Says | IMMEDIATELY Search | |-----------|-------------------| | "Create a service for X" | docs-search.sh "service", docs-find-by-type.sh class | | "Call the Y function" | docs-search.sh "Y", docs-search.sh --keyword "Y" | | "Implement authentication" | docs-search.sh "authentication", docs-search.sh "auth" | | "Fix the Z method" | docs-search.sh "Z" --keyword, docs-find-by-type.sh function | | Any API/function name | docs-search.sh "<name>" --keyword |

Usage Examples

Search for Documentation

# Semantic search - finds conceptually related docs
docs-search.sh "authentication flow"
docs-search.sh "how to validate user input"
docs-search.sh "database connection pooling"

# Keyword search - exact term matching
docs-search.sh --keyword "authenticate"
docs-search.sh --keyword "UserController"

Find by Document Type

# Find all function documentation
docs-find-by-type.sh function

# Find all class documentation
docs-find-by-type.sh class

# Find all module/concern documentation
docs-find-by-type.sh module

# Find all interface documentation
docs-find-by-type.sh interface

Get Full Document

# After finding a doc ID from search results
docs-get.sh doc-abc123

# Shows full content including all sections

List and Stats

# List all indexed documents
docs-list.sh

# Get index statistics
docs-stats.sh

Index Documentation

# Index current project (auto-detected from agent config)
docs-index.sh

# Index specific project
docs-index.sh /path/to/project

Delta Index Documentation

# Delta index - only process new and modified files (much faster)
docs-index-delta.sh

# Delta index a specific project
docs-index-delta.sh /path/to/project

Use delta indexing for incremental updates after code changes. Use full docs-index.sh for a complete re-index.

Document Types

The following document types are recognized:

| Type | Description | Sources | |------|-------------|---------| | function | Function/method documentation | JSDoc, RDoc, docstrings | | class | Class documentation | Class-level comments | | module | Module/namespace documentation | Module comments | | interface | Interface/type documentation | TypeScript interfaces | | component | React/Vue component documentation | Component comments | | constant | Documented constants | Constant comments | | readme | README files | README.md, README.txt | | guide | Guide/tutorial documentation | docs/ folder |

Integration with Other Skills

Docs-search works best when combined with other skills:

Combined Search Pattern (RECOMMENDED)

When you receive ANY user instruction:

# 1. Search your memory first
memory-search.sh "topic"

# 2. Search documentation
docs-search.sh "topic"

# 3. Check code structure
graph-describe.sh ComponentName

This gives you complete context:

• Memory: What was discussed before?
• Docs: What does the documentation say?
• Graph: What is the code structure?

Why This Matters

Without searching docs first, you will:

• Use wrong function signatures (then get runtime errors)
• Miss existing implementations (then duplicate code)
• Violate documented patterns (then create inconsistency)
• Misunderstand APIs (then build the wrong thing)

Doc search takes 1 second. Redoing work takes hours.

Helper Scripts

This skill relies on an internal helper script that provides shared utility functions:

• docs-helper.sh - Sourced by the docs-*.sh tool scripts. Provides documentation-specific API functions (docs_query, docs_index) and initialization logic. Located alongside the tool scripts in ~/.local/bin/ (installed) or plugin/src/scripts/ (source). If tool scripts fail with "common.sh not found", re-run the installer (./install-doc-tools.sh).

Error Handling

Script not found:

• Check PATH: which docs-search.sh
• Verify scripts installed: ls -la ~/.local/bin/docs-*.sh
• Scripts are installed to ~/.local/bin/ which should be in your PATH
• If not found, run: ./install-doc-tools.sh

API connection fails:

• Ensure AI Maestro is running: curl http://127.0.0.1:23000/api/hosts/identity
• Ensure documentation has been indexed: docs-stats.sh
• If no docs indexed, run: docs-index.sh

Documentation is empty:

• Check project has documented code (JSDoc, docstrings, comments)
• Verify project path is correct
• Re-index with: docs-index.sh /path/to/project

No results found:

• Inform the user: "No documentation found for X - proceeding with code analysis, but documentation may need to be generated."

Installation

If commands are not found:

./install-doc-tools.sh

This installs scripts to ~/.local/bin/.