Skip to content

Commit cc94714

Browse files
tusharmathtusharmath
authored
feat(skills): add plan validation scripts to create-plan skill (#2013)
1 parent 3dd4eff commit cc94714

File tree

4 files changed

+551
-2
lines changed

4 files changed

+551
-2
lines changed

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

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
# Create Plan Skill
2+
3+
Tools and scripts for creating and validating implementation plans.
4+
5+
## Files
6+
7+
- `SKILL.md` - Main skill instructions for AI agents
8+
- `validate-plan.sh` - Validates a single plan file
9+
- `validate-all-plans.sh` - Validates all plans in a directory
10+
11+
## Validation Scripts
12+
13+
### validate-plan.sh
14+
15+
Validates the structure and content of a single plan file.
16+
17+
**Usage:**
18+
```bash
19+
./.forge/skills/create-plan/validate-plan.sh plans/2025-11-27-example-v1.md
20+
```
21+
22+
**Checks:**
23+
- ✓ Filename follows convention: `YYYY-MM-DD-task-name-vN.md`
24+
- Year is reasonable (2020 to current year + 1)
25+
- Month is valid (01-12)
26+
- Day is valid (01-31)
27+
- Task name is meaningful (not generic like "test", "task", "temp")
28+
- Task name length is reasonable (5-60 characters)
29+
- Version number is reasonable (not > 50)
30+
- No uppercase letters or underscores (use lowercase and hyphens only)
31+
- ✓ File is in `plans/` directory
32+
- ✓ All required sections present:
33+
- Main heading (`# Title`)
34+
- `## Objective`
35+
- `## Implementation Plan`
36+
- `## Verification Criteria`
37+
- `## Potential Risks and Mitigations`
38+
- `## Alternative Approaches`
39+
- ✓ Implementation Plan uses checkbox format (`- [ ]`)
40+
- ✓ No numbered lists or plain bullets in Implementation Plan
41+
- ✓ No code blocks (` ``` `) in the plan
42+
- ✓ No code snippets (detects suspicious patterns)
43+
- ✓ No placeholder tasks (TODO, TBD, etc.)
44+
- ✓ **Task quality and density:**
45+
- Task descriptions are descriptive (≥ 20 characters recommended)
46+
- Average task length is substantial (30-200 chars recommended)
47+
- No generic/vague descriptions ("implement feature", "fix bug", etc.)
48+
- No duplicate or highly similar tasks
49+
- Consistent and sequential numbering if tasks are numbered
50+
- ✓ Verification criteria have content
51+
- ✓ Risks include mitigations
52+
- ✓ Reasonable number of tasks (3-20)
53+
54+
**Exit Codes:**
55+
- `0` - Validation passed
56+
- `1` - Validation failed (errors found)
57+
58+
### validate-all-plans.sh
59+
60+
Validates all plan files in a directory.
61+
62+
**Usage:**
63+
```bash
64+
# Validate all plans in default directory (plans/)
65+
./.forge/skills/create-plan/validate-all-plans.sh
66+
67+
# Validate plans in custom directory
68+
./.forge/skills/create-plan/validate-all-plans.sh path/to/plans
69+
```
70+
71+
**Exit Codes:**
72+
- `0` - All plans passed validation
73+
- `1` - One or more plans failed validation
74+
75+
## Integration
76+
77+
### Pre-commit Hook
78+
79+
Add to `.git/hooks/pre-commit`:
80+
81+
```bash
82+
#!/bin/bash
83+
# Validate plans before committing
84+
85+
if git diff --cached --name-only | grep -q "^plans/.*\.md$"; then
86+
echo "Validating modified plans..."
87+
./.forge/skills/create-plan/validate-all-plans.sh plans/
88+
exit $?
89+
fi
90+
```
91+
92+
### CI/CD
93+
94+
Add to your CI pipeline:
95+
96+
```yaml
97+
- name: Validate Plans
98+
run: ./.forge/skills/create-plan/validate-all-plans.sh plans/
99+
```
100+
101+
## Example Valid Plan
102+
103+
See `SKILL.md` for the complete plan template structure.
104+
105+
## Common Validation Errors
106+
107+
1. **Invalid filename format**: Must follow `YYYY-MM-DD-task-name-vN.md` pattern
108+
- Use lowercase letters only
109+
- Use hyphens (not underscores) to separate words
110+
- Use valid date (month 01-12, day 01-31, year 2020+)
111+
- Avoid generic names like "test", "task", "temp"
112+
2. **Missing checkboxes**: Use `- [ ]` not `1.` or `-`
113+
3. **Code blocks**: Plans should use natural language, not code
114+
4. **Missing sections**: All required sections must be present
115+
5. **Empty sections**: Sections should have meaningful content
116+
6. **Poor task quality**: Tasks should be descriptive and specific
117+
- Avoid short descriptions like "Do this", "Fix that", "Update code"
118+
- Avoid generic descriptions like "implement feature", "add functionality"
119+
- Include rationale and context in task descriptions
120+
- Aim for 30-150 characters per task description

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

Lines changed: 13 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
name: create-plan
3-
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.
3+
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.
44
---
55

66
# Create Implementation Plan
@@ -33,7 +33,17 @@ Generate a Markdown plan file in `plans/` directory with naming: `plans/{YYYY-MM
3333

3434
Example: `plans/2025-11-24-add-auth-v1.md`
3535

36-
### 3. Plan Structure
36+
### 3. Validate Plan
37+
38+
**MANDATORY:** Run the validation script to ensure the plan meets all requirements:
39+
40+
```bash
41+
./.forge/skills/create-plan/validate-plan.sh plans/{YYYY-MM-DD}-{task-name}-v{N}.md
42+
```
43+
44+
Fix any errors or warnings and re-validate until the plan passes all checks.
45+
46+
### 4. Plan Structure
3747

3848
```markdown
3949
# [Task Name]
@@ -69,6 +79,7 @@ Example: `plans/2025-11-24-add-auth-v1.md`
6979

7080
## Critical Requirements
7181

82+
- **ALWAYS validate the plan** using `./.forge/skills/create-plan/validate-plan.sh` after creation
7283
- **ALWAYS use checkbox format** (`- [ ]`) for ALL implementation tasks
7384
- **NEVER use numbered lists** or plain bullet points in Implementation Plan section
7485
- **NEVER write code, code snippets, or code examples** in the plan

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

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
#!/usr/bin/env bash
2+
# Validates all plan files in the plans directory
3+
# Usage: ./validate-all-plans.sh [plans-directory]
4+
5+
set -euo pipefail
6+
7+
# Colors for output
8+
RED='\033[0;31m'
9+
GREEN='\033[0;32m'
10+
YELLOW='\033[1;33m'
11+
BLUE='\033[0;34m'
12+
NC='\033[0m' # No Color
13+
14+
# Get the directory of this script
15+
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
16+
VALIDATOR="$SCRIPT_DIR/validate-plan.sh"
17+
18+
# Check if validator exists
19+
if [ ! -f "$VALIDATOR" ]; then
20+
echo -e "${RED}Error:${NC} Validator script not found at $VALIDATOR"
21+
exit 1
22+
fi
23+
24+
# Make validator executable
25+
chmod +x "$VALIDATOR"
26+
27+
# Get plans directory (default to plans/ in project root)
28+
PLANS_DIR="${1:-plans}"
29+
30+
if [ ! -d "$PLANS_DIR" ]; then
31+
echo -e "${RED}Error:${NC} Plans directory not found: $PLANS_DIR"
32+
exit 1
33+
fi
34+
35+
# Find all plan files
36+
PLAN_FILES=$(find "$PLANS_DIR" -name "*.md" -type f | sort)
37+
38+
if [ -z "$PLAN_FILES" ]; then
39+
echo -e "${YELLOW}No plan files found in $PLANS_DIR${NC}"
40+
exit 0
41+
fi
42+
43+
# Count files
44+
TOTAL_FILES=$(echo "$PLAN_FILES" | wc -l | tr -d ' ')
45+
PASSED=0
46+
FAILED=0
47+
48+
echo -e "${BLUE}Validating $TOTAL_FILES plan file(s) in $PLANS_DIR${NC}"
49+
echo ""
50+
51+
# Validate each file
52+
while IFS= read -r plan_file; do
53+
echo -e "${BLUE}═══════════════════════════════════════════════${NC}"
54+
if "$VALIDATOR" "$plan_file"; then
55+
((PASSED++))
56+
else
57+
((FAILED++))
58+
fi
59+
echo ""
60+
done <<< "$PLAN_FILES"
61+
62+
# Final summary
63+
echo -e "${BLUE}═══════════════════════════════════════════════${NC}"
64+
echo -e "${BLUE}Summary:${NC}"
65+
echo -e " Total: $TOTAL_FILES"
66+
echo -e " ${GREEN}Passed: $PASSED${NC}"
67+
echo -e " ${RED}Failed: $FAILED${NC}"
68+
echo ""
69+
70+
if [ $FAILED -eq 0 ]; then
71+
echo -e "${GREEN}✓ All plans validated successfully!${NC}"
72+
exit 0
73+
else
74+
echo -e "${RED}✗ Some plans failed validation${NC}"
75+
exit 1
76+
fi

0 commit comments

Comments
 (0)