@bhargavvc/sdd-cc 1.30.0 → 1.35.0

package/sdd/workflows/insert-phase.md

@@ -13,7 +13,7 @@ Parse the command arguments:
 - First argument: integer phase number to insert after
 - Remaining arguments: phase description
 
-Example: `/sdd:insert-phase 72 Fix critical auth bug`
+Example: `/sdd-insert-phase 72 Fix critical auth bug`
 -> after = 72
 -> description = "Fix critical auth bug"
 
@@ -21,8 +21,8 @@ If arguments missing:
 
 ```
 ERROR: Both phase number and description required
-Usage: /sdd:insert-phase <after> <description>
-Example: /sdd:insert-phase 72 Fix critical auth bug
+Usage: /sdd-insert-phase <after> <description>
+Example: /sdd-insert-phase 72 Fix critical auth bug
 ```
 
 Exit.
@@ -93,9 +93,9 @@ Project state updated: .planning/STATE.md
 
 **Phase {decimal_phase}: {description}** -- urgent insertion
 
-`/sdd:plan-phase {decimal_phase}`
+`/clear` then:
 
-<sub>`/clear` first -> fresh context window</sub>
+`/sdd-plan-phase {decimal_phase}`
 
 ---
 
@@ -111,11 +111,11 @@ Project state updated: .planning/STATE.md
 
 <anti_patterns>
 
-- Don't use this for planned work at end of milestone (use /sdd:add-phase)
+- Don't use this for planned work at end of milestone (use /sdd-add-phase)
 - Don't insert before Phase 1 (decimal 0.1 makes no sense)
 - Don't renumber existing phases
 - Don't modify the target phase content
-- Don't create plans yet (that's /sdd:plan-phase)
+- Don't create plans yet (that's /sdd-plan-phase)
 - Don't commit changes (user decides when to commit)
 </anti_patterns>
 

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

@@ -14,8 +14,8 @@ Phase number: $ARGUMENTS (required)
 ```
 Error: Phase number required.
 
-Usage: /sdd:list-phase-assumptions [phase-number]
-Example: /sdd:list-phase-assumptions 3
+Usage: /sdd-list-phase-assumptions [phase-number]
+Example: /sdd-list-phase-assumptions 3
 ```
 
 Exit workflow.
@@ -153,8 +153,8 @@ Present next steps:
 
 ```
 What's next?
-1. Discuss context (/sdd:discuss-phase ${PHASE}) - Let me ask you questions to build comprehensive context
-2. Plan this phase (/sdd:plan-phase ${PHASE}) - Create detailed execution plans
+1. Discuss context (/sdd-discuss-phase ${PHASE}) - Let me ask you questions to build comprehensive context
+2. Plan this phase (/sdd-plan-phase ${PHASE}) - Create detailed execution plans
 3. Re-examine assumptions - I'll analyze again with your corrections
 4. Done for now
 ```

package/sdd/workflows/list-workspaces.md

@@ -25,7 +25,7 @@ Parse JSON for: `workspace_base`, `workspaces`, `workspace_count`.
 No workspaces found in ~/sdd-workspaces/
 
 Create one with:
-  /sdd:new-workspace --name my-workspace --repos repo1,repo2
+  /sdd-new-workspace --name my-workspace --repos repo1,repo2
 ```
 
 Done.
@@ -44,7 +44,7 @@ SDD Workspaces (~/sdd-workspaces/)
 
 Manage:
   cd ~/sdd-workspaces/<name>     # Enter a workspace
-  /sdd:remove-workspace <name>   # Remove a workspace
+  /sdd-remove-workspace <name>   # Remove a workspace
 ```
 
 For each workspace, show:

package/sdd/workflows/manager.md

