@bhargavvc/sdd-cc 1.30.1 → 1.35.0

package/sdd/workflows/stats.md

@@ -48,7 +48,7 @@ X/Y plans complete (Z%)
 - **Project age:** N days
 ```
 
-If no `.planning/` directory exists, inform the user to run `/sdd:new-project` first.
+If no `.planning/` directory exists, inform the user to run `/sdd-new-project` first.
 </step>
 
 </process>

package/sdd/workflows/transition.md

@@ -2,15 +2,15 @@
 
 **This is an INTERNAL workflow — NOT a user-facing command.**
 
-There is no `/sdd:transition` command. This workflow is invoked automatically by
+There is no `/sdd-transition` command. This workflow is invoked automatically by
 `execute-phase` during auto-advance, or inline by the orchestrator after phase
-verification. Users should never be told to run `/sdd:transition`.
+verification. Users should never be told to run `/sdd-transition`.
 
 **Valid user commands for phase progression:**
-- `/sdd:discuss-phase {N}` — discuss a phase before planning
-- `/sdd:plan-phase {N}` — plan a phase
-- `/sdd:execute-phase {N}` — execute a phase
-- `/sdd:progress` — see roadmap progress
+- `/sdd-discuss-phase {N}` — discuss a phase before planning
+- `/sdd-plan-phase {N}` — plan a phase
+- `/sdd-execute-phase {N}` — execute a phase
+- `/sdd-progress` — see roadmap progress
 
 </internal_workflow>
 
@@ -93,7 +93,7 @@ Append to the completion confirmation message (regardless of mode):
 Outstanding verification items in this phase:
 {list filenames}
 
-These will carry forward as debt. Review: `/sdd:audit-uat`
+These will carry forward as debt. Review: `/sdd-audit-uat`
 ```
 
 This does NOT block transition — it ensures the user sees the debt before confirming.
@@ -446,7 +446,7 @@ Next: Phase [X+1] — [Name]
 ⚡ Auto-continuing: Plan Phase [X+1] in detail
 ```
 
-Exit skill and invoke SlashCommand("/sdd:plan-phase [X+1] --auto ${SDD_WS}")
+Exit skill and invoke SlashCommand("/sdd-plan-phase [X+1] --auto ${SDD_WS}")
 
 **If CONTEXT.md does NOT exist:**
 
@@ -458,7 +458,7 @@ Next: Phase [X+1] — [Name]
 ⚡ Auto-continuing: Discuss Phase [X+1] first
 ```
 
-Exit skill and invoke SlashCommand("/sdd:discuss-phase [X+1] --auto ${SDD_WS}")
+Exit skill and invoke SlashCommand("/sdd-discuss-phase [X+1] --auto ${SDD_WS}")
 
 </if>
 
@@ -475,15 +475,15 @@ Exit skill and invoke SlashCommand("/sdd:discuss-phase [X+1] --auto ${SDD_WS}")
 
 **Phase [X+1]: [Name]** — [Goal from ROADMAP.md]
 
-`/sdd:discuss-phase [X+1] ${SDD_WS}` — gather context and clarify approach
+`/clear` then:
 
-<sub>`/clear` first → fresh context window</sub>
+`/sdd-discuss-phase [X+1] ${SDD_WS}` — gather context and clarify approach
 
 ---
 
 **Also available:**
-- `/sdd:plan-phase [X+1] ${SDD_WS}` — skip discussion, plan directly
-- `/sdd:research-phase [X+1] ${SDD_WS}` — investigate unknowns
+- `/sdd-plan-phase [X+1] ${SDD_WS}` — skip discussion, plan directly
+- `/sdd-research-phase [X+1] ${SDD_WS}` — investigate unknowns
 
 ---
 ```
@@ -500,15 +500,15 @@ Exit skill and invoke SlashCommand("/sdd:discuss-phase [X+1] --auto ${SDD_WS}")
 **Phase [X+1]: [Name]** — [Goal from ROADMAP.md]
 <sub>✓ Context gathered, ready to plan</sub>
 
-`/sdd:plan-phase [X+1] ${SDD_WS}`
+`/clear` then:
 
-<sub>`/clear` first → fresh context window</sub>
+`/sdd-plan-phase [X+1] ${SDD_WS}`
 
 ---
 
 **Also available:**
-- `/sdd:discuss-phase [X+1] ${SDD_WS}` — revisit context
-- `/sdd:research-phase [X+1] ${SDD_WS}` — investigate unknowns
+- `/sdd-discuss-phase [X+1] ${SDD_WS}` — revisit context
+- `/sdd-research-phase [X+1] ${SDD_WS}` — investigate unknowns
 
 ---
 ```
