@ktpartners/dgs-platform 2.8.0 → 3.0.4

package/deliver-great-systems/workflows/create-milestone-job.md

@@ -24,7 +24,7 @@ Use `TIER_FILES` JSON `files` array for project context (PROJECT.md, STATE.md, c
 Parse `$ARGUMENTS` to extract version and flags.
 
 - **Version:** First non-flag argument (e.g., `v6`, `v6.0`). If omitted, auto-detection happens in the preview step.
-- **--no-check flag:** If present, omit audit-milestone and complete-milestone steps from the generated job.
+- **--no-check flag:** If present, omit the audit-milestone step from the generated job.
 
 ```bash
 # Pseudocode for argument parsing:
@@ -97,7 +97,7 @@ Present in this format:
 5. execute-phase 52
 6. verify-work 52
 ...
-N. complete-milestone v6.0
+N. audit-milestone v6.0
 
 Create this job? (yes/no)
 ```
@@ -123,13 +123,13 @@ node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs jobs create-milestone VER
 2. Commit the job file:
 
 ```bash
-node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "docs(50): create milestone job {version}" --files jobs/pending/milestone-{version}.md
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "docs(50): create milestone job {version}" --files jobs/milestone-{version}.md
 ```
 
 3. Display success and next steps:
 
 ```
-Job created: jobs/pending/milestone-{version}.md
+Job created: jobs/milestone-{version}.md
 
 ---
 

package/deliver-great-systems/workflows/develop-idea.md

@@ -89,7 +89,7 @@ Also check for prior research document:
 ```bash
 # Derive slug from filename (strip id prefix and .md suffix)
 SLUG=$(echo "${filename}" | sed 's/^[0-9]*-//' | sed 's/\.md$//')
-RESEARCH_DOC="${project_root}/docs/ideas/pending/${SLUG}-research.md"
+RESEARCH_DOC="${project_root}/docs/ideas/${SLUG}-research.md"
 ```
 If the research document file exists, read it for prior research context.
 
@@ -281,7 +281,7 @@ Per CONTEXT.md: idea body is NOT updated on partial save.
 <step name="discussion_commit">
 Commit the updated idea file immediately after discussion:
 ```bash
-node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "docs: discuss idea #${id} — ${title}" --files ${project_root}/ideas/${state}/${filename}
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "docs: discuss idea #${id} — ${title}" --files ${project_root}/ideas/${filename}
 ```
 
 **If `partial = true`** (user exited mid-discussion):
@@ -392,10 +392,10 @@ Create (or overwrite) the research document.
 
 Ensure directory exists:
 ```bash
-mkdir -p ${project_root}/docs/ideas/pending
+mkdir -p ${project_root}/docs/ideas
 ```
 
-Write the research document to `${project_root}/docs/ideas/pending/${SLUG}-research.md` using the Write tool.
+Write the research document to `${project_root}/docs/ideas/${SLUG}-research.md` using the Write tool.
 
 Document structure:
 ```markdown
@@ -456,7 +456,7 @@ Build the entry JSON:
   "summary": "{Actionable summary paragraph}",
   "keyFindings": "- {finding 1}\n- {finding 2}\n- {finding 3}",
   "recommendation": "{Strong recommendation or neutral options presentation}",
-  "documentLink": "${project_root}/docs/ideas/pending/${SLUG}-research.md",
+  "documentLink": "${project_root}/docs/ideas/${SLUG}-research.md",
   "outcome": "{Recommended next step: 'Ready for spec', 'Needs more discussion', 'Not feasible', etc.}"
 }
 ```
@@ -472,7 +472,7 @@ Parse the JSON result to confirm success.
 <step name="research_commit">
 Commit both the research document and the updated idea file:
 ```bash
-node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "docs: research idea #${id} -- ${title}" --files ${project_root}/docs/ideas/pending/${SLUG}-research.md ${project_root}/ideas/${state}/${filename}
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "docs: research idea #${id} -- ${title}" --files ${project_root}/docs/ideas/${SLUG}-research.md ${project_root}/ideas/${filename}
 ```
 </step>
 
@@ -490,8 +490,8 @@ Research: ${recommendation}
 Next step: ${contextAwareNextStep}
 
 Files:
-- ${project_root}/ideas/${state}/${filename}
-- ${project_root}/docs/ideas/pending/${SLUG}-research.md
+- ${project_root}/ideas/${filename}
+- ${project_root}/docs/ideas/${SLUG}-research.md
 ```
 
 **If only discussion ran** (research skipped by decision routing, user choice, or partial exit):
@@ -503,7 +503,7 @@ Decision: ${decision}
 Next step: ${contextAwareNextStep}
 
 Files:
-- ${project_root}/ideas/${state}/${filename}
+- ${project_root}/ideas/${filename}
 ```
 
 **If only research ran** (user chose "Just research" in assess_history):
@@ -516,8 +516,8 @@ Research: ${recommendation}
 Next step: ${contextAwareNextStep}
 
 Files:
-- ${project_root}/ideas/${state}/${filename}
-- ${project_root}/docs/ideas/pending/${SLUG}-research.md
+- ${project_root}/ideas/${filename}
+- ${project_root}/docs/ideas/${SLUG}-research.md
 ```
 
 **Context-aware next step logic:**

package/deliver-great-systems/workflows/diagnose-issues.md

@@ -33,6 +33,20 @@ TIER_FILES=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" contex
 ```
 
 Store the file list for passing to debug sub-agents in `<files_to_read>` blocks.
+
+**Worktree-aware code directory resolution (resolveCodeContext):**
+
+For each registered code repo, resolve the correct working directory. When a milestone or quick worktree is active, debug investigation must target the worktree directory, not the main checkout, so the debugger examines the correct code and can reproduce issues in the right context.
+
+```javascript
+// In the agent's execution context, use resolveCodeContext to determine the code directory:
+const { resolveCodeContext } = require('./bin/lib/context.cjs');
+const ctx = resolveCodeContext(planningRoot, repoName);
+// ctx.type: 'main' | 'milestone' | 'quick'
+// ctx.directory: absolute path to the correct working directory
+```
+
+Pass `ctx.directory` to debug sub-agents so they investigate code in the correct location.
 </step>
 
 <step name="parse_gaps">

package/deliver-great-systems/workflows/discuss-idea.md

@@ -86,7 +86,7 @@ IDEA_DOCS_DIR="${IDEA_DIR}/docs"
 If a flat structure is used (ideas stored as files, not directories), derive from the filename:
 ```bash
 IDEA_SLUG=$(echo "${filename}" | sed 's/^[0-9]*-//' | sed 's/\.md$//')
-IDEA_DOCS_DIR="$(dirname "$(dirname "${path}")")/docs/ideas/pending/${IDEA_SLUG}"
+IDEA_DOCS_DIR="$(dirname "$(dirname "${path}")")/docs/ideas/${IDEA_SLUG}"
 ```
 
 Check both paths. Use whichever exists.

package/deliver-great-systems/workflows/execute-phase.md

@@ -9,7 +9,7 @@ Orchestrator coordinates, not executes. Each subagent loads the full execute-pla
 </core_principle>
 
 <hard_boundary>
-**CRITICAL SCOPE CONSTRAINT:** You execute ONLY the single phase specified in $ARGUMENTS. After that phase completes (plans executed, verification done, roadmap updated), you MUST STOP. Do NOT read the roadmap to discover subsequent phases. Do NOT execute transition.md unless `--auto` flag is present. Do NOT advance to phase N+1. Violating this boundary causes duplicate work and corrupts job state.
+**CRITICAL SCOPE CONSTRAINT:** You execute ONLY the single phase specified in $ARGUMENTS. After that phase finishes (plans executed, verification done, roadmap updated), you MUST STOP. Do NOT read the roadmap to discover subsequent phases. Do NOT execute transition.md unless `--auto` flag is present. Do NOT advance to phase N+1. Violating this boundary causes duplicate work and corrupts job state.
 </hard_boundary>
 
 <required_reading>
@@ -27,7 +27,7 @@ INIT=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" init execute
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 ```
 
