Orchestrator Multiagent

Multi-Agent Orchestrator Skill

🚀 SESSION START (Do This First)

Everything below is reference material.

Core Rule: Delegate, Don't Implement

Orchestrator = Coordinator. Worker = Implementer.

# ✅ CORRECT - Worker via native team teammate
# Step 1: Create team (once per session, in PREFLIGHT)
Teammate(
    operation="spawnTeam",
    team_name="{initiative}-workers",
    description="Workers for {initiative}"
)

# Step 2: Create work item
TaskCreate(
    subject="Implement feature F001",
    description="""
    ## Task: [Task title from Beads]

    **Context**: [investigation summary]
    **Requirements**: [list requirements]
    **Acceptance Criteria**: [list criteria]
    **Scope** (ONLY these files): [file list]

    **Report back with**: Files modified, tests written/passed, any blockers
    """,
    activeForm="Implementing F001"
)

# Step 3: Spawn specialist worker into team
Task(
    subagent_type="frontend-dev-expert",
    team_name="{initiative}-workers",
    name="worker-frontend",
    prompt="You are worker-frontend in team {initiative}-workers. Check TaskList for available work. Claim tasks, implement, report completion via SendMessage to team-lead."
)

# Step 4: Worker results arrive via SendMessage (auto-delivered to you)
# Worker sends: SendMessage(type="message", recipient="team-lead", content="Task #X complete: ...")

Why native teams? Workers are persistent teammates that can claim tasks, communicate with each other, and handle multiple assignments within a single session. The orchestrator creates tasks and workers pick them up -- no blocking, no single-assignment limitation.

Parallel workers: Spawn multiple teammates into the same team. Each claims different tasks from the shared TaskList. Workers coordinate peer-to-peer via SendMessage.

Implementation Complete Handoff

When orchestrator's workers finish implementation:

Orchestrators mark tasks impl_complete to signal System 3 for independent validation. Orchestrators do NOT close tasks — System 3's oversight team handles validation and closure.

Handoff Protocol:

1. Workers confirm: code committed, unit tests pass, implementation complete
2. Orchestrator marks bead: bd update <id> --status=impl_complete
3. Orchestrator continues to next task (does NOT wait for S3 validation)

Custom Beads Status Lifecycle:

open → in_progress → impl_complete → [S3 validates] → closed
                         ↑                    │
                         └────────────────────┘
                       (s3_rejected → back to in_progress)

What orchestrators SHOULD NOT do:

• Do NOT run bd close — System 3 handles this after independent validation
• Do NOT spawn a validator teammate — validation is System 3's responsibility
• Do NOT wait for validation before starting next task

Quick Reference

State Management (Beads - Recommended)

Primary: .beads/ directory managed by bd commands

# Essential Beads commands
bd ready                          # Get unblocked tasks (MOST IMPORTANT)
bd list                           # All tasks
bd show <bd-id>                   # Task details
bd reopen <bd-id>                 # Reopen if regression found
bd dep list <bd-id>               # Show dependencies

Quick Reference: REFERENCE.md

Worker Types (Spawned as Teammates)

These types are used as subagent_type when spawning teammates via Task(..., team_name=..., name=...):

Pattern: Use Task(subagent_type="...", team_name="...", name="...") to spawn teammates. Workers claim tasks from the shared TaskList and report via SendMessage.

Key Directories

• .beads/ - Task state (managed by bd commands)
• .claude/progress/ - Session summaries and logs
• .claude/learnings/ - Accumulated patterns

Service Ports

• Frontend: 5001 | Backend: 8000 | eddy_validate: 5184 | user_chat: 5185

Essential Commands

# Services (see VALIDATION.md for details)
./my-project-backend/start_services.sh
cd my-project-frontend && npm run dev

# Task status (Beads - RECOMMENDED)
bd ready                                    # Get unblocked tasks
bd list                                     # All tasks
bd show <bd-id>                             # Task details

# Update task status (Beads)
bd update <bd-id> --status in-progress      # Mark as started
bd update <bd-id> --status=impl_complete     # Signal S3 for validation

# Commit (Beads)
git add .beads/ && git commit -m "feat(<bd-id>): [description]"

Workflow Triage (MANDATORY FIRST STEP)

Before any orchestration, determine which workflow applies:

1. Check Beads status: bd list
   ↓