@@ -554,18 +554,18 @@ This workstream's phases are complete. Other workstreams are still active:
 
 Archive this workstream:
 
-`/sdd:workstreams complete {current_ws_name} ${SDD_WS}`
+`/sdd-workstreams complete {current_ws_name} ${SDD_WS}`
 
 See overall milestone progress:
 
-`/sdd:workstreams progress ${SDD_WS}`
+`/sdd-workstreams progress ${SDD_WS}`
 
 <sub>Milestone completion will be available once all workstreams finish.</sub>
 
 ---
 ```
 
-Do NOT suggest `/sdd:complete-milestone` or `/sdd:new-milestone`.
+Do NOT suggest `/sdd-complete-milestone` or `/sdd-new-milestone`.
 Do NOT auto-invoke any further slash commands.
 
 **Stop here.** The user must explicitly decide what to do next.
@@ -593,7 +593,7 @@ Phase {X} marked complete.
 ⚡ Auto-continuing: Complete milestone and archive
 ```
 
-Exit skill and invoke SlashCommand("/sdd:complete-milestone {version} ${SDD_WS}")
+Exit skill and invoke SlashCommand("/sdd-complete-milestone {version} ${SDD_WS}")
 
 </if>
 
@@ -610,9 +610,9 @@ Exit skill and invoke SlashCommand("/sdd:complete-milestone {version} ${SDD_WS}"
 
 **Complete Milestone {version}** — archive and prepare for next
 
-`/sdd:complete-milestone {version} ${SDD_WS}`
+`/clear` then:
 
-<sub>`/clear` first → fresh context window</sub>
+`/sdd-complete-milestone {version} ${SDD_WS}`
 
 ---
 

package/sdd/workflows/ui-phase.md

@@ -44,11 +44,11 @@ UI_ENABLED=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" config-get workflow.ui_p
 
 **If `UI_ENABLED` is `false`:**
 ```
-UI phase is disabled in config. Enable via /sdd:settings.
+UI phase is disabled in config. Enable via /sdd-settings.
 ```
 Exit workflow.
 
-**If `planning_exists` is false:** Error — run `/sdd:new-project` first.
+**If `planning_exists` is false:** Error — run `/sdd-new-project` first.
 
 ## 2. Parse and Validate Phase
 
@@ -65,7 +65,7 @@ PHASE_INFO=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" roadmap get-phase "${PHA
 **If `has_context` is false:**
 ```
 No CONTEXT.md found for Phase {N}.
-Recommended: run /sdd:discuss-phase {N} first to capture design preferences.
+Recommended: run /sdd-discuss-phase {N} first to capture design preferences.
 Continuing without user decisions — UI researcher will ask all questions.
 ```
 Continue (non-blocking).
@@ -83,6 +83,8 @@ Continue (non-blocking).
 UI_SPEC_FILE=$(ls "${PHASE_DIR}"/*-UI-SPEC.md 2>/dev/null | head -1)
 ```
 
+
+**Text mode (`workflow.text_mode: true` in config or `--text` flag):** 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. This is required for non-Claude runtimes (OpenAI Codex, Gemini CLI, etc.) where `AskUserQuestion` is not available.
 **If exists:** Use AskUserQuestion:
 - header: "Existing UI-SPEC"
 - question: "UI-SPEC.md already exists for Phase {N}. What would you like to do?"
@@ -120,7 +122,7 @@ Answer: "What visual and interaction contracts does this phase need?"
 - {state_path} (Project State)
 - {roadmap_path} (Roadmap)
 - {requirements_path} (Requirements)
-- {context_path} (USER DECISIONS from /sdd:discuss-phase)
+- {context_path} (USER DECISIONS from /sdd-discuss-phase)
 - {research_path} (Technical Research — stack decisions)
 </files_to_read>
 
@@ -238,7 +240,7 @@ Max revision iterations reached. Remaining issues:
 
 Options:
 1. Force approve — proceed with current UI-SPEC (FLAGs become accepted)
-2. Edit manually — open UI-SPEC.md in editor, re-run /sdd:ui-phase
+2. Edit manually — open UI-SPEC.md in editor, re-run /sdd-ui-phase
 3. Abandon — exit without approving
 ```
 
@@ -261,11 +263,17 @@ Dimensions: 6/6 passed
 
 ## ▶ Next Up
 
+{If CONTEXT.md exists for this phase:}
 **Plan Phase {N}** — planner will use UI-SPEC.md as design context
 
-`/sdd:plan-phase {N}`
+`/clear` then: `/sdd-plan-phase {N}`
+
+{If CONTEXT.md does NOT exist:}
+**Discuss Phase {N}** — gather implementation context before planning
+
+`/clear` then: `/sdd-discuss-phase {N}`
 
-<sub>/clear first → fresh context window</sub>
+(or `/sdd-plan-phase {N}` to skip discussion)
 
 ───────────────────────────────────────────────────────────────
 ```

package/sdd/workflows/ui-review.md

@@ -42,8 +42,10 @@ UI_SPEC_FILE=$(ls "${PHASE_DIR}"/*-UI-SPEC.md 2>/dev/null | head -1)
 UI_REVIEW_FILE=$(ls "${PHASE_DIR}"/*-UI-REVIEW.md 2>/dev/null | head -1)
 ```
 
-**If `SUMMARY_FILES` empty:** Exit — "Phase {N} not executed. Run /sdd:execute-phase {N} first."
+**If `SUMMARY_FILES` empty:** Exit — "Phase {N} not executed. Run /sdd-execute-phase {N} first."
 
+
+**Text mode (`workflow.text_mode: true` in config or `--text` flag):** 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. This is required for non-Claude runtimes (OpenAI Codex, Gemini CLI, etc.) where `AskUserQuestion` is not available.
 **If `UI_REVIEW_FILE` non-empty:** Use AskUserQuestion:
 - header: "Existing UI Review"
 - question: "UI-REVIEW.md already exists for Phase {N}."
@@ -138,14 +140,37 @@ Full review: {path to UI-REVIEW.md}
 
 ## ▶ Next
 
-- `/sdd:verify-work {N}` — UAT testing
-- `/sdd:plan-phase {N+1}` — plan next phase
+`/clear` then one of:
+
+- `/sdd-verify-work {N}` — UAT testing
+- `/sdd-plan-phase {N+1}` — plan next phase
 
-<sub>/clear first → fresh context window</sub>
+- `/sdd-verify-work {N}` — UAT testing
+- `/sdd-plan-phase {N+1}` — plan next phase
 
 ───────────────────────────────────────────────────────────────
 ```
 
+## Automated UI Verification (when Playwright-MCP is available)
+
+If `mcp__playwright__*` tools are accessible in this session:
+
+1. Navigate to each UI component described in the phase's UI-SPEC.md using
+   `mcp__playwright__navigate` (or equivalent Playwright-MCP tool).
+2. Take a screenshot of each component using `mcp__playwright__screenshot`.
+3. Compare against the spec's visual requirements — dimensions, color palette,
+   layout, spacing scale, and typography.
+4. Report any dimension, color, or layout discrepancies automatically as
+   additional findings within the relevant pillar section of UI-REVIEW.md.
+5. Flag items that require human judgment (brand feel, content tone) as
+   `needs_human_review: true` in the findings — these are surfaced to the user
+   separately after the automated pass completes.
+
+If Playwright-MCP is not available in this session, this section is skipped
+entirely. The audit falls back to the standard code-only review described above.
+No configuration change is required — the availability of `mcp__playwright__*`
+tools is detected at runtime.
+
 ## 5. Commit (if configured)
 
 ```bash

package/sdd/workflows/undo.md

@@ -0,0 +1,314 @@
+<purpose>
+Safe git revert workflow. Rolls back SDD phase or plan commits using the phase manifest with dependency checks and a confirmation gate. Uses git revert --no-commit (NEVER git reset) to preserve history.
+</purpose>
+
+<required_reading>
+@~/.claude/sdd/references/ui-brand.md
+@~/.claude/sdd/references/gate-prompts.md
+</required_reading>
+
+<process>
+
+<step name="banner" priority="first">
+Display the stage banner:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ SDD ► UNDO
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+</step>
+
+<step name="parse_arguments">
+Parse $ARGUMENTS for the undo mode:
+
+- `--last N` → MODE=last, COUNT=N (integer, default 10 if N missing)
+- `--phase NN` → MODE=phase, TARGET_PHASE=NN (two-digit phase number)
+- `--plan NN-MM` → MODE=plan, TARGET_PLAN=NN-MM (phase-plan ID)
+
+If no valid argument is provided, display usage and exit:
+
+```
+Usage: /sdd-undo --last N | --phase NN | --plan NN-MM
+
+Modes:
+  --last N      Show last N SDD commits for interactive selection
+  --phase NN    Revert all commits for phase NN
+  --plan NN-MM  Revert all commits for plan NN-MM
+
+Examples:
+  /sdd-undo --last 5
+  /sdd-undo --phase 03
+  /sdd-undo --plan 03-02
+```
+</step>
+
+<step name="gather_commits">
+Based on MODE, gather candidate commits.
+
+**MODE=last:**
+
+Run:
+```bash
+git log --oneline --no-merges -${COUNT}
+```
+
+Filter for SDD conventional commits matching `type(scope): message` pattern (e.g., `feat(04-01):`, `docs(03):`, `fix(02-03):`).
+
+Display a numbered list of matching commits:
+```
+Recent SDD commits:
+  1. abc1234 feat(04-01): implement auth endpoint
+  2. def5678 docs(03-02): complete plan summary
+  3. ghi9012 fix(02-03): correct validation logic
+```
+
+
+**Text mode (`workflow.text_mode: true` in config or `--text` flag):** 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. This is required for non-Claude runtimes (OpenAI Codex, Gemini CLI, etc.) where `AskUserQuestion` is not available.
+Use AskUserQuestion to ask:
+- question: "Which commits to revert? Enter numbers (e.g., 1,3) or 'all'"
+- header: "Select"
+
+Parse the user's selection into COMMITS list.
+
+---
+
+**MODE=phase:**
+
+Read `.planning/.phase-manifest.json` if it exists.
+
+If the file exists and `manifest.phases?.[TARGET_PHASE]?.commits` is a non-empty array:
+  - Use `manifest.phases[TARGET_PHASE].commits` entries as COMMITS (each entry is a commit hash)
+
+If the file does not exist, or `manifest.phases?.[TARGET_PHASE]` is missing:
+  - Display: "Manifest has no entry for phase ${TARGET_PHASE} (or file missing), falling back to git log search"
+  - Fallback: run git log and filter for the target phase scope:
+    ```bash
+    git log --oneline --no-merges --all | grep -E "\(0*${TARGET_PHASE}(-[0-9]+)?\):" | head -50
+    ```
+  - Use matching commits as COMMITS
+
+---
+
+**MODE=plan:**
+
+Run:
+```bash
+git log --oneline --no-merges --all | grep -E "\(${TARGET_PLAN}\)" | head -50
+```
+
+Use matching commits as COMMITS.
+
+---
+
+**Empty check:**
+
+If COMMITS is empty after gathering:
+```
+No commits found for ${MODE} ${TARGET}. Nothing to revert.
+```
+Exit cleanly.
+</step>
+
+<step name="dependency_check">
+**Applies when MODE=phase or MODE=plan.**
+
+Skip this step entirely for MODE=last.
+
+---
+
+**MODE=phase:**
+
+Read `.planning/ROADMAP.md` inline.
+
+Search for phases that list a dependency on the target phase. Look for patterns like:
+- "Depends on: Phase ${TARGET_PHASE}"
+- "Depends on: ${TARGET_PHASE}"
+- "depends_on: [${TARGET_PHASE}]"
+
+For each dependent phase N found:
+1. Check if `.planning/phases/${N}-*/` directory exists
+2. If directory exists, check for any PLAN.md or SUMMARY.md files inside it
+
+If any downstream phase has started work, collect warnings:
+```
+⚠  Downstream dependency detected:
+   Phase ${N} depends on Phase ${TARGET_PHASE} and has started work.
+```
+
+---
+
+**MODE=plan:**
+
+Extract the phase number from TARGET_PLAN (the NN part of NN-MM). Extract the plan number (the MM part).
+
+Look for later plans in the same phase directory (`.planning/phases/${NN}-*/`). For each later plan (plans with number > MM):
+1. Read the later plan's PLAN.md
+2. Check if its `<files>` sections or `consumes` fields reference outputs from the target plan
+
+If any later plan references the target plan's outputs, collect warnings:
+```
+⚠  Intra-phase dependency detected:
+   Plan ${LATER_PLAN} in phase ${NN} references outputs from plan ${TARGET_PLAN}.
+```
+
+---
+
+If any warnings exist (from either mode):
+- Display all warnings
+- Use AskUserQuestion with approve-revise-abort pattern:
+  - question: "Downstream work depends on the target being reverted. Proceed anyway?"
+  - header: "Confirm"
+  - options: Proceed | Abort
+
+If user selects "Abort": exit with "Revert cancelled. No changes made."
+</step>
+
+<step name="confirm_revert">
+Display the confirmation gate using approve-revise-abort pattern from gate-prompts.md.
+
+Show:
+```
+The following commits will be reverted (in reverse chronological order):
+
+  {hash} — {message}
+  {hash} — {message}
+  ...
+
+Total: {N} commit(s) to revert
+```
+
+Use AskUserQuestion:
+- question: "Proceed with revert?"
+- header: "Approve?"
+- options: Approve | Abort
+
+If "Abort": display "Revert cancelled. No changes made." and exit.
+If "Approve": ask for a reason:
+
+```
+AskUserQuestion(
+  header: "Reason",
+  question: "Brief reason for the revert (used in commit message):",
+  options: []
+)
+```
+
+Store the response as REVERT_REASON. Continue to execute_revert.
+</step>
+
+<step name="execute_revert">
+**HARD CONSTRAINT: Use git revert --no-commit. NEVER use git reset (except for conflict cleanup as documented below).**
+
+**Dirty-tree guard (run first, before any revert):**
+
+Run `git status --porcelain`. If the output is non-empty, display the dirty files and abort:
+```
+Working tree has uncommitted changes. Commit or stash them before running /sdd-undo.
+```
+Exit immediately — do not proceed to any revert operations.
+
+---
+
+Sort COMMITS in reverse chronological order (newest first). If commits came from git log (already newest-first), they are already in correct order.
+
+For each commit hash in COMMITS:
+```bash
+git revert --no-commit ${HASH}
+```
+
+If any revert fails (merge conflict or error):
+1. Display the error message
+2. Run cleanup — handle both first-call and mid-sequence cases:
+   ```bash
+   # Try git revert --abort first (works if this is the first failed revert)
+   git revert --abort 2>/dev/null
+   # If prior --no-commit reverts already staged cleanly before this failure,
+   # revert --abort may be a no-op. Clean up staged and working tree changes:
+   git reset HEAD 2>/dev/null
+   git restore . 2>/dev/null
+   ```
+3. Display:
+   ```
+   ╔══════════════════════════════════════════════════════════════╗
+   ║  ERROR                                                       ║
+   ╚══════════════════════════════════════════════════════════════╝
+
+   Revert failed on commit ${HASH}.
+   Likely cause: merge conflict with subsequent changes.
+
+   **To fix:** Resolve the conflict manually or revert commits individually.
+   All pending reverts have been aborted — working tree is clean.
+   ```
+4. Exit with error.
+
+After all reverts are staged successfully, create a single commit:
+
+For MODE=phase:
+```bash
+git commit -m "revert(${TARGET_PHASE}): undo phase ${TARGET_PHASE} — ${REVERT_REASON}"
+```
+
+For MODE=plan:
+```bash
+git commit -m "revert(${TARGET_PLAN}): undo plan ${TARGET_PLAN} — ${REVERT_REASON}"
+```
+
+For MODE=last:
+```bash
+git commit -m "revert: undo ${N} selected commits — ${REVERT_REASON}"
+```
+</step>
+
+<step name="summary">
+Display the completion banner:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ SDD ► UNDO COMPLETE ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Show summary:
+```
+  ✓ ${N} commit(s) reverted
+  ✓ Single revert commit created: ${REVERT_HASH}
+```
+
+Show next steps:
+```
+───────────────────────────────────────────────────────────────
+
+## ▶ Next Up
+
+**Review state** — verify project is in expected state after revert
+
+/clear then:
+
+/sdd-progress
+
+───────────────────────────────────────────────────────────────
+
+**Also available:**
+- `/sdd-execute-phase ${PHASE}` — re-execute if needed
+- `/sdd-undo --last 1` — undo the revert itself if something went wrong
+
+───────────────────────────────────────────────────────────────
+```
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] Arguments parsed correctly for all three modes
+- [ ] --phase mode reads .planning/.phase-manifest.json using manifest.phases[TARGET_PHASE].commits
+- [ ] --phase mode falls back to git log if manifest entry missing
+- [ ] Dependency check warns when downstream phases have started (MODE=phase)
+- [ ] Dependency check warns when later plans reference target plan outputs (MODE=plan)
+- [ ] Dirty-tree guard aborts if working tree has uncommitted changes
+- [ ] Confirmation gate shown before any revert execution
+- [ ] Reverts use git revert --no-commit in reverse chronological order
+- [ ] Single commit created after all reverts staged
+- [ ] Error handling cleans up both first-call and mid-sequence conflict cases
+- [ ] git reset --hard is NEVER used anywhere in this workflow
+</success_criteria>