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.
A well-structured, actionable multi-step workflow with concrete CLI commands and real validation checkpoints. Its chief weakness is redundancy between the Steps, Guidelines, and Guardrails sections, and a slightly abstract artifact-writing step.
Suggestions
Collapse the overlapping guidance in 'Artifact Creation Guidelines' and 'Guardrails' into the Steps where it first appears to remove repetition and tighten conciseness.
Add one short filled-in example of an artifact file (e.g. a sample tasks.md) so the writing step is concrete rather than 'fill in the template'.
Consider moving the openspec instructions JSON schema breakdown and store-selection details into a reference file to improve progressive disclosure.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Mostly efficient and free of basic-concept padding, but the Artifact Creation Guidelines and Guardrails sections repeat guidance already given in Steps (re-reading dependencies, using template as structure, not copying context/rules), which could be tightened; not a 4 because the redundancy is noticeable rather than minor. | 3 / 5 |
Actionability | Provides concrete, copy-pasteable commands ('openspec new change', 'openspec status --change --json', 'openspec instructions <artifact-id> --change --json') with JSON field guidance; not a 5 because the actual artifact-writing step ('Create the artifact file using template as the structure') stays somewhat abstract without a filled example. | 4 / 5 |
Workflow Clarity | A clearly sequenced 5-step process with explicit checkpoints (re-run status until applyRequires done, verify each file exists before proceeding, ask the user when context is unclear); not a 5 because verification checks file existence rather than content validity, a minor gap. | 4 / 5 |
Progressive Disclosure | Well-organized into logical sections (Store selection, Input, Steps, Output, Guidelines, Guardrails) with no nested references and a navigable structure; not a 5 because at ~100 lines the instructions-JSON schema details and store-selection material could arguably live in one-level-deep reference files, and the simple-skill exception does not apply. | 4 / 5 |
Total | 15 / 20 Passed |