@bhargavvc/sdd-cc 1.30.0

package/commands/sdd/research-phase.md

@@ -0,0 +1,195 @@
+---
+name: sdd:research-phase
+description: Research how to implement a phase (standalone - usually use /sdd:plan-phase instead)
+argument-hint: "[phase]"
+allowed-tools:
+  - Read
+  - Bash
+  - Task
+---
+
+<objective>
+Research how to implement a phase. Spawns sdd-phase-researcher agent with phase context.
+
+**Note:** This is a standalone research command. For most workflows, use `/sdd:plan-phase` which integrates research automatically.
+
+**Use this command when:**
+- You want to research without planning yet
+- You want to re-research after planning is complete
+- You need to investigate before deciding if a phase is feasible
+
+**Orchestrator role:** Parse phase, validate against roadmap, check existing research, gather context, spawn researcher agent, present results.
+
+**Why subagent:** Research burns context fast (WebSearch, Context7 queries, source verification). Fresh 200k context for investigation. Main context stays lean for user interaction.
+</objective>
+
+<available_agent_types>
+Valid SDD subagent types (use exact names — do not fall back to 'general-purpose'):
+- sdd-phase-researcher — Researches technical approaches for a phase
+</available_agent_types>
+
+<context>
+Phase number: $ARGUMENTS (required)
+
+Normalize phase input in step 1 before any directory lookups.
+</context>
+
+<process>
+
+## 0. Initialize Context
+
+```bash
+INIT=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" init phase-op "$ARGUMENTS")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+```
+
+Extract from init JSON: `phase_dir`, `phase_number`, `phase_name`, `phase_found`, `commit_docs`, `has_research`, `state_path`, `requirements_path`, `context_path`, `research_path`.
+
+Resolve researcher model:
+```bash
+RESEARCHER_MODEL=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" resolve-model sdd-phase-researcher --raw)
+```
+
+## 1. Validate Phase
+
+```bash
+PHASE_INFO=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" roadmap get-phase "${phase_number}")
+```
+
+**If `found` is false:** Error and exit. **If `found` is true:** Extract `phase_number`, `phase_name`, `goal` from JSON.
+
+## 2. Check Existing Research
+
+```bash
+ls .planning/phases/${PHASE}-*/RESEARCH.md 2>/dev/null
+```
+
+**If exists:** Offer: 1) Update research, 2) View existing, 3) Skip. Wait for response.
+
+**If doesn't exist:** Continue.
+
+## 3. Gather Phase Context
+
+Use paths from INIT (do not inline file contents in orchestrator context):
+- `requirements_path`
+- `context_path`
+- `state_path`
+
+Present summary with phase description and what files the researcher will load.
+
+## 4. Spawn sdd-phase-researcher Agent
+
+Research modes: ecosystem (default), feasibility, implementation, comparison.
+
+```markdown
+<research_type>
+Phase Research — investigating HOW to implement a specific phase well.
+</research_type>
+
+<key_insight>
+The question is NOT "which library should I use?"
+
+The question is: "What do I not know that I don't know?"
+
+For this phase, discover:
+- What's the established architecture pattern?
+- What libraries form the standard stack?
+- What problems do people commonly hit?
+- What's SOTA vs what Claude's training thinks is SOTA?
+- What should NOT be hand-rolled?
+</key_insight>
+
+<objective>
+Research implementation approach for Phase {phase_number}: {phase_name}
+Mode: ecosystem
+</objective>
+
+<files_to_read>
+- {requirements_path} (Requirements)
+- {context_path} (Phase context from discuss-phase, if exists)
+- {state_path} (Prior project decisions and blockers)
+</files_to_read>
+
+<additional_context>
+**Phase description:** {phase_description}
+</additional_context>
+
+<downstream_consumer>
+Your RESEARCH.md will be loaded by `/sdd:plan-phase` which uses specific sections:
+- `## Standard Stack` → Plans use these libraries
+- `## Architecture Patterns` → Task structure follows these
+- `## Don't Hand-Roll` → Tasks NEVER build custom solutions for listed problems
+- `## Common Pitfalls` → Verification steps check for these
+- `## Code Examples` → Task actions reference these patterns
+
+Be prescriptive, not exploratory. "Use X" not "Consider X or Y."
+</downstream_consumer>
+
+<quality_gate>
+Before declaring complete, verify:
+- [ ] All domains investigated (not just some)
+- [ ] Negative claims verified with official docs
+- [ ] Multiple sources for critical claims
+- [ ] Confidence levels assigned honestly
+- [ ] Section names match what plan-phase expects
+</quality_gate>
+
+<output>
+Write to: .planning/phases/${PHASE}-{slug}/${PHASE}-RESEARCH.md
+</output>
+```
+
+```
+Task(
+  prompt=filled_prompt,
+  subagent_type="sdd-phase-researcher",
+  model="{researcher_model}",
+  description="Research Phase {phase}"
+)
+```
+
+## 5. Handle Agent Return
+
+**`## RESEARCH COMPLETE`:** Display summary, offer: Plan phase, Dig deeper, Review full, Done.
+
+**`## CHECKPOINT REACHED`:** Present to user, get response, spawn continuation.
+
+**`## RESEARCH INCONCLUSIVE`:** Show what was attempted, offer: Add context, Try different mode, Manual.
+
+## 6. Spawn Continuation Agent
+
+```markdown
+<objective>
+Continue research for Phase {phase_number}: {phase_name}
+</objective>
+
+<prior_state>
+<files_to_read>
+- .planning/phases/${PHASE}-{slug}/${PHASE}-RESEARCH.md (Existing research)
+</files_to_read>
+</prior_state>
+
+<checkpoint_response>
+**Type:** {checkpoint_type}
+**Response:** {user_response}
+</checkpoint_response>
+```
+
+```
+Task(
+  prompt=continuation_prompt,
+  subagent_type="sdd-phase-researcher",
+  model="{researcher_model}",
+  description="Continue research Phase {phase}"
+)
+```
+
+</process>
+
+<success_criteria>
+- [ ] Phase validated against roadmap
+- [ ] Existing research checked
+- [ ] sdd-phase-researcher spawned with context
+- [ ] Checkpoints handled correctly
+- [ ] User knows next steps
+</success_criteria>

