@bhargavvc/sdd-cc 1.35.0 → 1.42.4

package/sdd/workflows/discuss-phase/modes/text.md

@@ -0,0 +1,55 @@
+# --text mode — plain-text overlay (no AskUserQuestion)
+
+> **Lazy-loaded overlay.** Read this file from `workflows/discuss-phase.md`
+> when `--text` is present in `$ARGUMENTS`, OR when
+> `workflow.text_mode: true` is set in config (e.g., per-project default).
+
+## Effect
+
+When text mode is active, **do not use AskUserQuestion at all**. Instead,
+present every question as a plain-text numbered list and ask the user to
+type their choice number. Free-text input maps to the "Other" branch of
+the equivalent AskUserQuestion call.
+
+This is required for Claude Code remote sessions (`/rc` mode) where the
+Claude App cannot forward TUI menu selections back to the host.
+
+## Activation
+
+- Per-session: pass `--text` flag to any command (e.g.,
+  `/sdd:discuss-phase --text`)
+- Per-project: `sdd-sdk query config-set workflow.text_mode true`
+
+Text mode applies to ALL workflows in the session, not just discuss-phase.
+
+## Question rendering
+
+Replace this:
+```text
+AskUserQuestion(
+  header="Layout",
+  question="How should posts be displayed?",
+  options=["Cards", "List", "Timeline"]
+)
+```
+
+With this:
+```text
+Layout — How should posts be displayed?
+  1. Cards
+  2. List
+  3. Timeline
+  4. Other (type freeform)
+
+Reply with a number, or describe your preference.
+```
+
+Wait for the user's reply at the normal prompt. Parse:
+- Numeric reply → mapped to that option
+- Free text → treated as "Other" — reflect it back, confirm, then proceed
+
+## Empty-answer handling
+
+The same answer-validation rules from the parent file apply: empty
+responses trigger one retry, then a clarifying question. Do not proceed
+with empty input.

package/sdd/workflows/discuss-phase/templates/checkpoint.json

@@ -0,0 +1,18 @@
+{
+  "phase": "{PHASE_NUM}",
+  "phase_name": "{phase_name}",
+  "timestamp": "{ISO timestamp}",
+  "areas_completed": ["Area 1", "Area 2"],
+  "areas_remaining": ["Area 3", "Area 4"],
+  "decisions": {
+    "Area 1": [
+      {"question": "...", "answer": "...", "options_presented": ["..."]},
+      {"question": "...", "answer": "...", "options_presented": ["..."]}
+    ],
+    "Area 2": [
+      {"question": "...", "answer": "...", "options_presented": ["..."]}
+    ]
+  },
+  "deferred_ideas": ["..."],
+  "canonical_refs": ["..."]
+}

package/sdd/workflows/discuss-phase/templates/context.md

@@ -0,0 +1,136 @@
+# CONTEXT.md template — for discuss-phase write_context step
+
+> **Lazy-loaded.** Read this file only inside the `write_context` step of
+> `workflows/discuss-phase.md`, immediately before writing
+> `${phase_dir}/${padded_phase}-CONTEXT.md`. Do not put a reference to this
+> file in `<required_reading>` — that defeats the progressive-disclosure
+> savings introduced by issue #2551.
+
+## Variable substitutions
+
+The caller substitutes:
+- `[X]` → phase number
+- `[Name]` → phase name
+- `[date]` → ISO date when context was gathered
+- `${padded_phase}` → zero-padded phase number (e.g., `07`, `15`)
+- `{N}` → counts (requirements, etc.)
+
+## Conditional sections
+
+- **`<spec_lock>`** — include only when `spec_loaded = true` (a `*-SPEC.md`
+  was found by `check_spec`). Otherwise omit the entire `<spec_lock>` block.
+- **Folded Todos / Reviewed Todos** — include subsections only when the
+  `cross_reference_todos` step folded or reviewed at least one todo.
+
+## Template body
+
+```markdown
+# Phase [X]: [Name] - Context
+
+**Gathered:** [date]
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+[Clear statement of what this phase delivers — the scope anchor]
+
+</domain>
+
+[If spec_loaded = true, insert this section:]
+<spec_lock>
+## Requirements (locked via SPEC.md)
+
+**{N} requirements are locked.** See `{padded_phase}-SPEC.md` for full requirements, boundaries, and acceptance criteria.
+
+Downstream agents MUST read `{padded_phase}-SPEC.md` before planning or implementing. Requirements are not duplicated here.
+
+**In scope (from SPEC.md):** [copy the "In scope" bullet list from SPEC.md Boundaries]
+**Out of scope (from SPEC.md):** [copy the "Out of scope" bullet list from SPEC.md Boundaries]
+
+</spec_lock>
+
+<decisions>
+## Implementation Decisions
+
+### [Category 1 that was discussed]
+- **D-01:** [Decision or preference captured]
+- **D-02:** [Another decision if applicable]
+
+### [Category 2 that was discussed]
+- **D-03:** [Decision or preference captured]
+
+### Claude's Discretion
+[Areas where user said "you decide" — note that Claude has flexibility here]
+
+### Folded Todos
+[If any todos were folded into scope from the cross_reference_todos step, list them here.
+Each entry should include the todo title, original problem, and how it fits this phase's scope.
+If no todos were folded: omit this subsection entirely.]
+
+</decisions>
+
+<canonical_refs>
+## Canonical References
+
+**Downstream agents MUST read these before planning or implementing.**
+
+[MANDATORY section. Write the FULL accumulated canonical refs list here.
+Sources: ROADMAP.md refs + REQUIREMENTS.md refs + user-referenced docs during
+discussion + any docs discovered during codebase scout. Group by topic area.
+Every entry needs a full relative path — not just a name.]
+
+### [Topic area 1]
+- `path/to/adr-or-spec.md` — [What it decides/defines that's relevant]
+- `path/to/doc.md` §N — [Specific section reference]
+
+### [Topic area 2]
+- `path/to/feature-doc.md` — [What this doc defines]
+
+[If no external specs: "No external specs — requirements fully captured in decisions above"]
+
+</canonical_refs>
+
+<code_context>
+## Existing Code Insights
+
+### Reusable Assets
+- [Component/hook/utility]: [How it could be used in this phase]
+
+### Established Patterns
+- [Pattern]: [How it constrains/enables this phase]
+
+### Integration Points
+- [Where new code connects to existing system]
+
+</code_context>
+
+<specifics>
+## Specific Ideas
+
+[Any particular references, examples, or "I want it like X" moments from discussion]
+
+[If none: "No specific requirements — open to standard approaches"]
+
+</specifics>
+
+<deferred>
+## Deferred Ideas
+
+[Ideas that came up but belong in other phases. Don't lose them.]
+
+### Reviewed Todos (not folded)
+[If any todos were reviewed in cross_reference_todos but not folded into scope,
+list them here so future phases know they were considered.
+Each entry: todo title + reason it was deferred (out of scope, belongs in Phase Y, etc.)
+If no reviewed-but-deferred todos: omit this subsection entirely.]
+
+[If none: "None — discussion stayed within phase scope"]
+
+</deferred>
+
+---
+
+*Phase: [X]-[Name]*
+*Context gathered: [date]*
+```

package/sdd/workflows/discuss-phase/templates/discussion-log.md

@@ -0,0 +1,50 @@
+# DISCUSSION-LOG.md template — for discuss-phase git_commit step
+
+> **Lazy-loaded.** Read this file only inside the `git_commit` step of
+> `workflows/discuss-phase.md`, immediately before writing
+> `${phase_dir}/${padded_phase}-DISCUSSION-LOG.md`.
+
+## Purpose
+
+Audit trail for human review (compliance, learning, retrospectives). NOT
+consumed by downstream agents — those read CONTEXT.md only.
+
+## Template body
+
+```markdown
+# Phase [X]: [Name] - Discussion Log
+
+> **Audit trail only.** Do not use as input to planning, research, or execution agents.
+> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered.
+
+**Date:** [ISO date]
+**Phase:** [phase number]-[phase name]
+**Areas discussed:** [comma-separated list]
+
+---
+
+[For each gray area discussed:]
+
+## [Area Name]
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| [Option 1] | [Description from AskUserQuestion] | |
+| [Option 2] | [Description] | ✓ |
+| [Option 3] | [Description] | |
+
+**User's choice:** [Selected option or free-text response]
+**Notes:** [Any clarifications, follow-up context, or rationale the user provided]
+
+---
+
+[Repeat for each area]
+
+## Claude's Discretion
+
+[List areas where user said "you decide" or deferred to Claude]
+
+## Deferred Ideas
+
+[Ideas mentioned during discussion that were noted for future phases]
+```

package/sdd/workflows/discuss-phase-assumptions.md

@@ -64,9 +64,9 @@ plain-text numbered list and ask the user to type their choice number.
 Phase number from argument (required).
 
 ```bash
-INIT=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" init phase-op "${PHASE}")
+INIT=$(sdd-sdk query init.phase-op "${PHASE}")
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
-AGENT_SKILLS_ANALYZER=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" agent-skills sdd-assumptions-analyzer 2>/dev/null)
+AGENT_SKILLS_ANALYZER=$(sdd-sdk query agent-skills sdd-assumptions-analyzer)
 ```
 
 Parse JSON for: `commit_docs`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`,
@@ -77,7 +77,7 @@ Parse JSON for: `commit_docs`, `phase_found`, `phase_dir`, `phase_number`, `phas
 ```
 Phase [X] not found in roadmap.
 
-Use /sdd-progress to see available phases.
+Use /sdd:progress to see available phases.
 ```
 Exit workflow.
 
@@ -171,7 +171,7 @@ Structure the extracted information for use in assumption generation.
 Check if any pending todos are relevant to this phase's scope.
 
 ```bash
-TODO_MATCHES=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" todo match-phase "${PHASE_NUMBER}")
+TODO_MATCHES=$(sdd-sdk query todo.match-phase "${PHASE_NUMBER}")
 ```
 
 Parse JSON for: `todo_count`, `matches[]`.
@@ -254,7 +254,7 @@ If no USER-PROFILE.md: calibration_tier = "standard"
 **Spawn Explore subagent:**
 
 ```
-Task(subagent_type="sdd-assumptions-analyzer", prompt="""
+Agent(subagent_type="sdd-assumptions-analyzer", prompt="""
 Analyze the codebase for Phase {PHASE}: {phase_name}.
 
 Phase goal: {roadmap_description}
@@ -294,6 +294,8 @@ ${AGENT_SKILLS_ANALYZER}
 """)
 ```
 
+> **ORCHESTRATOR RULE — CODEX RUNTIME**: After calling Agent() above, stop working on this task immediately. Do not read more files, analyze the codebase, or process assumptions while the subagent is active. Wait for the subagent to return its result. This prevents duplicate work, conflicting edits, and wasted context. Only resume when the subagent result is available.
+
 Parse the subagent's response. Extract:
 - `assumptions[]` — each with area, statement, evidence, consequence, confidence
 - `needs_research[]` — topics requiring external research (may be empty)
@@ -310,7 +312,7 @@ Parse the subagent's response. Extract:
 If research topics were flagged, spawn a general-purpose research agent:
 
 ```
-Task(subagent_type="general-purpose", prompt="""
+Agent(subagent_type="general-purpose", prompt="""
 Research the following topics for Phase {PHASE}: {phase_name}.
 
 Topics needing research:
@@ -324,6 +326,8 @@ For each topic, return:
 Use Context7 (resolve-library-id then query-docs) for library-specific questions.
 Use WebSearch for ecosystem/best-practice questions.
 """)
+
+> **ORCHESTRATOR RULE — CODEX RUNTIME**: After calling Agent() above, stop working on this task immediately. Do not independently research any of these topics while the subagent is active. Wait for the subagent to return its result. This prevents duplicate work and wasted context. Only resume when the subagent result is available.
 ```
 
 Merge findings back into assumptions:
@@ -548,7 +552,7 @@ Write file.
 Commit phase context and discussion log:
 
 ```bash
-node "$HOME/.claude/sdd/bin/sdd-tools.cjs" commit "docs(${padded_phase}): capture phase context (assumptions mode)" --files "${phase_dir}/${padded_phase}-CONTEXT.md" "${phase_dir}/${padded_phase}-DISCUSSION-LOG.md"
+sdd-sdk query commit "docs(${padded_phase}): capture phase context (assumptions mode)" --files "${phase_dir}/${padded_phase}-CONTEXT.md" "${phase_dir}/${padded_phase}-DISCUSSION-LOG.md"
 ```
 
 Confirm: "Committed: docs(${padded_phase}): capture phase context (assumptions mode)"
@@ -558,7 +562,7 @@ Confirm: "Committed: docs(${padded_phase}): capture phase context (assumptions m
 Update STATE.md with session info:
 
 ```bash
-node "$HOME/.claude/sdd/bin/sdd-tools.cjs" state record-session \
+sdd-sdk query state.record-session \
   --stopped-at "Phase ${PHASE} context gathered (assumptions mode)" \
   --resume-file "${phase_dir}/${padded_phase}-CONTEXT.md"
 ```
