Add testplan artifact with downstream validation gates

design/README.md

@@ -35,10 +35,10 @@ graph TD
 | Ingest | `/ingest` | Read PRD, explore codebase | `01-context.md` |
 | Research | `/research` | Investigate problem space, solutions, standards | `02-research.md` |
 | Design | `/draft` | Draft design document | `03-design.md` |
-| Decompose | `/decompose` | Break into epics and stories | `04-epics.md`, `05-stories/`, `06-coverage.md` |
+| Decompose | `/decompose` | Break into epics and stories | `04-epics.md`, `05-stories/`, `06-coverage.md`, `07-testplan.md` |
 | Revise | `/revise` | Incorporate feedback | Updated design and/or stories |
-| Publish | `/publish` | Post design doc as GitHub PR | `07-pr-description.md` |
-| Respond | `/respond` | Address reviewer comments | `08-review-responses.md` |
+| Publish | `/publish` | Post design doc as GitHub PR | `08-pr-description.md` |
+| Respond | `/respond` | Address reviewer comments | `09-review-responses.md`, updated `07-testplan.md` / stories / `06-coverage.md` |
 | Sync | `/sync` | Sync Jira epics and stories | `sync-manifest.json` |
 
 ## Typical Flow
@@ -63,7 +63,7 @@ graph TD
 /decompose
   → breaks design into epics and stories
   → validates coverage against PRD requirements
-  → writes 04-epics.md, 05-stories/ (epics + stories), 06-coverage.md
+  → writes 04-epics.md, 05-stories/ (epics + stories), 06-coverage.md, 07-testplan.md
 
 /revise
   → user reviews, requests changes to design and/or decomposition
@@ -73,17 +73,19 @@ graph TD
 /publish
   → commits design document to feature branch in docs repo
   → creates draft GitHub PR
-  → writes 07-pr-description.md
+  → writes 08-pr-description.md
 
 /respond
   → fetches PR review comments
   → proposes responses (user approves before posting)
-  → updates design document if needed
+  → updates design document and testplan if needed
+  → cascades testplan changes to story Test Case References and coverage matrix
   → repeatable
 
 /sync
   → previews all Jira operations (dry run)
   → syncs epics and stories — creates new, updates changed, closes removed
+  → resolves testplan story references to Jira keys in docs repo
   → maintains sync-manifest.json with content hashes
 ```
 
@@ -109,8 +111,9 @@ Jira issue:
     epic-2/
       story-01-deploy-config.md        (→ Jira Story)
   06-coverage.md
-  07-pr-description.md
-  08-review-responses.md
+  07-testplan.md
+  08-pr-description.md
+  09-review-responses.md
   publish-metadata.json
   provenance.json
   sync-manifest.json

design/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: design
-version: 0.5.0
+version: 0.6.0
 description: >-
   Design-and-decompose workflow that takes a PRD, researches the problem space,
   drafts a technical design document, decomposes work into Jira-ready epics and

design/decomposition-review.md

@@ -7,8 +7,8 @@ whether the reviewer is a subagent or the decomposer performing inline
 self-review.
 
 The reviewer receives the PRD and the decomposition artifacts (epics,
-stories, coverage matrix) but intentionally does **not** receive the
-design document. This is the independence property: the reviewer
+stories, coverage matrix, testplan) but intentionally does **not**
+receive the design document. This is the independence property: the reviewer
 evaluates what the artifacts actually say, not what the decomposer
 intended. If a story's acceptance criteria are unclear without
 cross-referencing the design document, that is a real finding — the
@@ -99,14 +99,32 @@ impact:
    story fall back to "manual validation" or "document procedure for QE"
    where an automated test could be written?
 
-5. **Integration Stability** — Would implementing all stories in
+5. **Testplan Quality** — Does the testplan (`07-testplan.md`) cover
+   every FR and NFR that has implementing stories? Are test case IDs
+   correctly anchored to PRD requirement IDs (`TC-FR1-01`, not arbitrary
+   sequences)? Does each test case have concrete preconditions, numbered
+   scenario steps, and observable expected results — or do they contain
+   banned vague phrases ("works correctly", "handles appropriately", "is
+   validated", etc.)? Are expected results concrete enough to write an
+   assertion against (specific values, status codes, state changes)? Are
+   priorities assigned
+   consistently (critical for core workflows, not everything marked
+   high)? Do the `Test Case References` in story files match the
+   testplan's Story field? Does the coverage matrix's Test Cases column
+   match the testplan? Are there requirements with stories but no test
+   cases (testplan gaps)? Does every non-`[DOCS]` story AC appear in
+   at least one test case's AC field? Are there story ACs with no test
+   case mapping (AC-level gaps)? (`[DOCS]` stories are excluded from
+   testplan derivation.)
+
+6. **Integration Stability** — Would implementing all stories in
    dependency order produce a working feature end-to-end? Does any
    integration work fall between stories — work that is needed but not
    captured in any story? Are story dependencies documented and
    complete? Does each story leave the system in a stable state (all
    tests passing after merge)?
 
-6. **Documentation** — Do `[DOCS]` stories use the `[DOCS]` template
+7. **Documentation** — Do `[DOCS]` stories use the `[DOCS]` template
    (Documentation Scope and Documentation Inputs instead of
    Implementation Guidance and Testing Approach)? Does the Documentation
    Scope describe what the reader needs to understand without prescribing
@@ -123,7 +141,8 @@ Each finding must include:
 - **File:** artifact file path (e.g.,
   `05-stories/epic-1/story-02-add-validation.md`)
 - **Section:** section within the artifact (e.g., "Acceptance Criteria",
-  "Dependencies", "Testing Approach", "Documentation Scope")
+  "Dependencies", "Testing Approach", "Test Case References",
+  "Documentation Scope")
 - **Severity:** CRITICAL | HIGH | MEDIUM | LOW
 - **Category:** one of the evaluation criteria above
 - **Issue:** what the problem is
@@ -132,15 +151,16 @@ Each finding must include:
 Findings that cannot cite a specific file and section in the actual
 artifacts must be discarded — they indicate hallucinated references.
 Coverage matrix findings should cite `06-coverage.md` and the specific
-row or gap.
+row or gap. Testplan findings should cite `07-testplan.md` and the
+specific requirement section or test case entry.
 
 ## Severity Definitions
 
 | Severity | Meaning | Action |
 |----------|---------|--------|
-| CRITICAL | Would cause incorrect implementation — missing requirements, contradictory acceptance criteria, broken dependency chain, scope reduction | Must fix before presenting |
-| HIGH | Would cause rework — story too large to review in a single PR, missing testing commitment, integration gap between stories, `[QE]` story duplicating `[DEV]` test scope | Should fix before presenting |
-| MEDIUM | Would reduce clarity — vague acceptance criteria, imprecise implementation guidance or documentation scope, sizing concerns, minor coverage matrix inconsistencies | Fix if it adds value |
+| CRITICAL | Would cause incorrect implementation — missing requirements, contradictory acceptance criteria, broken dependency chain, scope reduction, missing test cases for requirements that have implementing stories | Must fix before presenting |
+| HIGH | Would cause rework — story too large to review in a single PR, missing testing commitment, integration gap between stories, `[QE]` story duplicating `[DEV]` test scope, test case with vague preconditions or non-observable expected result | Should fix before presenting |
+| MEDIUM | Would reduce clarity — vague acceptance criteria, imprecise implementation guidance or documentation scope, sizing concerns, minor coverage matrix inconsistencies, test case priority inconsistency, minor testplan-to-coverage matrix mismatch | Fix if it adds value |
 | LOW | Structural improvements — naming consistency, ordering suggestions, documentation clarity | Fix only if clearly valuable |
 
 ## Validation Rules

design/skills/controller.md

@@ -22,7 +22,7 @@ executing phases and handling transitions between them.
    Draft the design/architecture document using the template and section guidance.
 
 4. **Decompose** (`/decompose`) — `decompose.md`
-   Break the design into Jira-ready epics and stories with a coverage matrix.
+   Break the design into Jira-ready epics and stories with a testplan and coverage matrix.
 
 5. **Revise** (`/revise`) — `revise.md`
    Incorporate user feedback into the design document and/or task breakdown. Repeatable.
@@ -56,11 +56,12 @@ the source repo (this directory should be gitignored in the source repo):
 | Provenance log | `provenance.json` | `/draft`, `/revise`, `/respond` |
 | Epic metadata | `04-epics.md` | `/decompose`, `/revise` |
 | Epic files | `05-stories/epic-{N}-{slug}.md` | `/decompose`, `/revise` |
-| Story files | `05-stories/epic-{N}/story-{NN}-{slug}.md` | `/decompose`, `/revise` |
-| Coverage matrix | `06-coverage.md` | `/decompose`, `/revise` |
-| PR description | `07-pr-description.md` | `/publish` |
+| Story files | `05-stories/epic-{N}/story-{NN}-{slug}.md` | `/decompose`, `/revise`, `/respond` |
+| Coverage matrix | `06-coverage.md` | `/decompose`, `/revise`, `/respond` |
+| Testplan | `07-testplan.md` | `/decompose`, `/revise`, `/respond` |
+| PR description | `08-pr-description.md` | `/publish` |
 | Publish metadata | `publish-metadata.json` | `/publish` |
-| Review responses | `08-review-responses.md` | `/respond` |
+| Review responses | `09-review-responses.md` | `/respond` |
 | Jira sync manifest | `sync-manifest.json` | `/sync` |
 
 ### Docs repo configuration