first commit

plugins/document-navigator/.claude-plugin/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "document-navigator",
+  "version": "1.0.0",
+  "description": "Natural-language documentation discovery across the 500+ @suaveplan/* packages"
+}

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

@@ -0,0 +1,88 @@
+---
+name: sp
+description: 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
+
+```bash
+# 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.