📚 docs(agents): add comprehensive documentation for agent tools and processes

# Tools and MCP servers used for agentic coding

A concise, lint-friendly guide for contributors and agents working on this repository.

## Remarks on Tool Usage

If the coding agent, tool or any MCP server needs to create temporary files, test data, test results, or debug code (in particular those named `temp_*.*`, `tmp_*.*`, etc.), they **must** be created in the `/temp` directory. If `/temp` does not exist, it should be created. Never put temporary files in the root directory or any other directory.

## Tool: Issue tracking with beads (bd)

See `./110_Tool_beads.md` for detailed usage instructions.

## Tool: Memory-Graph

If MCP server `memorygraph` is available, recall project context using Memory-Graph when starting a new task:

```python

recall_memories(query="tdoc-crawler crawling and database patterns")

```

Store and recall relevant project-specific context (like `AGENTS.md` requirements or ongoing tasks) across turns; remind yourself of persisted notes before suggesting new changes to avoid repeating work.

See `./120_Tool_memorygraph.md` for detailed setup and usage instructions.

## Tool: Sequential Thinking

If MCP server `sequential-thinking` is available, use it to analyze problems through a flexible thinking process that can adapt and evolve.

See `./130_Tool_sequential_thinking.md` for detailed setup and usage instructions.

## Other recommended Tools

### subAgents

If the subagent capability is enabled, please create specialized subagents for complex workflows (e.g., multi-step refactors or downloads), delegate tasks and coordinate results before responding; mention in your summary which subagent was used if it changed the outcome.

### Code examples and documentation

If MCP server `context7` is available, always use it when code, setup or configuration steps are generated, or for library/API documentation. This means you should automatically use the Context7 MCP tools to resolve library id and get library docs without you having to explicitly ask.

### Tool discovery

If MCP server `ncp` is available, use it to discover the most suitable tools and currently available MCP servers for your current task:

- This server can analyze the task description and will delegate to other MCP servers or appropriate tools from its available set.

- Use before starting significant work to find optimal tools

- Example: `"I need to analyze test failures"` → ncp may suggest test analysis tools

### Desktop Commander

If MCP server `desktop-commander` is available, use this tool for:

- File system operations (create, edit, read directories)

- Process management and terminal interaction

- Search operations (files, content)

- Useful for workspace exploration and file organization

### Fetching web content

If MCP server `fetch` is available, use it to fetch web content and extract relevant information from given URLs.

### Additional MCP server search and selection

If MCP server `mcpadvisor` is available, use it to explore additional MCP servers and their capabilities, which might be useful for your task.

If MCP server `mcp-compass` is also available, use it to cross-check MCP servers identified by the `mcpadvisor` server.

<!-- Auto-generated by bd v0.29.0 - DO NOT EDIT MANUALLY -->

<!-- Run 'bd onboard --output .beads/BD_GUIDE.md' to regenerate -->

# BD (Beads) Guide for AI Agents

This file contains canonical bd (beads) workflow instructions for AI agents.

It is auto-generated and version-stamped to track bd upgrades.

> **For project-specific instructions**, see AGENTS.md in the repository root.

> This file only covers bd tool usage, not project-specific workflows.

______________________________________________________________________

## Issue Tracking with bd (beads)

**IMPORTANT**: This project uses **bd (beads)** for ALL issue tracking. Do NOT use markdown TODOs, task lists, or other tracking methods.

### Why bd?

- Dependency-aware: Track blockers and relationships between issues

- Git-friendly: Auto-syncs to JSONL for version control

- Agent-optimized: JSON output, ready work detection, discovered-from links

- Prevents duplicate tracking systems and confusion

### Quick Start

**Check for ready work:**

```bash

bd ready --json

```

**Create new issues:**

```bash

bd create "Issue title" -t bug|feature|task -p 0-4 --json

bd create "Issue title" -p 1 --deps discovered-from:bd-123 --json

bd create "Subtask" --parent <epic-id> --json  # Hierarchical subtask (gets ID like epic-id.1)

```

**Claim and update:**

