| name | kb-capture-codebase |
| description | Use when the user asks to capture, map, document, preserve, or add a repo area, codebase flow, subsystem, architecture path, runbook, or work topic into the local AI knowledge base. |
Capture Codebase Knowledge
Capture focused repo understanding into ~/.config/ai/knowledge-base so future agents can reuse it.
Rules
- KB root:
~/.config/ai/knowledge-base.
- Global KB only by default. Do not create repo-local docs unless the user asks.
- Work-private by default:
visibility: work-private, allowed_llm: ask.
- Never store secrets, tokens, private keys, credentialed logs, raw customer data, or full transcripts.
- Durable claims need evidence:
repo@commit:path:line or repo@commit:path#symbol.
- Do not run tests/builds unless explicitly asked. Record discovered commands and whether they were run.
Workflow
- Capture intent: repo path, question/flow, scope, target wiki.
- Privacy preflight: sensitivity, hosted-model allowance, secret/PII risk.
- Record repo identity: local path, remote URL, branch, commit SHA, dirty status, selected scope.
- Explore narrowly. For broad areas, dispatch focused agents for structure, flow, domain vocabulary, tests/checks, and gotchas.
- Write one raw artifact at
raw/work/codebase-explorations/YYYY-MM-DD-<repo>-<area>.md using templates/codebase-exploration.md.
- Update the relevant wiki, usually
wikis/work-polygraph or wikis/agent-workflows:
- add source link under
sources/ only if useful
- update concepts/projects/runbooks/patterns/questions with reusable knowledge
- append
log.md
- Report changed KB files and stale/unknown areas.
Capture quality bar
Include:
- question and scope
- repo identity and commit boundary
- architecture map
- important files/symbols
- control/data flow
- domain vocabulary
- conventions
- tests/checks/commands discovered
- gotchas
- open questions
- evidence list
- suggested wiki updates
Avoid:
- copying large code blocks
- dumping search results
- unsourced architecture claims
- treating a quick scan as complete truth
- mixing multiple unrelated areas in one capture
If the user says “be quick”
Still record repo identity, privacy defaults, source evidence, and open questions. Speed reduces scope, not provenance.
