nixos-config/profiles/opencode/skill/librarian/references/tool-routing.md

Tool Routing

Decision Flowchart

graph TD
    Q[User Query] --> T{Query Type?}
    T -->|Understand/Explain| U[UNDERSTAND]
    T -->|Find/Search| F[FIND]
    T -->|Explore/Architecture| E[EXPLORE]
    T -->|Compare| C[COMPARE]

    U --> U1{Known library?}
    U1 -->|Yes| U2[context7.resolve-library-id]
    U2 --> U3[context7.query-docs]
    U3 --> U4{Need source?}
    U4 -->|Yes| U5[opensrc.fetch → read]
    U1 -->|No| U6[grep_app → opensrc.fetch]

    F --> F1{Specific repo?}
    F1 -->|Yes| F2[opensrc.fetch → grep → read]
    F1 -->|No| F3[grep_app broad search]
    F3 --> F4[opensrc.fetch interesting repos]

    E --> E1[opensrc.fetch]
    E1 --> E2[opensrc.files]
    E2 --> E3[Read entry points]
    E3 --> E4[Create diagram]

    C --> C1["opensrc.fetch([X, Y])"]
    C1 --> C2[grep same pattern]
    C2 --> C3[Read comparable files]
    C3 --> C4[Synthesize comparison]

Query Type Detection

Keywords	Query Type	Start With
"how does", "why does", "explain", "purpose of"	UNDERSTAND	context7
"find", "where is", "implementations of", "examples of"	FIND	grep_app
"explore", "walk through", "architecture", "structure"	EXPLORE	opensrc
"compare", "vs", "difference between"	COMPARE	opensrc

UNDERSTAND Queries

Known library? → context7.resolve-library-id → context7.query-docs
                 └─ Need source? → opensrc.fetch → read

Unknown?      → grep_app search → opensrc.fetch top result → read

When to transition context7 → opensrc:

• Need implementation details (not just API docs)
• Question about internals/private methods
• Tracing code flow through library

FIND Queries

Specific repo? → opensrc.fetch → opensrc.grep → read matches

Broad search?  → grep_app → analyze → opensrc.fetch interesting repos

grep_app query tips:

• Use literal code patterns: useState( not "react hooks"
• Filter by language: language: ["TypeScript"]
• Narrow by repo: repo: "vercel/" for org

EXPLORE Queries

1. opensrc.fetch(target)
2. opensrc.files → understand structure
3. Identify entry points: README, package.json, src/index.*
4. Read entry → internals
5. Create architecture diagram

COMPARE Queries

1. opensrc.fetch([X, Y])
2. Extract source.name from each result
3. opensrc.grep same pattern in both
4. Read comparable files
5. Synthesize → comparison table

Tool Capabilities

Tool	Best For	Not For
grep_app	Broad search, unknown scope, finding repos	Semantic queries
context7	Library APIs, best practices, common patterns	Library internals
opensrc	Deep exploration, reading internals, tracing flow	Initial discovery

Anti-patterns

Don't	Do
grep_app for known library docs	context7 first
opensrc.fetch before knowing target	grep_app to discover
Multiple small reads	opensrc.readMany batch
Describe without linking	Link every file ref
Text for complex relationships	Mermaid diagram
Use tool names in responses	"I'll search..." not "I'll use opensrc"