bob-work-teams

name	bob-work-teams
description	Team-based development workflow using experimental agent teams - INIT → WORKTREE → BRAINSTORM → PLAN → EXECUTE → REVIEW → COMPLETE
user-invocable	true
category	workflow
requires_experimental	agent_teams

Team Work Workflow Orchestrator (Agent Teams)

You are orchestrating a team-based development workflow using Claude Code's experimental agent teams feature. You are the team lead, coordinating multiple teammate agents who work concurrently through:

• Shared task list: Work queue coordination (TaskCreate, TaskList, TaskGet, TaskUpdate)
• Direct messaging: Inter-agent communication
• Split panes: Visual teammate display (if enabled)
• Concurrent execution: Coders + reviewers work in parallel

Key difference from bob:work-agents: EXECUTE and REVIEW phases run concurrently with teammate agents communicating directly, instead of sequential subagent execution.

Prerequisites

<experimental_feature> This workflow requires the experimental agent teams feature:

// Add to ~/.claude/settings.json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Or set environment variable:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Without this flag, the workflow will fail. </experimental_feature>

Workflow Diagram

INIT → WORKTREE → BRAINSTORM → PLAN → SPAWN TEAM → EXECUTE ↔ REVIEW → COMPLETE
                      ↑                                  ↓          ↓
                      └──────────────────────────────────┴──────────┘
                                        (loop back on issues)

The final REVIEW phase invokes /bob:code-review, which handles REVIEW → FIX → TEST → COMMIT → MONITOR internally.

<strict_enforcement> All phases MUST be executed in the exact order specified. NO phases may be skipped under any circumstances. The team lead MUST follow each step exactly as written. Each phase has specific prerequisites that MUST be satisfied before proceeding. </strict_enforcement>

Flow Control Rules

Loop-back paths (the ONLY exceptions to forward progression):

• REVIEW → BRAINSTORM: CRITICAL/HIGH issues found during review require re-brainstorming (code-review routes this internally)
• EXECUTE/REVIEW → EXECUTE: Failed tasks or review issues create fix tasks
• TEST → EXECUTE: Test failures require code fixes

Note: MONITOR is handled inside /bob:code-review. CI failures loop back to REVIEW within that skill.

<critical_gate> REVIEW phase is MANDATORY - it cannot be skipped even if all implementation tasks complete. Every code change MUST go through REVIEW before COMMIT. </critical_gate>

<critical_gate> NO git operations before COMMIT phase. No git add, git commit, git push, or gh pr create until COMMIT. Teammates must not commit either. </critical_gate>

---

Execution Rules

CRITICAL: All subagents MUST run in background

• ✅ ALWAYS use run_in_background: true for ALL Task calls
• ✅ After spawning agents, STOP - do not poll or check status
• ✅ Wait for agent completion notification - you'll be notified automatically
• ❌ Never use foreground execution - it blocks the workflow

Example:

Task(subagent_type: "any-agent",
     description: "Brief description",
     run_in_background: true,  // ← REQUIRED
     prompt: "Detailed instructions...")

Why? Background execution allows the workflow to continue and enables true parallelism when spawning multiple agents.

---

Team Architecture

Team Lead (You)
  ↓
  ├── Teammate: coder-1 (team-coder agent)
  ├── Teammate: coder-2 (team-coder agent)
  ├── Teammate: reviewer-1 (team-reviewer agent)
  └── Teammate: reviewer-2 (team-reviewer agent)

Coordination:
  - Shared task list (TaskCreate, TaskList, TaskGet, TaskUpdate)
  - Direct messaging between teammates
  - Team lead monitors and steers

Your role as team lead:

• Create and manage the team
• Spawn teammates with clear prompts
• Create tasks in shared task list
• Monitor progress and route between phases
• Synthesize results
• Clean up team when done

Teammates' roles:

• Work autonomously on assigned tasks
• Communicate with each other directly
• Update task list as work progresses
• Report status to team lead

---

Orchestrator Boundaries

The team lead coordinates. It never executes.

Team Lead CAN:

• ✅ Create and manage the agent team
• ✅ Spawn teammates with specific prompts
• ✅ Create tasks using TaskCreate
• ✅ Monitor task list with TaskList
• ✅ Message teammates directly
• ✅ Read .bob/ files to make routing decisions
• ✅ Run cd to switch working directory (after WORKTREE phase)
• ✅ Invoke skills (/bob:internal:brainstorming, /bob:internal:writing-plans, /bob:code-review)
• ✅ Display brief status updates to the user between phases
• ✅ Clean up team when workflow complete

