start — infinite context execution

opus session

Caution

Context limits kill long tasks. A complex task spanning dozens of files and hours of work will hit Claude’s context window. Without handoff, all progress is lost and the task starts from scratch in a new session.

Tip

Start handles the full lifecycle. It reads your PLAN.md, spawns agents per phase, calls bc-coordinator after every agent, and after compaction resumes exactly where it left off — no manual intervention required.

Quick reference

Field	Value
Command	`/brewcode:start`
Arguments	`[task-path]` — defaults to first line of `.claude/TASK.md`
Model	opus
Tools	Read, Write, Edit, Bash, Task, Glob, Grep, Skill, AskUserQuestion

When to use

Run a task plan — after /brewcode:plan has produced a PLAN.md, use /brewcode:start to execute it
Resume after compaction — if the session compacted mid-task, re-invoke /brewcode:start with the same task path to continue
Long multi-phase projects — any task with more than 3 phases that you expect to take over 30 minutes
Parallel agent work — phases in the same parallel group are spawned together in a single message
After a failed session — if a previous run ended with agent errors, re-run to retry or escalate the failed phases
Pipeline step 3 — in the full brewcode pipeline the order is: setup → spec → plan → start → review

Examples

# Execute the active task (reads path from .claude/TASK.md)
/brewcode:start

# Execute a specific task by path
/brewcode:start .claude/tasks/20260417-120000_refactor-api_task/

# Natural language also works
"start the task"
"run the plan"
"execute brewcode task"

What you see during execution:

[bc-coordinator] initialize → task locked, status: in_progress
[manager] Phase Registry: 5 phases parsed, 3 parallel groups detected
[manager] TaskCreate: Phase 1 (analysis), Phase 2 (implementation), Phase 3 (tests)
[agent: developer] Phase 2 started → artifacts/P2-1T/developer_output.md
[bc-coordinator] standard → report validated, KNOWLEDGE updated
[manager] Phase 2 completed. Next: Phase 3 (unblocked)
...
[bc-coordinator] finalize → status: finished
[brewcode:rules] 4 patterns extracted → .claude/rules/

After compaction in a long session:

[autocompact triggered at ~93% context]
→ new session: /brewcode:start .claude/tasks/20260417-120000_refactor-api_task/
[manager] TaskList() → Phase 1 completed, Phase 2 in_progress, Phase 3 pending
[manager] Resuming Phase 2 with developer agent...

Flow

Resolve task path
Reads the path from $ARGUMENTS or from the first line of .claude/TASK.md. If neither exists, stops with a message directing you to run /brewcode:spec then /brewcode:plan first.
Initialize via coordinator
Spawns bc-coordinator in initialize mode. The coordinator validates the task directory, creates a lock file, and sets status to in_progress. Required — cannot be skipped.
Load context
Reads PLAN.md and KNOWLEDGE.jsonl. Verifies the artifacts/ directory exists. The phases/ directory is intentionally not read here — phase files are instructions for agents, not the manager.
Create tasks from Phase Registry
Parses the ## Phase Registry table in PLAN.md. Creates a TaskCreate for each row with phase number, summary, phase file path, artifact directory, and KNOWLEDGE path. Builds a phase-to-taskId map because IDs auto-increment and may not match phase numbers.
Execution loop
Calls TaskList() to find pending tasks with no blockers. Spawns all tasks in the same parallel group in one message. After each agent succeeds: writes a report to artifacts/, calls bc-coordinator in standard mode, marks the task completed. On failure: retries once, then escalates (R&D → split → reassign). On verification failure: writes a fix phase file and re-queues.
Handoff after compact
When context compacts, the next session calls TaskList() as the source of truth, re-reads PLAN.md for protocol, and continues from the current in_progress or next pending task. No phases/ files re-read. The 2-step write-report → call-coordinator protocol is always enforced.
Finalize and extract rules
Calls bc-coordinator in finalize mode (status: finished or failed). Then invokes /brewcode:rules to extract reusable patterns from KNOWLEDGE.jsonl into project rules, and bc-knowledge-manager to prune stale entries.

Session handoff & KNOWLEDGE

After compaction, the skill resumes with this exact sequence:

TaskList() — current task state is the only source of truth after compact
Read PLAN.md — protocol and Phase Registry (never phases/ files)
Continue with in_progress task or pick next pending with no blockers
WRITE report → CALL bc-coordinator after every agent — no exceptions

KNOWLEDGE.jsonl accumulates entries during the run:

Priority	Tag	Meaning
High	`❌`	Anti-patterns to avoid in this task
Medium	`✅`	Confirmed working patterns
Low	`ℹ️`	Architecture facts, decisions

Entries survive compaction because they are written to disk. The bc-knowledge-manager prunes low-value entries at finalization so the file stays useful for future tasks.

Deadlock detection runs after every loop iteration:

Condition	Meaning	Action
`ready=0, active=0, blocked>0`	Circular dependency or all dependents of a failed task	Cascade failure to all blocked tasks, finalize as `failed`
`ready=0, active=0, blocked=0`	All tasks done	Break loop, finalize as `finished`
Any other state	Work in progress	Continue loop

When a task fails permanently, the failure cascades transitively to all dependent tasks. Independent tasks (no dependency chain to the failed task) continue normally.

Escalation after repeated agent failures:

After	Action
1 fail	R&D task: explore root cause
2 fails	Split phase into sub-phases
3 fails	Upgrade model, reassign, or AskUserQuestion

📄

Updating plugins

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

start — infinite context execution

Caution

Tip

Quick reference

When to use

Examples

Flow

Plan

bc-coordinator

GitHub source

Brewcode overview

Rules

Updating plugins