From 628e1e2f3270816cb98efa53d8c46e8665ba0a38 Mon Sep 17 00:00:00 2001 From: Tom Boucher Date: Mon, 1 Jun 2026 10:01:59 -0400 Subject: [PATCH] feat(#78): complete documentation and release MVP Vertical Slice mode Closes #78 Completes the Vertical MVP Slice Mode feature. Core implementation was already on `next`; this PR adds the missing COMMANDS.md docs, CHANGELOG entries, INVENTORY row, --tdd CLI fix, and changeset fragment. Co-Authored-By: Claude Sonnet 4.6 --- .changeset/silly-seals-parade.md | 5 ++++ CHANGELOG.md | 5 ++++ docs/COMMANDS.md | 39 ++++++++++++++++++++++++++- docs/INVENTORY.md | 1 + get-shit-done/workflows/plan-phase.md | 6 ++--- 5 files changed, 52 insertions(+), 4 deletions(-) create mode 100644 .changeset/silly-seals-parade.md diff --git a/.changeset/silly-seals-parade.md b/.changeset/silly-seals-parade.md new file mode 100644 index 000000000..30350fe79 --- /dev/null +++ b/.changeset/silly-seals-parade.md @@ -0,0 +1,5 @@ +--- +type: Added +pr: 576 +--- +**Vertical MVP Slice mode shipped** — `/gsd-plan-phase --mvp` organizes tasks as vertical feature slices (UI→API→DB) instead of horizontal layers; `--mvp --tdd` produces slices where every behavior-adding task starts with a failing test; `**Mode:** mvp` in ROADMAP.md auto-applies without the flag; `/gsd-mvp-phase ` guides story capture + SPIDR splitting + mode persistence; Walking Skeleton fires on Phase 1 of a new project; `verify-phase` generates user-flow-first UAT for MVP phases; `new-project` offers Vertical MVP vs Horizontal Layers mode choice. Also fixes a silent bug where `--tdd` on the CLI was a no-op (TDD_MODE was config-only; now the flag sets TDD_MODE directly). diff --git a/CHANGELOG.md b/CHANGELOG.md index 87af8e3ff..8ca3af111 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,11 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). ### Added +- **Vertical MVP Slice mode** — `--mvp` flag on `/gsd-plan-phase` switches the planner from horizontal layer decomposition to vertical feature-slice decomposition (UI→API→DB in one task sequence). On Phase 1 of a new project with no prior phase summaries, also emits `SKELETON.md` via Walking Skeleton mode. Composable with `--tdd`: `--mvp --tdd` produces vertical slices where every behavior-adding task starts with a failing test. Phase-level persistence via `**Mode:** mvp` in ROADMAP.md applies `--mvp` automatically without the flag. (#78) +- **`/gsd-mvp-phase` command** — guided MVP planning: prompts for a user story (`As a / I want to / So that`), runs SPIDR story-splitting check (Spike/Paths/Interfaces/Data/Rules axes), writes `**Mode:** mvp` to ROADMAP.md, then delegates to `/gsd-plan-phase`. (#78) +- **MVP-aware UAT framing in `verify-phase`** — when a phase has `mode: mvp`, the verifier generates a user-flow-first UAT script (walks the feature as a user would) before any technical checks. (#78) +- **MVP progress and stats display** — `progress` and `stats` commands show Walking Skeleton completion status and per-feature-slice status lines for MVP-mode phases. (#78) +- **Six MVP reference files** — `planner-mvp-mode.md`, `skeleton-template.md`, `user-story-template.md`, `spidr-splitting.md`, `execute-mvp-tdd.md`, `verify-mvp-mode.md` — loaded by the planner, executor, and verifier agents when MVP mode is active. (#78) - Milestone-prefixed phase ID convention (M-NN) for globally unique phase IDs within a project (#39) - `getMilestoneFromPhaseId()` and `getPhaseDirFromPhaseId()` helpers in core.cjs (#39) - W021 validation rule: fires when a phase ID's integer prefix mismatches its enclosing milestone section (#39) diff --git a/docs/COMMANDS.md b/docs/COMMANDS.md index e8402a1a3..717b9378f 100644 --- a/docs/COMMANDS.md +++ b/docs/COMMANDS.md @@ -155,9 +155,11 @@ Research, plan, and verify a phase. | `--validate` | Run state validation before planning begins | | `--bounce` | Run external plan bounce validation after planning (uses `workflow.plan_bounce_script`) | | `--skip-bounce` | Skip plan bounce even if enabled in config | +| `--mvp` | Vertical MVP mode — planner organizes tasks as feature slices (UI→API→DB) instead of horizontal layers. On Phase 1 of a new project with no prior phase summaries, also emits `SKELETON.md` (Walking Skeleton). Can be persisted on a phase via `**Mode:** mvp` in ROADMAP.md, which applies `--mvp` automatically without the flag. | +| `--tdd` | TDD mode — planner applies `type: tdd` to eligible behavior-adding tasks so each begins with a failing test. Composable with `--mvp`: `--mvp --tdd` produces vertical slices where every behavior-adding task starts red-green. | **Prerequisites:** `.planning/ROADMAP.md` exists -**Produces:** `{phase}-RESEARCH.md`, `{phase}-{N}-PLAN.md`, `{phase}-VALIDATION.md` +**Produces:** `{phase}-RESEARCH.md`, `{phase}-{N}-PLAN.md`, `{phase}-VALIDATION.md`; `{phase}/SKELETON.md` when Walking Skeleton mode fires **Research-only mode (`--research-phase `):** - No modifier: prompts `update / view / skip` if RESEARCH.md already exists. @@ -186,6 +188,8 @@ See [Package Legitimacy Gate in the User Guide](USER-GUIDE.md#package-legitimacy /gsd-plan-phase --research-phase 4 # Research only on phase 4 (prompts if RESEARCH.md exists) /gsd-plan-phase --research-phase 4 --view # Print existing RESEARCH.md, no spawn /gsd-plan-phase --research-phase 4 --research # Force-refresh research, no prompt +/gsd-plan-phase 1 --mvp # Vertical-slice plan for phase 1 +/gsd-plan-phase 1 --mvp --tdd # Vertical slices + failing test per behavior-adding task ``` --- @@ -435,6 +439,39 @@ CRUD for phases in ROADMAP.md — add, insert, remove, or edit phases with a sin --- +### `/gsd-mvp-phase` + +Guided MVP planning for a phase — prompts for a user story, runs SPIDR splitting check, writes `**Mode:** mvp` to ROADMAP.md, then delegates to `/gsd-plan-phase` (which auto-detects MVP mode via the roadmap field). + +| Argument | Required | Description | +|----------|----------|-------------| +| `N` | **Yes** | Phase number to convert to MVP mode (integer or decimal like `2.1`) | + +| Flag | Description | +|------|-------------| +| `--force` | Allow converting an `in_progress` or `completed` phase | + +**Prerequisites:** Phase must already exist in ROADMAP.md (created via `/gsd-new-project`, `/gsd-phase`, or `/gsd-phase --insert`). The command does not create new phases — it converts an existing phase. + +**Process:** +1. Prompts for "As a / I want to / So that" user story (three structured questions) +2. Validates story format against the canonical regex +3. Runs SPIDR splitting check — if the story is too large, walks through Spike/Paths/Interfaces/Data/Rules axes and offers to split into multiple phases +4. Writes `**Goal:** ` and `**Mode:** mvp` to the phase's ROADMAP.md section (with confirmation gate) +5. Delegates to `/gsd-plan-phase `, which detects MVP mode automatically + +**Walking Skeleton:** Auto-triggered when `--mvp` (or `mode: mvp`) is used on Phase 1 of a new project with no prior phase summaries. The planner produces `SKELETON.md` alongside `PLAN.md`. + +**Produces:** Updated ROADMAP.md, then all artifacts from `/gsd-plan-phase`; `SKELETON.md` when Walking Skeleton mode fires. + +```bash +/gsd-mvp-phase 1 # MVP planning for phase 1 +/gsd-mvp-phase 2.1 # MVP planning for a decimal phase +/gsd-mvp-phase 3 --force # Convert phase 3 even if in-progress +``` + +--- + ### `/gsd-validate-phase` Retroactively audit and fill Nyquist validation gaps. diff --git a/docs/INVENTORY.md b/docs/INVENTORY.md index 052340ca2..f46aea556 100644 --- a/docs/INVENTORY.md +++ b/docs/INVENTORY.md @@ -313,6 +313,7 @@ Full roster at `get-shit-done/references/*.md`. References are shared knowledge | `executor-examples.md` | Worked examples for the gsd-executor agent. | | `doc-conflict-engine.md` | Shared conflict-detection contract for ingest/import workflows. | | `execute-mvp-tdd.md` | Runtime gate semantics for execute-phase under MVP+TDD — pre-task failing-test verification, end-of-phase blocking review. | +| `mvp-concepts.md` | Cross-reference index for the six MVP-related reference files; maps each file to its purpose and which workflow loads it. | | `verify-mvp-mode.md` | UAT framing rules for MVP-mode phases — user-flow-first ordering, deferred technical checks, user-story-format guard. | ### Sketch References diff --git a/get-shit-done/workflows/plan-phase.md b/get-shit-done/workflows/plan-phase.md index ab5d33949..be73f40d6 100644 --- a/get-shit-done/workflows/plan-phase.md +++ b/get-shit-done/workflows/plan-phase.md @@ -99,7 +99,7 @@ The gate fires only on `Complete`. `Executed` and `Needs Review` are not gated ## 2. Parse and Normalize Arguments -Extract from $ARGUMENTS: phase number (integer or decimal like `2.1`), flags (`--research`, `--skip-research`, `--research-phase `, `--gaps`, `--skip-verify`, `--skip-ui`, `--prd `, `--ingest `, `--ingest-format `, `--reviews`, `--text`, `--bounce`, `--skip-bounce`, `--chunked`, `--mvp`, `--force` (override closed-phase gate, see §1.5)). +Extract from $ARGUMENTS: phase number (integer or decimal like `2.1`), flags (`--research`, `--skip-research`, `--research-phase `, `--gaps`, `--skip-verify`, `--skip-ui`, `--prd `, `--ingest `, `--ingest-format `, `--reviews`, `--text`, `--bounce`, `--skip-bounce`, `--chunked`, `--mvp`, `--tdd`, `--force` (override closed-phase gate, see §1.5)). **`--research-phase ` — research-only mode (#3042 + #3044).** When this flag is present, parse `` as the phase number (overrides any positional phase argument), set `RESEARCH_ONLY=true`, and treat the rest of this workflow as a research-dispatch only — the planner spawn (step 8), plan-checker, verification, gaps, bounce, and post-planning-gaps blocks all skip on `RESEARCH_ONLY`. Use this for cross-phase research, doc review before committing to a planning approach, and correction-without-replanning loops. Replaces the deleted `/gsd-research-phase` command. @@ -127,10 +127,10 @@ Set `TEXT_MODE=true` if `--text` is present in $ARGUMENTS OR `text_mode` from in ```bash MVP_FLAG_ARG="" if [[ "$ARGUMENTS" =~ (^|[[:space:]])--mvp([[:space:]]|$) ]]; then MVP_FLAG_ARG="--cli-flag"; fi +if [[ "$ARGUMENTS" =~ (^|[[:space:]])--tdd([[:space:]]|$) ]]; then TDD_MODE=true; fi ``` -Defer the `phase.mvp-mode` query until `PHASE` is finalized (after explicit argument parsing/fallback phase detection + validation). -The verb returns `true|false`. Full result also exposes `source` (`cli_flag` | `roadmap` | `config` | `none`) for diagnostics. The mode is **all-or-nothing per phase** (PRD decision Q1) — never selective per task. +Defer the `phase.mvp-mode` query until `PHASE` is finalized (after explicit argument parsing/fallback phase detection + validation). The verb returns `true|false`; full result also exposes `source` (`cli_flag` | `roadmap` | `config` | `none`) for diagnostics. Mode is **all-or-nothing per phase** (PRD decision Q1). **Walking Skeleton gate.** When `MVP_MODE=true` AND `phase_number == "01"` AND there are zero prior phase summaries (new project), the planner runs in **Walking Skeleton mode** (per PRD decision Q2 — new projects only). Detect with: