skills/plugins/document-navigator/skills/sp/SKILL.md

name, description

name	description
sp	Navigate the 500+ @suaveplan/* packages to find libraries matching a stated development need. Extracts code examples from the mirrored docs tree.

Document Navigator for Suaveplan

Match natural-language intent to @suaveplan/* packages and extract working code examples from the in-repo documentation tree.

Architecture

Layer	Source
User intent	Natural language via /sp or direct invocation
Package index	packages/README.md → category READMEs → subcategory READMEs → package READMEs
Docs tree	.claude/plugins/suaveplan-skills/docs/ (.md-only mirror of packages/, maintained externally)
Examples	Linked .md files inside each package (src/**/*.md)

File Structure

.claude/plugins/suaveplan-skills/
  docs/                          # mirrored .md tree (maintained externally)
    <category>/
      README.md
      <subcategory>/
        README.md
        <package>/
          README.md
          src/
            <module>.md
  plugins/document-navigator/
    skills/sp/
      SKILL.md                   # this file

Patterns

Discovering packages by keyword

# Search package names and descriptions
grep -ri "sms" .claude/plugins/suaveplan-skills/docs/*/README.md

# Search all module documentation
grep -ri "twilio" .claude/plugins/suaveplan-skills/docs/

Traversing the hierarchy

The documentation is a four-tier chain. Each tier summarizes its children and links to their READMEs:

1. Root index — packages/README.md

   • Lists every category with a one-line summary.
   • Links to each packages/<category>/README.md.

2. Category index — packages/<category>/README.md

   • Lists every subcategory with a one-line summary.
   • Links to each packages/<category>/<subcategory>/README.md.

3. Subcategory index — packages/<category>/<subcategory>/README.md

   • Contains a table of every package in that subcategory.
   • Each row has the package name, a one-line description, and a link to packages/<category>/<subcategory>/<pkg>/README.md.
   • Read this to identify candidate packages before drilling deeper.

4. Package README — packages/<category>/<subcategory>/<pkg>/README.md

   • Full description, install command (bun add @suaveplan/<name>), and quick-start code block.
   • Contains a documentation tree that links to every module-level .md file inside src/.
   • Follow those links to find API usage patterns and typed examples.

Extracting examples from module docs

Module .md files (e.g., src/analysis/analysis-op.md) contain API usage patterns. Read these to answer "how do I use X?" questions.

Constraints

• Only reference packages that exist nested within packages/. Do not invent package names.
• Use exact @suaveplan/<name> identifiers from package.json.
• Extract code examples verbatim from .md files; do not fabricate import paths.
• Assume the docs tree is current; do not concern yourself with how it is maintained.

Checklist

1. User intent is parsed into domain, runtime, integration, and pattern needs.
2. Category and subcategory READMEs are consulted before drilling into package READMEs.
3. Top matches are ranked with a stated reason for each.
4. Code examples are pulled from the docs tree, not invented.
5. Cross-package composition is explained when the need spans multiple packages.