-Parse JSON for: `executor_model`, `verifier_model`, `commit_docs`, `parallelization`, `branching_strategy`, `branch_name`, `base_branch`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `plans`, `incomplete_plans`, `plan_count`, `incomplete_count`, `state_exists`, `roadmap_exists`, `author`, `phase_req_ids`, `sync_push`, `sync_pull`, `cadence_push`, `cadence_pull`.
+Parse JSON for: `executor_model`, `verifier_model`, `commit_docs`, `parallelization`, `branching_strategy`, `branch_name`, `base_branch`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `plans`, `incomplete_plans`, `plan_count`, `incomplete_count`, `state_exists`, `roadmap_exists`, `author`, `phase_req_ids`, `sync_push`, `sync_pull`, `cadence_push`, `cadence_pull`, `milestone_slug`, `milestone_version`, `milestone_name`.
 
 **Load execution tier context:**
 
@@ -119,34 +119,122 @@ node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" sync workflow-pull
   - If No: skip pull, continue
 </step>
 
-<step name="handle_branching">
-Check `branching_strategy` from init:
+<step name="handle_worktree">
+Check if this phase is part of a milestone with code repos registered in REPOS.md.
 
-**"none":** Skip, continue on current branch.
+**If no REPOS.md or no code repos:** Skip worktree creation entirely. Log: `No code repos registered — skipping worktree setup.` Continue to validate_phase.
+
+**If REPOS.md has code repos and `milestone_slug` is present:**
+
+Use `milestone_slug` from init JSON (already sanitized).
+
+**1. Check for existing worktree:**
 
-**"phase" or "milestone":** Use pre-computed `branch_name` from init for the product folder:
 ```bash
-git checkout -b "$BRANCH_NAME" 2>/dev/null || git checkout "$BRANCH_NAME"
+WORKTREE_LIST=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" worktrees list 2>/dev/null)
 ```
 
-All subsequent commits go to this branch. User handles merging.
+Parse the JSON array. Look for an entry matching `milestone_slug`.
 
-**Code repo branching (base_branch):**
+**If worktree exists with `setup_complete: true` for all repos:**
+```
+Using existing milestone worktree for ${MILESTONE_SLUG}
+```
+Skip to step 3 (set active_context).
 
-The product folder's own branch is always created from the current HEAD (typically `main`). The `base_branch` from init JSON applies only to code repos registered in REPOS.md.
+**If worktree exists but `setup_complete: false` for any repo:**
+```
+╔══════════════════════════════════════════════════════════════╗
+║  ERROR                                                       ║
+╚══════════════════════════════════════════════════════════════╝
 
-When branching is enabled and REPOS.md lists code repos, `createRepoBranches` (via `dgs-tools.cjs`) uses `base_branch` to:
-1. Pre-check all code repos upfront — verify the base branch exists in every registered repo before creating any branches
-2. Fetch the base branch from remote in each repo (`git fetch origin "$BASE_BRANCH"`)
-3. Create feature branches from the base branch (`git checkout "$BASE_BRANCH" && git checkout -b "$BRANCH_NAME"`)
+Worktree setup incomplete for milestone '${MILESTONE_SLUG}'.
+Repo(s) with failed setup need manual intervention.
 
-If the base branch does not exist in any code repo, the operation fails with a clear error before any branches are created:
+**To fix:** dgs-tools worktrees setup ${MILESTONE_SLUG}
+Then re-run: /dgs:execute-phase ${PHASE}
 ```
-Error: Base branch '{base_branch}' does not exist in repo '{repo_name}'.
-Create the branch or update git.base_branch in config.
+**STOP.** Do not proceed with phase execution.
+
+**If no worktree exists:**
+
+**2. Create milestone worktree:**
+
+```bash
+CREATE_RESULT=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" worktrees create "${MILESTONE_SLUG}" --type milestone)
 ```
 
