@bhargavvc/sdd-cc 1.35.0 → 1.42.4

package/sdd/workflows/new-milestone.md

@@ -46,6 +46,55 @@ If the flag is absent, keep the current behavior of continuing phase numbering f
 - 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
 
+## 2.5. Scan Planted Seeds
+
+Check `.planning/seeds/` for seed files that match the milestone goals gathered in step 2.
+
+```bash
+ls .planning/seeds/SEED-*.md 2>/dev/null
+```
+
+**If no seed files exist:** Skip this step silently — do not print any message or prompt.
+
+**If seed files exist:** Read each `SEED-*.md` file and extract from its frontmatter and body:
+- **Idea** — the seed title (heading after frontmatter, e.g. `# SEED-001: <idea>`)
+- **Trigger conditions** — the `trigger_when` frontmatter field and the "When to Surface" section's bullet list
+- **Planted during** — the `planted_during` frontmatter field (for context)
+
+Compare each seed's trigger conditions against the milestone goals from step 2. A seed matches when its trigger conditions are relevant to any of the milestone's target features or goals.
+
+**If no seeds match:** Skip silently — do not prompt the user.
+
+**If matching seeds found:**
+
+**`--auto` mode:** Auto-select ALL matching seeds. Log: `[auto] Selected N matching seed(s): [list seed names]`
+
+**Text mode (`TEXT_MODE=true`):** Present matching seeds as a plain-text numbered list:
+```
+Seeds that match your milestone goals:
+1. SEED-001: <idea> (trigger: <trigger_when>)
+2. SEED-003: <idea> (trigger: <trigger_when>)
+
+Enter numbers to include (comma-separated), or "none" to skip:
+```
+
+**Normal mode:** Present via AskUserQuestion:
+```
+AskUserQuestion(
+  header: "Seeds",
+  question: "These planted seeds match your milestone goals. Include any in this milestone's scope?",
+  multiSelect: true,
+  options: [
+    { label: "SEED-001: <idea>", description: "Trigger: <trigger_when> | Planted during: <planted_during>" },
+    ...
+  ]
+)
+```
+
+**After selection:**
+- Selected seeds become additional context for requirement definition in step 9. Store them in an accumulator (e.g. `$SELECTED_SEEDS`) so step 9 can reference the ideas and their "Why This Matters" sections when defining requirements.
+- Unselected seeds remain untouched in `.planning/seeds/` — never delete or modify seed files during this workflow.
+
 ## 3. Determine Milestone Version
 
 - Parse last version from MILESTONES.md
@@ -115,7 +164,7 @@ This document evolves at phase transitions and milestone boundaries.
 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?
@@ -124,6 +173,19 @@ This document evolves at phase transitions and milestone boundaries.
 
 ## 5. Update STATE.md
 
+Reset STATE.md frontmatter AND body atomically via the SDK. This writes the new
+milestone version/name into the YAML frontmatter, resets `status` to
+`planning`, zeroes `progress.*` counters, and rewrites the `## Current Position`
+section to the new-milestone template. Accumulated Context (decisions,
+blockers, todos) is preserved across the switch — symmetric with
+`milestone.complete`.
+
+```bash
+sdd-sdk query state.milestone-switch --milestone "v[X.Y]" --name "[Name]"
+```
+
+The resulting Current Position section looks like:
+
 ```markdown
 ## Current Position
 
@@ -133,7 +195,11 @@ Status: Defining requirements
 Last activity: [today] — Milestone v[X.Y] started
 ```
 
-Keep Accumulated Context section from previous milestone.
+Bug #2630: a prior version of this workflow rewrote the Current Position body
+manually but left the frontmatter pointing at the previous milestone, so every
+downstream reader (`state.json`, `getMilestoneInfo`, progress bars) reported the
+stale milestone until the first phase advance forced a resync. Always use the
+SDK handler above — do not hand-edit STATE.md here.
 
 ## 6. Cleanup and Commit
 
@@ -142,24 +208,38 @@ 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
+sdd-sdk query 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
+sdd-sdk query commit "docs: start milestone v[X.Y] [Name]" --files .planning/PROJECT.md .planning/STATE.md
 ```
 
 ## 7. Load Context and Resolve Models
 
 ```bash
-INIT=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" init new-milestone)
+INIT=$(sdd-sdk query init.new-milestone)
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
-AGENT_SKILLS_RESEARCHER=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" agent-skills sdd-project-researcher 2>/dev/null)
-AGENT_SKILLS_SYNTHESIZER=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" agent-skills sdd-synthesizer 2>/dev/null)
-AGENT_SKILLS_ROADMAPPER=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" agent-skills sdd-roadmapper 2>/dev/null)
+AGENT_SKILLS_RESEARCHER=$(sdd-sdk query agent-skills sdd-project-researcher)
+AGENT_SKILLS_SYNTHESIZER=$(sdd-sdk query agent-skills sdd-research-synthesizer)
+AGENT_SKILLS_ROADMAPPER=$(sdd-sdk query agent-skills sdd-roadmapper)
 ```
 
-Extract from init JSON: `researcher_model`, `synthesizer_model`, `roadmapper_model`, `commit_docs`, `research_enabled`, `current_milestone`, `project_exists`, `roadmap_exists`, `latest_completed_milestone`, `phase_dir_count`, `phase_archive_path`.
+Extract from init JSON: `researcher_model`, `synthesizer_model`, `roadmapper_model`, `commit_docs`, `research_enabled`, `current_milestone`, `project_exists`, `roadmap_exists`, `latest_completed_milestone`, `phase_dir_count`, `phase_archive_path`, `agents_installed`, `missing_agents`.
+
+**If `agents_installed` is false:** Display a warning before proceeding:
+```
+⚠ SDD agents not installed. The following agents are missing from your agents directory:
+  {missing_agents joined with newline}
+
+Subagent spawns (sdd-project-researcher, sdd-research-synthesizer, sdd-roadmapper) will fail
+with "agent type not found". Run the installer with --global to make agents available:
+
+  npx @bhargavvc/sdd-cc@latest --global
+
+Proceeding without research subagents — roadmap will be generated inline.
+```
+Skip the parallel research spawn step and generate the roadmap inline.
 
 ## 7.5 Reset-phase safety (only when `--reset-phase-numbers`)
 
@@ -179,7 +259,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
 
@@ -197,7 +277,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":**
 
@@ -217,8 +297,8 @@ mkdir -p .planning/research
 Spawn 4 parallel sdd-project-researcher agents. Each uses this template with dimension-specific fields:
 
 **Common structure for all 4 researchers:**
-```
-Task(prompt="
+```text
+Agent(prompt="
 <research_type>Project Research — {DIMENSION} for [new features].</research_type>
 
 <milestone_context>
@@ -256,10 +336,12 @@ Use template: ~/.claude/sdd/templates/research-project/{FILE}
 | GATES | Versions current (verify with Context7), rationale explains WHY, integration considered | Categories clear, complexity noted, dependencies identified | Integration points identified, new vs modified explicit, build order considers deps | Pitfalls specific to adding these features, integration pitfalls covered, prevention actionable |
 | FILE | STACK.md | FEATURES.md | ARCHITECTURE.md | PITFALLS.md |
 
+> **ORCHESTRATOR RULE — CODEX RUNTIME**: After calling all 4 researcher Agent() calls above, do NOT read research files or synthesize content independently while the subagents are active. Wait for all 4 researchers to complete before spawning the synthesizer. This prevents duplicate work and wasted context.
+
 After all 4 complete, spawn synthesizer:
 
-```
-Task(prompt="
+```text
+Agent(prompt="
 Synthesize research outputs into SUMMARY.md.
 
 <files_to_read>
@@ -277,6 +359,8 @@ Commit after writing.
 ", subagent_type="sdd-research-synthesizer", model="{synthesizer_model}", description="Synthesize research")
 ```
 
+> **ORCHESTRATOR RULE — CODEX RUNTIME**: After calling Agent() above, stop working on this task immediately. Do not read more files, edit code, or run tests related to this task 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.
+
 Display key findings from SUMMARY.md:
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -300,6 +384,8 @@ Display key findings from SUMMARY.md:
 
 Read PROJECT.md: core value, current milestone goals, validated requirements (what exists).
 
+**If `$SELECTED_SEEDS` is non-empty (from step 2.5):** Include selected seed ideas and their "Why This Matters" sections as additional input when defining requirements. Seeds provide user-validated feature ideas that should be incorporated into the requirement categories alongside research findings or conversation-gathered features.
+
 **If research exists:** Read FEATURES.md, extract feature categories.
 
 Present features by category:
@@ -358,7 +444,7 @@ If "adjust": Return to scoping.
 
 **Commit requirements:**
 ```bash
-node "$HOME/.claude/sdd/bin/sdd-tools.cjs" commit "docs: define milestone v[X.Y] requirements" --files .planning/REQUIREMENTS.md
+sdd-sdk query commit "docs: define milestone v[X.Y] requirements" --files .planning/REQUIREMENTS.md
 ```
 
 ## 10. Create Roadmap
@@ -375,8 +461,8 @@ node "$HOME/.claude/sdd/bin/sdd-tools.cjs" commit "docs: define milestone v[X.Y]
 - If `--reset-phase-numbers` is active, start at **Phase 1**
 - Otherwise, continue from the previous milestone's last phase number (v1.0 ended at phase 5 → v1.1 starts at phase 6)
 
-```
-Task(prompt="
+```text
+Agent(prompt="
 <planning_context>
 <files_to_read>
 - .planning/PROJECT.md
@@ -407,6 +493,8 @@ Write files first, then return.
 ", subagent_type="sdd-roadmapper", model="{roadmapper_model}", description="Create roadmap")
 ```
 
+> **ORCHESTRATOR RULE — CODEX RUNTIME**: After calling Agent() above, stop working on this task immediately. Do not read more files, edit code, or run tests related to this task 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.
+
 **Handle return:**
 
 **If `## ROADMAP BLOCKED`:** Present blocker, work with user, re-spawn.
@@ -442,7 +530,57 @@ Success criteria:
 
 **Commit roadmap** (after approval):
 ```bash
-node "$HOME/.claude/sdd/bin/sdd-tools.cjs" commit "docs: create milestone v[X.Y] roadmap ([N] phases)" --files .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md
+sdd-sdk query commit "docs: create milestone v[X.Y] roadmap ([N] phases)" --files .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md
+```
+
+## 10.5. Link Pending Todos to Roadmap Phases
+
+After roadmap approval, scan pending todos against the newly approved phases. For each todo whose scope matches a phase, tag it with `resolves_phase: N` in its YAML frontmatter.
+
+**Check for pending todos:**
+```bash
+PENDING_TODOS=$(ls .planning/todos/pending/*.md 2>/dev/null | head -50)
+```
+
+**If no pending todos exist:** Skip this step silently.
+
+**If pending todos exist:**
+
+Read the approved ROADMAP.md and extract the phase list: phase number, phase name, goal, and requirement IDs.
+
+For each pending todo, compare:
+- The todo's `title` and `area` frontmatter fields
+- The todo body (Problem and Solution sections)
+
+Against each phase's:
+- Phase goal
+- Requirement IDs and descriptions
+
+**Match criteria (best-effort — do not over-match):** A todo is considered resolved by a phase if the phase's goal or requirements directly describe implementing the same feature, area, or capability as the todo. Narrow, specific todos with concrete scopes are the best candidates. Vague or cross-cutting todos should be left unlinked.
+
+**For each matched todo**, add `resolves_phase: [N]` to the YAML frontmatter block (after the existing fields):
+```yaml
+---
+created: [existing]
+title: [existing]
+area: [existing]
+resolves_phase: [N]
+files: [existing]
+---
+```
+
+**Only modify todos that have a clear, confident match.** Leave unmatched todos unmodified.
+
+**If any todos were linked:**
+```bash
+sdd-sdk query commit "docs: tag [count] pending todos with resolves_phase after milestone v[X.Y] roadmap" --files .planning/todos/pending/*.md
+```
+
+Print a summary:
+```
+◆ Linked [N] pending todos to roadmap phases:
+  → [todo title] → Phase [N]: [Phase Name]
+  (Leave [M] unmatched todos in pending/)
 ```
 
 ## 11. Done
@@ -463,15 +601,15 @@ node "$HOME/.claude/sdd/bin/sdd-tools.cjs" commit "docs: create milestone v[X.Y]
 
 **[N] phases** | **[X] requirements** | Ready to build ✓
 
-## ▶ Next Up
+## ▶ Next Up — [${PROJECT_CODE}] ${PROJECT_TITLE}
 
 **Phase [N]: [Phase Name]** — [Goal]
 
 `/clear` then:
 
-`/sdd-discuss-phase [N] ${SDD_WS}` — gather context and clarify approach
+`/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>
@@ -488,7 +626,9 @@ 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}`
+- [ ] Pending todos scanned for phase matches; matched todos tagged with `resolves_phase: N`
+- [ ] User knows next step: `/sdd:discuss-phase [N] ${SDD_WS}`
 
 **Atomic commits:** Each phase commits its artifacts immediately.
 </success_criteria>
+</output>