2. If NO TASKS exist → IDEATION + PLANNING MODE (Phase 0 + Phase 1)

   🚨 STOP HERE - Before planning:
   □ Read WORKFLOWS.md Feature Decomposition section (MANDATORY)
   □ Complete Phase 0: Ideation (brainstorming + research)
   □ Create TodoWrite checklist for Phase 1 steps
   ↓
3. If TASKS exist → Check task status: bd stats
   ↓
4. Determine execution workflow type:

   ALL tasks open → EXECUTION MODE (Phase 2)
   SOME tasks closed, some open → CONTINUATION MODE (Phase 2)
   All impl done, AT pending → VALIDATION MODE (Phase 3)
   ALL tasks closed → MAINTENANCE MODE (delegate single hotfix)

Session Start Memory Check (CRITICAL CIRCUIT BREAKER)

🚨 MANDATORY: Run PREFLIGHT.md checklist before ANY investigation.

The preflight includes:

• ✅ Serena activation (code navigation only)
• ✅ Hindsight memory recall (patterns, lessons learned)
• ✅ Service health verification
• ✅ Regression validation (1-2 closed tasks)
• ✅ Session goal determination

Why This Matters: Memory check prevents repeating mistakes. Missing memories costs hours of repeated investigation (Session F087-F092 evidence).

Workflow Decision Matrix

The Four-Phase Pattern

Phase 0: Ideation (Brainstorming + Research)

Every new project MUST begin with structured ideation.

Essential Steps:

1. Research via Perplexity/Brave/context7
2. Skill("superpowers:brainstorming") - Explore 2-3 alternative approaches
3. For complex architectures: /parallel-solutioning - Deploys 7 solution-architects
4. Convert design to implementation steps via Skill("superpowers:writing-plan")

Outputs: PRD (business goals, user stories, architectural decisions, epics list)

• PRD template: .taskmaster/templates/prd-template.md
• PRD location: .taskmaster/docs/PRD-{CATEGORY}-{DESCRIPTOR}.md
• PRD is the operator-facing artifact — it does NOT go into Task Master directly
• Store research notes and decisions in Hindsight

Epic Hierarchy Patterns (MANDATORY)

Every initiative requires this hierarchy. No exceptions.

UBER-EPIC: "Q1 Authentication System"
│
├── EPIC: User Login Flow ─────────────────┐
│   ├── TASK: Implement login API          │ [parent-child]
│   ├── TASK: Create login form            │ Concurrent work OK
│   └── TASK: Add validation               │
│                                          │
├── EPIC: AT-User Login Flow ──────────────┤ [blocks]
│   ├── TASK: Unit tests for login API     │ AT blocks functional epic
│   ├── TASK: E2E test login flow          │
│   └── TASK: API integration tests        │
│                                          │
├── EPIC: Session Management ──────────────┤
│   ├── TASK: Implement session store      │ [parent-child]
│   └── TASK: Add session timeout          │
│                                          │
└── EPIC: AT-Session Management ───────────┘ [blocks]
    └── TASK: Session validation tests

Quick Setup:

# 1. Create uber-epic (ALWAYS FIRST)
bd create --title="Q1 Authentication System" --type=epic --priority=1
# Returns: my-project-001

# 2. Create functional epic + paired AT epic
bd create --title="User Login Flow" --type=epic --priority=2           # my-project-002
bd create --title="AT-User Login Flow" --type=epic --priority=2        # my-project-003
bd dep add my-project-002 my-project-003 --type=blocks                   # AT blocks functional

# 3. Create tasks under each epic
bd create --title="Implement login API" --type=task --priority=2
bd dep add my-project-004 my-project-002 --type=parent-child             # Task under epic

Dependency Types:

Key Rules:

• Uber-Epic First: Create before any planning work
• AT Pairing: Every functional epic MUST have a paired AT epic
• Closure Order: AT tasks → AT epic → Functional epic → Uber-epic
• Concurrent Development: parent-child allows ALL epics to progress simultaneously

Validation: Each AT task must pass 3-level validation (Unit + API + E2E). See WORKFLOWS.md.

Quick Reference: REFERENCE.md

Phase 1: Planning (Uber-Epic + Task Decomposition)

Prerequisites:

