Plan:docs/plans/add-research-agent-team.html Reviewed: 2026-06-08 13:51 UTC Reviewers: 7 (5 core + 2 UI-conditional) Verdict:Sound with Revisions
Executive Summary
The plan is sound with revisions. All 7 reviewers agree the design follows the proven review-plan Agent Team pattern and inserts cleanly into the existing pipeline as Step 0c with proper graceful degradation. However, the team identified three high-priority issues that should be resolved before implementation:
The dual-artifact redundancy between agent definition files and research-prompts.md — flagged by 5 of 7 reviewers — needs a single source of truth
The complexity auto-detection heuristic is underspecified, leaving the most common invocation path (no flags) with an undefined branch
The test infrastructure is incomplete — test files are declared but no runner, framework, or directory creation steps exist
All three issues have been addressed in the inline edits applied to the source plan.
Role-by-Role Findings
Architecture Review
Fit: Follows the established Agent Team pattern with well-scoped component boundaries and proper graceful degradation.
medium — Dual-artifact redundancy between agent definitions and research-prompts.md; recommends agent definitions as single source of truth
medium — Context injection is implicit and unstructured; Research Brief handoff between 0c and Step 1 has no defined serialization boundary
medium — Complexity auto-detection heuristic underspecified; no programmatic detection logic defined
low — Unverified TeamCreate/TeamDelete tool names
Completeness Review
Completeness: Well-structured with 12 steps covering all named files, but gaps could cause implementation friction.
high — Auto-detection heuristic buried in Unresolved Question, not in Step 6
high — Test files declared but no creation steps exist in Steps section
high — Two Unresolved Questions directly affect Step 6 implementation
medium — No directory creation steps for agents/ and references/
medium — No step to read existing SKILL.md before editing
medium — No test runner specified for .ts test files
Testability Review
Test coverage: Adequate for Tier 1, but critical paths lack automated coverage.
high — No test for auto-detection heuristic
high — Objective-verification test is manual CLI invocation, not automated
high — No test runner or framework specified
medium — No test for conditional researcher spawning based on UI signals
medium — Integration test doesn’t specify env var manipulation
Risk Review
Risk level: Medium overall.
high — No partial-failure handling for researcher agents; synthesis blocks if one hangs
high — Unverified tool names in allowed-tools could cause silent permission failures
medium — Dual-artifact prompt drift risk
medium — No token budget ceiling for 4–6 parallel researchers
medium — Experimental flag dependency; silent removal could break feature
Conventions Review
Fit: Closely follows established project patterns.
medium — Redundant prompt storage conflicts with review-plan single-source pattern
medium — Test file placement in non-existent tests/plan-agent/ directory
medium — allowed-tools casing for TeamCreate/TeamDelete needs verification
UX Review
User fit: Well-structured plan, but research phase UX lacks progress feedback and auto-detection predictability.
high — No progress indication during research phase; users face silent wait
high — Auto-detection UX undefined; users cannot predict when research spawns
medium — Graceful degradation is too quiet when --research was explicitly requested
low — Research Brief hidden by default in collapsed <details>
low — No empty-state handling for partial researcher failure in the Brief
Accessibility Review
A11y compliance: Largely WCAG 2.1 AA compliant, but medium-severity gaps in the HTML template.
medium — status-badge lacks accessible label tying it to plan title
medium — <details>/<summary> marker removal may break VoiceOver
medium — Disabled checkboxes removed from tab order without aria-disabled
medium — compare-grid uses divs instead of semantic table
medium — Pulse-dot animation missing prefers-reduced-motion suppression
Agreements & Conflicts
Confirmed Concerns (multiple reviewers agree)
Dual-artifact redundancy — 5/7 reviewers (architecture, completeness, risk, conventions, accessibility). Consensus: use agent definitions as single source of truth.