@bhargavvc/sdd-cc 1.30.1 → 1.35.0

package/sdd/workflows/next.md

@@ -29,45 +29,101 @@ Extract:
 
 If no `.planning/` directory exists:
 ```
-No SDD project detected. Run `/sdd:new-project` to get started.
+No SDD project detected. Run `/sdd-new-project` to get started.
 ```
 Exit.
 </step>
 
+<step name="safety_gates">
+Run hard-stop checks before routing. Exit on first hit unless `--force` was passed.
+
+If `--force` flag was passed, skip all gates and the consecutive guard.
+Print a one-line warning: `⚠ --force: skipping safety gates`
+Then proceed directly to `determine_next_action`.
+
+**Gate 1: Unresolved checkpoint**
+Check if `.planning/.continue-here.md` exists:
+```bash
+[ -f .planning/.continue-here.md ]
+```
+If found:
+```
+⛔ Hard stop: Unresolved checkpoint
+
+`.planning/.continue-here.md` exists — a previous session left
+unfinished work that needs manual review before advancing.
+
+Read the file, resolve the issue, then delete it to continue.
+Use `--force` to bypass this check.
+```
+Exit (do not route).
+
+**Gate 2: Error state**
+Check if STATE.md contains `status: error` or `status: failed`:
+If found:
+```
+⛔ Hard stop: Project in error state
+
+STATE.md shows status: {status}. Resolve the error before advancing.
+Run `/sdd-health` to diagnose, or manually fix STATE.md.
+Use `--force` to bypass this check.
+```
+Exit.
+
+**Gate 3: Unchecked verification**
+Check if the current phase has a VERIFICATION.md with any `FAIL` items that don't have overrides:
+If found:
+```
+⛔ Hard stop: Unchecked verification failures
+
+VERIFICATION.md for phase {N} has {count} unresolved FAIL items.
+Address the failures or add overrides before advancing to the next phase.
+Use `--force` to bypass this check.
+```
+Exit.
+
+**Consecutive-call guard:**
+After passing all gates, check a counter file `.planning/.next-call-count`:
+- If file exists and count >= 6: prompt "You've called /sdd-next {N} times consecutively. Continue? [y/N]"
+- If user says no, exit
+- Increment the counter
+- The counter file is deleted by any non-`/sdd-next` command (convention — other workflows don't need to implement this, the note here is sufficient)
+</step>
+
 <step name="determine_next_action">
 Apply routing rules based on state:
 
 **Route 1: No phases exist yet → discuss**
 If ROADMAP has phases but no phase directories exist on disk:
-→ Next action: `/sdd:discuss-phase <first-phase>`
+→ Next action: `/sdd-discuss-phase <first-phase>`
 
 **Route 2: Phase exists but has no CONTEXT.md or RESEARCH.md → discuss**
 If the current phase directory exists but has neither CONTEXT.md nor RESEARCH.md:
-→ Next action: `/sdd:discuss-phase <current-phase>`
+→ Next action: `/sdd-discuss-phase <current-phase>`
 
 **Route 3: Phase has context but no plans → plan**
 If the current phase has CONTEXT.md (or RESEARCH.md) but no PLAN.md files:
-→ Next action: `/sdd:plan-phase <current-phase>`
+→ Next action: `/sdd-plan-phase <current-phase>`
 
 **Route 4: Phase has plans but incomplete summaries → execute**
 If plans exist but not all have matching summaries:
-→ Next action: `/sdd:execute-phase <current-phase>`
+→ Next action: `/sdd-execute-phase <current-phase>`
 
 **Route 5: All plans have summaries → verify and complete**
 If all plans in the current phase have summaries:
-→ Next action: `/sdd:verify-work` then `/sdd:complete-phase`
+→ Next action: `/sdd-verify-work`
 
 **Route 6: Phase complete, next phase exists → advance**
 If the current phase is complete and the next phase exists in ROADMAP:
-→ Next action: `/sdd:discuss-phase <next-phase>`
+→ Next action: `/sdd-discuss-phase <next-phase>`
 
 **Route 7: All phases complete → complete milestone**
 If all phases are complete:
-→ Next action: `/sdd:complete-milestone`
+→ Next action: `/sdd-complete-milestone`
 
 **Route 8: Paused → resume**
 If STATE.md shows paused_at:
-→ Next action: `/sdd:resume-work`
+→ Next action: `/sdd-resume-work`
 </step>
 
 <step name="show_and_execute">
@@ -79,12 +135,12 @@ Display the determination:
 **Current:** Phase [N] — [name] | [progress]%
 **Status:** [status description]
 
-▶ **Next step:** `/sdd:[command] [args]`
+▶ **Next step:** `/sdd-[command] [args]`
   [One-line explanation of why this is the next step]
 ```
 
 Then immediately invoke the determined command via SlashCommand.
-Do not ask for confirmation — the whole point of `/sdd:next` is zero-friction advancement.
+Do not ask for confirmation — the whole point of `/sdd-next` is zero-friction advancement.
 </step>
 
 </process>

package/sdd/workflows/note.md

@@ -1,5 +1,7 @@
 <purpose>
 Zero-friction idea capture. One Write call, one confirmation line. No questions, no prompts.
+
+**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.
 Runs inline — no Task, no AskUserQuestion, no Bash.
 </purpose>
 
@@ -43,7 +45,7 @@ promoted: false
 | Arguments are empty (no text at all) | **list** |
 | Anything else | **append** (the text IS the note) |
 
-**Critical**: `list` is only a subcommand when it's the ENTIRE argument. `/sdd:note list of groceries` saves a note with text "list of groceries". Same for `promote` — only a subcommand when followed by exactly one number.
+**Critical**: `list` is only a subcommand when it's the ENTIRE argument. `/sdd-note list of groceries` saves a note with text "list of groceries". Same for `promote` — only a subcommand when followed by exactly one number.
 </step>
 
 <step name="append">
@@ -87,7 +89,7 @@ Project (.planning/notes/):
 Global (~/.claude/notes/):
   4. [2026-02-08 10:00] cross-project idea about shared config
 
-{count} active note(s). Use `/sdd:note promote <N>` to convert to a todo.
+{count} active note(s). Use `/sdd-note promote <N>` to convert to a todo.
 ```
 
 If a scope has no directory or no entries, show: `(no notes)`
@@ -99,9 +101,9 @@ If a scope has no directory or no entries, show: `(no notes)`
 1. Run the **list** logic to build the numbered index (both scopes)
 2. Find entry N from the numbered list
 3. If N is invalid or refers to an already-promoted note, tell the user and stop
-4. **Requires `.planning/` directory** — if it doesn't exist, warn: "Todos require a SDD project. Run `/sdd:new-project` to initialize one."
+4. **Requires `.planning/` directory** — if it doesn't exist, warn: "Todos require a SDD project. Run `/sdd-new-project` to initialize one."
 5. Ensure `.planning/todos/pending/` directory exists
-6. Generate todo ID: `{NNN}-{slug}` where NNN is the next sequential number (scan both `.planning/todos/pending/` and `.planning/todos/done/` for the highest existing number, increment by 1, zero-pad to 3 digits) and slug is the first ~4 meaningful words of the note text
+6. Generate todo ID: `{NNN}-{slug}` where NNN is the next sequential number (scan both `.planning/todos/pending/` and `.planning/todos/completed/` for the highest existing number, increment by 1, zero-pad to 3 digits) and slug is the first ~4 meaningful words of the note text
 7. Extract the note text from the source file (body after frontmatter)
 8. Create `.planning/todos/pending/{id}.md`:
 
@@ -110,7 +112,7 @@ If a scope has no directory or no entries, show: `(no notes)`
 title: "{note text}"
 status: pending
 priority: P2
-source: "promoted from /sdd:note"
+source: "promoted from /sdd-note"
 created: {YYYY-MM-DD}
 theme: general
 ---
@@ -135,9 +137,9 @@ Promoted from quick note captured on {original date}.
 </process>
 
 <edge_cases>
-1. **"list" as note text**: `/sdd:note list of things` saves note "list of things" (subcommand only when `list` is the entire arg)
+1. **"list" as note text**: `/sdd-note list of things` saves note "list of things" (subcommand only when `list` is the entire arg)
 2. **No `.planning/`**: Falls back to global `~/.claude/notes/` — works in any directory
-3. **Promote without project**: Warns that todos require `.planning/`, suggests `/sdd:new-project`
+3. **Promote without project**: Warns that todos require `.planning/`, suggests `/sdd-new-project`
 4. **Large files**: `list` shows last 10 when >20 active entries
 5. **Duplicate slugs**: Append `-2`, `-3` etc. to filename if slug already used on same date
 6. **`--global` position**: Stripped from anywhere — `--global my idea` and `my idea --global` both save "my idea" globally

package/sdd/workflows/pause-work.md

@@ -1,5 +1,5 @@
 <purpose>
-Create structured `.planning/HANDOFF.json` and `.continue-here.md` handoff files to preserve complete work state across sessions. The JSON provides machine-readable state for `/sdd:resume-work`; the markdown provides human-readable context.
+Create structured `.planning/HANDOFF.json` and `.continue-here.md` handoff files to preserve complete work state across sessions. The JSON provides machine-readable state for `/sdd-resume-work`; the markdown provides human-readable context.
 </purpose>
 
 <required_reading>
@@ -9,14 +9,28 @@ Read all files referenced by the invoking prompt's execution_context before star
 <process>
 
 <step name="detect">
-Find current phase directory from most recently modified files:
+## Context Detection
+
+Determine what kind of work is being paused and set the handoff destination accordingly:
 
 ```bash
-# Find most recent phase directory with work
-(ls -lt .planning/phases/*/PLAN.md 2>/dev/null || true) | head -1 | grep -oP 'phases/\K[^/]+' || true
+# Check for active phase
+phase=$(( ls -lt .planning/phases/*/PLAN.md 2>/dev/null || true ) | head -1 | grep -oP 'phases/\K[^/]+' || true)
+
+# Check for active spike
+spike=$(( ls -lt .planning/spikes/*/SPIKE.md .planning/spikes/*/DESIGN.md 2>/dev/null || true ) | head -1 | grep -oP 'spikes/\K[^/]+' || true)
+
+# Check for active deliberation
+deliberation=$(ls .planning/deliberations/*.md 2>/dev/null | head -1 || true)
 ```
 
-If no active phase detected, ask user which phase they're pausing work on.
+- **Phase work**: active phase directory → handoff to `.planning/phases/XX-name/.continue-here.md`
+- **Spike work**: active spike directory or spike-related files (no active phase) → handoff to `.planning/spikes/SPIKE-NNN/.continue-here.md` (create directory if needed)
+- **Deliberation work**: active deliberation file (no phase/spike) → handoff to `.planning/deliberations/.continue-here.md`
+- **Research work**: research notes exist but no phase/spike/deliberation → handoff to `.planning/.continue-here.md`
+- **Default**: no detectable context → handoff to `.planning/.continue-here.md`, note the ambiguity in `<current_state>`
+
+If phase is detected, proceed with phase handoff path. Otherwise use the first matching non-phase path above.
 </step>
 
 <step name="gather">
@@ -30,6 +44,9 @@ If no active phase detected, ask user which phase they're pausing work on.
 6. **Human actions pending**: Things that need manual intervention (MCP setup, API keys, approvals, manual testing)
 7. **Background processes**: Any running servers/watchers that were part of the workflow
 8. **Files modified**: What's changed but not committed
+9. **Blocking constraints**: Anti-patterns or methodological failures encountered during this session that a resuming agent MUST be aware of before proceeding. Only include items discovered through actual failure — not warnings or predictions. Assign each constraint a `severity`:
+   - `blocking` — The resuming agent MUST demonstrate understanding before proceeding. The discuss-phase and execute-phase workflows will enforce a mandatory understanding check.
+   - `advisory` — Important context but does not gate resumption.
 
 Ask user for clarifications if needed via conversational questions.
 
@@ -85,10 +102,11 @@ timestamp=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" current-timestamp full --
 </step>
 
 <step name="write">
-**Write handoff to `.planning/phases/XX-name/.continue-here.md`:**
+**Write handoff to the path determined in the detect step** (e.g. `.planning/phases/XX-name/.continue-here.md`, `.planning/spikes/SPIKE-NNN/.continue-here.md`, or `.planning/.continue-here.md`):
 
 ```markdown
 ---
+context: [phase|spike|deliberation|research|default]
 phase: XX-name
 task: 3
 total_tasks: 7
@@ -96,12 +114,35 @@ status: in_progress
 last_updated: [timestamp from current-timestamp]
 ---
 
+# BLOCKING CONSTRAINTS — Read Before Anything Else
+
+> These are not suggestions. Each constraint below was discovered through failure.
+> Acknowledge each one explicitly before proceeding.
+
+- [ ] CONSTRAINT: [name] — [what it is] — [structural mitigation required]
+
+**Do not proceed until all boxes are checked.**
+
+_If no constraints have been identified yet, remove this section._
+
+## Critical Anti-Patterns
+
+| Pattern | Description | Severity | Prevention Mechanism |
+|---------|-------------|----------|---------------------|
+| [pattern name] | [what it is and how it manifested] | blocking | [structural step that prevents recurrence — not acknowledgment] |
+| [pattern name] | [what it is and how it manifested] | advisory | [guidance for avoiding it] |
+
+**Severity values:** `blocking` — resuming agent must pass understanding check before proceeding. `advisory` — important context, does not gate resumption.
+
+_Remove rows that do not apply. The discuss-phase and execute-phase workflows parse this table and enforce a mandatory understanding check for any `blocking` rows._
+
 <current_state>
 [Where exactly are we? Immediate context]
 </current_state>
 
 <completed_work>
 
+Completed Tasks:
 - Task 1: [name] - Done
 - Task 2: [name] - Done
 - Task 3: [name] - In progress, [what's done]
@@ -124,6 +165,25 @@ last_updated: [timestamp from current-timestamp]
 - [Blocker 1]: [status/workaround]
 </blockers>
 
+## Required Reading (in order)
+<!-- List documents the resuming agent must read before acting -->
+1. [document] — [why it matters]
+1. `.planning/METHODOLOGY.md` (if it exists) — project analytical lenses; apply before any assumption analysis
+
+## Critical Anti-Patterns (do NOT repeat these)
+<!-- Mistakes discovered this session that must be structurally avoided -->
+- [ANTI-PATTERN]: [what it is] → [structural mitigation]
+
+## Infrastructure State
+<!-- Running services, external state, environment specifics -->
+- [service/env]: [current state]
+
+## Pre-Execution Critique Required
+<!-- Fill in ONLY if pausing between design and execution (e.g. spike design done, not yet run) -->
+- Design artifact: [path]
+- Critique focus: [key questions the critic should probe]
+- Gate: Do NOT begin execution until critique is complete and design is revised
+
 <context>
 [Mental state, what were you thinking, the plan]
 </context>
@@ -143,7 +203,7 @@ timestamp=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" current-timestamp full --
 
 <step name="commit">
 ```bash
-node "$HOME/.claude/sdd/bin/sdd-tools.cjs" commit "wip: [phase-name] paused at task [X]/[Y]" --files .planning/phases/*/.continue-here.md .planning/HANDOFF.json
+node "$HOME/.claude/sdd/bin/sdd-tools.cjs" commit "wip: [context-name] paused at [X]/[Y]" --files [handoff-path] .planning/HANDOFF.json
 ```
 </step>
 
@@ -151,17 +211,18 @@ node "$HOME/.claude/sdd/bin/sdd-tools.cjs" commit "wip: [phase-name] paused at t
 ```
 ✓ Handoff created:
   - .planning/HANDOFF.json (structured, machine-readable)
-  - .planning/phases/[XX-name]/.continue-here.md (human-readable)
+  - [handoff-path] (human-readable)
 
 Current state:
 
-- Phase: [XX-name]
+- Context: [phase|spike|deliberation|research]
+- Location: [XX-name or SPIKE-NNN]
 - Task: [X] of [Y]
 - Status: [in_progress/blocked]
 - Blockers: [count] ({human_actions_pending count} need human action)
 - Committed as WIP
 
-To resume: /sdd:resume-work
+To resume: /sdd-resume-work
 
 ```
 </step>
@@ -169,8 +230,10 @@ To resume: /sdd:resume-work
 </process>
 
 <success_criteria>
-- [ ] .continue-here.md created in correct phase directory
-- [ ] All sections filled with specific content
+- [ ] Context detected (phase/spike/deliberation/research/default)
+- [ ] .continue-here.md created at correct path for detected context
+- [ ] Required Reading, Anti-Patterns, and Infrastructure State sections filled
+- [ ] Pre-Execution Critique section filled if pausing between design and execution
 - [ ] Committed as WIP
 - [ ] User knows location and how to resume
 </success_criteria>

package/sdd/workflows/plan-milestone-gaps.md

@@ -1,5 +1,5 @@
 <purpose>
-Create all phases necessary to close gaps identified by `/sdd:audit-milestone`. Reads MILESTONE-AUDIT.md, groups gaps into logical phases, creates phase entries in ROADMAP.md, and offers to plan each phase. One command creates all fix phases — no manual `/sdd:add-phase` per gap.
+Create all phases necessary to close gaps identified by `/sdd-audit-milestone`. Reads MILESTONE-AUDIT.md, groups gaps into logical phases, creates phase entries in ROADMAP.md, and offers to plan each phase. One command creates all fix phases — no manual `/sdd-add-phase` per gap.
 </purpose>
 
 <required_reading>
@@ -22,7 +22,7 @@ Parse YAML frontmatter to extract structured gaps:
 
 If no audit file exists or has no gaps, error:
 ```
-No audit gaps found. Run `/sdd:audit-milestone` first.
+No audit gaps found. Run `/sdd-audit-milestone` first.
 ```
 
 ## 2. Prioritize Gaps
@@ -163,22 +163,22 @@ node "$HOME/.claude/sdd/bin/sdd-tools.cjs" commit "docs(roadmap): add gap closur
 
 **Plan first gap closure phase**
 
-`/sdd:plan-phase {N}`
+`/clear` then:
 
-<sub>`/clear` first → fresh context window</sub>
+`/sdd-plan-phase {N}`
 
 ---
 
 **Also available:**
-- `/sdd:execute-phase {N}` — if plans already exist
+- `/sdd-execute-phase {N}` — if plans already exist
 - `cat .planning/ROADMAP.md` — see updated roadmap
 
 ---
 
 **After all gap phases complete:**
 
-`/sdd:audit-milestone` — re-audit to verify gaps closed
-`/sdd:complete-milestone {version}` — archive when audit passes
+`/sdd-audit-milestone` — re-audit to verify gaps closed
+`/sdd-complete-milestone {version}` — archive when audit passes
 ```
 
 </process>
@@ -269,5 +269,5 @@ becomes:
 - [ ] Coverage count updated in REQUIREMENTS.md
 - [ ] Phase directories created
 - [ ] Changes committed (includes REQUIREMENTS.md)
-- [ ] User knows to run `/sdd:plan-phase` next
+- [ ] User knows to run `/sdd-plan-phase` next
 </success_criteria>