```bash

bd update bd-42 --status in_progress --json

bd update bd-42 --priority 1 --json

```

**Complete work:**

```bash

bd close bd-42 --reason "Completed" --json

```

### Issue Types

- `bug` - Something broken

- `feature` - New functionality

- `task` - Work item (tests, docs, refactoring)

- `epic` - Large feature with subtasks

- `chore` - Maintenance (dependencies, tooling)

### Priorities

- `0` - Critical (security, data loss, broken builds)

- `1` - High (major features, important bugs)

- `2` - Medium (default, nice-to-have)

- `3` - Low (polish, optimization)

- `4` - Backlog (future ideas)

### Workflow for AI Agents

1. **Check ready work**: `bd ready` shows unblocked issues

1. **Claim your task**: `bd update <id> --status in_progress`

1. **Work on it**: Implement, test, document

1. **Discover new work?** Create linked issue:

   - `bd create "Found bug" -p 1 --deps discovered-from:<parent-id>`

1. **Complete**: `bd close <id> --reason "Done"`

1. **Commit together**: Always commit the `.beads/issues.jsonl` file together with the code changes so issue state stays in sync with code state

### Auto-Sync

bd automatically syncs with git:

- Exports to `.beads/issues.jsonl` after changes (5s debounce)

- Imports from JSONL when newer (e.g., after `git pull`)

- No manual export/import needed!

### GitHub Copilot Integration

If using GitHub Copilot, also create `.github/copilot-instructions.md` for automatic instruction loading.

Run `bd onboard` to get the content, or see step 2 of the onboard instructions.

### MCP Server (Recommended)

If using Claude or MCP-compatible clients, install the beads MCP server:

```bash

pip install beads-mcp

```

Add to MCP config (e.g., `~/.config/claude/config.json`):

```json

{

  "beads": {

    "command": "beads-mcp",

    "args": []

  }

}

```

Then use `mcp__beads__*` functions instead of CLI commands.

### Managing AI-Generated Planning Documents

AI assistants often create planning and design documents during development:

- PLAN.md, IMPLEMENTATION.md, ARCHITECTURE.md

- DESIGN.md, CODEBASE_SUMMARY.md, INTEGRATION_PLAN.md

- TESTING_GUIDE.md, TECHNICAL_DESIGN.md, and similar files

**Best Practice: Use a dedicated directory for these ephemeral files**

**Recommended approach:**

- Create a `temp/history/` directory in the project root

- Store ALL AI-generated planning/design docs in `temp/history/`

- Keep the repository root clean and focused on permanent project files

- Only access `temp/history/` when explicitly asked to review past planning

**Example .gitignore entry (optional):**

```

# AI planning documents (ephemeral)

history/

```

**Benefits:**

- ✅ Clean repository root

- ✅ Clear separation between ephemeral and permanent documentation

- ✅ Easy to exclude from version control if desired

- ✅ Preserves planning history for archeological research

- ✅ Reduces noise when browsing the project

### CLI Help

Run `bd <command> --help` to see all available flags for any command.

For example: `bd create --help` shows `--parent`, `--deps`, `--assignee`, etc.

### Important Rules

- ✅ Use bd for ALL task tracking

- ✅ Always use `--json` flag for programmatic use

- ✅ Link discovered work with `discovered-from` dependencies

- ✅ Check `bd ready` before asking "what should I work on?"

- ✅ Store AI planning docs in `history/` directory

- ✅ Run `bd <cmd> --help` to discover available flags

- ❌ Do NOT create markdown TODO lists

- ❌ Do NOT use external issue trackers

- ❌ Do NOT duplicate tracking systems

- ❌ Do NOT clutter repo root with planning documents

For more details, see README.md and QUICKSTART.md.

______________________________________________________________________

# GitHub Copilot Instructions for Beads

## Project Overview

**beads** (command: `bd`) is a Git-backed issue tracker designed for AI-supervised coding workflows. We dogfood our own tool for all task tracking.

**Key Features:**

- Dependency-aware issue tracking

- Auto-sync with Git via JSONL

