Help us improve
Share bugs, ideas, or general feedback.
From kimchi
Detects bead task orchestration (GasTown or ACFS) from .beads/manifest.yaml and enforces protocol: read full bead, load context, TDD, prefixed git commits, verification, and mayor coordination.
npx claudepluginhub tromml/kimchi --plugin kimchiHow this skill is triggered — by the user, by Claude, or both
Slash command
/kimchi:bead-protocolThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Beads are self-contained task specifications. Executing them requires discipline: read fully, follow context, communicate status.
Converts markdown plans into structured beads with tasks, subtasks, and dependency links for implementation or swarm execution. Includes polishing protocol and lifecycle disciplines.
Guides implementation of a single bead in Lavra's workflow, including clarification, knowledge recall, and phased implementation with state machine. Invoked when working on exactly one bead.
Guides using Beads (bd) distributed git-backed issue tracker for task management, dependency tracking, AI agent workflows, and multi-branch parallel development.
Share bugs, ideas, or general feedback.
Beads are self-contained task specifications. Executing them requires discipline: read fully, follow context, communicate status.
Core principle: A bead contains everything you need. Read it completely before writing any code.
Before anything else, read .beads/manifest.yaml and check the orchestration field:
orchestration: gastown → Follow the GasTown Protocol section beloworchestration: acfs or field is missing → Follow the ACFS Protocol section belowREAD THE FULL BEAD BEFORE WRITING ANY CODE
No skimming. No "I'll check the rest later." Read every field.
🏘️ These are GasTown-managed beads. Coordination is handled by the mayor, not by individual agents.
If you are an agent and this manifest says orchestration: gastown, do NOT use the ACFS workflow below. Instead:
kimchi:tdd skill, write tests from the bead's tests.cases first{bead_id}: {description}What the mayor handles (NOT your responsibility in GasTown):
What you still own:
kimchi:verification-before-completion before reporting doneReport the blocker to the mayor. The mayor will reassign work or unblock you. Do NOT try to coordinate directly with other agents — that's the mayor's job.
This section applies when
orchestration: acfsor no orchestration field is set.
Before any code:
cat .beads/{bead_id}-{slug}.yaml
Understand ALL of:
find: landmark)Before editing any file:
# Check if file is reserved by another agent
acfs reserve --check {file_path}
If reserved:
Before starting work, claim the bead in the manifest to prevent duplicate execution:
# Update manifest status from "pending" to "in_progress"
# Include your agent name so others know who's working on it
sed -i '/id: "{bead_id}"/,/status:/ s/status: "pending"/status: "in_progress: {agent_name}"/' .beads/manifest.yaml
git add .beads/manifest.yaml && git commit -m "{bead_id}: claimed by {agent_name}"
git push origin HEAD:beads-sync
If the manifest already shows in_progress for your bead, STOP — another agent has it.
# Reserve files you'll be editing
acfs reserve --add {file_path} --ttl 3600
For each context reference in the bead:
find: value)Do not skip any context entry. Each one is there for a reason.
acfs bead status {bead_id} --set in_progress
Use the kimchi:tdd skill. Write tests from the bead's tests.cases field first.
Each logical unit of work gets a commit:
git add {specific_files}
git commit -m "{bead_id}: {description}"
Commit message format:
If blocked on a dependency:
Check if blocking bead is complete:
acfs bead status {blocking_bead_id}
If not complete, send Agent Mail:
acfs mail send \
--to {agent_on_blocking_bead} \
--subject "Blocked on {blocking_bead_id}" \
--body "Bead {bead_id} needs {specific_thing} from {blocking_bead_id}"
Work on non-blocked tasks while waiting
Complete the kimchi:verification-before-completion skill checklist:
acfs reserve --release {file_path}
acfs bead status {bead_id} --set complete
git push origin HEAD:beads-sync
acfs mail send \
--to {waiting_agents} \
--subject "Bead {bead_id} complete" \
--body "Deliverables available: {list}"
| Excuse | Reality |
|---|---|
| "I'll read the rest of the bead later" | You'll miss context. Read it all now. |
| "I know what this bead needs" | The bead knows what it needs. Read it. |
| "Skip context, I know the codebase" | Context entries reference specific patterns. Read them. |
| "Reservations slow me down" | Merge conflicts slow you down more. (ACFS) |
| "Agent Mail is overhead" | Silent blocking wastes everyone's time. (ACFS) |
| "I'll just coordinate directly" | Let the mayor handle it. (GasTown) |
ALL of these mean: STOP. Go back to step 1.
Read the full bead and find all landmarks before writing code. Every context entry exists for a reason.
Always update status. A bead stuck in "in_progress" blocks downstream work.
Always check reservations first. Conflicts waste everyone's time.
If you're blocked, communicate immediately via Agent Mail. Don't wait and hope.
Don't message other agents directly. The mayor handles all inter-agent coordination.