1. ✅ Phase 0 complete (ideation, brainstorming done)
2. ✅ PRD exists in .taskmaster/docs/PRD-{CATEGORY}-{DESCRIPTOR}.md (from Phase 0)
3. ✅ Read WORKFLOWS.md for MAKER decomposition principles

Two-Document Model:

• PRD (Phase 0 output) — business artifact: goals, user stories, architectural decisions, epics list. NOT fed into Task Master.
• SD (Phase 1 creates, one per epic) — automation input: business context + technical design. This is what Task Master parses.

Planning Workflow:

# 1. Create uber-epic in my-org/ (from validated PRD)
cd $CLAUDE_PROJECT_DIR
bd create --title="[Initiative from PRD]" --type=epic --priority=1
# Note the returned ID (e.g., my-project-001)

# 2. Create Solution Design (SD) per epic from PRD
#    Delegate to solution-design-architect worker — do NOT write SD yourself
#    SD template: .taskmaster/templates/solution-design-template.md
#    SD location: .taskmaster/docs/SD-{CATEGORY}-{NUMBER}-{epic-slug}.md
#    The SD includes:
#      - Business Context section (summarizes relevant PRD goals for Task Master)
#      - Technical Architecture (data models, API contracts, component design)
#      - Functional Decomposition (capabilities → features with explicit dependencies)
#      - Acceptance Criteria per feature (Gherkin-ready)
#      - File Scope (new/modified/excluded files)

# 2.5a. Codebase Analysis with ZeroRepo (Recommended — run before writing SD)
# For detailed workflow, see ZEROREPO.md
#
# Run ZeroRepo to map PRD against existing codebase:
python .claude/skills/orchestrator-multiagent/scripts/zerorepo-run-pipeline.py \
  --operation init --project-path .  # Once per project
python .claude/skills/orchestrator-multiagent/scripts/zerorepo-run-pipeline.py \
  --operation generate --prd .taskmaster/docs/PRD-{ID}.md \
  --baseline .zerorepo/baseline.json --model claude-sonnet-4-6 \
  --output .zerorepo/output
# Read delta report: .zerorepo/output/05-delta-report.md
# Use EXISTING/MODIFIED/NEW classification to populate SD File Scope section:
#   EXISTING → Reference only (no task needed)
#   MODIFIED → Scoped task with file path + specific changes
#   NEW      → Full implementation task with module structure
# Include delta context in SD Functional Decomposition and File Scope sections

# 2.5b. Enrich Beads with RPG Graph Context (After sync in step 5)
# For each bead created by sync, update --design with context from 04-rpg.json:
# bd update <bead-id> --design "Delta: NEW | Files: ... | Interface: ... | Dependencies: ..."
# See ZEROREPO.md "Enriching Beads with RPG Graph Context" for full pattern

# 3. Note current highest task ID before parsing
task-master list | tail -5  # e.g., last task is ID 170

# 4. Parse SD with Task Master (--append if tasks exist)
#    NOTE: Parse the SD, NOT the PRD — SD has the structured decomposition TM needs
task-master parse-prd .taskmaster/docs/SD-{CATEGORY}-{NUMBER}-{epic-slug}.md --research --append
task-master analyze-complexity --research
task-master expand --all --research
# Note the new ID range (e.g., 171-210)

# 5. Sync ONLY new tasks to Beads (run from my-org/ root!)
cd $CLAUDE_PROJECT_DIR
node my-project/.claude/skills/orchestrator-multiagent/scripts/sync-taskmaster-to-beads.js \
    --uber-epic=my-project-001 \
    --from-id=171 --to-id=210 \
    --tasks-path=my-project/.taskmaster/tasks/tasks.json
# This also closes Task Master tasks 171-210 (status=done)

# 6. Generate acceptance tests from SD (IMMEDIATELY after sync)
#    Use SD as source — it contains Business Context + per-feature Acceptance Criteria
Skill("acceptance-test-writer", args="--prd=PRD-AUTH-001 --source=.taskmaster/docs/SD-AUTH-001-login.md")
# This generates:
# acceptance-tests/PRD-AUTH-001/
# ├── manifest.yaml          # PRD metadata + feature list
# ├── AC-user-login.yaml     # Acceptance criteria (from SD Section 6)
# ├── AC-invalid-credentials.yaml
# └── ...

