bc-coordinator

Caution

The coordinator never writes code. It validates report files on disk, extracts knowledge entries, updates the Phase Status table in PLAN.md, and generates FINAL.md on completion. Per-phase Status: and Result: fields are managed exclusively by the manager via the Task API — the coordinator never touches them.

Tip

Called automatically by /brewcode:start. You never invoke bc-coordinator directly. The manager calls it after each agent completes, passing the report path as a flat text prompt. On task completion, the manager calls it one final time with mode: finalize.

Quick reference

FieldValue
Agentbc-coordinator
Modelhaiku
ToolsRead, Write, Edit, Bash
Permission modeacceptEdits
Invoked by/brewcode:start manager (never directly)
Modesinitialize, standard, finalize

When to use

  • Phase just completed — manager writes {AGENT}_output.md, then calls coordinator with mode: standard and the report path
  • Task starting — manager calls coordinator with mode: initialize to validate the PLAN.md structure, create the lock file, and transition status from pending to in progress
  • Task finished or failed — manager calls coordinator with mode: finalize to write FINAL.md and set the terminal status on line 1 of PLAN.md
  • KNOWLEDGE.jsonl nearing capacity — coordinator auto-compacts when entry count reaches maxEntries * 0.8, deduplicating and sorting by priority (❌ > ✅ > ℹ️)

Examples

Initialize at task start:

mode: initialize
taskPath: .claude/tasks/20260417-120000_my-feature_task/PLAN.md

Coordinator validates the task structure, creates the .lock file, and flips line 1 from status: pending to status: in progress.

After an agent completes (standard mode):

mode: standard
taskPath: .claude/tasks/20260417-120000_my-feature_task/PLAN.md
report: artifacts/1-1e/developer_output.md

Coordinator verifies the file exists on disk, reads it, extracts 3–10 KNOWLEDGE entries, and updates the Phase Status table.

Finalize on success:

mode: finalize
taskPath: .claude/tasks/20260417-120000_my-feature_task/PLAN.md
status: finished

Generates FINAL.md from the report template, sets line 1 to status: finished. The stop hook reads this value — any non-terminal status blocks session exit.

Flow

  1. Receive mode + taskPath

    The manager sends a flat text prompt specifying mode, taskPath, and (in standard mode) the report path. Coordinator reads lines 1–3 of PLAN.md for current state.

  2. Verify report on disk

    In standard mode: checks that {AGENT}_output.md exists at the given path. If missing — returns an error immediately. The manager must write the file before calling coordinator.

  3. Extract knowledge

    Reads the report and appends 3–10 genuinely reusable entries to KNOWLEDGE.jsonl using the schema `{"ts":"ISO","t":"❌|✅|ℹ️","txt":"...","src":"agent"}`. Skips phase summaries, vague statements, and progress notes.

  4. Update Phase Status table

    Adds or updates the row for the current phase in the ## Phase Status section at the bottom of PLAN.md. This is the only PLAN.md body section the coordinator ever writes.

  5. Auto-compact KNOWLEDGE if needed

    Counts entries. If count is at or above maxEntries * 0.8: deduplicates by exact txt match, sorts by priority then timestamp descending, trims to maxEntries, and atomically rewrites the file.

  6. Return summary

    Prints phase number, report verification result, KNOWLEDGE entry count, compaction status, and an explicit next-action recommendation for the manager.

Coordinator protocol & artifact rules

Modes in detail

initialize — called once at /brewcode:start:

  1. Validates task file exists and has a ## Phase Registry section
  2. Accepts status pending, in progress, or handoff (allows restart after crash)
  3. Writes .lock file (always overwrites — enables recovery): {"task_path":"...","started_at":"ISO"}
  4. Sets line 1 to status: in progress
  5. Validates/updates .claude/TASK.md reference (single-line path)

standard — called after each agent:

  1. Read PLAN.md header (lines 1–3)
  2. Verify report file exists on disk — error if missing
  3. Read report, extract 3–10 KNOWLEDGE entries
  4. Update Phase Status table (add row or update existing)
  5. Update header lines 2–3 (current_phase, total_phases) if phase completed
  6. Auto-compact KNOWLEDGE if entry count >= threshold

finalize — called on task completion:

  1. Generate FINAL.md from $BC_PLUGIN_ROOT/templates/reports/FINAL.md.template
  2. If status: failed — include failure summary from KNOWLEDGE.jsonl
  3. Set line 1 to status: finished (or failed)
  4. Lock deletion is handled by the stop hook, not coordinator

PLAN.md header format (first 3 lines)

status: in progress
current_phase: 2
total_phases: 5

Terminal statuses for line 1: finished, failed, cancelled, error. Any other value blocks session exit via the stop hook.

Phase Status table

## Phase Status
| # | Status | Started | Completed | Iterations |
|---|--------|---------|-----------|------------|
| 1 | completed | 2026-01-26T14:00 | 2026-01-26T14:30 | 1 |
| 1V | completed | 2026-01-26T14:31 | 2026-01-26T14:45 | 1 |
| 2 | in_progress | 2026-01-26T14:46 | - | 1 |

If the section does not exist — coordinator creates it at the end of PLAN.md. The Completed column is - while in progress, ISO timestamp when done.

Artifact directory layout

{TS}_{NAME}_task/artifacts/
├── FINAL.md
└── {P}-{N}{T}/          # e.g., 1-1e/ (phase 1, iter 1, exec)
    ├── {AGENT}_output.md
    └── summary.md

What coordinator never does

  • Implement code
  • Fabricate or hallucinate report content
  • Create {AGENT}_output.md — manager writes these before calling coordinator
  • Edit per-phase Status: or Result: fields in PLAN.md body (Task API only)
  • Read files from phases/ directory
📄

brewcode overview

All brewcode skills, agents, and hooks in one place.

🚀

/brewcode:start

The skill that drives task execution and calls bc-coordinator at each phase boundary.

🔗

GitHub source

Full coordinator protocol and agent definition.

Updating plugins

Use /brewtools:plugin-update to check and update the brewcode plugin suite in one command. See the FAQ for details.