beads-village

Category: Tools & Productivity | Uploader: LNS2905 | Downloads: 0 | Version: v1.0（Latest）

Use when working with beads-village MCP tools for multi-agent task coordination — covers init, claim, reserve, done lifecycle and common anti-patterns

Changelog: Source: GitHub https://github.com/LNS2905/mcp-beads-village

Directory Structure

Current level: tree/master/skills/beads-village/

📄 SKILL.md 3.5 KB

SKILL.md

---
name: beads-village
description: Use when working with beads-village MCP tools for multi-agent task coordination — covers init, claim, reserve, done lifecycle and common anti-patterns
---

# Beads Village Workflow

Multi-agent task coordination via MCP. Every session follows one lifecycle.

## Lifecycle (Mandatory Order)

```
init() → claim() → reserve(paths) → WORK → done(id, msg) → RESTART SESSION
```

```dot
digraph lifecycle {
  init [shape=box label="init()"];
  claim [shape=box label="claim()"];
  reserve [shape=box label="reserve(paths)"];
  work [shape=box label="Edit files"];
  done [shape=box label="done(id, msg)"];
  restart [shape=doublecircle label="Restart session"];
  side [shape=box label="add() side issue"];

  init -> claim;
  claim -> reserve;
  reserve -> work;
  work -> done;
  work -> side [style=dashed label="discovery"];
  side -> work;
  done -> restart;
}
```

## Rules

| Rule | Why |
|------|-----|
| `init()` is always first | All tools depend on workspace state |
| `reserve()` before editing | Prevents multi-agent file conflicts |
| Always include `desc` in `add()` | Context required for other agents |
| `done(id, msg)` with message | Msg communicates what was accomplished |
| Restart session after `done()` | Clean state for next task |
| `release()` when switching tasks | Prevents lock starvation |
| >2 min discovery → file as side issue | Keep tasks atomic |

## Quick Reference

### Core Tools

| Tool | Purpose | Key params |
|------|---------|------------|
| `init(team?, role?, leader?)` | Join workspace | `start_tui` is deprecated |
| `claim()` | Get next ready task | Auto-filtered by role |
| `reserve(paths, reason?, ttl?, mode?, region?)` | Lock files | `mode`: exclusive/shared, `region`: edit scope hint |
| `release(paths?)` | Unlock files | Empty = release all |
| `done(id, msg?)` | Complete task | Auto-releases locks |
| `add(title, desc, typ?, pri?, tags?)` | Create issue | Always include desc |
| `ls(status?)` | List issues | `ready` = no blockers |
| `show(id)` | Full issue details | |
| `msg(subj, body?, to?, global?)` | Send message | `global=true, to="all"` = broadcast |
| `inbox(n?, unread?)` | Check messages | SQLite-backed |
| `search_messages(query, status?, limit?)` | FTS5 search messages | Search subjects + bodies |
| `ack_message(id)` | Acknowledge message | Auto-replies to sender |
| `status(include_agents?)` | Workspace overview | Teammate discovery |
| `sync()` | Git sync | Auto-called by done() |

### Patterns

**Shared reservation (concurrent editing):**
```
reserve(paths=["src/app.py"], mode="shared", region="function parse_args")
```

**Side issue:**
```
add(title="Bug in auth", desc="Found during bd-42", typ="bug", parent="bd-42")
```

**Broadcast completion:**
```
done(id="bd-10", msg="API endpoints ready")
msg(subj="API Ready", global=true, to="all")
```

**Search + acknowledge:**
```
search_messages(query="deploy")
ack_message(id=42)
```

**Blocked → switch:**
```
release()   # Free current locks
claim()     # Get different task
```

## Red Flags

- Editing files without `reserve()` first
- Calling any tool before `init()`
- Creating issues without `desc`
- Forgetting `done()` (locks stay held)
- Not restarting session after `done()`
- Holding reservations across task switches

## Response Fields

`id`=Issue ID, `t`=title, `p`=priority(0-4), `s`=status, `f`=from, `b`=body, `tags`=role tags

## Priority

0=critical (production down), 1=high (blocking), 2=medium (default), 3=low, 4=backlog

## Roles

`fe`, `be`, `mobile`, `devops`, `qa` — used for `tags` in `add()` and `role` in `init()`

Comments 0

Latest | Hot

Please login before commenting.

No comments yet. Be the first one!

beads-village

Directory Structure

SKILL.md

Report

Notice