plan-grader
Grade implementation plans on a 0-10 scale without mutating the workspace. Accepts plan files, quoted inline plans, or best-effort latest-plan discovery for Claude, Codex, Copilot, and Gemini.
- License 许可
- MIT
- 最近更新
- 2026-10-26
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- plan-grader
- description
- Grade implementation plans on a 0-10 scale without mutating the workspace. Accepts plan files, quoted inline plans, or best-effort latest-plan discovery for Claude, Codex, Copilot, and Gemini.
- allowed-tools
- Read Grep Glob Bash
- argument-hint
- [--json] [--blind] <plan-path | file:<path> | text:"plan" | "plan" | latest <agent> plan>
02 资源文件 9
- 参考文档references/agent-formats.md1.8 KB
- 参考文档references/calibration-plans/35-dangerous.md1.9 KB
- 参考文档references/calibration-plans/55-rework.md1.9 KB
- 参考文档references/calibration-plans/75-solid.md2.2 KB
- 参考文档references/calibration-plans/95-excellent.md3.0 KB
- 参考文档references/context-resolution.md2.0 KB
- 参考文档references/plan-discovery.md3.1 KB
- 参考文档references/rubric.md6.8 KB
- 参考文档references/test-plan.md2.6 KB
03 SKILL.md 正文
Grade an implementation plan on a 0-10 scale using the plan-grader rubric. This skill is content-only: inspect, score, explain, and produce a paste-back prompt. Do not edit files, run formatters, commit changes, or implement the plan being graded.
Use when the user asks to grade, score, review, evaluate, improve, or calibrate a plan, especially
plans produced by Claude Code, Codex, GitHub Copilot, Gemini CLI, or similar agentic CLIs. Also
trigger directly via /plan-grader.
Inputs
$ARGUMENTS may be any of:
<path>orfile:<path>: read the plan from a local Markdown/text file."..."ortext:"...": grade the quoted inline plan text exactly as provided.latest claude plan,latest codex plan,latest copilot plan, orlatest gemini plan: discover candidate plan/session files usingreferences/plan-discovery.md.- Optional
--json: emit only the structured JSON object described below. - Optional
--blind: strip source-agent attribution before scoring. Keep explicit harness context that affects safety, validation, or repo fit.
If the input is ambiguous, ask for the plan path or paste. Do not guess a plan from unrelated chat.
Reference Order
Before grading, read these references:
references/rubric.mdreferences/context-resolution.mdreferences/plan-discovery.mdwhen discovery, imports, symlinks, oversized content, or transcript extraction are involvedreferences/agent-formats.mdwhen the source agent is known or a paste-back prompt is needed- Relevant examples in
references/calibration-plans/
Workflow
-
Parse flags and input mode.
--jsonchanges output format only.--blindremoves agent identity from the plan before scoring.file:forces file mode.text:forces inline text mode.- Top-level quoted text is inline plan text, not a path.
-
Resolve the plan text.
- For file inputs, read the target file.
- For inline text, use the supplied text verbatim.
- For
latest <agent> plan, followreferences/plan-discovery.md. - If discovery returns multiple candidates, present the top three most recent candidate paths and ask the user to choose.
- Refuse oversized inputs that cannot fit the context budget. Do not silently truncate.
-
Resolve intent sources.
- Treat files mentioned by the plan as intent evidence, especially
@roadmap.md,@spec.md,file:docs/foo.md, or explicit local paths. - Resolve transitive
@imports to the depth documented inreferences/plan-discovery.md. - If a referenced intent file is unreadable, record the missing file and lower confidence.
- If a readable intent file contradicts the plan, apply the relevant rubric cap.
- Treat files mentioned by the plan as intent evidence, especially
-
Resolve harness context.
- Read project-level
AGENTS.mdfirst as the cross-agent baseline when present. - Layer agent-specific project overrides:
CLAUDE.md,GEMINI.md,.github/copilot-instructions.md,.github/instructions/*.instructions.md, andAGENTS.override.md. - Consider user/global harness files only as preference context. They cannot weaken repo-local safety, validation, protected-path, release, or CI rules.
- Detect whether the plan violates configured harnesses or protected gates.
- Read project-level
-
Calibrate before scoring.
- Read at least the two calibration anchors closest to the expected score band.
- Use the anchors to normalize severity and avoid over-rewarding format polish.
-
Score the plan.
- Score each rubric dimension from 0 to 10.
- Compute the weighted score using rubric version
2.0.0. - Apply caps, then auto-reject rules, then floor at 0, then round to one decimal.
- Record
confidenceashigh,medium, orlow.
-
Produce output.
- Default: concise human-readable report with score, verdict, dimension table, caps, blocking gaps, non-blocking polish, and a paste-back prompt.
--json: emit only valid JSON with exactly these top-level keys:rubric_version,score,verdict,confidence,dimensions,caps_fired,blocking_gaps,non_blocking,paste_back_prompt.
Human Output Shape
Plan grade: X.X / 10
Verdict: <approve | approve with minor changes | revise before execution | reject>
Confidence: <high | medium | low>
<One short paragraph explaining the main reason for the grade.>
| Dimension | Weight | Score | Reasoning |
| --------- | -----: | ----: | ---------------------- |
| ... | 0.XX | N/10 | Evidence-backed reason |
Caps fired:
- <cap id or "None">
Blocking gaps:
1. <gap>
Non-blocking improvements:
- <improvement>
Paste-back prompt:
<agent-aware prompt from references/agent-formats.md>
JSON Output Shape
{
"rubric_version": "2.0.0",
"score": 8.4,
"verdict": "approve with minor changes",
"confidence": "high",
"dimensions": [
{
"name": "Goal and scope clarity",
"weight": 0.15,
"score": 9,
"reasoning": "The plan defines the output contract and non-goals.",
"evidence": ["plan.md:12"]
}
],
"caps_fired": [],
"blocking_gaps": [],
"non_blocking": ["Add one explicit smoke test for malformed input."],
"paste_back_prompt": "Revise the plan to add one malformed-input smoke test..."
}
Rules
- Do not mutate files or implement the plan being graded.
- Do not score from vibes. Cite concrete evidence from the plan, intent files, harness files, repo paths, tests, CI, or explicit missing evidence.
- Mention when the grade is based on incomplete transcript extraction rather than a real plan file.
- Auto-reject dangerous caps even when the weighted score is high.
- Keep all weights from
references/rubric.mdexactly. Do not silently reweight. - For
--blind, do not penalize or reward the plan because it came from Claude, Codex, Copilot, or Gemini. Grade the content and repo fit. - If a plan references images or diagrams, do not OCR them. Mark that portion partially ungradable.
- If a plan would touch protected paths, verify it includes the required Spec ID or No-spec rationale in the PR plan.
- Always include a paste-back prompt unless the user explicitly asks for only the numeric grade.
04 同仓库更多 Skills
yolo
Start temporary autonomy for the current task or an explicit scope with a required --for expiry. Codex permits scoped pushes, merges, deploys, and releases after strict testing and validation; Full access is a separate runtime setting. Claude Code uses a session permission hook with a protected-action denylist.
veracity-audit
Audit a data pipeline for Veracity and Value. Dispatches data-scientist, compliance-auditor, and data-engineer agents with project context injected at dispatch time. All source paths are supplied via flags — no defaults, no project assumptions. Subcommands: audit (full pipeline walk), score-check (scoring math only), gate-check (gate coverage only), source-trace <label> (single source end-to-end). Invoke when: "audit pipeline", "veracity check", "scoring math correct?", "check gates", "trace source", "verify quality gates", "formula correct?".
validate-spec
Audit an already-implemented spec against the codebase. Walks each constraint (ARCH-N, PERF-N, KD-N, etc.) and acceptance criterion, grounds findings in file:line evidence, runs the spec.json acceptance_commands, and writes a single audit doc to docs/audits/. Use whenever the user asks to "validate a spec", "audit a spec", "check if spec is implemented", "verify the spec is done", "is this spec really done", or otherwise wants closure on spec-driven work. Read-only against the spec — produces an audit, never modifies the spec itself.
terragrunt-specialist
Deep-dive Terragrunt hierarchy review, DRY pattern audits, and run-all orchestration analysis. Use for structured investigations of multi-environment Terragrunt layouts, dependency graphs, remote state config, and hook correctness. Triggers on: "Terragrunt audit", "run-all review", "dependency block", "DRY pattern review", "env hierarchy audit", "mock_outputs", "terragrunt hooks".
terraform-specialist
Deep-dive Terraform architecture review, module design, state management, and migration. Use for structured investigations of Terraform workspaces, provider configuration, module coupling, import workflows, and test coverage. Triggers on: "Terraform audit", "module review", "state management", "Terraform import", "workspace design", "provider config review", "Terraform testing".
spec
Create structured engineering specs through interactive pairing. Use when the user wants to create a spec, design doc, technical specification, architecture document, RFC, or engineering plan. Triggers on "let's spec this out", "create a spec", "design doc", "write a technical plan", "plan the architecture". Works for greenfield and brownfield projects. Outputs to docs/specs/.