Subagent Planificator

Subagent Planificator

Orchestrate collaborative planning where specialist subagents create plans, critique each other's work, and iterate toward consensus through structured discussion rounds.

Core Concept

Multiple specialists plan together, not in isolation. They see each other's work and improve it through discussion.

[DRAFT] → [WAIT] → [REVIEW] → [WAIT] → [REFINE] → [CONSENSUS?]
                                                      │
                                          ┌───────────┴───────────┐
                                          │                       │
                                     [CONSENSUS]           [MORE ROUNDS]
                                          │                       │
                                          ▼                       ▼
                                    [MASTER PLAN]          [Repeat refine]

Quick Start

Plan: [what needs planning]

Specialists needed:
- [Specialist A]: [their focus]
- [Specialist B]: [their focus]
- [Specialist C]: [their focus]

Orchestrator creates .plans/session-[id]/, dispatches specialists through draft → review → refine rounds, checks consensus, generates master plan.

Execution Model

YOU ARE THE ORCHESTRATOR: You coordinate rounds, dispatch specialists, manage waiting, synthesize results. You never write plans yourself.

Phase Flow

Round Cycle

1. All specialists draft simultaneously → wait for all complete 2. All specialists review others' drafts → wait for all complete 3. All specialists refine based on reviews → wait for all complete 4. Check consensus 5. If not consensus and rounds < max: repeat from step 2 6. Generate master plan

Coordination

File-Based Waiting

Specialists wait for dependencies using file polling with sleep:

# Wait for all drafts
while [ $(ls draft-*.md 2>/dev/null | wc -l) -lt 3 ]; do
    sleep 5
done

Critical: Always sleep between checks. Never busy-wait.

See waiting-script.md for full implementation.

Status File

status.yaml tracks progress:

phase: "draft"
rounds:
  current: 1
  max: 5
status:
  backend-architect:
    draft: "complete"
    review: "pending"
    refine: "pending"

Dispatching Specialists

Draft Phase

ROLE: [Specialist]
PHASE: Draft
MISSION: Create initial plan for [topic] from your domain perspective.

CONTEXT: .plans/session-[id]/context.md
OUTPUT: .plans/session-[id]/draft-[your-name].md

Include:
- Summary and approach
- Detailed phases with steps (must include phase type, requirements, inputs, outputs, validation criteria — see Orchestration Compatibility below)
- Dependencies on other specialists
- Risks and alternatives

Update status.yaml when complete.

Review Phase

ROLE: [Specialist]
PHASE: Review
MISSION: Review other specialists' drafts and provide feedback.

PLANS TO REVIEW:
- draft-[other-specialist-1].md
- draft-[other-specialist-2].md

WAIT: Before reviewing, poll for all draft files with 5s sleep.

OUTPUT: review-[your-name].md

For each plan:
- Strengths
- Concerns (specific, actionable)
- Alignment with your plan
- Conflicts identified

Update status.yaml when complete.

Refine Phase

ROLE: [Specialist]
PHASE: Refine Round [N]
MISSION: Refine your plan based on reviews.

REVIEWS: review-[specialist-1].md, review-[specialist-2].md
WAIT: Poll for all review files with 5s sleep.

OUTPUT: refined-[your-name]-round[N].md

Include:
- Changes from previous version (with reasons)
- Addressed feedback (how, or why not)
- Convergence notes (where you now agree with others)
- Remaining concerns

Update status.yaml when complete.

See plan-templates.md for full formats.

Consensus Checking

After each refine round, check for consensus:

Positive Signals

• "Aligned with [other]'s approach"
• "Incorporated [feedback]"
• "Converged on [decision]"

Negative Signals

• "Fundamentally disagree"
• "Cannot proceed if [condition]"
• "This conflicts with [requirement]"

Decision

IF no_negative_signals AND min_positive_per_specialist >= 2:
    consensus = full
    
ELSE IF negative_signals <= 2 AND movement_toward_agreement:
    consensus = partial
    trigger_another_round
    
ELSE IF rounds < max:
    trigger_another_round
    
ELSE:
    document_divergence
    proceed_to_master

See consensus-criteria.md for full algorithm.

Master Plan Generation

ROLE: Master Planner
MISSION: Combine refined plans into unified master plan that is ready for subagent-orchestration.

INPUTS: All refined plans, all reviews from final round
OUTPUT: master-plan.md

TEMPLATE: Use the Master Plan Template from references/plan-templates.md.
It MUST produce a plan compatible with subagent-orchestration — every phase needs:
- Type (Sequential/Parallel)
- Specific, actionable requirements
- Inputs (files to read) and Outputs (files to create/modify)
- Validation criteria
- Dependencies
- Gatekeeping commands for the project (typecheck, build)
- Phase-level Validation section for any parallel phase

Include:
- Executive summary
- Consensus decisions
- Integrated plan (orchestration-compatible phases)
- Resolved conflicts
- Open items
- Combined risk assessment
- Divergent views (if any)
- Success criteria with gatekeeping commands

File Structure

.plans/
└── session-[id]/
    ├── context.md              # Planning brief
    ├── status.yaml             # Coordination
    ├── draft-[spec].md         # Initial plans
    ├── review-[spec].md        # Cross-reviews
    ├── refined-[spec]-r[N].md  # Refined plans
    └── master-plan.md          # Final combined plan

Specialist Selection

Counts: 2-3 for simple plans, 3-5 for standard, 5-7 for complex.

Critical Rules

1. Orchestrator coordinates, never plans - You manage, not write 2. Specialists must wait - Poll with sleep before dependencies 3. Incremental saving - Save progress as you go 4. Constructive review - Improve, don't attack 5. Explicit disagreement - Explain why, don't stay silent 6. Max rounds cap - Stop at 5 even without full consensus

Progress Reporting

Session: [id]
Round: [N]/5
Phase: [draft|review|refine]
Status:
  - [Specialist A]: [complete|in_progress|pending]
  - [Specialist B]: [complete|in_progress|pending]

Final: Consensus level, divergent views (if any), output path.

Integration

• deep-agent-review: Use planificator to plan remediation after review
• subagent-orchestration: Master plan feeds directly into orchestration as input. See Orchestration Compatibility below.
• the-council: Council for decisions, Planificator for comprehensive plans

Orchestration Compatibility

The master plan produced by this skill is the direct input for subagent-orchestration. The master plan MUST be structured so the orchestrator can dispatch implementers without ambiguity.

Required Plan Structure

Every phase in the master plan MUST include:

Phase Sizing — Must Fit in Agent Context

Every phase must fit comfortably inside a single agent's context window. If a phase is too large, it MUST be split into sub-phases.

A phase is too large if:

• It creates or modifies more than ~15 files
• Its requirements would produce more than ~500 lines of new code
• It covers multiple unrelated concerns

When a phase is too large, split it into focused sub-phases. Each sub-phase gets its own implementer → validator flow, followed by a phase-wide validator.

Why: Agent context windows are finite. When context fills up, compaction discards earlier information and code quality drops precipitously — the agent loses track of patterns, conventions, and decisions made earlier. Smaller phases produce better code.

Parallel Phases

If a phase has multiple sub-tasks that can run simultaneously:

1. Mark it as Type: Parallel 2. Define each sub-task with its own requirements, inputs, outputs, and validation 3. Include a Phase-level Validation section for the mandatory phase-wide validator 4. The phase-wide validator checks: integration between sub-phases, shared types, imports, no circular dependencies, overall coherence

Handoff Contract

When the master plan is handed to the orchestrator:

1. Orchestrator reads the master plan and extracts phases 2. Each phase's requirements section is dispatched verbatim to implementers 3. Validation criteria are given to validators 4. Implementers run gatekeeping commands (typecheck, build) on their own before reporting done 5. Multi-sub-phase phases get a phase-wide validator after individual validations pass

This means the master plan must be self-contained — the orchestrator should never need to ask clarifying questions. If a requirement is vague, the plan is not ready.

Plan Checklist