# 7. Commit acceptance tests
git add acceptance-tests/ && git commit -m "test(PRD-AUTH-001): add acceptance test suite"

# 7.5. Generate DOT pipeline from beads (beads must exist from step 5)
# Set solution_design attribute on each codergen node to point to its SD file
cobuilder pipeline create \
    --prd PRD-AUTH-001 \
    --output .pipelines/pipelines/auth-001.dot
# Set SD reference on nodes (so Runner can brief orchestrators with full context):
cobuilder pipeline node-modify auth-001.dot impl_login \
    --set solution_design=.taskmaster/docs/SD-AUTH-001-login.md
# Validate
cobuilder pipeline validate \
    .pipelines/pipelines/auth-001.dot

# 8. Review hierarchy (filter by uber-epic)
bd list --parent=my-project-001   # See only tasks under this initiative
bd ready --parent=my-project-001  # Ready tasks for this initiative only

# 9. Commit planning artifacts (completes Phase 1)
git add .beads/ .taskmaster/docs/ .pipelines/pipelines/ && \
    git commit -m "plan: initialize [initiative] hierarchy with SD documents"
# Write progress summary to .claude/progress/

Manual Planning (Hotfixes only - already have clear scope):

bd create --title="[Hotfix Description]" --type=epic --priority=1
# Create tasks directly: bd create --title="[Task]" --type=task
# Skip Phase 0 only for emergency fixes with <3 file changes

Warning: Ignore plan skill's "execute with superpowers:executing-plans" -- we use native Agent Teams teammates.

Sync Script Reference (Task Master → Beads)

🚨 Run from project root (e.g., my-org/) to use the correct .beads database.

node my-project/.claude/skills/orchestrator-multiagent/scripts/sync-taskmaster-to-beads.js \
    --uber-epic=<id> --from-id=<start> --to-id=<end> --tasks-path=<path>

Key flags: --uber-epic (links to parent), --from-id/--to-id (filter range), --dry-run (preview)

After Sync:

• ✅ Creates beads with rich field mapping (description, design, acceptance)
• ✅ Links all beads to uber-epic via parent-child
• ✅ Closes synced Task Master tasks (status=done)
• ✅ Filter by initiative: bd ready --parent=my-project-001

Phase 2: Execution (Incremental Implementation)

🚨 For multi-feature autonomous operation, see WORKFLOWS.md

The autonomous mode protocol provides:

• ✅ Continuation criteria (when to proceed automatically)
• ✅ Stop conditions (when to pause and report)
• ✅ Comprehensive validation (Unit + API + E2E for backend and frontend)
• ✅ Session handoff procedures

Quick Reference (Single Feature):

1. Run PREFLIGHT.md checklist (includes team creation)
   ↓
2. `bd ready` -> Select next task
   ↓
3. `bd update <bd-id> --status in-progress`
   ↓
4. DELEGATE TO WORKER TEAMMATE
   TaskCreate(subject="Implement ...", description="...", activeForm="...")
   SendMessage(type="message", recipient="worker-backend", content="Task available", summary="New task")
   ↓
5. Worker sends results via SendMessage (auto-delivered to you)
   ↓
6. Mark impl_complete
   bd update <bd-id> --status=impl_complete
   ↓
7. `git add . && git commit -m "feat(<bd-id>): [description]"`

Critical Rules:

• One feature at a time. Leave clean state. Commit progress.
• Use TaskCreate + SendMessage for all worker delegation - Workers claim tasks from shared TaskList
• NEVER use bd close directly - Mark impl_complete and let S3 validate/close
• Orchestrator coordinates; Workers implement

Legacy feature_list.json: See LEGACY_FEATURE_LIST.md for legacy workflow.

Phase 3: Validation (System 3 Independent Oversight)

System 3 handles validation independently using its oversight team:

• s3-investigator verifies code changes
• s3-prd-auditor checks PRD coverage
• s3-validator runs real E2E tests
• s3-evidence-clerk produces closure reports

Orchestrator's role in Phase 3:

1. Ensure all tasks are marked impl_complete
2. Monitor for s3_rejected tasks (fix and re-submit)
3. When all tasks are closed by S3 → initiative complete

Closure Order (managed by System 3):

impl_complete → s3_validating → closed
                (or s3_rejected → in_progress → impl_complete)

Full Validation Protocol: See WORKFLOWS.md

State Integrity Principles

State = What can be independently verified (tests, browser, git status).

Immutability Rules:

MAKER-Inspired Decomposition: Tasks must be small enough for a Haiku model to complete reliably. See WORKFLOWS.md for the four questions and decision tree.

Memory-Driven Decision Making

Core principle: Before deciding, recall. After learning, retain. When stuck, reflect + validate.

Key integration points: task start (recall), user feedback (retain → reflect → retain), double-rejection (recall → reflect → Perplexity → retain), session closure (reflect → retain).

Full workflow: See references/hindsight-integration.md

Worker Delegation (Native Teams)

Orchestrators use native Agent Teams for all worker delegation.

Essential pattern: Create team → Spawn workers → Create tasks → Workers claim and report

# Spawn worker teammate (once per session in PREFLIGHT)
Task(
    subagent_type="backend-solutions-engineer",
    team_name="{initiative}-workers",
    name="worker-backend",
    prompt="Check TaskList, claim tasks, implement, report via SendMessage"
)

# Assign work
TaskCreate(subject="Implement X", description="...", activeForm="Implementing X")
SendMessage(type="message", recipient="worker-backend", content="Task available", summary="New task")

Quick Worker Selection

Full examples: See WORKERS.md for detailed patterns

Browser Testing Worker Pattern

When to use: Features requiring actual browser automation (not just unit tests)

Pattern: Orchestrator creates task, persistent tdd-test-engineer teammate picks it up. Because the tester is a persistent teammate, it can maintain browser sessions across multiple test tasks.

# Create browser testing task
TaskCreate(
    subject="E2E browser testing for F084",
    description="""
    MISSION: Validate feature F084 via browser automation

    TARGET: http://localhost:5001/[path]

    TESTING CHECKLIST:
    - [ ] Navigate to page
    - [ ] Verify UI renders correctly
    - [ ] Test user interactions
    - [ ] Capture screenshots as evidence

    Report: Pass/Fail per item, screenshots, overall assessment
    """,
    activeForm="Browser testing F084"
)
SendMessage(type="message", recipient="worker-tester", content="Browser test task available for F084", summary="Browser test request")
# Worker-tester picks up task, maintains browser session, reports results via SendMessage

Fallback: Task Subagent Mode

When AGENT_TEAMS is not enabled, fall back to the original Task subagent pattern:

result = Task(
    subagent_type="frontend-dev-expert",
    description="Implement [feature]",
    prompt="""
    ## Task: [Task title from Beads]

    **Context**: [investigation summary]
    **Requirements**: [list requirements]
    **Acceptance Criteria**: [list criteria]
    **Scope** (ONLY these files): [file list]

    **Report back with**: Files modified, tests written/passed, any blockers
    """
)
# Result returned directly - no monitoring, no cleanup needed

In fallback mode, after implementation the orchestrator marks tasks impl_complete:

bd update <bd-id> --status=impl_complete

How to detect: Check for CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in environment. If absent, use fallback.

Full Guide: WORKERS.md

• Worker Assignment Template
• Parallel Worker Pattern
• Browser Testing Workers (E2E validation)

Service Management

BEFORE starting Phase 2:

# Start services (see VALIDATION.md for details)
cd my-project-backend && ./start_services.sh
cd my-project-frontend && npm run dev

# Verify services running
lsof -i :5001 -i :8000 -i :5184 -i :5185 | grep LISTEN

Full Guide: VALIDATION.md

• Service Setup and Health Checks
• Starting from Clean State
• Worker Dependency Verification
• Troubleshooting Service Issues

Testing & Validation

Testing (Level 1 — Orchestrator Responsibility)

Orchestrators ensure basic quality before marking impl_complete:

• Unit tests pass (pytest/jest)
• Code compiles/builds without errors
• Basic smoke tests pass

Level 2+3 validation (E2E, PRD compliance) is performed independently by System 3's oversight team. The orchestrator does NOT need to set up E2E infrastructure or run acceptance tests.

Validation Types

Full Guide: VALIDATION.md

• 3-Level Validation Protocol
• Testing Infrastructure
• Hollow Test Problem explanation

Mandatory Regression Check (CIRCUIT BREAKER)

🚨 This is covered in PREFLIGHT.md Phase 3.

