@therocketcode/gsd-core 1.4.0

package/gsd-core/workflows/model-domain.md

@@ -0,0 +1,162 @@
+<purpose>
+Establish strategic Domain-Driven Design foundations for a greenfield project: a shared ubiquitous language and a subdomain distillation (core/supporting/generic), with optional bounded contexts via lightweight event storming. Runs after new-project, before architecture. Produces `.planning/DOMAIN-MODEL.md` — the single complexity assessment that later parameterizes architecture and test strategy. This workflow captures the PROBLEM (domain); it must never prescribe a solution (architecture).
+</purpose>
+
+<required_reading>
+@~/.claude/gsd-core/references/domain-modeling.md
+@~/.claude/gsd-core/templates/domain-model.md
+</required_reading>
+
+<process>
+
+## Step 1: Initialize
+
+```bash
+_GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; GSD_TOOLS="${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}"; if [ -f "$GSD_TOOLS" ]; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif command -v gsd-tools >/dev/null 2>&1; then GSD_TOOLS="$(command -v gsd-tools)"; gsd_run() { "$GSD_TOOLS" "$@"; }; elif [ -f "$HOME/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="$HOME/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH. Run: npx -y @therocketcode/gsd-core@latest --claude --local" >&2; exit 1; fi
+COMMIT_DOCS=$(gsd_run query config-get commit_docs 2>/dev/null || echo "true")
+RESPONSE_LANG=$(gsd_run query config-get response_language 2>/dev/null || true)
+ls .planning/PROJECT.md >/dev/null 2>&1 && echo "PROJECT_FOUND" || echo "NO_PROJECT"
+```
+
+**If `NO_PROJECT`:** Stop and display:
+```
+No project found (.planning/PROJECT.md is missing).
+Run /gsd:new-project first, then /gsd:model-domain.
+```
+Exit.
+
+**If `RESPONSE_LANG` is non-empty:** all user-facing text MUST be in that language. Technical terms, code, file paths, and the `core/supporting/generic` labels stay in English.
+
+**Text mode** (`--text` flag OR `workflow.text_mode: true`): replace every `AskUserQuestion` call below with a plain-text numbered list and read the user's number/freeform reply. (See the inline text-mode example in Step 3.)
+
+## Step 2: Load context (internal grounding — do not show the user yet)
+
+```bash
+cat .planning/PROJECT.md 2>/dev/null || true
+cat .planning/REQUIREMENTS.md 2>/dev/null || true
+cat .planning/ROADMAP.md 2>/dev/null || true
+```
+
+**Read `@~/.claude/gsd-core/references/domain-modeling.md` now** — it defines the strategic-vs-tactical split, the core/supporting/generic criteria, and the misclassification check you will apply.
+
+From the project docs, build an internal draft:
+- What problem domain is this? What are the candidate capabilities/areas (from REQUIREMENTS.md)?
+- Which nouns/verbs recur (candidate ubiquitous-language terms)?
+- Are there distinct business areas or user roles (candidate subdomains)?
+
+**Check for an existing model:**
+```bash
+ls .planning/DOMAIN-MODEL.md >/dev/null 2>&1 && echo "EXISTS" || echo "NEW"
+```
+If `EXISTS` and not `--auto`: ask (AskUserQuestion, header "Domain") whether to **Update** (refresh), **View** (show then Update/Skip), or **Skip** (keep existing — exit with: "Existing DOMAIN-MODEL.md preserved. Next: /gsd:plan-phase"). If `--auto`: update in place.
+
+## Step 3: Ubiquitous language
+
+Goal: capture the team's actual words (not textbook terms), ~8–15 core terms, conflicts surfaced.
+
+**`--auto` mode:** synthesize the glossary from PROJECT.md/REQUIREMENTS.md recurring terms; skip to Step 4.
+
+**Interactive:** open with your internal draft, then refine. Use `AskUserQuestion`:
+- header: "Language"
+- question: "I drafted these core terms from your project: [list 5–8 with one-line definitions]. Which need fixing, and what's missing?"
+- options: "They're right — add more", "Some are wrong (I'll correct)", "Let me describe the vocabulary from scratch"
+
+Then probe, one thread at a time:
+- "When you say *[term]*, what exactly do you mean — and who uses that word (team, users, both)?"
+- "Is *[A]* the same as *[B]*, or different?" (a word that means two things → flag as a context-boundary signal)
+- "What do you call *[recurring action]*?"
+
+Continue 2–3 rounds until ~8–15 terms each have a definition + usage context. Record conflicts/polysemes explicitly.
+
+**Text-mode form of an AskUserQuestion (use this shape whenever `--text`):**
+```
+Language — I drafted these terms: [list]. What needs fixing?
+  1. They're right — add more
+  2. Some are wrong (I'll correct)
+  3. Let me describe the vocabulary from scratch
+Reply with a number, or just tell me the corrections.
+```
+
+## Step 4: Subdomain distillation (the pivotal step)
+
+For each candidate area, classify it and **capture the rationale**. Apply the misclassification check from the reference.
+
+For each area, use `AskUserQuestion` (header = the area name):
+- question: "Is *[area]* where you compete and win, something you need but isn't your edge, or a commodity every product has?"
+- options:
+  - "Core — we differentiate here" (→ build in-house, invest)
+  - "Supporting — needed, not our edge" (→ build simply / buy-and-extend)
+  - "Generic — commodity" (→ buy / off-the-shelf / library)
+
+**Apply these checks before finalizing each classification (state them to the user when they apply):**
+1. **Differentiation — not difficulty — decides Core.** If the user justifies Core by *difficulty, criticality, security, risk, or regulatory burden* rather than by competitive differentiation, test it: "Is this actually your competitive advantage, or a hard/critical-but-standard problem (e.g., tax, auth, encryption, compliance) you could buy?" If standard → **Generic (buy)**, not core. Critical ≠ differentiating; regulated ≠ differentiating.
+2. **CRUD that will grow.** Before accepting Generic/CRUD, ask: "Will this accumulate real business rules and invariants over time, or stay simple data-in/data-out?" If it will grow → mark it **emerging Supporting** (the default for growing areas), not generic. It is Core only if it is itself the competitive differentiator — and there is normally exactly one of those.
+3. **Generic ≠ low quality.** Note to the user that "generic" means *not differentiating*, not *low effort*.
+
+Record each subdomain's name, type, one-line description, rationale, and a rough complexity (low/medium/high). You should end with exactly **one** clearly-named core domain in most cases — if the user names many "core" areas, push back (anti-sprawl): "Which ONE is the real competitive core?"
+
+For the single core domain only, capture in one line **what "winning" means** — the decision dimensions the core optimizes (e.g., "best match = price × reliability × lane-fit") — NOT the algorithm or any implementation. This sharpens the core for the architecture and planning phases.
+
+## Step 5: Bounded contexts (optional — only if `--event-storming`)
+
+If `--event-storming` is NOT set: write in DOMAIN-MODEL.md "Bounded Contexts: deferred — single context assumed; planning will refine if boundaries emerge." Skip to Step 6.
+
+If set, run a **Big-Picture** pass (timeline of events, not aggregates):
+1. Ask (AskUserQuestion or text list) for the major domain events: "What significant things *happen* in this system? (e.g., 'Order Placed', 'Payment Captured', 'Shipment Dispatched')". Collect 5–10.
+2. For each event ask: "Who triggers it? Who reacts? What decision follows?"
+3. Group events by actor/responsibility. Each cluster = a candidate bounded context. Boundaries fall where the **language changes** or the **rate of change** differs.
+4. If boundaries are unclear, say so and **defer** them. Do NOT drill into aggregates (that's tactical, out of scope here).
+
+## Step 6: Write DOMAIN-MODEL.md
+
+Render `@~/.claude/gsd-core/templates/domain-model.md` (fill `[DATE]` with today's date and `[PROJECT_TITLE]` from PROJECT.md), filling:
+- **Ubiquitous Language** table (term, definition, used-by, aliases/confusions)
+- **Subdomains** table + the Core/Supporting/Generic groupings, each with rationale; note the misclassification check was applied
+- **Bounded Contexts** (filled or explicitly deferred)
+- **Notes for downstream phases** — one line for architecture (e.g., "Core 'X' is high-complexity → expect a richer domain model; rest is CRUD") plus deferred boundaries. **Any polyseme / language conflict flagged in Step 3 MUST appear here**, even when bounded contexts are deferred — it is a candidate context boundary.
+
+Write to `.planning/DOMAIN-MODEL.md`. **Do not include any architecture recommendation** — only the domain.
+
+## Step 7: Commit
+
+```bash
+if [ "$COMMIT_DOCS" = "true" ]; then
+  gsd_run query commit "docs: add domain model (ubiquitous language + subdomain distillation)" --files .planning/DOMAIN-MODEL.md
+else
+  echo "DOMAIN-MODEL.md written but not committed (commit_docs is false)."
+fi
+```
+
+## Step 8: Wrap up
+
+Display (counts filled in):
+```
+DOMAIN-MODEL.md written — strategic domain foundation set.
+
+  Ubiquitous language: [N] terms ([C] conflicts flagged)
+  Subdomains: [N]  ([core] core · [supporting] supporting · [generic] generic)
+  Bounded contexts: [N]  (or "deferred")
+
+Next: /gsd:plan-phase   (planning will use the subdomain complexity to shape architecture and tests)
+```
+
+</process>
+
+<critical_rules>
+- **Strategic only.** Capture language + subdomains (+ optional contexts). Never prescribe architecture, never design aggregates — that is a later phase.
+- **Buy-vs-build is allowed; stacks are not.** Classifying a subdomain as buy / off-the-shelf / library is strategic and encouraged. Choosing architecture patterns, frameworks, or deployment topology is forbidden here — that is `recommend-architecture`.
+- Every subdomain classification MUST carry an explicit rationale, and the misclassification check (complex≠core, CRUD-that-grows, generic≠low-quality) MUST be applied.
+- Capture the team's language, not textbook definitions.
+- Anti-sprawl: aim for one clearly-named core domain; defer unclear context boundaries rather than inventing them.
+- Respect `commit_docs` and `response_language`.
+</critical_rules>
+
+<success_criteria>
+- Project context loaded (PROJECT.md/REQUIREMENTS.md) before questioning
+- Ubiquitous language captured (~8–15 terms) with definitions, usage, and conflicts
+- Every subdomain classified with rationale + misclassification check applied
+- Bounded contexts surfaced (with `--event-storming`) or explicitly deferred
+- No architecture prescribed
+- DOMAIN-MODEL.md written from the template and committed (when commit_docs is true)
+- User directed to /gsd:plan-phase
+</success_criteria>

package/gsd-core/workflows/mvp-phase.md

@@ -0,0 +1,222 @@
+<purpose>
+Guide the user through MVP-mode planning for a phase. Prompts for an "As a / I want to / So that" user story, runs SPIDR splitting check on the story, writes the result to ROADMAP.md, and delegates to `/gsd plan-phase` (which auto-detects MVP via the roadmap mode field shipped in PRD Phase 1).
+</purpose>
+
+<required_reading>
+@~/.claude/gsd-core/references/user-story-template.md
+@~/.claude/gsd-core/references/spidr-splitting.md
+@~/.claude/gsd-core/references/planner-mvp-mode.md
+</required_reading>
+
+<runtime_note>
+**Copilot (VS Code):** Use `vscode_askquestions` wherever this workflow calls `AskUserQuestion`. They are equivalent.
+
+**TEXT_MODE fallback:** Set TEXT_MODE=true if `--text` is present in `$ARGUMENTS` OR `text_mode` from init JSON is true. When TEXT_MODE is active, replace every AskUserQuestion call with a plain-text numbered list and ask the user to type their choice number.
+</runtime_note>
+
+<process>
+
+## 1. Parse and validate phase argument
+
+Extract the phase number from `$ARGUMENTS` (integer or decimal like `2.1`). Optional flag: `--force` (allow operating on `in_progress` / `completed` phases).
+
+If no argument:
+```
+ERROR: Phase number required
+Usage: /gsd mvp-phase <phase-number>
+Example: /gsd mvp-phase 1
+Example: /gsd mvp-phase 2.1
+```
+Exit.
+
+Normalize per `@~/.claude/gsd-core/references/phase-argument-parsing.md` (zero-pad integer phases to two digits).
+
+## 2. Validate phase exists and check status
+
+```bash
+_GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; GSD_TOOLS="${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}"; if [ -f "$GSD_TOOLS" ]; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif command -v gsd-tools >/dev/null 2>&1; then GSD_TOOLS="$(command -v gsd-tools)"; gsd_run() { "$GSD_TOOLS" "$@"; }; elif [ -f "$HOME/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="$HOME/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH. Run: npx -y @therocketcode/gsd-core@latest --claude --local" >&2; exit 1; fi
+PHASE_INFO=$(gsd_run query roadmap.get-phase "${PHASE}")
+PHASE_FOUND=$(echo "$PHASE_INFO" | jq -r '.found')
+PHASE_NAME=$(echo "$PHASE_INFO" | jq -r '.phase_name')
+PHASE_GOAL=$(echo "$PHASE_INFO" | jq -r '.goal')
+PHASE_MODE=$(echo "$PHASE_INFO" | jq -r '.mode // ""')
+PHASE_COMPLETE=$(echo "$PHASE_INFO" | jq -r '.roadmap_complete // false')
+
+ANALYZE=$(gsd_run query roadmap.analyze)
+if [[ "$ANALYZE" == @file:* ]]; then ANALYZE=$(cat "${ANALYZE#@file:}"); fi
+DISK_STATUS=$(echo "$ANALYZE" | jq -r --arg p "$PHASE" '.phases[] | select((.phase_number|tostring)==$p) | .disk_status' | head -1)
+if [[ "$DISK_STATUS" == "complete" || "$PHASE_COMPLETE" == "true" ]]; then
+  STATUS="completed"
+elif [[ "$DISK_STATUS" == "planned" || "$DISK_STATUS" == "partial" ]]; then
+  STATUS="in_progress"
+else
+  STATUS="not_started"
+fi
+```
+
+If `PHASE_FOUND` is `false`: error and exit. Suggest `/gsd add-phase` or `/gsd insert-phase` to create the phase first.
+
+**Status guard.** If the phase is `in_progress` (has plans but not complete) or `completed`, refuse unless `--force` is in `$ARGUMENTS`:
+
+```text
+ERROR: Phase ${PHASE} is currently ${STATUS}.
+Converting an active or completed phase to MVP mode mid-flight will
+invalidate any existing plans and summaries.
+
+To proceed anyway: /gsd mvp-phase ${PHASE} --force
+```
+
+**Already-MVP guard.** If `PHASE_MODE` is already `mvp`, surface this and ask whether to re-prompt the user story or abort:
+
+> "Phase ${PHASE} is already in MVP mode with goal: «${PHASE_GOAL}». Re-run user-story prompts and SPIDR check?"
+
+Use `AskUserQuestion` with options [Re-prompt / Abort]. On Abort, exit cleanly. On Re-prompt, proceed.
+
+## 3. User story prompts
+
+Run three sequential `AskUserQuestion` calls. Each is free-text. After all three, assemble into the canonical sentence per `@~/.claude/gsd-core/references/user-story-template.md`:
+
+**Prompt 1 — As a:**
+> "As a [user role]?"
+> (Examples: "new user", "admin", "signed-in customer", "API consumer")
+
+**Prompt 2 — I want to:**
+> "I want to [capability]?"
+> (Examples: "register and log in", "upload a CSV", "see my dashboard")
+
+**Prompt 3 — So that:**
+> "So that [outcome]?"
+> (Examples: "I can access my account", "I can bulk-import contacts", "I can see at a glance what needs attention")
+
+Assemble:
+
+```
+USER_STORY="As a ${ROLE}, I want to ${CAPABILITY}, so that ${OUTCOME}."
+```
+
+If any of the three answers is empty or whitespace-only, error and re-prompt that single field. Do NOT proceed with a partial story.
+
+**Validate via the centralized User Story validator.** The verb owns the canonical regex `/^As a .+, I want to .+, so that .+\.$/` and surfaces per-error guidance:
+
+```bash
+USER_STORY_RESULT=$(gsd_run query user-story.validate --story "$USER_STORY")
+if [ "$(echo "$USER_STORY_RESULT" | jq -r '.valid')" != "true" ]; then
+  echo "$USER_STORY_RESULT" | jq -r '.errors[]' >&2
+  # Re-prompt the offending field(s) per surfaced errors, then re-run validation.
+  # Do not abort the workflow on first invalid draft.
+  RE_PROMPT_USER_STORY=true
+fi
+```
+
+This guarantees the goal stored in ROADMAP.md will satisfy the same guard the verifier applies later.
+If `RE_PROMPT_USER_STORY=true`, re-run only the offending prompt field(s), rebuild `USER_STORY`, and validate again before continuing.
+
+## 4. SPIDR splitting check
+
+Run the SPIDR rules from `@~/.claude/gsd-core/references/spidr-splitting.md`. Briefly:
+
+**Trigger evaluation.** Check the assembled `USER_STORY` against the four size signals from the reference (compound capabilities, multi-actor, length > 120 chars, vague capability). If none fire, **skip SPIDR** entirely — go to step 5.
+
+**If SPIDR triggers.**
+
+a) Restate the story to the user:
+
+> "Your story: «${USER_STORY}»
+>
+> This story has [signal description, e.g., 'two compound capabilities joined by and']. Splitting it into multiple phases will produce a cleaner Walking Skeleton and reduce the risk of mid-phase scope creep.
+>
+> Want to walk through SPIDR splitting?"
+
+Use `AskUserQuestion` with options [Yes, walk through SPIDR / No, proceed with the story as-is].
+
+If "No": skip SPIDR, go to step 5.
+
+If "Yes": continue to (b).
+
+b) Ask which SPIDR axis fits best:
+
+> "Which axis best fits how to split this story?"
+
+Use `AskUserQuestion` with the five options from `spidr-splitting.md` (Spike / Paths / Interfaces / Data / Rules). Each option includes its targeted question as the description so the user can pick by understanding what each axis means.
+
+c) Walk through the chosen axis with **one** targeted question (not all five). For example, if the user picked "Paths":
+
+> "Does this feature have a happy path and one or more error/edge paths?"
+
+Free-text response. Workflow parses to identify the split.
+
+d) Produce a split proposal. Example:
+
+> "Proposed split (Paths axis):
+> - **Phase ${PHASE} (this one):** Happy path — ${HAPPY_STORY}
+> - **Phase ${PHASE+1} (new):** Edge case — ${EDGE_STORY}
+>
+> Accept this split?"
+
+Use `AskUserQuestion` [Accept / Modify / Reject].
+
+- **Accept**: `USER_STORY` becomes the first split's story (`${HAPPY_STORY}` in the example). Surface the remaining splits as a list of `/gsd add-phase` invocations the user can run after this command completes — do NOT auto-create the new phases (preserve user control over numbering).
+- **Modify**: re-prompt the splits one more time, then accept or reject.
+- **Reject**: revert `USER_STORY` to the original, proceed without splitting.
+
+## 5. Update ROADMAP.md
+
+Read `ROADMAP.md`. Find the section for `Phase ${PHASE}`. Apply two edits:
+
+**Edit 1 — Update Goal line.**
+
+Find: `**Goal:** ${OLD_GOAL_TEXT}`
+Replace with: `**Goal:** ${USER_STORY}`
+
+**Edit 2 — Insert Mode line.**
+
+If `**Mode:**` already exists in the section (replacing or re-running), update it to `**Mode:** mvp`.
+If `**Mode:**` does not exist, insert `**Mode:** mvp` on the line immediately after `**Goal:**`.
+
+Show the user a unified diff (lines being changed) and ask:
+
+> "Apply these changes to ROADMAP.md?"
+
+Use `AskUserQuestion` [Apply / Cancel]. On Cancel, exit without writing.
+
+On Apply, write the updated `ROADMAP.md` atomically (read-edit-write).
+
+## 6. Verify the write
+
+```bash
+NEW_MODE=$(gsd_run query roadmap.get-phase "${PHASE}" --pick mode)
+NEW_GOAL=$(gsd_run query roadmap.get-phase "${PHASE}" --pick goal)
+```
+
+Assert:
+- `NEW_MODE` equals `mvp`
+- `NEW_GOAL` equals the assembled user story
+
+If either assertion fails, surface the discrepancy to the user and exit. Do not proceed to plan-phase delegation with a half-applied write.
+
+## 7. Delegate to /gsd plan-phase
+
+Invoke `/gsd plan-phase ${PHASE}` (no flags). Phase 1's MVP_MODE resolution chain (CLI flag → roadmap mode → config → false) will detect the new `**Mode:** mvp` line and run plan-phase in vertical-slice mode automatically.
+
+The Walking Skeleton gate (also from Phase 1) will fire automatically if `${PHASE} == "01"` and there are zero prior phase summaries.
+
+## 8. Surface deferred phase splits (if any)
+
+If SPIDR produced a split in step 4, append a final user-facing message:
+
+> "**SPIDR split deferred phases.**
+>
+> Your original story was split. The first slice is now planned via plan-phase.
+> To create the remaining slice(s) as new phases, run:
+>
+> - `/gsd add-phase` — for the next slice: «${SPLIT_2_STORY}»
+> - `/gsd add-phase` — for the next slice: «${SPLIT_3_STORY}»
+>
+> Each will be added to the end of the current milestone. You can then run
+> `/gsd mvp-phase <new-phase-number>` on each to plan them as MVP slices."
+
+## 9. Exit
+
+Workflow ends. The phase is now in MVP mode with a planned PLAN.md, optionally with deferred follow-up phases surfaced for the user.
+
+</process>