@ktpartners/dgs-platform 2.8.0 → 2.9.0

package/CHANGELOG.md

@@ -8,6 +8,20 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [2.9.0] - 2026-03-25
+
+### Changed
+- **new-project/new-milestone split** — `/dgs:new-project` now only handles questioning and PROJECT.md creation; all milestone-scoped work (research, requirements, roadmap, STATE.md) moves to `/dgs:new-milestone`, which now handles both first and subsequent milestones
+- **Codereview gate moved to orchestrator** — code review execution moved from `dgs-executor` (which lacks Task tool) to `execute-phase` orchestrator where Task spawning is available; skips in non-interactive/job mode with log message
+- **Map-codebase staleness gate** — in `--auto` mode (job runs), checks git history since last map; skips if no changes, narrows to single repo if only one changed; `--force` flag bypasses
+
+### Added
+- **Job file commit+push on status changes** — `run-job` now commits and pushes the job file after every step status update (in-progress, completed, failed, move operations), making job progress visible on remote in real time
+- **First-milestone guards in new-milestone** — handles missing MILESTONES.md/STATE.md gracefully with v1.0 default, phase-1 numbering, greenfield research framing, and STATE.md creation
+
+### Fixed
+- **Codereview silent failure in job mode** — codereview was silently skipped in job mode because the executor agent lacked Task/Agent tools needed to spawn the 9 review subagents
+
 ## [2.8.0] - 2026-03-25
 
 ### Changed

package/README.md

@@ -194,7 +194,7 @@ If you prefer not to use that flag, add this to your project's `.claude/settings
 
 DGS operates at the **product** level. A product contains one or more **projects**, each with its own milestones and phases. Ideas and specs live at the product level and feed into project or milestone creation.
 
-> **Already have code?** Run `/dgs:map-codebase` first. It spawns parallel agents per registered repo to analyze stack, architecture, structure, conventions, testing, integrations, and concerns. Per-repo maps are synthesized into unified top-level files. Then `/dgs:new-project` knows your codebase — questions focus on what you're adding, and planning automatically loads your patterns. Update a single repo after changes with `/dgs:map-codebase <repo-name>`.
+> **Already have code?** Run `/dgs:map-codebase` first. It spawns parallel agents per registered repo to analyze stack, architecture, structure, conventions, testing, integrations, and concerns. Per-repo maps are synthesized into unified top-level files. Then `/dgs:new-project` captures your project identity — goals, constraints, and scope. `/dgs:new-milestone` takes it from there with research, requirements, and roadmap. Update a single repo after changes with `/dgs:map-codebase <repo-name>`.
 
 ### 1. Set Up Product
 
@@ -236,18 +236,21 @@ If you have OpenAI or Gemini API keys configured, the spec goes through a **cros
 
 ```
 /dgs:new-project
+/dgs:new-milestone
 ```
 
-One command, one flow. The system:
+Two commands, one setup. First, `/dgs:new-project` asks questions until it understands your idea completely — goals, constraints, tech preferences, edge cases — then creates `PROJECT.md`.
+
+Then `/dgs:new-milestone` takes over:
 
-1. **Questions** — Asks until it understands your idea completely (goals, constraints, tech preferences, edge cases)
-2. **Research** — Spawns parallel agents to investigate the domain (optional but recommended)
-3. **Requirements** — Extracts what's v1, v2, and out of scope
-4. **Roadmap** — Creates phases mapped to requirements
+1. **Research** — Spawns parallel agents to investigate the domain (optional but recommended)
+2. **Requirements** — Extracts what's v1, v2, and out of scope
+3. **Roadmap** — Creates phases mapped to requirements
 
 You approve the roadmap. Now you're ready to build.
 
-**Creates:** `PROJECT.md`, `REQUIREMENTS.md`, `ROADMAP.md`, `STATE.md`, `.planning/research/`
+**`new-project` creates:** `PROJECT.md`
+**`new-milestone` creates:** `REQUIREMENTS.md`, `ROADMAP.md`, `STATE.md`, `research/`
 
 ---
 
