Systematic cleanup of stale documentation references left over from the Dolt migration: - Replace all 'bd sync' → 'bd dolt push' / 'bd dolt pull' across 40+ files - Replace all 'bd import' → 'bd init --from-jsonl' or remove - Replace 'bd init --branch' → note about refs/dolt/data separation - Fix AGENT_INSTRUCTIONS.md (highest impact: agents read this directly) - Fix npm-package, claude-plugin, integrations, examples, website docs Add scripts/check-doc-flags.sh to catch stale doc references: - Checks for removed commands (bd sync, bd import) - Checks for removed flags (bd init --branch) - Warns on legacy SQLite/beads.db references - Compares CLI_REFERENCE.md against bd help --all Add CI job (check-doc-flags) and Makefile target (check-docs) to gate PRs against doc freshness. Prior art: feat/help-doc-generator branch has bd help --doc/--list for generating docs FROM CLI output. This script validates docs AGAINST CLI output — complementary approaches. Amp-Thread-ID: https://ampcode.com/threads/T-019cde77-0722-7353-b63a-1779a5773ca6 Co-authored-by: Amp <amp@ampcode.com>
3.8 KiB
3.8 KiB
| id | title | sidebar_position |
|---|---|---|
| junie | Junie | 4 |
Junie Integration
How to use beads with Junie (JetBrains AI Agent).
Setup
Quick Setup
bd setup junie
This creates:
.junie/guidelines.md- Agent instructions for beads workflow.junie/mcp/mcp.json- MCP server configuration
Verify Setup
bd setup junie --check
How It Works
- Session starts → Junie reads
.junie/guidelines.mdfor workflow context - MCP tools available → Junie can use beads MCP tools directly
- You work → Use
bdCLI commands or MCP tools - Session ends → Run
bd dolt pushto push changes to Dolt remote
Configuration Files
Guidelines (.junie/guidelines.md)
Contains workflow instructions that Junie reads automatically:
- Core workflow rules
- Command reference
- Issue types and priorities
- MCP tool documentation
MCP Config (.junie/mcp/mcp.json)
Configures the beads MCP server:
{
"mcpServers": {
"beads": {
"command": "bd",
"args": ["mcp"]
}
}
}
MCP Tools
With MCP configured, Junie can use these tools directly:
| Tool | Description |
|---|---|
mcp_beads_ready |
Find tasks ready for work |
mcp_beads_list |
List issues with filters |
mcp_beads_show |
Show issue details |
mcp_beads_create |
Create new issues |
mcp_beads_update |
Update issue status/priority |
mcp_beads_close |
Close completed issues |
mcp_beads_dep |
Manage dependencies |
mcp_beads_blocked |
Show blocked issues |
mcp_beads_stats |
Get issue statistics |
CLI Commands
You can also use the bd CLI directly:
Creating Issues
# Always include description for context
bd create "Fix authentication bug" \
--description="Login fails with special characters in password" \
-t bug -p 1 --json
# Link discovered issues
bd create "Found SQL injection" \
--description="User input not sanitized in query builder" \
--deps discovered-from:bd-42 --json
Working on Issues
# Find ready work
bd ready --json
# Start work
bd update bd-42 --claim --json
# Complete work
bd close bd-42 --reason "Fixed in commit abc123" --json
Querying
# List open issues
bd list --status open --json
# Show issue details
bd show bd-42 --json
# Check blocked issues
bd blocked --json
Syncing
# ALWAYS run at session end
bd dolt push
Best Practices
Always Use --json
bd list --json # Parse programmatically
bd create "Task" --json # Get issue ID from output
bd show bd-42 --json # Structured data
Always Include Descriptions
# Good
bd create "Fix auth bug" \
--description="Login fails when password contains quotes" \
-t bug -p 1 --json
# Bad - no context for future work
bd create "Fix auth bug" -t bug -p 1 --json
Link Related Work
# When you discover issues during work
bd create "Found related bug" \
--deps discovered-from:bd-current --json
Push Before Session End
# ALWAYS run before ending
bd dolt push
Troubleshooting
Guidelines not loaded
# Check setup
bd setup junie --check
# Reinstall if needed
bd setup junie
MCP tools not available
# Verify MCP config exists
cat .junie/mcp/mcp.json
# Test MCP server
bd mcp --help
Changes not syncing
# Force push
bd dolt push
# Check system health
bd doctor
Database not found
# Initialize beads
bd init --quiet
Removing Integration
bd setup junie --remove
This removes:
.junie/guidelines.md.junie/mcp/mcp.json- Empty
.junie/mcp/and.junie/directories
See Also
- MCP Server - MCP server details
- Claude Code - Similar hook-based integration
- IDE Setup - Other editors