Content
67%Weight 40%Scale 1-5Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
The body is a well-sequenced, largely executable workflow with real validation checkpoints (gates, constitution checks, prerequisites) and concrete commands, paths, and output templates. Its main weaknesses are the verbatim duplication of the extension-hook procedure and one underspecified step ('the agent script'), which cost tokens and leave a small execution gap.
Suggestions
Factor the extension-hook procedure (enabled filtering, condition policy, dot-to-hyphen conversion, output templates) into a single shared block referenced by both the pre-execution check and Outline step 5, cutting ~25 duplicated lines.
Name the exact agent-context script and command in Phase 1 ('Update the plan reference... by running the agent script') so the step is executable as written.
Specify what to do when setup-plan.sh fails or its JSON cannot be parsed, mirroring the silent-skip guidance already given for invalid extensions.yml.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense and imperative with no tutoring of known concepts, but the ~28-line extension-hook procedure (enabled filtering, condition handling, dot-to-hyphen command conversion, output templates) is duplicated verbatim for before_plan and after_plan. That matches 'Mostly efficient but includes some unnecessary explanation or could be tightened' — not 2, since the redundancy is the only notable padding and the remainder is lean; not 4, because the duplication is a real, avoidable token cost that a single shared procedure would eliminate. | 3 / 5 |
Actionability | Most steps are concrete and executable: the exact command '.specify/scripts/bash/setup-plan.sh --json', specific paths (.specify/memory/constitution.md, CLAUDE.md SPECKIT markers), a shell-quoting escape example, and exact output templates for each hook type. It falls short of 5 because 'Update agent context by running the agent script' never names the script or command, and the plan workflow defers to an external IMPL_PLAN template whose structure is not reproduced — minor gaps that keep it from copy-paste readiness throughout. | 4 / 5 |
Workflow Clarity | The sequence is explicit (Setup → Load context → Execute plan workflow → Stop and report → post-hooks), phases carry prerequisites ('research.md complete'), and validation checkpoints exist: gate evaluation with 'ERROR if violations unjustified', NEEDS CLARIFICATION markers resolved in Phase 0, and a post-design Constitution Check re-evaluation. Not 5 because there is no recovery loop for gate failures beyond 'ERROR', and failure handling for the setup script/JSON parse is unspecified; comfortably above 3, which requires missing or merely implicit checkpoints. | 4 / 5 |
Progressive Disclosure | The body is well-sectioned (User Input, Pre-Execution Checks, Outline, Phases, Key rules) at ~135 lines with no bundle files, and it appropriately defers bulk detail (the plan structure) to the project's own IMPL_PLAN template rather than inlining it. This matches 'Good structure; most content is appropriately placed; minor organization gaps' — the minor gap being the duplicated hook boilerplate living inline. Not 5 because the file exceeds a lean overview and the repeated hook block would sit better in a shared reference section. | 4 / 5 |
Total | 15 / 20 Passed |