Brewcode:Start

Execute Task — [task-file-path]

<instructions>

How It Works

/brewcode:start -> Load PLAN.md -> Parse Phase Registry
   |
   v
TaskCreate for each row -> TaskUpdate dependencies
   |
   v
Execution Loop: TaskList() -> pending+unblocked -> spawn agents
   |
   v
Per agent: WRITE report -> CALL bc-coordinator (2-step, ALWAYS)
   |
   v
TaskUpdate(completed) -> repeat -> Finalize
   |
   v
After compact: TaskList() -> Read PLAN.md -> continue

Execution Steps

1. Resolve Task Path

• If $ARGUMENTS has path -> use it
• If $ARGUMENTS empty -> read .claude/TASK.md (first line = active path)
• If neither -> STOP: No task path! Run: /brewcode:spec "description" then /brewcode:plan

2. Initialize via Coordinator (REQUIRED)

Task tool:
  subagent_type: "brewcode:bc-coordinator"
  prompt: "Mode: initialize. Task path: {TASK_PATH}"

Coordinator validates, creates lock, updates status -> in progress.

• Suggest user run /goal (CC 2.1.115+) to anchor the session's objective before execution proceeds.

3. Load Context

• Read PLAN.md (ONLY PLAN.md from the task directory)
• Read KNOWLEDGE.jsonl if exists
• Verify artifacts/ directory exists
• DO NOT read phases/ files -- they are for agents, not the manager

4. Create Tasks from Phase Registry

Parse the ## Phase Registry table in PLAN.md.

FOR each row in Phase Registry:
  TaskCreate(
    subject  = "Phase {#}: {Subject}",
    description = "Phase {#}: {Summary}\n\nFull instructions: phases/{Phase File}\nTask dir: {TASK_DIR}\nArtifacts: artifacts/{Artifact Dir from Phase Registry}/\nKNOWLEDGE: KNOWLEDGE.jsonl",
    activeForm = "{Present continuous of Subject}"
  )

Sub-step 4a: Phase-to-TaskID Map Task IDs are auto-incremented (1,2,3...) and may NOT match Phase # (1,1V,2,3...). Build a map: {phase# -> taskId} during creation. Include phase # explicitly in description.

5. Set Dependencies

FOR each row where "Blocked By" column is non-empty:
  TaskUpdate(taskId, addBlockedBy=[mapped task IDs from Blocked By column])

6. Execution Loop

LOOP while pending tasks remain:
  a. TaskList() -> find tasks: status=pending, blockedBy=[]
  b. Same Parallel group -> spawn in ONE message (parallel Task calls)
  c. Per task:
     i.   TaskUpdate(taskId, status="in_progress")
     ii.  Task(subagent_type="{Agent from Phase Registry}", prompt from description)
          -- If Phase Registry agent not found as plugin: check `.claude/agents/` for project/team agent
     -- If agent REFUSED (Task Acceptance Protocol — returned refusal with colleague suggestion):
        a. Re-delegate to suggested colleague agent (max 2 retries)
        b. If no suitable colleague or retries exhausted: fall back to plugin agent
        c. Log refusal to KNOWLEDGE.jsonl:
           {"ts":"...","t":"ℹ️","txt":"Phase {N}: {agent} refused, re-delegated to {new_agent}","src":"manager"}
     -- If agent FAILED (is_error=true):
        a. TaskUpdate(taskId, status="in_progress") -- keep in progress for retry
        b. Persist failure to KNOWLEDGE.jsonl:
           {"ts":"...","t":"❌","txt":"Phase {N} agent failed: {error_summary}. Attempt {I}/{MAX}.","src":"manager"}
        c. Retry once with same agent
        d. If retry fails: TaskUpdate(taskId, status="failed"), apply Escalation table
        e. Skip steps iii-v (no report to write, no coordinator to call)
     -- If agent SUCCEEDED:
        iii. WRITE report -> artifacts/{P}-{N}{T}/{AGENT}_output.md
        iv.  Task(subagent_type="brewcode:bc-coordinator",
                  prompt="Mode: standard. Task path: {TASK_PATH}. Report: {REPORT_PATH}")
             -- If coordinator FAILED (is_error=true): log warning, proceed to TaskUpdate(completed)
        v.   TaskUpdate(taskId, status="completed")
  d. On verification FAIL:
     i.   Read verification report from artifacts/{P}-{N}{T}/{VERIFY_AGENT}_output.md
          (manager can read artifacts/ — the rule is NEVER read phases/)
          Extract: {ISSUES_TABLE}, {FILES_TO_FIX} from the issues table in the report
          {VERIFY_AGENT} = agent from the verification row in Phase Registry
          {VERIFY_ARTIFACT_DIR} = artifact dir of the verification phase
     ii.  Write phases/{N}F{I}-fix-{name}.md using phase-fix.md.template
          (from .claude/tasks/templates/ or $BC_PLUGIN_ROOT/skills/setup/templates/)
          Fill: {PHASE_NUM}, {ITERATION}, {PHASE_NAME}, {FIX_AGENT}=original agent,
          {ORIGINAL_PHASE_FILE}, {VERIFY_ARTIFACT_DIR}, {VERIFY_AGENT},
          {ISSUES_TABLE} from verification report (step 6.d.i), {FILES_TO_FIX}, {ARTIFACT_DIR}
     iii. TaskCreate(subject="Fix phase {N} issues (iter {I})", ...)
     iv.  TaskCreate(subject="Re-verify phase {N} (iter {I+1})",
               addBlockedBy=[fix task ID])
     v.   Max 3 iterations -> Escalation
  e. Deadlock check after each iteration:
     TaskList() -> categorize:
     - ready = pending + blockedBy=[]
     - blocked = pending + blockedBy non-empty
     - active = in_progress
     If ready=0 AND active=0 AND blocked>0:
       DEADLOCK -> cascade failure to all blocked tasks, BREAK -> Finalize(status="failed")
     If ready=0 AND active=0 AND blocked=0:
       ALL DONE -> BREAK -> Finalize(status="finished")
     Else: continue loop

