Workflow Overview#

Goal: Review a document from multiple expert perspectives in parallel

Phase: Any (works across all phases)

Agent: Team Lead

Inputs: Document path, document type (auto-detected or user-specified)

Output: Individual review files + integrated review summary

Duration: 5-10 minutes (parallel vs 15-30 min sequential review)

When to use: When you want comprehensive multi-perspective review of a BMAD document

Prerequisite: Agent Teams preferred (CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1); when unavailable this workflow reroutes to the sequential route, it does not stop (Pre-Flight step 3)

Substrate: Agent Teams — unchanged. Read-only reviewers, one output file per perspective, disjoint paths: this is one of the few genuinely safe fan-outs in the repo, so it is not migrated to the Workflow substrate — that would buy schema enforcement only, and a second substrate here buys drift risk for no correctness change. The substrate row, its branch prohibition, the width: / own: / tier: fan-out obligations, and the gate tri-state are defined once in plugins/cc-dev/rules/orchestration-graph.md → "Substrate Selection — 6행 매트릭스", "Fan-out Obligations", "Gate Contract — verdict 는 tri-state 다"; they are not restated here. Per-loop values live at each loop's own site below.

Pre-Flight#

1. Load context per helpers.md#Combined-Config-Load
2. Check Agent Teams per helpers.md#Check-Agent-Teams-Available
3. If teams_available = false — reroute to the sequential route, do not stop: Falling back is the declared default behaviour of every substrate — same result, only slower (plugins/cc-dev/skills/agent-teams/SKILL.md → "Fallback Principle", restated as a fan-out obligation in plugins/cc-dev/rules/orchestration-graph.md → "Fan-out Obligations"). An unavailable substrate is a speed problem, not a reason to abandon the review.
   • Output:

           ⚠ Agent Teams not available — running the same panel sequentially.
     
     Agent Teams is an experimental feature that requires:
       CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
     
     Sequential route (same perspectives, same output paths, same consensus rule;
     ~15-30 min instead of 5-10):
       /cc-product:review --persona {persona}  " {document_path} 검토 "     ← once per perspective
     

   • Continue with Part 1 — perspective selection and the width: cap are substrate-independent — then run the panel one perspective at a time, mapping PM → product-manager, Architect → architect, Developer → flutter-developer (or backend-developer for server-side documents), Scrum Master → scrum-master. Invoke /cc-product:review once per persona; never --persona a,b, which fans out again on a substrate that was just declared unavailable (introduce no new parallelism here).
   • Each sequential run writes the same .bmad/reviews/{doc_name}-review-{perspective}.md, so Part 3's per-reviewer accounting and Part 4's consensus rule apply unchanged. A persona whose run is skipped or errors is a MISSING reviewer, exactly as in the parallel route.
   • Record Substrate: sequential fallback (Agent Teams unavailable) in the integrated summary.
   • Stop only if the user declines the sequential route — and then report which perspectives were never run instead of emitting a consensus over an unrun panel.
4. Read target document:
   • Accept document path as argument (e.g., /team-review .bmad/prd-myapp.md)
   • If no argument: ask user for document path
5. Detect document type from filename or content:
   • prd-* or content has "Product Requirements" → PRD
   • architecture-* or content has "Architecture" → Architecture
   • sprint-plan-* or content has "Sprint" → Sprint Plan
   • tech-spec-* or content has "Technical Specification" → Tech Spec
   • Other → ask user for document type
6. Load max_teammates from config agent_teams.max_teammates (default: 3). This is the width: budget for Part 1's panel, not a decoration — today it is loaded and never applied, so the panel width is decided by the perspective tables alone. width: obligations (a cap, plus a deferred log for whatever the cap postponed — no silent truncation) are defined in plugins/cc-dev/rules/orchestration-graph.md → "Fan-out Obligations".

Part 1: Select Review Perspectives#

Auto-select reviewers based on document type:

PRD (Product Requirements Document):

Architecture Document:

Sprint Plan:

Tech Spec:

Fix the panel — width: = min(selected perspectives, max_teammates):

• panel = the perspectives selected above, in table order. reporting_target = len(panel), and that number is what Part 3 prints and Part 4's consensus rule measures against. The panel is fixed here and never grows during Part 3.
• If len(selected) > max_teammates: keep the first max_teammates in table order and write the remainder to a deferred log — .bmad/reviews/{doc_name}-review-deferred.md, one entry per perspective with the reason (width: cap {max_teammates}) and the command that runs it later (/cc-product:review --persona {persona}). Dropping a perspective silently is prohibited (plugins/cc-dev/rules/orchestration-graph.md → "Fan-out Obligations").
• A deferred perspective is a missing reviewer for Part 4: the panel was capped, not completed, so Pass is not reachable for that run (consensus rule row 3).
• Never raise width: above max_teammates to "fit everyone in" — the cap is the budget.

Display plan:

Review Plan for: {document_path}
Document Type: {type}
Panel: {reporting_target} reviewers (width cap: {max_teammates})
Deferred: {none | perspective list → .bmad/reviews/{doc_name}-review-deferred.md}

Reviewer 1 ({perspective}):
  Focus: {focus_description}
  Output: .bmad/reviews/{doc_name}-review-{perspective}.md

Reviewer 2 ({perspective}):
  Focus: {focus_description}
  Output: .bmad/reviews/{doc_name}-review-{perspective}.md

Reviewer 3 ({perspective}):
  Focus: {focus_description}
  Output: .bmad/reviews/{doc_name}-review-{perspective}.md

Proceed? (y/n)

Wait for user confirmation.

If config.agent_teams.auto_approve_plans = true, skip confirmation.

Part 2: Spawn Reviewers#

Step 1: Ensure review output directory exists:

Create .bmad/reviews/ directory if not exists

Step 2: Create shared task list per helpers.md#Create-Team-Task-List:

For each reviewer:

TaskCreate:
  subject:  " Reviewer ({perspective}): Review {document_name} " 
   description: Document content, review focus, checklist, output path
  activeForm:  " Reviewing {document_name} as {perspective} "

Step 3: Spawn teammates per helpers.md#Spawn-BMAD-Teammate:

For each reviewer in panel (exactly reporting_target spawns — no more, no fewer):

• role: "reviewer"
• effort_tier: standard — mandatory, never left unset. The teammate returns findings and its own per-perspective assessment; the Lead composes the consensus verdict (Part 4), so no teammate's verdict gates the pipeline by itself and frontier is not warranted. Every agent-spawning node must declare tier: (plugins/cc-dev/rules/orchestration-graph.md → "Fan-out Obligations"): unset = silent inherit, which at width 3 is a 3× multiplier, not a default. Tier → model mapping: plugins/cc-dev/skills/agent-teams/SKILL.md → "Effort Routing Convention".
• context:
  • document_path: full path to document
  • document_type: detected type
  • review_perspective: PM / Architect / Developer / Scrum Master
  • review_focus: specific focus areas for this perspective
  • review_checklist: perspective-specific checklist items
  • review_output_path: .bmad/reviews/{doc_name}-review-{perspective}.md

Review checklists by perspective:

PM Review Checklist:

• All user personas identified and addressed
• User stories follow correct format (As a... I want... So that...)
• Acceptance criteria are specific, measurable, testable
• Scope is clearly defined (in-scope and out-of-scope)
• Priority levels are assigned and justified
• Dependencies are identified
• Success metrics defined

Architect Review Checklist:

• Technology choices are justified
• Security considerations addressed
• Scalability approach defined
• Data model is appropriate
• API design follows best practices
• Error handling strategy defined
• Performance requirements addressed
• Integration points documented

Developer Review Checklist:

• Enough detail to begin implementation
• No ambiguous requirements
• Edge cases identified
• Testing strategy clear
• API contracts fully specified
• Database migrations clear
• Third-party integrations documented
• No conflicting requirements

Scrum Master Review Checklist:

• Stories follow INVEST criteria
• Story points are reasonable (no >8 point stories)
• Dependencies clearly mapped
• Sprint capacity is realistic
• Priority order makes sense
• Acceptance criteria are testable
• Definition of Done is clear

Part 3: Monitor & Collect Reviews#

Monitor reviewer progress — bounded. "everyone finished" is not the only exit.

1. Poll task status (every interval, not continuously):

       Call TaskList
   Display: {reporting}/{reporting_target} reviewers reporting · elapsed {t} / cap 20m
   

   reporting counts only reviewers whose output file passed step 2. It is not the count of tasks marked completed.