Quick Summary: Before ANY new feature work:

1. Pick 1-2 closed tasks (bd list --status=closed)
2. Run 3-level validation (Unit + API + E2E)
3. If ANY fail: bd reopen <id> and fix BEFORE new work

Why It Matters: Hidden regressions multiply across features. Session F089-F090 evidence shows regression checks prevented 3+ hour blockages.

Full Validation Protocol: See WORKFLOWS.md

Failure Recovery: VALIDATION.md

Progress Tracking

Session Handoff Checklist

Before Ending:

1. ✅ Current feature complete or cleanly stopped
2. ✅ Beads state synced (bd sync)
3. ✅ Progress summary updated (.claude/progress/)
4. ✅ Git status clean, changes committed and pushed
5. ✅ Learnings stored in Hindsight (mcp__hindsight__retain())

Starting New:

1. Run PREFLIGHT.md checklist (includes memory check)
2. bd ready to find next available work
3. Review task details with bd show <id>
4. Continue with Phase 2 workflow

Full Guide: WORKFLOWS.md

• Session Summary template
• Progress Log template
• Learnings Accumulation
• Handoff procedures

Quick Troubleshooting

Worker Red Flags

Orchestrator Self-Check

Before Starting Phase 1 (Planning):

• ✅ Completed Phase 0 (Ideation)?
• ✅ Read WORKFLOWS.md Feature Decomposition section?
• ✅ Created TodoWrite checklist for Phase 1?
• ✅ Used MAKER checklist to evaluate approach?
• ✅ Chose correct workflow (Task Master vs Manual)?

After each feature:

• Did I use TaskCreate + SendMessage for worker delegation (or Task subagent fallback)?
• Ran regression check first?
• Worker stayed within scope?
• Validated feature works (not just tests pass)?
• Marked impl_complete (bd update <bd-id> --status=impl_complete)?
• Committed with message?
• Git status clean?

Pattern: All worker delegation uses native Agent Teams (TaskCreate + SendMessage to teammates). When AGENT_TEAMS is not enabled, fall back to Task(subagent_type="...").

Full Guide: VALIDATION.md

• Worker Red Flags & Recovery
• Orchestrator Anti-Patterns
• Hollow Test Problem
• Voting Protocol (when consensus needed)
• Recovery Patterns

Graph Editing Workflow

Orchestrators use the attractor CLI CRUD commands to build and maintain pipeline graphs.

Command Reference

Typical Workflow

1. Scaffold: cli.py generate --scaffold --prd PRD-XXX-001 --output pipeline.dot
2. Populate: Add task nodes with node add, connect with edge add
3. Validate: cli.py validate pipeline.dot after each batch of changes
4. Iterate: Modify status with node modify --set status=active, remove obsolete nodes/edges as scope evolves

Notes

• --dry-run is available on all mutating commands (add, remove, modify)
• --output json is available on list/add/remove for machine-readable output
• node remove automatically removes all edges referencing the deleted node
• All mutations append to <file>.ops.jsonl for audit trail

Pipeline Status & Transition Tracking

After building and validating a pipeline graph, orchestrators track execution progress using the status, transition, and checkpoint commands.

Status Commands

# Full status overview with node distribution
cobuilder pipeline status pipeline.dot --json --summary

# Human-readable status table
cobuilder pipeline status pipeline.dot

# JSON output for programmatic consumption
cobuilder pipeline status pipeline.dot --json

Transition Commands

Advance nodes through the lifecycle: pending → active → impl_complete → validated (or failed → active retry).

# Mark a node as active (implementation started)
cobuilder pipeline transition pipeline.dot impl_auth active

# Mark implementation complete (triggers paired validation gate)
cobuilder pipeline transition pipeline.dot impl_auth impl_complete

# Mark validated after passing acceptance criteria
cobuilder pipeline transition pipeline.dot val_auth validated

# Retry on failure — transition back to active
cobuilder pipeline transition pipeline.dot impl_auth active

Checkpoint Commands

Save and restore graph state as a safety net during complex transitions.

# Save current state before a batch of transitions
cobuilder pipeline checkpoint-save pipeline.dot

# Checkpoint after every transition (recommended)
cobuilder pipeline transition pipeline.dot node_x active && \
cobuilder pipeline checkpoint-save pipeline.dot

Transition Best Practices

