From 0367aa58fcb4fc969b68bcc4fb5c400ab91c2440 Mon Sep 17 00:00:00 2001 From: Levi Neely Date: Tue, 24 Feb 2026 07:45:38 +0100 Subject: [PATCH] Add KB protocol integration across bot templates and skills - Add _kb-protocol.md shared protocol document for KB usage rules - Integrate KB protocol into Conductor and Taskmaster bot templates - Add denote skill (file naming/frontmatter conventions) - Refactor agent-kb SKILL.md to defer file naming to denote skill - Add staleness handling table to agent-kb SKILL.md - Update beads SKILL.md workflow to include KB lookup step Co-Authored-By: Claude Sonnet 4.6 --- bot-templates/Conductor | 18 ++++++++- bot-templates/Taskmaster | 31 ++++++++++++++- bot-templates/_kb-protocol.md | 27 +++++++++++++ skills/agent-kb/SKILL.md | 65 ++++++++++-------------------- skills/beads/SKILL.md | 18 +++++++-- skills/denote/SKILL.md | 75 +++++++++++++++++++++++++++++++++++ 6 files changed, 184 insertions(+), 50 deletions(-) create mode 100644 bot-templates/_kb-protocol.md create mode 100644 skills/denote/SKILL.md diff --git a/bot-templates/Conductor b/bot-templates/Conductor index 49ecfb3..8992f5d 100755 --- a/bot-templates/Conductor +++ b/bot-templates/Conductor @@ -55,7 +55,23 @@ Workflow: 7. Check if ALL children are complete by reading "9p read agent/beads/children/ | jq 'all(.status == \"closed\")'" 8. Only mark the parent bead complete when all children have status==closed -Core skills: beads, anvillm-communication +Core skills: beads, anvillm-communication, agent-kb + +## KB Protocol + +Before starting any task, search the knowledge base for relevant context: + + grep -ril "" ~/doc/agent-kb/ + +Extract keywords from the bead title and description. Read all relevant hits before touching any source file. + +Rules: +1. On session start: search KB with keywords from the assigned bead title/description. Read all relevant hits before touching any source file. +2. Before ANY file exploration: check KB first. If KB has a file path or function name, use it directly. +3. After a significant discovery: write a KB entry immediately using the agent-kb skill write-back format. +4. On task completion (mandatory): write KB entries for anything discovered not already in KB. + +Staleness: trust entries verified within 30 days; treat 31-90 days as potentially stale; verify 90+ day entries against source before acting. When creating a bot: 1. Start the session: echo "new " | 9p write agent/ctl diff --git a/bot-templates/Taskmaster b/bot-templates/Taskmaster index 7a00a0e..6fc7732 100755 --- a/bot-templates/Taskmaster +++ b/bot-templates/Taskmaster @@ -39,9 +39,38 @@ When sending PROMPT_RESPONSE, use: Status / Beads / Errors / Notes (only if acti ## Role -You are a task management specialist. Do not implement solutions or write code. Core skills: beads, anvillm-communication. +You are a task management specialist. Do not implement solutions or write code. Core skills: beads, anvillm-communication, agent-kb. You create and update tasks based on requirements using the beads skill, and pull context from Jira, GitHub, web search, or agent-kb to enrich details. You maintain clear descriptions and link sources. + +## KB Protocol + +Before starting any task, search the knowledge base for relevant context: + + grep -ril "" ~/doc/agent-kb/ + +Extract keywords from the bead title and description. Read all relevant hits before touching any source file. + +Rules: +1. On session start: search KB with keywords from the assigned bead title/description. Read all relevant hits before touching any source file. +2. Before ANY file exploration: check KB first. If KB has a file path or function name, use it directly. +3. After a significant discovery: write a KB entry immediately using the agent-kb skill write-back format. +4. On task completion (mandatory): write KB entries for anything discovered not already in KB. + +Staleness: trust entries verified within 30 days; treat 31-90 days as potentially stale; verify 90+ day entries against source before acting. + +## KB Enrichment at Bead Creation + +When creating a bead: +1. Extract technical keywords from the task title and intent. +2. Search KB: grep -ril ~/doc/agent-kb/ +3. For each relevant KB hit: + - Extract file paths → add to Where field of the bead description + - Extract function names → add to How field (pattern to follow) + - Extract architectural notes → add to description context +4. Write the bead with this enriched Where/How content. + +This amortizes KB lookup cost at creation time — the implementing agent inherits file paths and patterns without needing to discover them. EOF echo "" diff --git a/bot-templates/_kb-protocol.md b/bot-templates/_kb-protocol.md new file mode 100644 index 0000000..120cbd8 --- /dev/null +++ b/bot-templates/_kb-protocol.md @@ -0,0 +1,27 @@ +## KB Protocol + +Before starting any task, search the knowledge base for relevant context: + +```bash +grep -ril "" ~/doc/agent-kb/ +``` + +Extract keywords from the bead title and description (technical terms, file names, feature names, system names). Run multiple searches for different keywords. Read any matching entries in full. + +**Rules:** + +1. **On session start**: Search KB with keywords from the assigned bead title/description. Read all relevant hits before touching any source file. + +2. **Before ANY file exploration**: Check KB first. If KB has a file path or function name relevant to the task, use it directly. Do not read files speculatively when KB provides the answer. + +3. **After a significant discovery** (new file location, architectural insight, pattern, gotcha): Write a KB entry immediately using the agent-kb skill write-back format. + +4. **On task completion (mandatory)**: Review what you learned during the task. Write KB entries for anything discovered that is not already in KB. Tag entries with relevant keywords so future agents can find them. + +**Staleness handling:** + +- `verified` date within 30 days: trust the entry, use directly +- `verified` date 31–90 days old: use with caution, flag as potentially stale +- `verified` date 90+ days old: verify against source code before acting on it; update `verified` date in frontmatter if confirmed, or correct the entry if wrong + +When you confirm a KB entry is still accurate, update its `verified` date. When you find a wrong entry, correct it and add a note: `Updated YYYY-MM-DD: `. diff --git a/skills/agent-kb/SKILL.md b/skills/agent-kb/SKILL.md index 119f91e..6031920 100644 --- a/skills/agent-kb/SKILL.md +++ b/skills/agent-kb/SKILL.md @@ -3,6 +3,11 @@ name: agent-kb description: Query and maintain a local knowledge base of code insights and architecture notes. Use when encountering unfamiliar code, needing context beyond training, or when asked to save/update learned knowledge. --- +## Required Skills + +This skill requires the **denote** skill for file naming and frontmatter conventions. +Load and follow: `/home/lkn/.claude/skills/denote/SKILL.md` + # Agent Knowledge Base ## Purpose @@ -66,58 +71,30 @@ After significant code exploration, consider what was learned: 4. Read relevant entries before researching code. -## File Naming Convention - -``` -YYYYMMDDThhmmss--title-in-lowercase-alphanumeric__tag1_tag2_tagN.md -``` - -- Timestamp: `date +%Y%m%dT%H%M%S` -- Title: lowercase, alphanumeric, hyphens only -- Tags: lowercase alphanumeric, underscore-separated, after double-underscore, no hyphens - ``` - -Examples: -- `20260128T133522--example-flow__ref.md` -- `20260126T144226---architecture-notes__component1_component2_tag3.md` - ## Creating KB Entries -1. Generate timestamp: - ```bash - date +%Y%m%dT%H%M%S - ``` +See the **denote** skill for file naming convention and frontmatter format. -2. Create file with frontmatter matching filename: - ```markdown - --- - title: Title In Title Case - date: YYYY-MM-DD Day HH:MM - tags: [tag1, tag2] - identifier: YYYYMMDDThhmmss - verified: YYYY-MM-DD - source: code-inspection | documentation | online | verbal | inferred - --- +1. Generate timestamp: `date +%Y%m%dT%H%M%S` +2. Create file using Denote naming convention with `.md` extension +3. Add frontmatter (see denote skill for fields: `title`, `date`, `tags`, `identifier`, `verified`, `source`) +4. Keep entries focused—one topic per file. +5. **Link to other KB entries using `denote:{identifier}`** - e.g., "See denote:20260130T171856 for query details" +6. **Don't automatically follow cross-references** - Only load referenced documents if directly relevant to the current question. - # Title +## Staleness Handling - Content here. - ``` +KB entries carry a `verified` date in frontmatter. Apply these thresholds when reading entries: - **Provenance fields:** - - `verified`: Date last confirmed against code (update on confirmation) - - `source`: How the knowledge was obtained - - `code-inspection` - directly verified in source code - - `documentation` - from internal docs (Confluence, etc.) - - `online` - from external online documentation - - `verbal` - expert opinion, discussion, tacit knowledge - - `inferred` - derived from training data (lowest priority) +| Age | Action | +|-----|--------| +| Within 30 days | Trust entry, use directly | +| 31–90 days | Use with caution; flag as potentially stale | +| 90+ days | Verify against source code before acting; do not use blindly | - If a source has a URL (online or documentation), add a `## Sources` section at the bottom of the document with the citation(s). +**When you confirm an entry is still accurate**: update the `verified` date in frontmatter. -3. Keep entries focused—one topic per file. -4. **Link to other KB entries using `denote:{identifier}`** - e.g., "See denote:20260130T171856 for query details" -5. **Don't automatically follow cross-references** - Only load referenced documents if directly relevant to the current question. +**When you find an entry is wrong**: correct the content, update `verified`, and add a note on the last line: `Updated YYYY-MM-DD: `. ## Updating KB Entries diff --git a/skills/beads/SKILL.md b/skills/beads/SKILL.md index 01de809..d2092d0 100644 --- a/skills/beads/SKILL.md +++ b/skills/beads/SKILL.md @@ -120,9 +120,10 @@ To determine if a parent bead has incomplete child tasks, query the children end ### Recommended Workflow 1. Check ready work: `9p read agent/beads/ready` 2. Claim an unblocked bead: `echo "claim bd-xyz $AGENT_ID" | 9p write agent/beads/ctl` -3. Do the work -4. Complete it: `echo "complete bd-xyz" | 9p write agent/beads/ctl` -5. Completing a bead unblocks its dependents +3. Search KB for relevant context: `grep -ril "" ~/doc/agent-kb/` +4. Do the work (using KB-sourced file paths and patterns where available) +5. Complete it: `echo "complete bd-xyz" | 9p write agent/beads/ctl` +6. Completing a bead unblocks its dependents ## Leaving Context for Future Agents @@ -250,7 +251,16 @@ All operations immediately persist to the database. Agents can resume work after echo "claim bd-abc $AGENT_ID" | 9p write agent/beads/ctl ``` -3. **Work**: Perform the task +3. **Before You Start**: Search the knowledge base for relevant context before doing anything else + ```bash + # Extract keywords from the bead title and description (technical terms, file names, feature names) + grep -ril "" ~/doc/agent-kb/ + ``` + Read all matching entries in full. If KB has a file path or function name relevant to the task, use it directly — do not perform speculative file reads when KB provides the answer. + + Staleness: trust entries verified within 30 days; treat 31–90 days as potentially stale; verify 90+ day entries against source before acting. + +4. **Work**: Perform the task 4. **Complete**: Atomically complete the bead ```bash diff --git a/skills/denote/SKILL.md b/skills/denote/SKILL.md new file mode 100644 index 0000000..6699cdc --- /dev/null +++ b/skills/denote/SKILL.md @@ -0,0 +1,75 @@ +--- +name: denote +description: Denote file format conventions for timestamped notes. Use when creating, naming, or linking structured note files in the ~/doc/ hierarchy. +--- + +# Denote File Format + +Denote is an Emacs structured note-taking system by Protesilaos Stavrou. It uses a strict filename convention to encode metadata. + +## File Naming Convention + +``` +YYYYMMDDThhmmss--title-in-lowercase-alphanumeric__tag1_tag2_tagN.ext +``` + +Components: +- **Timestamp**: `date +%Y%m%dT%H%M%S` — ISO 8601 compact, seconds precision +- **Title**: lowercase, alphanumeric characters and hyphens only (no spaces, no underscores) +- **Tags**: lowercase alphanumeric, underscore-separated, after double-underscore, no hyphens in individual tags + +Examples: +- `20260128T133522--example-flow__ref.md` +- `20260126T144226--architecture-notes__component1_component2_tag3.md` + +## Frontmatter Format + +Every Denote file begins with YAML frontmatter that mirrors the filename: + +```markdown +--- +title: Title In Title Case +date: YYYY-MM-DD Day HH:MM +tags: [tag1, tag2] +identifier: YYYYMMDDThhmmss +verified: YYYY-MM-DD +source: code-inspection | documentation | online | verbal | inferred +--- + +# Title + +Content here. +``` + +**Provenance fields** (for agent-kb entries): +- `verified`: Date last confirmed against code (update on confirmation) +- `source`: How the knowledge was obtained + - `code-inspection` — directly verified in source code + - `documentation` — from internal docs + - `online` — from external online documentation + - `verbal` — expert opinion, discussion, tacit knowledge + - `inferred` — derived from training data (lowest priority) + +If a source has a URL, add a `## Sources` section at the bottom. + +## Cross-References + +Link to other Denote entries using the identifier: + +``` +See denote:20260130T171856 for query details. +``` + +**Do not automatically follow cross-references.** Only load referenced documents if directly relevant to the current question. + +## Looking Up an Entry by Identifier + +```bash +grep -r "20260130T171856" ~/doc/agent-kb/ +``` + +Or search by keyword: + +```bash +grep -il "keyword" ~/doc/agent-kb/*.md +```