feat: complete bd-kwro messaging & knowledge graph epic
- Add bd cleanup --ephemeral flag for transient message cleanup (bd-kwro.9) - Add Ephemeral filter to IssueFilter type - Add ephemeral filtering to SQLite storage queries Tests (bd-kwro.10): - Add internal/hooks/hooks_test.go for hook system - Add cmd/bd/mail_test.go for mail commands - Add internal/storage/sqlite/graph_links_test.go for graph links Documentation (bd-kwro.11): - Add docs/messaging.md for full messaging reference - Add docs/graph-links.md for graph link types - Update AGENTS.md with inter-agent messaging section - Update CHANGELOG.md with all bd-kwro features 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Steve Yegge
278
docs/graph-links.md
Normal file
278
docs/graph-links.md
Normal file
@@ -0,0 +1,278 @@
|
||||
# Graph Links in Beads
|
||||
|
||||
Beads supports several types of links between issues to create a knowledge graph. These links enable rich querying and traversal beyond simple blocking dependencies.
|
||||
|
||||
## Link Types
|
||||
|
||||
### replies_to - Conversation Threading
|
||||
|
||||
Creates message threads, similar to email or chat conversations.
|
||||
|
||||
**Created by:**
|
||||
- `bd mail reply <id>` command
|
||||
|
||||
**Use cases:**
|
||||
- Agent-to-agent message threads
|
||||
- Discussion chains on issues
|
||||
- Follow-up communications
|
||||
|
||||
**Example:**
|
||||
|
||||
```bash
|
||||
# Original message
|
||||
bd mail send worker-1 -s "Review needed" -m "Please review bd-xyz"
|
||||
# Creates: bd-a1b2
|
||||
|
||||
# Reply (automatically sets replies_to: bd-a1b2)
|
||||
bd mail reply bd-a1b2 -m "Done! Approved with minor comments."
|
||||
# Creates: bd-c3d4 with replies_to: bd-a1b2
|
||||
```
|
||||
|
||||
**Viewing threads:**
|
||||
|
||||
```bash
|
||||
bd show bd-a1b2 --thread
|
||||
```
|
||||
|
||||
### relates_to - Loose Associations
|
||||
|
||||
Bidirectional "see also" links between related issues. Not blocking, not hierarchical - just related.
|
||||
|
||||
**Created by:**
|
||||
- `bd relate <id1> <id2>` - Links both issues to each other
|
||||
|
||||
**Removed by:**
|
||||
- `bd unrelate <id1> <id2>` - Removes link in both directions
|
||||
|
||||
**Use cases:**
|
||||
- Cross-referencing related features
|
||||
- Linking bugs to associated tasks
|
||||
- Building knowledge graphs
|
||||
- "See also" connections
|
||||
|
||||
**Example:**
|
||||
|
||||
```bash
|
||||
# Link two related issues
|
||||
bd relate bd-auth bd-security
|
||||
# Result: bd-auth.relates_to includes bd-security
|
||||
# bd-security.relates_to includes bd-auth
|
||||
|
||||
# View related issues
|
||||
bd show bd-auth
|
||||
# Shows: Related: bd-security
|
||||
|
||||
# Remove the link
|
||||
bd unrelate bd-auth bd-security
|
||||
```
|
||||
|
||||
**Multiple links:**
|
||||
An issue can have multiple relates_to links:
|
||||
|
||||
```bash
|
||||
bd relate bd-api bd-auth
|
||||
bd relate bd-api bd-docs
|
||||
bd relate bd-api bd-tests
|
||||
# bd-api now relates to 3 issues
|
||||
```
|
||||
|
||||
### duplicates - Deduplication
|
||||
|
||||
Marks an issue as a duplicate of a canonical issue. The duplicate is automatically closed.
|
||||
|
||||
**Created by:**
|
||||
- `bd duplicate <id> --of <canonical>`
|
||||
|
||||
**Use cases:**
|
||||
- Consolidating duplicate bug reports
|
||||
- Merging similar feature requests
|
||||
- Database deduplication at scale
|
||||
|
||||
**Example:**
|
||||
|
||||
```bash
|
||||
# Two similar bug reports exist
|
||||
bd show bd-bug1 # "Login fails on Safari"
|
||||
bd show bd-bug2 # "Safari login broken"
|
||||
|
||||
# Mark bug2 as duplicate of bug1
|
||||
bd duplicate bd-bug2 --of bd-bug1
|
||||
# Result: bd-bug2 is closed with duplicate_of: bd-bug1
|
||||
|
||||
# View shows the relationship
|
||||
bd show bd-bug2
|
||||
# Status: closed
|
||||
# Duplicate of: bd-bug1
|
||||
```
|
||||
|
||||
**Behavior:**
|
||||
- Duplicate issue is automatically closed
|
||||
- Original (canonical) issue remains open
|
||||
- `duplicate_of` field stores the canonical ID
|
||||
|
||||
### supersedes - Version Chains
|
||||
|
||||
Marks an issue as superseded by a newer version. The old issue is automatically closed.
|
||||
|
||||
**Created by:**
|
||||
- `bd supersede <old-id> --with <new-id>`
|
||||
|
||||
**Use cases:**
|
||||
- Design document versions
|
||||
- Spec evolution
|
||||
- Artifact versioning
|
||||
- RFC chains
|
||||
|
||||
**Example:**
|
||||
|
||||
```bash
|
||||
# Original design doc
|
||||
bd create --title "Design Doc v1" --type task
|
||||
# Creates: bd-doc1
|
||||
|
||||
# Later, create updated version
|
||||
bd create --title "Design Doc v2" --type task
|
||||
# Creates: bd-doc2
|
||||
|
||||
# Mark v1 as superseded
|
||||
bd supersede bd-doc1 --with bd-doc2
|
||||
# Result: bd-doc1 closed with superseded_by: bd-doc2
|
||||
|
||||
# View shows the chain
|
||||
bd show bd-doc1
|
||||
# Status: closed
|
||||
# Superseded by: bd-doc2
|
||||
```
|
||||
|
||||
**Behavior:**
|
||||
- Old issue is automatically closed
|
||||
- New issue remains in its current state
|
||||
- `superseded_by` field stores the replacement ID
|
||||
|
||||
## Schema Fields
|
||||
|
||||
These fields are added to issues:
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `replies_to` | string | ID of parent message (threading) |
|
||||
| `relates_to` | []string | IDs of related issues (bidirectional) |
|
||||
| `duplicate_of` | string | ID of canonical issue |
|
||||
| `superseded_by` | string | ID of replacement issue |
|
||||
|
||||
## Querying Links
|
||||
|
||||
### View Issue Details
|
||||
|
||||
```bash
|
||||
bd show <id>
|
||||
```
|
||||
|
||||
Shows all link types for an issue:
|
||||
|
||||
```
|
||||
bd-auth: Implement authentication
|
||||
Status: open
|
||||
Priority: P1
|
||||
|
||||
Related to (3):
|
||||
bd-security: Security audit
|
||||
bd-users: User management
|
||||
bd-sessions: Session handling
|
||||
```
|
||||
|
||||
### View Threads
|
||||
|
||||
```bash
|
||||
bd show <id> --thread
|
||||
```
|
||||
|
||||
Follows `replies_to` chain to show conversation history.
|
||||
|
||||
### JSON Output
|
||||
|
||||
```bash
|
||||
bd show <id> --json
|
||||
```
|
||||
|
||||
Returns all fields including graph links:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "bd-auth",
|
||||
"title": "Implement authentication",
|
||||
"relates_to": ["bd-security", "bd-users", "bd-sessions"],
|
||||
"duplicate_of": "",
|
||||
"superseded_by": ""
|
||||
}
|
||||
```
|
||||
|
||||
## Comparison with Dependencies
|
||||
|
||||
| Link Type | Blocking? | Hierarchical? | Direction |
|
||||
|-----------|-----------|---------------|-----------|
|
||||
| `blocks` | Yes | No | One-way |
|
||||
| `parent_id` | No | Yes | One-way |
|
||||
| `relates_to` | No | No | Bidirectional |
|
||||
| `replies_to` | No | No | One-way |
|
||||
| `duplicate_of` | No | No | One-way |
|
||||
| `superseded_by` | No | No | One-way |
|
||||
|
||||
## Use Cases
|
||||
|
||||
### Knowledge Base
|
||||
|
||||
Link related documentation:
|
||||
|
||||
```bash
|
||||
bd relate bd-api-ref bd-quickstart
|
||||
bd relate bd-api-ref bd-examples
|
||||
bd relate bd-quickstart bd-install
|
||||
```
|
||||
|
||||
### Bug Triage
|
||||
|
||||
Consolidate duplicate reports:
|
||||
|
||||
```bash
|
||||
# Find potential duplicates
|
||||
bd duplicates
|
||||
|
||||
# Merge duplicates
|
||||
bd duplicate bd-bug42 --of bd-bug17
|
||||
bd duplicate bd-bug58 --of bd-bug17
|
||||
```
|
||||
|
||||
### Version History
|
||||
|
||||
Track document evolution:
|
||||
|
||||
```bash
|
||||
bd supersede bd-rfc1 --with bd-rfc2
|
||||
bd supersede bd-rfc2 --with bd-rfc3
|
||||
# bd-rfc3 is now the current version
|
||||
```
|
||||
|
||||
### Message Threading
|
||||
|
||||
Build conversation chains:
|
||||
|
||||
```bash
|
||||
bd mail send dev -s "Question" -m "How does X work?"
|
||||
bd mail reply bd-q1 -m "X works by..."
|
||||
bd mail reply bd-q1.reply -m "Thanks!"
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Use relates_to sparingly** - Too many links become noise
|
||||
2. **Prefer specific link types** - `duplicates` is clearer than generic relates_to
|
||||
3. **Keep threads shallow** - Deep reply chains are hard to follow
|
||||
4. **Document supersedes chains** - Note why version changed
|
||||
5. **Query before creating duplicates** - `bd search` first
|
||||
|
||||
## See Also
|
||||
|
||||
- [Messaging](messaging.md) - Mail commands and threading
|
||||
- [Dependencies](QUICKSTART.md#dependencies) - Blocking dependencies
|
||||
- [CLI Reference](CLI_REFERENCE.md) - All commands
|
||||
254
docs/messaging.md
Normal file
254
docs/messaging.md
Normal file
@@ -0,0 +1,254 @@
|
||||
# Beads Messaging System
|
||||
|
||||
Beads provides a built-in messaging system for inter-agent communication. Messages are stored as beads issues with type `message`, enabling git-native communication without external services.
|
||||
|
||||
## Overview
|
||||
|
||||
The messaging system enables:
|
||||
- **Agent-to-agent communication** - Send messages between workers
|
||||
- **Thread tracking** - Replies link back to original messages
|
||||
- **Priority signaling** - Mark messages as urgent (P0) or routine
|
||||
- **Ephemeral cleanup** - Messages can be bulk-deleted after completion
|
||||
|
||||
## Identity Configuration
|
||||
|
||||
Before using mail commands, configure your identity:
|
||||
|
||||
### Environment Variable
|
||||
|
||||
```bash
|
||||
export BEADS_IDENTITY="worker-1"
|
||||
```
|
||||
|
||||
### Config File
|
||||
|
||||
Add to `.beads/config.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"identity": "worker-1"
|
||||
}
|
||||
```
|
||||
|
||||
### Priority
|
||||
|
||||
1. `--identity` flag (if provided)
|
||||
2. `BEADS_IDENTITY` environment variable
|
||||
3. `.beads/config.json` identity field
|
||||
4. System username (fallback)
|
||||
|
||||
## Commands
|
||||
|
||||
### Send a Message
|
||||
|
||||
```bash
|
||||
bd mail send <recipient> -s <subject> -m <body>
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `-s, --subject` - Message subject (required)
|
||||
- `-m, --body` - Message body (required)
|
||||
- `--urgent` - Set priority=0 (urgent)
|
||||
- `--identity` - Override sender identity
|
||||
|
||||
**Examples:**
|
||||
|
||||
```bash
|
||||
# Basic message
|
||||
bd mail send worker-1 -s "Task complete" -m "Finished bd-xyz"
|
||||
|
||||
# Urgent message
|
||||
bd mail send manager -s "Blocked!" -m "Need credentials for deploy" --urgent
|
||||
|
||||
# With custom identity
|
||||
bd mail send worker-2 -s "Handoff" -m "Your turn on bd-abc" --identity refinery
|
||||
```
|
||||
|
||||
### Check Your Inbox
|
||||
|
||||
```bash
|
||||
bd mail inbox
|
||||
```
|
||||
|
||||
Lists all open messages addressed to your identity.
|
||||
|
||||
**Options:**
|
||||
- `--from <sender>` - Filter by sender
|
||||
- `--priority <n>` - Filter by priority (0-4)
|
||||
|
||||
**Output:**
|
||||
|
||||
```
|
||||
Inbox for worker-1 (2 messages):
|
||||
|
||||
bd-a1b2: Task assigned [URGENT]
|
||||
From: manager (5m ago)
|
||||
|
||||
bd-c3d4: FYI: Design doc updated
|
||||
From: worker-2 (1h ago)
|
||||
Re: bd-x7y8
|
||||
```
|
||||
|
||||
### Read a Message
|
||||
|
||||
```bash
|
||||
bd mail read <id>
|
||||
```
|
||||
|
||||
Displays full message content. Does NOT mark as read.
|
||||
|
||||
**Example output:**
|
||||
|
||||
```
|
||||
──────────────────────────────────────────────────────────────────
|
||||
ID: bd-a1b2
|
||||
From: manager
|
||||
To: worker-1
|
||||
Subject: Task assigned
|
||||
Time: 2025-12-16 10:30:45
|
||||
Priority: P0
|
||||
Status: open
|
||||
──────────────────────────────────────────────────────────────────
|
||||
|
||||
Please prioritize bd-xyz. It's blocking the release.
|
||||
|
||||
Let me know if you need anything.
|
||||
```
|
||||
|
||||
### Acknowledge (Mark as Read)
|
||||
|
||||
```bash
|
||||
bd mail ack <id> [id2...]
|
||||
```
|
||||
|
||||
Closes messages to mark them as acknowledged.
|
||||
|
||||
**Examples:**
|
||||
|
||||
```bash
|
||||
# Single message
|
||||
bd mail ack bd-a1b2
|
||||
|
||||
# Multiple messages
|
||||
bd mail ack bd-a1b2 bd-c3d4 bd-e5f6
|
||||
```
|
||||
|
||||
### Reply to a Message
|
||||
|
||||
```bash
|
||||
bd mail reply <id> -m <body>
|
||||
```
|
||||
|
||||
Creates a threaded reply to an existing message.
|
||||
|
||||
**Options:**
|
||||
- `-m, --body` - Reply body (required)
|
||||
- `--urgent` - Set priority=0
|
||||
- `--identity` - Override sender identity
|
||||
|
||||
**Behavior:**
|
||||
- Sets `replies_to` to original message ID
|
||||
- Sends to original message's sender
|
||||
- Prefixes subject with "Re:" if not already present
|
||||
|
||||
**Example:**
|
||||
|
||||
```bash
|
||||
bd mail reply bd-a1b2 -m "On it! Should be done by EOD."
|
||||
```
|
||||
|
||||
## Message Storage
|
||||
|
||||
Messages are stored as issues with these fields:
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| `type` | `message` |
|
||||
| `title` | Subject line |
|
||||
| `description` | Message body |
|
||||
| `assignee` | Recipient identity |
|
||||
| `sender` | Sender identity |
|
||||
| `priority` | 0 (urgent) to 4 (routine), default 2 |
|
||||
| `ephemeral` | `true` - can be bulk-deleted |
|
||||
| `replies_to` | ID of parent message (for threads) |
|
||||
| `status` | `open` (unread) / `closed` (read) |
|
||||
|
||||
## Cleanup
|
||||
|
||||
Messages are ephemeral by default and can be cleaned up:
|
||||
|
||||
```bash
|
||||
# Preview ephemeral message cleanup
|
||||
bd cleanup --ephemeral --dry-run
|
||||
|
||||
# Delete all closed ephemeral messages
|
||||
bd cleanup --ephemeral --force
|
||||
```
|
||||
|
||||
## Hooks
|
||||
|
||||
The messaging system fires hooks when messages are sent:
|
||||
|
||||
**Hook file:** `.beads/hooks/on_message`
|
||||
|
||||
The hook receives:
|
||||
- **Arg 1:** Issue ID
|
||||
- **Arg 2:** Event type (`message`)
|
||||
- **Stdin:** Full issue JSON
|
||||
|
||||
**Example hook:**
|
||||
|
||||
```bash
|
||||
#!/bin/sh
|
||||
# .beads/hooks/on_message
|
||||
|
||||
ISSUE_ID="$1"
|
||||
EVENT="$2"
|
||||
|
||||
# Parse assignee from JSON stdin
|
||||
ASSIGNEE=$(cat | jq -r '.assignee')
|
||||
|
||||
# Notify recipient (example: send to external system)
|
||||
curl -X POST "https://example.com/notify" \
|
||||
-d "to=$ASSIGNEE&message=$ISSUE_ID"
|
||||
```
|
||||
|
||||
Make the hook executable:
|
||||
|
||||
```bash
|
||||
chmod +x .beads/hooks/on_message
|
||||
```
|
||||
|
||||
## JSON Output
|
||||
|
||||
All commands support `--json` for programmatic use:
|
||||
|
||||
```bash
|
||||
bd mail inbox --json
|
||||
bd mail read bd-a1b2 --json
|
||||
bd mail send worker-1 -s "Hi" -m "Test" --json
|
||||
```
|
||||
|
||||
## Thread Visualization
|
||||
|
||||
Use `bd show --thread` to view message threads:
|
||||
|
||||
```bash
|
||||
bd show bd-c3d4 --thread
|
||||
```
|
||||
|
||||
This shows the full conversation chain via `replies_to` links.
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Use descriptive subjects** - Recipients scan subjects first
|
||||
2. **Mark urgent sparingly** - P0 should be reserved for blockers
|
||||
3. **Acknowledge promptly** - Keep inbox clean
|
||||
4. **Clean up after sprints** - Run `bd cleanup --ephemeral` periodically
|
||||
5. **Configure identity** - Use `BEADS_IDENTITY` for consistent sender names
|
||||
|
||||
## See Also
|
||||
|
||||
- [Graph Links](graph-links.md) - Other link types (relates_to, duplicates, supersedes)
|
||||
- [Hooks](EXTENDING.md) - Custom hook scripts
|
||||
- [Config](CONFIG.md) - Configuration options
|
||||
Reference in New Issue
Block a user