• Always checkpoint after transitions — enables rollback if downstream work fails
• Validate after transitions: cobuilder pipeline validate pipeline.dot
• Check status before dispatch: Ensure upstream dependencies are validated before transitioning a node to active
• Report transitions to System 3 after impl_complete (via bd update <bd-id> --status=impl_complete)

Pipeline Dashboard & Progress

Use the dashboard for a unified view of initiative progress across all lifecycle stages.

# Human-readable progress table
cobuilder pipeline status pipeline.dot --summary

# JSON output for programmatic consumption
cobuilder pipeline status pipeline.dot --json --summary

Dashboard Output Includes

• Pipeline stage: Definition / Implementation / Validation / Finalized
• Node status distribution: pending / active / impl_complete / validated / failed
• Dependency readiness: Which nodes have all upstream dependencies met
• Progress percentage: Validated nodes vs total implementation nodes

Integration with Orchestrator Workflow

1. Before Phase 3 (Execution): Check dashboard to identify dispatchable nodes
2. During Execution: Monitor after each worker completion to track progress
3. After Validation: Verify all hexagon gates show validated before signaling finalization

# Check if all validation gates are validated (finalize-ready)
cobuilder pipeline status pipeline.dot --json | \
  python3 -c "import sys,json; d=json.load(sys.stdin); print('READY' if all(n['status']=='validated' for n in d.get('nodes',[]) if n.get('shape')=='hexagon') else 'NOT_READY')"

Progress Tracking Across Sessions

Status is persisted in the DOT file itself. After context compaction or session restart:

1. Re-read pipeline status: cobuilder pipeline status pipeline.dot --summary
2. Resume from last checkpoint if needed
3. Continue dispatching from where the previous session left off

Reference Guides

When to Consult Each Guide

Quick Lookup:

• REFERENCE.md - Commands, ports, directories, session templates

Session Start (MANDATORY):

• PREFLIGHT.md - 🚨 MANDATORY - Unified pre-flight checklist consolidating all circuit breakers (Serena, services, memory, regression)

During Ideation + Planning (Phase 0-1):

• WORKFLOWS.md - 🚨 MANDATORY READ before Phase 1 - Contains MAKER checklist, decision tree, red flags
• ZEROREPO.md - Codebase analysis with ZeroRepo. Delta classification (EXISTING/MODIFIED/NEW), CLI commands, troubleshooting, worker context enrichment

During Execution (Phase 2):

• WORKFLOWS.md - 4-Phase Pattern, Autonomous Mode Protocol, Validation (Unit + API + E2E), Progress Tracking, Session Handoffs
• WORKERS.md - Launching workers, monitoring, feedback, browser testing
• VALIDATION.md - Service startup, health checks, testing infrastructure, troubleshooting, recovery patterns

Session Boundaries:

• WORKFLOWS.md - Handoff checklists, summaries, learning documentation

Memory:

• references/hindsight-integration.md - Memory-driven decision making, learning loops, feedback patterns

Legacy Support:

• LEGACY_FEATURE_LIST.md - Archived feature_list.json documentation for migration

Skill Version: 5.3 (Progressive Disclosure Streamlining) Progressive Disclosure: 8 reference files for detailed information Last Updated: 2026-02-08 Latest Enhancements:

• v5.3: Progressive Disclosure Streamlining - Reduced SKILL.md from 6,473 to 3,800 words (41% reduction). Moved Memory-Driven Decision Making (~600 words) to reference file (references/hindsight-integration.md). Compressed Phase 0 Ideation, Sync Script, Worker Delegation, and Testing & Validation sections. Removed duplicate Acceptance Test Generation subsection (already in Phase 1 workflow). All writing converted to imperative/infinitive form (no second-person).
• v5.2: Bead Enrichment from RPG Graph - Added Phase 1.5 workflow to inject 04-rpg.json context into beads after Task Master sync. New "Enriching Beads with RPG Graph Context" section in ZEROREPO.md documents the enrichment pattern with real examples. Updated model from claude-sonnet-4-20250514 to claude-sonnet-4-5-20250929. Step 2.5 now split into 2.5a (generate delta) and 2.5b (enrich beads). Workers receive implementation-ready specs with file paths, interfaces, and technology stacks extracted from RPG graph.
• v5.1: ZeroRepo Integration - Added codebase-aware orchestration via ZeroRepo delta analysis. New Step 2.5 in Phase 1 planning runs zerorepo init + zerorepo generate to classify PRD components as EXISTING/MODIFIED/NEW. Delta context enriches worker task assignments with precise file paths and change summaries. New ZEROREPO.md reference guide. Three wrapper scripts (zerorepo-init.sh, zerorepo-generate.sh, zerorepo-update.sh). Codebase-Aware Task Creation workflow added to WORKFLOWS.md.
• v5.0: Native Agent Teams - Replaced Task subagent worker delegation with native Agent Teams (Teammate + TaskCreate + SendMessage). Workers are now persistent teammates that claim tasks from a shared TaskList, communicate peer-to-peer, and maintain session state across multiple assignments. Validator is a team role (not a separate Task subagent). Worker communication uses native team inboxes. Fallback to Task subagent mode when AGENT_TEAMS is not enabled.
• v4.0: Task-Based Worker Delegation - Replaced tmux worker delegation with Task subagents. Workers now receive assignments via Task(subagent_type="...") and return results directly. No session management, monitoring loops, or cleanup required. Parallel workers use run_in_background=True with TaskOutput() collection. System 3 -> Orchestrator still uses tmux for session isolation; Orchestrator -> Worker now uses Task subagents.
• v3.13: 🆕 Sync Script Finalization - Sync script now auto-closes Task Master tasks after sync (status=done). Removed mapping file (redundant with beads hierarchy). IMPORTANT: Must run from my-org/ root to use correct .beads database. Updated all docs with correct paths and --tasks-path usage.
• v3.12: ID Range Filtering - --from-id=<id> and --to-id=<id> to filter which Task Master tasks to sync. Essential for multi-PRD projects.
• v3.11: Enhanced Sync Script - --uber-epic=<id> for parent-child linking. Auto-maps description, details→design, testStrategy→acceptance.
• v3.10: Reference Consolidation - Created REFERENCE.md as quick reference card. Merged BEADS_INTEGRATION.md, README.md, and ORCHESTRATOR_INITIALIZATION_TEMPLATE.md into REFERENCE.md. Reduced reference files from 6 to 5. Essential commands, patterns, and session templates now in single quick-lookup location.
• v3.9: Validation Consolidation - Merged TESTING_INFRASTRUCTURE.md, TROUBLESHOOTING.md, and SERVICE_MANAGEMENT.md into unified VALIDATION.md. Reduced reference files from 8 to 6. All testing, troubleshooting, and service management now in single location.
• v3.8: Workflow Consolidation - Merged AUTONOMOUS_MODE.md, ORCHESTRATOR_PROCESS_FLOW.md, FEATURE_DECOMPOSITION.md, and PROGRESS_TRACKING.md into unified WORKFLOWS.md. Reduced reference files from 11 to 8. All workflow documentation now in single location.
• v3.7: Removed legacy inter-instance messaging (replaced by beads status updates).
• v3.6: Memory-Driven Decision Making - Integrated Hindsight for continuous learning. Task start recall, user feedback loop (retain → reflect → retain), double-rejection analysis with Perplexity validation, hollow test prevention, session closure reflection. Creates learning loop where each task benefits from all previous experience.
• v3.5: Clear four-phase pattern (Phase 0: Ideation → Phase 1: Planning → Phase 2: Execution → Phase 3: Validation). Consolidated Uber-Epic and AT-Epic patterns into unified "Epic Hierarchy Patterns" section with cleaner visual. Updated all phase references for consistency.
• v3.4: Beads-only workflow - Removed ALL feature_list.json references (now in LEGACY_FEATURE_LIST.md). Added MANDATORY Ideation Phase with brainstorming + parallel-solutioning.
• v3.3: Major streamlining - Created PREFLIGHT.md (unified session checklist), AUTONOMOUS_MODE.md (multi-feature protocol with 3-level validation), LEGACY_FEATURE_LIST.md (archived legacy docs).
• v3.2: Added Mandatory Acceptance Test Epic Pattern - every functional epic requires a paired AT epic with blocking dependency.
• v3.1: Added Uber-Epic First Pattern - mandatory hierarchy (uber-epic → epic → task) for all initiatives.
• v3.0: Added Beads task management integration as recommended state tracking method.