Interactive review of spec documents with validation, status updates, and archival
Reviews spec documents with validation checks and manages status workflow.
/plugin marketplace add Data-Wise/craft/plugin install data-wise-craft@Data-Wise/craftworkflow/Interactive review of formal specs with validation, status updates, and archival.
| Argument | What it does |
|---|---|
| (none) | List all specs in project |
[topic] | Review specific spec |
list | List all specs with status |
show [topic] | Display spec content |
review [topic] | Interactive review with validation |
approve [topic] | Mark spec as approved |
archive [topic] | Move to archive (completed) |
# Find specs in project
find docs/specs -name "SPEC-*.md" -type f 2>/dev/null
# If no specs directory, check root
find . -maxdepth 1 -name "SPEC-*.md" -type f 2>/dev/null
| Input | Behavior |
|---|---|
/spec:review | List all specs, then ask which to review |
/spec:review auth | Review spec matching "auth" |
/spec:review list | Show all specs with status |
/spec:review approve auth | Mark auth spec as approved |
Show all specs with their status:
┌─────────────────────────────────────────────────────────────┐
│ 📋 SPECS IN PROJECT │
├─────────────────────────────────────────────────────────────┤
│ │
│ Active Specs: │
│ 📝 SPEC-auth-system-2025-12-30.md │
│ Status: draft │ Created: 2025-12-30 │
│ Open Questions: 2 │
│ │
│ ✅ SPEC-notifications-2025-12-28.md │
│ Status: approved │ Created: 2025-12-28 │
│ Ready for implementation │
│ │
│ 🔧 SPEC-cache-layer-2025-12-25.md │
│ Status: implementing │ Created: 2025-12-25 │
│ In progress │
│ │
│ Archived: 3 specs in docs/specs/_archive/ │
│ │
├─────────────────────────────────────────────────────────────┤
│ 🔗 Actions: │
│ /spec:review [topic] ← review a spec │
│ /spec:review approve [t] ← mark as approved │
│ │
└─────────────────────────────────────────────────────────────┘
Display spec content:
# Read and display spec
cat docs/specs/SPEC-[topic]-*.md
# Highlight sections:
# - Overview
# - User Stories + Acceptance Criteria
# - Technical Requirements
# - Open Questions
# - Review Checklist
Interactive review with validation checks:
┌─────────────────────────────────────────────────────────────┐
│ 📋 REVIEWING: SPEC-auth-system-2025-12-30.md │
├─────────────────────────────────────────────────────────────┤
│ │
│ Topic: Authentication System │
│ Status: draft │
│ Created: 2025-12-30 │
│ From Brainstorm: BRAINSTORM-auth-2025-12-30.md │
│ │
│ ─────────────────────────────────────────────────────────── │
│ │
│ Sections: │
│ ✅ Overview - Complete │
│ ✅ User Stories - 1 primary, 2 secondary │
│ ⚠️ Technical Requirements - Missing API endpoints │
│ ✅ UI/UX Specifications - Complete │
│ ❌ Open Questions - 2 unresolved │
│ │
└─────────────────────────────────────────────────────────────┘
| Check | Status | Description |
|---|---|---|
| Acceptance criteria testable | ✅/⚠️/❌ | Each criterion can be verified |
| Technical requirements complete | ✅/⚠️/❌ | APIs, data models defined |
| Dependencies identified | ✅/⚠️/❌ | All deps listed |
| No blocking questions | ✅/⚠️/❌ | Open questions resolved |
AskUserQuestion:
question: "What would you like to do with this spec?"
header: "Action"
multiSelect: false
options:
- label: "Approve - Ready for implementation"
description: "Mark status as 'approved'"
- label: "Update - Add missing information"
description: "Edit spec to fill gaps"
- label: "Add Questions - Note concerns"
description: "Add to Open Questions section"
- label: "Keep as Draft - Not ready yet"
description: "Leave status unchanged"
If Approve:
approvedIf Update:
If Add Questions:
Quick approval without full review:
AskUserQuestion:
question: "Confirm approval of this spec?"
header: "Approve"
multiSelect: false
options:
- label: "Yes - Approve for implementation"
description: "Status → approved"
- label: "No - Review first"
description: "Run full review"
If confirmed:
approvedMove completed spec to archive:
AskUserQuestion:
question: "Archive this spec?"
header: "Archive"
multiSelect: false
options:
- label: "Yes - Implementation complete"
description: "Move to docs/specs/_archive/"
- label: "Yes - Superseded by new spec"
description: "Archive as replaced"
- label: "No - Keep active"
description: "Don't archive"
If confirmed:
docs/specs/_archive/donedef validate_acceptance_criteria(spec):
criteria = extract_criteria(spec)
issues = []
for criterion in criteria:
# Check if testable (contains action verb)
if not has_action_verb(criterion):
issues.append(f"Criterion not testable: {criterion}")
# Check if measurable
if not has_measurable_outcome(criterion):
issues.append(f"Criterion not measurable: {criterion}")
return issues
def validate_technical_requirements(spec):
issues = []
# Check for API endpoints
if "| Endpoint |" not in spec and "API" in spec:
issues.append("API mentioned but no endpoints defined")
# Check for data models
if "Model:" not in spec and ("database" in spec.lower() or "data" in spec.lower()):
issues.append("Data mentioned but no models defined")
# Check for dependencies
if "Dependencies" not in spec:
issues.append("No dependencies section")
return issues
def validate_open_questions(spec):
questions = extract_open_questions(spec)
unchecked = [q for q in questions if q.startswith("- [ ]")]
if unchecked:
return f"{len(unchecked)} unresolved questions"
return None
stateDiagram-v2
[*] --> draft: Created from brainstorm
draft --> reviewed: /spec:review (validation passes)
reviewed --> approved: /spec:review approve
approved --> implementing: /craft:do starts work
implementing --> done: /workflow:done completes
done --> [*]: /spec:review archive
draft --> draft: Add questions
reviewed --> draft: Issues found
Rich formatted output with colors, boxes, and status indicators.
--format json){
"specs": [
{
"file": "SPEC-auth-system-2025-12-30.md",
"topic": "auth-system",
"status": "draft",
"created": "2025-12-30",
"updated": "2025-12-30",
"validation": {
"acceptance_criteria": "pass",
"technical_requirements": "warning",
"open_questions": "fail"
},
"open_questions_count": 2
}
]
}
Called by:
/workflow:brainstorm - Suggests review after spec capture/craft:do - Checks for relevant spec before implementationWorks with:
/workflow:done - Offers to archive completed specs/craft:docs:update - Can generate docs from approved specsUser: /spec:review
Claude: Shows list of all specs in project
→ 3 active, 2 archived
→ User selects "auth-system" to review
User: /spec:review auth
Claude: Finds SPEC-auth-system-2025-12-30.md
→ Shows summary with validation results
→ Asks for action (approve/update/add questions/keep draft)
User: /spec:review approve notifications
Claude: Confirms approval
→ Updates status to "approved"
→ Shows next steps (/craft:do "implement notifications")
User: /spec:review archive cache-layer
Claude: Confirms archive
→ Moves to docs/specs/_archive/
→ Updates status to "done"
Initial Release: