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

| Phase | What | Output | Parallel | |-------|------|--------|----------| | draft | Initial plans | draft-[specialist].md | Yes | | review | Cross-review | review-[specialist].md | Yes | | refine | Refine from feedback | refined-[specialist]-round[N].md | Yes | | consensus | Check agreement | (orchestrator action) | No | | master | Combine plans | master-plan.md | No |

Round Cycle

All specialists draft simultaneously → wait for all complete
All specialists review others' drafts → wait for all complete
All specialists refine based on reviews → wait for all complete
Check consensus
If not consensus and rounds < max: repeat from step 2
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

| Domain | Agent Type | |--------|------------| | Architecture | architect-review | | Security | code-reviewer | | Frontend | frontend-developer | | Backend | backend-security-coder | | DevOps | devops-troubleshooter |

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

Critical Rules

Orchestrator coordinates, never plans - You manage, not write
Specialists must wait - Poll with sleep before dependencies
Incremental saving - Save progress as you go
Constructive review - Improve, don't attack
Explicit disagreement - Explain why, don't stay silent
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:

| Field | Required | Why | |-------|----------|-----| | Phase type (Sequential/Parallel) | Yes | Orchestrator dispatches parallel sub-phases simultaneously | | Requirements (specific, not vague) | Yes | Dispatched verbatim to implementers | | Inputs (files to read) | Yes | Implementers need context | | Outputs (files to create/modify) | Yes | Validators check these | | Validation criteria | Yes | Validators check against these | | Dependencies | Yes | Orchestrator enforces ordering | | Gatekeeping commands | Yes | Implementers must run check-types/build before reporting done |

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:

Mark it as Type: Parallel
Define each sub-task with its own requirements, inputs, outputs, and validation
Include a Phase-level Validation section for the mandatory phase-wide validator
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:

Orchestrator reads the master plan and extracts phases
Each phase's requirements section is dispatched verbatim to implementers
Validation criteria are given to validators
Implementers run gatekeeping commands (typecheck, build) on their own before reporting done
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