package/commands/sdd/resume-work.md

@@ -0,0 +1,40 @@
+---
+name: sdd:resume-work
+description: Resume work from previous session with full context restoration
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+  - AskUserQuestion
+  - SlashCommand
+---
+
+<objective>
+Restore complete project context and resume work seamlessly from previous session.
+
+Routes to the resume-project workflow which handles:
+
+- STATE.md loading (or reconstruction if missing)
+- Checkpoint detection (.continue-here files)
+- Incomplete work detection (PLAN without SUMMARY)
+- Status presentation
+- Context-aware next action routing
+  </objective>
+
+<execution_context>
+@~/.claude/sdd/workflows/resume-project.md
+</execution_context>
+
+<process>
+**Follow the resume-project workflow** from `@~/.claude/sdd/workflows/resume-project.md`.
+
+The workflow handles all resumption logic including:
+
+1. Project existence verification
+2. STATE.md loading or reconstruction
+3. Checkpoint and incomplete work detection
+4. Visual status presentation
+5. Context-aware option offering (checks CONTEXT.md before suggesting plan vs discuss)
+6. Routing to appropriate next command
+7. Session continuity updates
+   </process>

package/commands/sdd/review-backlog.md

@@ -0,0 +1,61 @@
+---
+name: sdd:review-backlog
+description: Review and promote backlog items to active milestone
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+---
+
+<objective>
+Review all 999.x backlog items and optionally promote them into the active
+milestone sequence or remove stale entries.
+</objective>
+
+<process>
+
+1. **List backlog items:**
+   ```bash
+   ls -d .planning/phases/999* 2>/dev/null || echo "No backlog items found"
+   ```
+
+2. **Read ROADMAP.md** and extract all 999.x phase entries:
+   ```bash
+   cat .planning/ROADMAP.md
+   ```
+   Show each backlog item with its description, any accumulated context (CONTEXT.md, RESEARCH.md), and creation date.
+
+3. **Present the list to the user** via AskUserQuestion:
+   - For each backlog item, show: phase number, description, accumulated artifacts
+   - Options per item: **Promote** (move to active), **Keep** (leave in backlog), **Remove** (delete)
+
+4. **For items to PROMOTE:**
+   - Find the next sequential phase number in the active milestone
+   - Rename the directory from `999.x-slug` to `{new_num}-slug`:
+     ```bash
+     NEW_NUM=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" phase add "${DESCRIPTION}" --raw)
+     ```
+   - Move accumulated artifacts to the new phase directory
+   - Update ROADMAP.md: move the entry from `## Backlog` section to the active phase list
+   - Remove `(BACKLOG)` marker
+   - Add appropriate `**Depends on:**` field
+
+5. **For items to REMOVE:**
+   - Delete the phase directory
+   - Remove the entry from ROADMAP.md `## Backlog` section
+
+6. **Commit changes:**
+   ```bash
+   node "$HOME/.claude/sdd/bin/sdd-tools.cjs" commit "docs: review backlog — promoted N, removed M" --files .planning/ROADMAP.md
+   ```
+
+7. **Report summary:**
+   ```
+   ## 📋 Backlog Review Complete
+
+   Promoted: {list of promoted items with new phase numbers}
+   Kept: {list of items remaining in backlog}
+   Removed: {list of deleted items}
+   ```
+
+</process>

package/commands/sdd/review.md

@@ -0,0 +1,37 @@
+---
+name: sdd:review
+description: Request cross-AI peer review of phase plans from external AI CLIs
+argument-hint: "--phase N [--gemini] [--claude] [--codex] [--all]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+---
+
+<objective>
+Invoke external AI CLIs (Gemini, Claude, Codex) to independently review phase plans.
+Produces a structured REVIEWS.md with per-reviewer feedback that can be fed back into
+planning via /sdd:plan-phase --reviews.
+
+**Flow:** Detect CLIs → Build review prompt → Invoke each CLI → Collect responses → Write REVIEWS.md
+</objective>
+
+<execution_context>
+@~/.claude/sdd/workflows/review.md
+</execution_context>
+
+<context>
+Phase number: extracted from $ARGUMENTS (required)
+
+**Flags:**
+- `--gemini` — Include Gemini CLI review
+- `--claude` — Include Claude CLI review (uses separate session)
+- `--codex` — Include Codex CLI review
+- `--all` — Include all available CLIs
+</context>
+
+<process>
+Execute the review workflow from @~/.claude/sdd/workflows/review.md end-to-end.
+</process>

package/commands/sdd/session-report.md

@@ -0,0 +1,19 @@
+---
+name: sdd:session-report
+description: Generate a session report with token usage estimates, work summary, and outcomes
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+---
+<objective>
+Generate a structured SESSION_REPORT.md document capturing session outcomes, work performed, and estimated resource usage. Provides a shareable artifact for post-session review.
+</objective>
+
+<execution_context>
+@~/.claude/sdd/workflows/session-report.md
+</execution_context>
+
+<process>
+Execute the session-report workflow from @~/.claude/sdd/workflows/session-report.md end-to-end.
+</process>

package/commands/sdd/set-profile.md

@@ -0,0 +1,12 @@
+---
+name: sdd:set-profile
+description: Switch model profile for SDD agents (quality/balanced/budget/inherit)
+argument-hint: <profile (quality|balanced|budget|inherit)>
+model: haiku
+allowed-tools:
+  - Bash
+---
+
+Show the following output to the user verbatim, with no extra commentary:
+
+!`node "$HOME/.claude/sdd/bin/sdd-tools.cjs" config-set-model-profile $ARGUMENTS --raw`

package/commands/sdd/settings.md

@@ -0,0 +1,36 @@
+---
+name: sdd:settings
+description: Configure SDD workflow toggles and model profile
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - AskUserQuestion
+---
+
+<objective>
+Interactive configuration of SDD workflow agents and model profile via multi-question prompt.
+
+Routes to the settings workflow which handles:
+- Config existence ensuring
+- Current settings reading and parsing
+- Interactive 5-question prompt (model, research, plan_check, verifier, branching)
+- Config merging and writing
+- Confirmation display with quick command references
+</objective>
+
+<execution_context>
+@~/.claude/sdd/workflows/settings.md
+</execution_context>
+
+<process>
+**Follow the settings workflow** from `@~/.claude/sdd/workflows/settings.md`.
+
+The workflow handles all logic including:
+1. Config file creation with defaults if missing
+2. Current config reading
+3. Interactive settings presentation with pre-selection
+4. Answer parsing and config merging
+5. File writing
+6. Confirmation display
+</process>

package/commands/sdd/ship.md

@@ -0,0 +1,23 @@
+---
+name: sdd:ship
+description: Create PR, run review, and prepare for merge after verification passes
+argument-hint: "[phase number or milestone, e.g., '4' or 'v1.0']"
+allowed-tools:
+  - Read
+  - Bash
+  - Grep
+  - Glob
+  - Write
+  - AskUserQuestion
+---
+<objective>
+Bridge local completion → merged PR. After /sdd:verify-work passes, ship the work: push branch, create PR with auto-generated body, optionally trigger review, and track the merge.
+
+Closes the plan → execute → verify → ship loop.
+</objective>
+
+<execution_context>
+@~/.claude/sdd/workflows/ship.md
+</execution_context>
+
+Execute the ship workflow from @~/.claude/sdd/workflows/ship.md end-to-end.

package/commands/sdd/stats.md

@@ -0,0 +1,18 @@
+---
+name: sdd:stats
+description: Display project statistics — phases, plans, requirements, git metrics, and timeline
+allowed-tools:
+  - Read
+  - Bash
+---
+<objective>
+Display comprehensive project statistics including phase progress, plan execution metrics, requirements completion, git history stats, and project timeline.
+</objective>
+
+<execution_context>
+@~/.claude/sdd/workflows/stats.md
+</execution_context>
+
+<process>
+Execute the stats workflow from @~/.claude/sdd/workflows/stats.md end-to-end.
+</process>

package/commands/sdd/thread.md

@@ -0,0 +1,127 @@
+---
+name: sdd:thread
+description: Manage persistent context threads for cross-session work
+argument-hint: [name | description]
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+---
+
+<objective>
+Create, list, or resume persistent context threads. Threads are lightweight
+cross-session knowledge stores for work that spans multiple sessions but
+doesn't belong to any specific phase.
+</objective>
+
+<process>
+
+**Parse $ARGUMENTS to determine mode:**
+
+<mode_list>
+**If no arguments or $ARGUMENTS is empty:**
+
+List all threads:
+```bash
+ls .planning/threads/*.md 2>/dev/null
+```
+
+For each thread, read the first few lines to show title and status:
+```
+## Active Threads
+
+| Thread | Status | Last Updated |
+|--------|--------|-------------|
+| fix-deploy-key-auth | OPEN | 2026-03-15 |
+| pasta-tcp-timeout | RESOLVED | 2026-03-12 |
+| perf-investigation | IN PROGRESS | 2026-03-17 |
+```
+
+If no threads exist, show:
+```
+No threads found. Create one with: /sdd:thread <description>
+```
+</mode_list>
+
+<mode_resume>
+**If $ARGUMENTS matches an existing thread name (file exists):**
+
+Resume the thread — load its context into the current session:
+```bash
+cat ".planning/threads/${THREAD_NAME}.md"
+```
+
+Display the thread content and ask what the user wants to work on next.
+Update the thread's status to `IN PROGRESS` if it was `OPEN`.
+</mode_resume>
+
+<mode_create>
+**If $ARGUMENTS is a new description (no matching thread file):**
+
+Create a new thread:
+
+1. Generate slug from description:
+   ```bash
+   SLUG=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" generate-slug "$ARGUMENTS")
+   ```
+
+2. Create the threads directory if needed:
+   ```bash
+   mkdir -p .planning/threads
+   ```
+
+3. Write the thread file:
+   ```bash
+   cat > ".planning/threads/${SLUG}.md" << 'EOF'
+   # Thread: {description}
+
+   ## Status: OPEN
+
+   ## Goal
+
+   {description}
+
+   ## Context
+
+   *Created from conversation on {today's date}.*
+
+   ## References
+
+   - *(add links, file paths, or issue numbers)*
+
+   ## Next Steps
+
+   - *(what the next session should do first)*
+   EOF
+   ```
+
+4. If there's relevant context in the current conversation (code snippets,
+   error messages, investigation results), extract and add it to the Context
+   section.
+
+5. Commit:
+   ```bash
+   node "$HOME/.claude/sdd/bin/sdd-tools.cjs" commit "docs: create thread — ${ARGUMENTS}" --files ".planning/threads/${SLUG}.md"
+   ```
+
+6. Report:
+   ```
+   ## 🧵 Thread Created
+
+   Thread: {slug}
+   File: .planning/threads/{slug}.md
+
+   Resume anytime with: /sdd:thread {slug}
+   ```
+</mode_create>
+
+</process>
+
+<notes>
+- Threads are NOT phase-scoped — they exist independently of the roadmap
+- Lighter weight than /sdd:pause-work — no phase state, no plan context
+- The value is in Context and Next Steps — a cold-start session can pick up immediately
+- Threads can be promoted to phases or backlog items when they mature:
+  /sdd:add-phase or /sdd:add-backlog with context from the thread
+- Thread files live in .planning/threads/ — no collision with phases or other SDD structures
+</notes>

package/commands/sdd/ui-phase.md

@@ -0,0 +1,34 @@
+---
+name: sdd:ui-phase
+description: Generate UI design contract (UI-SPEC.md) for frontend phases
+argument-hint: "[phase]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - Task
+  - WebFetch
+  - AskUserQuestion
+  - mcp__context7__*
+---
+<objective>
+Create a UI design contract (UI-SPEC.md) for a frontend phase.
+Orchestrates sdd-ui-researcher and sdd-ui-checker.
+Flow: Validate → Research UI → Verify UI-SPEC → Done
+</objective>
+
+<execution_context>
+@~/.claude/sdd/workflows/ui-phase.md
+@~/.claude/sdd/references/ui-brand.md
+</execution_context>
+
+<context>
+Phase number: $ARGUMENTS — optional, auto-detects next unplanned phase if omitted.
+</context>
+
+<process>
+Execute @~/.claude/sdd/workflows/ui-phase.md end-to-end.
+Preserve all workflow gates.
+</process>

package/commands/sdd/ui-review.md

@@ -0,0 +1,32 @@
+---
+name: sdd:ui-review
+description: Retroactive 6-pillar visual audit of implemented frontend code
+argument-hint: "[phase]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - Task
+  - AskUserQuestion
+---
+<objective>
+Conduct a retroactive 6-pillar visual audit. Produces UI-REVIEW.md with
+graded assessment (1-4 per pillar). Works on any project.
+Output: {phase_num}-UI-REVIEW.md
+</objective>
+
+<execution_context>
+@~/.claude/sdd/workflows/ui-review.md
+@~/.claude/sdd/references/ui-brand.md
+</execution_context>
+
+<context>
+Phase: $ARGUMENTS — optional, defaults to last completed phase.
+</context>
+
+<process>
+Execute @~/.claude/sdd/workflows/ui-review.md end-to-end.
+Preserve all workflow gates.
+</process>

package/commands/sdd/update.md

@@ -0,0 +1,37 @@
+---
+name: sdd:update
+description: Update SDD to latest version with changelog display
+allowed-tools:
+  - Bash
+  - AskUserQuestion
+---
+
+<objective>
+Check for SDD updates, install if available, and display what changed.
+
+Routes to the update workflow which handles:
+- Version detection (local vs global installation)
+- npm version checking
+- Changelog fetching and display
+- User confirmation with clean install warning
+- Update execution and cache clearing
+- Restart reminder
+</objective>
+
+<execution_context>
+@~/.claude/sdd/workflows/update.md
+</execution_context>
+
+<process>
+**Follow the update workflow** from `@~/.claude/sdd/workflows/update.md`.
+
+The workflow handles all logic including:
+1. Installed version detection (local/global)
+2. Latest version checking via npm
+3. Version comparison
+4. Changelog fetching and extraction
+5. Clean install warning display
+6. User confirmation
+7. Update execution
+8. Cache clearing
+</process>