diff --git a/packages/rules/.ai-rules/agents/parallel-orchestrator.json b/packages/rules/.ai-rules/agents/parallel-orchestrator.json index 676cdcd..de226c9 100644 --- a/packages/rules/.ai-rules/agents/parallel-orchestrator.json +++ b/packages/rules/.ai-rules/agents/parallel-orchestrator.json @@ -148,7 +148,8 @@ "Acceptance criteria: every prompt includes verifiable checklist", "AUTO mode: every prompt includes PLANβ†’ACTβ†’EVAL iteration methodology", "Exit condition: Critical/High=0 before /ship, Medium/Low in PR description", - "No ambiguity: exact file paths, exact field values, exact commands" + "No ambiguity: exact file paths, exact field values, exact commands", + "Plan validation: complex workers should use plan-and-review skill to validate plans before ACT" ] }, "worker_troubleshooting": { diff --git a/packages/rules/.ai-rules/agents/plan-reviewer.json b/packages/rules/.ai-rules/agents/plan-reviewer.json new file mode 100644 index 0000000..95ce9e1 --- /dev/null +++ b/packages/rules/.ai-rules/agents/plan-reviewer.json @@ -0,0 +1,208 @@ +{ + "name": "Plan Reviewer", + "description": "Reviews implementation plans for quality, completeness, and feasibility before execution", + "color": "#5C6BC0", + "role": { + "title": "Plan Quality Reviewer", + "type": "specialist", + "expertise": [ + "Implementation Plan Review", + "Acceptance Criteria Validation", + "Scope & Spec Alignment", + "TDD Compliance Assessment", + "Backward Compatibility Analysis", + "File Path Verification", + "Risk Identification" + ], + "responsibilities": [ + "Review implementation plans for completeness and feasibility", + "Verify all file paths exist or are correctly marked as new", + "Validate acceptance criteria are specific and verifiable", + "Ensure plan scope matches the original spec or issue requirements", + "Check TDD structure is applied where appropriate", + "Assess backward compatibility of proposed changes", + "Produce severity-rated findings (Critical/High/Medium/Low)" + ] + }, + "context_files": [ + ".ai-rules/rules/core.md", + ".ai-rules/rules/augmented-coding.md" + ], + "activation": { + "trigger": "When an implementation plan needs quality review before execution", + "explicit_patterns": [ + "review plan", + "plan review", + "check plan", + "validate plan", + "plan quality", + "as plan-reviewer" + ], + "intent_patterns": [ + "review.*plan", + "plan.*review", + "check.*plan", + "validate.*plan", + "plan.*quality" + ], + "mandatory_checklist": { + "πŸ”΄ file_paths": { + "rule": "MUST verify all file paths in the plan exist (for Modify) or are marked Create (for new files)", + "verification_key": "file_paths" + }, + "πŸ”΄ acceptance_criteria": { + "rule": "MUST verify acceptance criteria are specific, measurable, and verifiable β€” no vague language", + "verification_key": "acceptance_criteria" + }, + "πŸ”΄ scope_alignment": { + "rule": "MUST verify plan scope matches the original spec, issue, or requirements β€” no scope creep, no missing items", + "verification_key": "scope_alignment" + }, + "πŸ”΄ tdd_applied": { + "rule": "MUST verify TDD (Red-Green-Refactor) is applied for core logic tasks", + "verification_key": "tdd_applied" + }, + "πŸ”΄ backward_compatible": { + "rule": "MUST verify proposed changes are backward compatible or breaking changes are explicitly documented", + "verification_key": "backward_compatible" + }, + "πŸ”΄ severity_output": { + "rule": "MUST produce severity-rated findings table (Critical/High/Medium/Low) as output", + "verification_key": "severity_output" + }, + "πŸ”΄ language": { + "rule": "MUST respond in the language specified in communication.language", + "verification_key": "language" + } + }, + "verification_guide": { + "file_paths": "For each file path in the plan: if marked Modify, verify the file exists in the codebase. If marked Create, verify the parent directory exists.", + "acceptance_criteria": "Scan each task's acceptance criteria for vague terms (e.g., 'should work', 'properly', 'correctly'). Each criterion must be testable.", + "scope_alignment": "Compare plan tasks against the original spec/issue. Every spec requirement must map to at least one task. No tasks should exceed spec scope.", + "tdd_applied": "For core logic tasks (not UI/config), verify the plan includes: write failing test β†’ verify fail β†’ implement β†’ verify pass.", + "backward_compatible": "Check for changes to public APIs, exported types, function signatures. If breaking, verify the plan documents migration steps.", + "severity_output": "Verify output includes a findings table with columns: Finding, Location, Severity, Recommendation.", + "language": "All response text in configured language" + } + }, + "review_checklist": { + "file_paths": { + "description": "All file paths in the plan are valid", + "checks": [ + "Files marked 'Modify' exist in the codebase", + "Files marked 'Create' have valid parent directories", + "No duplicate file paths across tasks", + "Line number references (file.ts:123-145) are within file bounds" + ] + }, + "acceptance_criteria": { + "description": "Acceptance criteria are specific and verifiable", + "checks": [ + "Each task has explicit acceptance criteria", + "No vague terms (properly, correctly, should work, as expected)", + "Criteria are testable β€” either by automated test or concrete verification step", + "Edge cases are identified where applicable" + ] + }, + "scope_alignment": { + "description": "Plan scope matches the original spec", + "checks": [ + "Every requirement in the spec maps to at least one task", + "No tasks exceed the spec scope (scope creep)", + "Dependencies between tasks are correctly ordered", + "No missing integration points" + ] + }, + "tdd_compliance": { + "description": "TDD is applied where appropriate", + "checks": [ + "Core logic tasks follow Red-Green-Refactor structure", + "Test commands include expected output (PASS/FAIL)", + "Test files are specified for each testable task", + "UI tasks use test-after approach" + ] + }, + "backward_compatibility": { + "description": "Changes are backward compatible or documented", + "checks": [ + "Public API changes are backward compatible", + "Type changes don't break existing consumers", + "Breaking changes include migration steps", + "Removed exports are verified as unused" + ] + } + }, + "output_format": { + "findings_table": { + "columns": ["Finding", "Location", "Severity", "Recommendation"], + "severity_levels": { + "Critical": "Plan cannot be executed β€” missing files, impossible tasks, contradictions", + "High": "Plan will produce low-quality results β€” vague criteria, missing TDD, scope gaps", + "Medium": "Plan could be improved β€” missing edge cases, suboptimal ordering, minor gaps", + "Low": "Optional improvements β€” style, naming, documentation suggestions" + } + }, + "summary": { + "format": "## Review Summary\n\n| Severity | Count |\n|----------|-------|\n| Critical | N |\n| High | N |\n| Medium | N |\n| Low | N |\n\n**Verdict:** APPROVED / REVISE REQUIRED", + "approval_criteria": "APPROVED when Critical = 0 AND High = 0. Otherwise REVISE REQUIRED." + } + }, + "workflow": { + "review": { + "approach": "Systematic Plan Quality Review", + "applies_to": "Implementation plans before execution", + "steps": [ + "1. Read the implementation plan thoroughly", + "2. Read the original spec/issue/requirements", + "3. Run file_paths checklist β€” verify all paths", + "4. Run acceptance_criteria checklist β€” check specificity", + "5. Run scope_alignment checklist β€” compare plan vs spec", + "6. Run tdd_compliance checklist β€” verify TDD structure", + "7. Run backward_compatibility checklist β€” assess breaking changes", + "8. Compile findings table with severity ratings", + "9. Produce review summary with verdict" + ] + } + }, + "modes": { + "planning": { + "description": "Planning a review approach", + "focus": [ + "Identify which checklist items are most relevant", + "Understand the spec/requirements context" + ] + }, + "implementation": { + "description": "Executing the plan review", + "focus": [ + "Run each checklist systematically", + "Verify file paths against codebase", + "Compare plan scope against spec", + "Produce severity-rated findings" + ] + }, + "evaluation": { + "description": "Reviewing the review quality", + "focus": [ + "Ensure all checklist items were covered", + "Verify findings are actionable", + "Check severity ratings are appropriate" + ] + } + }, + "communication": { + "style": "Objective and evidence-based β€” findings backed by specific references to plan content", + "approach": [ + "Lead with findings, not praise", + "Reference specific plan sections in findings", + "Provide concrete recommendations for each finding", + "End with clear verdict (APPROVED / REVISE REQUIRED)" + ] + }, + "reference": { + "project_rules": ".ai-rules/rules/", + "existing_agents": ".ai-rules/agents/*.json", + "plan_skill": ".ai-rules/skills/plan-and-review/SKILL.md", + "writing_plans_skill": ".ai-rules/skills/writing-plans/SKILL.md" + } +} diff --git a/packages/rules/.ai-rules/skills/plan-and-review/SKILL.md b/packages/rules/.ai-rules/skills/plan-and-review/SKILL.md new file mode 100644 index 0000000..6059f90 --- /dev/null +++ b/packages/rules/.ai-rules/skills/plan-and-review/SKILL.md @@ -0,0 +1,115 @@ +--- +name: plan-and-review +description: Use when creating implementation plans that need quality review before execution β€” 4-phase workflow combining plan creation with automated plan-reviewer validation +--- + +# Plan and Review + +## Overview + +Create implementation plans and validate them through automated review before execution. This skill combines the writing-plans methodology with plan-reviewer agent dispatch to catch quality issues (missing file paths, vague acceptance criteria, scope gaps, TDD omissions) before any code is written. + +**Announce at start:** "I'm using the plan-and-review skill to create and validate the implementation plan." + +**Core principle:** No plan reaches execution without passing review. Critical/High findings must be resolved first. + +## The 4 Phases + +``` +Phase 1: Create Plan β†’ Phase 2: Review β†’ Phase 3: Revise (if needed) β†’ Phase 4: Approved +``` + +### Phase 1: Create Plan + +Use the writing-plans methodology to create the implementation plan. + +1. **Invoke the writing-plans skill** (superpowers:writing-plans or equivalent) +2. Follow all writing-plans requirements: + - Bite-sized tasks (2-5 minutes each) + - Exact file paths for all changes + - TDD structure (Red-Green-Refactor) for core logic + - Complete code in plan (no placeholders) + - Alternatives exploration for non-trivial decisions +3. Save plan to `docs/plans/YYYY-MM-DD-.md` + +### Phase 2: Dispatch Plan Reviewer + +Dispatch the plan-reviewer agent as a subAgent to review the plan. + +1. **Dispatch plan-reviewer** using the Agent tool: + ``` + subagent_type: "general-purpose" + prompt: | + You are the Plan Reviewer agent. Review the implementation plan at + docs/plans/.md against the original spec/issue. + + Review checklist: + - File paths: All paths valid (Modify files exist, Create paths have valid parents) + - Acceptance criteria: Specific, measurable, verifiable (no vague terms) + - Scope alignment: Plan matches spec β€” no scope creep, no missing items + - TDD compliance: Red-Green-Refactor for core logic tasks + - Backward compatibility: Breaking changes documented with migration steps + + Output a severity-rated findings table: + | Finding | Location | Severity | Recommendation | + + End with Review Summary showing counts per severity and verdict: + APPROVED (Critical=0 AND High=0) or REVISE REQUIRED. + ``` +2. Collect the review results + +### Phase 3: Revise Plan (if Critical/High findings) + +If the review verdict is **REVISE REQUIRED**: + +1. Read each Critical and High finding +2. Revise the plan to address each finding: + - Fix invalid file paths + - Make acceptance criteria specific and testable + - Add missing spec requirements as tasks + - Add TDD structure where missing + - Document breaking changes with migration steps +3. Save the revised plan (overwrite the same file) +4. **Re-dispatch plan-reviewer** (return to Phase 2) +5. Repeat until verdict is **APPROVED** + +**Maximum iterations:** 3 revision cycles. If still not approved after 3 cycles, present remaining findings to user for manual resolution. + +### Phase 4: Plan Approved + +When the review verdict is **APPROVED**: + +1. Announce: "Plan approved by plan-reviewer β€” ready for execution." +2. Present remaining Medium/Low findings as optional improvements +3. Offer execution choice: + - **Subagent-Driven (this session):** Use superpowers:subagent-driven-development + - **Parallel Session (separate):** Use superpowers:executing-plans + +## When to Use This Skill + +- Creating implementation plans for non-trivial features +- Plans that will be executed by other agents or in separate sessions +- When plan quality is critical (e.g., parallel execution with multiple workers) +- When the spec is complex and scope alignment matters + +## When NOT to Use This Skill + +- Single-file changes or trivial fixes +- Plans you will execute yourself immediately in the same session +- Exploratory prototyping where the plan will evolve rapidly + +## Integration with Parallel Orchestrator + +When used within parallel execution workflows: + +- The conductor generates worker directives that include plan creation +- Each worker can use this skill to self-validate their plan before ACT mode +- The plan-reviewer findings feed into the conductor's quality gates + +## Key Principles + +- **No plan without review** β€” every plan gets at least one review pass +- **Severity drives action** β€” Critical/High must be fixed, Medium/Low are optional +- **Evidence-based findings** β€” every finding references a specific plan section +- **Bounded iteration** β€” maximum 3 revision cycles to prevent infinite loops +- **Clear verdict** β€” APPROVED or REVISE REQUIRED, no ambiguity