RFC: Three-level planning hierarchy (Initiative → Wave → Feature) on top of /mdd

[iKon85]

Status: CONCEPT / PROPOSAL — not yet battle-tested. Looking for feedback, not asking for merge.
This describes a planning layer we are currently prototyping on top of the Starter Kit's existing /mdd workflow. It works well for us so far on one real project, but several pieces (auto-status updates, multi-edition flow, mid-flight roadmap rewrites) are still open. Sharing it here as food for thought. Feedback, pushback, and counter-proposals very welcome.

(Would normally post this in GitHub Discussions, but Discussions are not enabled on the repo — happy to move it there if you'd like to turn them on.)

Context

We use the Starter Kit for medium-to-large projects (currently a test-management / analytics tool for SAP S/4HANA rollouts, among others). For a single feature, /mdd is great — document the feature, write test skeletons, implement TDD, verify. That holds up as long as you already know which feature you're tackling.

The moment a project is bigger than one feature (greenfield, or a significant new module inside an existing system), two levels above /mdd are missing:

1. How do you decompose a spec into meaningful releases?
2. How do you decompose a release into features?

This proposal adds those two levels as approval-gated, top-down planning, designed to prevent thrashing (no redesigns after code already exists) and to force a demonstrable checkpoint at every step.

The three levels at a glance

Level	Skill	Artifact	Scope
Initiative	/plan-initiative	.mdd/roadmap.md (new or extended)	Decomposes a spec into 2–6 Waves with a demo-state each
Wave	/plan-wave <wave-slug>	Updates the same .mdd/roadmap.md	Decomposes one wave into 2–8 features with optional research topics
Feature	/mdd (existing)	.mdd/docs/<NN>-<feature-name>.md + tests + code	Doc-first, TDD, live verification

Each level stops at the end and waits for approval — there is no auto-handoff to the next level.

Core concept: Demo-State

The load-bearing idea is a demo-state per wave — one sentence describing what a user can manually perform at the end of the wave. Example:

"User signs up, logs in, sees an empty dashboard."

Consequences:

• Waves are vertical slices (end-to-end), not horizontal layers ("all DBs first, all APIs second"). Every wave is releasable / demo-able on its own.
• The demo-state is the single acceptance criterion for wave completion — no fuzzy "Wave 2 is mostly done".
• The next wave may only start once the previous wave's demo-state has been manually verified. This is a real gate, not a nice-to-have.

Workflow (happy path)

Spec / requirements
        ↓
  /plan-initiative
  → .mdd/roadmap.md with 2–6 waves, demo-states, open product questions
        ↓  [user approval + open product questions answered]
        ↓
  /plan-wave wave-1
  → same file: wave 1 flipped to "active", features added, demo-state sharpened
        ↓  [user approval]
        ↓
  /mdd  (per feature)
  → .mdd/docs/NN-<feature>.md → test skeletons → build plan → TDD → verify
        ↓  [wave-1 demo verified manually → status "complete"]
        ↓
  /plan-wave wave-2   ...

Gates (deliberately hard to skip)

1. Open product questions before Wave 1. /plan-initiative collects everything the team must decide before kickoff (tech stack, auth model, hosting, data sources, stakeholder roles). /plan-wave wave-1 explicitly asks whether those are answered before feature decomposition.
2. Predecessor wave complete. /plan-wave wave-N reads .mdd/roadmap.md — if the wave that wave-N depends on is still planned or active, it stops and quotes the unmet demo-state back at the user.
3. Feature impact analysis (Phase 2 of /mdd). Mandatory gate at feature level — trace data flow, grep all usages of touched code, check app-wide consistency, before any doc or code is written.

Artifact structure

.mdd/roadmap.md (single source of truth for the top two levels)

# Roadmap: <ProjectName>

## Open product questions (before Wave 1)
- [ ] Auth model? (SSO vs. custom login)
- [ ] Database? (Supabase vs. self-hosted Postgres)

## Wave 1: Auth foundation
**Status:** active
**Demo-state:** User signs up, logs in, sees an empty dashboard.
**Depends on:** none

### Features
- [ ] auth-signup — signup flow with email verification
  - Research: none
- [ ] auth-login — login + session handling
  - Depends on: auth-signup
  - Research: none
- [ ] dashboard-shell — empty dashboard layout
  - Research: which routing pattern to use?

## Wave 2: User management
**Status:** planned
**Demo-state:** Admin creates a user, user list shows all created users.
**Depends on:** Wave 1 (login works)

### Features
_Filled in via `/plan-wave wave-2` when the wave starts._

Status values: planned → active → complete.

.mdd/docs/<NN>-<feature>.md (per feature, existing)

Frontmatter includes, among others: id, title, wave: <wave-slug> (optional — enables future auto-update of roadmap status when all features of a wave are complete), depends_on, source_files, test_files, known_issues.

Skill responsibilities (deliberately narrow)

/plan-initiative does not

• Name features (→ wave level)
• Pick file paths / code structure (→ feature level)
• Make tech decisions (→ parks them as open product questions)
• Auto-proceed to /plan-wave (always stop + approval)

/plan-wave does not

• Implement anything
• Write feature MDD docs (→ /mdd)
• Invent research topics to fill the field — if nothing's open, it reads none
• Start the wave if its predecessor is not yet complete

/mdd does not (existing rules)

• Write or code before Phase 2 (impact analysis) passes
• Move past the MDD doc without user approval
• Treat green unit tests as "done" — Definition of Done is happy path against real services

Why this split (the non-obvious parts)

1. Lazy refinement. /plan-initiative does not break waves down into features — that only happens when the wave actually starts. Otherwise you plan three months ahead for something you'll rethink anyway by the time wave 2 kicks off.
2. Approval gates instead of automation. Between every level there's a deliberate stop. In longer chains (Initiative → Wave → Feature → Code), every auto-handoff carries the risk that a misunderstanding propagates three levels deep before the user intervenes.
3. Demo-state as a semantic gate. Instead of steering by story points / velocity / burndown, steering happens via demo-state: either the wave is manually demoable, or it isn't done. No shades of grey.
4. One file (.mdd/roadmap.md) for the upper hierarchy. No separate folder per wave or per initiative — one document where status and structure grow together. Benefit: the whole project plan is visible and diffable on one page.

What we have not sharply solved yet (honest open points)

1. Auto-status update of waves. The wave: field in feature frontmatter is defined, but we don't yet have tooling that flips the wave status to complete when all its features are complete. Currently manual.
2. Multi-edition projects. The edition: Both | Frontend | Backend field exists, but we have no workflow for projects that need two editions in parallel (e.g. OSS + Enterprise).
3. Cross-wave feature dependencies. We currently model dependencies within a wave and between waves, not from a feature in wave 3 back onto a feature in wave 1. We haven't needed it so far because vertical slicing catches most of it — but it's a known gap.
4. Retro integration. /retro exists, but there is no automatic link between wave completion and retro trigger.
5. Roadmap migration for mid-flight changes. If wave 2 reveals that waves 3 and 4 need reshaping, there is no clean flow for it. Today: re-run /plan-initiative, merge manually.

Possible integration points for the Starter Kit (concrete suggestions)

• Treat plan-initiative, plan-wave, mdd as a trio in the README — each skill loses context when documented in isolation.
• Ship .mdd/roadmap.md as a template with an empty example and a comment block explaining the three status values.
• Optionally a /mdd-wave-status check that scans all wave: <x> features for a given slug and flips the wave status when they're all complete.
• In the /new-project flow, ask: "Is this a single-feature project or a multi-wave project?" — and only in the second case suggest /plan-initiative.

---

Happy to turn any of this into a PR if a direction sounds useful to you. For now: does this shape of the problem resonate? Would love your thoughts on the gates (especially whether the demo-state-as-gate is too rigid in practice), the "one file" vs. "folder per wave" tradeoff, and whether the open points above are things you'd want solved before this lands in the kit or after.

[TheDecipherist]

Thanks for this — seriously one of the most thought-through RFCs I've seen on a project this size. The demo-state concept especially is the kind of thing that sounds simple but changes how you think about shipping. Going to implement this. Here's the full direction we've planned out.

---

Approach: Everything stays under /mdd

Rather than separate skills, the entire hierarchy lives under a single entry point. One mental model, one place to look:

Sub-command	What it does
/mdd plan-initiative	Decomposes a spec into waves → creates .mdd/initiatives/<slug>.md
/mdd plan-wave <slug>	Decomposes one wave into features → creates .mdd/waves/<initiative>-wave-<N>.md
/mdd plan-execute <wave-slug>	Runs the full MDD feature flow per feature, sequentially with stops
/mdd plan-sync	Detects manual edits to initiative/wave files via hash → increments versions, flags affected waves
/mdd	Unchanged — still works standalone for single features
/mdd status	Updated to show initiatives + waves + features

Chain flow: After plan-initiative is approved, MDD asks "Want to plan Wave 1 now?" — if yes, runs plan-wave inline. After each wave is planned, asks "Want to plan Wave 2 now?". You can stop at any point and resume with /mdd plan-wave. Lazy refinement stays intact.

---

File structure

Three folders, one per level:

.mdd/
  initiatives/
    auth-system.md
  waves/
    auth-system-wave-1.md
    auth-system-wave-2.md
  docs/                    ← existing feature docs, completely unchanged
    01-auth-signup.md
  audits/

Feature docs get three new optional frontmatter fields. If absent, the existing /mdd flow is completely unaffected:

initiative: auth-system
wave: auth-system-wave-1
wave_status: planned      # planned | active | complete

Note: wave_status is intentionally separate from the existing status field which some docs use for authoring state — two different concepts, two different fields.

---

Initiative doc format

---
id: auth-system
title: Auth System
status: active            # planned | active | complete
version: 1                # auto-incremented by MDD on every update
hash: a3f5b2c1            # hash of file content excluding this line
created: 2026-04-15
---

# Auth System

## Overview
2-3 sentences on what this initiative delivers and why.

## Open Product Questions
- [ ] Auth model? (SSO vs. custom login)
- [ ] Session storage? (JWT vs. cookies)

## Waves
| Wave | File | Demo-state | Status |
|------|------|------------|--------|
| Wave 1 | waves/auth-system-wave-1.md | User signs up, logs in, sees empty dashboard | active |
| Wave 2 | waves/auth-system-wave-2.md | Admin creates a user, user list shows results | planned |

---

Wave doc format

---
id: auth-system-wave-1
title: "Wave 1: Auth Foundation"
initiative: auth-system
initiative_version: 1     # initiative version this wave was planned against
status: active            # planned | active | complete
depends_on: none          # or: auth-system-wave-1
demo_state: "User signs up, logs in, sees an empty dashboard."
version: 1                # auto-incremented by MDD on every update
hash: b2c9d1e4            # hash of file content excluding this line
created: 2026-04-15
---

# Wave 1: Auth Foundation

## Demo-State
User signs up, logs in, sees an empty dashboard.
*(This wave is not complete until this can be manually demonstrated.)*

## Features
| # | Feature | Doc | Status | Depends on |
|---|---------|-----|--------|------------|
| 1 | auth-signup | — | planned | — |
| 2 | auth-login | — | planned | auth-signup |
| 3 | dashboard-shell | — | planned | — |

## Open Research
- Which routing pattern to use for the dashboard?

The Doc column starts as — during plan-wave. plan-execute fills it in at Phase 3 (when the feature doc is created) and flips wave_status to active. At Phase 7 (verify), flips to complete. Both the feature doc frontmatter and wave doc table update in sync.

---

Gates — hard stops, not warnings

1. Before plan-wave — always reads initiative file fresh from disk first (not session memory — it may have been updated between waves). All open product questions must be checked off. MDD quotes the unchecked ones back if blocked.

2. Before plan-execute — the wave's depends_on predecessor must be complete. Hard stop with a clear message quoting the unmet demo-state.

3. Feature ordering within a wave — plan-execute validates the dependency graph before starting. If ordering is wrong:

✗ auth-login (feature 2) depends on auth-signup (feature 3) — but auth-signup comes after it.

Fix manually or auto-reorder?

Auto-reorder presents the proposed order for confirmation before touching anything.

4. Silent hash check — plan-wave and plan-execute run a hash check at startup. If a mismatch is detected: hard stop with "Initiative file has been manually edited. Run /mdd plan-sync first."

---

Execute flow — sequential, one feature at a time

plan-execute builds features one at a time with explicit confirmation between each:

1. Read wave doc, run all gate checks
2. For each feature: full MDD flow (doc → test skeletons → build plan → TDD → verify)
3. After Phase 3 (doc created): wave doc gets path + feature flips to active
4. After Phase 7 (verified): feature flips to complete in both feature doc and wave table
5. "Feature N done. Start Feature N+1?"
6. After all features: "Have you manually verified the demo-state? [demo-state text]"
7. Confirmed → wave flips to complete in both wave doc and initiative waves table

If plan-execute is interrupted mid-wave: re-running it reads wave_status from each feature doc, skips complete features, and resumes at the first active or planned one. If active but no doc exists yet (interrupted before Phase 3), restarts that feature from Phase 1.

---

Versioning and manual edit detection

The problem: if someone manually edits an initiative or wave markdown file, version numbers don't increment and completed waves don't get flagged for review.

The solution: both initiative and wave docs store a hash field (hash of full file content excluding the hash line itself). The version integer is human-readable; the hash is the detection mechanism.

/mdd plan-sync scans all initiative and wave files:

🔍 Plan sync detected changes:

  initiatives/auth-system.md       — manually edited (hash mismatch)
    → version 1 → 2
    → Wave 1 (complete) now behind — will prompt for review
    → Wave 2 (planned) unaffected

  waves/auth-system-wave-2.md      — manually edited (hash mismatch)
    → version 1 → 2

Apply these updates? (yes / no)

When the initiative version advances past a completed wave's initiative_version:

⚠️  Initiative updated (v1 → v2) since these waves were completed:
    - Wave 1: Auth Foundation (completed 2026-04-10)

Mark back to in_progress for review? (yes / no / skip)

yes → rolls back to in_progress | no → keeps complete, user takes responsibility | skip → continues without asking this session

---

/mdd status output

📊 MDD Status

Initiatives:  2 active, 1 complete
  → auth-system        [Wave 2/3 active]  "User can reset password"
  → billing-module     [Wave 1/2 active]  "User can view invoice"

Feature docs: 13 files in docs/
Last audit:   2026-03-01 (17 fixed, 3 deferred)
Test coverage: 94 unit tests, 12 E2E tests
Known issues:  3 tracked across 2 features

Run /mdd plan-initiative to start a new initiative.
Run /mdd plan-execute <wave-slug> to continue an active wave.

---

What we kept from your RFC

• Demo-state as the semantic gate for wave completion — unchanged
• Lazy refinement — plan-initiative does not name features, plan-wave does not implement
• No auto-handoff between levels — every transition is user-gated
• depends_on between waves as a hard stop
• One file per initiative/wave, not folders

What we changed or added

• Everything under /mdd rather than separate skills
• plan-wave always reads initiative fresh from disk regardless of how it was invoked
• Demo-state confirmation is honour system — the hard gate is between waves
• Feature ordering validated with offer to auto-reorder
• Initiative versioning (version + initiative_version on waves)
• Hash-based manual edit detection + /mdd plan-sync

---

Your open points

1. Auto-status flip
Solved. wave_status in each feature doc's frontmatter is updated in real time by plan-execute — planned → active when the doc is created (Phase 3), active → complete after verification (Phase 7). When all features in a wave show complete, MDD auto-detects it and triggers the demo-state prompt. No manual tracking needed.

2. Multi-edition projects
The edition field already exists on feature docs (Both | Frontend | Backend). The natural extension is adding edition to initiative and wave docs too, letting plan-execute filter features by edition — which would support running two editions of a wave in parallel. But we don't want to design this blind. How are you currently using multi-edition in practice? What does the workflow actually look like for you? Happy to spec it properly with your input before implementing.

3. Cross-wave feature dependencies
We think vertical slicing is the right answer here rather than building a cross-wave dependency graph. If Feature X in Wave 3 genuinely depends on Feature Y in Wave 1, that's a signal that Wave 3 should carry depends_on: wave-1 at the wave level — which is already supported. A feature-to-feature dependency across waves usually means the wave decomposition needs rethinking, not the tooling. We'd call this a design smell rather than a gap to fill. Curious if you've hit a real case where wave-level depends_on wasn't enough?

4. Retro integration
There's no /retro command in the starter kit — we don't want to assume what yours does. The hook point is obvious though: when a wave flips to complete, MDD could naturally prompt "Want to run a retro on this wave?". If you're willing to share what your /retro does, we'd love to make it a proper starter kit command with a wave completion trigger built in.

5. Mid-flight roadmap rewrites
plan-sync covers the detection side — if you manually edit the initiative file to reshape waves 3 and 4, it detects the hash mismatch, increments the version, and flags any completed waves that are now behind. The replan itself is still manual (edit the initiative, run plan-sync, review flagged waves) but MDD knows something changed and surfaces it explicitly. A guided replan flow could come later — for now we think the manual approach is fine, you know your project better than MDD does.

---

Not starting implementation until we hear back. Would love your thoughts on the plan-sync approach, the /mdd single entry point vs. separate skills, and anything we may have missed.