Skip to content

feat(cdt): add machine-verifiable acceptance criteria to plan template #113

@rube-de

Description

@rube-de

Part of #104

Context

CDT's plan template has a "Testing Strategy" section (plan-workflow.md:128-130) with prose descriptions: "Framework, scenarios, acceptance criteria." But there are no structured, machine-verifiable acceptance criteria that the dev phase can self-check without human oversight.

This is CDT's biggest risk in auto-task mode (no human gate). Sean Moran's research shows unstructured multi-agent systems amplify errors by 17x — the root cause is agents deviating from commitments and holding wrong expectations. Machine-verifiable acceptance criteria serve as the gate that a human reviewer would otherwise provide.

GitHub's Spec Kit and Addy Osmani's 70/30 rule both emphasize: specs with testable assertions, not prose.

Task

Add a structured "Acceptance Criteria" section to the plan template that the architect must fill with machine-verifiable assertions. Also add a "Three-Tier Boundaries" section for scope control.

Acceptance Criteria

  • VERIFY: Plan template includes ## Acceptance Criteria section with VERIFY: prefixed items
  • VERIFY: Architect prompt instructs: "Write acceptance criteria as testable assertions, not prose"
  • VERIFY: Plan template includes ## Boundaries section with green/yellow/red tiers
  • VERIFY: Dev-workflow parse step extracts acceptance criteria for verification in Final Verification (Step 7)
  • VERIFY: Testing Strategy section references acceptance criteria instead of duplicating them

Implementation Guide

Files to Modify

  • plugins/cdt/skills/cdt/references/plan-workflow.md — Add sections to plan template (after line 130), update architect prompt
  • plugins/cdt/skills/cdt/references/dev-workflow.md — Update Final Verification (Step 7, lines 235-241) to check acceptance criteria

Approach

  1. In plan template (plan-workflow.md, after Testing Strategy section, line 130), add:

    ## Acceptance Criteria
    [Machine-verifiable — each must be testable by an agent without human judgment]
    - [ ] VERIFY: [Function/endpoint/component] returns [expected] given [input]
    - [ ] VERIFY: [Performance target: specific numbers]
    - [ ] VERIFY: Zero regressions on existing test suite
    - [ ] VERIFY: [Additional criteria specific to this task]
    
    ## Boundaries
    - 🟢 Agent proceeds freely: [implementation details, naming, internal structure]
    - 🟡 Pause and confirm with lead: [new dependencies, public API changes, schema changes]
    - 🔴 Never without explicit approval: [deleting tests, modifying auth code, changing prod config]
  2. In architect prompt (plan-workflow.md, step 6 area), add:

    Acceptance criteria rule: Write every acceptance criterion as a testable assertion prefixed with "VERIFY:". Each must be verifiable by running a command, checking output, or inspecting code — never subjective prose like "improved performance" or "better UX".
    
  3. In dev-workflow.md, Step 7 "Final Verification" (lines 235-241), add:

    5. Check acceptance criteria from plan — verify each VERIFY: item passes
    
  4. Update Testing Strategy section in plan template to reference acceptance criteria:

    ## Testing Strategy
    [Framework, test types, QA scenarios]
    [Tests should validate the Acceptance Criteria above — each VERIFY item should map to at least one test]
    

Patterns to Follow

  • The PM skill's issue templates use VERIFY: prefix for acceptance criteria — same convention
  • The plan template's existing "Validation" section (line 134-135) is the PM verdict — acceptance criteria are different (spec-level, not approval-level)

Scope

In Scope

  • Adding Acceptance Criteria and Boundaries sections to plan template
  • Updating architect prompt with criteria-writing rules
  • Updating dev-workflow final verification to check criteria

Out of Scope

  • Automated acceptance criteria enforcement via scripts
  • Changing the PM validation flow
  • Adding Carmack's functional-vs-quality gate distinction (future enhancement)

Dependencies

Definition of Done

  • Implementation complete
  • bun scripts/validate-plugins.mjs passes
  • PR approved and merged
  • Epic checklist updated

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions