Workflow

This section is a deep dive into Brewcode mechanics. Unlike the Quick Start, here every stage is covered: from specification creation to automatic context handoff between sessions and artifact structure.

High-level overview

/brewcode:spec              /brewcode:plan              /brewcode:start
      |                           |                           |
  Research                   Phase generation            Execution loop
  (5-10 agents)              + quorum review             + handoff
      |                           |                           |
      v                           v                           v
   SPEC.md                     PLAN.md                   artifacts/
                              phases/                   KNOWLEDGE.jsonl
                           KNOWLEDGE.jsonl                FINAL.md

Phase 1: Specification (/brewcode:spec)

The spec skill creates a structured task specification through parallel codebase research and user dialog.

Phase 2: Planning (/brewcode:plan)

The plan skill transforms a specification into a detailed plan with phases, dependencies, and completion criteria.

Input sources

Phase generation

Each task is split into 5-12 phases. For every execution phase, a verification phase is created, and a Final Review is added at the end.

phases/
├── 1-create-entity.md          # Execution: developer
├── 1V-verify-entity.md         # Verification: reviewer
├── 2-implement-service.md      # Execution: developer
├── 2V-verify-service.md        # Verification: tester
├── 3-add-api-endpoint.md       # Execution: developer
├── 3V-verify-endpoint.md       # Verification: reviewer
└── FR-final-review.md          # Final Review: reviewer+tester+architect

Phase Registry in PLAN.md

PLAN.md uses a “slim” v3 format — only the Phase Registry table and metadata. Phase details are in separate phases/*.md files.

Plan quorum review

3 agents review the plan in parallel. The 2/3 rule: an issue is accepted only if confirmed by 2+ agents.

After the quorum — requirements tracing: every SPEC item must have a phase in the plan.

Phase 3: Execution (/brewcode:start)

The start skill is the heart of Brewcode. It executes tasks with infinite context via Task API, the 2-step protocol, and automatic handoff during compaction.

Initialization

/brewcode:start -> Load PLAN.md -> Parse Phase Registry
   |
   v
TaskCreate for each phase -> TaskUpdate dependencies
   |
   v
Execution Loop: TaskList() -> pending+unblocked -> spawn agents

1. Resolve path — from arguments or .claude/TASK.md
2. Initialize — bc-coordinator creates the lock, sets status to in progress
3. Load context — reads PLAN.md and KNOWLEDGE.jsonl (NOT phases/ — those are for agents)
4. Create tasks — TaskCreate for each Phase Registry row
5. Set dependencies — TaskUpdate with addBlockedBy

Execution loop

LOOP while pending tasks remain:
  1. TaskList() -> find pending + unblocked
  2. Same group -> launch in PARALLEL (one message)
  3. For each:
     a. TaskUpdate(status="in_progress")
     b. Task(agent) -> execution
     c. WRITE report -> artifacts/{P}-{N}{T}/{AGENT}_output.md
     d. CALL bc-coordinator (knowledge extraction)
     e. TaskUpdate(status="completed")
  4. On verification failure -> fix loop (max 3 iterations)
  5. Deadlock check

2-step protocol

After every agent, two steps must be performed:

Failure escalation

When escalation is exhausted — cascading failure: dependent tasks are marked failed, independent ones continue execution.

Handoff mechanism (context transfer)

Handoff is Brewcode’s key mechanism that provides “infinite context”. When Claude Code approaches the context window limit, automatic compaction kicks in.

What happens during compaction

KNOWLEDGE.jsonl

KNOWLEDGE.jsonl is the knowledge accumulation file that is transferred between sessions and injected into agent prompts.

Entry format

{"ts":"2026-01-26T14:00:00","t":"❌","txt":"Avoid SELECT * in JOOQ queries","src":"reviewer"}
{"ts":"2026-01-26T14:05:00","t":"✅","txt":"Use .fetchInto(Record.class) for type-safe queries","src":"developer"}
{"ts":"2026-01-26T14:10:00","t":"ℹ️","txt":"Project uses PostgreSQL 15 with JOOQ 3.19","src":"architect"}

Entry types

Knowledge lifecycle

Agent completes work
      |
      v
bc-coordinator reads report -> extracts 3-10 entries
      |
      v
KNOWLEDGE.jsonl accumulates entries
      |
      v
pre-compact hook: deduplicate + trim to maxEntries
      |
      v
pre-task hook: compress to maxTokens -> inject as ## K block
      |
      v
/brewcode:rules -> sync to .claude/rules/ (avoid.md, best-practice.md)
      |
      v
bc-knowledge-manager: prune-rules (remove synced entries)

Injection into agents

The pre-task.mjs hook compresses KNOWLEDGE.jsonl to maxTokens (default 500) and adds a ## K block to the agent prompt:

## K
❌ Avoid SELECT * in JOOQ queries
✅ Use .fetchInto(Record.class)
ℹ️ PostgreSQL 15 + JOOQ 3.19

System agents (Explore, Plan, general-purpose) do not receive the ## K block.

Artifact structure

.claude/tasks/{TS}_{NAME}_task/
├── PLAN.md                          # Phase Registry + metadata
├── SPEC.md                          # Task specification
├── KNOWLEDGE.jsonl                  # Accumulated knowledge
├── phases/                          # Phase files (for agents)
│   ├── 1-create-entity.md
│   ├── 1V-verify-entity.md
│   ├── 1F1-fix-entity.md           # Fix phase (created dynamically)
│   └── FR-final-review.md
├── artifacts/                       # Agent reports
│   ├── FINAL.md                     # Final report
│   ├── 1-1e/                        # Phase 1, Execution, iter 1
│   │   └── developer_output.md
│   ├── 1-1v/                        # Phase 1, Verification, iter 1
│   │   └── reviewer_output.md
│   └── FR-1e/                       # Final Review
│       └── reviewer_output.md
├── backup/                          # Backups
└── .lock                            # Session lock file

Artifact naming

Finalization

After all phases are complete:

1. bc-coordinator generates FINAL.md with consolidated results
2. Task status -> finished
3. /brewcode:rules extracts knowledge into .claude/rules/
4. bc-knowledge-manager removes synced entries from KNOWLEDGE.jsonl
5. Lock file is deleted on the next Stop