@ktpartners/dgs-platform 2.6.2

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

@@ -0,0 +1,997 @@
+<purpose>
+Display the complete DGS command reference. Output ONLY the reference content. Do NOT add project-specific analysis, git status, next-step suggestions, or any commentary beyond the reference.
+</purpose>
+
+<context_tier>none</context_tier>
+
+<reference>
+# DGS Command Reference
+
+**DGS** (Deliver Great Systems) creates hierarchical project plans optimized for solo agentic development with Claude Code.
+
+## 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
+
+**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)
+
+## Layout Detection
+
+DGS supports two directory layouts:
+
+- **`.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.
+
+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.
+
+## Staying Updated
+
+DGS evolves fast. Update periodically:
+
+```bash
+npx @ktpartners/dgs-platform@latest
+```
+
+## Context Tiers
+
+Each command loads a specific tier of project context. Higher tiers include all lower-tier files.
+
+| Tier | Name | What it loads |
+|------|------|---------------|
+| 0 | none | No project context |
+| 1 | lite | PROJECT.md, STATE.md, config.json |
+| 2 | planning | + ROADMAP.md, REQUIREMENTS.md, REPOS.md, codebase docs |
+| 3 | execution | + Phase files (CONTEXT.md, RESEARCH.md, PLANs, SUMMARYs) |
+| 4 | verification | + VERIFICATION.md, UAT artifacts |
+
+## Core Workflow
+
+```
+/dgs:new-project → /dgs:plan-phase → /dgs:execute-phase → repeat
+```
+
+### Product Setup (v2)
+
+**`/dgs:init-product`**
+One-time setup of the product folder for multi-project, multi-repo work. *(Tier 1: lite)*
+
+- Creates `REPOS.md` and `PROJECTS.md` in the planning root
+- Scans for git repos in subdirectories and registers them
+- Offers migration from existing v1 setup (moves artifacts into project subfolder)
+- Initializes product-level git if not already a repo
+
+Usage: `/dgs:init-product`
+
+### Project Initialization
+
+**`/dgs:new-project`**
+Initialize new project through unified flow. *(Tier 2: planning)*
+
+One command takes you from idea to ready-for-planning:
+- 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
+
+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>/`.
+
+Usage: `/dgs:new-project`
+
+**`/dgs:map-codebase [<repo-name>]`**
+Map registered repos with parallel agents to produce structured codebase documentation. *(Tier 2: planning)*
+
+- Reads REPOS.md to discover registered repos and their paths
+- Spawns 4 parallel mapper agents per repo (Stack, Architecture, Quality, Concerns)
+- Creates `codebase/<repo-name>/` subdirectory per repo with 7 documents: STACK.md, ARCHITECTURE.md, STRUCTURE.md, CONVENTIONS.md, TESTING.md, INTEGRATIONS.md, CONCERNS.md
+- Synthesizes 7 unified top-level files from per-repo content (labeled repo sections + cross-repo summary)
+- Generates CROSS-REPO.md with comparison tables for shared dependencies, API boundaries, common/divergent patterns (2+ repos only)
+- Runs secret scanning across all per-repo and unified files
+- Use before `/dgs:new-project` on existing codebases
+
+**Modes:**
+- **Refresh** (default, no args): Clears all codebase maps and remaps everything from scratch
+- **Update** (`/dgs:map-codebase <repo-name>` or `--only <name>`): Re-maps only the specified repo, regenerates unified files from all repos
+
+**Directory structure:**
+```
+codebase/
+├── <repo-name>/          # Per-repo maps (one per registered repo)
+│   ├── STACK.md
+│   ├── ARCHITECTURE.md
+│   ├── STRUCTURE.md
+│   ├── CONVENTIONS.md
+│   ├── TESTING.md
+│   ├── INTEGRATIONS.md
+│   └── CONCERNS.md
+├── ARCHITECTURE.md       # Unified (synthesized from all repos)
+├── STACK.md              # Unified
+├── STRUCTURE.md          # Unified
+└── CROSS-REPO.md         # Cross-repo analysis (2+ repos)
+```
+
+Usage: `/dgs:map-codebase` (refresh all repos)
+Usage: `/dgs:map-codebase api-service` (update specific repo)
+Usage: `/dgs:map-codebase --only api-service` (same, explicit flag)
+
+### Project Management (v2)
+
+**`/dgs:switch-project [name]`**
+Switch active project context. *(Tier 1: lite)*
+
+- If no name given, shows picker with all active projects
+- Sets `current_project` in `dgs.config.json`
+- All subsequent DGS commands operate on the selected project
+- Shows brief status of the switched-to project
+
+Usage: `/dgs:switch-project auth-overhaul`
+Usage: `/dgs:switch-project` (shows picker)
+
+**`/dgs:list-projects`**
+Show all projects and their status. *(Tier 1: lite)*
+
+- Reads PROJECTS.md and each project's STATE.md
+- Shows active and completed projects with progress bars
+- Displays which repos each project touches
+
+Usage: `/dgs:list-projects`
+
+**`/dgs:complete-project`**
+Mark the current project as done. *(Tier 1: lite)*
+
+- Verifies all phases complete (or prompts for early completion)
+- Sets `status: completed` in project's STATE.md
+- Moves project from Active to Completed in PROJECTS.md
+- Clears `current_project` and prompts to switch if other projects exist
+
+Usage: `/dgs:complete-project`
+
+### Repo Management (v2)
+
+**`/dgs:add-repo [path]`**
+Register a new repo with the product. *(Tier 1: lite)*
+
+- Verifies path exists and contains a git repo
+- Extracts GitHub URL from git remote
+- Adds to REPOS.md
+- Optionally runs `/dgs:map-codebase` for the new repo
+
+Usage: `/dgs:add-repo ./services/api`
+
+**`/dgs:remove-repo [name]`**
+Unregister a repo from the product. *(Tier 1: lite)*
+
+- Checks if active projects reference this repo
+- Warns before removal if references found
+- Removes from REPOS.md
+
+Usage: `/dgs:remove-repo legacy-service`
+
+**`/dgs:overlap-check`**
+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`
+
+Usage: `/dgs:overlap-check`
+
+### Phase Planning
+
+**`/dgs:discuss-phase <number>`**
+Help articulate your vision for a phase before planning. *(Tier 2: planning)*
+
+- Captures how you imagine this phase working
+- Creates CONTEXT.md with your vision, essentials, and boundaries
+- Use when you have ideas about how something should look/feel
+- Optional `--batch` asks 2-5 related questions at a time instead of one-by-one
+
+Usage: `/dgs:discuss-phase 2`
+Usage: `/dgs:discuss-phase 2 --batch`
+Usage: `/dgs:discuss-phase 2 --batch=3`
+
+**`/dgs:research-phase <number>`**
+Comprehensive ecosystem research for niche/complex domains. *(Tier 2: planning)*
+
+- Discovers standard stack, architecture patterns, pitfalls
+- Creates RESEARCH.md with "how experts build this" knowledge
+- Use for 3D, games, audio, shaders, ML, and other specialized domains
+- Goes beyond "which library" to ecosystem knowledge
+
+Usage: `/dgs:research-phase 3`
+
+**`/dgs:list-phase-assumptions <number>`**
+See what Claude is planning to do before it starts. *(Tier 2: planning)*
+
+- Shows Claude's intended approach for a phase
+- Lets you course-correct if Claude misunderstood your vision
+- No files created - conversational output only
+
+Usage: `/dgs:list-phase-assumptions 3`
+
+**`/dgs:plan-phase <number>`**
+Create detailed execution plan for a specific phase. *(Tier 2: planning)*
+
+- Generates PLAN.md files in the phase directory
+- Breaks phase into concrete, actionable tasks
+- Includes verification criteria and success measures
+- Multiple plans per phase supported (XX-01, XX-02, etc.)
+- `--non-interactive`: Skip interactive prompts (auto-resolve confirmation gates) without auto-advancing to execute-phase
+- `--auto`: Auto-advance through plan-phase into execute-phase (implies `--non-interactive`)
+
+**v2 additions:** Each task includes a `<repos>` field identifying which repos it touches. Planner auto-detects repos from file paths against REPOS.md.
+
+Usage: `/dgs:plan-phase 1`
+Usage: `/dgs:plan-phase 1 --non-interactive` (skip prompts, stop after planning)
+Usage: `/dgs:plan-phase 1 --auto` (skip prompts and auto-advance to execution)
+
+### Execution
+
+**`/dgs:execute-phase <phase-number>`**
+Execute all plans in a phase. *(Tier 3: execution)*
+
+- Groups plans by wave (from frontmatter), executes waves sequentially
+- Plans within each wave run in parallel via Task tool
+- Verifies phase goal after all plans complete
+- Updates REQUIREMENTS.md, ROADMAP.md, STATE.md
+- `--non-interactive`: Auto-approve checkpoints and verification without auto-advancing to next phase
+- `--auto`: Auto-advance to next phase via transition.md (implies `--non-interactive`)
+- `--gaps-only`: Execute only gap-closure plans
+
+**v2 additions:** Pre-flight check for uncommitted changes in touched repos. Git commits are scoped per-repo automatically (changes to `server/` and `web-app/` produce separate commits). Commit messages include project context: `feat(auth-overhaul/02-01): add OAuth callback`.
+
+Usage: `/dgs:execute-phase 5`
+Usage: `/dgs:execute-phase 5 --non-interactive` (auto-approve without auto-advancing)
+Usage: `/dgs:execute-phase 5 --auto` (auto-approve and advance to next phase)
+
+### Quick Mode
+
+**`/dgs:quick`**
+Execute small, ad-hoc tasks with DGS guarantees but skip optional agents. *(Tier 2: planning)*
+
+Quick mode uses the same system with a shorter path:
+- Spawns planner + executor (skips researcher, checker, verifier)
+- Quick tasks live in the project's `quick/` directory
+- Updates STATE.md tracking (not ROADMAP.md)
+
+Use when you know exactly what to do and the task is small enough to not need research or verification.
+
+Usage: `/dgs:quick`
+
+### Roadmap Management
+
+**`/dgs:add-phase <description>`**
+Add new phase to end of current milestone. *(Tier 2: planning)*
+
+- Appends to ROADMAP.md
+- Uses next sequential number
+- Updates phase directory structure
+
+Usage: `/dgs:add-phase "Add admin dashboard"`
+
+**`/dgs:insert-phase <after> <description>`**
+Insert urgent work as decimal phase between existing phases. *(Tier 2: planning)*
+
+- Creates intermediate phase (e.g., 7.1 between 7 and 8)
+- Useful for discovered work that must happen mid-milestone
+- Maintains phase ordering
+
+Usage: `/dgs:insert-phase 7 "Fix critical auth bug"`
+Result: Creates Phase 7.1
+
+**`/dgs:remove-phase <number>`**
+Remove a future phase and renumber subsequent phases. *(Tier 2: planning)*
+
+- Deletes phase directory and all references
+- Renumbers all subsequent phases to close the gap
+- Only works on future (unstarted) phases
+- Git commit preserves historical record
+
+Usage: `/dgs:remove-phase 17`
+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)*
+
+- Deep questioning to understand what you're building next
+- 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).
+
+Usage: `/dgs:new-milestone "v2.0 Features"`
+
+**`/dgs:complete-milestone <version>`**
+Archive completed milestone and prepare for next version. *(Tier 4: verification)*
+
+- Creates MILESTONES.md entry with stats
+- Archives full details to milestones/ directory
+- Creates git tag for the release
+- Prepares workspace for next version
+
+When invoked from a milestone job (`<job-mode>silent</job-mode>`), all interactive gates are auto-resolved: scope confirmation, incomplete requirements acknowledgment, phase archival (skipped), branch handling (kept for manual review), and tag push (skipped for safety).
+
+Usage: `/dgs:complete-milestone 1.0.0`
+
+### Progress Tracking
+
+**`/dgs:progress`**
+Check project status and intelligently route to next action. *(Tier 1: lite)*
+
+- Shows visual progress bar and completion percentage
+- Summarizes recent work from SUMMARY files
+- Displays current position and what's next
+- Lists key decisions and open issues
+- Offers to execute next plan or create it if missing
+- Detects 100% milestone completion
+
+**v2 additions:** Shows current project context and which repos it touches. Notes if other active projects overlap on the same repos.
+
+Usage: `/dgs:progress`
+
+### Session Management
+
+**`/dgs:resume-work`**
+Resume work from previous session with full context restoration. *(Tier 1: lite)*
+
+- Reads STATE.md for project context
+- Shows current position and recent progress
+- Offers next actions based on project state
+
+Usage: `/dgs:resume-work`
+
+**`/dgs:pause-work`**
+Create context handoff when pausing work mid-phase. *(Tier 1: lite)*
+
+- Creates .continue-here file with current state
+- Updates STATE.md session continuity section
+- Captures in-progress work context
+
+Usage: `/dgs:pause-work`
+
+### Debugging
+
+**`/dgs:debug [issue description]`**
+Systematic debugging with persistent state across context resets. *(Tier 2: planning)*
+
+- Gathers symptoms through adaptive questioning
+- Creates debug tracking file in the debug directory
+- Investigates using scientific method (evidence -> hypothesis -> test)
+- Survives `/clear` -- run `/dgs:debug` with no args to resume
+- Archives resolved issues to debug/resolved/
+
+Usage: `/dgs:debug "login button doesn't work"`
+Usage: `/dgs:debug` (resume active session)
+
+### Todo Management
+
+**`/dgs:add-todo [description]`**
+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
+- Infers area from file paths for grouping
+- Checks for duplicates before creating
+- Updates STATE.md todo count
+
+Usage: `/dgs:add-todo` (infers from conversation)
+Usage: `/dgs:add-todo Add auth token refresh`
+
+**`/dgs:check-todos [area]`**
+List pending todos and select one to work on. *(Tier 1: lite)*
+
+- Lists all pending todos with title, area, age
+- Optional area filter (e.g., `/dgs:check-todos api`)
+- Loads full context for selected todo
+- Routes to appropriate action (work now, add to phase, brainstorm)
+- Moves todo to done/ when work begins
+
+Usage: `/dgs:check-todos`
+Usage: `/dgs:check-todos api`
+
+### Ideas & Specs
+
+`capture ideas → develop idea → write spec → new-project --auto`
+
+#### Ideas
+
+**`/dgs:add-idea [description]`**
+Capture a new idea with title, problem statement, and optional tags. *(Tier 1: lite)*
+
+- Interactive mode: guided prompts for title, problem, rough idea, tags
+- Auto mode: `/dgs:add-idea --auto "freeform text"` extracts structure automatically
+
+Usage: `/dgs:add-idea`
+Usage: `/dgs:add-idea --auto "Let users export data as CSV"`
+
+**`/dgs:update-idea <id>`**
+Update an existing idea's content or append notes. *(Tier 1: lite)*
+
+- Edit title, problem, rough idea, or tags
+- Append timestamped notes: `/dgs:update-idea 3 --note "Talked to users, they want this"`
+
+Usage: `/dgs:update-idea 3`
+Usage: `/dgs:update-idea 3 --note "Priority increased"`
+
+**`/dgs:list-ideas`**
+View all ideas grouped by state (pending, done, rejected). *(Tier 1: lite)*
+
+- Filter by tag: `--tag api`
+- Warns about orphaned done ideas with no spec reference
+
+Usage: `/dgs:list-ideas`
+Usage: `/dgs:list-ideas --tag backend`
+
+**`/dgs:reject-idea <id>`**
+Mark an idea as rejected with optional reason. *(Tier 1: lite)*
+
+- Requires confirmation before rejecting
+- Preserves git history via `git mv`
+
+Usage: `/dgs:reject-idea 5`
+
+**`/dgs:restore-idea <id>`**
+Restore a rejected or done idea back to pending. *(Tier 1: lite)*
+
+- Requires confirmation before restoring
+- Preserves git history via `git mv`
+
+Usage: `/dgs:restore-idea 5`
+
+**`/dgs:discuss-idea [id]`**
+Develop and refine an idea through structured discussion. *(Tier 2: planning)*
+
+- Three phases: Understanding, Exploration, Refinement
+- Appends Discussion Log to idea file (Key Insights, Refined Problem, Refined Approach, Open Questions, Decision)
+- Builds on prior discussions when re-running
+- User can exit mid-discussion; partial progress saved
+
+Usage: `/dgs:discuss-idea 5`
+Usage: `/dgs:discuss-idea` (shows picker)
+
+**`/dgs:research-idea [id]`**
+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)
+- Appends Research Log to idea file (Summary, Document link, Key Finding, Recommendation)
+- Can run multiple times; each run appends a new entry
+
+Usage: `/dgs:research-idea 5`
+Usage: `/dgs:research-idea` (shows picker)
+
+**`/dgs:develop-idea [id]`**
+Combined discussion then research in one continuous flow. *(Tier 2: planning)*
+
+- Runs discussion first, commits, then research
+- Skips research if discussion concludes idea is not viable
+- Offers re-run choices when prior history exists (re-do both, just discuss, just research)
+
+Usage: `/dgs:develop-idea 5`
+Usage: `/dgs:develop-idea` (shows picker)
+
+**`/dgs:consolidate-ideas [id...] [--title "..."]`**
+Merge two or more related pending ideas into a single AI-synthesised idea. *(Tier 2: planning)*
+
+- Without IDs: lists pending ideas for interactive selection (minimum 2 required)
+- AI synthesises a coherent body capturing the combined intent of all source ideas (not mechanical concatenation)
+- Tags are the deduplicated union of all source idea tags
+- Discussion and research logs are merged with `[from #ID]` attribution, ordered chronologically
+- User reviews a diff-style preview comparing source ideas with the synthesised result before committing
+- User can approve, request edits, or cancel
+- After approval, source ideas move to `consolidated/` with lineage references, new idea created in `pending/`
+- Single atomic git commit: `ideas: consolidate #id1, #id2 -> #new-id - title`
+- `--title "..."`: Provide an explicit title instead of AI-generated one
+
+Usage: `/dgs:consolidate-ideas 1 3 17` (consolidate ideas 1, 3, and 17)
+Usage: `/dgs:consolidate-ideas` (interactive selection)
+Usage: `/dgs:consolidate-ideas 1 3 --title "Unified API resilience"` (with explicit title)
+
+**`/dgs:find-related-ideas [id] [--threshold high|medium|low]`**
+Find pending ideas related to a selected idea using multi-signal scoring. *(Tier 2: planning)*
+
+- Without ID: lists pending ideas for interactive selection
+- Three scoring signals: tag overlap (algorithmic), semantic similarity (AI), implementation overlap (AI)
+- Project context files (codebase/, docs/product/) inform implementation overlap scoring when available
+- Results grouped by match level (HIGH/MEDIUM/LOW) with per-idea reasoning
+- User can select ideas from results and flow directly into consolidation without a separate command
+- `--threshold`: Filter by minimum match level (default: `medium`)
+  - `high`: Only high-confidence matches
+  - `medium`: High and medium matches
+  - `low`: All matches including low-confidence
+
+Usage: `/dgs:find-related-ideas 42` (find ideas related to #42)
+Usage: `/dgs:find-related-ideas` (interactive selection)
+Usage: `/dgs:find-related-ideas 42 --threshold low` (show all matches including low)
+
+**`/dgs:undo-consolidation [id]`**
+Undo a previous consolidation -- restore source ideas to pending and delete the consolidated idea. *(Tier 1: lite)*
+
+- Without ID: lists pending ideas that have `consolidated_from` for interactive selection
+- Validates the target idea is a consolidated result (has `consolidated_from` field)
+- Shows affected ideas and asks for confirmation before proceeding
+- Restores all source ideas from `consolidated/` back to `pending/`, removes their `consolidated_into` references
+- Deletes the consolidated result idea
+- Single atomic git commit: `ideas: undo consolidation #id - title`
+
+Usage: `/dgs:undo-consolidation 5` (undo consolidation of idea #5)
+Usage: `/dgs:undo-consolidation` (interactive selection)
+
+#### Specs
+
+**`/dgs:write-spec`**
+Write a structured PRD spec from selected pending ideas. *(Tier 2: planning)*
+
+- Generates Problem, Goals, Non-Goals, User Stories, Requirements, Success Metrics
+- Cross-LLM review loop with OpenAI and Gemini (if configured)
+- Auto-searches for related prior art before drafting
+- `--auto` mode: runs full flow without user review step
+
+Usage: `/dgs:write-spec`
+Usage: `/dgs:write-spec --auto 1 3 7`
+
+**`/dgs:import-spec <path> [--ideas <id...>]`**
+Import an external document (PDF, markdown, image) and convert it into a structured 9-section PRD spec. *(Tier 2: planning)*
+
+- Reads the source file and restructures its content into DGS spec format
+- Presents converted spec for review with options to save, edit, discard, or restart
+- Saves as draft spec with original document preserved as attachment
+- `--ideas <id...>`: Link to existing idea IDs (sets source_ideas in spec frontmatter)
+
+Usage: `/dgs:import-spec ./requirements.pdf`
+Usage: `/dgs:import-spec ./mobile-app-redesign.md --ideas 3 7`
+
+**`/dgs:list-specs`**
+View all specs grouped by status (Draft, Final) with version and implementation tracking. *(Tier 1: lite)*
+
+- `--draft`: Show only draft specs
+- `--final`: Show only finalized specs
+- Output includes Version and Implementation columns showing spec version and linked milestone status
+
+Usage: `/dgs:list-specs`
+Usage: `/dgs:list-specs --final`
+
+**`/dgs:refine-spec <slug> [--section <N>]`**
+Refine a spec through conversational editing with Claude as a collaborative thinking partner. *(Tier 2: planning)*
+
+- `--section <N>`: Focus on a specific section by number or heading name
+- Version increments by 0.1 on each refinement
+- All changes saved atomically at end of session
+- Warns when refining a final-status spec (moves back to draft)
+
+Usage: `/dgs:refine-spec spec-lifecycle-management`
+Usage: `/dgs:refine-spec spec-lifecycle-management --section 5`
+Usage: `/dgs:refine-spec spec-lifecycle-management --section "requirements"`
+
+**`/dgs:approve-spec <slug>`**
+Approve a draft spec after completeness validation, transitioning to final status. *(Tier 2: planning)*
+
+- Validates required sections (Problem Statement, Goals, Requirements) and P0 requirements
+- Blocks on errors (missing required sections, blocking open questions)
+- Warns on missing optional sections (Success Metrics, Implementation Notes) -- user confirms to proceed
+- Already-final specs show informational message with no changes
+
+Usage: `/dgs:approve-spec spec-lifecycle-management`
+
+#### Documents
+
+**`/dgs:add-doc <file>`**
+Add a supporting document (PDF, image, spreadsheet) to a scope. *(Tier 1: lite)*
+
+- Scopes: product, idea, or spec
+- Auto-extracts text from PDF, XLSX, CSV, DOCX
+- Generates INDEX.md and SHA-256 checksums
+
+Usage: `/dgs:add-doc research.pdf --scope product`
+
+**`/dgs:list-docs`**
+View all documents grouped by scope with optional filters. *(Tier 1: lite)*
+
+Usage: `/dgs:list-docs`
+
+**`/dgs:remove-doc`**
+Remove a document with confirmation, or move between scopes with `--move`. *(Tier 1: lite)*
+
+Usage: `/dgs:remove-doc research.pdf --scope product`
+
+#### Search
+
+**`/dgs:search <query>`**
+Keyword search across ideas, specs, docs, and projects. *(Tier 1: lite)*
+
+- Results grouped by type with context snippets
+- Filters: `--ideas-only`, `--specs-only`, `--docs-only`, `--include-rejected`, `--tags`
+
+Usage: `/dgs:search "authentication"`
+Usage: `/dgs:search "api" --specs-only`
+
+### User Acceptance Testing
+
+**`/dgs:verify-work [phase]`**
+Validate built features through conversational UAT. *(Tier 4: verification)*
+
+- Extracts testable deliverables from SUMMARY.md files
+- Presents tests one at a time (yes/no responses)
+- Automatically diagnoses failures and creates fix plans
+- Ready for re-execution if issues found
+
+**v2 additions:** Verification runs holistically across all repos for a phase. Verifier detects repo tech stacks to run verification steps correctly.
+
+Usage: `/dgs:verify-work 3`
+
+### Milestone Auditing
+
+**`/dgs:audit-milestone [version]`**
+Audit milestone completion against original intent. *(Tier 4: verification)*
+
+- Reads all phase VERIFICATION.md files
+- Checks requirements coverage
+- Spawns integration checker for cross-phase wiring
+- Creates MILESTONE-AUDIT.md with gaps and tech debt
+
+Usage: `/dgs:audit-milestone`
+
+**`/dgs:plan-milestone-gaps`**
+Create phases to close gaps identified by audit. *(Tier 2: planning)*
+
+- Reads MILESTONE-AUDIT.md and groups gaps into phases
+- Prioritizes by requirement priority (must/should/nice)
+- Adds gap closure phases to ROADMAP.md
+- Ready for `/dgs:plan-phase` on new phases
+- `--auto`: Non-interactive mode -- auto-approve gap closure phases without user confirmation
+
+Usage: `/dgs:plan-milestone-gaps`
+Usage: `/dgs:plan-milestone-gaps --auto` (non-interactive gap closure)
+
+### Milestone Jobs
+
+| Command | What it does | When to use |
+|---------|--------------|-------------|
+| `/dgs:create-milestone-job [version] [--no-check]` | Generate a build job from roadmap | Start automated milestone build |
+| `/dgs:run-job <version> [--dry-run]` | Execute a milestone job end-to-end | Run or resume a milestone job |
+| `/dgs:list-jobs` | List all jobs grouped by status | See job pipeline |
+| `/dgs:cancel-job <version>` | Cancel an in-progress job | Abort a running job |
+| `/dgs:rollback-job <version>` | Roll back code changes to pre-job state | Undo a completed or failed job |
+
+**`/dgs:rollback-job <version>`**
+Roll back all code changes made by a milestone job to pre-job commit SHAs. *(Tier 1: lite)*
+
+- Reads starting SHAs recorded by run-job
+- Shows preview of repos and phases affected
+- Requires explicit "rollback" confirmation (destructive)
+- Resets CODE repos only (planning repo preserved)
+- Deletes SUMMARY.md files for executed phases
+- Marks job status as "rolled_back"
+
+Usage: `/dgs:rollback-job v6`
+
+### Configuration
+
+**`/dgs:settings`**
+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`
+
+Usage: `/dgs:settings`
+
+**`/dgs:set-profile <profile>`**
+Quick switch model profile for DGS agents. *(Tier 0: none)*
+
+- `quality` -- Opus everywhere except verification
+- `balanced` -- Opus for planning, Sonnet for execution (default)
+- `budget` -- Sonnet for writing, Haiku for research/verification
+
+Usage: `/dgs:set-profile budget`
+
+### Utility Commands
+
+**`/dgs:cleanup`**
+Archive accumulated phase directories from completed milestones. *(Tier 1: lite)*
+
+- Identifies phases from completed milestones still in the phases directory
+- Shows dry-run summary before moving anything
+- Moves phase dirs to the milestones archive
+- Use after multiple milestones to reduce phases/ clutter
+
+Usage: `/dgs:cleanup`
+
+**`/dgs:capture-principle [description]`**
+Capture a design principle from conversation context. *(Tier 1: lite)*
+
+- Distills actionable rule from debugging sessions, root cause analysis, or architectural discussions
+- Presents proposed principle for user confirmation/editing
+- Saves to `.agents/skills/design-principles/SKILL.md` in the project repo
+- Checks for duplicate/overlapping principles before appending
+- Principles are automatically loaded by DGS planner and executor during skill discovery
+
+Usage: `/dgs:capture-principle` (infers from conversation)
+Usage: `/dgs:capture-principle "Always validate at boundaries"`
+
+**`/dgs:help`**
+Show this command reference. *(Tier 0: none)*
+
+**`/dgs:update`**
+Update DGS to latest version with changelog preview. *(Tier 0: none)*
+
+- Shows installed vs latest version comparison
+- Displays changelog entries for versions you've missed
+- Highlights breaking changes
+- Confirms before running install
+- Better than raw `npx @ktpartners/dgs-platform`
+
+Usage: `/dgs:update`
+
+**`/dgs:join-discord`**
+Join the DGS Discord community. *(Tier 0: none)*
+
+- Get help, share what you're building, stay updated
+- Connect with other DGS users
+
+Usage: `/dgs:join-discord`
+
+## Files & Structure
+
+DGS supports two directory layouts. Choose during `/dgs:init-product`:
+
+### .planning/ Layout (Default)
+
+Standard layout for repos that also contain source code:
+
+```
+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
+├── 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/
+    └── 02-core-features/
+```
+
+### v2 (Multi-Project, Multi-Repo)
+
+Multi-project mode works with either layout. Planning root contains project subfolders:
+
+```
+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
+│   ├── auth-overhaul/             # Project: auth-overhaul
+│   │   ├── PROJECT.md
+│   │   ├── REQUIREMENTS.md
+│   │   ├── ROADMAP.md
+│   │   ├── STATE.md
+│   │   ├── research/
+│   │   ├── phases/
+│   │   ├── todos/
+│   │   ├── quick/
+│   │   └── debug/
+│   └── dashboard-v2/              # Project: dashboard-v2
+│       ├── PROJECT.md
+│       └── ...
+├── CLAUDE.md                      # Product-level Claude context
+├── web-app/                       # Repo: web frontend (own git repo)
+├── server/                        # Repo: API server (own git repo)
+└── shared-lib/                    # Repo: shared utilities (own 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.
+- **Repo** = a source code repository. Registered in REPOS.md. Projects can touch multiple repos.
+
+## Workflow Modes
+
+Set during `/dgs:new-project`:
+
+**Interactive Mode**
+
+- Confirms each major decision
+- Pauses at checkpoints for approval
+- More guidance throughout
+
+**YOLO Mode**
+
+- Auto-approves most decisions
+- Executes plans without confirmation
+- Only stops for critical checkpoints
+
+Change anytime by editing `dgs.config.json`
+
+## Planning Configuration
+
+Configure how planning artifacts are managed in `dgs.config.json`:
+
+**`planning.commit_docs`** (default: `true`)
+- `true`: Planning artifacts committed to git (standard workflow)
+- `false`: Planning artifacts kept local-only, not committed
+
+When `commit_docs: false`:
+- Add the planning root to your `.gitignore`
+- Useful for OSS contributions, client projects, or keeping planning private
+- All planning files still work normally, just not tracked in git
+
+**`planning.search_gitignored`** (default: `false`)
+- `true`: Add `--no-ignore` to broad ripgrep searches
+- Only needed when the planning root is gitignored and you want project-wide searches to include it
+
+**`git.branching_strategy`** (default: `"none"`)
+- `"none"`: All work commits to current branch
+- `"phase"`: Creates branch per phase (e.g., `dgs/phase-03-authentication`)
+- `"milestone"`: Creates branch per milestone (e.g., `dgs/v1.0-mvp`)
+
+Example config:
+```json
+{
+  "planning": {
+    "commit_docs": false,
+    "search_gitignored": true
+  },
+  "git": {
+    "branching_strategy": "phase"
+  }
+}
+```
+
+## Common Workflows
+
+**Starting a new project (v1):**
+
+```
+/dgs:new-project        # Unified flow: questioning -> research -> requirements -> roadmap
+/clear
+/dgs:plan-phase 1       # Create plans for first phase
+/clear
+/dgs:execute-phase 1    # Execute all plans in phase
+```
+
+**Starting with multi-repo (v2):**
+
+```
+/dgs:init-product       # One-time: register repos, create product structure
+/dgs:new-project        # Create project (picks name, selects repos)
+/clear
+/dgs:plan-phase 1       # Plan with per-repo task tracking
+/clear
+/dgs:execute-phase 1    # Execute with per-repo commits
+```
+
+**Switching between projects (v2):**
+
+```
+/dgs:list-projects      # See all active projects
+/dgs:switch-project dashboard-v2  # Switch context
+/dgs:progress           # See where this project is at
+```
+
+**Resuming work after a break:**
+
+```
+/dgs:progress  # See where you left off and continue
+```
+
+**Adding urgent mid-milestone work:**
+
+```
+/dgs:insert-phase 5 "Critical security fix"
+/dgs:plan-phase 5.1
+/dgs:execute-phase 5.1
+```
+
+**Completing a milestone:**
+
+```
+/dgs:complete-milestone 1.0.0
+/clear
+/dgs:new-milestone  # Start next milestone (questioning -> research -> requirements -> roadmap)
+```
+
+**Completing a project (v2):**
+
+```
+/dgs:complete-project   # Mark project done, switch to another
+```
+
+**Capturing ideas during work:**
+
+```
+/dgs:add-todo                    # Capture from conversation context
+/dgs:add-todo Fix modal z-index  # Capture with explicit description
+/dgs:check-todos                 # Review and work on todos
+/dgs:check-todos api             # Filter by area
+```
+
+**Turning ideas into projects:**
+
+```
+/dgs:add-idea                       # Capture ideas as they come
+/dgs:list-ideas                     # Review when ready
+/dgs:develop-idea                   # Optional: discuss + research in one flow
+#   or separately:
+#   /dgs:discuss-idea               # Refine through conversation
+#   /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
+```
+
+**Debugging an issue:**
+
+```
+/dgs:debug "form submission fails silently"  # Start debug session
+# ... investigation happens, context fills up ...
+/clear
+/dgs:debug                                    # Resume from where you left off
+```
+
+## Getting Help
+
+- Read PROJECT.md for project vision
+- Read STATE.md for current context
+- Check ROADMAP.md for phase status
+- Run `/dgs:progress` to check where you're up to
+- Run `/dgs:list-projects` to see all projects (v2)
+</reference>