# Expert Review Piece # Review piece with Architecture, Frontend, Security, and QA experts # # Flow: # plan -> implement -> ai_review -> reviewers (parallel) -> supervise -> COMPLETE # ↓ ├─ arch-review ↓ # ai_fix ├─ frontend-review fix_supervisor # ├─ security-review # └─ qa-review # any("needs_fix") → fix → reviewers # # AI review runs immediately after implementation to catch AI-specific issues early, # before expert reviews begin. # # Boilerplate sections (Piece Context, User Request, Previous Response, # Additional User Inputs, Instructions heading) are auto-injected by buildInstruction(). # Only movement-specific content belongs in instruction_template. # # Template Variables (available in instruction_template): # {iteration} - Piece-wide turn count (total movements executed across all agents) # {max_iterations} - Maximum iterations allowed for the piece # {movement_iteration} - Per-movement iteration count (how many times THIS movement has been executed) # {previous_response} - Output from the previous movement (only when pass_previous_response: true) # {report_dir} - Report directory name (e.g., "20250126-143052-task-summary") # # Movement-level Fields: # report: - Report file(s) for the movement (auto-injected as Report File/Files in Piece Context) # Single: report: 00-plan.md # Multiple: report: # - Scope: 01-coder-scope.md # - Decisions: 02-coder-decisions.md name: expert-hybrid-codex description: Architecture, Frontend, Security, QA Expert Review max_iterations: 30 stances: coding: ../stances/coding.md review: ../stances/review.md testing: ../stances/testing.md personas: planner: ../personas/planner.md coder: ../personas/coder.md ai-antipattern-reviewer: ../personas/ai-antipattern-reviewer.md architecture-reviewer: ../personas/architecture-reviewer.md frontend-reviewer: ../personas/frontend-reviewer.md security-reviewer: ../personas/security-reviewer.md qa-reviewer: ../personas/qa-reviewer.md expert-supervisor: ../personas/expert-supervisor.md instructions: plan: ../instructions/plan.md implement: ../instructions/implement.md ai-review: ../instructions/ai-review.md ai-fix: ../instructions/ai-fix.md arbitrate: ../instructions/arbitrate.md review-arch: ../instructions/review-arch.md review-frontend: ../instructions/review-frontend.md review-security: ../instructions/review-security.md review-qa: ../instructions/review-qa.md fix: ../instructions/fix.md supervise: ../instructions/supervise.md fix-supervisor: ../instructions/fix-supervisor.md report_formats: plan: ../report-formats/plan.md ai-review: ../report-formats/ai-review.md architecture-review: ../report-formats/architecture-review.md frontend-review: ../report-formats/frontend-review.md security-review: ../report-formats/security-review.md qa-review: ../report-formats/qa-review.md validation: ../report-formats/validation.md summary: ../report-formats/summary.md initial_movement: plan movements: # =========================================== # Movement 0: Planning # =========================================== - name: plan edit: false persona: planner report: name: 00-plan.md format: plan allowed_tools: - Read - Glob - Grep - Bash - WebSearch - WebFetch instruction: plan rules: - condition: Task analysis and planning is complete next: implement - condition: Requirements are unclear and planning cannot proceed next: ABORT # =========================================== # Movement 1: Implementation # =========================================== - name: implement edit: true persona: coder stance: - coding - testing provider: codex session: refresh report: - Scope: 01-coder-scope.md - Decisions: 02-coder-decisions.md allowed_tools: - Read - Glob - Grep - Edit - Write - Bash - WebSearch - WebFetch instruction: implement rules: - condition: Implementation is complete next: ai_review - condition: No implementation (report only) next: ai_review - condition: Cannot proceed with implementation next: ai_review - condition: User input required next: implement requires_user_input: true interactive_only: true # =========================================== # Movement 2: AI Review # =========================================== - name: ai_review edit: false persona: ai-antipattern-reviewer stance: review report: name: 03-ai-review.md format: ai-review allowed_tools: - Read - Glob - Grep - WebSearch - WebFetch instruction: ai-review rules: - condition: No AI-specific issues found next: reviewers - condition: AI-specific issues detected next: ai_fix - name: ai_fix edit: true persona: coder stance: - coding - testing provider: codex session: refresh allowed_tools: - Read - Glob - Grep - Edit - Write - Bash - WebSearch - WebFetch instruction: ai-fix rules: - condition: AI Reviewer's issues have been fixed next: ai_review - condition: No fix needed (verified target files/spec) next: ai_no_fix - condition: Unable to proceed with fixes next: ai_no_fix - name: ai_no_fix edit: false persona: architecture-reviewer stance: review allowed_tools: - Read - Glob - Grep rules: - condition: ai_review's findings are valid (fix required) next: ai_fix - condition: ai_fix's judgment is valid (no fix needed) next: reviewers instruction: arbitrate # =========================================== # Movement 3: Expert Reviews (Parallel) # =========================================== - name: reviewers parallel: - name: arch-review edit: false persona: architecture-reviewer stance: review report: name: 04-architect-review.md format: architecture-review allowed_tools: - Read - Glob - Grep - WebSearch - WebFetch rules: - condition: approved - condition: needs_fix instruction: review-arch - name: frontend-review edit: false persona: frontend-reviewer stance: review report: name: 05-frontend-review.md format: frontend-review allowed_tools: - Read - Glob - Grep - WebSearch - WebFetch rules: - condition: approved - condition: needs_fix instruction: review-frontend - name: security-review edit: false persona: security-reviewer stance: review report: name: 06-security-review.md format: security-review allowed_tools: - Read - Glob - Grep - WebSearch - WebFetch rules: - condition: approved - condition: needs_fix instruction: review-security - name: qa-review edit: false persona: qa-reviewer stance: review report: name: 07-qa-review.md format: qa-review allowed_tools: - Read - Glob - Grep - WebSearch - WebFetch rules: - condition: approved - condition: needs_fix instruction: review-qa rules: - condition: all("approved") next: supervise - condition: any("needs_fix") next: fix - name: fix edit: true persona: coder stance: - coding - testing provider: codex allowed_tools: - Read - Glob - Grep - Edit - Write - Bash - WebSearch - WebFetch permission_mode: edit rules: - condition: Fix complete next: reviewers - condition: Cannot proceed, insufficient info next: plan instruction: fix # =========================================== # Movement 4: Supervision # =========================================== - name: supervise edit: false persona: expert-supervisor stance: review report: - Validation: 08-supervisor-validation.md - Summary: summary.md allowed_tools: - Read - Glob - Grep - WebSearch - WebFetch instruction: supervise rules: - condition: All validations pass and ready to merge next: COMPLETE - condition: Issues detected during final review next: fix_supervisor - name: fix_supervisor edit: true persona: coder stance: - coding - testing provider: codex allowed_tools: - Read - Glob - Grep - Edit - Write - Bash - WebSearch - WebFetch instruction: fix-supervisor rules: - condition: Supervisor's issues have been fixed next: supervise - condition: Unable to proceed with fixes next: plan