feat(skills): add plan validation scripts to create-plan skill

.forge/skills/create-plan/README.md

@@ -0,0 +1,120 @@
+# Create Plan Skill
+
+Tools and scripts for creating and validating implementation plans.
+
+## Files
+
+- `SKILL.md` - Main skill instructions for AI agents
+- `validate-plan.sh` - Validates a single plan file
+- `validate-all-plans.sh` - Validates all plans in a directory
+
+## Validation Scripts
+
+### validate-plan.sh
+
+Validates the structure and content of a single plan file.
+
+**Usage:**
+```bash
+./.forge/skills/create-plan/validate-plan.sh plans/2025-11-27-example-v1.md
+```
+
+**Checks:**
+- ✓ Filename follows convention: `YYYY-MM-DD-task-name-vN.md`
+  - Year is reasonable (2020 to current year + 1)
+  - Month is valid (01-12)
+  - Day is valid (01-31)
+  - Task name is meaningful (not generic like "test", "task", "temp")
+  - Task name length is reasonable (5-60 characters)
+  - Version number is reasonable (not > 50)
+  - No uppercase letters or underscores (use lowercase and hyphens only)
+- ✓ File is in `plans/` directory
+- ✓ All required sections present:
+  - Main heading (`# Title`)
+  - `## Objective`
+  - `## Implementation Plan`
+  - `## Verification Criteria`
+  - `## Potential Risks and Mitigations`
+  - `## Alternative Approaches`
+- ✓ Implementation Plan uses checkbox format (`- [ ]`)
+- ✓ No numbered lists or plain bullets in Implementation Plan
+- ✓ No code blocks (` ``` `) in the plan
+- ✓ No code snippets (detects suspicious patterns)
+- ✓ No placeholder tasks (TODO, TBD, etc.)
+- ✓ **Task quality and density:**
+  - Task descriptions are descriptive (≥ 20 characters recommended)
+  - Average task length is substantial (30-200 chars recommended)
+  - No generic/vague descriptions ("implement feature", "fix bug", etc.)
+  - No duplicate or highly similar tasks
+  - Consistent and sequential numbering if tasks are numbered
+- ✓ Verification criteria have content
+- ✓ Risks include mitigations
+- ✓ Reasonable number of tasks (3-20)
+
+**Exit Codes:**
+- `0` - Validation passed
+- `1` - Validation failed (errors found)
+
+### validate-all-plans.sh
+
+Validates all plan files in a directory.
+
+**Usage:**
+```bash
+# Validate all plans in default directory (plans/)
+./.forge/skills/create-plan/validate-all-plans.sh
+
+# Validate plans in custom directory
+./.forge/skills/create-plan/validate-all-plans.sh path/to/plans
+```
+
+**Exit Codes:**
+- `0` - All plans passed validation
+- `1` - One or more plans failed validation
+
+## Integration
+
+### Pre-commit Hook
+
+Add to `.git/hooks/pre-commit`:
+
+```bash
+#!/bin/bash
+# Validate plans before committing
+
+if git diff --cached --name-only | grep -q "^plans/.*\.md$"; then
+    echo "Validating modified plans..."
+    ./.forge/skills/create-plan/validate-all-plans.sh plans/
+    exit $?
+fi
+```
+
+### CI/CD
+
+Add to your CI pipeline:
+
+```yaml
+- name: Validate Plans
+  run: ./.forge/skills/create-plan/validate-all-plans.sh plans/
+```
+
+## Example Valid Plan
+
+See `SKILL.md` for the complete plan template structure.
+
+## Common Validation Errors
+
+1. **Invalid filename format**: Must follow `YYYY-MM-DD-task-name-vN.md` pattern
+   - Use lowercase letters only
+   - Use hyphens (not underscores) to separate words
+   - Use valid date (month 01-12, day 01-31, year 2020+)
+   - Avoid generic names like "test", "task", "temp"
+2. **Missing checkboxes**: Use `- [ ]` not `1.` or `-`
+3. **Code blocks**: Plans should use natural language, not code
+4. **Missing sections**: All required sections must be present
+5. **Empty sections**: Sections should have meaningful content
+6. **Poor task quality**: Tasks should be descriptive and specific
+   - Avoid short descriptions like "Do this", "Fix that", "Update code"
+   - Avoid generic descriptions like "implement feature", "add functionality"
+   - Include rationale and context in task descriptions
+   - Aim for 30-150 characters per task description

.forge/skills/create-plan/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: create-plan
-description: Generate detailed implementation plans for complex tasks. Creates comprehensive strategic plans in Markdown format with objectives, step-by-step implementation tasks using checkbox format, verification criteria, risk assessments, and alternative approaches. Use when users need thorough analysis and structured planning before implementation, when breaking down complex features into actionable steps, or when they explicitly ask for a plan, roadmap, or strategy. Strictly planning-focused with no code modifications.
+description: Generate detailed implementation plans for complex tasks. Creates comprehensive strategic plans in Markdown format with objectives, step-by-step implementation tasks using checkbox format, verification criteria, risk assessments, and alternative approaches. All plans MUST be validated using the included validation script. Use when users need thorough analysis and structured planning before implementation, when breaking down complex features into actionable steps, or when they explicitly ask for a plan, roadmap, or strategy. Strictly planning-focused with no code modifications.
 ---
 
 # Create Implementation Plan
@@ -33,7 +33,17 @@ Generate a Markdown plan file in `plans/` directory with naming: `plans/{YYYY-MM
 
 Example: `plans/2025-11-24-add-auth-v1.md`
 
-### 3. Plan Structure
+### 3. Validate Plan
+
+**MANDATORY:** Run the validation script to ensure the plan meets all requirements:
+
+```bash
+./.forge/skills/create-plan/validate-plan.sh plans/{YYYY-MM-DD}-{task-name}-v{N}.md
+```
+
+Fix any errors or warnings and re-validate until the plan passes all checks.
+
+### 4. Plan Structure
 
 ```markdown
 # [Task Name]
@@ -69,6 +79,7 @@ Example: `plans/2025-11-24-add-auth-v1.md`
 
 ## Critical Requirements
 
+- **ALWAYS validate the plan** using `./.forge/skills/create-plan/validate-plan.sh` after creation
 - **ALWAYS use checkbox format** (`- [ ]`) for ALL implementation tasks
 - **NEVER use numbered lists** or plain bullet points in Implementation Plan section
 - **NEVER write code, code snippets, or code examples** in the plan

.forge/skills/create-plan/validate-all-plans.sh

@@ -0,0 +1,76 @@
+#!/usr/bin/env bash
+# Validates all plan files in the plans directory
+# Usage: ./validate-all-plans.sh [plans-directory]
+
+set -euo pipefail
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+# Get the directory of this script
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+VALIDATOR="$SCRIPT_DIR/validate-plan.sh"
+
+# Check if validator exists
+if [ ! -f "$VALIDATOR" ]; then
+    echo -e "${RED}Error:${NC} Validator script not found at $VALIDATOR"
+    exit 1
+fi
+
+# Make validator executable
+chmod +x "$VALIDATOR"
+
+# Get plans directory (default to plans/ in project root)
+PLANS_DIR="${1:-plans}"
+
+if [ ! -d "$PLANS_DIR" ]; then
+    echo -e "${RED}Error:${NC} Plans directory not found: $PLANS_DIR"
+    exit 1
+fi
+
+# Find all plan files
+PLAN_FILES=$(find "$PLANS_DIR" -name "*.md" -type f | sort)
+
+if [ -z "$PLAN_FILES" ]; then
+    echo -e "${YELLOW}No plan files found in $PLANS_DIR${NC}"
+    exit 0
+fi
+
+# Count files
+TOTAL_FILES=$(echo "$PLAN_FILES" | wc -l | tr -d ' ')
+PASSED=0
+FAILED=0
+
+echo -e "${BLUE}Validating $TOTAL_FILES plan file(s) in $PLANS_DIR${NC}"
+echo ""
+
+# Validate each file
+while IFS= read -r plan_file; do
+    echo -e "${BLUE}═══════════════════════════════════════════════${NC}"
+    if "$VALIDATOR" "$plan_file"; then
+        ((PASSED++))
+    else
+        ((FAILED++))
+    fi
+    echo ""
+done <<< "$PLAN_FILES"
+
+# Final summary
+echo -e "${BLUE}═══════════════════════════════════════════════${NC}"
+echo -e "${BLUE}Summary:${NC}"
+echo -e "  Total:  $TOTAL_FILES"
+echo -e "  ${GREEN}Passed: $PASSED${NC}"
+echo -e "  ${RED}Failed: $FAILED${NC}"
+echo ""
+
+if [ $FAILED -eq 0 ]; then
+    echo -e "${GREEN}✓ All plans validated successfully!${NC}"
+    exit 0
+else
+    echo -e "${RED}✗ Some plans failed validation${NC}"
+    exit 1
+fi