kimchi:beads

# Kimchi Beads

<command_purpose>
Convert plan tasks into self-contained bead YAML files with full context (using find: landmarks), deliverables, test specifications, and acceptance criteria. Each bead must be executable by an agent with ZERO external context.
</command_purpose>

## Input

Read in order of preference: `.kimchi/PLAN-SYNTHESIZED.md`, `.kimchi/PLAN-DRAFT.md`, `.kimchi/PLAN-REVIEWED.md`, or `.kimchi/PLAN.md`.
Also read `.kimchi/RESEARCH.md` for context references with landmarks.

Parse options:
- `--orchestration acfs|gastown` (default: acfs) — Determines the orchestration system that will consume and execute the beads. This affects manifest metadata and post-generation guidance.

## Process

### 1. Create .beads/ Directory

```bash
mkdir -p .beads
```

### 2. Convert Each Task to Bead YAML

For each task in the plan, create a bead file at `.beads/{id}-{slug}.yaml`:

```yaml
bead_id: "[ID]"
title: "[Task title]"
description: |
  [Detailed description of what to implement.
   Must be complete enough to execute without reading the plan.]

depends_on: ["[bead IDs]"]

context:
  - file: "[path/to/file]"
    find: "[search term to locate relevant code]"
    scope: "[entire class|entire method|block|etc]"
    purpose: "[Why this context is relevant]"

deliverables:
  - type: "[file_create|file_modify|file_delete]"
    path: "[full/path/to/file]"
    find: "[anchor point for file_modify]"
    action: "[add after|replace|add before — for file_modify]"
    description: |
      [What will be created or changed]

tests:
  file: "[path/to/test/file]"
  cases:
    - "[Test case description 1]"
    - "[Test case description 2]"
    - "[Edge case description]"
  run_command: "[command to run tests]"

acceptance_criteria:
  - "[Verifiable criterion 1]"
  - "[Verifiable criterion 2]"

estimated_complexity: "[S|M|L]"
requirements: ["[REQ-ID1]", "[REQ-ID2]"]
```

### 3. Context Rules (CRITICAL)

**Every file reference MUST use `find:` landmarks:**

```yaml
# GOOD
context:
  - file: "app/services/storage/s3_client.rb"
    find: "class S3Client"
    purpose: "Existing S3 wrapper to use"

# BAD — never use line numbers
context:
  - file: "app/services/storage/s3_client.rb"
    lines: "12-34"
```

**Find terms must be:**
- Specific enough to be unique in the file
- Stable (survive refactoring — class names, method names, not comments)
- Appropriate scope for purpose

### 4. Test Case Minimums

| Complexity | Minimum Cases | Edge Cases Required |
|------------|--------------|-------------------|
| S | 2+ | 0 |
| M | 4+ | 1+ |
| L | 6+ | 2+ |

### 5. Create Manifest

Write `.beads/manifest.yaml`:

```yaml
version: "1.0"
plan_id: "[feature-slug]-[date]"
created_at: "[ISO 8601 timestamp]"
created_by: "kimchi:beads"
orchestration: "[acfs|gastown]"  # Which system will execute these beads

source:
  context: ".kimchi/CONTEXT.md"
  requirements: ".kimchi/REQUIREMENTS.md"
  plan: ".kimchi/PLAN-SYNTHESIZED.md"  # or whichever plan file was used

beads:
  - id: "[ID]"
    file: "[filename].yaml"
    status: "pending"
    depends_on: []

  - id: "[ID]"
    file: "[filename].yaml"
    status: "pending"
    depends_on: ["[ID]"]

dependency_graph: |
  [ASCII art showing dependency relationships]
```

### 6. Validate No Cycles

Check that the dependency graph has no circular dependencies. If cycles found, report them as errors and ask user to resolve.

Report: "Beads created. [N] bead files in .beads/"
Suggest: "Run `/kimchi:validate` to verify beads are standalone-executable."

### 7. Orchestration-Specific Guidance

After bead generation, provide guidance based on the `--orchestration` flag:

**If `acfs` (default):**
```
Beads are configured for ACFS orchestration.
Next: Run /kimchi:validate, then use /kimchi:bead-protocol for execution.
```

**If `gastown`:**
```
🏘️ These are GasTown-compatible beads.
The manifest is tagged with orchestration: gastown.

To execute these beads, use the GasTown mayor process:
  1. The mayor reads .beads/manifest.yaml to understand the dependency graph
  2. The mayor assigns beads to worker agents based on availability and dependencies
  3. Workers execute beads and report completion back to the mayor
  4. The mayor tracks progress and unblocks dependent beads as predecessors complete

Do NOT use /kimchi:bead-protocol (that's for ACFS). Let the mayor handle coordination.
Run /kimchi:validate first to ensure beads are standalone-executable.
```

## Key Principles

- **Self-contained**: An agent reads ONE bead and has everything it needs
- **No cross-references**: Don't say "use the service from bead 002". Point to the actual file.
- **Landmarks over coordinates**: `find:` always, line numbers never
- **Explicit over implicit**: If the agent might need to search for it, put it in the bead