Skip to content

tools-reference.md

Latest commit

 

History

History
270 lines (200 loc) · 8.99 KB

tools-reference.md

File metadata and controls

270 lines (200 loc) · 8.99 KB

Tools Reference - Quick Guide

Reference for all development tools integrated in this project.

Overview

Tool Type Purpose
bd CLI Issue tracking with git storage (beads)
bv TUI Visual dashboard for beads
docs-mcp-server MCP + Web UI Documentation indexer with semantic search
compound-engineering Plugin Multi-agent workflows (brainstorm, plan, work, review)
wshobson/agents Plugin (17x) Specialized development agents
/project:* Skills Project-specific workflows integrating all tools

bd (Beads CLI)

Issue tracker that stores data in git (.beads/ directory). Used by devs and agents.

Essential Commands

bd init                                  # Initialize beads in repo
bd create --title="Task name" --type=task  # Create new issue
bd ready                                 # List tasks ready to work on
bd update <id> --status=in_progress      # Start working on task
bd close <id>                            # Mark task as done
bd list                                  # List all issues
bd show <id>                             # Show issue details
bd sync                                  # Sync with git remote
bd stats                                 # Show statistics

When to Use

  • Creating and tracking development tasks
  • Updating task status during development
  • Closing tasks after PR merge
  • Syncing task state across team members

bv (Beads Viewer)

Terminal UI for visualizing beads data. Provides dependency graphs, triage recommendations, and sprint views.

Essential Commands

bv                     # Launch interactive TUI (humans only)
bv --robot-triage      # AI-friendly: dependency-aware task recommendations
bv --robot-graph       # AI-friendly: graph analysis output
bv --robot-stats       # AI-friendly: statistics

When to Use

  • Reviewing task dependencies and priorities
  • Sprint planning and progress visualization
  • Getting AI-powered triage recommendations (via --robot-* flags)
  • Understanding critical path in task graph

Important

  • Interactive bv (no flags) is for humans only - it launches a TUI
  • AI agents must use --robot-* flags for non-interactive output

Compound Engineering Plugin

Multi-agent workflows for structured software development.

Available Workflows

Skill Purpose When to Use
compound-engineering:workflows:brainstorm Explore approaches and trade-offs Starting a new feature, unclear requirements
compound-engineering:workflows:plan Create structured implementation plan After brainstorm, before coding
compound-engineering:workflows:work Execute with quality checks During implementation
compound-engineering:workflows:review Multi-agent code review Before PR, quality gate

Review Specialists

Skill Focus
compound-engineering:review:typescript-pro TypeScript-specific review
compound-engineering:review:kieran-rails-reviewer Rails/Ruby review

Typical Flow

brainstorm → plan → work → review → commit

wshobson/agents (17 Plugins)

Specialized development agents organized by domain.

By Development Stage

Implementation

Plugin Key Skills Use For
backend-development feature-development, tdd-orchestrator Backend features, TDD
full-stack-orchestration full-stack-feature Full-stack features (BE+FE+DB)
api-scaffolding scaffold-api New API endpoints
javascript-typescript JS/TS utilities JavaScript/TypeScript tasks
developer-essentials General dev tools Common development tasks

Review & Quality

Plugin Key Skills Use For
git-pr-workflows code-reviewer PR review, Git workflows
code-review-ai ai-review AI-powered code review
backend-api-security backend-security-coder Security review for APIs

Testing

Plugin Key Skills Use For
unit-testing test-generate, test-automator Unit test creation
api-testing-observability API test tools API test suites

Debugging

Plugin Key Skills Use For
debugging-toolkit debugger, smart-debug Bug investigation