Before declaring the master plan complete, verify:

• [ ] Every phase has a type (Sequential or Parallel)
• [ ] Every phase has specific, actionable requirements (not "make it work")
• [ ] Every phase lists exact files to create/modify
• [ ] Every phase has explicit validation criteria
• [ ] Every phase states its dependencies
• [ ] Gatekeeping commands for the project are listed (check-types, build)
• [ ] Parallel phases have a Phase-level Validation section
• [ ] No vague or ambiguous requirements remain
• [ ] Every phase fits in a single agent context (~15 files max, ~500 lines of code max). If not, it's split into sub-phases.

Quick Reference

1. Create .plans/session-[id]/ with context.md, status.yaml
2. Draft: dispatch all specialists in parallel, wait for files
3. Review: dispatch all specialists, each waits for all drafts
4. Refine: dispatch all specialists, each waits for all reviews
5. Check consensus → if not and rounds < 5, goto 3
6. Master: dispatch agent to synthesize
7. Report to user

Reference Documentation

• Waiting Scripts - File-based coordination
• Plan Templates - Full format for each phase
• Consensus Criteria - Agreement detection

Consensus Criteria - When is agreement reached?

Consensus Levels

Full Consensus

All specialists agree on:

• Core approach
• Major phases
• Dependencies
• Risk handling
• Timeline

Signal: No negative signals, all positive signals present.

Partial Consensus

Agreement on most items, divergence on specific issues.

Signal: Most items agreed, some items have documented disagreements.

No Consensus

Fundamental disagreement on approach.

Signal: Multiple negative signals, specialists standing firm.

Consensus Signals

Positive Signals

In specialist communications, look for:

Negative Signals

Consensus Check Algorithm

Per-Round Check

consensus_check:
  inputs:
    - all refined plans from current round
    - all reviews from current round
    
  process:
    1. Count positive signals across all documents
    2. Count negative signals across all documents
    3. Identify unresolved conflicts
    4. Check if specialists are moving toward or away from agreement
    
  decision:
    if no_negative_signals and min_positive_signals_per_specialist >= 2:
      consensus: full
      
    elif negative_signals <= 2 and movement_toward_agreement:
      consensus: partial
      trigger_another_round: true
      
    else:
      consensus: none
      if rounds < max:
        trigger_another_round: true
        focus_areas: [conflict topics]
      else:
        document_divergence: true

Movement Detection

Compare rounds to detect convergence or divergence:

movement_detection:
  compare:
    - round[N-1] disagreements
    - round[N] disagreements
    
  patterns:
    convergence:
      - Fewer disagreements than previous round
      - Disagreements becoming more specific (narrowing)
      - Specialists acknowledging others' points
      
    divergence:
      - More disagreements than previous round
      - Positions hardening (same points repeated)
      - New disagreements emerging
      
    stalled:
      - Same disagreements across rounds
      - No new positive signals
      - Specialists not engaging with feedback

Conflict Categories

Resolvable Conflicts

Can be resolved through discussion:

Irreconcilable Conflicts

Require escalation or decision authority:

Consensus Scoring

Individual Specialist Score

specialist_consensus_score:
  factors:
    - positive_signals: +1 each
    - negative_signals: -2 each
    - feedback_incorporated: +2
    - feedback_rejected_without_reason: -1
    - new_compromise_suggested: +3
    
  scoring:
    excellent: >= 8    # Fully aligned
    good: 4-7          # Generally aligned
    moderate: 0-3      # Some alignment
    poor: < 0          # Not aligned

Overall Session Score

session_consensus_score:
  formula: "average(all specialist scores) + convergence_bonus"
  
  convergence_bonus:
    rounds_1_to_2_improvement: +2
    rounds_2_to_3_improvement: +1
    stalled: 0
    regression: -2
    
  thresholds:
    full_consensus: >= 7
    partial_consensus: 3-6
    no_consensus: < 3

Escalation Triggers

Auto-escalate if:

