Design: Capy Knowledge Base Integration

Issue: serpro69/claude-toolbox#44 Status: draft Created: 2026-04-01

Problem

The kk plugin's skills execute in isolated sessions with no cross-session memory. Architecture decisions made during analysis-process, review findings from solid-code-review, testing patterns discovered during testing-process — all lost when the conversation ends. Each new session starts from scratch.

Solution

Integrate capy's persistent FTS5 knowledge base into the kk plugin's skill system. Skills become knowledge-aware — they search for relevant context before executing and index valuable learnings after producing output. Knowledge persists across sessions per-project.

Architecture

Trigger vs. Taxonomy Hybrid

The integration follows a "Trigger vs. Taxonomy" pattern that balances LLM prompt effectiveness with maintainability:

• Taxonomy (shared) — A single protocol file defines the namespaced source labels, search conventions, and indexing conventions. All skills reference this for consistency.
• Triggers (per-skill) — Each skill contains explicit, actionable steps — "search capy for X", "index this as Y". No vague indirection.

Source Label Taxonomy

All plugin-managed labels use the kk: namespace prefix to separate from user-indexed content.

Relationship to Static References

The solid-code-review skill's existing static reference files (reference/go/solid-checklist.md, etc.) remain unchanged. They are curated, version-controlled, and always available with no cold-start problem. Capy provides a supplementary dynamic layer — project-specific learnings, accumulated findings, fetched external resources. The two complement each other.

Graceful Degradation

Capy is not a hard dependency. All skill modifications are written so that if capy MCP is not available:

• Search triggers return nothing — the cold-start fallback kicks in ("if no results, proceed with standard guidelines")
• Index steps are simply skipped
• Skills work exactly as they do today

The shared protocol file states this principle once; skills inherit the behavior.

Per-Skill Integration

Every skill gets a search phase (at workflow start) and an index phase (after producing valuable output).

analysis-process

• Search: Before refining the idea (Step 3), search kk:arch-decisions and kk:project-conventions for prior design context relevant to the feature area.
• Index: After documenting the design (Step 5), index key architecture decisions and trade-offs as kk:arch-decisions.

implementation-process

• Search: During plan review (Step 1), search kk:arch-decisions, kk:project-conventions, kk:lang-idioms, and kk:review-findings for context relevant to the task being implemented.
• Index: After completing a task (Step 3), if a non-obvious pattern or convention was established during implementation, index it as kk:project-conventions.

solid-code-review

• Search: During preflight context (Step 1), search kk:review-findings for prior findings in the same area, and kk:lang-idioms for language-specific best practices. If kk:lang-idioms has no results for the detected language, optionally capy_fetch_and_index a well-known idioms resource (e.g., Effective Go) and label it kk:lang-idioms.
• Index: After self-check (Step 7), index any P0/P1 findings that reveal recurring patterns as kk:review-findings.

testing-process

• Search: Before applying test guidelines, search kk:test-patterns for project-specific testing approaches and known edge cases.
• Index: If a novel testing approach or tricky edge case is discovered, index as kk:test-patterns.

development-guidelines

• Search: Before consulting context7 for external dependency docs, search kk:lang-idioms and kk:project-conventions for previously indexed knowledge about the dependency.
• Index: If context7 or web search yields a valuable best-practice nugget that isn't obvious from the docs themselves, index as kk:lang-idioms.

implementation-review

• Search: During "Load feature documents" phase, search kk:arch-decisions for design rationale that may explain intentional spec deviations. Also search kk:review-findings for known patterns from prior reviews.
• Index: After presenting findings, index any SPEC_DEV or EXTRA_IMPL findings confirmed by the user as intentional — save as kk:arch-decisions to prevent the same deviation from being flagged again.

documentation-process

• Search: Before writing docs, search kk:arch-decisions and kk:project-conventions for context that should be reflected in documentation — decisions not obvious from code alone.
• Index: None — this skill consumes knowledge but doesn't typically produce new knowledge worth persisting.

merge-docs

• Search: Before merging competing design docs, search kk:arch-decisions for prior decisions that might inform which approach to favor.
• Index: After producing the merged document, if the merge resolved a genuine architectural conflict, index the resolution rationale as kk:arch-decisions.

cove

• Search (standard mode — cove-process.md): During Step 3 (Independent Verification), search kk: broadly as another tool source alongside WebSearch and context7.
• Search (isolated mode — cove-isolated.md): Do NOT inject capy results into sub-agent prompts — curating and injecting results leaks the main agent's framing. Sub-agents may independently query capy as part of their own tool-first research (capy is project state, not context — blinding verifiers to project ground truth produces false negatives).
• Search (reconciliation — both modes): During Step 4, search kk: broadly to help adjudicate contradicted or inconclusive claims.
• Index: Strictly prohibited. capy_index and capy_fetch_and_index must not be called during the CoVe workflow. CoVe is a read-only verification tool — if corrections reveal knowledge worth persisting, the calling agent handles indexing after CoVe completes.

Bootstrapping

Bootstrap Integration

The template's .github/scripts/bootstrap.sh gains a capy setup step:

1. Check if capy binary is on PATH
2. If found: run capy setup to configure MCP server, hooks, and guidance files
3. If not found: print a warning — "capy not found on PATH, skipping knowledge base setup. Install from https://github.com/serpro69/capy"
4. Opt-out: SKIP_CAPY=1 ./bootstrap.sh or --no-capy flag skips the capy step entirely

README Updates

Add capy to the MCP Servers table alongside Context7, Serena, and Pal. Add a brief section explaining the knowledge base integration — what it does, how skills use it, how to install.