2. On reviewer completion — verify before counting it (tri-state):

   • reporting ← the review document exists at review_output_path and contains all required sections (Overall Assessment, Strengths, Issues, Recommendations) and its Overall Assessment parses to one of Pass | Conditional Pass | Fail.
   • Missing file, missing section, or an unparseable assessment ⇒ undetermined, and undetermined is not a pass (plugins/cc-dev/rules/orchestration-graph.md → "Gate Contract — verdict 는 tri-state 다"). Mark that reviewer INCOMPLETE, exclude it from reporting, and record it durably in .bmad/reviews/{doc_name}-review-deferred.md. A completed task with an empty review file must never be read as "nothing to fix" (fail-open type nothing-to-check pass, same document → "이름 붙은 fail-open 5형").

3. On reviewer failure or stall:

   • Failure ⇒ mark FAILED; no activity (task status, output file mtime, file size) for stallWindow ⇒ mark STALLED. Both are terminal and both are excluded from reporting.
   • Record every exclusion durably in .bmad/reviews/{doc_name}-review-deferred.md (perspective, terminal state, reported blocker, the /cc-product:review --persona {persona} command that re-runs it). Console output is not durable.
   • Continue monitoring the remaining reviewers — one reviewer must not halt the panel — but reporting_target stays fixed, so the shrunken panel is visible to Part 4's consensus rule instead of silently becoming the whole panel.