1. Stalled for 3 rounds: Same conflicts, no movement 2. Negative score specialist: Any specialist < 0 for 2 rounds 3. New conflicts emerging: More conflicts in later rounds 4. Domain expert veto: Security/safety expert says "unsafe"

Escalation actions:

• Document all positions clearly
• Identify what information would resolve
• Recommend decision authority
• Note risks of each path

Documenting Divergence

When consensus cannot be reached:

## Divergent Views

### Issue: [Topic]

**[Specialist A] Position:**
- [Their view]
- Rationale: [Why]
- Trade-offs accepted: [What they give up]
- Would accept: [What would change their mind]

**[Specialist B] Position:**
- [Their view]
- Rationale: [Why]
- Trade-offs accepted: [What they give up]
- Would accept: [What would change their mind]

**Impact of Each Path:**
- Path A ([Specialist A]'s preference): [Consequences]
- Path B ([Specialist B]'s preference): [Consequences]

**Recommendation:**
[Orchestrator's recommendation based on session goals]

**Decision Needed From:**
[Who has authority to decide]

Quick Reference

Consensus Checklist

Before declaring consensus, verify:

• [ ] No negative signals in latest round
• [ ] Each specialist has ≥2 positive signals
• [ ] All dependencies acknowledged
• [ ] No "fundamental disagreements"
• [ ] No "cannot proceed" statements
• [ ] Movement toward agreement (not stalled)

Round Decision Tree

Check signals
    │
    ├─ No negative, positive ≥ 2 per specialist?
    │       │
    │       └─ YES → Full consensus → Create master plan
    │
    ├─ Negative ≤ 2, movement toward agreement?
    │       │
    │       └─ YES → Partial → Another round
    │
    ├─ Rounds < max?
    │       │
    │       ├─ YES → Another round, focus on conflicts
    │       │
    │       └─ NO → Document divergence, recommend escalation

Plan Templates - Formats for each planning phase

Context Template

File: .plans/session-[id]/context.md

# Planning Context

## Topic
[What is being planned]

## Background
[Relevant context, constraints, history]

## Goals
1. [Primary goal]
2. [Secondary goal]
3. [Tertiary goal]

## Constraints
- [Constraint 1]
- [Constraint 2]
- [Constraint 3]

## Scope
In scope:
- [Item 1]
- [Item 2]

Out of scope:
- [Item 1]
- [Item 2]

## Timeline
[Any deadlines or time constraints]

## Resources
[Available resources, team size, budget considerations]

## Related Artifacts
- [Link to relevant docs]
- [Link to existing code]
- [Link to previous decisions]

## Success Criteria
[How will we know the plan succeeded]

Draft Plan Template

File: .plans/session-[id]/draft-[specialist].md

# [Specialist Name] Plan - Draft

## Metadata
- Specialist: [Name]
- Domain: [What domain this covers]
- Created: [Timestamp]

## Executive Summary
[2-3 sentences summarizing the approach]

## Problem Analysis
[How this specialist sees the problem]

## Proposed Approach
[High-level strategy]

## Detailed Plan

### Phase 1: [Phase Name]
**Type:** [Sequential/Parallel]
**Dependencies:** [What's needed first, or "None"]

**Requirements**:
- [Specific, actionable requirement]
- [Specific, actionable requirement]

**Inputs**:
- Read: [files this phase needs as context]
- Reference: [existing patterns to follow]

**Outputs**:
- Create: [files to create]
- Modify: [files to modify]

**Validation Criteria**:
- Type check: Zero errors
- Build: Success
- [Phase-specific criteria]

Steps:
1. [Step 1]
   - Details: [More info]
   - Risk: [Any risks]
    
2. [Step 2]
   - Details: [More info]
   - Risk: [Any risks]

### Phase 2: [Phase Name]
[Same structure]

### Phase 3: [Phase Name]
[Same structure]

## Dependencies on Other Specialists
- [Specialist B]: [What I need from them]
- [Specialist C]: [What I need from them]

## What Others Need From Me
- [Deliverable 1]: [For whom]
- [Deliverable 2]: [For whom]

## Risks
| Risk | Likelihood | Impact | Mitigation |
|------|------------|--------|------------|
| [Risk 1] | H/M/L | H/M/L | [How to handle] |
| [Risk 2] | H/M/L | H/M/L | [How to handle] |

## Open Questions
- [Question 1]
- [Question 2]

## Alternatives Considered
### [Alternative A]
[Description]
Why not chosen: [Reason]

### [Alternative B]
[Description]
Why not chosen: [Reason]

## Confidence Level
[High/Medium/Low] - [Why]

Review Template

File: .plans/session-[id]/review-[specialist].md

# [Specialist Name] Review - Round [N]

## Metadata
- Reviewer: [Name]
- Round: [N]
- Created: [Timestamp]

## Reviews

### Review of [Other Specialist A]'s Plan

**Overall Assessment:** [Positive/Mixed/Concerning]

**Strengths:**
1. [Strength 1]
2. [Strength 2]
3. [Strength 3]

**Concerns:**
1. **[Concern 1]**
   - Location: [Phase/Step reference]
   - Issue: [What's wrong]
   - Impact: [Why it matters]
   - Suggestion: [How to fix]

2. **[Concern 2]**
   [Same structure]

**Dependencies on My Plan:**
- [Where their plan depends on mine]
- [Any conflicts with my approach]

**Questions:**
- [Question about their approach]

---

### Review of [Other Specialist B]'s Plan

[Same structure as above]

---

## Cross-Cutting Observations

### Points of Agreement
- [Where all plans align]

### Points of Conflict
- [Where plans contradict]

| Topic | [Specialist A] | [Specialist B] | [My View] |
|-------|----------------|----------------|-----------|
| [Issue 1] | [Position] | [Position] | [Position] |
| [Issue 2] | [Position] | [Position] | [Position] |

### Integration Opportunities
- [Where plans could be combined]

### Missing Perspectives
- [What's not covered by any plan]

## Synthesis Suggestions

### Proposed Compromises
1. **[Conflict 1]**
   - Current positions: [A says X, B says Y]
   - Suggested resolution: [Z]
   - Rationale: [Why this works]

### Recommended Approach
[How to combine plans into unified approach]

## Confidence in Consensus
[High/Medium/Low] - [What would change this]

Refined Plan Template

File: .plans/session-[id]/refined-[specialist]-round[N].md

# [Specialist Name] Plan - Refined Round [N]

## Metadata
- Specialist: [Name]
- Round: [N]
- Previous: [Link to previous version]
- Created: [Timestamp]

## Changelog

### Changes from Round [N-1]
| Change | Reason | Feedback Source |
|--------|--------|-----------------|
| [Change 1] | [Why] | [Who suggested] |
| [Change 2] | [Why] | [Who suggested] |
| [Change 3] | [Why] | [Who suggested] |

### Feedback Not Incorporated
| Feedback | From | Why Not Incorporated |
|----------|------|---------------------|
| [Feedback 1] | [Specialist] | [Reason] |
| [Feedback 2] | [Specialist] | [Reason] |

## Updated Executive Summary
[2-3 sentences, updated from feedback]

## Refined Plan

### Phase 1: [Phase Name]
[Updated based on feedback]

### Phase 2: [Phase Name]
[Updated based on feedback]

## Updated Dependencies
- [Specialist B]: [Updated needs]
- [Specialist C]: [Updated needs]

## Convergence Notes
[Where this plan now aligns with others]

### Agreements Reached
- [With Specialist B]: [What was agreed]
- [With Specialist C]: [What was agreed]

### Remaining Differences
- [Issue where agreement not reached]

## Updated Confidence
[High/Medium/Low] - [What changed]

Master Plan Template

File: .plans/session-[id]/master-plan.md

This template produces a plan directly consumable by subagent-orchestration. Every phase must be self-contained with enough detail for an implementer subagent to execute without asking questions.

Phase sizing rule: Each phase must fit comfortably in a single agent's context window (~15 files max, ~500 lines of output max). If a phase is too large, split it into sub-phases with a phase-wide validator.

# Master Plan - [Topic]

## Metadata
- Session: [ID]
- Created: [Timestamp]
- Rounds: [N]
- Consensus: [Full/Partial/None]

## Prerequisites
- Tools required (e.g., pnpm, TypeScript)
- Files that must exist before starting
- Environment setup needed

## Gatekeeping Commands
List the commands implementers must run before reporting done:
- Type check: [e.g., `pnpm run check-types`]
- Build: [e.g., `pnpm run build`]

## Executive Summary
[3-5 sentences on the unified approach]

## Consensus Decisions
These decisions were agreed upon by all specialists:

1. **[Decision 1]**
   - What: [The decision]
   - Why: [Rationale]
   - Specialists: [Who agreed]

2. **[Decision 2]**
   [Same structure]

## Integrated Plan

### Overview Timeline

Phase 1: [Name] [Sequential] Phase 2: [Name] [Sequential] Phase 3: [Name] [Parallel: Sub-task A, Sub-task B, Sub-task C] Phase 4: [Name] [Sequential]

---

### Phase 1: [Phase Name]
**Type**: Sequential
**Owner:** [Lead specialist]
**Dependencies:** [Prerequisites, or "None" for first phase]

**Requirements**:
- [Specific requirement 1]
- [Specific requirement 2]
- [Specific requirement 3]

**Inputs**:
- Read: [file1.ts, file2.ts]
- Reference: [existing patterns to follow]

**Outputs**:
- Create: [new-file1.ts, new-file2.ts]
- Modify: [existing-file.ts]

**Validation Criteria**:
- Type check: Zero errors
- Build: Success
- [Specific criteria for this phase]

---

### Phase 2: [Phase Name]
**Type**: Sequential
**Dependencies:** Phase 1 must complete

[Same structure as Phase 1]

---

### Phase 3: [Phase Name]
**Type**: Parallel
**Dependencies:** Phase 2 must complete

#### 3.1: [Sub-task A Name]
**Requirements**:
- [Specific requirement 1]
- [Specific requirement 2]

**Inputs**:
- Read: [files]

**Outputs**:
- Create: [fileA1.ts, fileA2.ts]

**Validation**:
- [Criteria for sub-task A]

#### 3.2: [Sub-task B Name]
**Requirements**:
- [Specific requirement 1]
- [Specific requirement 2]

**Inputs**:
- Read: [files]

**Outputs**:
- Create: [fileB1.ts, fileB2.ts]

**Validation**:
- [Criteria for sub-task B]

#### 3.3: [Sub-task C Name]
**Requirements**:
- [Specific requirement 1]

**Inputs**:
- Read: [files]

**Outputs**:
- Create: [fileC1.ts]

**Validation**:
- [Criteria for sub-task C]

**Phase-level Validation**:
- All sub-tasks pass individual validation
- Integration: Sub-tasks work together (shared types, imports)
- No circular dependencies
- Type check: Zero errors across all files
- Build: Success

---

### Phase 4: [Phase Name]
**Type**: Sequential
**Dependencies:** Phase 3 must complete

[Same structure as Phase 1]

---

## Resolved Conflicts

### [Conflict 1]
- Original positions:
  - [Specialist A]: [Position]
  - [Specialist B]: [Position]
- Resolution: [How resolved]
- Rationale: [Why this resolution]

## Open Items

### Decisions Needed
- [ ] [Decision 1] - Owner: [Who]
- [ ] [Decision 2] - Owner: [Who]

### Information Needed
- [ ] [Info 1] - From: [Source]
- [ ] [Info 2] - From: [Source]

## Risks and Mitigations

| Risk | Likelihood | Impact | Owner | Mitigation |
|------|------------|--------|-------|------------|
| [Risk 1] | H/M/L | H/M/L | [Who] | [Strategy] |
| [Risk 2] | H/M/L | H/M/L | [Who] | [Strategy] |

## Success Criteria

Overall success requires:
- All phases complete and validate successfully
- Gatekeeping commands pass: [typecheck command], [build command]
- All requirements from all phases met

## Appendix

### Divergent Views
[If partial consensus, document remaining disagreements]

### Alternatives Considered
[Combined alternatives from all specialists]

Status YAML Template

File: .plans/session-[id]/status.yaml

session:
  id: "session-[id]"
  created: "[timestamp]"
  topic: "[planning topic]"
  
specialists:
  - name: "[specialist-1]"
    agent_type: "[agent-type]"
    focus: "[domain focus]"
    
  - name: "[specialist-2]"
    agent_type: "[agent-type]"
    focus: "[domain focus]"

rounds:
  current: 1
  max: 5
  completed: []

phase: "draft"  # draft | review | refine | consensus | master

status:
  "[specialist-1]":
    draft: "pending"      # pending | in_progress | complete
    review: "pending"
    refine_round1: "pending"
    refine_round2: "pending"
    
  "[specialist-2]":
    draft: "pending"
    review: "pending"
    refine_round1: "pending"
    refine_round2: "pending"

files:
  context: "context.md"
  drafts:
    - "draft-[specialist-1].md"
    - "draft-[specialist-2].md"
  reviews:
    - "review-[specialist-1].md"
    - "review-[specialist-2].md"
  refined:
    round1:
      - "refined-[specialist-1]-round1.md"
      - "refined-[specialist-2]-round1.md"
  master: "master-plan.md"

consensus:
  reached: false
  round: null
  divergent_views: []

Waiting Script - File-based coordination without CPU thrash

Purpose

Specialists need to wait for other specialists to complete their work before proceeding. This script provides a polling mechanism with configurable intervals.

Core Functions

wait_for_files

Wait until all specified files exist.

#!/bin/bash
# wait-for-files.sh

set -e

MAX_WAIT=${MAX_WAIT:-300}      # 5 minutes default
INTERVAL=${INTERVAL:-5}        # 5 seconds between checks
TIMEOUT_EXIT=${TIMEOUT_EXIT:-1}

wait_for_files() {
    local files=("$@")
    local waited=0
    local remaining=()
    
    echo "Waiting for files: ${files[*]}"
    echo "Max wait: ${MAX_WAIT}s, Interval: ${INTERVAL}s"
    
    while [ $waited -lt $MAX_WAIT ]; do
        remaining=()
        
        for file in "${files[@]}"; do
            if [ ! -f "$file" ]; then
                remaining+=("$file")
            fi
        done
        
        if [ ${#remaining[@]} -eq 0 ]; then
            echo "All files present after ${waited}s"
            return 0
        fi
        
        echo "Waiting... (${waited}s elapsed, ${#remaining[@]} files pending)"
        sleep $INTERVAL
        waited=$((waited + INTERVAL))
    done
    
    echo "Timeout after ${waited}s. Missing files:"
    printf '  - %s\n' "${remaining[@]}"
    return $TIMEOUT_EXIT
}

# Usage: wait_for_files file1.md file2.md file3.md
wait_for_files "$@"

wait_for_status

Wait for status.yaml to show all specialists at expected phase.

#!/bin/bash
# wait-for-status.sh

set -e

SESSION_DIR=${1:-.plans/session-current}
PHASE=${2:-draft}
EXPECTED_STATUS=${3:-complete}
MAX_WAIT=${MAX_WAIT:-300}
INTERVAL=${INTERVAL:-5}

wait_for_status() {
    local status_file="$SESSION_DIR/status.yaml"
    local waited=0
    
    if [ ! -f "$status_file" ]; then
        echo "Status file not found: $status_file"
        return 1
    fi
    
    # Extract specialist names from status.yaml
    local specialists=$(grep -E "^  [a-z].*:$" "$status_file" | sed 's/:$//' | tr -d ' ')
    
    echo "Waiting for specialists to reach $PHASE = $EXPECTED_STATUS"
    echo "Specialists: $specialists"
    
    while [ $waited -lt $MAX_WAIT ]; do
        local all_complete=true
        
        for spec in $specialists; do
            local status=$(grep -A1 "^  $spec:" "$status_file" | grep "$PHASE:" | awk '{print $2}' | tr -d '"')
            
            if [ "$status" != "$EXPECTED_STATUS" ]; then
                all_complete=false
                echo "  $spec: $status (waiting...)"
            else
                echo "  $spec: $status ✓"
            fi
        done
        
        if $all_complete; then
            echo "All specialists complete after ${waited}s"
            return 0
        fi
        
        sleep $INTERVAL
        waited=$((waited + INTERVAL))
    done
    
    echo "Timeout after ${waited}s"
    return 1
}

wait_for_status

wait_with_callback

Wait with optional callback when files appear.

#!/bin/bash
# wait-with-callback.sh

wait_with_callback() {
    local pattern="$1"
    local callback="$2"
    local max_wait=${3:-300}
    local interval=${4:-5}
    local waited=0
    
    while [ $waited -lt $max_wait ]; do
        local files=$(ls $pattern 2>/dev/null || true)
        
        if [ -n "$files" ]; then
            if [ -n "$callback" ]; then
                eval "$callback \"$files\""
            fi
            return 0
        fi
        
        sleep $interval
        waited=$((waited + interval))
    done
    
    return 1
}

# Example: Wait for any review file, then process it
# wait_with_callback "plans/review-*.md" "process_reviews"

Agent Instructions

In Specialist Prompts

Include waiting instructions in the specialist dispatch:

WAIT PROTOCOL:

Before starting your review, you must wait for all draft files to exist.

1. Check for these files:
   - plans/draft-backend-architect.md
   - plans/draft-frontend-lead.md
   - plans/draft-security-analyst.md

2. If any file is missing:
   - Wait 5 seconds
   - Check again
   - Repeat until all exist

3. If waiting more than 5 minutes, report timeout

You can implement this with:

for file in plans/draft-*.md; do while [ ! -f "$file" ]; do echo "Waiting for $file..." sleep 5 done done echo "All drafts complete, proceeding with review"

DO NOT busy-wait (loop without sleep). Always use sleep between checks.

Polling Intervals

Timeout Handling

TIMEOUT HANDLING:

If you timeout while waiting:

1. Report what you were waiting for
2. List which files exist and which are missing
3. Suggest:
   - Extending the timeout
   - Checking if other specialists are stuck
   - Proceeding with available information

Do not proceed without dependencies unless explicitly told to.

Status Updates

Specialists should update status.yaml as they progress:

# Mark draft as complete
update_status() {
    local session_dir="$1"
    local specialist="$2"
    local phase="$3"
    local status="$4"
    
    local status_file="$session_dir/status.yaml"
    
    # Simple status update (requires yq or similar)
    if command -v yq &> /dev/null; then
        yq -i ".status.$specialist.$phase = \"$status\"" "$status_file"
    else
        # Fallback: append status line
        echo "  $phase: \"$status\"" >> "$status_file"
    fi
}

# Usage: update_status ".plans/session-abc" "backend-architect" "draft" "complete"

CPU-Friendly Patterns

Good

while [ ! -f "$file" ]; do
    sleep 5
done

Bad

while [ ! -f "$file" ]; do
    : # No sleep - pegs CPU at 100%
done

Good (with timeout)

waited=0
while [ $waited -lt 300 ] && [ ! -f "$file" ]; do
    sleep 5
    waited=$((waited + 5))
done

Integration with Orchestrator

The orchestrator can also use these patterns:

// Orchestrator checking for completion
async function waitForPhase(sessionDir, phase, specialists, timeout = 300000) {
    const startTime = Date.now();
    const interval = 5000; // 5 seconds
    
    while (Date.now() - startTime < timeout) {
        let allComplete = true;
        
        for (const specialist of specialists) {
            const file = `${sessionDir}/${phase}-${specialist}.md`;
            if (!fs.existsSync(file)) {
                allComplete = false;
                break;
            }
        }
        
        if (allComplete) {
            return true;
        }
        
        await new Promise(resolve => setTimeout(resolve, interval));
    }
    
    return false;
}