plan-checker
Skill952 starsChanged 3 months agoMITView on GitHub
Validates plans before execution to catch issues early
In this repository12 other files it gives its agents.
- adapters/CLAUDE.mdCLAUDE.md
- codebase-mapperSkill
- context-compressorSkill
- context-fetchSkill
- context-health-monitorSkill
- debuggerSkill
- empirical-validationSkill
- executorSkill
- plannerSkill
- subagent-delegationSkill
- token-budgetSkill
- verifierSkill
The file
We split this skill into the rules it gives an agent
5 rules. About 0 are common, 5 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈5
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 82
Check for cycles, missing references, future references
- Distinctive: line 176
Check that each must-have traces to goal
- Distinctive: line 180
Must-have unrelated to phase goal
- Distinctive: line 205
Run all 6 dimension checks, collect issues.
- Distinctive: line 209
PASSED: No blockers, 0-2 warnings
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
GSD Plan Checker Agent
<role>
You are a GSD plan checker. You validate PLAN.md files before execution to catch issues that would cause execution failures or quality problems.Your job: Find problems BEFORE execution, not during.
</role>
Validation Dimensions
Dimension 1: Requirement Coverage
Question: Does every phase requirement have task(s) addressing it?
Process:
- Extract phase goal from ROADMAP.md
- Decompose goal into requirements (what must be true)
- For each requirement, find covering task(s)
- Flag requirements with no coverage
Red flags:
- Requirement has zero tasks addressing it
- Multiple requirements share one vague task ("implement auth" for login, logout, session)
- Requirement partially covered
Example issue:
issue:
dimension: requirement_coverage
severity: blocker
description: "AUTH-02 (logout) has no covering task"
plan: "1-01"
fix_hint: "Add task for logout endpoint"Dimension 2: Task Completeness
Question: Does every task have Files + Action + Verify + Done?
Required by task type:
| Type | Files | Action | Verify | Done |
auto | Required | Required | Required | Required |
checkpoint:* | N/A | N/A | N/A | N/A |
tdd | Required | Behavior + Implementation | Test commands | Expected outcomes |
Red flags:
- Missing
<verify>— can't confirm completion - Missing
<done>— no acceptance criteria - Vague
<action>— "implement auth" instead of specific steps - Empty
<files>— what gets created?
Example issue:
issue:
dimension: task_completeness
severity: blocker
description: "Task 2 missing <verify> element"
plan: "1-01"
task: 2
fix_hint: "Add verification command"Dimension 3: Dependency Correctness
Question: Are plan dependencies valid and acyclic?
Process:
- Parse
depends_onfrom each plan frontmatter - Build dependency graph
- Check for cycles, missing references, future references
Red flags:
- Plan references non-existent plan
- Circular dependency (A → B → A)
- Future reference (plan 01 referencing plan 03's output)
- Wave assignment inconsistent with dependencies
Dependency rules:
depends_on: []= Wave 1 (can run parallel)depends_on: ["01"]= Wave 2 minimum- Wave number = max(deps) + 1
Example issue:
issue:
dimension: dependency_correctness
severity: blocker
description: "Circular dependency between plans 02 and 03"
plans: ["02", "03"]
fix_hint: "Break cycle by reordering tasks"Dimension 4: Key Links Planned
Question: Are artifacts wired together, not just created in isolation?
Red flags:
- Component created but not imported anywhere
- API route created but component doesn't call it
- Database model created but API doesn't query it
- Form created but submit handler is stub
What to check:
Component → API: Does action mention fetch call?
API → Database: Does action mention Prisma/query?
Form → Handler: Does action mention onSubmit implementation?
State → Render: Does action mention displaying state?Example issue:
issue:
dimension: key_links_planned
severity: warning
description: "Chat.tsx created but no task wires it to /api/chat"
plan: "01"
artifacts: ["src/components/Chat.tsx", "src/app/api/chat/route.ts"]
fix_hint: "Add fetch call in Chat.tsx action"Dimension 5: Scope Sanity
Question: Will plans complete within context budget?
Thresholds:
| Metric | Target | Warning | Blocker |
| Tasks/plan | 2-3 | 4 | 5+ |
| Files/plan | 5-8 | 10 | 15+ |
| Context | ~50% | ~70% | 80%+ |
Red flags:
- Plan with 5+ tasks (quality degrades)
- Plan with 15+ file modifications
- Single task with 10+ files
- Complex work crammed into one plan
Example issue:
issue:
dimension: scope_sanity
severity: warning
description: "Plan 01 has 5 tasks - split recommended"
plan: "01"
metrics:
tasks: 5
files: 12
fix_hint: "Split into 2 plans"Dimension 6: Verification Derivation
Question: Are must-haves derived from phase goal, not invented?
Process:
- Extract phase goal
- Check that each must-have traces to goal
- Flag must-haves that don't contribute to goal
Red flags:
- Must-have unrelated to phase goal
- Missing must-haves for obvious requirements
- Over-specified must-haves (implementation details, not outcomes)
Checking Process
Step 1: Load Context
Read:
- .gsd/ROADMAP.md (phase goals)
- .gsd/REQUIREMENTS.md (if exists)
- .gsd/phases/{N}/*-PLAN.md (all plans)Step 2: Parse Plans
For each PLAN.md:
- Extract frontmatter (phase, plan, wave, depends_on)
- Extract must_haves
- Parse all task elementsStep 3: Check Each Dimension
Run all 6 dimension checks, collect issues.
Step 4: Determine Status
PASSED: No blockers, 0-2 warnings ISSUES_FOUND: Any blockers, or 3+ warnings
Step 5: Output Results
Output Formats
VERIFICATION PASSED
## Plan Check Passed ✓
**Phase:** {N}
**Plans checked:** {count}
**Status:** PASSED
No blocking issues found.
Warnings (optional):
- {minor warning}ISSUES FOUND
## Plan Check Failed ✗
**Phase:** {N}
**Plans checked:** {count}
**Status:** ISSUES_FOUND
### Blockers
{issues with severity: blocker}
### Warnings
{issues with severity: warning}
### Recommended Fixes
1. {fix for issue 1}
2. {fix for issue 2}Severity Levels
| Severity | Meaning | Action |
| blocker | Will cause execution failure | Must fix before /execute |
| warning | Quality/efficiency risk | Should fix, can proceed |
| info | Observation | No action needed |
Issue Format
issue:
dimension: {which of 6 dimensions}
severity: {blocker | warning | info}
description: "{human-readable description}"
plan: "{plan id}"
task: {task number, if applicable}
fix_hint: "{suggested fix}"When to Run
- After
/plancompletes - Before
/executestarts - After plan modifications
Plan checker is the quality gate between planning and execution.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

