feat(plan): add machine-checkable success-criteria gate (#209)

Author: omartinma

skills/build/SKILL.md

@@ -45,7 +45,7 @@ ls docs/plan/
 
 Do not proceed without a plan.
 
-**After loading the plan:** parse title, type, acceptance criteria, tasks, and file paths. Summarize scope to the user, then use **AskUserQuestion** to confirm:
+**After loading the plan:** parse title, type, the `success-criteria` block, tasks, and file paths. Summarize scope to the user, then use **AskUserQuestion** to confirm:
 
 - **Start building (Recommended)**: proceed with implementation
 - **Review the plan first**: open the plan file for review

skills/plan-technical-review/references/success-criteria.md

@@ -0,0 +1 @@
+../../shared/references/plan-templates/success-criteria.md

skills/plan/SKILL.md

@@ -119,9 +119,25 @@ After planning the issue structure, run the **user-flow-analysis-agent** to anal
 
 - [ ] Review flow analysis results
 - [ ] Incorporate any identified gaps or edge cases into the issue
-- [ ] Update acceptance criteria based on flow analysis findings
+- [ ] Update success criteria based on flow analysis findings
 
-### 4. Select implementation detail template
+### 4. Success Criteria Gate
+
+Before selecting a template, derive the plan's success criteria and make each one machine-checkable. This block is the contract `/build` consumes, so it must be precise.
+
+**For each criterion, apply one rule — can a command prove this without human judgment?**
+
+- **Yes** → attach `verify: <command>` (exit code 0 = pass).
+- **No, but a human can check it** → attach `verify: manual <numbered steps>`.
+- **Neither (vacuous or unmeasurable, e.g. "make it work", "code is clean")** → reject it and rewrite it into a concrete, provable criterion.
+
+Surface every rejected or rewritten criterion to the user with **AskUserQuestion** before writing the plan file — do not silently change the spec they approved.
+
+These criteria populate the `success-criteria` block defined in [success-criteria.md](references/success-criteria.md); fill it in when you write the plan file in Step 6. That reference shows the block's shape and the `verify:` convention.
+
+`verify:` commands reflect the project's own toolchain. If the project has a companion verification skill available, its gates are the canonical `verify:` commands.
+
+### 5. Select implementation detail template
 
 **Default to Standard.** Use a different level only when the task clearly warrants it.
 
@@ -131,13 +147,13 @@ After planning the issue structure, run the **user-flow-analysis-agent** to anal
 | **Standard** (default) | Most features and bug fixes needing moderate detail | [standard](references/standard.md) |
 | **Extensive** | Major features, architectural changes, significant risk or uncertainty | [extensive](references/extensive.md) |
 
-### 4.1. Set up workspace
+### 5.1. Set up workspace
 
 Before writing the plan file, ensure the session is on a feature branch:
 
 - Call /create-branch to check and optionally create a working branch or worktree.
 
-### 5. Issue creation and formatting
+### 6. Issue creation and formatting
 
 **Formatting checklist:**
 
@@ -147,15 +163,15 @@ Before writing the plan file, ensure the session is on a feature branch:
 - [ ] Include prompts or instructions that worked well during research
 - [ ] Emphasize comprehensive testing given rapid AI-assisted implementation
 
-### 6. Final review
+### 7. Final review
 
 **Pre-submission Checklist:**
 
 - [ ] Title is searchable and descriptive
 - [ ] Labels accurately categorize the issue
 - [ ] All template sections are complete
 - [ ] Links and references are working
-- [ ] Acceptance criteria are measurable
+- [ ] Success criteria each carry a `verify:` command (or `verify: manual <steps>`)
 - [ ] Add names of files in pseudo code examples and todo lists
 - [ ] Add an ERD mermaid diagram if applicable for new model changes
 

skills/plan/references/success-criteria.md

@@ -0,0 +1 @@
+../../shared/references/plan-templates/success-criteria.md

skills/shared/references/plan-templates/extensive.md

@@ -29,42 +29,28 @@ date: YYYY-MM-DD
 #### Phase 1: [Foundation]
 
 - Tasks and deliverables
-- Success criteria
+- Phase exit condition
 - Estimated effort
 
 #### Phase 2: [Core Implementation]
 
 - Tasks and deliverables
-- Success criteria
+- Phase exit condition
 - Estimated effort
 
 #### Phase 3: [Polish & Optimization]
 
 - Tasks and deliverables
-- Success criteria
+- Phase exit condition
 - Estimated effort
 
 ## Alternative Approaches Considered
 
 [Other solutions evaluated and why rejected]
 
-## Acceptance Criteria
+## Success Criteria
 
-### Functional Requirements
-
-- [ ] Detailed functional criteria
-
-### Non-Functional Requirements
-
-- [ ] Performance targets
-- [ ] Security requirements
-- [ ] Accessibility standards
-
-### Quality Gates
-
-- [ ] Test coverage requirements
-- [ ] Documentation completeness
-- [ ] Code review approval
+Embed the machine-checkable block defined in [success-criteria.md](success-criteria.md), with the placeholders filled in. For an extensive plan, cover functional, non-functional, and quality-gate requirements as concrete criteria.
 
 ## Success Metrics
 

skills/shared/references/plan-templates/minimal.md

@@ -8,10 +8,9 @@ date: YYYY-MM-DD
 
 [Brief problem/feature description]
 
-## Acceptance Criteria
+## Success Criteria
 
-- [ ] Core requirement 1
-- [ ] Core requirement 2
+Embed the machine-checkable block defined in [success-criteria.md](success-criteria.md), with the placeholders filled in.
 
 ## Context
 

skills/shared/references/plan-templates/standard.md

@@ -24,11 +24,9 @@ date: YYYY-MM-DD
 - Performance implications
 - Security considerations
 
-## Acceptance Criteria
+## Success Criteria
 
-- [ ] Detailed requirement 1
-- [ ] Detailed requirement 2
-- [ ] Testing requirements
+Embed the machine-checkable block defined in [success-criteria.md](success-criteria.md), with the placeholders filled in.
 
 ## Success Metrics
 

skills/shared/references/plan-templates/success-criteria.md

@@ -0,0 +1,20 @@
+# Success Criteria block
+
+The single source for the machine-checkable success-criteria block. Every plan template and the `/plan` Success Criteria Gate reference this file so it is maintained once.
+
+Each criterion names the command that proves it. Use `verify: <command>` (exit 0 = pass) when a command can prove it without human judgment, or `verify: manual <steps>` when only a human can. Reject vacuous criteria like "make it work" — rewrite them as something provable. Fold functional, non-functional, and quality-gate requirements into concrete criteria.
+
+Embed this block verbatim in the plan's `## Success Criteria` section, filling in the placeholders:
+
+```success-criteria
+GOAL: <one sentence describing the intended end state>
+
+SUCCESS CRITERIA:
+- <observable criterion> | verify: <shell command; exit 0 = pass>
+- <observable criterion> | verify: manual <numbered human steps>
+
+NON-GOALS:
+- <explicitly out of scope>
+
+VERIFICATION COMMAND: <the non-manual verify commands above joined into one runnable command (e.g. with &&); exit 0 = all green>
+```