@@ -23,7 +23,14 @@ INIT=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" init manager)
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 ```
 
-Parse JSON for: `milestone_version`, `milestone_name`, `phase_count`, `completed_count`, `in_progress_count`, `phases`, `recommended_actions`, `all_complete`, `waiting_signal`.
+Parse JSON for: `milestone_version`, `milestone_name`, `phase_count`, `completed_count`, `in_progress_count`, `phases`, `recommended_actions`, `all_complete`, `waiting_signal`, `manager_flags`.
+
+`manager_flags` contains per-step passthrough flags from config:
+- `manager_flags.discuss` — appended to `/sdd-discuss-phase` args (e.g. `"--auto --analyze"`)
+- `manager_flags.plan` — appended to plan agent init command
+- `manager_flags.execute` — appended to execute agent init command
+
+These are empty strings by default. Set via: `sdd-tools config-set manager.flags.discuss "--auto --analyze"`
 
 **If error:** Display the error message and exit.
 
@@ -106,17 +113,19 @@ If `all_complete` is true:
 ╚══════════════════════════════════════════════════════════════╝
 
 All {phase_count} phases done. Ready for final steps:
-  → /sdd:verify-work — run acceptance testing
-  → /sdd:complete-milestone — archive and wrap up
+  → /sdd-verify-work — run acceptance testing
+  → /sdd-complete-milestone — archive and wrap up
 ```
 
+
+**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.
 Ask user via AskUserQuestion:
 - **question:** "All phases complete. What next?"
 - **options:** "Verify work" / "Complete milestone" / "Exit manager"
 
 Handle responses:
-- "Verify work": `Skill(skill="sdd:verify-work")`  then loop to dashboard.
-- "Complete milestone": `Skill(skill="sdd:complete-milestone")` then exit.
+- "Verify work": `Skill(skill="sdd-verify-work")`  then loop to dashboard.
+- "Complete milestone": `Skill(skill="sdd-complete-milestone")` then exit.
 - "Exit manager": Go to exit step.
 
 **If NOT all_complete**, build compound options from `recommended_actions`:
@@ -193,24 +202,24 @@ When the user selects a compound option:
 2. **Then run the inline discuss:**
 
 ```
-Skill(skill="sdd:discuss-phase", args="{PHASE_NUM}")
+Skill(skill="sdd-discuss-phase", args="{PHASE_NUM} {manager_flags.discuss}")
 ```
 
 After discuss completes, loop back to dashboard step (background agents continue running).
 
 ### Discuss Phase N
 
-Discussion is interactive — needs user input. Run inline:
+Discussion is interactive — needs user input. Run inline with any configured flags:
 
 ```
-Skill(skill="sdd:discuss-phase", args="{PHASE_NUM}")
+Skill(skill="sdd-discuss-phase", args="{PHASE_NUM} {manager_flags.discuss}")
 ```
 
 After discuss completes, loop back to dashboard step.
 
 ### Plan Phase N
 
-Planning runs autonomously. Spawn a background agent:
+Planning runs autonomously. Spawn a background agent that delegates to the Skill pipeline with any configured flags:
 
 ```
 Task(
@@ -221,17 +230,14 @@ Task(
 Working directory: {cwd}
 Phase: {N} — {phase_name}
 Goal: {goal}
+Manager flags: {manager_flags.plan}
 
-Steps:
-1. Read the plan-phase workflow: cat ~/.claude/sdd/workflows/plan-phase.md
-2. Run: node \"$HOME/.claude/sdd/bin/sdd-tools.cjs\" init plan-phase {N}
-3. Follow the workflow steps to produce PLAN.md files for this phase.
-4. If research is enabled in config, run the research step first.
-5. Spawn a sdd-planner subagent via Task() to create the plans.
-6. If plan-checker is enabled, spawn a sdd-plan-checker subagent to verify.
-7. Commit plan files when complete.
+Run the plan-phase Skill with any configured manager flags:
+Skill(skill=\"sdd-plan-phase\", args=\"{N} --auto {manager_flags.plan}\")
 
-Important: You are running in the background. Do NOT use AskUserQuestion — make autonomous decisions based on project context. If you hit a blocker, write it to STATE.md as a blocker and stop. Do NOT silently work around permission or file access errors — let them fail so the manager can surface them with resolution hints."
+This delegates to the full plan-phase pipeline including local patches, research, plan-checker, and all quality gates.
+
+Important: You are running in the background. Do NOT use AskUserQuestion — make autonomous decisions based on project context. If you hit a blocker, write it to STATE.md as a blocker and stop. Do NOT silently work around permission or file access errors — let them fail so the manager can surface them with resolution hints. Do NOT use --no-verify on git commits."
 )
 ```
 
@@ -245,7 +251,7 @@ Loop back to dashboard step.
 
 ### Execute Phase N
 
-Execution runs autonomously. Spawn a background agent:
+Execution runs autonomously. Spawn a background agent that delegates to the Skill pipeline with any configured flags:
 
 ```
 Task(
@@ -256,17 +262,14 @@ Task(
 Working directory: {cwd}
 Phase: {N} — {phase_name}
 Goal: {goal}
+Manager flags: {manager_flags.execute}
+
+Run the execute-phase Skill with any configured manager flags:
+Skill(skill=\"sdd-execute-phase\", args=\"{N} {manager_flags.execute}\")
 
-Steps:
-1. Read the execute-phase workflow: cat ~/.claude/sdd/workflows/execute-phase.md
-2. Run: node \"$HOME/.claude/sdd/bin/sdd-tools.cjs\" init execute-phase {N}
-3. Follow the workflow steps: discover plans, analyze dependencies, group into waves.
-4. For each wave, spawn sdd-executor subagents via Task() to execute plans in parallel.
-5. After all waves complete, spawn a sdd-verifier subagent if verifier is enabled.
-6. Update ROADMAP.md and STATE.md with progress.
-7. Commit all changes.
+This delegates to the full execute-phase pipeline including local patches, branching, wave-based execution, verification, and all quality gates.
 
-Important: You are running in the background. Do NOT use AskUserQuestion — make autonomous decisions. Use --no-verify on git commits. If you hit a permission error, file lock, or any access issue, do NOT work around it — let it fail and write the error to STATE.md as a blocker so the manager can surface it with resolution guidance."
+Important: You are running in the background. Do NOT use AskUserQuestion — make autonomous decisions. Do NOT use --no-verify on git commits — let pre-commit hooks run normally. If you hit a permission error, file lock, or any access issue, do NOT work around it — let it fail and write the error to STATE.md as a blocker so the manager can surface it with resolution guidance."
 )
 ```
 
@@ -306,7 +309,7 @@ Classify the error:
   - **question:** "Phase {N} failed — permission denied for `{tool_or_command}`. Want me to add it to settings.local.json so it's allowed?"
   - **options:** "Add permission and retry" / "Run this phase inline instead" / "Skip and continue"
   - "Add permission and retry": Use `Skill(skill="update-config")` to add the permission to `settings.local.json`, then re-spawn the background agent. Loop to dashboard.
-  - "Run this phase inline instead": Dispatch the same action (plan/execute) inline via `Skill()` instead of a background Task. Loop to dashboard after.
+  - "Run this phase inline instead": Dispatch the same action inline via the appropriate Skill — use `Skill(skill="sdd-plan-phase", args="{N}")` if the failed action was planning, or `Skill(skill="sdd-execute-phase", args="{N}")` if the failed action was execution. Loop to dashboard after.
   - "Skip and continue": Loop to dashboard (phase stays in current state).
 
 **Other errors** (git lock, file conflict, logic error, etc.):
@@ -314,7 +317,7 @@ Classify the error:
   - **question:** "Background agent for Phase {N} encountered an issue: {error}. What next?"
   - **options:** "Retry" / "Run inline instead" / "Skip and continue" / "View details"
   - "Retry": Re-spawn the same background agent. Loop to dashboard.
-  - "Run inline instead": Dispatch the action inline via `Skill()`. Loop to dashboard after.
+  - "Run inline instead": Dispatch the action inline via the appropriate Skill — use `Skill(skill="sdd-plan-phase", args="{N}")` if the failed action was planning, or `Skill(skill="sdd-execute-phase", args="{N}")` if the failed action was execution. Loop to dashboard after.
   - "Skip and continue": Loop to dashboard (phase stays in current state).
   - "View details": Read STATE.md blockers section, display, then re-present options.
 
@@ -334,11 +337,11 @@ Display final status with progress bar:
  {milestone_version} — {milestone_name}
  {PROGRESS_BAR} {progress_pct}%  ({completed_count}/{phase_count} phases)
 
- Resume anytime: /sdd:manager
+ Resume anytime: /sdd-manager
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
-**Note:** Any background agents still running will continue to completion. Their results will be visible on next `/sdd:manager` or `/sdd:progress` invocation.
+**Note:** Any background agents still running will continue to completion. Their results will be visible on next `/sdd-manager` or `/sdd-progress` invocation.
 
 </step>
 

package/sdd/workflows/map-codebase.md

@@ -36,7 +36,7 @@ if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 AGENT_SKILLS_MAPPER=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" agent-skills sdd-codebase-mapper 2>/dev/null)
 ```
 
-Extract from init JSON: `mapper_model`, `commit_docs`, `codebase_dir`, `existing_maps`, `has_maps`, `codebase_dir_exists`.
+Extract from init JSON: `mapper_model`, `commit_docs`, `codebase_dir`, `existing_maps`, `has_maps`, `codebase_dir_exists`, `subagent_timeout`.
 </step>
 
 <step name="check_existing">
@@ -199,9 +199,11 @@ Wait for all 4 agents to complete using TaskOutput tool.
 TaskOutput tool:
   task_id: "{task_id from Agent result}"
   block: true
-  timeout: 300000
+  timeout: {subagent_timeout from init context, default 300000}
 ```
 
+> The timeout is configurable via `workflow.subagent_timeout` in `.planning/config.json` (milliseconds). Default: 300000 (5 minutes). Increase for large codebases or slower models.
+
 Call TaskOutput for all 4 agents in parallel (single message with 4 TaskOutput calls).
 
 Once all TaskOutput calls return, read each agent's output file to collect confirmations.
@@ -347,14 +349,14 @@ Created .planning/codebase/:
 
 **Initialize project** — use codebase context for planning
 
-`/sdd:new-project`
+`/clear` then:
 
-<sub>`/clear` first → fresh context window</sub>
+`/sdd-new-project`
 
 ---
 
 **Also available:**
-- Re-run mapping: `/sdd:map-codebase`
+- Re-run mapping: `/sdd-map-codebase`
 - Review specific file: `cat .planning/codebase/STACK.md`
 - Edit any document before proceeding
 

package/sdd/workflows/milestone-summary.md

@@ -15,7 +15,7 @@ If `$ARGUMENTS` is empty:
 1. Check `.planning/STATE.md` for current milestone version
 2. Check `.planning/milestones/` for the latest archived version
 3. If neither found, check if `.planning/ROADMAP.md` exists (project may be mid-milestone)
-4. If nothing found: error "No milestone found. Run /sdd:new-project or /sdd:new-milestone first."
+4. If nothing found: error "No milestone found. Run /sdd-new-project or /sdd-new-milestone first."
 
 Set `VERSION` to the resolved version (e.g., "1.0").
 
@@ -212,7 +212,7 @@ If the user asks questions:
 - Stay grounded in what was actually built (not speculation)
 
 If the user is done:
-- Suggest next steps: `/sdd:new-milestone`, `/sdd:progress`, or sharing the summary with the team
+- Suggest next steps: `/sdd-new-milestone`, `/sdd-progress`, or sharing the summary with the team
 
 ## Step 9: Update STATE.md
 

package/sdd/workflows/new-milestone.md

@@ -30,7 +30,7 @@ If the flag is absent, keep the current behavior of continuing phase numbering f
 - Read PROJECT.md (existing project, validated requirements, decisions)
 - Read MILESTONES.md (what shipped previously)
 - Read STATE.md (pending todos, blockers)
-- Check for MILESTONE-CONTEXT.md (from /sdd:discuss-milestone)
+- Check for MILESTONE-CONTEXT.md (from /sdd-discuss-milestone)
 
 ## 2. Gather Milestone Goals
 
@@ -40,6 +40,8 @@ If the flag is absent, keep the current behavior of continuing phase numbering f
 
 **If no context file:**
 - Present what shipped in last milestone
+
+**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.
 - Ask inline (freeform, NOT AskUserQuestion): "What do you want to build next?"
 - Wait for their response, then use AskUserQuestion to probe specifics
 - If user selects "Other" at any point to provide freeform input, ask follow-up as plain text — not another AskUserQuestion
@@ -106,14 +108,14 @@ Ensure the `## Evolution` section exists in PROJECT.md. If missing (projects cre
 
 This document evolves at phase transitions and milestone boundaries.
 
-**After each phase transition** (via `/sdd:transition`):
+**After each phase transition** (via `/sdd-transition`):
 1. Requirements invalidated? → Move to Out of Scope with reason
 2. Requirements validated? → Move to Validated with phase reference
 3. New requirements emerged? → Add to Active
 4. Decisions to log? → Add to Key Decisions
 5. "What This Is" still accurate? → Update if drifted
 
-**After each milestone** (via `/sdd:complete-milestone`):
+**After each milestone** (via `/sdd-complete-milestone`):
 1. Full review of all sections
 2. Core Value check — still the right priority?
 3. Audit Out of Scope — reasons still valid?
@@ -137,6 +139,12 @@ Keep Accumulated Context section from previous milestone.
 
 Delete MILESTONE-CONTEXT.md if exists (consumed).
 
+Clear leftover phase directories from the previous milestone:
+
+```bash
+node "$HOME/.claude/sdd/bin/sdd-tools.cjs" phases clear --confirm
+```
+
 ```bash
 node "$HOME/.claude/sdd/bin/sdd-tools.cjs" commit "docs: start milestone v[X.Y] [Name]" --files .planning/PROJECT.md .planning/STATE.md
 ```
@@ -171,7 +179,7 @@ Then verify `.planning/phases/` no longer contains old milestone directories bef
 
 If `phase_dir_count > 0` but `phase_archive_path` is missing:
 - Stop and explain that reset numbering is unsafe without a completed milestone archive target.
-- Tell the user to complete/archive the previous milestone first, then rerun `/sdd:new-milestone --reset-phase-numbers ${SDD_WS}`.
+- Tell the user to complete/archive the previous milestone first, then rerun `/sdd-new-milestone --reset-phase-numbers ${SDD_WS}`.
 
 ## 8. Research Decision
 
@@ -189,7 +197,7 @@ AskUserQuestion: "Research the domain ecosystem for new features before defining
 - "Skip research (current default)" — Go straight to requirements
 - "Research first" — Discover patterns, features, architecture for NEW capabilities
 
-**IMPORTANT:** Do NOT persist this choice to config.json. The `workflow.research` setting is a persistent user preference that controls plan-phase behavior across the project. Changing it here would silently alter future `/sdd:plan-phase` behavior. To change the default, use `/sdd:settings`.
+**IMPORTANT:** Do NOT persist this choice to config.json. The `workflow.research` setting is a persistent user preference that controls plan-phase behavior across the project. Changing it here would silently alter future `/sdd-plan-phase` behavior. To change the default, use `/sdd-settings`.
 
 **If user chose "Research first":**
 
@@ -459,11 +467,11 @@ node "$HOME/.claude/sdd/bin/sdd-tools.cjs" commit "docs: create milestone v[X.Y]
 
 **Phase [N]: [Phase Name]** — [Goal]
 
-`/sdd:discuss-phase [N] ${SDD_WS}` — gather context and clarify approach
+`/clear` then:
 
-<sub>`/clear` first → fresh context window</sub>
+`/sdd-discuss-phase [N] ${SDD_WS}` — gather context and clarify approach
 
-Also: `/sdd:plan-phase [N] ${SDD_WS}` — skip discussion, plan directly
+Also: `/sdd-plan-phase [N] ${SDD_WS}` — skip discussion, plan directly
 ```
 
 </process>
@@ -480,7 +488,7 @@ Also: `/sdd:plan-phase [N] ${SDD_WS}` — skip discussion, plan directly
 - [ ] User feedback incorporated (if any)
 - [ ] Phase numbering mode respected (continued or reset)
 - [ ] All commits made (if planning docs committed)
-- [ ] User knows next step: `/sdd:discuss-phase [N] ${SDD_WS}`
+- [ ] User knows next step: `/sdd-discuss-phase [N] ${SDD_WS}`
 
 **Atomic commits:** Each phase commits its artifacts immediately.
 </success_criteria>

package/sdd/workflows/new-project.md

@@ -33,7 +33,7 @@ Check if `--auto` flag is present in $ARGUMENTS.
 **Document requirement:**
 Auto mode requires an idea document — either:
 
-- File reference: `/sdd:new-project --auto @prd.md`
+- File reference: `/sdd-new-project --auto @prd.md`
 - Pasted/written text in the prompt
 
 If no document content provided, error:
@@ -42,8 +42,8 @@ If no document content provided, error:
 Error: --auto requires an idea document.
 
 Usage:
-  /sdd:new-project --auto @your-idea.md
-  /sdd:new-project --auto [paste or write your idea here]
+  /sdd-new-project --auto @your-idea.md
+  /sdd-new-project --auto [paste or write your idea here]
 
 The document should describe what you want to build.
 ```
@@ -66,7 +66,30 @@ AGENT_SKILLS_ROADMAPPER=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" agent-skill
 
 Parse JSON for: `researcher_model`, `synthesizer_model`, `roadmapper_model`, `commit_docs`, `project_exists`, `has_codebase_map`, `planning_exists`, `has_existing_code`, `has_package_file`, `is_brownfield`, `needs_codebase_map`, `has_git`, `project_path`.
 
-**If `project_exists` is true:** Error — project already initialized. Use `/sdd:progress`.
+**Detect runtime and set instruction file name:**
+
+Derive `RUNTIME` from the invoking prompt's `execution_context` path:
+- Path contains `/.codex/` → `RUNTIME=codex`
+- Path contains `/.gemini/` → `RUNTIME=gemini`
+- Path contains `/.config/opencode/` or `/.opencode/` → `RUNTIME=opencode`
+- Otherwise → `RUNTIME=claude`
+
+If `execution_context` path is not available, fall back to env vars:
+```bash
+if [ -n "$CODEX_HOME" ]; then RUNTIME="codex"
+elif [ -n "$GEMINI_CONFIG_DIR" ]; then RUNTIME="gemini"
+elif [ -n "$OPENCODE_CONFIG_DIR" ] || [ -n "$OPENCODE_CONFIG" ]; then RUNTIME="opencode"
+else RUNTIME="claude"; fi
+```
+
+Set the instruction file variable:
+```bash
+if [ "$RUNTIME" = "codex" ]; then INSTRUCTION_FILE="AGENTS.md"; else INSTRUCTION_FILE="CLAUDE.md"; fi
+```
+
+All subsequent references to the project instruction file use `$INSTRUCTION_FILE`.
+
+**If `project_exists` is true:** Error — project already initialized. Use `/sdd-progress`.
 
 **If `has_git` is false:** Initialize git:
 
@@ -80,18 +103,20 @@ git init
 
 **If `needs_codebase_map` is true** (from init — existing code detected but no codebase map):
 
+
+**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:
 
 - header: "Codebase"
 - question: "I detected existing code in this directory. Would you like to map the codebase first?"
 - options:
-  - "Map codebase first" — Run /sdd:map-codebase to understand existing architecture (Recommended)
+  - "Map codebase first" — Run /sdd-map-codebase to understand existing architecture (Recommended)
   - "Skip mapping" — Proceed with project initialization
 
 **If "Map codebase first":**
 
 ```
-Run `/sdd:map-codebase` first, then return to `/sdd:new-project`
+Run `/sdd-map-codebase` first, then return to `/sdd-new-project`
 ```
 
 Exit command.
@@ -358,14 +383,14 @@ Initialize with any decisions made during questioning:
 
 This document evolves at phase transitions and milestone boundaries.
 
-**After each phase transition** (via `/sdd:transition`):
+**After each phase transition** (via `/sdd-transition`):
 1. Requirements invalidated? → Move to Out of Scope with reason
 2. Requirements validated? → Move to Validated with phase reference
 3. New requirements emerged? → Add to Active
 4. Decisions to log? → Add to Key Decisions
 5. "What This Is" still accurate? → Update if drifted
 
-**After each milestone** (via `/sdd:complete-milestone`):
+**After each milestone** (via `/sdd-complete-milestone`):
 1. Full review of all sections
 2. Core Value check — still the right priority?
 3. Audit Out of Scope — reasons still valid?
@@ -511,7 +536,7 @@ mkdir -p .planning
 node "$HOME/.claude/sdd/bin/sdd-tools.cjs" config-new-project '{"mode":"[yolo|interactive]","granularity":"[selected]","parallelization":true|false,"commit_docs":true|false,"model_profile":"quality|balanced|budget|inherit","workflow":{"research":true|false,"plan_check":true|false,"verifier":true|false,"nyquist_validation":[false if granularity=coarse, true otherwise]}}'
 ```
 
-**Note:** Run `/sdd:settings` anytime to update model profile, workflow agents, branching strategy, and other preferences.
+**Note:** Run `/sdd-settings` anytime to update model profile, workflow agents, branching strategy, and other preferences.
 
 **If commit_docs = No:**
 
@@ -1106,18 +1131,18 @@ Use AskUserQuestion:
 
 **If "Review full file":** Display raw `cat .planning/ROADMAP.md`, then re-ask.
 
-**Generate or refresh project CLAUDE.md before final commit:**
+**Generate or refresh project instruction file before final commit:**
 
 ```bash
-node "$HOME/.claude/sdd/bin/sdd-tools.cjs" generate-claude-md
+node "$HOME/.claude/sdd/bin/sdd-tools.cjs" generate-claude-md --output "$INSTRUCTION_FILE"
 ```
 
-This ensures new projects get the default SDD workflow-enforcement guidance and current project context in `CLAUDE.md`.
+This ensures new projects get the default SDD workflow-enforcement guidance and current project context in `$INSTRUCTION_FILE`.
 
 **Commit roadmap (after approval or auto mode):**
 
 ```bash
-node "$HOME/.claude/sdd/bin/sdd-tools.cjs" commit "docs: create roadmap ([N] phases)" --files .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md CLAUDE.md
+node "$HOME/.claude/sdd/bin/sdd-tools.cjs" commit "docs: create roadmap ([N] phases)" --files .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md "$INSTRUCTION_FILE"
 ```
 
 ## 9. Done
@@ -1138,7 +1163,7 @@ Present completion summary:
 | Research       | `.planning/research/`       |
 | Requirements   | `.planning/REQUIREMENTS.md` |
 | Roadmap        | `.planning/ROADMAP.md`      |
-| Project guide  | `CLAUDE.md`                 |
+| Project guide  | `$INSTRUCTION_FILE`         |
 
 **[N] phases** | **[X] requirements** | Ready to build ✓
 ```
@@ -1151,7 +1176,7 @@ Present completion summary:
 ╚══════════════════════════════════════════╝
 ```
 
-Exit skill and invoke SlashCommand("/sdd:discuss-phase 1 --auto")
+Exit skill and invoke SlashCommand("/sdd-discuss-phase 1 --auto")
 
 **If interactive mode:**
 
@@ -1171,15 +1196,15 @@ PHASE1_HAS_UI=$(echo "$PHASE1_SECTION" | grep -qi "UI hint.*yes" && echo "true"
 
 **Phase 1: [Phase Name]** — [Goal from ROADMAP.md]
 
-/sdd:discuss-phase 1 — gather context and clarify approach
+/clear then:
 
-<sub>/clear first → fresh context window</sub>
+/sdd-discuss-phase 1 — gather context and clarify approach
 
 ---
 
 **Also available:**
-- /sdd:ui-phase 1 — generate UI design contract (recommended for frontend phases)
-- /sdd:plan-phase 1 — skip discussion, plan directly
+- /sdd-ui-phase 1 — generate UI design contract (recommended for frontend phases)
+- /sdd-plan-phase 1 — skip discussion, plan directly
 
 ───────────────────────────────────────────────────────────────
 ```
@@ -1193,14 +1218,14 @@ PHASE1_HAS_UI=$(echo "$PHASE1_SECTION" | grep -qi "UI hint.*yes" && echo "true"
 
 **Phase 1: [Phase Name]** — [Goal from ROADMAP.md]
 
-/sdd:discuss-phase 1 — gather context and clarify approach
+/clear then:
 
-<sub>/clear first → fresh context window</sub>
+/sdd-discuss-phase 1 — gather context and clarify approach
 
 ---
 
 **Also available:**
-- /sdd:plan-phase 1 — skip discussion, plan directly
+- /sdd-plan-phase 1 — skip discussion, plan directly
 
 ───────────────────────────────────────────────────────────────
 ```
@@ -1220,7 +1245,7 @@ PHASE1_HAS_UI=$(echo "$PHASE1_SECTION" | grep -qi "UI hint.*yes" && echo "true"
 - `.planning/REQUIREMENTS.md`
 - `.planning/ROADMAP.md`
 - `.planning/STATE.md`
-- `CLAUDE.md`
+- `$INSTRUCTION_FILE` (`AGENTS.md` for Codex, `CLAUDE.md` for all other runtimes)
 
 </output>
 
@@ -1242,8 +1267,8 @@ PHASE1_HAS_UI=$(echo "$PHASE1_SECTION" | grep -qi "UI hint.*yes" && echo "true"
 - [ ] ROADMAP.md created with phases, requirement mappings, success criteria
 - [ ] STATE.md initialized
 - [ ] REQUIREMENTS.md traceability updated
-- [ ] CLAUDE.md generated with SDD workflow guidance
-- [ ] User knows next step is `/sdd:discuss-phase 1`
+- [ ] `$INSTRUCTION_FILE` generated with SDD workflow guidance (AGENTS.md for Codex, CLAUDE.md otherwise)
+- [ ] User knows next step is `/sdd-discuss-phase 1`
 
 **Atomic commits:** Each phase commits its artifacts immediately. If context is lost, artifacts persist.
 

package/sdd/workflows/new-workspace.md

@@ -31,6 +31,8 @@ Extract from $ARGUMENTS:
 
 **If `--name` is missing and not `--auto`:**
 
+
+**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:
 - header: "Workspace Name"
 - question: "What should this workspace be called?"
@@ -71,7 +73,7 @@ Error:
 No git repos found in the current directory and this is not a git repo.
 
 Run this command from a directory containing git repos, or specify repos explicitly:
-  /sdd:new-workspace --name my-workspace --repos /path/to/repo1,/path/to/repo2
+  /sdd-new-workspace --name my-workspace --repos /path/to/repo1,/path/to/repo2
 ```
 Exit.
 
@@ -82,7 +84,7 @@ Error:
 Error: --auto requires --repos to specify which repos to include.
 
 Usage:
-  /sdd:new-workspace --name my-workspace --repos repo1,repo2 --auto
+  /sdd-new-workspace --name my-workspace --repos repo1,repo2 --auto
 ```
 Exit.
 
@@ -201,7 +203,7 @@ Workspace created: $TARGET_PATH
 
 Next steps:
   cd $TARGET_PATH
-  /sdd:new-project    # Initialize SDD in the workspace
+  /sdd-new-project    # Initialize SDD in the workspace
 ```
 
 **If some repos failed:**
@@ -214,7 +216,7 @@ Workspace created with $SUCCESS_COUNT of $TOTAL_COUNT repos: $TARGET_PATH
 
 Next steps:
   cd $TARGET_PATH
-  /sdd:new-project    # Initialize SDD in the workspace
+  /sdd-new-project    # Initialize SDD in the workspace
 ```
 
 **Offer to initialize SDD (if not `--auto`):**
@@ -223,7 +225,7 @@ Use AskUserQuestion:
 - header: "Initialize SDD"
 - question: "Would you like to initialize a SDD project in the new workspace?"
 - options:
-  - "Yes — run /sdd:new-project" → tell user to `cd $TARGET_PATH` first, then run `/sdd:new-project`
+  - "Yes — run /sdd-new-project" → tell user to `cd $TARGET_PATH` first, then run `/sdd-new-project`
   - "No — I'll set it up later" → done
 
 </process>