Meta: plan-reviewer — orchestrator for implementation plan review

[dapi]

Summary

Create plan-reviewer plugin with /review-plan command — an orchestrator that reviews implementation plans before execution, similar to how /spec-review orchestrates spec analysis.

Pipeline position:

/spec-review → writing-plans → /review-plan → executing-plans → code-reviewer
       ↑                            ↑
  validates SPEC             validates PLAN

Motivation

Source: eTechLead stream — AI-Ready Codebase

Workflow Максима:

1. Спека → 2. Ревью спеки → 3. Разбивка на стейджи → 4. Grounding на кодовую базу → 5. Feasibility check → 6. Имплементация

Steps 4-5 сейчас не покрыты. writing-plans создаёт план, executing-plans выполняет, но между ними нет валидации.

Architecture

Один плагин plan-reviewer/ с агентами внутри. Sub-issues #32 и #33 — это агенты, не отдельные плагины.

plan-reviewer/
  .claude-plugin/plugin.json
  agents/
    plan-grounder.md      (#32)
    plan-coverage.md      (#33)
    plan-structure.md
  skills/
    review-plan/SKILL.md
  commands/
    review-plan.md

Command interface

/review-plan docs/plans/2026-03-09-feature.md [--spec <spec-url>] [--reground]

• --spec <url> — включает coverage check (план ↔ спека)
• --reground — re-grounding: проверяет только шаги, затронутые git changes с даты плана

Orchestration flow

/review-plan plan.md [--spec url]
       |
       v
  Parse plan (writing-plans format)
       |
       +---> plan-grounder     ALWAYS   — grounding against codebase
       +---> plan-structure    ALWAYS   — TDD, atomicity, dependency order
       +---> plan-coverage     IF --spec — traceability plan <-> spec
       |
       v                    (parallel)
  Aggregate results
       |
       v
  Unified report (per-step OK/WARN/FAIL + summary score)
       |
       v
  Gate check: есть FAIL?
       |
    NO |          YES
       v            v
    PASS       Show findings + offer:
               1. Fix and re-run
               2. Accept with warnings
               3. Cancel

Classifier не нужен — всего 2-3 агента (vs 11 в spec-review). Grounder и structure запускаются всегда, coverage — по флагу. Нет смысла тратить токены на классификацию.

Supported plan formats (MVP)

MVP поддерживает только формат writing-plans:

### Task N: [Component Name]
**Files:**
- Create: `path/to/file.py`
- Modify: `path/to/existing.py:123-145`
- Test: `tests/path/to/test.py`
**Step 1: ...**
**Step 2: ...**

Свободный формат, Google Docs, Notion — out of scope для MVP. Можно добавить позже через парсер-адаптеры.

Sub-issues (agents)

• New plugin: plan-grounder — ground implementation plans against real codebase #32 — plan-grounder: ground plan against real codebase (paths, APIs, line numbers, conflicts, staleness)
• New plugin: plan-coverage — verify plan covers all spec requirements #33 — plan-coverage: verify plan covers all spec requirements (traceability matrix)
• plan-structure (inline, без отдельного issue): TDD cycle, step atomicity, dependency order, commit points

Output format

Per-step report с severity levels:

/review-plan docs/plans/2026-03-09-auth.md --spec #45

PLAN REVIEW: 2026-03-09-auth.md
================================================================

Task 1: Setup DB schema                              PASS
  GRD-1  Modify: src/models/user.py:45-60            OK    file exists, lines match
  GRD-2  Create: src/models/payment.py               OK    directory exists
  STR-1  TDD cycle                                   OK    test before implementation

Task 4: Refactor auth middleware                      FAIL
  GRD-3  Modify: src/middleware/auth.py:12-30         FAIL  lines 12-30 are imports, not auth logic
  GRD-4  API: verify_token()                          FAIL  actual name is verify_jwt_token()
  GRD-5  Conflict: Task 2 also modifies auth.py       WARN  potential merge conflict
  STR-2  Step 3 references output of Step 5           FAIL  dependency order violation

Coverage (--spec #45):
  COV-1  R1: User login        -> Task 2, 3          COVERED
  COV-2  R3: 2FA support       -> (none)              MISSING
  COV-3  Task 6: Refactor      -> (no spec req)       ORPHAN

================================================================
SUMMARY: 8/10 tasks grounded | 2 FAIL, 1 WARN | Coverage: 85%
VERDICT: FAIL — fix GRD-3, GRD-4, STR-2 before execution

Options:
  1. Fix plan and re-run /review-plan
  2. Accept with warnings
  3. Cancel

Severity levels:

• FAIL — plan cannot be executed as written, must fix
• WARN — potential issue, can proceed with caution
• OK — verified, no issues

Prefixes: GRD-* (grounder), STR-* (structure), COV-* (coverage)

Re-grounding (stale plan detection)

/review-plan docs/plans/2026-03-09-auth.md --reground

1. Parse plan creation date from filename or frontmatter
2. git log --since=<plan-date> --name-only — find changed files
3. Cross-reference with plan's file list
4. Re-ground only affected tasks
5. Report: "3 files changed since plan was written, 2 tasks affected"

Acceptance criteria

• Plugin plan-reviewer/ follows marketplace conventions
• Command /review-plan accepts plan file path
• --spec flag enables coverage check via plan-coverage agent
• --reground flag enables stale plan detection
• plan-grounder agent validates paths, APIs, line numbers, conflicts (New plugin: plan-grounder — ground implementation plans against real codebase #32)
• plan-coverage agent maps plan <-> spec bidirectionally (New plugin: plan-coverage — verify plan covers all spec requirements #33)
• plan-structure checks TDD cycle, atomicity, dependency order
• Agents run in parallel where possible
• Unified report with per-step OK/WARN/FAIL and summary
• Gate check: FAIL findings block with options (fix/accept/cancel)
• MVP supports writing-plans format only
• Skill auto-triggers on "review plan", "ground plan", "проверь план"
• TRIGGER_EXAMPLES.md with 20+ positive, 5+ negative examples
• Quality score >=75/100 from review_skill_triggers.sh