@ktpartners/dgs-platform 2.6.2

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

@@ -0,0 +1,591 @@
+<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.
+
+</purpose>
+
+<context_tier>planning</context_tier>
+
+<required_reading>
+
+Read all files referenced by the invoking prompt's execution_context before starting.
+
+</required_reading>
+
+<auto_mode>
+## Auto Mode Detection
+
+Check if `--auto` flag is present in $ARGUMENTS.
+
+**If auto mode with spec reference:**
+
+The `--auto` argument must reference a spec file path or spec ID (starting with `spec-` or ending in `.md` within `${project_root}/specs/`).
+
+1. Read the spec file
+2. Validate the spec has `status: final` — if not, error:
+   ```
+   Error: Spec must be finalized before creating a milestone. Run /dgs:write-spec to complete it.
+   ```
+3. Enter spec-driven flow (replaces Steps 2-5, feeds into Steps 7-10)
+
+**If --auto without spec reference:** Error:
+```
+Error: --auto requires a finalized spec reference.
+
+Usage:
+  /dgs:new-milestone --auto <spec-id>                # From spec ID
+  /dgs:new-milestone --auto @${project_root}/specs/X.md    # From spec file path
+
+The spec must have status: final.
+```
+
+**Scope rule:** Each spec creates exactly ONE milestone. If the user wants multiple milestones, they should write separate specs for each scope.
+</auto_mode>
+
+<process>
+
+## 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)
+
+## 1b. Spec-Driven Milestone (auto mode only)
+
+**Triggered when:** `--auto` argument references a spec file.
+
+### Parse the Spec
+
+Read the spec file and extract:
+- **Title** → milestone name
+- **Problem** section → milestone goal description
+- **Goals** section → target features
+- **Non-Goals** section → out of scope
+- **Requirements** (P0/P1/P2) → milestone requirements (P0 + P1 for this milestone, P2 deferred)
+- **"Repos likely touched"** or Technical Considerations → repos for cross-checking
+
+### 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.
+
+### Repo Cross-Check (v2 only)
+
+If v2 install (REPOS.md exists):
+
+```bash
+REPOS_JSON=$(node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs repos list --raw)
+```
+
+Compare spec-mentioned repos against registered repos. For each unregistered repo, use AskUserQuestion with 4 options:
+
+```
+AskUserQuestion([{
+  question: "Repo '{repo_name}' mentioned in spec is not registered. How should we handle it?",
+  header: "Repo",
+  multiSelect: false,
+  options: [
+    { label: "Continue", description: "Proceed without registering this repo" },
+    { label: "Register existing", description: "Register an already-existing repo at this path" },
+    { label: "Create + Register", description: "Create folder, git init, and register" },
+    { label: "Cancel", description: "Stop milestone creation" }
+  ]
+}])
+```
+
+Handle each choice identically to new-project's repo cross-check:
+- **Continue:** Skip, proceed
+- **Register existing:** Ask path, run `repos add`
+- **Create + Register:** `mkdir -p`, `git init`, `repos add`
+- **Cancel:** Stop with message: "Milestone creation cancelled. Resolve repo registration and try again."
+
+If no unregistered repos OR not v2: skip silently.
+
+### Update PROJECT.md
+
+Add/update the Current Milestone section:
+
+```markdown
+## Current Milestone: v[X.Y] [Spec Title]
+
+**Goal:** [Derived from spec Problem section — one sentence]
+**Source Spec:** `[relative path to spec file]`
+
+**Target features:**
+[From spec Goals section, as bullet list]
+```
+
+### Update STATE.md
+
+```markdown
+## Current Position
+
+Phase: Not started (defining requirements)
+Plan: —
+Status: Defining requirements
+Last activity: [today] — Milestone v[X.Y] started (from spec [spec-id])
+```
+
+### Commit
+
+```bash
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "docs: start milestone v[X.Y] [Name] (from spec)" --files ${project_path} ${state_path}
+```
+
+### Link Spec to Milestone
+
+Update the spec's milestones frontmatter to record the bidirectional link:
+
+```bash
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs specs link-milestone --id "$SPEC_ID" --milestone "v$VERSION"
+```
+
+Include the updated spec file in a commit:
+
+```bash
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "specs: link $SPEC_ID to v$VERSION" --files ${project_root}/specs/$SPEC_FILENAME
+```
+
+### 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:
+
+- Step 8 (Research Decision): Default to "Research first" in auto mode
+- Step 9 (Define Requirements): Generate from spec instead of interactive scoping:
+  - P0 requirements → this milestone (must have)
+  - P1 requirements → this milestone (should have)
+  - P2 requirements → Future
+  - Non-Goals → Out of Scope
+  - Requirements use standard [CATEGORY]-[NUMBER] REQ-ID format
+  - Requirements are user-centric and atomic (not verbatim spec text)
+  - Auto-approve (no user confirmation gate)
+- Step 10 (Create Roadmap): Spawn roadmapper as usual
+  - In auto mode: auto-approve roadmap without user confirmation
+- Step 10.5 (Overlap Check): Run as usual
+- Step 11 (Done): Show source spec in completion output
+
+## 2. Gather Milestone Goals
+
+**If MILESTONE-CONTEXT.md exists:**
+- Use features and scope from discuss-milestone
+- Present summary for confirmation
+
+**If no context file:**
+- Present what shipped in last milestone
+- Ask: "What do you want to build next?"
+- Use AskUserQuestion to explore features, priorities, constraints, scope
+
+## 3. Determine Milestone Version
+
+- Parse last version from MILESTONES.md
+- Suggest next version (v1.0 → v1.1, or v2.0 for major)
+- Confirm with user
+
+## 4. Update PROJECT.md
+
+Add/update:
+
+```markdown
+## Current Milestone: v[X.Y] [Name]
+
+**Goal:** [One sentence describing milestone focus]
+
+**Target features:**
+- [Feature 1]
+- [Feature 2]
+- [Feature 3]
+```
+
+Update Active requirements section and "Last updated" footer.
+
+## 5. Update STATE.md
+
+```markdown
+## Current Position
+
+Phase: Not started (defining requirements)
+Plan: —
+Status: Defining requirements
+Last activity: [today] — Milestone v[X.Y] started
+```
+
+Keep Accumulated Context section from previous milestone.
+
+## 6. Cleanup and Commit
+
+Delete MILESTONE-CONTEXT.md if exists (consumed).
+
+```bash
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "docs: start milestone v[X.Y] [Name]" --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`.
+
+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)
+```
+
+## 8. Research Decision
+
+AskUserQuestion: "Research the domain ecosystem for new features before defining requirements?"
+- "Research first (Recommended)" — Discover patterns, features, architecture for NEW capabilities
+- "Skip research" — Go straight to requirements
+
+**Persist choice to config** (so future `/dgs:plan-phase` honors it):
+
+```bash
+# If "Research first": persist true
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs config-set workflow.research true
+
+# If "Skip research": persist false
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs config-set workflow.research false
+```
+
+**If "Research first":**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ DGS ► RESEARCHING
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+◆ Spawning 4 researchers in parallel...
+  → Stack, Features, Architecture, Pitfalls
+```
+
+```bash
+mkdir -p ${project_root}/research
+```
+
+Spawn 4 parallel dgs-project-researcher agents. Each uses this template with dimension-specific fields:
+
+**Common structure for all 4 researchers:**
+```
+Task(prompt="
+<research_type>Project Research — {DIMENSION} for [new features].</research_type>
+
+<milestone_context>
+SUBSEQUENT MILESTONE — Adding [target features] to existing app.
+{EXISTING_CONTEXT}
+Focus ONLY on what's needed for the NEW features.
+</milestone_context>
+
+<question>{QUESTION}</question>
+
+<files_to_read>
+- ${project_path} (Project context)
+- ${project_root}/docs/product/ARCHITECTURE.md (Target architecture, if exists)
+- ${project_root}/docs/product/PRODUCT-SUMMARY.md (Product summary, if exists)
+</files_to_read>
+
+<downstream_consumer>{CONSUMER}</downstream_consumer>
+
+<quality_gate>{GATES}</quality_gate>
+
+<output>
+Write to: ${project_root}/research/{FILE}
+Use template: ~/.claude/deliver-great-systems/templates/research-project/{FILE}
+</output>
+", subagent_type="dgs-project-researcher", model="{researcher_model}", description="{DIMENSION} research")
+```
+
+**Dimension-specific fields:**
+
+| Field | Stack | Features | Architecture | Pitfalls |
+|-------|-------|----------|-------------|----------|
+| EXISTING_CONTEXT | Existing validated capabilities (DO NOT re-research): [from PROJECT.md] | Existing features (already built): [from PROJECT.md] | Existing architecture: [from PROJECT.md or codebase map] | Focus on common mistakes when ADDING these features to existing system |
+| QUESTION | What stack additions/changes are needed for [new features]? | How do [target features] typically work? Expected behavior? | How do [target features] integrate with existing architecture? | Common mistakes when adding [target features] to [domain]? |
+| CONSUMER | Specific libraries with versions for NEW capabilities, integration points, what NOT to add | Table stakes vs differentiators vs anti-features, complexity noted, dependencies on existing | Integration points, new components, data flow changes, suggested build order | Warning signs, prevention strategy, which phase should address it |
+| 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 |
+
+After all 4 complete, spawn synthesizer:
+
+```
+Task(prompt="
+Synthesize research outputs into SUMMARY.md.
+
+<files_to_read>
+- ${project_root}/research/STACK.md
+- ${project_root}/research/FEATURES.md
+- ${project_root}/research/ARCHITECTURE.md
+- ${project_root}/research/PITFALLS.md
+</files_to_read>
+
+Write to: ${project_root}/research/SUMMARY.md
+Use template: ~/.claude/deliver-great-systems/templates/research-project/SUMMARY.md
+Commit after writing.
+", subagent_type="dgs-research-synthesizer", model="{synthesizer_model}", description="Synthesize research")
+```
+
+Display key findings from SUMMARY.md:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ DGS ► RESEARCH COMPLETE ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Stack additions:** [from SUMMARY.md]
+**Feature table stakes:** [from SUMMARY.md]
+**Watch Out For:** [from SUMMARY.md]
+```
+
+**If "Skip research":** Continue to Step 9.
+
+## 9. Define Requirements
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ DGS ► DEFINING REQUIREMENTS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Read PROJECT.md: core value, current milestone goals, validated requirements (what exists).
+
+**If research exists:** Read FEATURES.md, extract feature categories.
+
+Present features by category:
+```
+## [Category 1]
+**Table stakes:** Feature A, Feature B
+**Differentiators:** Feature C, Feature D
+**Research notes:** [any relevant notes]
+```
+
+**If no research:** Gather requirements through conversation. Ask: "What are the main things users need to do with [new features]?" Clarify, probe for related capabilities, group into categories.
+
+**Scope each category** via AskUserQuestion (multiSelect: true, header max 12 chars):
+- "[Feature 1]" — [brief description]
+- "[Feature 2]" — [brief description]
+- "None for this milestone" — Defer entire category
+
+Track: Selected → this milestone. Unselected table stakes → future. Unselected differentiators → out of scope.
+
+**Identify gaps** via AskUserQuestion:
+- "No, research covered it" — Proceed
+- "Yes, let me add some" — Capture additions
+
+**Generate REQUIREMENTS.md:**
+- v1 Requirements grouped by category (checkboxes, REQ-IDs)
+- Future Requirements (deferred)
+- Out of Scope (explicit exclusions with reasoning)
+- Traceability section (empty, filled by roadmap)
+
+**REQ-ID format:** `[CATEGORY]-[NUMBER]` (AUTH-01, NOTIF-02). Continue numbering from existing.
+
+**Requirement quality criteria:**
+
+Good requirements are:
+- **Specific and testable:** "User can reset password via email link" (not "Handle password reset")
+- **User-centric:** "User can X" (not "System does Y")
+- **Atomic:** One capability per requirement (not "User can login and manage profile")
+- **Independent:** Minimal dependencies on other requirements
+
+Present FULL requirements list for confirmation:
+
+```
+## Milestone v[X.Y] Requirements
+
+### [Category 1]
+- [ ] **CAT1-01**: User can do X
+- [ ] **CAT1-02**: User can do Y
+
+### [Category 2]
+- [ ] **CAT2-01**: User can do Z
+
+Does this capture what you're building? (yes / adjust)
+```
+
+If "adjust": Return to scoping.
+
+**Commit requirements:**
+```bash
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "docs: define milestone v[X.Y] requirements" --files ${project_root}/REQUIREMENTS.md
+```
+
+## 10. Create Roadmap
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ DGS ► CREATING ROADMAP
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+◆ 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).
+
+```
+Task(prompt="
+<planning_context>
+<files_to_read>
+- ${project_path}
+- ${project_root}/REQUIREMENTS.md
+- ${project_root}/research/SUMMARY.md (if exists)
+- ${config_path}
+- ${project_root}/MILESTONES.md
+- ${project_root}/docs/product/ARCHITECTURE.md (Target architecture, if exists)
+- ${project_root}/docs/product/PRODUCT-SUMMARY.md (Product summary, if exists)
+</files_to_read>
+</planning_context>
+
+<instructions>
+Create roadmap for milestone v[X.Y]:
+1. Start phase numbering from [N]
+2. Derive phases from THIS MILESTONE's requirements only
+3. Map every requirement to exactly one phase
+4. Derive 2-5 success criteria per phase (observable user behaviors)
+5. Validate 100% coverage
+6. Write files immediately (ROADMAP.md, STATE.md, update REQUIREMENTS.md traceability)
+7. Return ROADMAP CREATED with summary
+
+Write files first, then return.
+</instructions>
+", subagent_type="dgs-roadmapper", model="{roadmapper_model}", description="Create roadmap")
+```
+
+**Handle return:**
+
+**If `## ROADMAP BLOCKED`:** Present blocker, work with user, re-spawn.
+
+**If `## ROADMAP CREATED`:** Read ROADMAP.md, present inline:
+
+```
+## Proposed Roadmap
+
+**[N] phases** | **[X] requirements mapped** | All covered ✓
+
+| # | Phase | Goal | Requirements | Success Criteria |
+|---|-------|------|--------------|------------------|
+| [N] | [Name] | [Goal] | [REQ-IDs] | [count] |
+
+### Phase Details
+
+**Phase [N]: [Name]**
+Goal: [goal]
+Requirements: [REQ-IDs]
+Success criteria:
+1. [criterion]
+2. [criterion]
+```
+
+**Ask for approval** via AskUserQuestion:
+- "Approve" — Commit and continue
+- "Adjust phases" — Tell me what to change
+- "Review full file" — Show raw ROADMAP.md
+
+**If "Adjust":** Get notes, re-spawn roadmapper with revision context, loop until approved.
+**If "Review":** Display raw ROADMAP.md, re-ask.
+
+**Commit roadmap** (after approval):
+```bash
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "docs: create milestone v[X.Y] roadmap ([N] phases)" --files ${roadmap_path} ${state_path} ${project_root}/REQUIREMENTS.md
+```
+
+## 10.5. Overlap Check (v2 only)
+
+If v2 install (PROJECTS.md or REPOS.md exists in the planning root):
+
+```bash
+OVERLAP=$(node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs overlap check --raw 2>/dev/null)
+```
+
+Parse JSON. If `overlapping_repos` array is non-empty, display warning:
+
+```
+⚠ Cross-project overlap detected:
+
+| Repo | Also touched by |
+|------|----------------|
+| {repo} | {other-project} |
+
+This is informational — work can proceed.
+```
+
+If no overlaps or not v2: skip silently.
+
+## 11. Done
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ DGS ► MILESTONE INITIALIZED ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Milestone v[X.Y]: [Name]**
+
+| Artifact       | Location                    |
+|----------------|-----------------------------|
+| Project        | `${project_path}`           |
+| Research       | `${project_root}/research/` |
+| Requirements   | `${project_root}/REQUIREMENTS.md` |
+| Roadmap        | `${roadmap_path}`           |
+
+**[N] phases** | **[X] requirements** | Ready to build ✓
+```
+
+**If spec-driven mode (auto):** Also display:
+
+```
+**Source:** `[spec path]` — [spec title]
+**Mode:** One milestone from one spec (auto-derived)
+```
+
+```
+## ▶ Next Up
+
+**Phase [N]: [Phase Name]** — [Goal]
+
+`/dgs:discuss-phase [N]` — gather context and clarify approach
+
+<sub>`/clear` first → fresh context window</sub>
+
+Also: `/dgs:plan-phase [N]` — skip discussion, plan directly
+```
+
+</process>
+
+<success_criteria>
+- [ ] PROJECT.md updated with Current Milestone section
+- [ ] STATE.md reset for new milestone
+- [ ] MILESTONE-CONTEXT.md consumed and deleted (if existed)
+- [ ] Research completed (if selected) — 4 parallel agents, milestone-aware
+- [ ] Requirements gathered and scoped per category
+- [ ] REQUIREMENTS.md created with REQ-IDs
+- [ ] dgs-roadmapper spawned with phase numbering context
+- [ ] Roadmap files written immediately (not draft)
+- [ ] User feedback incorporated (if any)
+- [ ] ROADMAP.md phases continue from previous milestone
+- [ ] All commits made (if planning docs committed)
+- [ ] User knows next step: `/dgs:discuss-phase [N]`
+- [ ] Auto mode: spec parsed and validated (status: final)
+- [ ] Auto mode: PROJECT.md includes Source Spec reference
+- [ ] Auto mode: requirements derived (not verbatim) from spec P0/P1/P2
+- [ ] Auto mode: repo cross-check completed (if v2)
+- [ ] Auto mode: one milestone per spec enforced
+- [ ] Auto mode: spec milestones field updated with link-milestone call
+
+**Atomic commits:** Each phase commits its artifacts immediately.
+</success_criteria>
+
+<output>
+
+**Standard mode artifacts:**
+- `${project_path}` — Updated Current Milestone section
+- `${state_path}` — Reset for new milestone
+- `${project_root}/REQUIREMENTS.md` — Scoped requirements with REQ-IDs
+- `${roadmap_path}` — Phased execution plan
+- `${project_root}/research/` — Research files (if research selected)
+
+**Auto mode (--auto <spec>) artifacts:**
+Same as standard mode, plus:
+- PROJECT.md includes `Source Spec` reference linking to the originating spec
+- Requirements derived from spec P0/P1/P2 priorities (not verbatim)
+- All interactive gates (research decision, requirements approval, roadmap approval) are auto-approved
+
+</output>