@ktpartners/dgs-platform 2.6.2

package/deliver-great-systems/references/planning-config.md

@@ -0,0 +1,224 @@
+<planning_config>
+
+Configuration options for planning directory behavior.
+
+> **v2 Multi-Project:** Config file (`dgs.config.json`) is always product-level — not project-scoped. In v2 setups, project-specific paths (STATE.md, ROADMAP.md, phases/) resolve to `<project-slug>/` within the planning root via init commands, but config stays at the product root.
+
+<config_schema>
+```json
+"workflow": {
+  "research": true,
+  "plan_check": true,
+  "verifier": true,
+  "auto_advance": false,
+  "nyquist_validation": true,
+  "codereview": false
+},
+"planning": {
+  "commit_docs": true,
+  "search_gitignored": false
+},
+"git": {
+  "base_branch": "main",
+  "branching_strategy": "none",
+  "phase_branch_template": "dgs/{project}/phase-{phase}-{slug}",
+  "milestone_branch_template": "dgs/{project}/{milestone}-{slug}"
+}
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `workflow.codereview` | `false` | Spawn 3-pass multi-agent code reviewer after plan execution. Auto-fixes low-risk issues in separate commit. |
+| `commit_docs` | `true` | Whether to commit planning artifacts to git |
+| `search_gitignored` | `false` | Add `--no-ignore` to broad rg searches |
+| `git.base_branch` | `"main"` | Integration target branch for code repo branching operations (branch creation and merge) |
+| `git.branching_strategy` | `"none"` | Git branching approach: `"none"`, `"phase"`, or `"milestone"` |
+| `git.phase_branch_template` | `"dgs/{project}/phase-{phase}-{slug}"` | Branch template for phase strategy |
+| `git.milestone_branch_template` | `"dgs/{project}/{milestone}-{slug}"` | Branch template for milestone strategy |
+</config_schema>
+
+<commit_docs_behavior>
+
+**When `commit_docs: true` (default):**
+- Planning files committed normally
+- SUMMARY.md, STATE.md, ROADMAP.md tracked in git
+- Full history of planning decisions preserved
+
+**When `commit_docs: false`:**
+- Skip all `git add`/`git commit` for planning files
+- User must add planning directory to `.gitignore`
+- Useful for: OSS contributions, client projects, keeping planning private
+
+**Using dgs-tools.cjs (preferred):**
+
+```bash
+# Commit with automatic commit_docs + gitignore checks:
+node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" commit "docs: update state" --files ${state_path}
+
+# Load config via state load (returns JSON):
+INIT=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" state load)
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+# commit_docs is available in the JSON output
+
+# Or use init commands which include commit_docs:
+INIT=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" init execute-phase "1")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+# commit_docs is included in all init command outputs
+```
+
+**Auto-detection:** If the planning directory is gitignored, `commit_docs` is automatically `false` regardless of config. This prevents git errors when users have the planning directory in `.gitignore`.
+
+**Commit via CLI (handles checks automatically):**
+
+```bash
+node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" commit "docs: update state" --files ${state_path}
+```
+
+The CLI checks `commit_docs` config and gitignore status internally — no manual conditionals needed.
+
+</commit_docs_behavior>
+
+<search_behavior>
+
+**When `search_gitignored: false` (default):**
+- Standard rg behavior (respects .gitignore)
+- Direct path searches work: `rg "pattern" ${project_root}/` finds files
+- Broad searches skip gitignored: `rg "pattern"` skips planning directory
+
+**When `search_gitignored: true`:**
+- Add `--no-ignore` to broad rg searches that should include the planning directory
+- Only needed when searching entire repo and expecting planning directory matches
+
+**Note:** Most DGS operations use direct file reads or explicit paths, which work regardless of gitignore status.
+
+</search_behavior>
+
+<setup_uncommitted_mode>
+
+To use uncommitted mode:
+
+1. **Set config:**
+   ```json
+   "planning": {
+     "commit_docs": false,
+     "search_gitignored": true
+   }
+   ```
+
+2. **Add to .gitignore:**
+   ```
+   .planning/
+   ```
+
+3. **Existing tracked files:** If the planning directory was previously tracked:
+   ```bash
+   git rm -r --cached ${project_root}
+   git commit -m "chore: stop tracking planning docs"
+   ```
+
+4. **Branch merges:** When using `branching_strategy: phase` or `milestone`, the `complete-milestone` workflow automatically strips planning files from staging before merge commits when `commit_docs: false`.
+
+</setup_uncommitted_mode>
+
+<branching_strategy_behavior>
+
+**Branching Strategies:**
+
+| Strategy | When branch created | Branch scope | Merge point |
+|----------|---------------------|--------------|-------------|
+| `none` | Never | N/A | N/A |
+| `phase` | At `execute-phase` start | Single phase | User merges after phase |
+| `milestone` | At first `execute-phase` of milestone | Entire milestone | At `complete-milestone` |
+
+**Base Branch:**
+
+All branching operations on code repos (branch creation in `execute-phase`, merge in `complete-milestone`) use `git.base_branch` as the starting point instead of hardcoded `main`. Default is `main`. Set during `/dgs:init-product` or change via `/dgs:settings`. The product folder repo always uses `main` — only sibling code repos registered in REPOS.md use the configured base branch.
+
+**When `git.branching_strategy: "none"` (default):**
+- All work commits to current branch
+- Standard DGS behavior
+
+**When `git.branching_strategy: "phase"`:**
+- `execute-phase` creates/switches to a branch before execution
+- Branch name from `phase_branch_template` (e.g., `dgs/checkout/phase-03-authentication`)
+- All plan commits go to that branch
+- User merges branches manually after phase completion
+- `complete-milestone` offers to merge all phase branches
+
+**When `git.branching_strategy: "milestone"`:**
+- First `execute-phase` of milestone creates the milestone branch
+- Branch name from `milestone_branch_template` (e.g., `dgs/checkout/v1.0-mvp`)
+- All phases in milestone commit to same branch
+- `complete-milestone` offers to merge milestone branch to main
+
+**Template variables:**
+
+| Variable | Available in | Description |
+|----------|--------------|-------------|
+| `{project}` | Both | Project slug from current_project (e.g., "checkout") |
+| `{phase}` | phase_branch_template | Zero-padded phase number (e.g., "03") |
+| `{slug}` | Both | Lowercase, hyphenated name |
+| `{milestone}` | milestone_branch_template | Milestone version (e.g., "v1.0") |
+
+**Checking the config:**
+
+Use `init execute-phase` which returns all config as JSON:
+```bash
+INIT=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" init execute-phase "1")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+# JSON output includes: branching_strategy, phase_branch_template, milestone_branch_template
+```
+
+Or use `state load` for the config values:
+```bash
+INIT=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" state load)
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+# Parse branching_strategy, phase_branch_template, milestone_branch_template from JSON
+```
+
+**Branch creation:**
+
+```bash
+# For phase strategy (code repos — product folder always uses main)
+if [ "$BRANCHING_STRATEGY" = "phase" ]; then
+  PHASE_SLUG=$(echo "$PHASE_NAME" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//')
+  BRANCH_NAME=$(echo "$PHASE_BRANCH_TEMPLATE" | sed "s/{project}/$PROJECT_SLUG/g" | sed "s/{phase}/$PADDED_PHASE/g" | sed "s/{slug}/$PHASE_SLUG/g")
+  # In code repos: fetch and checkout base branch first
+  git fetch origin "$BASE_BRANCH" 2>/dev/null || true
+  git checkout "$BASE_BRANCH"
+  git checkout -b "$BRANCH_NAME" 2>/dev/null || git checkout "$BRANCH_NAME"
+fi
+
+# For milestone strategy (code repos — product folder always uses main)
+if [ "$BRANCHING_STRATEGY" = "milestone" ]; then
+  MILESTONE_SLUG=$(echo "$MILESTONE_NAME" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//')
+  BRANCH_NAME=$(echo "$MILESTONE_BRANCH_TEMPLATE" | sed "s/{project}/$PROJECT_SLUG/g" | sed "s/{milestone}/$MILESTONE_VERSION/g" | sed "s/{slug}/$MILESTONE_SLUG/g")
+  # In code repos: fetch and checkout base branch first
+  git fetch origin "$BASE_BRANCH" 2>/dev/null || true
+  git checkout "$BASE_BRANCH"
+  git checkout -b "$BRANCH_NAME" 2>/dev/null || git checkout "$BRANCH_NAME"
+fi
+```
+
+**Merge options at complete-milestone:**
+
+| Option | Git command | Result |
+|--------|-------------|--------|
+| Squash merge (recommended) | `git merge --squash` | Single clean commit per branch |
+| Merge with history | `git merge --no-ff` | Preserves all individual commits |
+| Delete without merging | `git branch -D` | Discard branch work |
+| Keep branches | (none) | Manual handling later |
+
+Squash merge is recommended — keeps main branch history clean while preserving the full development history in the branch (until deleted).
+
+**Use cases:**
+
+| Strategy | Best for |
+|----------|----------|
+| `none` | Solo development, simple projects |
+| `phase` | Code review per phase, granular rollback, team collaboration |
+| `milestone` | Release branches, staging environments, PR per version |
+
+</branching_strategy_behavior>
+
+</planning_config>

package/deliver-great-systems/references/questioning.md

@@ -0,0 +1,162 @@
+<questioning_guide>
+
+Project initialization is dream extraction, not requirements gathering. You're helping the user discover and articulate what they want to build. This isn't a contract negotiation — it's collaborative thinking.
+
+<philosophy>
+
+**You are a thinking partner, not an interviewer.**
+
+The user often has a fuzzy idea. Your job is to help them sharpen it. Ask questions that make them think "oh, I hadn't considered that" or "yes, that's exactly what I mean."
+
+Don't interrogate. Collaborate. Don't follow a script. Follow the thread.
+
+</philosophy>
+
+<the_goal>
+
+By the end of questioning, you need enough clarity to write a PROJECT.md that downstream phases can act on:
+
+- **Research** needs: what domain to research, what the user already knows, what unknowns exist
+- **Requirements** needs: clear enough vision to scope v1 features
+- **Roadmap** needs: clear enough vision to decompose into phases, what "done" looks like
+- **plan-phase** needs: specific requirements to break into tasks, context for implementation choices
+- **execute-phase** needs: success criteria to verify against, the "why" behind requirements
+
+A vague PROJECT.md forces every downstream phase to guess. The cost compounds.
+
+</the_goal>
+
+<how_to_question>
+
+**Start open.** Let them dump their mental model. Don't interrupt with structure.
+
+**Follow energy.** Whatever they emphasized, dig into that. What excited them? What problem sparked this?
+
+**Challenge vagueness.** Never accept fuzzy answers. "Good" means what? "Users" means who? "Simple" means how?
+
+**Make the abstract concrete.** "Walk me through using this." "What does that actually look like?"
+
+**Clarify ambiguity.** "When you say Z, do you mean A or B?" "You mentioned X — tell me more."
+
+**Know when to stop.** When you understand what they want, why they want it, who it's for, and what done looks like — offer to proceed.
+
+</how_to_question>
+
+<question_types>
+
+Use these as inspiration, not a checklist. Pick what's relevant to the thread.
+
+**Motivation — why this exists:**
+- "What prompted this?"
+- "What are you doing today that this replaces?"
+- "What would you do if this existed?"
+
+**Concreteness — what it actually is:**
+- "Walk me through using this"
+- "You said X — what does that actually look like?"
+- "Give me an example"
+
+**Clarification — what they mean:**
+- "When you say Z, do you mean A or B?"
+- "You mentioned X — tell me more about that"
+
+**Success — how you'll know it's working:**
+- "How will you know this is working?"
+- "What does done look like?"
+
+</question_types>
+
+<using_askuserquestion>
+
+Use AskUserQuestion to help users think by presenting concrete options to react to.
+
+**Good options:**
+- Interpretations of what they might mean
+- Specific examples to confirm or deny
+- Concrete choices that reveal priorities
+
+**Bad options:**
+- Generic categories ("Technical", "Business", "Other")
+- Leading options that presume an answer
+- Too many options (2-4 is ideal)
+- Headers longer than 12 characters (hard limit — validation will reject them)
+
+**Example — vague answer:**
+User says "it should be fast"
+
+- header: "Fast"
+- question: "Fast how?"
+- options: ["Sub-second response", "Handles large datasets", "Quick to build", "Let me explain"]
+
+**Example — following a thread:**
+User mentions "frustrated with current tools"
+
+- header: "Frustration"
+- question: "What specifically frustrates you?"
+- options: ["Too many clicks", "Missing features", "Unreliable", "Let me explain"]
+
+**Tip for users — modifying an option:**
+Users who want a slightly modified version of an option can select "Other" and reference the option by number: `#1 but for finger joints only` or `#2 with pagination disabled`. This avoids retyping the full option text.
+
+</using_askuserquestion>
+
+<freeform_rule>
+
+**When the user wants to explain freely, STOP using AskUserQuestion.**
+
+If a user selects "Other" and their response signals they want to describe something in their own words (e.g., "let me describe it", "I'll explain", "something else", or any open-ended reply that isn't choosing/modifying an existing option), you MUST:
+
+1. **Ask your follow-up as plain text** — NOT via AskUserQuestion
+2. **Wait for them to type at the normal prompt**
+3. **Resume AskUserQuestion** only after processing their freeform response
+
+The same applies if YOU include a freeform-indicating option (like "Let me explain" or "Describe in detail") and the user selects it.
+
+**Wrong:** User says "let me describe it" → AskUserQuestion("What feature?", ["Feature A", "Feature B", "Describe in detail"])
+**Right:** User says "let me describe it" → "Go ahead — what are you thinking?"
+
+</freeform_rule>
+
+<context_checklist>
+
+Use this as a **background checklist**, not a conversation structure. Check these mentally as you go. If gaps remain, weave questions naturally.
+
+- [ ] What they're building (concrete enough to explain to a stranger)
+- [ ] Why it needs to exist (the problem or desire driving it)
+- [ ] Who it's for (even if just themselves)
+- [ ] What "done" looks like (observable outcomes)
+
+Four things. If they volunteer more, capture it.
+
+</context_checklist>
+
+<decision_gate>
+
+When you could write a clear PROJECT.md, offer to proceed:
+
+- header: "Ready?"
+- question: "I think I understand what you're after. Ready to create PROJECT.md?"
+- options:
+  - "Create PROJECT.md" — Let's move forward
+  - "Keep exploring" — I want to share more / ask me more
+
+If "Keep exploring" — ask what they want to add or identify gaps and probe naturally.
+
+Loop until "Create PROJECT.md" selected.
+
+</decision_gate>
+
+<anti_patterns>
+
+- **Checklist walking** — Going through domains regardless of what they said
+- **Canned questions** — "What's your core value?" "What's out of scope?" regardless of context
+- **Corporate speak** — "What are your success criteria?" "Who are your stakeholders?"
+- **Interrogation** — Firing questions without building on answers
+- **Rushing** — Minimizing questions to get to "the work"
+- **Shallow acceptance** — Taking vague answers without probing
+- **Premature constraints** — Asking about tech stack before understanding the idea
+- **User skills** — NEVER ask about user's technical experience. Claude builds.
+
+</anti_patterns>
+
+</questioning_guide>

package/deliver-great-systems/references/spec-review-loop.md

@@ -0,0 +1,177 @@
+# Spec Review Loop Reference
+
+## Overview
+The review loop sends the spec to external LLM reviewers (OpenAI, Gemini) and processes their feedback autonomously until convergence. This reference is loaded by the write-spec workflow and provides all the details Claude needs to execute the review loop.
+
+## Loading Review Configuration
+
+```bash
+REVIEW_CONFIG=$(node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs review-config)
+```
+
+Parse JSON: `{ reviewers: { openai: { api_key, model }, gemini: { api_key, model } }, max_rounds, has_any_key }`.
+
+If `has_any_key = false`: warn "No review API keys configured. Edit review-keys.json in your planning root to add OpenAI or Gemini keys. Skipping review." and exit the review loop.
+
+## API Call Patterns
+
+### OpenAI Chat Completions
+
+Write the JSON payload to a temp file to avoid shell quoting issues with markdown content, then use `curl -d @file`:
+
+```bash
+python3 -c "
+import sys, json
+spec = sys.stdin.read()
+payload = {
+    'model': '$MODEL',
+    'messages': [
+        {'role': 'system', 'content': 'You are a senior product manager reviewing a PRD spec. Provide specific, actionable feedback organized by section. For each item, indicate severity: [critical], [important], or [suggestion]. If the spec is solid, respond with only: LGTM - no changes needed.'},
+        {'role': 'user', 'content': 'Review this PRD spec:\n\n' + spec}
+    ],
+    'temperature': 0.3
+}
+json.dump(payload, open('/tmp/dgs-review-openai.json', 'w'))
+" < "$SPEC_FILE"
+
+curl -s https://api.openai.com/v1/chat/completions \
+  -H "Authorization: Bearer $OPENAI_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d @/tmp/dgs-review-openai.json
+
+rm -f /tmp/dgs-review-openai.json
+```
+
+Parse response: extract `choices[0].message.content` for feedback, `usage.prompt_tokens` and `usage.completion_tokens` for token tracking.
+
+### Google Gemini
+
+Write the JSON payload to a temp file to avoid shell quoting issues with markdown content, then use `curl -d @file`:
+
+```bash
+python3 -c "
+import sys, json
+spec = sys.stdin.read()
+payload = {
+    'contents': [{'parts': [{'text': 'You are a senior product manager reviewing a PRD spec. Provide specific, actionable feedback organized by section. For each item, indicate severity: [critical], [important], or [suggestion]. If the spec is solid, respond with only: LGTM - no changes needed.\n\nReview this PRD spec:\n\n' + spec}]}],
+    'generationConfig': {'temperature': 0.3}
+}
+json.dump(payload, open('/tmp/dgs-review-gemini.json', 'w'))
+" < "$SPEC_FILE"
+
+curl -s "https://generativelanguage.googleapis.com/v1beta/models/$MODEL:generateContent?key=$GEMINI_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d @/tmp/dgs-review-gemini.json
+
+rm -f /tmp/dgs-review-gemini.json
+```
+
+Parse response: extract `candidates[0].content.parts[0].text` for feedback, `usageMetadata.promptTokenCount` and `usageMetadata.candidatesTokenCount` for token tracking.
+
+## Sending Reviews in Parallel
+
+Both API calls should be made concurrently. Use two Bash tool calls issued in parallel. If one fails, the other's result is still usable.
+
+## Error Handling & Retry
+
+For each reviewer:
+
+1. First attempt: make API call.
+2. If HTTP error or malformed response: retry once after 2 seconds.
+3. If retry also fails: mark reviewer as `failed` for this round.
+4. If both reviewers fail in a round: exit loop, warn user "Both reviewers unavailable. Review skipped."
+5. If one reviewer fails: continue with the other reviewer's feedback only.
+
+## Feedback Processing
+
+### Parse Feedback Items
+
+Extract individual feedback items from each reviewer's response. Each item has:
+
+- `section`: which PRD section it targets
+- `severity`: critical, important, or suggestion
+- `feedback`: the actual feedback text
+- `reviewer`: openai or gemini
+
+### Auto-Reject Non-Goal Contradictions (SPEC-04)
+
+For each feedback item, check if it contradicts a stated Non-Goal:
+
+1. Read the `## Non-Goals` section from the spec.
+2. If a feedback item suggests adding something explicitly listed as a Non-Goal, reject it.
+3. Disposition: `rejected-non-goal` with reason "Contradicts Non-Goal: [quoted non-goal]".
+
+### Apply Accepted Feedback
+
+For accepted feedback items:
+
+1. Claude reads each item and decides whether to apply it by modifying the spec.
+2. If the change is warranted: update the relevant section in the spec body.
+3. Disposition: `accepted` with brief description of change made.
+4. If the feedback is already addressed or too vague: disposition `no-action` with reason.
+
+### Convergence Detection (SPEC-06)
+
+Track rejected items across rounds. If an item (or substantially similar item) is rejected in 2+ consecutive rounds:
+
+1. Move the item's core concern to the `## Open Questions` section.
+2. Tag it: "From review: [summarized concern]"
+3. Disposition: `moved-to-open-questions`.
+
+This prevents infinite loops where reviewers keep suggesting the same rejected change.
+
+## Exit Conditions (SPEC-05)
+
+After each round, check:
+
+1. **No changes applied**: all feedback items were either rejected, already addressed, or too vague. EXIT.
+2. **Green-only**: all reviewers responded with "LGTM" or equivalent (no actionable feedback). EXIT.
+3. **Max rounds reached**: round number >= max_rounds from config. EXIT.
+
+If none met: start next round with the updated spec.
+
+## Review History Format (SPEC-07)
+
+After the loop completes, append Review History to the spec:
+
+```markdown
+### Round 1
+**Reviewers:** OpenAI (gpt-5-mini), Gemini (gemini-2.5-flash)
+**Changes applied:** 3 | **Rejected:** 1 (non-goal) | **No action:** 2
+
+| # | Section | Severity | Disposition | Detail |
+|---|---------|----------|-------------|--------|
+| 1 | Requirements | critical | accepted | Added error handling requirement to P0 |
+| 2 | Non-Goals | important | rejected-non-goal | Contradicts "No dark mode" |
+| 3 | User Stories | suggestion | accepted | Added admin user story |
+
+### Round 2
+...
+```
+
+Append via:
+
+```bash
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs specs append-review --id "$SPEC_ID" --entry "$HISTORY_MD"
+```
+
+## Token & Cost Tracking (SPEC-14)
+
+Track cumulative tokens across all rounds:
+
+- `total_prompt_tokens`: sum of all prompt tokens
+- `total_completion_tokens`: sum of all completion tokens
+- Per reviewer: `openai_tokens`, `gemini_tokens`
+
+Approximate cost calculation (use current API pricing as estimates):
+
+- OpenAI gpt-5-mini: ~$2.50/1M input, ~$10.00/1M output
+- Gemini gemini-2.5-flash: ~$0.075/1M input, ~$0.30/1M output
+
+Display at end of review loop:
+
+```
+Review complete (N rounds).
+Tokens: OpenAI [X prompt + Y completion] | Gemini [X prompt + Y completion]
+Estimated cost: ~$X.XX
+```