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 <noreply@anthropic.com>
This commit is contained in:
Levi Neely
parent
88c68720bf
commit
0367aa58fc
|
|
@ -55,7 +55,23 @@ Workflow:
|
|||
7. Check if ALL children are complete by reading "9p read agent/beads/children/<parent-id> | 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 "<keyword>" ~/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 <backend> <workdir>" | 9p write agent/ctl
|
||||
|
|
|
|||
|
|
@ -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 "<keyword>" ~/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 <keywords> ~/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 ""
|
||||
|
|
|
|||
|
|
@ -0,0 +1,27 @@
|
|||
## KB Protocol
|
||||
|
||||
Before starting any task, search the knowledge base for relevant context:
|
||||
|
||||
```bash
|
||||
grep -ril "<keyword>" ~/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: <what changed>`.
|
||||
|
|
@ -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: <what changed>`.
|
||||
|
||||
## Updating KB Entries
|
||||
|
||||
|
|
|
|||
|
|
@ -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 "<keyword>" ~/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 "<keyword>" ~/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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
```
|
||||
Reference in New Issue