- AI-optimized CLI with JSON output

- Built-in daemon for background operations

- MCP server integration for Claude and other AI assistants

## Tech Stack

- **Language**: Go 1.21+

- **Storage**: SQLite (internal/storage/sqlite/)

- **CLI Framework**: Cobra

- **Testing**: Go standard testing + table-driven tests

- **CI/CD**: GitHub Actions

- **MCP Server**: Python (integrations/beads-mcp/)

## Coding Guidelines

### Testing

- Always write tests for new features

- Use `BEADS_DB=/tmp/test.db` to avoid polluting production database

- Run `go test -short ./...` before committing

- Never create test issues in production DB (use temporary DB)

### Code Style

- Run `golangci-lint run ./...` before committing

- Follow existing patterns in `cmd/bd/` for new commands

- Add `--json` flag to all commands for programmatic use

- Update docs when changing behavior

### Git Workflow

- Always commit `.beads/issues.jsonl` with code changes

- Run `bd sync` at end of work sessions

- Install git hooks: `bd hooks install` (ensures DB ↔ JSONL consistency)

## Issue Tracking with bd

**CRITICAL**: This project uses **bd** for ALL task tracking. Do NOT create markdown TODO lists.

### Essential Commands

```bash

# Find work

bd ready --json                    # Unblocked issues

bd stale --days 30 --json          # Forgotten issues

# Create and manage

bd create "Title" -t bug|feature|task -p 0-4 --json

bd create "Subtask" --parent <epic-id> --json  # Hierarchical subtask

bd update <id> --status in_progress --json

bd close <id> --reason "Done" --json

# Search

bd list --status open --priority 1 --json

bd show <id> --json

# Sync (CRITICAL at end of session!)

bd sync  # Force immediate export/commit/push

```

### Workflow

1. **Check ready work**: `bd ready --json`

1. **Claim task**: `bd update <id> --status in_progress`

1. **Work on it**: Implement, test, document

1. **Discover new work?** `bd create "Found bug" -p 1 --deps discovered-from:<parent-id> --json`

1. **Complete**: `bd close <id> --reason "Done" --json`

1. **Sync**: `bd sync` (flushes changes to git immediately)

### Priorities

- `0` - Critical (security, data loss, broken builds)

- `1` - High (major features, important bugs)

- `2` - Medium (default, nice-to-have)

- `3` - Low (polish, optimization)

- `4` - Backlog (future ideas)

## Project Structure

```

beads/

├── cmd/bd/              # CLI commands (add new commands here)

├── internal/

│   ├── types/           # Core data types

│   └── storage/         # Storage layer

│       └── sqlite/      # SQLite implementation

├── integrations/

│   └── beads-mcp/       # MCP server (Python)

├── examples/            # Integration examples

├── docs/                # Documentation

└── .beads/

    ├── beads.db         # SQLite database (DO NOT COMMIT)

    └── issues.jsonl     # Git-synced issue storage

```

## Available Resources

### MCP Server (Recommended)

Use the beads MCP server for native function calls instead of shell commands:

- Install: `pip install beads-mcp`

- Functions: `mcp__beads__ready()`, `mcp__beads__create()`, etc.

- See `integrations/beads-mcp/README.md`

### Scripts

- `./scripts/bump-version.sh <version> --commit` - Update all version files atomically

- `./scripts/release.sh <version>` - Complete release workflow

- `./scripts/update-homebrew.sh <version>` - Update Homebrew formula

### Key Documentation

- **AGENTS.md** - Comprehensive AI agent guide (detailed workflows, advanced features)

- **AGENT_INSTRUCTIONS.md** - Development procedures, testing, releases

- **README.md** - User-facing documentation

- **docs/CLI_REFERENCE.md** - Complete command reference

## CLI Help

Run `bd <command> --help` to see all available flags for any command.

For example: `bd create --help` shows `--parent`, `--deps`, `--assignee`, etc.

## Important Rules

- ✅ Use bd for ALL task tracking

- ✅ Always use `--json` flag for programmatic use