4. Display progress (the panel size is asserted, never assumed):

       Review Progress (poll #6, t+3m / cap 20m):
   Reviewers reporting: 2/3 (Developer: FAILED — excluded)
   
   PM Review: ✓ Complete
     Assessment: Conditional Pass (2 issues)
     Output: .bmad/reviews/{doc_name}-review-pm.md
   
   Architect Review: ✓ Complete
     Assessment: Pass (1 minor issue)
     Output: .bmad/reviews/{doc_name}-review-architect.md
   
   Developer Review: ⛔ FAILED — excluded from consensus
     Recorded: .bmad/reviews/{doc_name}-review-deferred.md
     Re-run: /cc-product:review --persona flutter-developer
   

Loop contract L-TR-poll (team-review.progress-poll) — 7 fields per plugins/cc-dev/rules/orchestration-graph.md → "Loop Contract — 필수 7 필드". Values live here, not there.

inv:      reporting_target is fixed at Part 1 and unchanged for the whole poll · a reviewer
          already marked FAILED | STALLED | INCOMPLETE is never counted as pending again ·
          reviewers write only their own review_output_path; the Lead writes the deferred log
prog:     remainingWallClock = cap - elapsed, strictly decreasing every poll ·
          pendingReviewers is non-increasing (no reviewer is ever spawned mid-poll)
          no-prog: if one reviewer ' s task status, output file mtime and size are all unchanged
          for stallWindow, stop spending budget on that wait and settle it as STALLED
term:     pendingReviewers == 0 — every reviewer is reporting | INCOMPLETE | FAILED | STALLED
          (all four terminal).  " repeat until the reviews look good "   is not a term:
budget:   interval 30s · per-reviewer stallWindow 5 min · run-wide wall-clock cap 20 min
          (= the 5-10 min stated Duration × 2; sizing SoT
          plugins/cc-dev/skills/job-timeout-budget/SKILL.md)
          no outer re-entry: re-running the command is a new run with a fresh budget
exhaust:  at the cap, mark every still-pending reviewer STALLED, exclude them from reporting,
          record them in the deferred log, and hand the reduced panel to Part 4 — where a
          reduced panel caps the consensus at Conditional Pass (row 3) and reporting == 0
          emits NO consensus (row 0). Never wait silently, never count an unfinished review.
          Escalation ladder: plugins/cc-dev/agents/sequential-workflow.md
           " Stall Budget — 3-Rung Ladder "   (do not invent a new one)
resume:   the review files on disk are the position — on re-entry the Lead re-derives progress by
          globbing .bmad/reviews/{doc_name}-review-*.md and re-running step 2 on each, plus
          TaskList and the deferred log. An in-session counter is not state (it does not survive
          /clear). Re-deriving is idempotent; already-excluded reviewers are not revived.
log:      one line per poll:  " poll#6 (t+3m): reporting 2/3 · pending 0 · failed 1 "   +
          a durable entry in .bmad/reviews/{doc_name}-review-deferred.md for every reviewer
          dropped, with its terminal state and re-run command

If the wait is delegated to helpers.md#Collect-Team-Results (contract L-CTR — the same barrier), call it with this site's values (poll_interval 30s, wall_clock_cap 20 min); the helper takes them as input, so no second set of numbers exists. Delegation does not move the accounting — reporting (step 2), the exclusions (step 3) and the panel line stay with the Lead, because a delegated loop is still this loop (plugins/cc-dev/rules/orchestration-graph.md → "Loop Contract — 필수 7 필드", 위임된 루프도 루프다).

Part 4: Integrated Review Summary#

Barrier — nothing in this Part runs until L-TR-poll terminates, i.e. every reviewer in the panel is reporting | INCOMPLETE | FAILED | STALLED. mode:barrier, because: the consensus verdict is a cross-item comparison over the whole panel — one computed while a reviewer is still writing expires the moment it is produced (the justification requirement for any barrier is in plugins/cc-dev/rules/orchestration-graph.md → "barrier(= mode:barrier)가 정당한 자리"). Terminating is not the same as succeeding: the barrier closing with reporting < reporting_target is normal, and the consensus rule below is what makes that visible.

1. Read all review documents that passed Part 3 step 2 (reporting set only)

2. Build integrated summary:

# Integrated Review: {document_name}

**Document:** {document_path}
**Type:** {document_type}
**Reviewed:** {date}
**Reviewers reporting:** {reporting}/{reporting_target} (excluded: none | {perspective}: {FAILED/STALLED/INCOMPLETE/DEFERRED}, ...)
**Substrate:** {Agent Teams | sequential fallback (Agent Teams unavailable)}

---

## Overall Assessment

| Reviewer | Assessment | Critical | Major | Minor |
|----------|-----------|----------|-------|-------|
| PM | {Pass/Conditional/Fail} | {count} | {count} | {count} |
| Architect | {Pass/Conditional/Fail} | {count} | {count} | {count} |
| Developer | MISSING ({FAILED/STALLED/INCOMPLETE/DEFERRED}) | — | — | — |

Every panel member gets a row. A MISSING row is never omitted and its counts stay `—`, never `0`
(a missing review is not a clean review).

**Consensus:** {Pass / Conditional Pass / Needs Revision}   ← computed by the rule below, not written freehand
**Consensus ceiling:** {none | Conditional Pass — panel incomplete ({reporting}/{reporting_target})}

---

## Critical Issues (Must Fix)

1. [{Reviewer}] {Issue description}
   - Impact: {why this matters}
   - Suggestion: {how to fix}

---

## Major Issues (Should Fix)

1. [{Reviewer}] {Issue description}
   - Suggestion: {how to fix}

---

## Minor Issues (Consider)

1. [{Reviewer}] {Issue description}

---

## Strengths (Consensus)

- {Strength noted by multiple reviewers}
- {Another shared strength}

---

## Recommendations

### High Priority
- {Recommendation from critical/major issues}

### Medium Priority
- {Recommendation from major/minor issues}

### Low Priority
- {Nice-to-have improvements}

---

## Individual Reviews

- PM: .bmad/reviews/{doc_name}-review-pm.md
- Architect: .bmad/reviews/{doc_name}-review-architect.md
- Developer: MISSING — .bmad/reviews/{doc_name}-review-deferred.md (re-run: /cc-product:review --persona flutter-developer)

3. Compute the consensus verdict — precedence table, first match wins. Consensus is derived, never free-written. Same shape as commands/plan-technical-review.md → Phase 3 "최종 판정 기준" (conditions in precedence order, one verdict out), applied to the panel instead of to three fixed axes.

   #	Condition (evaluated top-down, first match wins)	Consensus
   0	reporting == 0 — no review passed Part 3 step 2	NOT COMPUTED — emit no verdict; report the empty panel and the re-run commands
   1	Any reporting reviewer raised ≥1 Critical issue	Needs Revision
   2	Any reporting reviewer's own Overall Assessment is Fail	Needs Revision
   3	reporting < reporting_target — any panel member is FAILED / STALLED / INCOMPLETE / DEFERRED	Conditional Pass — this is a ceiling: Pass is unreachable this run
   4	reporting == reporting_target and every assessment is Pass	Pass
   5	Otherwise (Major/Minor issues only, or a Conditional Pass among them)	Conditional Pass

   • Row order is load-bearing. Rows 1-2 precede row 3 so a missing reviewer can never mask a Critical raised by someone who did report; row 3 precedes row 4 so a shrunken panel can never reach Pass. Row 4 is the only path to Pass, and it requires the panel to be complete.
   • undetermined is not a pass (plugins/cc-dev/rules/orchestration-graph.md → "Gate Contract — verdict 는 tri-state 다"): an unparseable or absent assessment was already excluded from reporting in Part 3 step 2, so it lands on row 3, not on row 4.
   • Row 0 and row 3 exist because "note the failure and continue" used to let a 3-reviewer panel shrink to 1 — or to 0 — and still emit a consensus, which is the empty-set pass / nothing-to-check pass pair in plugins/cc-dev/rules/orchestration-graph.md → "이름 붙은 fail-open 5형".
   • Record the matched row number in the integrated summary (Consensus: Conditional Pass (rule 3 — panel 2/3)) so the verdict is auditable.

4. Save integrated summary:

   • Path: .bmad/reviews/{doc_name}-review-integrated.md

5. Display summary to user:

       ✓ Team Review Complete!
   
   Document: {document_path}
   Reviewers reporting: 2/3 (Developer: FAILED — excluded)
   Consensus: Conditional Pass (rule 3 — panel incomplete, Pass unreachable this run)
   
   Issues Found:
     Critical: {count}
     Major: {count}
     Minor: {count}
   
   Strengths: {count} consensus strengths identified
   
   Review Files:
     .bmad/reviews/{doc_name}-review-pm.md
     .bmad/reviews/{doc_name}-review-architect.md
     .bmad/reviews/{doc_name}-review-deferred.md      ← excluded/deferred reviewers + re-run commands
     .bmad/reviews/{doc_name}-review-integrated.md  ← Start here
   
   Next Steps:
     1. Read integrated review: .bmad/reviews/{doc_name}-review-integrated.md
     2. Address critical issues first
     3. Recover the missing perspectives (lifts the Conditional Pass ceiling):
        /cc-product:review --persona flutter-developer  " {document_path} 검토 " 
      4. Revise document and re-review if needed
   

Helper References#

• Load config: helpers.md#Combined-Config-Load
• Check Agent Teams: helpers.md#Check-Agent-Teams-Available
• Spawn teammate: helpers.md#Spawn-BMAD-Teammate
• Create team tasks: helpers.md#Create-Team-Task-List
• Collect results: helpers.md#Collect-Team-Results (barrier contract L-CTR; call it with this file's poll_interval / wall_clock_cap)
• Notation, loop contract (7 fields), gate tri-state, substrate matrix, fan-out obligations: plugins/cc-dev/rules/orchestration-graph.md — cited here, never restated. Per-loop values (L-TR-poll) live at the loop's own site in Part 3.
• Sequential route / Fallback Principle / tier: → model mapping: plugins/cc-dev/skills/agent-teams/SKILL.md
• budget: number sizing: plugins/cc-dev/skills/job-timeout-budget/SKILL.md
• Stall ladder for exhaust:: plugins/cc-dev/agents/sequential-workflow.md

Notes for LLMs#

• ALWAYS check Agent Teams availability first (Pre-Flight step 2-3)
• If teams are not available, reroute to the sequential route (/cc-product:review, one persona per invocation) and report it — do NOT stop. Same perspectives, same output paths, same consensus rule; only slower (plugins/cc-dev/skills/agent-teams/SKILL.md → "Fallback Principle")
• Every spawn declares effort_tier: standard (Part 2 step 3). Unset = silent inherit = a reporting_target× multiplier, never a default
• The panel is fixed in Part 1 at width: min(selected, max_teammates); capped perspectives go to .bmad/reviews/{doc_name}-review-deferred.md. Never truncate silently, never widen the panel later
• Each reviewer writes to a UNIQUE file path — no conflicts possible
• Reviewers must NOT modify the document being reviewed
• Sprint-status.yaml is NOT modified by this workflow
• Document type detection drives reviewer perspective selection
• Integrated summary should highlight cross-reviewer consensus and conflicts
• The poll is bounded (L-TR-poll): interval 30s, stallWindow 5 min, cap 20 min. At the cap, pending reviewers become STALLED and are excluded — never wait silently
• If a reviewer fails, stalls, or returns an incomplete/unparseable review: exclude it from reporting, keep reporting_target fixed, record it durably in the deferred log, and print Reviewers reporting: {reporting}/{reporting_target} next to every consensus. A shrunken panel must be asserted, not assumed
• Consensus is computed by the Part 4 precedence table, never free-written. Any Critical or any Fail ⇒ Needs Revision; a missing reviewer caps the run at Conditional Pass (Pass unreachable); reporting == 0 ⇒ NOT COMPUTED. Record the matched row number
• Review output directory (.bmad/reviews/) is created if it doesn't exist

Remember: Multi-perspective review catches issues that single-perspective review misses. The PM sees requirement gaps, the Architect sees technical risks, and the Developer sees implementation ambiguities. Together they provide comprehensive quality assurance.