-The `base_branch` value is passed from init JSON to `createRepoBranches` automatically — the two-pass validation (verify all repos, then create all branches) is handled by the library function (see Plan 01, Task 3).
+Parse JSON output. Check each repo:
+- If all repos have `setup_complete: true` (or no setup command): continue.
+- If any repo has `setup_complete: false`:
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  ERROR                                                       ║
+╚══════════════════════════════════════════════════════════════╝
+
+Setup failed for one or more repos during worktree creation.
+Phase cannot start until setup succeeds.
+
+**To fix:** dgs-tools worktrees setup ${MILESTONE_SLUG}
+Then re-run: /dgs:execute-phase ${PHASE}
+```
+**STOP.** Do not proceed.
+
+Note: The worktree directory and branch are kept (not removed) so the user can fix and re-run setup.
+
+**3. Set active_context and capture worktree repos:**
+
+```bash
+node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" config-local-set execution.active_context "${MILESTONE_SLUG}"
+```
+
+Read the worktree repos map from config.local.json so it can be passed to executor agents:
+
+```bash
+WORKTREE_REPOS=$(node -e "
+  const fs = require('fs');
+  const cfg = JSON.parse(fs.readFileSync('config.local.json', 'utf-8'));
+  const project = cfg.current_project;
+  const repos = (cfg.projects && cfg.projects[project] && cfg.projects[project].worktrees && cfg.projects[project].worktrees['${MILESTONE_SLUG}'] && cfg.projects[project].worktrees['${MILESTONE_SLUG}'].repos) || {};
+  process.stdout.write(JSON.stringify(repos));
+")
+```
+
+Store `$WORKTREE_REPOS` (JSON object mapping repoName -> worktreePath) for use in executor prompts.
+
+**4. Verify worktree health:**
+
+For each code repo registered in REPOS.md, verify the worktree is healthy:
+
+```bash
+HEALTH=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" worktrees health "${MILESTONE_SLUG}" 2>/dev/null || echo '{"healthy":true,"issues":[]}')
+```
+
+If the `worktrees health` subcommand is not available, perform inline checks:
+
+For each repo in the worktree:
+```bash
+# Check branch
+BRANCH=$(git -C "${WORKTREE_PATH}" rev-parse --abbrev-ref HEAD 2>/dev/null)
+# Check clean state
+STATUS=$(git -C "${WORKTREE_PATH}" status --porcelain 2>/dev/null)
+```
+
+If branch is wrong or uncommitted changes exist, **warn** but continue (quick sanity check, not a full health audit):
+```
+⚠ Worktree health warning for ${REPO_NAME}:
+  - Expected branch: milestone/${MILESTONE_SLUG}, actual: ${BRANCH}
+  - Has uncommitted changes
+Continuing anyway — review worktree state after execution.
+```
+
+**5. Do NOT clear active_context after phase completion.**
+
+The milestone worktree persists across all phases within the milestone until `complete-milestone` is run. active_context is NOT cleared in the post-execution steps of this workflow.
+
+**Note on backward compatibility:**
+The old `branching_strategy` check and `createRepoBranches` code path is removed. If `branching_strategy` is set to "phase" or "milestone" in an older config, the worktree path runs instead.
 </step>
 
 <step name="validate_phase">
@@ -217,6 +305,13 @@ Execute each wave in sequence. Within a wave: parallel if `PARALLELIZATION=true`
        Commit each task atomically. Create SUMMARY.md. Update STATE.md and ROADMAP.md.
        </objective>
 
+       ${WORKTREE_REPOS && WORKTREE_REPOS !== '{}' ? `
+       <worktree_context>
+       This phase is executing in a git worktree. Work in these directories — do NOT use the main checkout paths:
+       ${Object.entries(JSON.parse(WORKTREE_REPOS)).map(([name, dir]) => '- ' + name + ': ' + dir).join('\n       ')}
+       </worktree_context>
+       ` : ''}
+
        <execution_context>
        @~/.claude/deliver-great-systems/workflows/execute-plan.md
        @~/.claude/deliver-great-systems/templates/summary.md
@@ -292,11 +387,7 @@ Execute each wave in sequence. Within a wave: parallel if `PARALLELIZATION=true`
 
    If `CODEREVIEW` is not `true`: skip silently, proceed to next step.
 
-   **If `NON_INTERACTIVE` is true:**
-   Log: `[AUTO-RESOLVE] Code review enabled but skipping in non-interactive mode (codereview requires interactive Task spawning)`
-   Skip codereview, proceed to next step.
-
-   **If `NON_INTERACTIVE` is false (interactive mode) AND `CODEREVIEW` is `true`:**
+   The codereview workflow is non-interactive by design — it auto-fixes low-risk issues and logs CRITICAL/HIGH findings as deviations to SUMMARY.md rather than prompting. It runs in both interactive and job modes.
 
    For each plan that completed successfully in this wave:
 
@@ -570,10 +661,10 @@ Gap closure cycle: `/dgs:plan-phase {X} --gaps` reads VERIFICATION.md → create
 </step>
 
 <step name="update_roadmap">
-**Mark phase complete and update all tracking files:**
+**Mark phase done, commit tracking files, and push — all atomically:**
 
 ```bash
-COMPLETION=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" phase complete "${PHASE_NUMBER}")
+FINALIZE=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" phase finalize "${PHASE_NUMBER}" --push)
 ```
 
 The CLI handles:
@@ -582,14 +673,12 @@ The CLI handles:
 - Updating plan count to final
 - Advancing STATE.md to next phase
 - Updating REQUIREMENTS.md traceability
+- **Committing** ROADMAP.md, STATE.md, REQUIREMENTS.md, and `${phase_dir}/*-VERIFICATION.md` in a single atomic commit
+- Pushing (if sync_push=auto) in the same call
 
-Extract from result: `next_phase`, `next_phase_name`, `is_last_phase`.
-
-```bash
-node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" commit "docs(phase-{X}): complete phase execution" --push --files ${roadmap_path} ${state_path} ${requirements_path} ${phase_dir}/*-VERIFICATION.md
-```
+Extract from result: `next_phase`, `next_phase_name`, `is_last_phase`, `committed`, `hash`, `pushed`.
 
-Parse the commit result JSON. If `needs_push` is true (sync_push is "prompt" mode), handle push prompting via the existing sync_after step. If `pushed` is true, the push already happened atomically with the commit -- skip the sync_after push for this commit (avoid double-push). If `pushed` is false and `push_result` exists, log the push warning but do not halt.
+Parse the result JSON. If `needs_push` is true (sync_push is "prompt" mode), handle push prompting via the existing sync_after step. If `pushed` is true, the push already happened atomically with the commit — skip the sync_after push for this commit (avoid double-push). If `pushed` is false and `push_result` exists, log the push warning but do not halt.
 </step>
 
 <step name="sync_after">
@@ -683,7 +772,7 @@ Read and follow `~/.claude/deliver-great-systems/workflows/transition.md`, passi
 
 **HARD STOP.** The workflow ends here. Do NOT read transition.md. Do NOT read ROADMAP.md. Do NOT execute any additional phases.
 
-**Use ONLY the `is_last_phase`, `next_phase`, and `next_phase_name` values from the `phase complete` result in the update_roadmap step.** Do NOT read the roadmap or any other file to determine remaining phases — the CLI already computed this.
+**Use ONLY the `is_last_phase`, `next_phase`, and `next_phase_name` values from the `phase finalize` result in the update_roadmap step.** Do NOT read the roadmap or any other file to determine remaining phases — the CLI already computed this.
 
 If `is_last_phase` is `false`:
 ```

package/deliver-great-systems/workflows/execute-plan.md

@@ -452,25 +452,10 @@ Keep STATE.md under 150 lines.
 If SUMMARY "Issues Encountered" ≠ "None": yolo → log and continue. Interactive → present issues, wait for acknowledgment.
 </step>
 
-<step name="update_roadmap">
-```bash
-node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" roadmap update-plan-progress "${PHASE}"
-```
-Counts PLAN vs SUMMARY files on disk. Updates progress table row with correct count and status (`In Progress` or `Complete` with date).
-</step>
-
-<step name="update_requirements">
-Mark completed requirements from the PLAN.md frontmatter `requirements:` field:
-
-```bash
-node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" requirements mark-complete ${REQ_IDS}
-```
-
-Extract requirement IDs from the plan's frontmatter (e.g., `requirements: [AUTH-01, AUTH-02]`). If no requirements field, skip.
-</step>
+<step name="finalize_plan">
+**Update state/roadmap/requirements and commit plan metadata atomically.**
 
-<step name="git_commit_metadata">
-**Multi-repo guard:** If any task used `commit --multi-repo` and returned `success: false`, display a warning before committing planning metadata:
+**Multi-repo guard:** If any task used `commit --multi-repo` and returned `success: false`, display a warning before finalizing:
 
 ```
 Warning: Some repo commits failed. Planning metadata will still be committed to track partial progress.
@@ -479,11 +464,17 @@ Check SUMMARY.md status field for per-repo details.
 
 The planning metadata commit proceeds regardless (to track partial progress), but the warning ensures visibility. The SUMMARY.md `status: partial` field records which repos failed.
 
-Task code already committed per-task. Commit plan metadata:
-
 ```bash
-node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" commit "docs({phase}-{plan}): complete [plan-name] plan" --files ${phase_dir}/{phase}-{plan}-SUMMARY.md ${state_path} ${roadmap_path} ${requirements_path}
+node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" plan finalize "${PHASE}" "${PLAN}"
 ```
+
+The CLI handles (in one atomic call):
+- `roadmap update-plan-progress` (progress table, status, date, checkbox)
+- `requirements mark-complete` (from PLAN.md `requirements:` frontmatter — auto-extracted)
+- `state update-progress` (global progress bar, idempotent with `record_metrics`)
+- Commits `{phase}-{plan}-PLAN.md`, `{phase}-{plan}-SUMMARY.md`, `STATE.md`, `ROADMAP.md`, `REQUIREMENTS.md` with message `docs({phase}-{plan}): complete {plan-name} plan`
+
+The plan name is auto-extracted from the PLAN.md `plan_name` frontmatter field (fallback: "execution"). To override, add `--plan-name "<name>"` to the call.
 </step>
 
 <step name="update_codebase_map">

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"`
 
@@ -386,7 +384,7 @@ Usage: `/dgs:debug` (resume active session)
 Capture idea or task as todo from current conversation. *(Tier 1: lite)*
 
 - Extracts context from conversation (or uses provided description)
-- Creates structured todo file in the project's todos/pending/ directory
+- Creates structured todo file in the project's todos/ directory
 - Infers area from file paths for grouping
 - Checks for duplicates before creating
 - Updates STATE.md todo count
@@ -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
 
@@ -470,7 +468,7 @@ Usage: `/dgs:discuss-idea` (shows picker)
 Research an idea's feasibility and technical landscape. *(Tier 2: planning)*
 
 - Five dimensions: web search, codebase analysis, landscape survey, approaches, feasibility
-- Creates research document at `docs/ideas/pending/{slug}-research.md` (relative to planning root)
+- Creates research document at `docs/ideas/{slug}-research.md` (relative to planning root)
 - Appends Research Log to idea file (Summary, Document link, Key Finding, Recommendation)
 - Can run multiple times; each run appends a new entry
 
@@ -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/init-product.md

@@ -206,16 +206,6 @@ AskUserQuestion([
       { label: "Yes (Recommended)", description: "Planning docs tracked in version control" },
       { label: "No", description: "Keep planning docs local-only (add to .gitignore)" }
     ]
-  },
-  {
-    header: "Branching",
-    question: "Git branching strategy?",
-    multiSelect: false,
-    options: [
-      { label: "None (Recommended)", description: "Commit to current branch (fine for single projects)" },
-      { label: "Per Phase", description: "Branch per phase, review before merging" },
-      { label: "Per Milestone", description: "Branch per project, merge all at end (for parallel projects)" }
-    ]
   }
 ])
 ```
@@ -282,10 +272,9 @@ AskUserQuestion([
     "discipline": true|false
   },
   "git": {
-    "branching_strategy": "none|phase|milestone",
     "base_branch": "[from earlier question]",
-    "sync_push": "prompt",
-    "sync_pull": "prompt"
+    "sync_push": "auto",
+    "sync_pull": "auto"
   }
 }
 ```
@@ -300,11 +289,6 @@ Smart defaults (not asked): `parallelization: true`, `auto_advance: false`, `nyq
 node /Users/adrian/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "chore: add product config" --files ${config_path}
 ```
 
-**Branch name preview:** If `branching_strategy` is not `"none"`, show:
-```
-Branch names will look like: dgs/{project-slug}/phase-03-auth
-```
-
 **b7. Commit initialized files:**
 
 Use the `files_created` array from the init response to build the commit file list: