Content
73%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 highly actionable, well-sequenced workflow with excellent validation and rollback behavior for a destructive operation (moving changeRoot). The main weakness is token efficiency: repetitive caveat restatements and a Guardrails section that duplicates body content inflate the budget without adding guidance.
Suggestions
Cut redundant restatements: the store-selection paragraph, the instructions-archive advisory handling, and the Guardrails section each repeat rules already stated in the body — consolidate to one statement each.
Move the detailed post-sync structural verification contract (title, Purpose, heading rules) into a reference file or delegate it to the openspec-sync-specs workflow it describes, shortening step 4 substantially.
Tighten the project-check section's three branches into a compact decision list to reduce conditional prose.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Most content is CLI-specific contract knowledge Claude would not know, but it is noticeably padded: the store-selection and project-check sections repeat the same caveats in multiple phrasings, and the Guardrails section restates rules already stated in the body. It could be tightened considerably without losing information. | 3 / 5 |
Actionability | Nearly every step has copy-paste commands ("openspec instructions archive --change \"<name>\" --json", "openspec status --change \"<name>\" --json", "mkdir -p", "mv") with named JSON fields to parse. Minor gaps remain: the sync execution ("run the openspec-sync-specs workflow inline") and the post-sync comparison are prose-level rather than concrete invocations. | 4 / 5 |
Workflow Clarity | A clear six-step sequence with explicit validation checkpoints at every phase — artifact status, task-count validation, pre-sync rule fetch with required zero exit, post-sync structural verification re-run across all capabilities — plus explicit failure handling, stop conditions, and rollback guarantees ("Nothing has moved... so the user can fix the blocking condition"). | 5 / 5 |
Progressive Disclosure | No bundle files exist and the content is the executable workflow itself rather than deferrable reference material, organized into well-labeled sections (Store selection, Project check, Steps 1-6, Output, Guardrails). The main gap is that step 4 inlines the ~60-line sync contract that belongs to the referenced openspec-sync-specs workflow, which a separate reference file could absorb. | 4 / 5 |
Total | 16 / 20 Passed |