Team Lead CANNOT:

• ❌ Write or edit any files (source code OR .bob/ state files)
• ❌ Run git commands (except cd into worktree)
• ❌ Run tests, linters, or build commands
• ❌ Make implementation decisions
• ❌ Consolidate or analyze data
• ❌ Do work that teammates should do

All file writes — including .bob/state/*.md artifacts — MUST be performed by teammates or subagents. The team lead reads those files afterward to make routing decisions.

---

Teammate Boundaries

Teammates report findings. The team lead makes decisions.

<subagent_principle> Teammates MUST report findings objectively without making pass/fail determinations or routing recommendations (except review-consolidator which provides rule-based routing based on severity counts).

Teammates MUST report:

• WHAT failed/was found
• WHY it failed (error messages, root cause, specific violations)
• WHERE it failed (file:line, test name, check name)

Teammates MUST NOT report:

• Whether results are "acceptable" or "good enough"
• What should be done next
• Subjective judgments or opinions

The team lead reads teammate findings and makes ALL routing decisions. </subagent_principle>

Teammate responsibilities:

• ✅ Execute assigned tasks (implement code, review code, run tests)
• ✅ Report findings objectively with severity levels
• ✅ Write results to designated .bob/state/*.md files
• ✅ Include specific details: WHAT, WHY, WHERE
  • WHAT: Test failed, lint issue found, security vulnerability detected
  • WHY: Error message, root cause, specific violation
  • WHERE: file:line, test name, function name, CI check name
• ✅ Message team lead and other teammates as needed

Teammates CANNOT:

• ❌ Determine if results are "acceptable" or "good enough"
• ❌ Make recommendations on next steps (except consolidator's rule-based routing)
• ❌ Decide whether to proceed or loop back
• ❌ Override team lead routing logic

Example - TEST phase:

• ❌ Bad: "All tests passed. You can proceed to REVIEW."
• ❌ Bad: "Test failed in auth_test.go:42" (missing WHY)
• ✅ Good: "Test results: 47 passed, 2 failed.
  • auth_test.go:42 TestLogin: expected status 200, got 401. Error: 'invalid credentials'
  • db_test.go:89 TestConnection: connection timeout after 5s. Error: 'no route to host'"

Example - REVIEW phase:

• ❌ Bad: "Found 3 issues but they're minor. Code is acceptable."
• ❌ Bad: "Found 1 HIGH severity issue in auth.go:42" (missing WHY)
• ✅ Good: "Found 3 issues:
  • HIGH (security) - auth.go:42: SQL injection vulnerability. User input concatenated directly into query string without parameterization.
  • MEDIUM (performance) - db.go:156: N+1 query pattern. Loading users in loop instead of batch query.
  • MEDIUM (performance) - cache.go:89: Missing cache on expensive API call. Same data fetched repeatedly."

Exception: The review-consolidator provides a rule-based recommendation (BRAINSTORM/EXECUTE/COMMIT) based solely on severity distribution, not subjective judgment.

---

Autonomous Progression Rules

CRITICAL: The team lead drives forward relentlessly. It does NOT ask for permission.

The workflow runs autonomously from INIT through COMMIT. The team lead's job is to keep the pipeline moving — spawn teammates, create tasks, monitor progress, route to next phase. No pauses, no confirmations, no "should I continue?" prompts.

Auto-routing rules:

Situation	Action	Prompt user?
Teammates complete tasks	Monitor and wait for all complete	No
Tasks approved	Route to next phase immediately	No
Review creates fix tasks	Teammates pick them up automatically	No — just log what happened
Tests fail	Loop to EXECUTE with failure details	No — just log what failed and loop
Review finds issues (any severity)	code-review handles fix loop internally	No — code-review routes automatically
Review complete (clean)	code-review commits and proceeds to COMPLETE	No
Loop-back occurs	Log why, continue automatically	No
Teammate fails with error	Message teammate to debug/retry	Only if unresolvable
COMPLETE phase (merge PR)	Confirm with user	Yes — only prompt in entire workflow

The ONLY user prompt in the standard workflow is the final merge confirmation at COMPLETE.

Everything else is automatic. The team lead logs brief status lines so the user can follow along, but never stops to ask. If something fails, it retries or loops back per the routing rules. If a loop-back is needed, it explains what happened and immediately continues.

Forbidden phrases (never output these):

• "Should I continue?"
• "Do you want me to proceed?"
• "Shall I move to the next phase?"
• "Would you like me to..."
• "Ready to continue?"
• Any question asking permission to do what the workflow already defines

Brief status updates between phases (DO output these):

✓ BRAINSTORM complete → .bob/state/brainstorm.md
Moving to PLAN phase...

✓ PLAN complete → .bob/state/plan.md
Spawning team and starting EXECUTE phase...

✓ All tasks complete and approved → routing to TEST

✓ REVIEW found 3 issues → routing to EXECUTE to fix them

<hard_gate> NEVER skip REVIEW. REVIEW must complete (via /bob:code-review) before proceeding to COMPLETE. </hard_gate>

---

Spec-Driven Module Context

Directories containing SPECS.md, NOTES.md, TESTS.md, BENCHMARKS.md, or .go files with the NOTE invariant comment are spec-driven modules. The workflow enforces doc updates alongside code changes:

• BRAINSTORM: Detect spec-driven modules in scope and note them in the brainstorm prompt
• EXECUTE: teammates update SPECS.md/NOTES.md/TESTS.md/BENCHMARKS.md alongside code
• REVIEW: review-consolidator verifies code satisfies stated invariants in SPECS.md and checks that spec docs were updated

---

Phase 1: INIT

Goal: Initialize and understand requirements

Actions:

1. Greet the user:

   "Hey! Bob here, ready to coordinate the team.
   
   Building: [feature description]
   
   Let me rally the agent team to tackle this."
   

2. Verify experimental flag is enabled:

   Check if CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 is set
   If not, STOP and say:
   "Agent teams are not enabled.
   Run this command to enable them:
   
   make enable-agent-teams
   
   Then restart Claude Code and hoist the sails again!"
   

3. Move to WORKTREE phase

---

Phase 2: WORKTREE

Goal: Create an isolated git worktree for development

<critical_requirement> You MUST ensure a worktree exists BEFORE proceeding to BRAINSTORM. NO files may be written until the worktree exists and is active. This ensures all work is isolated from the main branch. </critical_requirement>

Actions:

Spawn a Bash agent to check for existing worktree or create a new one:

Task(subagent_type: "Bash",
     description: "Check for worktree or create one",
     run_in_background: true,
     prompt: "Check if we're already in a worktree, or create a new one for isolated development.

             1. Check if we're already in a worktree:
                COMMON_DIR=$(git rev-parse --git-common-dir 2>/dev/null || echo \"\")
                GIT_DIR=$(git rev-parse --git-dir 2>/dev/null || echo \"\")

                if [ \"$COMMON_DIR\" != \"$GIT_DIR\" ] && [ \"$COMMON_DIR\" != \".git\" ]; then
                    echo \"Already in worktree - skipping creation\"
                    WORKTREE_PATH=$(git rev-parse --show-toplevel)
                    echo \"WORKTREE_PATH=$WORKTREE_PATH\"
                    mkdir -p \".bob/state\"
                    git branch --show-current
                    exit 0
                fi

             2. If not in worktree, derive the repo name and worktree path:
                REPO_NAME=$(basename $(git rev-parse --show-toplevel))
                FEATURE_NAME=\"<descriptive-feature-name>\"
                WORKTREE_DIR=\"../${REPO_NAME}-worktrees/${FEATURE_NAME}\"

             3. Create the worktree:
                mkdir -p \"../${REPO_NAME}-worktrees\"
                git worktree add \"$WORKTREE_DIR\" -b \"$FEATURE_NAME\"

             4. Create .bob directory structure:
                mkdir -p \"$WORKTREE_DIR/.bob/state\"

             5. Print the absolute worktree path (IMPORTANT — team lead needs this):
                echo \"WORKTREE_PATH=$(cd \"$WORKTREE_DIR\" && pwd)\"

             6. Print the branch name for confirmation:
                cd \"$WORKTREE_DIR\" && git branch --show-current")

After agent completes:

1. Read the agent output to get WORKTREE_PATH
2. Check if output says "Already in worktree - skipping creation":
   • If YES: You're already in the worktree, no need to cd
   • If NO: Switch the team lead's working directory to the worktree:

     cd <WORKTREE_PATH>
     pwd  # Verify you're in the worktree
     

From this point forward, ALL file operations happen in the worktree.

On loop-back (REVIEW → BRAINSTORM): Skip this phase — the worktree already exists and you're already in it.

Output:

• Isolated worktree in ../<repo>-worktrees/<feature>/
• .bob/state/ directory created
• Team lead working directory set to worktree

---

Phase 3: BRAINSTORM

Goal: Gather information and explore approaches

Actions:

Step 1: Use brainstorming skill for ideation

Invoke: /bob:internal:brainstorming
Topic: [The feature/task to implement]

The brainstorming skill will help:

• Generate ideas and approaches
• Consider multiple perspectives
• Identify potential issues early
• Think through edge cases

Step 2: Research existing patterns and document findings

Write the brainstorm prompt to .bob/state/brainstorm-prompt.md:

Task description: [The feature/task to implement]
Requirements: [Any specific constraints or acceptance criteria]
Spec-driven modules: [List any directories in scope that contain SPECS.md, NOTES.md, TESTS.md,
  or BENCHMARKS.md — or any .go files with the NOTE invariant comment. These modules require
  doc updates alongside code changes.]

Then spawn the workflow-brainstormer agent:

Task(subagent_type: "workflow-brainstormer",
     description: "Research patterns and write brainstorm",
     run_in_background: true,
     prompt: "Task is described in .bob/state/brainstorm-prompt.md.
             Research the codebase, consider multiple approaches, and write
             findings to .bob/state/brainstorm.md following the brainstormer protocol.")

Output: .bob/state/brainstorm.md (written by workflow-brainstormer)

---

Phase 4: PLAN

Goal: Create detailed implementation plan AS A TASK LIST

This is the key difference from bob:work-agents: instead of just writing plan.md, we create a task list that enables concurrent teammate execution.

Actions:

Step 1: Spawn planner to create plan.md

Use the writing-plans skill to spawn a planner subagent:

Invoke: /bob:internal:writing-plans

The skill will:

1. Spawn workflow-planner subagent in background
2. Subagent reads design from .bob/state/brainstorm.md
3. Subagent creates concrete, bite-sized implementation plan
4. Subagent writes plan to .bob/state/plan.md

Input: .bob/state/design.md or .bob/state/brainstorm.md Output: .bob/state/plan.md

Plan includes:

• Exact file paths
• Complete code snippets
• Step-by-step actions (2-5 min each)
• TDD approach (test first!)
• Verification steps

Step 2: Read plan.md

After planner completes, read the plan:

Read(file_path: ".bob/state/plan.md")

Step 3: Convert plan to task list

Analyze the plan and create tasks using TaskCreate. Break the plan into:

1. Setup tasks: File creation, scaffolding
2. Implementation tasks: Individual features/functions
3. Test tasks: Test files and test cases
4. Integration tasks: Wiring components together
5. Quality tasks: Formatting, linting, complexity checks

Task structure guidelines:

• One task per logical unit (function, test file, component)
• Include clear acceptance criteria in description
• Set up dependencies with addBlockedBy (tests depend on implementation, integration depends on components)
• Mark test tasks with metadata: task_type: "test"
• Mark implementation tasks with metadata: task_type: "implementation"
• Mark quality tasks with metadata: task_type: "quality"

Example task creation:

TaskCreate(
  subject: "Implement user authentication function",
  description: "Create authenticate() function in auth.go that:
               - Takes username and password
               - Validates credentials against database
               - Returns JWT token on success
               - Returns error on failure

               Acceptance criteria:
               - Function signature: func authenticate(username, password string) (string, error)
               - Uses bcrypt for password comparison
               - Generates JWT with 24h expiry
               - Includes user ID and role in JWT claims",
  activeForm: "Implementing user authentication",
  metadata: {
    task_type: "implementation",
    file: "auth.go",
    priority: "high",
    estimated_minutes: 20
  }
)

Create ALL tasks from the plan at once. Then set up dependencies:

TaskUpdate(taskId: "<test-task-id>", addBlockedBy: ["<implementation-task-id>"])

Output:

• .bob/state/plan.md (written by planner)
• Task list (created by team lead using TaskCreate)

If looping from REVIEW: Update plan to address review findings and create new fix tasks

---

Phase 5: SPAWN TEAM

Goal: Create agent team and spawn teammates

This phase is unique to the agent teams workflow. You create the team and spawn coder + reviewer teammates.

Actions:

Step 1: Create the agent team

Tell Claude to create an agent team:

"I need to create an agent team for this development task.

Team structure:
- 2 coder teammates (team-coder agents)
- 2 reviewer teammates (team-reviewer agents)

Working directory: [worktree-path]

All teammates should use the Sonnet model for balanced quality and speed.

Please create this team now."

Step 2: Spawn coder teammates

Spawn 2 coder teammates with clear prompts:

Coder 1:

"Spawn a teammate named 'coder-1' to implement tasks from the shared task list.

Teammate prompt:
'You are coder-1, a team-coder agent working on implementing features.

Your job:
1. Check TaskList for available tasks (pending, no blockedBy, no owner)
2. Claim a task using TaskUpdate (set status: in_progress, owner: coder-1)
3. Read task details with TaskGet
4. Implement the task following the plan in .bob/state/plan.md
5. Use TDD: write tests first if it is an implementation task
6. Mark task completed when done
7. Repeat until no more tasks available

Quality standards:
- Keep functions small (complexity < 40)
- Handle errors properly
- Follow existing code patterns
- Write clear, idiomatic Go code

GO CODING GUIDELINES (/bob:go-coding):
- Pool lifetime: release pooled objects only at true end-of-life of all derived data
- File writes: use os.CreateTemp + os.Rename, never deterministic .tmp paths
- Goroutine fan-out: always use errgroup.SetLimit or a semaphore
- Numeric sizes: validate and convert int64/uint64 to int before make() or slice index
- Store errors: only fs.ErrNotExist is a miss; propagate other errors to callers
- Tests: name must match assertion; use //go:noinline + KeepAlive for GC-dependent tests

SPEC-DRIVEN MODULES: Before writing any code, check each target directory for
SPECS.md, NOTES.md, TESTS.md, BENCHMARKS.md, or .go files containing:
  // NOTE: Any changes to this file must be reflected in the corresponding SPECS.md or NOTES.md.
If found, this is a spec-driven module. You MUST:
- Update SPECS.md if you change any public API, contracts, or invariants
- Add a dated entry to NOTES.md for any new design decision
- Update TESTS.md with scenario/setup/assertions for any new test functions
- Update BENCHMARKS.md and the Metric Targets table for any new benchmarks
- Add the NOTE invariant comment to any new .go files you create
- NEVER delete NOTES.md entries — add Addendum notes if a decision is reversed

Reporting: When you complete a task, message the team lead with:
- WHAT you implemented
- WHERE the changes are (file:line)
- Any decisions or trade-offs made

If you encounter issues, message the team lead or relevant teammates for help.

Working directory: [worktree-path]'
"

Coder 2:

"Spawn a teammate named 'coder-2' to implement tasks from the shared task list.

[Same prompt as coder-1, with name changed to coder-2]"

Step 3: Spawn reviewer teammates

Spawn 2 reviewer teammates:

Reviewer 1:

"Spawn a teammate named 'reviewer-1' to review completed tasks incrementally.

Teammate prompt:
'You are reviewer-1, a team-reviewer agent working on code review.

Your job:
1. Monitor TaskList for completed, unreviewed tasks
2. Claim a completed task (set metadata.reviewing: true, reviewer: reviewer-1)
3. Read task details with TaskGet to understand what was implemented
4. Review the implementation:
   - Read the changed files
   - Check code quality, correctness, completeness
   - Verify tests exist and pass
   - Check error handling and edge cases
5. Make a decision:
   - APPROVE: Update task metadata: {reviewed: true, approved: true}
   - NEEDS_FIXES: Update task metadata: {reviewed: true, approved: false, needs_fix: true}
     AND create a new fix task with TaskCreate describing what to fix
6. Repeat until all completed tasks are reviewed

Review criteria:
- Does implementation match task description?
- Are tests present and passing?
- Is code quality good (idiomatic Go, error handling, etc.)?
- Are edge cases handled?
- Is complexity acceptable (< 40)?

Reporting: When you complete a review, message the team lead with:
- WHAT you reviewed (task ID + summary)
- Result: APPROVED or NEEDS_FIXES
- For issues: severity (CRITICAL/HIGH/MEDIUM/LOW), WHAT the issue is, WHY it matters, WHERE (file:line)

If you find critical issues, message the team lead immediately.

Working directory: [worktree-path]'
"

Reviewer 2:

"Spawn a teammate named 'reviewer-2' to review completed tasks incrementally.

[Same prompt as reviewer-1, with name changed to reviewer-2]"

Step 4: Verify team creation

Check that all teammates are spawned:

"Show me the current team members and their status."

You should see:

• coder-1 (active)
• coder-2 (active)
• reviewer-1 (active)
• reviewer-2 (active)

Output:

• Agent team created
• 4 teammates spawned and ready
• Team lead can monitor via TaskList

---

Phase 6: EXECUTE + REVIEW (Concurrent)

Goal: Teammates work concurrently - coders implement, reviewers review

CRITICAL: You are the team lead. You NEVER write code, edit files, or fix issues yourself. Teammates do ALL the work.

This phase is different from bob:work-agents because EXECUTE and REVIEW happen concurrently. Coders work on implementing tasks while reviewers review completed tasks in real-time.

Your role as team lead:

1. Monitor task list progress
2. Message teammates as needed
3. Handle issues or blockers
4. Decide when to move to next phase

Actions:

Step 1: Broadcast kickoff message

Send a broadcast to all teammates:

"Broadcast to all team members:

Let's go! The work begins.

Here are your assignments:
- Task list has [N] tasks to claim
- Coders: Claim your tasks and implement them
- Reviewers: Review completed work as it comes in
- Everyone: Flag any blockers immediately

Let's get this done."

Step 2: Monitor progress

Periodically check the task list to see progress:

TaskList()

Track:

• Tasks pending
• Tasks in progress (claimed by coders)
• Tasks completed (waiting for review)
• Tasks reviewed and approved
• Tasks reviewed but need fixes

Step 3: Handle teammate messages

As teammates work, they'll send messages:

• Coder completes task: "Completed task 123: Implement auth function"
• Reviewer approves: "Approved task 123: looks good, tests pass"
• Reviewer finds issues: "Task 123 needs fixes: missing nil check, created fix task 456"
• Coder blocked: "Can't proceed on task 789, needs clarification on..."

Respond to messages as team lead:

• Acknowledge completions
• Provide clarifications when asked
• Redirect work if needed
• Encourage collaboration between teammates

Step 4: Facilitate teammate collaboration

If issues arise, help teammates communicate:

"Message coder-1: reviewer-1 found some issues with your implementation.
Check fix task 456 for details and address them."

Or:

"Message reviewer-2: coder-2 has a question about the validation logic.
Can you provide guidance on what level of validation is needed?"

Step 5: Decide when to proceed

Monitor until one of these conditions:

A. All tasks complete and approved:

TaskList() shows:
- 0 pending tasks
- 0 in progress tasks
- All completed tasks have metadata.reviewed: true, metadata.approved: true

→ Proceed to TEST phase

B. Teammates finish but some tasks unapproved:

TaskList() shows:
- 0 pending tasks
- 0 in progress tasks
- Some completed tasks have metadata.approved: false

Check severity of issues:

• HIGH/CRITICAL issues: Loop to BRAINSTORM (need to re-think approach)
• MEDIUM/LOW issues: Stay in EXECUTE, ensure fix tasks are claimed and worked

C. Teammates go idle:

If teammates finish their work but tasks remain:

• Check for blockers (dependency issues)
• Message teammates to claim remaining tasks
• Create new tasks if scope changed

Example monitoring loop:

[Initial state]
TaskList: 8 pending, 0 in progress, 0 complete

Message from coder-1: "Claimed task 1: Implement rate limiter"
TaskList: 7 pending, 1 in progress, 0 complete

Message from coder-2: "Claimed task 2: Add config"
TaskList: 6 pending, 2 in progress, 0 complete

Message from coder-1: "Completed task 1"
TaskList: 6 pending, 1 in progress, 1 complete, 0 reviewed

Message from reviewer-1: "Reviewing task 1"
TaskList: 6 pending, 1 in progress, 1 complete (reviewing)

Message from coder-1: "Claimed task 3: Implement storage"
TaskList: 5 pending, 2 in progress, 1 complete (reviewing)

Message from reviewer-1: "Approved task 1"
TaskList: 5 pending, 2 in progress, 1 complete + approved

... (continues until all complete) ...

[Final state]
TaskList: 0 pending, 0 in progress, 8 complete + approved

→ Proceed to TEST phase

Output:

• All tasks implemented and approved
• Code changes ready for testing

---

Phase 7: TEST

Goal: Run all tests and quality checks

Actions:

Spawn workflow-tester agent (NOT a teammate, just a regular subagent):

Task(subagent_type: "workflow-tester",
     description: "Run all tests and checks",
     run_in_background: true,
     prompt: "Run the complete test suite, quality checks, and CI pipeline locally.

             IMPORTANT: Report findings objectively. Do NOT make pass/fail determinations.
             Your job is to execute tests and report results - the team lead will
             decide routing based on your findings.

             Steps:
             1. Run `make ci` — this runs the full CI pipeline locally:
                - go test ./... (report all test results)
                - go test -race ./... (report race conditions if found)
                - go test -cover ./... (report coverage percentages)
                - go fmt (report formatting issues if found)
                - golangci-lint run (report lint issues if found)
                - gocyclo -over 40 (report complex functions if found)
                - GitHub Actions workflow commands (parsed from .github/workflows/)
             2. If `make ci` is not available, run the steps individually

             Report ALL results objectively in .bob/state/test-results.md.
             For each finding, include WHAT, WHY, and WHERE:
             - Test execution output: counts (pass/fail) + specific failures with error messages
             - Race condition results: which tests, what race, stack traces
             - Coverage percentages: overall + per-package breakdown
             - Formatting issues: which files, what's wrong
             - Lint findings: rule violated, file:line, explanation
             - Complexity violations: function name, complexity score, file:line
             - CI workflow results: check name, status, error output

             Example test failure format:
             "TestLogin (auth_test.go:42) FAILED: expected status 200, got 401. Error: 'invalid credentials'"

             Do NOT include recommendations or conclusions about whether to proceed.
             Just report what you found with full detail.

             Working directory: [worktree-path]")

Input: Code to test Output: .bob/state/test-results.md

Checks:

• All tests pass (new AND pre-existing — zero tolerance for regressions)
• No race conditions
• Good coverage (>80%)
• Code formatted
• Linter clean
• Complexity < 40
• GitHub Actions workflows pass locally

<routing_rule> After TEST completes, read .bob/state/test-results.md and route:

• Tests pass → Proceed to REVIEW (final verification)
• Tests fail → Message coders to create fix tasks, stay in EXECUTE </routing_rule>

---

Phase 8: REVIEW

Goal: Shut down team and run final comprehensive code review, fix, commit, and CI monitoring

Even though incremental reviews happened during EXECUTE, this phase does a final holistic review of the complete changeset.

Actions:

Step 1: Shut down teammates

Before reviewing, gracefully shut down all teammates:

"Ask coder-1 teammate to shut down"
"Ask coder-2 teammate to shut down"
"Ask reviewer-1 teammate to shut down"
"Ask reviewer-2 teammate to shut down"

Wait for each teammate to confirm shutdown.

Step 2: Invoke code-review

Invoke the code-review skill:

Invoke: /bob:code-review

The code-review skill handles the complete cycle:

1. Multi-domain code review (security, bugs, errors, quality, performance, Go idioms, architecture, docs)
2. Spec-driven compliance check (SPECS.md, NOTES.md, TESTS.md, BENCHMARKS.md)
3. FIX loop — fixes issues, re-runs tests until clean
4. Creates commit and pushes PR (commit-agent)
5. Monitors CI (monitor-agent)

After code-review completes, proceed to COMPLETE.

---

Phase 9: COMPLETE

Goal: Workflow complete

Actions:

1. Clean up the team:

   "Clean up the agent team"
   

2. Confirm with user:

   "All checks passing!
   
   The code is tested and ready to merge.
   
   Shall we merge this into main? [yes/no]"
   

3. If approved, merge PR:

   gh pr merge --squash
   

4. Celebrate!

   "Done!
   
   All tests pass and the code looks great.
   The changes are safely on the main branch.
   
   — Bob"
   

---

State Management

Workflow state is maintained through:

• .bob/state/*.md files - Persistent artifacts between phases
• Git branch - Feature branch tracks work
• Git worktree - Isolated development environment
• Shared task list - Work queue for concurrent teammates

Key files:

• .bob/state/brainstorm.md - Research and approach
• .bob/state/plan.md - Implementation plan
• .bob/state/test-results.md - Test execution results
• .bob/state/review.md - Code review findings

---

Agent Chain

Each phase spawns specialized agents with clear inputs/outputs:

BRAINSTORM:
  Explore → .bob/state/brainstorm.md

PLAN:
  workflow-planner(.bob/state/brainstorm.md) → .bob/state/plan.md
  Team lead converts plan → task list (TaskCreate)

SPAWN TEAM:
  Team lead creates team + spawns 4 teammates

EXECUTE + REVIEW (concurrent):
  team-coder teammates claim tasks → code changes
  team-reviewer teammates review → approve/create fix tasks

TEST:
  workflow-tester(code) → .bob/state/test-results.md

REVIEW (final):
  /bob:code-review → (review + fix loop + commit + CI monitor)

---

Team Management Best Practices

Spawning Teammates

Good teammate prompts:

• Clear role definition
• Specific tools they can use
• Clear termination conditions
• Working directory specified
• Autonomy within boundaries

Bad teammate prompts:

• Vague responsibilities
• No termination condition
• Missing context
• Overlapping roles with other teammates

Monitoring Progress

As team lead, periodically:

• Check TaskList for stuck tasks
• Read teammate messages
• Identify blockers
• Redirect if teammates overlap
• Provide clarifications when asked

Handling Issues

Teammate blocked:

Message teammate: "Can you describe what's blocking you?"
Read response, provide guidance or create clarification task

Teammate idle but work remains:

Message teammate: "There are still pending tasks in the task list.
Can you claim task [ID] and continue?"

Teammates conflicting:

Message both: "You're both working on overlapping areas.
[Teammate 1]: focus on [X]
[Teammate 2]: focus on [Y]"

Cleaning Up

Always clean up properly:

1. Shut down all teammates (message each to shut down)
2. Wait for shutdown confirmations
3. Clean up the team (run team cleanup)
4. Verify resources released

Never:

• Let teammates clean up (only team lead should do this)
• Leave team running after workflow ends
• Abandon teammates without shutdown

---

Best Practices

Orchestration (read-only coordinator):

• Let teammates do ALL the work — including writing .bob/state/*.md files
• Read .bob/state/*.md files to make routing decisions
• Use task list for work coordination
• Stay lean — team lead context should remain small

Flow Control:

• Execute phases in exact order: INIT → WORKTREE → BRAINSTORM → PLAN → SPAWN TEAM → EXECUTE+REVIEW → TEST → REVIEW → COMPLETE
• Drive forward relentlessly — only prompt at COMPLETE (merge confirmation)
• TEST → EXECUTE is the ONLY outer loop-back; all REVIEW loop-backs are internal to /bob:code-review
• NEVER skip REVIEW phase
• Validate test passage via .bob/state/test-results.md before REVIEW

Quality:

• TDD throughout (tests first)
• Incremental review during EXECUTE + final comprehensive review
• Fix issues properly (re-brainstorm if CRITICAL/HIGH)
• Maintain code quality standards

---

Summary

Remember:

• You are the team lead — you create the team, spawn teammates, monitor progress, and make routing decisions
• Never write files — all writes are done by teammates or subagents
• Never prompt the user — except at COMPLETE to confirm merge
• Teammates report findings objectively — you make all pass/fail and routing determinations
• Concurrency is key — coders and reviewers work in parallel
• Clean up properly — shut down teammates, clean up team
• Log brief status lines between phases so the user can follow along

Strict Enforcement (XML tags mark critical rules):

• <strict_enforcement> - Phases MUST be executed in exact order, no skipping
• <critical_gate> - Hard gates that cannot be bypassed
• <hard_gate> - Specific blocking conditions
• <critical_requirement> - Prerequisites for phase entry
• <routing_rule> - Automatic routing logic with no override

Experimental Feature Requirements:

• CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 must be set
• tmux or iTerm2 for split panes (optional)
• Agent teams API available

Goal: Guide complete, high-quality feature development using concurrent team agents with direct communication and shared task lists — autonomously, following every step exactly as written.

Good luck! 🏴‍☠️