@@ -393,7 +396,7 @@ When all phases are done, `/dgs:complete-milestone` archives the milestone and t
 
 **Automated alternative:** Instead of running each phase command manually, use `/dgs:create-milestone-job` to generate a build job and `/dgs:run-job` to execute the entire milestone pipeline automatically with subagent isolation per step. See the [User Guide](docs/USER-GUIDE.md#milestone-jobs) for details.
 
-Then `/dgs:new-milestone` starts the next version — same flow as `new-project` but for your existing codebase. You describe what you want to build next, the system researches the domain, you scope requirements, and it creates a fresh roadmap. Each milestone is a clean cycle: define → build → ship.
+Then `/dgs:new-milestone` starts the next cycle. This is the same command used after `new-project` — it handles research, requirements, and roadmap for each version. You describe what you want to build next, it researches the domain, you scope requirements, and it creates a fresh roadmap. Each milestone is a clean cycle: define → build → ship.
 
 ---
 
@@ -460,7 +463,7 @@ DGS handles it for you:
 | `REQUIREMENTS.md` | Scoped v1/v2 requirements with phase traceability |
 | `ROADMAP.md` | Where you're going, what's done |
 | `STATE.md` | Decisions, blockers, position — memory across sessions |
-| `docs/product/` | Product-level documents (architecture, summary) — loaded as context by write-spec, plan-phase, new-project, new-milestone |
+| `docs/product/` | Product-level documents (architecture, summary) — loaded as context by write-spec, plan-phase, new-milestone |
 | `codebase/` | Per-repo maps + unified synthesis from `/dgs:map-codebase` |
 | `research/` | Ecosystem knowledge (stack, features, architecture, pitfalls) |
 | `PLAN.md` | Atomic task with XML structure, verification steps |
@@ -554,7 +557,7 @@ See the [User Guide](docs/USER-GUIDE.md#context-tiers) for the complete command-
 
 | Command | What it does |
 |---------|--------------|
-| `/dgs:new-project [--auto]` | Full initialization: questions → research → requirements → roadmap |
+| `/dgs:new-project [--auto]` | Project identity: questioning → PROJECT.md |
 | `/dgs:discuss-phase [N] [--auto]` | Capture implementation decisions before planning |
 | `/dgs:plan-phase [N] [--auto]` | Research + plan + verify for a phase |
 | `/dgs:execute-phase <N>` | Execute all plans in parallel waves, verify when complete |
@@ -562,7 +565,7 @@ See the [User Guide](docs/USER-GUIDE.md#context-tiers) for the complete command-
 | `/dgs:audit-phase <phase> [--rerun-failed]` | Automated phase verification: test execution + structural inspection |
 | `/dgs:audit-milestone` | Verify milestone achieved its definition of done |
 | `/dgs:complete-milestone` | Archive milestone, tag release |
-| `/dgs:new-milestone [name]` | Start next version: questions → research → requirements → roadmap |
+| `/dgs:new-milestone [name]` | Start milestone: research → requirements → roadmap (first or subsequent) |
 
 ### Navigation
 
@@ -665,7 +668,7 @@ See the [User Guide](docs/USER-GUIDE.md#context-tiers) for the complete command-
 
 ## Configuration
 
-DGS stores product-level settings in `.planning/config.json`. This file is shared across all projects in the product. Configure during `/dgs:init-product` or `/dgs:new-project`, and update later with `/dgs:settings`. For the full config schema, workflow toggles, git branching options, and per-agent model breakdown, see the [User Guide](docs/USER-GUIDE.md#configuration-reference).
+DGS stores product-level settings in `.planning/config.json`. This file is shared across all projects in the product. Configure during `/dgs:init-product`, and update later with `/dgs:settings`. For the full config schema, workflow toggles, git branching options, and per-agent model breakdown, see the [User Guide](docs/USER-GUIDE.md#configuration-reference).
 
 ### Core Settings
 

package/deliver-great-systems/workflows/help.md

@@ -12,15 +12,17 @@ Display the complete DGS command reference. Output ONLY the reference content. D
 ## Quick Start
 
 **Single-project (v1):**
-1. `/dgs:new-project` - Initialize project (includes research, requirements, roadmap)
-2. `/dgs:plan-phase 1` - Create detailed plan for first phase
-3. `/dgs:execute-phase 1` - Execute the phase
+1. `/dgs:new-project` - Create project (questioning + PROJECT.md)
+2. `/dgs:new-milestone` - First milestone (research, requirements, roadmap)
+3. `/dgs:plan-phase 1` - Create detailed plan for first phase
+4. `/dgs:execute-phase 1` - Execute the phase
 
 **Multi-project / multi-repo (v2):**
 1. `/dgs:init-product` - Set up product folder and register repos
-2. `/dgs:new-project` - Create a project (prompts for name and repos)
-3. `/dgs:plan-phase 1` - Plan first phase (repos tracked per task)
-4. `/dgs:execute-phase 1` - Execute (commits per-repo automatically)
+2. `/dgs:new-project` - Create a project (questioning + PROJECT.md)
+3. `/dgs:new-milestone` - First milestone (research, requirements, roadmap)
+4. `/dgs:plan-phase 1` - Plan first phase (repos tracked per task)
+5. `/dgs:execute-phase 1` - Execute (commits per-repo automatically)
 
 ## Project Structure
 
@@ -54,7 +56,7 @@ Each command loads a specific tier of project context. Higher tiers include all
 ## Core Workflow
 
 ```
-/dgs:new-project → /dgs:plan-phase → /dgs:execute-phase → repeat
+/dgs:new-project → /dgs:new-milestone → /dgs:plan-phase → /dgs:execute-phase → repeat
 ```
 
 ### Product Setup (v2)
@@ -72,23 +74,19 @@ Usage: `/dgs:init-product`
 ### Project Initialization
 
 **`/dgs:new-project`**
-Initialize new project through unified flow. *(Tier 2: planning)*
+Initialize new project through deep questioning. *(Tier 2: planning)*
 
-One command takes you from idea to ready-for-planning:
+One command takes you from idea to project identity:
 - Deep questioning to understand what you're building
-- Optional domain research (spawns 4 parallel researcher agents)
-- Requirements definition with v1/v2/out-of-scope scoping
-- Roadmap creation with phase breakdown and success criteria
+- Optional brownfield mapping for existing codebases
+- PROJECT.md creation with vision, requirements hypotheses, and key decisions
 
 Creates project artifacts:
 - `PROJECT.md` — vision and requirements
-- `config.json` — workflow mode (interactive/yolo)
-- `research/` — domain research (if selected)
-- `REQUIREMENTS.md` — scoped requirements with REQ-IDs
-- `ROADMAP.md` — phases mapped to requirements
-- `STATE.md` — project memory
 
-**v2 additions:** Prompts for project name (used as folder slug), prompts for which repos this project touches (from REPOS.md), checks for overlap with other active projects. Artifacts are created under `projects/<project-slug>/`.
+**v2 additions:** Prompts for project name (used as folder slug), prompts for which repos this project touches (from REPOS.md). Artifacts are created under `projects/<project-slug>/`.
+
+After completion, run `/dgs:new-milestone` to start your first milestone.
 
 Usage: `/dgs:new-project`
 
@@ -186,7 +184,7 @@ Show which repos are touched by multiple active projects. *(Tier 1: lite)*
 
 - Scans plan files across all active projects for repo references
 - Highlights specific file-level overlaps
-- Runs automatically during `/dgs:new-project` and `/dgs:new-milestone`
+- Runs automatically during `/dgs:new-milestone`
 
 Usage: `/dgs:overlap-check`
 
@@ -307,14 +305,14 @@ Result: Phase 17 deleted, phases 18-20 become 17-19
 ### Milestone Management
 
 **`/dgs:new-milestone <name>`**
-Start a new milestone through unified flow. *(Tier 2: planning)*
+Start a new milestone (or the first milestone after `/dgs:new-project`). *(Tier 2: planning)*
 
-- Deep questioning to understand what you're building next
+- Gathers milestone goals (interactive or from spec via --auto)
 - Optional domain research (spawns 4 parallel researcher agents)
 - Requirements definition with scoping
 - Roadmap creation with phase breakdown
 
-Mirrors `/dgs:new-project` flow for brownfield projects (existing PROJECT.md).
+Handles both first milestones (creates STATE.md, defaults to v1.0) and subsequent milestones (continues from MILESTONES.md).
 
 Usage: `/dgs:new-milestone "v2.0 Features"`
 
@@ -408,7 +406,7 @@ Usage: `/dgs:check-todos api`
 
 ### Ideas & Specs
 
-`capture ideas → develop idea → write spec → new-project --auto`
+`capture ideas → develop idea → write spec → new-project --auto → new-milestone --auto`
 
 #### Ideas
 
@@ -812,7 +810,7 @@ my-product/                        # Product folder (git repo)
 
 ## Workflow Modes
 
-Set during `/dgs:new-project`:
+Set during `/dgs:init-product`:
 
 **Interactive Mode**
 
@@ -868,7 +866,9 @@ Example config:
 **Starting a new project (v1):**
 
 ```
-/dgs:new-project        # Unified flow: questioning -> research -> requirements -> roadmap
+/dgs:new-project        # Questioning -> PROJECT.md
+/clear
+/dgs:new-milestone      # Research -> requirements -> roadmap
 /clear
 /dgs:plan-phase 1       # Create plans for first phase
 /clear
@@ -879,7 +879,9 @@ Example config:
 
 ```
 /dgs:init-product       # One-time: register repos, create product structure
-/dgs:new-project        # Create project (picks name, selects repos)
+/dgs:new-project        # Questioning -> PROJECT.md
+/clear
+/dgs:new-milestone      # Research -> requirements -> roadmap
 /clear
 /dgs:plan-phase 1       # Plan with per-repo task tracking
 /clear
@@ -942,7 +944,9 @@ Example config:
 #   /dgs:research-idea              # Investigate feasibility
 /dgs:write-spec                     # Turn ideas into structured spec
 /clear
-/dgs:new-project --auto @spec.md    # Create project directly from spec
+/dgs:new-project --auto @spec.md    # Create project from spec
+/clear
+/dgs:new-milestone --auto <spec-id> # First milestone from spec
 ```
 
 **Debugging an issue:**

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="

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

@@ -1,5 +1,5 @@
 <purpose>
-Initialize a new project through unified flow: questioning, research (optional), requirements, roadmap. This is the most leveraged moment in any project — deep questioning here means better plans, better execution, better outcomes. One workflow takes you from idea to ready-for-planning.
+Initialize a new project through questioning and PROJECT.md creation. This is the most leveraged moment in any project — deep questioning here means better plans, better execution, better outcomes. Run /dgs:new-milestone after to start your first milestone.
 </purpose>
 
 <context_tier>planning</context_tier>
@@ -16,12 +16,9 @@ Check if `--auto` flag is present in $ARGUMENTS.
 **If auto mode:**
 - Skip brownfield mapping offer (assume greenfield)
 - Skip deep questioning (extract context from provided document)
-- Config: Use existing product config from init-product (Step 2a sets auto_advance only)
-- After config: run Steps 6-9 automatically with smart defaults:
-  - Research: Always yes
-  - Requirements: Include all table stakes + features from provided document
-  - Requirements approval: Auto-approve
-  - Roadmap approval: Auto-approve
+- Config: Use existing product config from init-product
+- After config: run Step 2b (parse spec), Step 2c (repo cross-check), write PROJECT.md
+- End with completion output directing to `/dgs:new-milestone --auto <spec-id>`
 
 **Document requirement:**
 Auto mode requires an idea document or spec reference — either:
@@ -64,7 +61,7 @@ If the `--auto` argument references a spec file path or spec ID:
 INIT=$(node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs init new-project)
 ```
 
-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`, `state_path`, `roadmap_path`, `requirements_path`, `research_dir`, `milestone_version`, `milestone_name`.
+Parse JSON for: `commit_docs`, `project_exists`, `has_codebase_map`, `planning_exists`, `has_existing_code`, `has_package_file`, `is_brownfield`, `needs_codebase_map`, `has_git`, `project_path`, `state_path`.
 
 Load planning-tier context files:
 
@@ -116,12 +113,6 @@ Exit command.
 
 **If auto mode:** Use existing product config (set during `/dgs:init-product`). No config questions needed here.
 
-**Persist auto-advance to config (survives context compaction):**
-
-```bash
-node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs config-set workflow.auto_advance true
-```
-
 Proceed to Step 4 (skip Step 3).
 
 ## 2b. Spec-Driven Project Creation (spec-driven auto mode only)
@@ -135,7 +126,7 @@ Read the spec file and extract:
 - **Problem** section → project description / core value
 - **Goals** section → project goals
 - **Non-Goals** section → out of scope
-- **Requirements** (P0/P1/P2) → v1 requirements (P0 + P1) and future requirements (P2)
+- **Requirements** (P0/P1/P2) → requirements hypotheses for PROJECT.md
 - **User Stories** → inform requirement specificity
 - **Technical Considerations** → inform research/architecture
 - **"Repos likely touched"** or similar section → repos for cross-checking (Step 2c)
@@ -190,27 +181,16 @@ Create `${project_path}` with standard template structure, but derived entirely
 - Do NOT copy verbatim — restructure for project planning context
 - Add a `Source spec: [path]` line to PROJECT.md (per user decision — reference, not copy)
 
-### Write REQUIREMENTS.md
-
-Generate `${requirements_path}` with:
-- REQ-IDs in `[CATEGORY]-[NUMBER]` format (e.g., AUTH-01, UI-02)
-- P0 requirements → v1 (must have)
-- P1 requirements → v1 (should have)
-- P2 requirements → Future
-- Non-Goals → Out of Scope with reasoning
-
-The requirements must be user-centric and atomic (one capability per requirement), following the quality criteria in the existing new-project workflow.
-
 ### Commit and Continue
 
-Commit PROJECT.md and REQUIREMENTS.md, then continue to Step 5 (Resolve Model Profile) — skip Steps 3 (Deep Questioning) and 4 (Write PROJECT.md) since they're replaced by spec-driven derivation.
+Commit PROJECT.md, then proceed to Done.
 
 **Branch name preview:** After the project folder is created, if `branching_strategy` is not `"none"`, show:
 ```
 Branch names will look like: dgs/{project-slug}/phase-03-auth
 ```
 
-After model profile resolution, proceed to Step 6, 7 (if research selected, auto-default yes), 8 (Create Roadmap), 8.5 (Overlap Check), 9 (Done).
+After PROJECT.md is committed, proceed to Step 5 (Done).
 
 ## 2c. Repo Cross-Check (spec-driven mode, v2 only)
 
@@ -422,595 +402,13 @@ Do not compress. Capture everything gathered.
 node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "docs: initialize project" --push --files ${project_path}
 ```
 
-## 5. Resolve Model Profile
-
-Use models from init: `researcher_model`, `synthesizer_model`, `roadmapper_model`.
-
-## 6. Research Decision
-
-**If auto mode:** Default to "Research first" without asking.
-
-Use AskUserQuestion:
-- header: "Research"
-- question: "Research the domain ecosystem before defining requirements?"
-- options:
-  - "Research first (Recommended)" — Discover standard stacks, expected features, architecture patterns
-  - "Skip research" — I know this domain well, go straight to requirements
-
-**If "Research first":**
-
-Display stage banner:
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- DGS ► RESEARCHING
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Researching [domain] ecosystem...
-```
-
-Create research directory:
-```bash
-mkdir -p ${research_dir}
-```
-
-**Determine milestone context:**
-
-Check if this is greenfield or subsequent milestone:
-- If no "Validated" requirements in PROJECT.md → Greenfield (building from scratch)
-- If "Validated" requirements exist → Subsequent milestone (adding to existing app)
-
-**Discover product-level documents:**
-
-Before spawning researchers, check for product-level documents that should inform research:
-
-```bash
-ls ${project_root}/docs/product/ 2>/dev/null
-```
-
-If the directory exists and contains files, store the list of file paths as `$product_doc_files`. For each file, format as a `<files_to_read>` entry: `- ${project_root}/docs/product/{filename} (Product doc)`. If the directory does not exist or is empty, set `$product_doc_files` to empty string.
-
-Display spawning indicator:
-```
-◆ Spawning 4 researchers in parallel...
-  → Stack research
-  → Features research
-  → Architecture research
-  → Pitfalls research
-```
-
-Spawn 4 parallel dgs-project-researcher agents with path references:
-
-```
-Task(prompt="First, read ~/.claude/agents/dgs-project-researcher.md for your role and instructions.
-
-<research_type>
-Project Research — Stack dimension for [domain].
-</research_type>
-
-<milestone_context>
-[greenfield OR subsequent]
-
-Greenfield: Research the standard stack for building [domain] from scratch.
-Subsequent: Research what's needed to add [target features] to an existing [domain] app. Don't re-research the existing system.
-</milestone_context>
-
-<question>
-What's the standard 2025 stack for [domain]?
-</question>
-
-<files_to_read>
-- {project_path} (Project context and goals)
-${product_doc_files}
-</files_to_read>
-
-<downstream_consumer>
-Your STACK.md feeds into roadmap creation. Be prescriptive:
-- Specific libraries with versions
-- Clear rationale for each choice
-- What NOT to use and why
-</downstream_consumer>
-
-<quality_gate>
-- [ ] Versions are current (verify with Context7/official docs, not training data)
-- [ ] Rationale explains WHY, not just WHAT
-- [ ] Confidence levels assigned to each recommendation
-</quality_gate>
-
-<output>
-Write to: ${research_dir}/STACK.md
-Use template: ~/.claude/deliver-great-systems/templates/research-project/STACK.md
-</output>
-", subagent_type="general-purpose", model="{researcher_model}", description="Stack research")
-
-Task(prompt="First, read ~/.claude/agents/dgs-project-researcher.md for your role and instructions.
-
-<research_type>
-Project Research — Features dimension for [domain].
-</research_type>
-
-<milestone_context>
-[greenfield OR subsequent]
-
-Greenfield: What features do [domain] products have? What's table stakes vs differentiating?
-Subsequent: How do [target features] typically work? What's expected behavior?
-</milestone_context>
-
-<question>
-What features do [domain] products have? What's table stakes vs differentiating?
-</question>
-
-<files_to_read>
-- {project_path} (Project context)
-${product_doc_files}
-</files_to_read>
-
-<downstream_consumer>
-Your FEATURES.md feeds into requirements definition. Categorize clearly:
-- Table stakes (must have or users leave)
-- Differentiators (competitive advantage)
-- Anti-features (things to deliberately NOT build)
-</downstream_consumer>
-
-<quality_gate>
-- [ ] Categories are clear (table stakes vs differentiators vs anti-features)
-- [ ] Complexity noted for each feature
-- [ ] Dependencies between features identified
-</quality_gate>
-
-<output>
-Write to: ${research_dir}/FEATURES.md
-Use template: ~/.claude/deliver-great-systems/templates/research-project/FEATURES.md
-</output>
-", subagent_type="general-purpose", model="{researcher_model}", description="Features research")
-
-Task(prompt="First, read ~/.claude/agents/dgs-project-researcher.md for your role and instructions.
-
-<research_type>
-Project Research — Architecture dimension for [domain].
-</research_type>
-
-<milestone_context>
-[greenfield OR subsequent]
-
-Greenfield: How are [domain] systems typically structured? What are major components?
-Subsequent: How do [target features] integrate with existing [domain] architecture?
-</milestone_context>
-
-<question>
-How are [domain] systems typically structured? What are major components?
-</question>
-
-<files_to_read>
-- {project_path} (Project context)
-${product_doc_files}
-</files_to_read>
-
-<downstream_consumer>
-Your ARCHITECTURE.md informs phase structure in roadmap. Include:
-- Component boundaries (what talks to what)
-- Data flow (how information moves)
-- Suggested build order (dependencies between components)
-</downstream_consumer>
-
-<quality_gate>
-- [ ] Components clearly defined with boundaries
-- [ ] Data flow direction explicit
-- [ ] Build order implications noted
-</quality_gate>
-
-<output>
-Write to: ${research_dir}/ARCHITECTURE.md
-Use template: ~/.claude/deliver-great-systems/templates/research-project/ARCHITECTURE.md
-</output>
-", subagent_type="general-purpose", model="{researcher_model}", description="Architecture research")
-
-Task(prompt="First, read ~/.claude/agents/dgs-project-researcher.md for your role and instructions.
-
-<research_type>
-Project Research — Pitfalls dimension for [domain].
-</research_type>
-
-<milestone_context>
-[greenfield OR subsequent]
-
-Greenfield: What do [domain] projects commonly get wrong? Critical mistakes?
-Subsequent: What are common mistakes when adding [target features] to [domain]?
-</milestone_context>
-
-<question>
-What do [domain] projects commonly get wrong? Critical mistakes?
-</question>
-
-<files_to_read>
-- {project_path} (Project context)
-${product_doc_files}
-</files_to_read>
-
-<downstream_consumer>
-Your PITFALLS.md prevents mistakes in roadmap/planning. For each pitfall:
-- Warning signs (how to detect early)
-- Prevention strategy (how to avoid)
-- Which phase should address it
-</downstream_consumer>
-
-<quality_gate>
-- [ ] Pitfalls are specific to this domain (not generic advice)
-- [ ] Prevention strategies are actionable
-- [ ] Phase mapping included where relevant
-</quality_gate>
-
-<output>
-Write to: ${research_dir}/PITFALLS.md
-Use template: ~/.claude/deliver-great-systems/templates/research-project/PITFALLS.md
-</output>
-", subagent_type="general-purpose", model="{researcher_model}", description="Pitfalls research")
-```
-
-After all 4 agents complete, spawn synthesizer to create SUMMARY.md:
-
-```
-Task(prompt="
-<task>
-Synthesize research outputs into SUMMARY.md.
-</task>
-
-<files_to_read>
-- ${research_dir}/STACK.md
-- ${research_dir}/FEATURES.md
-- ${research_dir}/ARCHITECTURE.md
-- ${research_dir}/PITFALLS.md
-</files_to_read>
-
-<output>
-Write to: ${research_dir}/SUMMARY.md
-Use template: ~/.claude/deliver-great-systems/templates/research-project/SUMMARY.md
-Commit after writing.
-</output>
-", subagent_type="dgs-research-synthesizer", model="{synthesizer_model}", description="Synthesize research")
-```
-
-Display research complete banner and key findings:
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- DGS ► RESEARCH COMPLETE ✓
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-## Key Findings
-
-**Stack:** [from SUMMARY.md]
-**Table Stakes:** [from SUMMARY.md]
-**Watch Out For:** [from SUMMARY.md]
-
-Files: `${research_dir}/`
-```
-
-**If "Skip research":** Continue to Step 7.
-
-## 7. Define Requirements
-
-Display stage banner:
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- DGS ► DEFINING REQUIREMENTS
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
-**Load context:**
-
-Read PROJECT.md and extract:
-- Core value (the ONE thing that must work)
-- Stated constraints (budget, timeline, tech limitations)
-- Any explicit scope boundaries
-
-**If research exists:** Read research/FEATURES.md and extract feature categories.
-
-**If auto mode:**
-- Auto-include all table stakes features (users expect these)
-- Include features explicitly mentioned in provided document
-- Auto-defer differentiators not mentioned in document
-- Skip per-category AskUserQuestion loops
-- Skip "Any additions?" question
-- Skip requirements approval gate
-- Generate REQUIREMENTS.md and commit directly
-
-**Present features by category (interactive mode only):**
-
-```
-Here are the features for [domain]:
-
-## Authentication
-**Table stakes:**
-- Sign up with email/password
-- Email verification
-- Password reset
-- Session management
-
-**Differentiators:**
-- Magic link login
-- OAuth (Google, GitHub)
-- 2FA
-
-**Research notes:** [any relevant notes]
-
----
-
-## [Next Category]
-...
-```
-
-**If no research:** Gather requirements through conversation instead.
-
-Ask: "What are the main things users need to be able to do?"
-
-For each capability mentioned:
-- Ask clarifying questions to make it specific
-- Probe for related capabilities
-- Group into categories
-
-**Scope each category:**
-
-For each category, use AskUserQuestion:
-
-- header: "[Category]" (max 12 chars)
-- question: "Which [category] features are in v1?"
-- multiSelect: true
-- options:
-  - "[Feature 1]" — [brief description]
-  - "[Feature 2]" — [brief description]
-  - "[Feature 3]" — [brief description]
-  - "None for v1" — Defer entire category
-
-Track responses:
-- Selected features → v1 requirements
-- Unselected table stakes → v2 (users expect these)
-- Unselected differentiators → out of scope
-
-**Identify gaps:**
-
-Use AskUserQuestion:
-- header: "Additions"
-- question: "Any requirements research missed? (Features specific to your vision)"
-- options:
-  - "No, research covered it" — Proceed
-  - "Yes, let me add some" — Capture additions
-
-**Validate core value:**
-
-Cross-check requirements against Core Value from PROJECT.md. If gaps detected, surface them.
-
-**Generate REQUIREMENTS.md:**
-
-Create `${requirements_path}` with:
-- v1 Requirements grouped by category (checkboxes, REQ-IDs)
-- v2 Requirements (deferred)
-- Out of Scope (explicit exclusions with reasoning)
-- Traceability section (empty, filled by roadmap)
-
-**REQ-ID format:** `[CATEGORY]-[NUMBER]` (AUTH-01, CONTENT-02)
-
-**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
-
-Reject vague requirements. Push for specificity:
-- "Handle authentication" → "User can log in with email/password and stay logged in across sessions"
-- "Support sharing" → "User can share post via link that opens in recipient's browser"
-
-**Present full requirements list (interactive mode only):**
-
-Show every requirement (not counts) for user confirmation:
-
-```
-## v1 Requirements
-
-### Authentication
-- [ ] **AUTH-01**: User can create account with email/password
-- [ ] **AUTH-02**: User can log in and stay logged in across sessions
-- [ ] **AUTH-03**: User can log out from any page
-
-### Content
-- [ ] **CONT-01**: User can create posts with text
-- [ ] **CONT-02**: User can edit their own posts
-
-[... full list ...]
-
----
-
-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 v1 requirements" --push --files ${requirements_path}
-```
-
-## 8. Create Roadmap
-
-Display stage banner:
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- DGS ► CREATING ROADMAP
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-◆ Spawning roadmapper...
-```
-
-Spawn dgs-roadmapper agent with path references:
-
-```
-Task(prompt="
-<planning_context>
-
-<files_to_read>
-- ${project_path} (Project context)
-- ${requirements_path} (v1 Requirements)
-- ${research_dir}/SUMMARY.md (Research findings - if exists)
-- ${config_path} (Depth and mode settings)
-${product_doc_files}
-</files_to_read>
-
-<milestone>
-version: ${milestone_version}
-name: ${milestone_name}
-</milestone>
-
-</planning_context>
-
-<instructions>
-Create roadmap:
-1. Derive phases from requirements (don't impose structure)
-2. Map every v1 requirement to exactly one phase
-3. Derive 2-5 success criteria per phase (observable user behaviors)
-Use the milestone version from <milestone> when writing STATE.md frontmatter and ROADMAP.md headings.
-4. Validate 100% coverage
-5. Write files immediately (ROADMAP.md, STATE.md, update REQUIREMENTS.md traceability)
-6. Return ROADMAP CREATED with summary
-
-Write files first, then return. This ensures artifacts persist even if context is lost.
-</instructions>
-", subagent_type="dgs-roadmapper", model="{roadmapper_model}", description="Create roadmap")
-```
-
-**Handle roadmapper return:**
-
-**If `## ROADMAP BLOCKED`:**
-- Present blocker information
-- Work with user to resolve
-- Re-spawn when resolved
-
-**If `## ROADMAP CREATED`:**
-
-Read the created ROADMAP.md and present it nicely inline:
-
-```
----
-
-## Proposed Roadmap
-
-**[N] phases** | **[X] requirements mapped** | All v1 requirements covered ✓
-
-| # | Phase | Goal | Requirements | Success Criteria |
-|---|-------|------|--------------|------------------|
-| 1 | [Name] | [Goal] | [REQ-IDs] | [count] |
-| 2 | [Name] | [Goal] | [REQ-IDs] | [count] |
-| 3 | [Name] | [Goal] | [REQ-IDs] | [count] |
-...
-
-### Phase Details
-
-**Phase 1: [Name]**
-Goal: [goal]
-Requirements: [REQ-IDs]
-Success criteria:
-1. [criterion]
-2. [criterion]
-3. [criterion]
-
-**Phase 2: [Name]**
-Goal: [goal]
-Requirements: [REQ-IDs]
-Success criteria:
-1. [criterion]
-2. [criterion]
-
-[... continue for all phases ...]
-
----
-```
-
-**If auto mode:** Skip approval gate — auto-approve and commit directly.
-
-**CRITICAL: Ask for approval before committing (interactive mode only):**
-
-Use AskUserQuestion:
-- header: "Roadmap"
-- question: "Does this roadmap structure work for you?"
-- options:
-  - "Approve" — Commit and continue
-  - "Adjust phases" — Tell me what to change
-  - "Review full file" — Show raw ROADMAP.md
-
-**If "Approve":** Continue to commit.
-
-**If "Adjust phases":**
-- Get user's adjustment notes
-- Re-spawn roadmapper with revision context:
-  ```
-  Task(prompt="
-  <revision>
-  User feedback on roadmap:
-  [user's notes]
-
-  <files_to_read>
-  - ${roadmap_path} (Current roadmap to revise)
-  </files_to_read>
-
-  Update the roadmap based on feedback. Edit files in place.
-  Return ROADMAP REVISED with changes made.
-  </revision>
-  ", subagent_type="dgs-roadmapper", model="{roadmapper_model}", description="Revise roadmap")
-  ```
-- Present revised roadmap
-- Loop until user approves
-
-**If "Review full file":** Display raw `cat ${roadmap_path}`, then re-ask.
-
-**Commit roadmap (after approval or auto mode):**
-
-```bash
-node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "docs: create roadmap ([N] phases)" --push --files ${roadmap_path} ${state_path} ${requirements_path}
-```
-
-### Link Spec to Milestone (spec-driven mode only)
-
-If this project was created from a spec (spec-driven auto mode), 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 "v1.0"
-```
-
-Include the updated spec file in a commit:
-
-```bash
-node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "specs: link $SPEC_ID to v1.0" --push --files $SPEC_PATH
-```
-
-## 8.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.
-
-## 9. Done
+## 5. Done
 
 Present completion summary:
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- DGS ► PROJECT INITIALIZED ✓
+ DGS ► PROJECT CREATED ✓
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 **[Project Name]**
@@ -1018,60 +416,24 @@ Present completion summary:
 | Artifact       | Location                    |
 |----------------|-----------------------------|
 | Project        | `${project_path}`           |
-| Config         | `${config_path}`            |
-| Research       | `${research_dir}/`          |
-| Requirements   | `${requirements_path}`      |
-| Roadmap        | `${roadmap_path}`           |
 
-**[N] phases** | **[X] requirements** | Ready to build ✓
-```
+## Next Up
 
-**If spec-driven mode**, add to the summary table:
+**Start your first milestone:**
 
-```
-**Source:** `[spec path]`
-**Created from spec:** {spec_id} — "{spec_title}"
-```
+`/dgs:new-milestone`
 
-**If auto mode (spec-driven):**
-
-```
-**Created from spec:** {spec_id} — "{spec_title}"
-
-╔══════════════════════════════════════════╗
-║  AUTO-ADVANCING → DISCUSS PHASE 1        ║
-╚══════════════════════════════════════════╝
-```
-
-**If auto mode (idea-driven):**
-
-```
-╔══════════════════════════════════════════╗
-║  AUTO-ADVANCING → DISCUSS PHASE 1        ║
-╚══════════════════════════════════════════╝
+<sub>`/clear` first - fresh context window</sub>
 ```
 
-Exit skill and invoke SlashCommand("/dgs:discuss-phase 1 --auto")
-
-**If interactive mode:**
+**If spec-driven mode**, add:
 
 ```
-───────────────────────────────────────────────────────────────
-
-## ▶ Next Up
-
-**Phase 1: [Phase Name]** — [Goal from ROADMAP.md]
-
-/dgs:discuss-phase 1 — gather context and clarify approach
-
-<sub>/clear first → fresh context window</sub>
-
----
+**Created from spec:** {spec_id} -- "{spec_title}"
 
-**Also available:**
-- /dgs:plan-phase 1 — skip discussion, plan directly
+**Start first milestone from this spec:**
 
-───────────────────────────────────────────────────────────────
+`/dgs:new-milestone --auto <spec-id>`
 ```
 
 </process>
@@ -1079,16 +441,7 @@ Exit skill and invoke SlashCommand("/dgs:discuss-phase 1 --auto")
 <output>
 
 - `${project_path}`
-- `${config_path}`
-- `${research_dir}/` (if research selected)
-  - `STACK.md`
-  - `FEATURES.md`
-  - `ARCHITECTURE.md`
-  - `PITFALLS.md`
-  - `SUMMARY.md`
-- `${requirements_path}`
-- `${roadmap_path}`
-- `${state_path}`
+- `${config_path}` (from init-product, not created here)
 
 </output>
 
@@ -1098,20 +451,9 @@ Exit skill and invoke SlashCommand("/dgs:discuss-phase 1 --auto")
 - [ ] Git repo initialized
 - [ ] Brownfield detection completed
 - [ ] Deep questioning completed (threads followed, not rushed)
-- [ ] PROJECT.md captures full context → **committed**
-- [ ] Product config validated (mode, depth, workflow settings from init-product)
-- [ ] Research completed (if selected) — 4 parallel agents spawned → **committed**
-- [ ] Requirements gathered (from research or conversation)
-- [ ] User scoped each category (v1/v2/out of scope)
-- [ ] REQUIREMENTS.md created with REQ-IDs → **committed**
-- [ ] dgs-roadmapper spawned with context
-- [ ] Roadmap files written immediately (not draft)
-- [ ] User feedback incorporated (if any)
-- [ ] ROADMAP.md created with phases, requirement mappings, success criteria
-- [ ] STATE.md initialized
-- [ ] REQUIREMENTS.md traceability updated
-- [ ] Spec-driven mode: spec milestones field updated with link-milestone call
-- [ ] User knows next step is `/dgs:discuss-phase 1`
+- [ ] PROJECT.md captures full context -- **committed**
+- [ ] Product config validated
+- [ ] User knows next step is `/dgs:new-milestone`
 
 **Atomic commits:** Each phase commits its artifacts immediately. If context is lost, artifacts persist.
 

package/package.json

@@ -8,7 +8,7 @@
   "bugs": {
     "url": "https://github.com/KT-Partners-Ltd/dgs-platform-docs/issues"
   },
-  "version": "2.8.0",
+  "version": "2.9.0",
   "description": "Deliver Great Systems Platform — A meta-prompting, context engineering and spec-driven development system for Claude Code and Gemini by KT Partners.",
   "bin": {
     "dgs": "bin/install.js"