Escalation after repeated failures:

Failure Cascade

When escalation exhausted (task permanently failed): 1. TaskUpdate(failedTaskId, status="failed") 2. Persist to KNOWLEDGE.jsonl: {"ts":"...","t":"❌","txt":"Phase {N} permanently failed: {reason}","src":"manager"} 3. Cascade: TaskList() -> for each task T where failedTaskId in T.blockedBy (transitive): TaskUpdate(T.id, status="failed") 4. Log: "Phase {N} permanently failed. Cascaded to {count} dependent tasks." 5. Independent tasks (no dependency on failed task) continue normally

7. Finalize

Task(subagent_type="brewcode:bc-coordinator",
     prompt="Mode: finalize. Task path: {TASK_PATH}. Status: {finished|failed}")

Status is "finished" when all tasks completed, "failed" when deadlock/cascade occurred.

8. Extract Rules (REQUIRED)

Skill(skill="brewcode:rules", args="{KNOWLEDGE_PATH}")

9. Prune Knowledge (REQUIRED)

Task(subagent_type="brewcode:bc-knowledge-manager",
     prompt="mode: prune-rules\ntaskPath: {TASK_PATH}")

Handoff (After Compact)

1. TaskList() -- current task state (source of truth) 2. Read PLAN.md -- protocol and Phase Registry 3. DO NOT read phases/ -- they are for agents 4. Continue with current in_progress or next pending task 5. WRITE report -> CALL coordinator after EVERY agent (ALWAYS)

</instructions>

Start

Execute a task with infinite context -- the skill runs multi-agent phases from a PLAN.md, automatically handing off to a new session when context fills up, and resuming exactly where it left off. No manual intervention, no lost progress.

Quick Start

/brewcode:start

Runs the task referenced in .claude/TASK.md (first line = active task path).

Modes

Examples

Good Usage

# 1. Full workflow: spec -> plan -> start
/brewcode:spec "Migrate REST endpoints from v1 to v2"
/brewcode:plan
/brewcode:start

# 2. Explicit path to a specific task
/brewcode:start .claude/tasks/20260401-093000_refactor_auth/PLAN.md

# 3. Multiple tasks over time -- each with its own PLAN.md
/brewcode:spec "Add rate limiting middleware"
/brewcode:plan
/brewcode:start .claude/tasks/20260401-150000_rate_limiting/PLAN.md

# 4. Resume a task that was interrupted (TASK.md still points to it)
/brewcode:start

# 5. Long-running task with many phases -- just start and walk away
/brewcode:start .claude/tasks/20260331-080000_full_rewrite/PLAN.md

Common Mistakes

# BAD: No PLAN.md exists yet -- start has nothing to execute
/brewcode:start
# -> Error: "No task path! Run: /brewcode:spec then /brewcode:plan"

# BAD: Pointing to the task directory instead of PLAN.md
/brewcode:start .claude/tasks/20260401-120000_migrate_api/
# -> The argument should be the full path to PLAN.md

# BAD: Skipping /brewcode:spec and /brewcode:plan
#      A PLAN.md with a Phase Registry is required before start

How It Works

1. Initialize -- The coordinator validates the task, creates an execution lock, and sets status to in progress. 2. Parse phases -- The Phase Registry table in PLAN.md is read. Each row becomes a Task with subject, agent assignment, and dependency links. 3. Execution loop -- Pending tasks with no blockers are spawned in parallel. Each agent runs its phase, writes a report to artifacts/, then the coordinator extracts knowledge. 4. Failure handling -- If an agent fails, it retries once. After repeated failures: root-cause exploration, phase splitting, model upgrade, or user escalation. Failed tasks cascade to their dependents, but independent tasks continue. 5. Context compaction (handoff) -- When the context window fills, the PreCompact hook triggers automatic compaction. On resume, the skill calls TaskList() to get current state, re-reads PLAN.md, and continues from wherever it left off. No progress is lost. 6. Finalize -- The coordinator marks the task finished (or failed if deadlock/cascade occurred). 7. Rules extraction -- KNOWLEDGE.jsonl entries are promoted to .claude/rules/*.md files, then pruned from the knowledge file.

The handoff mechanism is what makes execution "infinite": the skill can survive any number of context compactions and keep going until every phase completes or permanently fails.

Output

All artifacts live under the task directory: .claude/tasks/{TS}_{NAME}_task/.

Tips

• Prepare before starting. Always run /brewcode:spec and /brewcode:plan first. The skill needs a PLAN.md with a Phase Registry table to execute.
• Let it run. The handoff mechanism handles context limits automatically. There is no need to monitor or intervene unless the skill asks a question via AskUserQuestion.
• Check KNOWLEDGE.jsonl after completion. It contains lessons learned during execution -- anti-patterns to avoid, patterns that worked, and architectural facts about your codebase.
• Use explicit paths when juggling multiple tasks. If you switch between tasks frequently, pass the PLAN.md path directly instead of relying on .claude/TASK.md.

Documentation

Full docs: start