@ktpartners/dgs-platform 2.7.5 → 2.9.0

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

@@ -12,33 +12,26 @@ 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)
 
-## Layout Detection
+## Project Structure
 
-DGS supports two directory layouts:
+Planning artifacts live at the repo root. DGS detects single-project or multi-project mode automatically:
 
-- **`.planning/` layout (default):** Planning artifacts live in a `.planning/` subdirectory. Standard for repos that also contain source code.
-- **Root layout:** Planning artifacts live at the repo root. For dedicated planning repos where DGS owns the entire directory.
+- **v1 (single-project):** Standard setup. PROJECT.md, ROADMAP.md, STATE.md, phases/ live at root. All existing commands work as before.
+- **v2 (multi-project):** Detected when `PROJECTS.md` or `REPOS.md` exists. Project artifacts live under `projects/<project-slug>/`. Commands available for repo management and project switching.
 
-Choose your layout during `/dgs:init-product`. DGS detects the active layout from `dgs.config.json` and resolves all paths automatically.
-
-### v1 vs v2 Detection
-
-Within either layout, DGS detects single-project or multi-project mode:
-
-- **v1 (single-project):** Standard setup. The planning root contains PROJECT.md, ROADMAP.md, STATE.md, phases/ directly. All existing commands work as before.
-- **v2 (multi-project):** Detected when `PROJECTS.md` or `REPOS.md` exists in the planning root. Project artifacts live under `<planning-root>/<project-slug>/`. New commands available for repo management and project switching.
-
-No migration required. v1 installations continue working unchanged. Run `/dgs:init-product` when you want to adopt v2 features.
+Run `/dgs:init-product` to set up multi-project mode.
 
 ## Staying Updated
 
@@ -63,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)
@@ -81,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 `<planning-root>/<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`
 
@@ -143,7 +132,7 @@ Usage: `/dgs:map-codebase --only api-service` (same, explicit flag)
 Switch active project context. *(Tier 1: lite)*
 
 - If no name given, shows picker with all active projects
-- Sets `current_project` in `dgs.config.json`
+- Sets `current_project` in `config.json`
 - All subsequent DGS commands operate on the selected project
 - Shows brief status of the switched-to project
 
@@ -195,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`
 
@@ -316,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"`
 
@@ -417,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
 
@@ -698,7 +687,7 @@ Configure workflow toggles and model profile interactively. *(Tier 1: lite)*
 
 - Toggle researcher, plan checker, verifier agents
 - Select model profile (quality/balanced/budget)
-- Updates `dgs.config.json`
+- Updates `config.json`
 
 Usage: `/dgs:settings`
 
@@ -759,41 +748,13 @@ Usage: `/dgs:join-discord`
 
 ## Files & Structure
 
-DGS supports two directory layouts. Choose during `/dgs:init-product`:
+### Directory Layout
 
-### .planning/ Layout (Default)
-
-Standard layout for repos that also contain source code:
+Planning artifacts live at the repo root:
 
 ```
 my-repo/
-├── .planning/                # Planning root
-│   ├── dgs.config.json       # Workflow mode & gates
-│   ├── PROJECT.md            # Project vision
-│   ├── ROADMAP.md            # Current phase breakdown
-│   ├── STATE.md              # Project memory & context
-│   ├── REQUIREMENTS.md       # Scoped requirements
-│   ├── todos/                # Captured ideas and tasks
-│   ├── debug/                # Active debug sessions
-│   ├── milestones/           # Archived milestone snapshots
-│   ├── codebase/             # Codebase map (brownfield projects)
-│   └── phases/               # Phase directories
-│       ├── 01-foundation/
-│       │   ├── 01-01-PLAN.md
-│       │   └── 01-01-SUMMARY.md
-│       └── 02-core-features/
-│           ├── 02-01-PLAN.md
-│           └── 02-01-SUMMARY.md
-└── src/                      # Your source code
-```
-
-### Root Layout
-
-For dedicated planning repos where DGS owns the entire directory:
-
-```
-my-planning-repo/
-├── dgs.config.json           # Workflow mode & gates
+├── config.json               # Workflow mode & gates
 ├── PROJECT.md                # Project vision
 ├── ROADMAP.md                # Current phase breakdown
 ├── STATE.md                  # Project memory & context
@@ -804,21 +765,25 @@ my-planning-repo/
 ├── codebase/                 # Codebase map (brownfield projects)
 └── phases/                   # Phase directories
     ├── 01-foundation/
+    │   ├── 01-01-PLAN.md
+    │   └── 01-01-SUMMARY.md
     └── 02-core-features/
+        ├── 02-01-PLAN.md
+        └── 02-01-SUMMARY.md
 ```
 
 ### v2 (Multi-Project, Multi-Repo)
 
-Multi-project mode works with either layout. Planning root contains project subfolders:
+Multi-project mode adds project subfolders and a repo registry:
 
 ```
 my-product/                        # Product folder (git repo)
-├── <planning-root>/               # .planning/ or repo root
-│   ├── REPOS.md                   # Repo registry (names, paths, URLs)
-│   ├── PROJECTS.md                # Project index (auto-generated)
-│   ├── dgs.config.json            # Product-level config
-│   ├── codebase/                  # Shared codebase map
-│   │   └── <repo-name>/          # Per-repo codebase maps
+├── REPOS.md                       # Repo registry (names, paths, URLs)
+├── PROJECTS.md                    # Project index (auto-generated)
+├── config.json                    # Product-level config
+├── codebase/                      # Shared codebase map
+│   └── <repo-name>/              # Per-repo codebase maps
+├── projects/
 │   ├── auth-overhaul/             # Project: auth-overhaul
 │   │   ├── PROJECT.md
 │   │   ├── REQUIREMENTS.md
@@ -840,12 +805,12 @@ my-product/                        # Product folder (git repo)
 
 **Key concepts:**
 - **Product** = top-level container with its own git repo for planning changes
-- **Project** = a unit of work (feature, initiative). Lives in `<planning-root>/<project-slug>/`. Multiple can be active.
+- **Project** = a unit of work (feature, initiative). Lives in `projects/<project-slug>/`. Multiple can be active.
 - **Repo** = a source code repository. Registered in REPOS.md. Projects can touch multiple repos.
 
 ## Workflow Modes
 
-Set during `/dgs:new-project`:
+Set during `/dgs:init-product`:
 
 **Interactive Mode**
 
@@ -859,11 +824,11 @@ Set during `/dgs:new-project`:
 - Executes plans without confirmation
 - Only stops for critical checkpoints
 
-Change anytime by editing `dgs.config.json`
+Change anytime by editing `config.json`
 
 ## Planning Configuration
 
-Configure how planning artifacts are managed in `dgs.config.json`:
+Configure how planning artifacts are managed in `config.json`:
 
 **`planning.commit_docs`** (default: `true`)
 - `true`: Planning artifacts committed to git (standard workflow)
@@ -901,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
@@ -912,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
@@ -975,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:**