@ktpartners/dgs-platform 2.8.0 → 3.0.4

package/deliver-great-systems/workflows/new-milestone.md

@@ -1,6 +1,6 @@
 <purpose>
 
-Start a new milestone cycle for an existing project. Loads project context, gathers milestone goals (from MILESTONE-CONTEXT.md, conversation, or a finalized spec via --auto), updates PROJECT.md and STATE.md, optionally runs parallel research, defines scoped requirements with REQ-IDs, spawns the roadmapper to create phased execution plan, and commits all artifacts. Brownfield equivalent of new-project. In --auto mode, derives everything from a finalized spec without interactive questioning.
+Start a new milestone cycle for an existing project, or the first milestone after /dgs:new-project. Loads project context, gathers milestone goals (from MILESTONE-CONTEXT.md, conversation, or a finalized spec via --auto), updates PROJECT.md and STATE.md, optionally runs parallel research, defines scoped requirements with REQ-IDs, spawns the roadmapper to create phased execution plan, and commits all artifacts. In --auto mode, derives everything from a finalized spec without interactive questioning.
 
 </purpose>
 
@@ -44,12 +44,28 @@ The spec must have status: final.
 
 <process>
 
+## 0. Resolve Paths and Models
+
+```bash
+INIT=$(node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs init new-milestone)
+```
+
+Extract from init JSON: `researcher_model`, `synthesizer_model`, `roadmapper_model`, `commit_docs`, `research_enabled`, `current_milestone`, `current_milestone_name`, `project_exists`, `roadmap_exists`, `state_exists`, `project_path`, `roadmap_path`, `state_path`, `current_project`, `project_root`.
+
+Load planning-tier context files:
+
+```bash
+TIER_FILES=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" context load-tier planning --raw 2>/dev/null)
+```
+
+All subsequent steps use these resolved paths. Never reference PROJECT.md, STATE.md, etc. by bare name — always use `${project_path}`, `${state_path}`, `${project_root}`, etc.
+
 ## 1. Load Context
 
-- 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 /dgs:discuss-milestone)
+- Read `${project_path}` (existing project, validated requirements, decisions)
+- Read `${project_root}/MILESTONES.md` (what shipped previously) — if file does not exist, this is the first milestone; skip and use defaults
+- Read `${state_path}` (pending todos, blockers) — if file does not exist, will be created in Step 5
+- Check for `${project_root}/MILESTONE-CONTEXT.md` (from /dgs:discuss-milestone)
 
 ## 1b. Spec-Driven Milestone (auto mode only)
 
@@ -67,7 +83,7 @@ Read the spec file and extract:
 
 ### Determine Milestone Version
 
-Parse MILESTONES.md for last version. Suggest next version automatically (e.g., v1.0 → v1.1, or v2.0 for major). In auto mode, use the minor bump without asking.
+Parse `${project_root}/MILESTONES.md` for last version. If no MILESTONES.md exists (first milestone): default to v1.0 (auto mode: use v1.0 without asking). Suggest next version automatically (e.g., v1.0 → v1.1, or v2.0 for major). In auto mode, use the minor bump without asking.
 
 ### Repo Cross-Check (v2 only)
 
@@ -148,7 +164,7 @@ node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "specs: link $SPEC
 
 ### Continue to Step 7
 
-Skip Steps 2-6 (questioning, version determination, update, cleanup, context loading) — they're replaced by spec-driven derivation. Proceed to Step 7 (Load Context and Resolve Models), then:
+Skip Steps 2-6 (questioning, version determination, update, cleanup) — they're replaced by spec-driven derivation. Proceed to Step 8 (Research Decision), then:
 
 - Step 8 (Research Decision): Default to "Research first" in auto mode
 - Step 9 (Define Requirements): Generate from spec instead of interactive scoping:
@@ -166,7 +182,7 @@ Skip Steps 2-6 (questioning, version determination, update, cleanup, context loa
 
 ## 2. Gather Milestone Goals
 
-**If MILESTONE-CONTEXT.md exists:**
+**If `${project_root}/MILESTONE-CONTEXT.md` exists:**
 - Use features and scope from discuss-milestone
 - Present summary for confirmation
 
@@ -177,7 +193,8 @@ Skip Steps 2-6 (questioning, version determination, update, cleanup, context loa
 
 ## 3. Determine Milestone Version
 
-- Parse last version from MILESTONES.md
+- Parse last version from `${project_root}/MILESTONES.md`
+- If no MILESTONES.md exists (first milestone): default to v1.0 and suggest it to user
 - Suggest next version (v1.0 → v1.1, or v2.0 for major)
 - Confirm with user
 
@@ -200,6 +217,9 @@ Update Active requirements section and "Last updated" footer.
 
 ## 5. Update STATE.md
 
+**If `${state_path}` does not exist (first milestone):** Create it with the structure below.
+**If it exists:** Update the Current Position section.
+
 ```markdown
 ## Current Position
 
@@ -213,25 +233,15 @@ Keep Accumulated Context section from previous milestone.
 
 ## 6. Cleanup and Commit
 
-Delete MILESTONE-CONTEXT.md if exists (consumed).
+Delete `${project_root}/MILESTONE-CONTEXT.md` if exists (consumed).
 
 ```bash
 node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "docs: start milestone v[X.Y] [Name]" --push --files ${project_path} ${state_path}
 ```
 
-## 7. Load Context and Resolve Models
-
-```bash
-INIT=$(node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs init new-milestone)
-```
-
-Extract from init JSON: `researcher_model`, `synthesizer_model`, `roadmapper_model`, `commit_docs`, `research_enabled`, `current_milestone`, `project_exists`, `roadmap_exists`.
+## 7. Research Decision Gate
 
-Load planning-tier context files:
-
-```bash
-TIER_FILES=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" context load-tier planning --raw 2>/dev/null)
-```
+Paths and models already resolved in Step 0.
 
 ## 8. Research Decision
 
@@ -264,6 +274,12 @@ node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs config-set workflow.resea
 mkdir -p ${project_root}/research
 ```
 
+**Determine milestone context for researchers:**
+- If MILESTONES.md does not exist (first milestone): Use greenfield framing:
+  `NEW PROJECT — Building [target features] from scratch.`
+- If MILESTONES.md exists (subsequent milestone): Use existing framing:
+  `SUBSEQUENT MILESTONE — Adding [target features] to existing app.`
+
 Spawn 4 parallel dgs-project-researcher agents. Each uses this template with dimension-specific fields:
 
 **Common structure for all 4 researchers:**
@@ -272,7 +288,7 @@ Task(prompt="
 <research_type>Project Research — {DIMENSION} for [new features].</research_type>
 
 <milestone_context>
-SUBSEQUENT MILESTONE — Adding [target features] to existing app.
+{MILESTONE_FRAMING}
 {EXISTING_CONTEXT}
 Focus ONLY on what's needed for the NEW features.
 </milestone_context>
@@ -419,7 +435,7 @@ node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "docs: define mile
 ◆ Spawning roadmapper...
 ```
 
-**Starting phase number:** Read MILESTONES.md for last phase number. Continue from there (v1.0 ended at phase 5 → v1.1 starts at phase 6).
+**Starting phase number:** Read `${project_root}/MILESTONES.md` for last phase number. Continue from there (v1.0 ended at phase 5 → v1.1 starts at phase 6). If no MILESTONES.md exists (first milestone): start phase numbering at 1.
 
 ```
 Task(prompt="