|
| 1 | +--- |
| 2 | +name: qmd markdown search integration |
| 3 | +about: Integrate qmd as a local CLI search engine for docs/knowledge base |
| 4 | +title: 'feat: integrate qmd for markdown document search' |
| 5 | +labels: enhancement |
| 6 | +assignees: '' |
| 7 | +--- |
| 8 | + |
| 9 | +**Is your feature request related to a problem?** |
| 10 | +As the project's documentation base grows (engine reference docs, ADRs, GDDs, skill files, sprint logs), agents spend increasing context and time searching through plain markdown. The project needs a fast, local, agent-friendly search layer that doesn't require shipping content to external APIs. |
| 11 | + |
| 12 | +**Describe the solution you'd like** |
| 13 | + |
| 14 | +Integrate [qmd](https://github.com/tobi/qmd) (Query Markup Documents) — a mini CLI search engine purpose-built for markdown knowledge bases: |
| 15 | + |
| 16 | +1. **Installation** — Add `@tobilu/qmd` as a dev dependency (npm or bun global install). |
| 17 | +2. **Indexing** — Run `qmd index` across key doc directories (`docs/`, `.opencode/agents/`, `.opencode/skills/`, `design/`, `production/`) via a script or pre-commit hook. |
| 18 | +3. **Skill / command** — Create an `.opencode/skills/qmd-search/SKILL.md` skill that teaches agents to use: |
| 19 | + - `qmd search "..."` for fast BM25 keyword search |
| 20 | + - `qmd vsearch "..."` for semantic vector search |
| 21 | + - `qmd query "..."` for hybrid (FTS + vector + re-ranking) best-quality search |
| 22 | +4. **Context hook integration** — Wire into the `ccgs-hooks.ts` plugin so relevant doc snippets are auto-retrieved as session context when an agent loads. |
| 23 | +5. **CI freshness check** — Add a GitHub Action step that validates the qmd index is up-to-date with the doc tree. |
| 24 | + |
| 25 | +**Describe alternatives you've considered** |
| 26 | + |
| 27 | +- **ripgrep / grep** — Fast but no ranking, no semantic search, no relevance scoring. |
| 28 | +- **WebFetch for docs** — Requires network, doesn't work for local/private docs. |
| 29 | +- **Context7 MCP** — Good for external libraries, not for project-internal docs. |
| 30 | +- **Rolling our own FTS** — qmd already bundles BM25 + sqlite-vec embeddings + query expansion + re-ranking in a single CLI. No need to reinvent. |
| 31 | + |
| 32 | +**Additional context** |
| 33 | + |
| 34 | +qmd is authored by tobi (Tobi L.) — well-maintained, MIT-licensed, 24k+ stars. It stores its index in SQLite (FTS5 + sqlite-vec), is fully local, and has no external API dependencies. The `.claude-plugin/` directory in the qmd repo suggests it was designed with AI agent integration in mind. |
0 commit comments