@ktpartners/dgs-platform 2.6.2

package/README.md

@@ -0,0 +1,851 @@
+<div align="center">
+
+# DELIVER GREAT SYSTEMS
+
+**A light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code, OpenCode, and Gemini CLI.**
+
+**Solves context rot — the quality degradation that happens as Claude fills its context window.**
+
+[![npm version](https://img.shields.io/npm/v/@ktpartners/dgs-platform?style=for-the-badge&logo=npm&logoColor=white&color=CB3837)](https://www.npmjs.com/package/@ktpartners/dgs-platform)
+[![npm downloads](https://img.shields.io/npm/dm/@ktpartners/dgs-platform?style=for-the-badge&logo=npm&logoColor=white&color=CB3837)](https://www.npmjs.com/package/@ktpartners/dgs-platform)
+[![Discord](https://img.shields.io/badge/Discord-Join-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/5JJgD5svVS)
+[![GitHub stars](https://img.shields.io/github/stars/TraceTasks/deliver-great-systems?style=for-the-badge&logo=github&color=181717)](https://github.com/TraceTasks/deliver-great-systems)
+[![License](https://img.shields.io/badge/license-MIT-blue?style=for-the-badge)](LICENSE)
+
+<br>
+
+```bash
+npx @ktpartners/dgs-platform@latest
+```
+
+**Works on Mac, Windows, and Linux.**
+
+<br>
+
+[Why I Built This](#why-i-built-this) · [How It Works](#how-it-works) · [Commands](#commands) · [Why It Works](#why-it-works) · [User Guide](docs/USER-GUIDE.md)
+
+</div>
+
+---
+
+> **DGS is a fork of [Get Shit Done](https://github.com/glittercowboy/get-shit-done)**
+> by [@glittercowboy](https://github.com/glittercowboy). The original project provided
+> the foundation for this tool. DGS extends it with multi-project and multi-repo support.
+
+---
+
+## Why I Built This
+
+[Get Shit Done (GSD)](https://github.com/glittercowboy/get-shit-done) proved that context engineering and subagent orchestration could make Claude Code genuinely reliable for building software. It's excellent work, and DGS is built directly on that foundation.
+
+But GSD targets solo developers working on a single codebase. Real-world products often span multiple repositories, involve a small team coordinating across services, and need a structured pipeline from idea to specification before any code gets written. That's the gap DGS fills.
+
+DGS extends GSD with:
+
+- **Product-level management** — multiple projects and repositories under one planning structure
+- **Ideas and specs pipeline** — capture ideas, develop them into formal PRDs, run cross-LLM review with OpenAI and Gemini before committing to a project
+- **Multi-repo orchestration** — plans reference repos by name, execution resolves paths at runtime, branches stay scoped per project
+
+The complexity stays in the system, not in your workflow. Behind the scenes: context engineering, XML prompt formatting, subagent orchestration, state management. What you see: a few commands that produce consistent, verified results.
+
+---
+
+Vibecoding has a bad reputation. You describe what you want, AI generates code, and you get inconsistent garbage that falls apart at scale.
+
+DGS fixes that. It's the context engineering layer that makes Claude Code reliable. Describe your idea, let the system structure it properly, and let Claude Code get to work.
+
+---
+
+## Who This Is For
+
+Small teams and solo developers building real products — people who want to describe what they want and have it built correctly, without the overhead of enterprise process.
+
+---
+
+## Getting Started
+
+```bash
+npx @ktpartners/dgs-platform@latest
+```
+
+The installer prompts you to choose:
+1. **Runtime** — Claude Code, OpenCode, Gemini, or all
+2. **Location** — Global (all projects) or local (current project only)
+
+Verify with `/dgs:help` inside your chosen runtime.
+
+> [!NOTE]
+> The npm package is called `@ktpartners/dgs-platform`, but the installed directory is `deliver-great-systems/` (the project's original name). This is cosmetic — everything works the same regardless of the directory name.
+
+### Multi-Repo Projects
+
+DGS manages multiple repos from a single planning repo. Repos sit as siblings in the same parent directory:
+
+```
+~/projects/
+├── my-product/          <- planning repo (run DGS here)
+│   └── .planning/
+├── api-service/         <- source repo (sibling)
+├── web-app/             <- source repo (sibling)
+└── mobile-app/          <- source repo (sibling)
+```
+
+Setup:
+```bash
+cd ~/projects
+mkdir my-product && cd my-product
+/dgs:init-product
+/dgs:add-repo api-service      # registers ../api-service
+/dgs:add-repo web-app           # registers ../web-app
+```
+
+Repos are registered in `.planning/REPOS.md` with `../` paths. All DGS commands run from the planning repo. See the [User Guide](docs/USER-GUIDE.md#multi-repo-setup) for detailed multi-repo setup, REPOS.md format, and migration steps.
+
+### Staying Updated
+
+DGS evolves fast. Update periodically:
+
+```bash
+npx @ktpartners/dgs-platform@latest
+```
+
+<details>
+<summary><strong>Non-interactive Install (Docker, CI, Scripts)</strong></summary>
+
+```bash
+# Claude Code
+npx @ktpartners/dgs-platform --claude --global   # Install to ~/.claude/
+npx @ktpartners/dgs-platform --claude --local    # Install to ./.claude/
+
+# OpenCode (open source, free models)
+npx @ktpartners/dgs-platform --opencode --global # Install to ~/.config/opencode/
+
+# Gemini CLI
+npx @ktpartners/dgs-platform --gemini --global   # Install to ~/.gemini/
+
+# All runtimes
+npx @ktpartners/dgs-platform --all --global      # Install to all directories
+```
+
+Use `--global` (`-g`) or `--local` (`-l`) to skip the location prompt.
+Use `--claude`, `--opencode`, `--gemini`, or `--all` to skip the runtime prompt.
+
+</details>
+
+<details>
+<summary><strong>Development Installation</strong></summary>
+
+Clone the repository and run the installer locally:
+
+```bash
+git clone https://github.com/TraceTasks/deliver-great-systems.git
+cd deliver-great-systems
+node bin/install.js --claude --local
+```
+
+Installs to `./.claude/` for testing modifications before contributing.
+
+</details>
+
+### Recommended: Skip Permissions Mode
+
+DGS is designed for frictionless automation. Run Claude Code with:
+
+```bash
+claude --dangerously-skip-permissions
+```
+
+> [!TIP]
+> This is how DGS is intended to be used — stopping to approve `date` and `git commit` 50 times defeats the purpose.
+
+<details>
+<summary><strong>Alternative: Granular Permissions</strong></summary>
+
+If you prefer not to use that flag, add this to your project's `.claude/settings.json`:
+
+```json
+{
+  "permissions": {
+    "allow": [
+      "Bash(date:*)",
+      "Bash(echo:*)",
+      "Bash(cat:*)",
+      "Bash(ls:*)",
+      "Bash(mkdir:*)",
+      "Bash(wc:*)",
+      "Bash(head:*)",
+      "Bash(tail:*)",
+      "Bash(sort:*)",
+      "Bash(grep:*)",
+      "Bash(tr:*)",
+      "Bash(git add:*)",
+      "Bash(git commit:*)",
+      "Bash(git status:*)",
+      "Bash(git log:*)",
+      "Bash(git diff:*)",
+      "Bash(git tag:*)"
+    ]
+  }
+}
+```
+
+</details>
+
+---
+
+## How It Works
+
+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>`.
+
+### 1. Set Up Product
+
+```
+/dgs:init-product
+/dgs:add-repo api-service
+/dgs:add-repo web-app
+```
+
+Creates the `.planning/` directory structure with `config.json`, `PROJECTS.md`, and `REPOS.md`. Register your source repos as siblings. This is a one-time setup — everything else builds on top of it.
+
+> **Single-repo projects** work fine too. Skip `add-repo` and DGS operates on the current directory.
+
+---
+
+### 2. Capture Ideas & Write Specs
+
+```
+/dgs:add-idea
+/dgs:discuss-idea        # optional: refine through conversation
+/dgs:research-idea       # optional: investigate feasibility
+/dgs:develop-idea        # optional: discuss + research in one step
+/dgs:write-spec
+```
+
+Ideas are lightweight captures — a title, a problem statement, optional tags. Add them whenever inspiration strikes.
+
+Before writing a spec, you can develop ideas further. `/dgs:discuss-idea` walks you through a structured conversation to refine the problem and approach. `/dgs:research-idea` investigates feasibility and the technical landscape. `/dgs:develop-idea` does both in sequence. All three are optional — go straight to `/dgs:write-spec` if the idea is already clear.
+
+When you're ready to formalize, `/dgs:write-spec` lets you select one or more ideas and generates a 9-section PRD.
+
+If you have OpenAI or Gemini API keys configured, the spec goes through a **cross-LLM review loop** — external models review the draft and provide feedback until convergence. The finalized spec then feeds directly into `/dgs:new-project --auto @spec.md` or `/dgs:new-milestone --auto <spec-id>`.
+
+> **Skip this step** if you already know what you're building. Go straight to `/dgs:new-project` and answer its questions directly.
+
+---
+
+### 3. Initialize Project
+
+```
+/dgs:new-project
+```
+
+One command, one flow. The system:
+
+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
+
+You approve the roadmap. Now you're ready to build.
+
+**Creates:** `PROJECT.md`, `REQUIREMENTS.md`, `ROADMAP.md`, `STATE.md`, `.planning/research/`
+
+---
+
+### 4. Discuss Phase
+
+```
+/dgs:discuss-phase 1
+```
+
+**This is where you shape the implementation.**
+
+Your roadmap has a sentence or two per phase. That's not enough context to build something the way *you* imagine it. This step captures your preferences before anything gets researched or planned.
+
+The system analyzes the phase and identifies gray areas based on what's being built:
+
+- **Visual features** → Layout, density, interactions, empty states
+- **APIs/CLIs** → Response format, flags, error handling, verbosity
+- **Content systems** → Structure, tone, depth, flow
+- **Organization tasks** → Grouping criteria, naming, duplicates, exceptions
+
+For each area you select, it asks until you're satisfied. The output — `CONTEXT.md` — feeds directly into the next two steps:
+
+1. **Researcher reads it** — Knows what patterns to investigate ("user wants card layout" → research card component libraries)
+2. **Planner reads it** — Knows what decisions are locked ("infinite scroll decided" → plan includes scroll handling)
+
+The deeper you go here, the more the system builds what you actually want. Skip it and you get reasonable defaults. Use it and you get *your* vision.
+
+**Creates:** `{phase_num}-CONTEXT.md`
+
+---
+
+### 5. Plan Phase
+
+```
+/dgs:plan-phase 1
+```
+
+The system:
+
+1. **Researches** — Investigates how to implement this phase, guided by your CONTEXT.md decisions
+2. **Plans** — Creates 2-3 atomic task plans with XML structure
+3. **Verifies** — Checks plans against requirements, loops until they pass
+
+Each plan is small enough to execute in a fresh context window. No degradation, no "I'll be more concise now."
+
+**Creates:** `{phase_num}-RESEARCH.md`, `{phase_num}-{N}-PLAN.md`
+
+---
+
+### 6. Execute Phase
+
+```
+/dgs:execute-phase 1
+```
+
+The system:
+
+1. **Runs plans in waves** — Parallel where possible, sequential when dependent
+2. **Fresh context per plan** — 200k tokens purely for implementation, zero accumulated garbage
+3. **Commits per task** — Every task gets its own atomic commit
+4. **Verifies against goals** — Checks the codebase delivers what the phase promised
+
+Walk away, come back to completed work with clean git history.
+
+**How Wave Execution Works:**
+
+Plans are grouped into "waves" based on dependencies. Within each wave, plans run in parallel. Waves run sequentially.
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│  PHASE EXECUTION                                                     │
+├─────────────────────────────────────────────────────────────────────┤
+│                                                                      │
+│  WAVE 1 (parallel)          WAVE 2 (parallel)          WAVE 3       │
+│  ┌─────────┐ ┌─────────┐    ┌─────────┐ ┌─────────┐    ┌─────────┐ │
+│  │ Plan 01 │ │ Plan 02 │ →  │ Plan 03 │ │ Plan 04 │ →  │ Plan 05 │ │
+│  │         │ │         │    │         │ │         │    │         │ │
+│  │ User    │ │ Product │    │ Orders  │ │ Cart    │    │ Checkout│ │
+│  │ Model   │ │ Model   │    │ API     │ │ API     │    │ UI      │ │
+│  └─────────┘ └─────────┘    └─────────┘ └─────────┘    └─────────┘ │
+│       │           │              ↑           ↑              ↑       │
+│       └───────────┴──────────────┴───────────┘              │       │
+│              Dependencies: Plan 03 needs Plan 01            │       │
+│                          Plan 04 needs Plan 02              │       │
+│                          Plan 05 needs Plans 03 + 04        │       │
+│                                                                      │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+**Why waves matter:**
+- Independent plans → Same wave → Run in parallel
+- Dependent plans → Later wave → Wait for dependencies
+- File conflicts → Sequential plans or same plan
+
+This is why "vertical slices" (Plan 01: User feature end-to-end) parallelize better than "horizontal layers" (Plan 01: All models, Plan 02: All APIs).
+
+**Creates:** `{phase_num}-{N}-SUMMARY.md`, `{phase_num}-VERIFICATION.md`
+
+---
+
+### 7. Verify Work
+
+```
+/dgs:verify-work 1
+```
+
+**This is where you confirm it actually works.**
+
+Automated verification checks that code exists and tests pass. But does the feature *work* the way you expected? This is your chance to use it.
+
+The system:
+
+1. **Extracts testable deliverables** — What you should be able to do now
+2. **Walks you through one at a time** — "Can you log in with email?" Yes/no, or describe what's wrong
+3. **Diagnoses failures automatically** — Spawns debug agents to find root causes
+4. **Creates verified fix plans** — Ready for immediate re-execution
+
+If everything passes, you move on. If something's broken, you don't manually debug — you just run `/dgs:execute-phase` again with the fix plans it created.
+
+**Automated alternative:** Use `/dgs:audit-phase` instead of interactive UAT for programmatic verification. It runs your test suite, then structurally inspects deliverables against PLAN.md. Failures trigger automatic diagnosis and fix planning. Use `--rerun-failed` after gap closure to re-verify only previously-failed items. See the [User Guide](docs/USER-GUIDE.md#phase-audit) for details.
+
+**Creates:** `{phase_num}-UAT.md`, fix plans if issues found
+
+---
+
+### 8. Repeat → Complete → Next Milestone
+
+```
+/dgs:discuss-phase 2
+/dgs:plan-phase 2
+/dgs:execute-phase 2
+/dgs:verify-work 2
+...
+/dgs:complete-milestone
+/dgs:new-milestone
+```
+
+Loop **discuss → plan → execute → verify** until milestone complete.
+
+Each phase gets your input (discuss), proper research (plan), clean execution (execute), and human verification (verify). Context stays fresh. Quality stays high.
+
+When all phases are done, `/dgs:complete-milestone` archives the milestone and tags the release.
+
+**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.
+
+---
+
+### Quick Mode
+
+```
+/dgs:quick
+```
+
+**For ad-hoc tasks that don't need full planning.**
+
+Quick mode gives you DGS guarantees (atomic commits, state tracking) with a faster path:
+
+- **Same agents** — Planner + executor, same quality
+- **Skips optional steps** — No research, no plan checker, no verifier
+- **Separate tracking** — Lives in `.planning/quick/`, not phases
+
+Use for: bug fixes, small features, config changes, one-off tasks.
+
+```
+/dgs:quick
+> What do you want to do? "Add dark mode toggle to settings"
+```
+
+**Creates:** `.planning/quick/001-add-dark-mode-toggle/PLAN.md`, `SUMMARY.md`
+
+#### Fast Mode
+
+```
+/dgs:fast <description>
+```
+
+**For changes that don't even need a planner.**
+
+Fast mode is the lightest DGS command — no subagents, no planning directory, just an atomic commit:
+
+- **No subagents** — orchestrator makes edits directly
+- **Single commit** — infers conventional prefix (fix:/feat:/chore:/docs:)
+- **Scope guard** — warns if you exceed 3 files or 30 lines
+
+Use for: typo fixes, config tweaks, one-line changes.
+
+```
+/dgs:fast fix the typo in the error message
+```
+
+---
+
+## Why It Works
+
+### Context Engineering
+
+Claude Code is incredibly powerful *if* you give it the context it needs. Most people don't.
+
+DGS handles it for you:
+
+| File | What it does |
+|------|--------------|
+| `PROJECTS.md` | Product-level project registry |
+| `REPOS.md` | Multi-repo registry — paths to sibling repos |
+| `ideas/` | Lightweight idea captures with tags and notes |
+| `specs/` | Formalized PRDs from ideas (draft → review → final) |
+| `PROJECT.md` | Project vision, always loaded |
+| `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 |
+| `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 |
+| `SUMMARY.md` | What happened, what changed, committed to history |
+
+Size limits based on where Claude's quality degrades. Stay under, get consistent excellence.
+
+### XML Prompt Formatting
+
+Every plan is structured XML optimized for Claude:
+
+```xml
+<task type="auto">
+  <name>Create login endpoint</name>
+  <files>src/app/api/auth/login/route.ts</files>
+  <action>
+    Use jose for JWT (not jsonwebtoken - CommonJS issues).
+    Validate credentials against users table.
+    Return httpOnly cookie on success.
+  </action>
+  <verify>curl -X POST localhost:3000/api/auth/login returns 200 + Set-Cookie</verify>
+  <done>Valid credentials return cookie, invalid return 401</done>
+</task>
+```
+
+Precise instructions. No guessing. Verification built in.
+
+### Multi-Agent Orchestration
+
+Every stage uses the same pattern: a thin orchestrator spawns specialized agents, collects results, and routes to the next step.
+
+| Stage | Orchestrator does | Agents do |
+|-------|------------------|-----------|
+| Research | Coordinates, presents findings | 4 parallel researchers investigate stack, features, architecture, pitfalls |
+| Planning | Validates, manages iteration | Planner creates plans, checker verifies, loop until pass |
+| Execution | Groups into waves, tracks progress | Executors implement in parallel, each with fresh 200k context |
+| Verification | Presents results, routes next | Verifier checks codebase against goals, debuggers diagnose failures |
+
+The orchestrator never does heavy lifting. It spawns agents, waits, integrates results.
+
+**The result:** You can run an entire phase — deep research, multiple plans created and verified, thousands of lines of code written across parallel executors, automated verification against goals — and your main context window stays at 30-40%. The work happens in fresh subagent contexts. Your session stays fast and responsive.
+
+### Atomic Git Commits
+
+Each task gets its own commit immediately after completion:
+
+```bash
+abc123f docs(08-02): complete user registration plan
+def456g feat(08-02): add email confirmation flow
+hij789k feat(08-02): implement password hashing
+lmn012o feat(08-02): create registration endpoint
+```
+
+> [!NOTE]
+> **Benefits:** Git bisect finds exact failing task. Each task independently revertable. Clear history for Claude in future sessions. Better observability in AI-automated workflow.
+
+Every commit is surgical, traceable, and meaningful.
+
+### Modular by Design
+
+- Add phases to current milestone
+- Insert urgent work between phases
+- Complete milestones and start fresh
+- Adjust plans without rebuilding everything
+
+You're never locked in. The system adapts.
+
+### Context Tiers
+
+Every command loads only the project files it needs. DGS uses a 5-tier system to control this, preventing unnecessary context consumption while ensuring each command has the information it requires.
+
+| Tier | Name | What it loads | Example commands |
+|------|------|---------------|-----------------|
+| 0 | none | No project files | `/dgs:help`, `/dgs:update` |
+| 1 | lite | PROJECT.md, STATE.md, config | `/dgs:progress`, `/dgs:add-idea` |
+| 2 | planning | + ROADMAP.md, REQUIREMENTS.md, REPOS.md, codebase docs | `/dgs:plan-phase`, `/dgs:write-spec` |
+| 3 | execution | + Phase files (CONTEXT.md, PLANs, SUMMARYs) | `/dgs:execute-phase` |
+| 4 | verification | + VERIFICATION.md, UAT artifacts | `/dgs:verify-work` |
+
+Each tier includes all files from lower tiers. Tier 3 (execution) loads everything from Tier 2 (planning) plus phase-specific files. Commands also accept scope flags (`--phase`, `--idea`, `--spec`) to load additional scoped files when needed.
+
+This keeps Tier 0 commands like `/dgs:help` instant (zero files loaded) while `/dgs:execute-phase` gets the full context it needs to implement correctly. No manual file management required.
+
+See the [User Guide](docs/USER-GUIDE.md#context-tiers) for the complete command-to-tier mapping.
+
+---
+
+## Commands
+
+### Core Workflow
+
+| Command | What it does |
+|---------|--------------|
+| `/dgs:new-project [--auto]` | Full initialization: questions → research → requirements → roadmap |
+| `/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 |
+| `/dgs:verify-work [N] [--auto]` | Validate features through interactive UAT (`--auto` for rubber-stamp pass) |
+| `/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 |
+
+### Navigation
+
+| Command | What it does |
+|---------|--------------|
+| `/dgs:progress` | Where am I? What's next? |
+| `/dgs:help` | Show all commands and usage guide |
+| `/dgs:update` | Update DGS with changelog preview |
+
+### Brownfield
+
+| Command | What it does |
+|---------|--------------|
+| `/dgs:map-codebase [<repo-name>]` | Map registered repos, synthesize unified codebase docs |
+
+### Phase Management
+
+| Command | What it does |
+|---------|--------------|
+| `/dgs:add-phase` | Append phase to roadmap |
+| `/dgs:insert-phase [N]` | Insert urgent work between phases |
+| `/dgs:remove-phase [N]` | Remove future phase, renumber |
+| `/dgs:list-phase-assumptions [N]` | See Claude's intended approach before planning |
+| `/dgs:plan-milestone-gaps` | Create phases to close gaps from audit |
+
+### Session
+
+| Command | What it does |
+|---------|--------------|
+| `/dgs:pause-work` | Create handoff when stopping mid-phase |
+| `/dgs:resume-work` | Restore from last session |
+
+### Ideas & Specs
+
+| Command | What it does |
+|---------|--------------|
+| `/dgs:add-idea [--auto]` | Capture a new idea (interactive or auto-extract from context) |
+| `/dgs:list-ideas [--tag TAG]` | View ideas by state, optionally filtered by tag |
+| `/dgs:discuss-idea [id]` | Develop and refine an idea through structured discussion |
+| `/dgs:research-idea [id]` | Research an idea's feasibility and technical landscape |
+| `/dgs:develop-idea [id]` | Combined discussion then research in one flow |
+| `/dgs:update-idea <id> [--note "text"]` | Edit idea content or append a timestamped note |
+| `/dgs:reject-idea <id>` | Move idea to rejected |
+| `/dgs:restore-idea <id>` | Restore a rejected/done idea to pending |
+| `/dgs:consolidate-ideas [id...] [--title "..."]` | Merge related pending ideas into a single AI-synthesised idea |
+| `/dgs:find-related-ideas [id] [--threshold high\|medium\|low]` | Find ideas related to a selected idea with multi-signal scoring |
+| `/dgs:undo-consolidation [id]` | Undo a consolidation: restore source ideas and remove the merged idea |
+| `/dgs:write-spec [id...] [--auto]` | Draft PRD from ideas with optional cross-LLM review |
+| `/dgs:import-spec <path> [--ideas <id...>]` | Import external document (PDF, markdown, image) as DGS spec |
+| `/dgs:list-specs [--draft\|--final]` | View specs by status with version and implementation tracking |
+| `/dgs:refine-spec <slug> [--section <N>]` | Refine a spec through conversational editing (increments version) |
+| `/dgs:approve-spec <slug>` | Approve a draft spec after completeness validation |
+
+### Documents & Search
+
+| Command | What it does |
+|---------|--------------|
+| `/dgs:add-doc <file> [--scope ...]` | Attach supporting document to an idea, spec, or product. Product-scoped docs are loaded as context by spec writing and planning workflows |
+| `/dgs:list-docs` | List all supporting documents by scope |
+| `/dgs:remove-doc [--move]` | Remove or move a document between scopes |
+| `/dgs:search <query> [--ideas-only\|--specs-only\|--docs-only]` | Search across ideas, specs, docs, and projects |
+
+### Project Management
+
+| Command | What it does |
+|---------|--------------|
+| `/dgs:init-product` | Initialize product-level planning structure |
+| `/dgs:add-repo [name]` | Register a sibling source repo |
+| `/dgs:remove-repo [name]` | Unregister a repo from REPOS.md |
+| `/dgs:list-projects` | Show all projects with status and repos |
+| `/dgs:switch-project [name]` | Switch active project context |
+| `/dgs:complete-project` | Mark current project as completed |
+| `/dgs:overlap-check` | Show repos touched by multiple active projects |
+| `/dgs:health [--repair]` | Validate `.planning/` directory integrity, auto-repair with `--repair` |
+
+### Utilities
+
+| Command | What it does |
+|---------|--------------|
+| `/dgs:settings` | Configure model profile and workflow agents |
+| `/dgs:set-profile <profile>` | Switch model profile (quality/balanced/budget) |
+| `/dgs:add-todo [desc]` | Capture idea for later |
+| `/dgs:check-todos [area]` | List pending todos, optionally filtered by area |
+| `/dgs:cleanup` | Archive accumulated phase directories |
+| `/dgs:debug [desc]` | Systematic debugging with persistent state |
+| `/dgs:fast <desc> [--dry-run]` | Trivial edit with single atomic commit — no subagents |
+| `/dgs:quick [--fast\|--full]` | Execute ad-hoc task with DGS guarantees (`--fast` skips subagents; `--full` adds plan-checking and verification) |
+
+### Milestone Jobs
+
+| Command | What it does |
+|---------|--------------|
+| `/dgs:create-milestone-job [version] [--no-check]` | Generate a milestone build job from the current roadmap |
+| `/dgs:run-job <version> [--dry-run]` | Execute a milestone build job end-to-end with subagent isolation |
+| `/dgs:list-jobs` | List all milestone jobs grouped by status with progress |
+| `/dgs:cancel-job <version>` | Cancel an in-progress job, reset to pending |
+| `/dgs:rollback-job <version>` | Roll back all code changes from a job to pre-job state |
+
+---
+
+## 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).
+
+### Core Settings
+
+| Setting | Options | Default | What it controls |
+|---------|---------|---------|------------------|
+| `mode` | `yolo`, `interactive` | `interactive` | Auto-approve vs confirm at each step |
+| `depth` | `quick`, `standard`, `comprehensive` | `standard` | Planning thoroughness (phases × plans) |
+
+### Model Profiles
+
+Control which Claude model each agent uses. Balance quality vs token spend.
+
+| Profile | Planning | Execution | Verification |
+|---------|----------|-----------|--------------|
+| `quality` | Opus | Opus | Sonnet |
+| `balanced` (default) | Opus | Sonnet | Sonnet |
+| `budget` | Sonnet | Sonnet | Haiku |
+
+Switch profiles:
+```
+/dgs:set-profile budget
+```
+
+Or configure via `/dgs:settings`.
+
+### Workflow Agents
+
+These spawn additional agents during planning/execution. They improve quality but add tokens and time.
+
+| Setting | Default | What it does |
+|---------|---------|--------------|
+| `workflow.research` | `true` | Researches domain before planning each phase |
+| `workflow.plan_check` | `true` | Verifies plans achieve phase goals before execution |
+| `workflow.verifier` | `true` | Confirms must-haves were delivered after execution |
+| `workflow.auto_advance` | `false` | Auto-chain discuss → plan → execute without stopping |
+| `workflow.codereview` | `false` | 3-pass, 9-agent code review after each plan execution |
+
+Use `/dgs:settings` to toggle these, or override per-invocation:
+- `/dgs:plan-phase --skip-research`
+- `/dgs:plan-phase --skip-verify`
+
+### Execution
+
+| Setting | Default | What it controls |
+|---------|---------|------------------|
+| `parallelization.enabled` | `true` | Run independent plans simultaneously |
+| `planning.commit_docs` | `true` | Track `.planning/` in git |
+
+### Git Branching
+
+Control how DGS handles branches during execution.
+
+| Setting | Options | Default | What it does |
+|---------|---------|---------|--------------|
+| `git.branching_strategy` | `none`, `phase`, `milestone` | `none` | Branch creation strategy |
+| `git.base_branch` | string | `main` | Integration target branch for merges |
+| `git.phase_branch_template` | string | `dgs/{project}/phase-{phase}-{slug}` | Template for phase branches |
+| `git.milestone_branch_template` | string | `dgs/{project}/{milestone}-{slug}` | Template for milestone branches |
+
+**Strategies:**
+- **`none`** — Commits to current branch (default DGS behavior)
+- **`phase`** — Creates a branch per phase, merges at milestone completion
+- **`milestone`** — Creates one branch for entire milestone, merges at completion
+
+**Template variables:** `{phase}` = zero-padded number, `{slug}` = phase name, `{milestone}` = version, `{project}` = project slug (prevents branch collisions in multi-project setups).
+
+**Base branch:** Set `git.base_branch` to your integration target (e.g., `develop`, `staging`). All branch creation and merge operations use this instead of `main`.
+
+**Conflict resolution:** When merges produce conflicts during `/dgs:complete-milestone`, DGS automatically classifies each conflict (ADDITIVE, DIVERGENT, STRUCTURAL, DELETION), resolves high-confidence conflicts, and escalates low-confidence ones to you with context and a proposed resolution. See the [User Guide](docs/USER-GUIDE.md#conflict-resolution) for details.
+
+---
+
+## Security
+
+### Protecting Sensitive Files
+
+DGS's codebase mapping and analysis commands read files to understand your project. **Protect files containing secrets** by adding them to Claude Code's deny list:
+
+1. Open Claude Code settings (`.claude/settings.json` or global)
+2. Add sensitive file patterns to the deny list:
+
+```json
+{
+  "permissions": {
+    "deny": [
+      "Read(.env)",
+      "Read(.env.*)",
+      "Read(**/secrets/*)",
+      "Read(**/*credential*)",
+      "Read(**/*.pem)",
+      "Read(**/*.key)"
+    ]
+  }
+}
+```
+
+This prevents Claude from reading these files entirely, regardless of what commands you run.
+
+> [!IMPORTANT]
+> DGS includes built-in protections against committing secrets, but defense-in-depth is best practice. Deny read access to sensitive files as a first line of defense.
+
+---
+
+## Troubleshooting
+
+**Commands not found after install?**
+- Restart Claude Code to reload slash commands
+- Verify files exist in `~/.claude/commands/dgs/` (global) or `./.claude/commands/dgs/` (local)
+
+**Commands not working as expected?**
+- Run `/dgs:help` to verify installation
+- Re-run `npx @ktpartners/dgs-platform` to reinstall
+
+**Updating to the latest version?**
+```bash
+npx @ktpartners/dgs-platform@latest
+```
+
+**Using Docker or containerized environments?**
+
+If file reads fail with tilde paths (`~/.claude/...`), set `CLAUDE_CONFIG_DIR` before installing:
+```bash
+CLAUDE_CONFIG_DIR=/home/youruser/.claude npx @ktpartners/dgs-platform --global
+```
+This ensures absolute paths are used instead of `~` which may not expand correctly in containers.
+
+### Uninstalling
+
+To remove DGS completely:
+
+```bash
+# Global installs
+npx @ktpartners/dgs-platform --claude --global --uninstall
+npx @ktpartners/dgs-platform --opencode --global --uninstall
+
+# Local installs (current project)
+npx @ktpartners/dgs-platform --claude --local --uninstall
+npx @ktpartners/dgs-platform --opencode --local --uninstall
+```
+
+This removes all DGS commands, agents, hooks, and settings while preserving your other configurations.
+
+---
+
+## Community Ports
+
+OpenCode and Gemini CLI are now natively supported via `npx @ktpartners/dgs-platform`.
+
+These community ports pioneered multi-runtime support for the original GSD project:
+
+| Project | Platform | Description |
+|---------|----------|-------------|
+| [gsd-opencode](https://github.com/rokicool/gsd-opencode) | OpenCode | Original GSD OpenCode adaptation |
+| gsd-gemini (archived) | Gemini CLI | Original GSD Gemini adaptation by uberfuzzy |
+
+---
+
+## Star History
+
+<a href="https://star-history.com/#glittercowboy/get-shit-done&Date">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=glittercowboy/get-shit-done&type=Date&theme=dark" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=glittercowboy/get-shit-done&type=Date" />
+   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=glittercowboy/get-shit-done&type=Date" />
+ </picture>
+</a>
+
+---
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.
+
+---
+
+<div align="center">
+
+**Claude Code is powerful. DGS makes it reliable.**
+
+</div>