teamkb

TeamKB — bounded local Registrar capture

Turn a small, explicit set of durable team insights into local spool proposals. Search before capture, inspect imports before writing, and report proposals as ungoverned until the curator disposes them.

Overview

This self-contained operator workflow uses the full locally built Registrar MCP server. It does not depend on repository subagents, and it does not work with the read-only intent-brain marketplace runtime. Capture and import write candidate files to the local spool; deterministic governance and promotion happen later in the curator.

Prerequisites

• Build and configure apps/mcp-server from the Registrar repository.
• Set TEAMKB_TENANT_ID, TEAMKB_BASE_PATH, and TEAMKB_ROLE=admin.
• Keep TEAMKB_API_URL unset when search and writes must target the same local brain.
• Read the runtime contract for exact bounds and result semantics.

Modes

• capture: distill up to five durable insights from the current session and explicitly supplied files, then propose only new content.
• import GLOB: inspect and explicitly approve 1–20 Markdown files before teamkb_import queues them.
• review QUERY: search only; make no writes.
• status: call teamkb_status; make no writes.

Instructions

Capture a session

1. Review the conversation and use Read, Glob, or Grep only on files the user placed in scope.
2. Select at most five items that would help a teammate after 30 days. Classify each as decision, pattern, convention, architecture, troubleshooting, onboarding, or reference.
3. Reject ephemeral steps, personal preferences, secrets, and facts already maintained in an authoritative README or project instruction file.
4. For each candidate, call teamkb_search with 1–4 keywords and scope: "all". Skip covered facts; surface contradictions instead of creating a competing memory.
5. Call teamkb_propose once for each surviving item. The returned candidate UUID proves only that the local spool write succeeded.

Import Markdown files

1. Require an explicit base directory and glob. Refuse a home directory, repository root, hidden credential directory, or an unresolved environment variable as the base.
2. Use Glob to resolve the exact set. Accept 1–20 .md files; require the user to split larger batches.
3. Use Grep for common secret markers and Read any suspicious file. Exclude credentials, tokens, private keys, environment dumps, and empty files.
4. Show the final relative file list and use AskUserQuestion for explicit confirmation because teamkb_import writes every match to the spool.
5. Call teamkb_import({ glob, basePath }) exactly once. Report queued, failed, and every failed file from outcomes; never claim promotion.

Review or status

• For review, call teamkb_search with curated first and broaden to all only if needed. Cite the exact returned qmd:// URIs.
• For status, call teamkb_status and summarize local counts and recent feedback. Do not print the absolute dbPath unless explicitly requested.

Output

• Mode and local tenant context, without secrets or absolute storage paths.
• Proposed or imported candidate UUIDs, categories, and spool disposition.
• Skipped duplicates, conflicts, rejected files, and reasons.
• Clear statement that queued candidates are not governed memory until curator processing.

Examples

/teamkb capture
Reviewed the session, skipped one README-duplicated fact, and queued two local proposals:
- decision — 4f3a2e0e-0ee4-4f63-b63e-22306c45115a
- pattern — 83e1bc9a-0048-44e7-b70b-52bc7cf6e954
Neither proposal is promoted yet.

/teamkb import docs/runbooks/*.md
Resolved 6 Markdown files. After explicit approval, teamkb_import queued 5 and failed 1; the failed
file and error are reported without claiming a partial batch was fully successful.

/teamkb review deployment rollback
Searched curated memory first and returned two cited runbook results. No write tools were called.

/teamkb status
Reported local lifecycle/category/tenant counts and recent feedback without exposing the database path.

Error Handling

Situation	Response
Write tools are absent	Use the built local server with TEAMKB_ROLE=admin; the shipped marketplace plugin is read-only.
Search is unexpectedly empty	Check the local qmd index and tenant before concluding no memory exists.
Import resolves 0 or more than 20 files	Stop; correct the glob or split the batch.
Secret-like content is found	Exclude the file or redact the candidate before any MCP write.
A spool write fails	Report exact failed outcomes; do not claim they were queued.

Guardrails

• Local operating-system permissions are the write security boundary; TEAMKB_ROLE=admin is a registration gate, not authentication.
• Never broaden an import glob after confirmation.
• Never save secrets or rely solely on downstream policy detection.
• Provenance identifies capture origin, not truth.

Resources

• Bob's Big Brain Registrar — source, build instructions, and governance architecture.
• apps/mcp-server — the full local operator runtime required by this skill.
• brain-save — one-item write workflow; brain — read-only cited-query workflow.