@@ -566,7 +570,7 @@ node "$HOME/.claude/sdd/bin/sdd-tools.cjs" state record-session \
 Commit STATE.md:
 
 ```bash
-node "$HOME/.claude/sdd/bin/sdd-tools.cjs" commit "docs(state): record phase ${PHASE} context session" --files .planning/STATE.md
+sdd-sdk query commit "docs(state): record phase ${PHASE} context session" --files .planning/STATE.md
 ```
 </step>
 
@@ -593,19 +597,19 @@ Created: .planning/phases/${PADDED_PHASE}-${SLUG}/${PADDED_PHASE}-CONTEXT.md
 
 ---
 
-## ▶ Next Up
+## ▶ Next Up — [${PROJECT_CODE}] ${PROJECT_TITLE}
 
 **Phase ${PHASE}: {phase_name}** — {Goal from ROADMAP.md}
 
 `/clear` then:
 
-`/sdd-plan-phase ${PHASE}`
+`/sdd:plan-phase ${PHASE}`
 
 ---
 
 **Also available:**
-- `/sdd-plan-phase ${PHASE} --skip-research` — plan without research
-- `/sdd-ui-phase ${PHASE}` — generate UI design contract (if frontend work)
+- `/sdd:plan-phase ${PHASE} --skip-research` — plan without research
+- `/sdd:ui-phase ${PHASE}` — generate UI design contract (if frontend work)
 - Review/edit CONTEXT.md before continuing
 
 ---
@@ -619,24 +623,23 @@ Check for auto-advance trigger:
 2. Sync chain flag:
    ```bash
    if [[ ! "$ARGUMENTS" =~ --auto ]]; then
-     node "$HOME/.claude/sdd/bin/sdd-tools.cjs" config-set workflow._auto_chain_active false 2>/dev/null
+     sdd-sdk query config-set workflow._auto_chain_active false || true
    fi
    ```
-3. Read chain flag and user preference:
+3. Read consolidated auto-mode (`active` = chain flag OR user preference):
    ```bash
-   AUTO_CHAIN=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" config-get workflow._auto_chain_active 2>/dev/null || echo "false")
-   AUTO_CFG=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" config-get workflow.auto_advance 2>/dev/null || echo "false")
+   AUTO_MODE=$(sdd-sdk query check auto-mode --pick active 2>/dev/null || echo "false")
    ```
 
-**If `--auto` flag present AND `AUTO_CHAIN` is not true:**
+**If `--auto` flag present AND `AUTO_MODE` is not true:**
 ```bash
-node "$HOME/.claude/sdd/bin/sdd-tools.cjs" config-set workflow._auto_chain_active true
+sdd-sdk query config-set workflow._auto_chain_active true
 ```
 
-**If `--auto` flag present OR `AUTO_CHAIN` is true OR `AUTO_CFG` is true:**
+**If `--auto` flag present OR `AUTO_MODE` is true:**
 
 Display banner:
-```
+```text
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  SDD ► AUTO-ADVANCING TO PLAN
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

package/sdd/workflows/discuss-phase-power.md

@@ -5,7 +5,7 @@ Power user mode for discuss-phase. Generates ALL questions upfront into a JSON s
 </purpose>
 
 <trigger>
-This workflow executes when `--power` flag is present in ARGUMENTS to `/sdd-discuss-phase`.
+This workflow executes when `--power` flag is present in ARGUMENTS to `/sdd:discuss-phase`.
 
 The caller (discuss-phase.md) has already:
 - Validated the phase exists
@@ -265,7 +265,7 @@ Process all answered questions from the JSON file and generate CONTEXT.md.
 ```
 Warning: Only {answered}/{total} questions answered ({pct}%).
 CONTEXT.md generated with available decisions. Unanswered questions listed as deferred.
-Consider running /sdd-discuss-phase {N} again to refine before planning.
+Consider running /sdd:discuss-phase {N} again to refine before planning.
 ```
 
 7. Print completion message:
@@ -275,7 +275,7 @@ CONTEXT.md written: {phase_dir}/{padded_phase}-CONTEXT.md
   Decisions captured: {answered}
   Deferred:          {remaining}
 
-Next step: /sdd-plan-phase {N}
+Next step: /sdd:plan-phase {N}
 ```
 </step>