Content
81%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.
A tightly written, highly actionable end-to-end workflow contract with excellent sequencing and validation feedback loops. Its main weaknesses are minor verbosity in the Review/Finish sections and an inlined template that could be split into a reference file.
Suggestions
Trim the Review prose to the essential reviewer contract and move elaboration into a reference file to improve conciseness.
Extract the spec template block into a references/spec-template.md file referenced from the Spec section to strengthen progressive disclosure.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | A dense, directive contract that assumes Claude's competence and avoids explaining known concepts, but the Review and Finish sections contain prose that could be trimmed without losing the contract. | 4 / 5 |
Actionability | Provides concrete, executable guidance — 'git rev-parse --git-dir', 'git worktree add "$path" -b "$branch"', 'bun ci', 'uv sync --frozen', 'docs/compose/spec/<feature-name>.md' — though much of it is directive prose rather than copy-paste-ready code covering common cases. | 4 / 5 |
Workflow Clarity | Phases (Step 0, Grill, Spec, Workspace, Implement, Verify, Review, Finalize, Finish) are explicitly sequenced with validation checkpoints ('run the repository's relevant tests', 'Verification and review are strictly sequential') and feedback loops ('After two failed fixes, stop patching and re-derive the cause', fix-and-re-review convergence detection). | 5 / 5 |
Progressive Disclosure | Well-organized with a clear overview line and distinct section headers, and no nested references; the inlined spec template and some longer sections (Review) could arguably live in separate reference files, leaving minor organization gaps. | 4 / 5 |
Total | 17 / 20 Passed |