refactor: externalize documentation into reusable skills

---

name: cli-bd

description: Issue tracking using bd (beads) CLI with dependency-aware task management, Dolt-powered version control, and AI-optimized workflows

---

# CLI Tool: Issue Tracking with bd (beads)

## Overview

**bd (beads)** is the issue tracking system for this project. Use it for ALL task tracking - do NOT use markdown TODOs, task lists, or other tracking methods.

## Quick Start

### Check for Ready Work

```bash

# Show unblocked issues

bd ready --json

# Show forgotten issues

bd stale --days 30 --json

```

### Create New Issues

```bash

# Basic issue

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

# Issue with dependency

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

# Hierarchical subtask (parent epic)

bd create "Subtask" --parent <epic-id> --json

```

### Search and Manage

```bash

# List open issues by priority

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

# Show specific issue

bd show <id> --json

```

### Claim and Update

```bash

# Claim issue (mark as in-progress)

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

# Update priority

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

```

### Complete Work

```bash

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

```

### Sync (CRITICAL at end of session!)

```bash

bd sync

```

Flushes changes to git immediately. Always run at end of work session.

## Why bd?

- **Dependency-aware**: Track blockers and relationships between issues

- **Git-friendly**: Dolt-powered version control with native sync

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

- **Prevents duplicate tracking systems and confusion**

## 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

2. **Claim your task atomically**: `bd update <id> --claim`

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

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

   - `bd create "Found bug" --description="Details about what was found" -p 1 --deps discovered-from:<parent-id>`

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

## Auto-Sync

bd automatically syncs via Dolt:

- Each write auto-commits to Dolt history

- Use `bd dolt push`/`bd dolt pull` for remote sync

- No manual export/import needed!

## 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?"

- ✅ Run `bd sync` at end of session

- ✅ Test with `BEADS_DB=/tmp/test.db` (don't create test issues in production)

- ❌ Do NOT create markdown TODO lists

- ❌ Do NOT use external issue trackers

- ❌ Do NOT duplicate tracking systems

## GitHub Copilot Integration

If using GitHub Copilot, also create `.github/copilot-instructions.md` for automatic instruction loading. Run `bd onboard` to get content.

## MCP Server (Recommended)

If using Claude or MCP-compatible clients, install **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 ephemeral files**

Create `temp/history/` directory in project root:

```

temp/history/

```

Store ALL AI-generated planning/design docs in `temp/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 project

Example `.gitignore` entry:

```gitignore

# AI planning documents (ephemeral)

history/

```

## CLI Help

Run `bd <command> --help` to discover all available flags:

```bash

bd create --help    # Shows --parent, --deps, --assignee, etc.

bd update --help    # Shows all update flags

bd list --help      # Shows search and filter flags

```

## Reference

[beads GitHub](https://github.com/steveyegge/beads)

# Documentation

---

name: documentation-workflow

description: Documentation workflow, structure, and best practices for maintaining project documentation. Use when creating, updating, or refactoring documentation.

---

## Documentation Requirements

# Documentation Workflow

### README.md Structure

## Overview

- Provide a clear project description and legal disclaimer.

- Document installation instructions using `uv`.

- Include a quick start guide with examples.

- Link to API documentation.

- Describe conformance testing expectations.

- Outline contributing guidelines.

This skill defines the workflow for maintaining project documentation across multiple audiences (humans and AI coding assistants) and ensuring consistency between code and documentation.

### Code Documentation

- Write Google-style docstrings for all public APIs.

- Provide type hints on all function signatures.

- Add inline comments for complex algorithms.

- Include examples in docstrings where appropriate.

- Write clear and concise docstrings for all functions, classes, and modules using the Google style.

- Include type hints in docstrings for function parameters and return values.

- Use examples in docstrings to illustrate how to use functions and classes.

- Ensure that the code is well-commented to explain complex logic and decisions.

## User Documentation

### Documentation Structure

## Documentation Structure

This repository maintains separate documentation for humans and for coding agents:

1. **docs/index.md** - Main documentation entry point (Jekyll-ready)

1. **docs/\*.md** - Modular task-oriented user guides (crawl, query, utils, etc.)

1. **README.md** - Project overview and contributor entry points

1. **docs/agents-md/** - Agent-facing modular implementation and workflow guidance

1. **AGENTS.md** - Core guidelines and rules for coding agents (standalone context)

2. **docs/*.md** - Modular task-oriented user guides (crawl, query, utils, etc.)

3. **README.md** - Project overview and contributor entry points

4. **docs/agents-md/** - Agent-facing modular implementation and workflow guidance

5. **AGENTS.md** - Core guidelines and rules for coding assistants (standalone context)

### Critical Rules

## Critical Rules

- The modular user documentation in `docs/` **MUST** always be up to date and reflect current CLI behavior

- **AGENTS.md** serves as the primary rule set and context for AI assistants

- When adding or modifying features, update relevant sections in both user docs (`docs/*.md`) and agent docs (`docs/agents-md/`)

- Keep documentation consistent with actual implementation

### Documentation Workflow

## Documentation Workflow

**When adding/modifying features:**

### When Adding/Modifying Features

1. **Implement** feature in code

1. **Update** relevant sections in `docs/agents-md/` modular files

1. **Verify** `AGENTS.md` table of contents remains accurate

1. **Test** that all examples in documentation work correctly

1. **Run** linting and formatting on documentation files

2. **Update** relevant sections in `docs/agents-md/` modular files

3. **Verify** `AGENTS.md` table of contents remains accurate

4. **Test** that all examples in documentation work correctly

5. **Run** linting and formatting on documentation files

**Example workflow for adding a new feature:**

### Example Workflow for Adding a New Feature

1. Implement: src/tdoc_crawler/ - add new component

1. Test: tests/ - add corresponding tests

1. Update agent docs: docs/agents-md/ - document new structure/patterns

1. Update human docs (if CLI behavior changed): docs/QUICK_REFERENCE.md

1. Verify: AGENTS.md - table of contents is current

1. Implement: `src/tdoc_crawler/` - add new component

2. Test: `tests/` - add corresponding tests

3. Update agent docs: `docs/agents-md/` - document new structure/patterns

4. Update human docs (if CLI behavior changed): `docs/QUICK_REFERENCE.md`

5. Verify: `AGENTS.md` - table of contents is current

### Documentation Updates

## Documentation Updates

Focus updates on these key areas:

- **3GPP domain/crawling changes** → Use skills in `.config/skills/3gpp/`

- **Architecture changes** → `300_*`

- **Database contract changes** → `320_*`

- **Engineering standards** → `600_*`

- **Testing approaches** → `700_*`

- **Architecture changes** → `docs/agents-md/300_*`

- **Database contract changes** → `docs/agents-md/320_*`

- **Engineering standards** → `docs/agents-md/600_*`

- **Testing approaches** → `docs/agents-md/700_*`

### Cleanup

## Documentation Cleanup

Any documentation generated during development should be:

- Removed from project root after integration

- Kept focused and concise without redundant information

______________________________________________________________________

### General Documentation Guidelines

## General Documentation Guidelines

- Use markdown formatting for headings, lists, code blocks, and links

- Use clear and concise language

- Keep documentation focused on practical guidance for developers

- Ensure all code examples are tested and functional

- Maintain consistency across all modular documentation files

## References

- Jekyll documentation site: https://jekyllrb.com/

- Markdown guide: https://www.markdownguide.org/

---

name: mcp-context7

description: Automatic documentation and library API discovery using Context7 MCP server

---

# Context7 - Automatic Documentation

**If MCP server `context7` is available**, always use it when generating code, setup steps, or library/API documentation.

## When to Use

Use context7 for:

- **Generated code examples**: Any code, configuration, or implementation steps

- **Library API documentation**: Resolve library IDs and get docs automatically

- **Setup instructions**: Installation, configuration, or initialization steps

- **Tool integration**: How to use tools together

## Library API Discovery

When working with a library:

1. **Context7 will automatically**: Identify the library and its usage

2. **Fetch documentation**: Get relevant API docs without you asking explicitly

3. **Provide examples**: Show how to use the library in this project's context

## Example Workflow

When you need to work with a library:

```

1. Mention the library name

2. Context7 resolves library ID

3. Fetches API documentation

4. Provides usage examples

5. You write code using the library

```

## Best Practices

- **Let context7 work**: Don't try to manually resolve library docs

- **Use in context**: Allow context7 to provide project-specific examples

- **Verify examples**: Ensure provided examples work in your project's context

## References

- [Upstash Context7](https://github.com/upstash/context7)

---

name: mcp-desktop-commander

description: File system operations, process management, terminal interaction, and workspace exploration

---

# Desktop Commander

**If MCP server `desktop-commander` is available**, use this tool for file system and terminal operations.

## When to Use

Use desktop-commander for:

- **File system operations**: Create, edit, read directories and files

- **Process management**: Start, stop, and manage terminal processes

- **Search operations**: Search files and content efficiently

- **Workspace exploration**: Navigate and understand workspace structure

- **Terminal interaction**: Execute shell commands and scripts

## Key Capabilities

### File Operations

```python

# List directory contents

list_directory(path, depth=2)

# Read files

read_file(path, offset=0, length=100)

# Write files

write_file(path, content, mode="rewrite" | "append")

# Create directories

create_directory(path)

```

### Process Operations

```python

# Start process

start_process(command, timeout_ms=120000, shell="powershell")

# Read process output

read_process_output(pid, offset=0, length=100)

# Send input to process

interact_with_process(pid, input="command", timeout_ms=8000)

# Terminate process

force_terminate(pid)

```

### Search Operations

```python

# Start file search

start_search(path, pattern, search_type="files" | "content")

# Get search results

get_more_search_results(session_id, offset=0, length=100)

# Stop search

stop_search(session_id)

```

## Best Practices

- **Use for file operations**: Prefer desktop-commander over manual shell commands

- **Batch operations**: Use read_multiple_files for multiple files

- **Error handling**: Handle file permissions and path errors gracefully

- **Process management**: Always terminate processes when done

- **Search efficiently**: Use appropriate search_type for your needs

## References

- [Desktop Commander](https://github.com/wonderwhy-er/DesktopCommanderMCP)

---

name: mcp-fetch

description: Web content fetching and extracting relevant information from URLs for AI agents.

---

# Fetch - Web Content Retrieval

**If MCP server `fetch` is available**, use it to fetch and analyze web content from URLs.

## When to Use

Use fetch for:

- **Documentation retrieval**: Fetch documentation from URLs

- **API information**: Get API specs or reference docs

- **Example code**: Download code examples from documentation

- **External references**: Fetch content referenced in issues or PRs

## Usage

```python

fetch_url(url, format="markdown" | "text" | "html")

```

- **url**: The URL to fetch content from

- **format**: Output format (markdown default)

## Format Options

- **markdown**: Rendered markdown (default)

- **text**: Plain text content

- **html**: Raw HTML

## Best Practices

- **Use for docs**: Prefer fetch over manual web browsing

- **Parse carefully**: Extract relevant information from fetched content

- **Cite sources**: Reference URLs when using fetched information

## Examples

```python

# Fetch documentation

fetch_url("https://example.com/docs/api.html", format="markdown")

# Fetch raw content

fetch_url("https://example.com/config.json", format="text")

```

## References

- [Fetch MCP](https://github.com/zcaceres/fetch-mcp)