Database`

Plugin Key Skills Use For
database-design Schema design Database architecture
database-migrations Migration tools Schema migrations

DevOps & Security

Plugin Key Skills Use For
cicd-automation workflow-automate CI/CD pipelines
observability-monitoring monitor-setup Monitoring, logging
security-compliance compliance-check Security audits

AI/LLM

Plugin Key Skills Use For
llm-application-dev LLM app tools Building AI applications

Integration with /project:* Commands

The /project:* commands orchestrate these tools automatically:

Command Tools Used
/project:iniciar BEAD_ID bd (fetch task, update status) + git (create branch)
/project:enviar git (push) + gh (create PR) + bd (label in-review)
/project:corrigir gh (read PR feedback) + agents (apply fixes)
/project:testar npm (lint, test, build)
/project:status bd + bv --robot-* + git + gh (unified dashboard)
/project:triage bv --robot-triage (PageRank, critical path)
/project:graph bv --robot-graph (dependency visualization)

Recommended Workflow

/project:triage          # Pick next task (uses bv)
/project:iniciar ID      # Start task (uses bd + git)
  → brainstorm           # compound-engineering
  → plan                 # compound-engineering
  → implement            # wshobson agents
  → review               # compound + wshobson review
/project:testar          # Run checks
/project:enviar          # Create PR
/project:corrigir        # Fix review feedback

Docs MCP Server (Documentation Indexer)

Servidor local para indexar, buscar e consultar documentacao de bibliotecas. Roda em background no devcontainer com Web UI acessivel pelo navegador.

Acesso

Interface URL Descricao
Web UI http://localhost:6280 Gerenciar bibliotecas, scrape docs, buscar
MCP (Claude Code) Automatico via HTTP Claude usa as tools search_docs, scrape_docs, etc.

Como usar a Web UI

  1. Abra http://localhost:6280 no navegador
  2. Clique em "Add Library" para indexar documentacao
  3. Cole a URL da documentacao (ex: https://docs.python.org/3/)
  4. O servidor faz scrape, indexa e disponibiliza para busca

Tools disponiveis via MCP (Claude Code)

Tool O que faz
search_docs Busca semantica na documentacao indexada
scrape_docs Indexa nova documentacao a partir de URL
list_libraries Lista bibliotecas indexadas
fetch_url Busca e converte URL para Markdown
find_version Detecta versao de biblioteca no projeto

Configuracao de Embeddings (Busca Semantica)

Sem configuracao, o servidor funciona com busca por texto (FTS). Para habilitar busca vetorial semantica (muito mais precisa):

  1. Copie .env.example para .env: 
    cp .env.example .env
  2. Edite .env e adicione sua OpenAI API key: 
    OPENAI_API_KEY=sk-proj-sua-key-aqui
  3. Rebuild o devcontainer (ou reinicie o servidor manualmente): 
    pkill -f "docs-mcp-server.*--protocol http"
source .env && nohup npx -y @arabold/docs-mcp-server@latest --protocol http --host 127.0.0.1 --port 6280 > /tmp/docs-mcp-server.log 2>&1 &

Cada membro do time usa sua propria key. O arquivo .env esta no .gitignore e nao e commitado.

Logs e Troubleshooting

cat /tmp/docs-mcp-server.log          # Ver log do servidor
curl -s http://localhost:6280 | head   # Verificar se esta rodando
cat /tmp/docs-mcp-server.pid          # PID do processo

Se o servidor nao estiver rodando:

nohup npx -y @arabold/docs-mcp-server@latest --protocol http --host 127.0.0.1 --port 6280 > /tmp/docs-mcp-server.log 2>&1 &

Installation

All tools are installed automatically via .devcontainer/setup-beads-plugins.sh when the devcontainer is created. MCP servers are configured via .devcontainer/setup-mcp.sh. To reinstall manually:

./.devcontainer/setup-beads-plugins.sh   # Plugins (beads, bv, compound, etc.)
./.devcontainer/setup-mcp.sh             # MCP servers (repomix, docs-mcp-server, beads)

Verify Installation

bd --version             # Beads CLI
bv --version             # Beads Viewer
claude plugin list       # All installed plugins
claude mcp list          # All MCP servers
ls .beads/               # Beads initialized
curl -s localhost:6280   # Docs MCP Server running

Last Updated: 2026-02-11