- ✅ Run `bd sync` at end of sessions

- ✅ Test with `BEADS_DB=/tmp/test.db`

- ✅ Run `bd <cmd> --help` to discover available flags

- ❌ Do NOT create markdown TODO lists

- ❌ Do NOT create test issues in production DB

- ❌ Do NOT commit `.beads/beads.db` (JSONL only)

______________________________________________________________________

**For detailed workflows and advanced features, see [AGENTS.md](../AGENTS.md)**

______________________________________________________________________

**Generated by bd v0.29.0**

To regenerate this file after upgrading bd:

```bash

bd onboard --output .beads/BD_GUIDE.md

```

# Memory Protocol

See [memory-graph](https://github.com/gregorydickson/memory-graph) for more details.

## REQUIRED: Before Starting Work

You MUST use `recall_memories` before any task. Query by project, tech, or task type.

## REQUIRED: Automatic Storage Triggers

Store memories on ANY of:

- **Git commit** → what was fixed/added

- **Bug fix** → problem + solution

- **Version release** → summarize changes

- **Architecture decision** → choice + rationale

- **Pattern discovered** → reusable approach

## Timing Mode (default: on-commit)

`memory_mode: immediate | on-commit | session-end`

## Memory Fields

- **Type**: solution | problem | code_pattern | fix | error | workflow

- **Title**: Specific, searchable (not generic)

- **Content**: Accomplishment, decisions, patterns

- **Tags**: project, tech, category (REQUIRED)

- **Importance**: 0.8+ critical, 0.5-0.7 standard, 0.3-0.4 minor

- **Relationships**: Link related memories when they exist

Do NOT wait to be asked. Memory storage is automatic.

# Sequential Thinking

A detailed tool for dynamic and reflective problem-solving through thoughts.

This tool helps analyze problems through a flexible thinking process that can adapt and evolve.

Each thought can build on, question, or revise previous insights as understanding deepens.

When to use this tool:

- Breaking down complex problems into steps

- Planning and design with room for revision

- Analysis that might need course correction

- Problems where the full scope might not be clear initially

- Problems that require a multi-step solution

- Tasks that need to maintain context over multiple steps

- Situations where irrelevant information needs to be filtered out

Key features:

- You can adjust total_thoughts up or down as you progress

- You can question or revise previous thoughts

- You can add more thoughts even after reaching what seemed like the end

- You can express uncertainty and explore alternative approaches

- Not every thought needs to build linearly - you can branch or backtrack

- Generates a solution hypothesis

- Verifies the hypothesis based on the Chain of Thought steps

- Repeats the process until satisfied

- Provides a correct answer

Parameters explained:

- thought: Your current thinking step, which can include:

  - Regular analytical steps

  - Revisions of previous thoughts

  - Questions about previous decisions

  - Realizations about needing more analysis

  - Changes in approach

  - Hypothesis generation

  - Hypothesis verification

- nextThoughtNeeded: True if you need more thinking, even if at what seemed like the end

- thoughtNumber: Current number in sequence (can go beyond initial total if needed)

- totalThoughts: Current estimate of thoughts needed (can be adjusted up/down)

- isRevision: A boolean indicating if this thought revises previous thinking

- revisesThought: If is_revision is true, which thought number is being reconsidered

- branchFromThought: If branching, which thought number is the branching point

- branchId: Identifier for the current branch (if any)

- needsMoreThoughts: If reaching end but realizing more thoughts needed

You should:

1. Start with an initial estimate of needed thoughts, but be ready to adjust

1. Feel free to question or revise previous thoughts

1. Don't hesitate to add more thoughts if needed, even at the "end"

1. Express uncertainty when present

1. Mark thoughts that revise previous thinking or branch into new paths

1. Ignore information that is irrelevant to the current step

1. Generate a solution hypothesis when appropriate

1. Verify the hypothesis based on the Chain of Thought steps

1. Repeat the process until satisfied with the solution

1. Provide a single, ideally correct answer as the final output

1. Only set nextThoughtNeeded to false when truly done and a satisfactory answer is reached