@ktpartners/dgs-platform 2.7.5 → 2.9.0

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>
 
@@ -47,8 +47,8 @@ The spec must have status: final.
 ## 1. Load Context
 
 - Read PROJECT.md (existing project, validated requirements, decisions)
-- Read MILESTONES.md (what shipped previously)
-- Read STATE.md (pending todos, blockers)
+- Read MILESTONES.md (what shipped previously) — if file does not exist, this is the first milestone; skip and use defaults
+- Read STATE.md (pending todos, blockers) — if file does not exist, will be created in Step 5
 - Check for MILESTONE-CONTEXT.md (from /dgs:discuss-milestone)
 
 ## 1b. Spec-Driven Milestone (auto mode only)
@@ -67,7 +67,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 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)
 
@@ -178,6 +178,7 @@ Skip Steps 2-6 (questioning, version determination, update, cleanup, context loa
 ## 3. Determine Milestone Version
 
 - Parse last version from 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 +201,9 @@ Update Active requirements section and "Last updated" footer.
 
 ## 5. Update STATE.md
 
+**If STATE.md does not exist (first milestone):** Create it with the structure below.
+**If STATE.md exists:** Update the Current Position section.
+
 ```markdown
 ## Current Position
 
@@ -264,6 +268,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 +282,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 +429,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 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="