# Capy Knowledge Base Protocol

If `capy` MCP tools are not available in this session, skip all search and index steps below and proceed normally.

## Source Label Taxonomy

All plugin-managed labels use the `kk:` namespace prefix.

| Label                    | Contents                                                              |
| ------------------------ | --------------------------------------------------------------------- |
| `kk:arch-decisions`      | Architecture decisions, design rationale, trade-offs                  |
| `kk:review-findings`     | Code review patterns, recurring issues, anti-patterns                 |
| `kk:lang-idioms`         | Language best practices, idiomatic patterns from external sources     |
| `kk:project-conventions` | Discovered project patterns, naming conventions, structural decisions |
| `kk:test-patterns`       | Testing approaches, edge cases, test infrastructure decisions         |
| `kk:debug-context`       | Root causes, tricky bugs and their fixes, environment gotchas         |

## Search Conventions

- Use 2-4 specific terms per query — not vague keywords
- Always scope with `source` filter to relevant `kk:*` labels
- Use `source: "kk:"` only for broad cross-domain searches (e.g., CoVe verification)
- Default `limit: 3` per query unless more context is needed
- **Cold-start fallback:** If no results, proceed with standard guidelines — empty results are normal for new projects

## Index Conventions

- Only index non-obvious learnings not derivable from reading the code or git history
- Keep content concise — summarize the insight, don't dump raw output
- Always use a `kk:` prefixed label from the taxonomy above
- One concept per `capy_index` call — don't bundle unrelated learnings
- Skip indexing if the insight is already captured in design docs or CLAUDE.md

---
name: dependency-handling
description: |
  TRIGGER when: adding or upgrading any dependency — library, SDK, framework, API, IaC API version (K8s/Terraform/Helm), CRD, or container image. Use BEFORE writing the call. Forces context7/capy lookup instead of guessing.
---
<!-- codex: tool-name mapping applied. See .codex/scripts/session-start.sh -->

# Dependency & External API Handling

## Conventions

- **Read capy knowledge base conventions** at [shared-capy-knowledge-protocol.md](shared-capy-knowledge-protocol.md).

## Workflow

**Mandatory order — lookup before usage.** Do not write, modify, or recommend any call, import, config key, or version specifier involving the dependency until you have completed the lookup cascade below. Guessing a signature or API version and fixing it after the fact is the failure mode this skill exists to prevent.

1. **Extract the dependency identity.** From the calling context, identify the dependency name, the version constraint (declared or inferred), and the specific API surface being used (function, config key, API version, image tag). This is the minimal scope — enough to drive the lookup, not enough to guess the answer.
2. **Capy search.** Search `kk:lang-idioms` and `kk:project-conventions` for previously indexed knowledge about this dependency.
3. **Context7 lookup.** Use the context7 MCP to fetch documentation. The doc version MUST match the declared dependency version.
4. **Web fallback.** Only if context7 has no coverage.
5. **Apply.** With verified knowledge now loaded, write or recommend the call, import, or config.

## Rules

1. **Prefer the latest stable version** when introducing a new dependency. Pin deliberately; don't inherit a stale version by copy-paste.
2. **Never assume how an external dependency behaves.** If you are not 100% sure of the signature, config, or semantics, look it up. Guessing is the failure mode this skill exists to prevent.
3. **Capy search first.** Before hitting external docs, search `kk:lang-idioms` and `kk:project-conventions` for previously indexed knowledge about the dependency.
4. **Context7 second.** Use the context7 MCP to fetch documentation for libraries, SDKs, APIs, and frameworks.
   - **IMPORTANT:** the doc version MUST match the declared dependency version. A right answer against the wrong version is a wrong answer.
   - Only fall back to web search if context7 has no coverage.
5. **Index what you learn.** If context7 or web search yields a best-practice nugget that isn't obvious from the docs themselves, index it as `kk:lang-idioms` so the next agent doesn't pay the lookup cost again.

## IaC and config artifacts

The cascade rule (capy-first, context7-second, web-last) applies uniformly to all dependency categories — libraries, SDKs, frameworks, APIs, IaC API versions, CRDs, Helm charts, and container images. Per-domain lookup targets (which context7 library to query, which local command to run, which registry to consult) live in each profile's `overview.md` under a "Looking up dependencies" heading. When the `k8s` profile is active, consult `../../profiles/k8s/overview.md` under the `## Looking up Kubernetes dependencies` heading for Kubernetes API versions, third-party CRDs, Helm chart versions, and container image targets.