@ktpartners/dgs-platform 2.6.2

package/deliver-great-systems/templates/verification-report.md

@@ -0,0 +1,324 @@
+# Verification Report Template
+
+Template for `phases/XX-name/{phase_num}-VERIFICATION.md` (in planning root) — phase goal verification results.
+
+> **Layout-agnostic:** Workflows resolve the phase directory path via `${phase_dir}` from init output. Works in both standard and root layouts.
+
+---
+
+## File Template
+
+```markdown
+---
+phase: XX-name
+verified: YYYY-MM-DDTHH:MM:SSZ
+status: passed | gaps_found | human_needed
+score: N/M must-haves verified
+---
+
+# Phase {X}: {Name} Verification Report
+
+**Phase Goal:** {goal from ROADMAP.md}
+**Verified:** {timestamp}
+**Status:** {passed | gaps_found | human_needed}
+
+## Goal Achievement
+
+### Observable Truths
+
+| # | Truth | Status | Evidence |
+|---|-------|--------|----------|
+| 1 | {truth from must_haves} | ✓ VERIFIED | {what confirmed it} |
+| 2 | {truth from must_haves} | ✗ FAILED | {what's wrong} |
+| 3 | {truth from must_haves} | ? UNCERTAIN | {why can't verify} |
+
+**Score:** {N}/{M} truths verified
+
+### Required Artifacts
+
+| Artifact | Expected | Status | Details |
+|----------|----------|--------|---------|
+| `src/components/Chat.tsx` | Message list component | ✓ EXISTS + SUBSTANTIVE | Exports ChatList, renders Message[], no stubs |
+| `src/app/api/chat/route.ts` | Message CRUD | ✗ STUB | File exists but POST returns placeholder |
+| `prisma/schema.prisma` | Message model | ✓ EXISTS + SUBSTANTIVE | Model defined with all fields |
+
+**Artifacts:** {N}/{M} verified
+
+### Key Link Verification
+
+| From | To | Via | Status | Details |
+|------|----|----|--------|---------|
+| Chat.tsx | /api/chat | fetch in useEffect | ✓ WIRED | Line 23: `fetch('/api/chat')` with response handling |
+| ChatInput | /api/chat POST | onSubmit handler | ✗ NOT WIRED | onSubmit only calls console.log |
+| /api/chat POST | database | prisma.message.create | ✗ NOT WIRED | Returns hardcoded response, no DB call |
+
+**Wiring:** {N}/{M} connections verified
+
+## Requirements Coverage
+
+| Requirement | Status | Blocking Issue |
+|-------------|--------|----------------|
+| {REQ-01}: {description} | ✓ SATISFIED | - |
+| {REQ-02}: {description} | ✗ BLOCKED | API route is stub |
+| {REQ-03}: {description} | ? NEEDS HUMAN | Can't verify WebSocket programmatically |
+
+**Coverage:** {N}/{M} requirements satisfied
+
+## Anti-Patterns Found
+
+| File | Line | Pattern | Severity | Impact |
+|------|------|---------|----------|--------|
+| src/app/api/chat/route.ts | 12 | `// TODO: implement` | ⚠️ Warning | Indicates incomplete |
+| src/components/Chat.tsx | 45 | `return <div>Placeholder</div>` | 🛑 Blocker | Renders no content |
+| src/hooks/useChat.ts | - | File missing | 🛑 Blocker | Expected hook doesn't exist |
+
+**Anti-patterns:** {N} found ({blockers} blockers, {warnings} warnings)
+
+## Human Verification Required
+
+{If no human verification needed:}
+None — all verifiable items checked programmatically.
+
+{If human verification needed:}
+
+### 1. {Test Name}
+**Test:** {What to do}
+**Expected:** {What should happen}
+**Why human:** {Why can't verify programmatically}
+
+### 2. {Test Name}
+**Test:** {What to do}
+**Expected:** {What should happen}
+**Why human:** {Why can't verify programmatically}
+
+## Gaps Summary
+
+{If no gaps:}
+**No gaps found.** Phase goal achieved. Ready to proceed.
+
+{If gaps found:}
+
+### Critical Gaps (Block Progress)
+
+1. **{Gap name}**
+   - Missing: {what's missing}
+   - Impact: {why this blocks the goal}
+   - Fix: {what needs to happen}
+
+2. **{Gap name}**
+   - Missing: {what's missing}
+   - Impact: {why this blocks the goal}
+   - Fix: {what needs to happen}
+
+### Non-Critical Gaps (Can Defer)
+
+1. **{Gap name}**
+   - Issue: {what's wrong}
+   - Impact: {limited impact because...}
+   - Recommendation: {fix now or defer}
+
+## Recommended Fix Plans
+
+{If gaps found, generate fix plan recommendations:}
+
+### {phase}-{next}-PLAN.md: {Fix Name}
+
+**Objective:** {What this fixes}
+
+**Tasks:**
+1. {Task to fix gap 1}
+2. {Task to fix gap 2}
+3. {Verification task}
+
+**Estimated scope:** {Small / Medium}
+
+---
+
+### {phase}-{next+1}-PLAN.md: {Fix Name}
+
+**Objective:** {What this fixes}
+
+**Tasks:**
+1. {Task}
+2. {Task}
+
+**Estimated scope:** {Small / Medium}
+
+---
+
+## Verification Metadata
+
+**Verification approach:** Goal-backward (derived from phase goal)
+**Must-haves source:** {PLAN.md frontmatter | derived from ROADMAP.md goal}
+**Automated checks:** {N} passed, {M} failed
+**Human checks required:** {N}
+**Total verification time:** {duration}
+
+---
+*Verified: {timestamp}*
+*Verifier: Claude (subagent)*
+```
+
+---
+
+## Guidelines
+
+**Status values:**
+- `passed` — All must-haves verified, no blockers
+- `gaps_found` — One or more critical gaps found
+- `human_needed` — Automated checks pass but human verification required
+
+**Evidence types:**
+- For EXISTS: "File at path, exports X"
+- For SUBSTANTIVE: "N lines, has patterns X, Y, Z"
+- For WIRED: "Line N: code that connects A to B"
+- For FAILED: "Missing because X" or "Stub because Y"
+
+**Severity levels:**
+- 🛑 Blocker: Prevents goal achievement, must fix
+- ⚠️ Warning: Indicates incomplete but doesn't block
+- ℹ️ Info: Notable but not problematic
+
+**Fix plan generation:**
+- Only generate if gaps_found
+- Group related fixes into single plans
+- Keep to 2-3 tasks per plan
+- Include verification task in each plan
+
+---
+
+## Example
+
+```markdown
+---
+phase: 03-chat
+verified: 2025-01-15T14:30:00Z
+status: gaps_found
+score: 2/5 must-haves verified
+---
+
+# Phase 3: Chat Interface Verification Report
+
+**Phase Goal:** Working chat interface where users can send and receive messages
+**Verified:** 2025-01-15T14:30:00Z
+**Status:** gaps_found
+
+## Goal Achievement
+
+### Observable Truths
+
+| # | Truth | Status | Evidence |
+|---|-------|--------|----------|
+| 1 | User can see existing messages | ✗ FAILED | Component renders placeholder, not message data |
+| 2 | User can type a message | ✓ VERIFIED | Input field exists with onChange handler |
+| 3 | User can send a message | ✗ FAILED | onSubmit handler is console.log only |
+| 4 | Sent message appears in list | ✗ FAILED | No state update after send |
+| 5 | Messages persist across refresh | ? UNCERTAIN | Can't verify - send doesn't work |
+
+**Score:** 1/5 truths verified
+
+### Required Artifacts
+
+| Artifact | Expected | Status | Details |
+|----------|----------|--------|---------|
+| `src/components/Chat.tsx` | Message list component | ✗ STUB | Returns `<div>Chat will be here</div>` |
+| `src/components/ChatInput.tsx` | Message input | ✓ EXISTS + SUBSTANTIVE | Form with input, submit button, handlers |
+| `src/app/api/chat/route.ts` | Message CRUD | ✗ STUB | GET returns [], POST returns { ok: true } |
+| `prisma/schema.prisma` | Message model | ✓ EXISTS + SUBSTANTIVE | Message model with id, content, userId, createdAt |
+
+**Artifacts:** 2/4 verified
+
+### Key Link Verification
+
+| From | To | Via | Status | Details |
+|------|----|----|--------|---------|
+| Chat.tsx | /api/chat GET | fetch | ✗ NOT WIRED | No fetch call in component |
+| ChatInput | /api/chat POST | onSubmit | ✗ NOT WIRED | Handler only logs, doesn't fetch |
+| /api/chat GET | database | prisma.message.findMany | ✗ NOT WIRED | Returns hardcoded [] |
+| /api/chat POST | database | prisma.message.create | ✗ NOT WIRED | Returns { ok: true }, no DB call |
+
+**Wiring:** 0/4 connections verified
+
+## Requirements Coverage
+
+| Requirement | Status | Blocking Issue |
+|-------------|--------|----------------|
+| CHAT-01: User can send message | ✗ BLOCKED | API POST is stub |
+| CHAT-02: User can view messages | ✗ BLOCKED | Component is placeholder |
+| CHAT-03: Messages persist | ✗ BLOCKED | No database integration |
+
+**Coverage:** 0/3 requirements satisfied
+
+## Anti-Patterns Found
+
+| File | Line | Pattern | Severity | Impact |
+|------|------|---------|----------|--------|
+| src/components/Chat.tsx | 8 | `<div>Chat will be here</div>` | 🛑 Blocker | No actual content |
+| src/app/api/chat/route.ts | 5 | `return Response.json([])` | 🛑 Blocker | Hardcoded empty |
+| src/app/api/chat/route.ts | 12 | `// TODO: save to database` | ⚠️ Warning | Incomplete |
+
+**Anti-patterns:** 3 found (2 blockers, 1 warning)
+
+## Human Verification Required
+
+None needed until automated gaps are fixed.
+
+## Gaps Summary
+
+### Critical Gaps (Block Progress)
+
+1. **Chat component is placeholder**
+   - Missing: Actual message list rendering
+   - Impact: Users see "Chat will be here" instead of messages
+   - Fix: Implement Chat.tsx to fetch and render messages
+
+2. **API routes are stubs**
+   - Missing: Database integration in GET and POST
+   - Impact: No data persistence, no real functionality
+   - Fix: Wire prisma calls in route handlers
+
+3. **No wiring between frontend and backend**
+   - Missing: fetch calls in components
+   - Impact: Even if API worked, UI wouldn't call it
+   - Fix: Add useEffect fetch in Chat, onSubmit fetch in ChatInput
+
+## Recommended Fix Plans
+
+### 03-04-PLAN.md: Implement Chat API
+
+**Objective:** Wire API routes to database
+
+**Tasks:**
+1. Implement GET /api/chat with prisma.message.findMany
+2. Implement POST /api/chat with prisma.message.create
+3. Verify: API returns real data, POST creates records
+
+**Estimated scope:** Small
+
+---
+
+### 03-05-PLAN.md: Implement Chat UI
+
+**Objective:** Wire Chat component to API
+
+**Tasks:**
+1. Implement Chat.tsx with useEffect fetch and message rendering
+2. Wire ChatInput onSubmit to POST /api/chat
+3. Verify: Messages display, new messages appear after send
+
+**Estimated scope:** Small
+
+---
+
+## Verification Metadata
+
+**Verification approach:** Goal-backward (derived from phase goal)
+**Must-haves source:** 03-01-PLAN.md frontmatter
+**Automated checks:** 2 passed, 8 failed
+**Human checks required:** 0 (blocked by automated failures)
+**Total verification time:** 2 min
+
+---
+*Verified: 2025-01-15T14:30:00Z*
+*Verifier: Claude (subagent)*
+```

package/deliver-great-systems/workflows/add-doc.md

@@ -0,0 +1,151 @@
+<purpose>
+Add a supporting document (PDF, image, spreadsheet, etc.) to a scoped docs/ directory. Handles source detection (local file or conversation attachment), scope inference, file size validation, duplicate checking, document storage with text extraction, git commit, and markdown link output. URLs are not supported.
+</purpose>
+
+<context_tier>lite</context_tier>
+
+<required_reading>
+Read all files referenced by the invoking prompt's execution_context before starting.
+</required_reading>
+
+<process>
+
+<step name="load_context" priority="first">
+Load project context via tier system:
+
+```bash
+TIER_FILES=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" context load-tier lite --raw 2>/dev/null)
+```
+
+Use `TIER_FILES` JSON `files` array for project context (PROJECT.md, STATE.md, config.json).
+</step>
+
+<step name="detect_source">
+Determine the document source from `$ARGUMENTS` and conversation context.
+
+**Local file path:**
+- If `$ARGUMENTS` contains what looks like a file path, verify it exists:
+  ```bash
+  ls "$source_path" 2>/dev/null
+  ```
+- If file exists: set `source_path` to that path
+
+**Conversation attachment:**
+- If user provided a conversation attachment (file pasted or dragged into chat): save it to a temp location, set `source_path` to the saved path
+
+**URL detected:**
+- If `$ARGUMENTS` contains a URL (http:// or https://): output error and stop:
+  ```
+  URL fetching is not supported. Please provide a local file path.
+  ```
+
+**Neither:**
+- If no file path and no attachment detected: prompt with AskUserQuestion:
+  - question: "Provide a file path or paste/attach a file"
+- Process the response (file path or attachment)
+</step>
+
+<step name="determine_scope">
+Determine the target scope for the document.
+
+**From arguments:**
+- Parse `$ARGUMENTS` for `--scope <product|idea|spec>` and `--scope-id <id>`
+- If both provided, use them directly
+
+**From conversation context (if not in arguments):**
+- If currently discussing an idea (e.g., recent /dgs commands touched an idea file): set scope = `idea`, infer scope_id from the idea slug
+- If currently discussing a spec: set scope = `spec`, infer scope_id from the spec slug
+- Otherwise: default to `product` scope
+
+**Missing scope-id:**
+- If scope is `idea` or `spec` but no scope-id available: prompt with AskUserQuestion:
+  - question: "Which {scope} should this document be attached to? (provide the slug or ID)"
+
+**Validate scope target exists:**
+- For `product`: verify planning directory exists
+- For `idea`: verify the idea file exists in `ideas/` (relative from planning root)
+- For `spec`: verify the spec directory exists in `specs/` (relative from planning root)
+
+If scope target does not exist: output error "Scope target '{scope}/{scope_id}' not found." and stop.
+</step>
+
+<step name="check_size">
+Validate file size does not exceed 10MB limit.
+
+```bash
+FILE_SIZE=$(stat -f%z "$source_path" 2>/dev/null || stat -c%s "$source_path" 2>/dev/null)
+```
+
+If file size > 10485760 bytes (10MB):
+- Calculate actual size in MB: `$(( FILE_SIZE / 1048576 ))`
+- Output error and stop:
+  ```
+  File exceeds 10MB limit ({actual_size}MB). Document not added.
+  ```
+</step>
+
+<step name="check_duplicate">
+Check for an existing document with the same slug in the target scope.
+
+Derive slug from the source filename (slugified version preserving extension).
+
+```bash
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs docs check-duplicate --scope "$scope" --scope-id "$scope_id" --slug "$slug"
+```
+
+Parse JSON result. If `exists: true`:
+- Ask user with AskUserQuestion:
+  - question: "A document named '{slug}' already exists in {scope}. Overwrite? (yes/no)"
+- If user says no: output "Cancelled." and stop
+- If user says yes: continue (overwrite will happen in next step)
+</step>
+
+<step name="add_document">
+Add the document via dgs-tools CLI.
+
+```bash
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs docs add --source "$source_path" --scope "$scope" --scope-id "$scope_id"
+```
+
+Parse the JSON result for:
+- `slug`: the slugified filename
+- `extraction_status`: success, failed, or skipped
+- `relative_link`: markdown-formatted relative link to the document
+- `files_created`: list of all files created/modified (document, sidecars, INDEX.md)
+</step>
+
+<step name="git_commit">
+Commit the document and all sidecars.
+
+Per CONTEXT.md: one file per invocation, each gets its own commit. Commit the document file + any sidecars (.extracted.txt, .summary.txt) + INDEX.md.
+
+```bash
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "docs: add ${slug} to ${scope}" --files <all files from files_created list>
+```
+</step>
+
+<step name="confirm">
+Output the result in this format:
+
+```
+Document added: {original_name} -> {slug}
+Scope: {scope}{scope_id ? '/' + scope_id : ''}
+Extraction: {extraction_status}
+
+Markdown link: {relative_link}
+```
+
+The markdown link line enables easy copy-paste into ideas and specs.
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] Document source detected (local file or attachment; URLs rejected)
+- [ ] Scope determined (from args, context, or user prompt)
+- [ ] File size validated (under 10MB)
+- [ ] Duplicate check performed with user confirmation if needed
+- [ ] Document stored with extraction sidecars via dgs-tools
+- [ ] Git commit created for document + sidecars + INDEX.md + .names.json
+- [ ] Markdown link output displayed for copy-paste
+</success_criteria>

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

@@ -0,0 +1,96 @@
+<purpose>
+Capture a new idea into the DGS ideas system. Two modes: interactive (prompts for each field sequentially) and auto (Claude extracts from freeform text). Enables quick idea capture without breaking flow.
+</purpose>
+
+<context_tier>lite</context_tier>
+
+<required_reading>
+Read all files referenced by the invoking prompt's execution_context before starting.
+</required_reading>
+
+<process>
+
+<step name="parse_arguments">
+Check `$ARGUMENTS` for the `--auto` flag.
+
+- If `--auto "some freeform text"` detected: set `mode = auto`, extract the freeform text after `--auto`
+- Otherwise: set `mode = interactive`
+
+Examples:
+- `/dgs:add-idea` → interactive mode
+- `/dgs:add-idea --auto "We should auto-review PRs when specs change"` → auto mode
+</step>
+
+<step name="init_context">
+```bash
+INIT=$(node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs init milestone-op)
+TIER_FILES=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" context load-tier lite --raw 2>/dev/null)
+```
+
+Extract from init JSON: `project_root`, `commit_docs`.
+Use `TIER_FILES` JSON `files` array for project context (PROJECT.md, STATE.md, config.json).
+</step>
+
+<step name="ensure_directories">
+```bash
+mkdir -p ${project_root}/ideas/pending ${project_root}/ideas/done ${project_root}/ideas/rejected
+```
+</step>
+
+<step name="interactive_capture" condition="mode = interactive">
+Prompt one question at a time using AskUserQuestion:
+
+1. **Title**: "What's the idea?" (required, 3-10 words preferred)
+2. **Body**: "Describe the problem or opportunity" (required, freeform)
+3. **Tags**: "Any tags? (comma-separated, or skip)" (optional, can be skipped)
+
+All three fields are prompted. Tags can be skipped by the user.
+
+Set variables:
+- `title` = user's response to prompt 1
+- `body` = user's response to prompt 2
+- `tags` = user's response to prompt 3 (or empty string if skipped)
+</step>
+
+<step name="auto_capture" condition="mode = auto">
+Claude reads the freeform text and intelligently extracts:
+
+- `title`: concise 3-10 word title capturing the core idea
+- `body`: the problem or opportunity described, expanded if needed for clarity
+- `tags`: any relevant tags inferred from the text (comma-separated string)
+
+No interactive prompts in auto mode.
+</step>
+
+<step name="create_idea">
+```bash
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs ideas create --title "$title" --body "$body" --tags "$tags"
+```
+
+Parse the JSON result to get `id`, `filename`, `path`.
+</step>
+
+<step name="git_commit">
+```bash
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "ideas: add #${id} - ${title}" --files ${project_root}/ideas/pending/${filename} ${project_root}/ideas/manifest.json
+```
+</step>
+
+<step name="confirm">
+Minimal confirmation only. Output exactly:
+
+```
+Idea #${id} created.
+```
+
+Nothing else -- no file path, no tags display, no next steps.
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] Idea file exists in `ideas/pending/` with correct frontmatter
+- [ ] Manifest updated with incremented next_id
+- [ ] Git commit created
+- [ ] Minimal confirmation displayed
+</success_criteria>

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

@@ -0,0 +1,120 @@
+<purpose>
+Add a new integer phase to the end of the current milestone in the roadmap. Automatically calculates next phase number, creates phase directory, and updates roadmap structure.
+</purpose>
+
+<context_tier>planning</context_tier>
+
+<required_reading>
+Read all files referenced by the invoking prompt's execution_context before starting.
+</required_reading>
+
+<process>
+
+<step name="parse_arguments">
+Parse the command arguments:
+- All arguments become the phase description
+- Example: `/dgs:add-phase Add authentication` → description = "Add authentication"
+- Example: `/dgs:add-phase Fix critical performance issues` → description = "Fix critical performance issues"
+
+If no arguments provided:
+
+```
+ERROR: Phase description required
+Usage: /dgs:add-phase <description>
+Example: /dgs:add-phase Add authentication system
+```
+
+Exit.
+</step>
+
+<step name="init_context">
+Load phase operation context:
+
+```bash
+INIT=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" init phase-op "0")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+```
+
+Load planning-tier context files:
+
+```bash
+TIER_FILES=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" context load-tier planning --raw 2>/dev/null)
+```
+
+Check `roadmap_exists` from init JSON. If false:
+```
+ERROR: No roadmap found (${roadmap_path})
+Run /dgs:new-project to initialize.
+```
+Exit.
+</step>
+
+<step name="add_phase">
+**Delegate the phase addition to dgs-tools:**
+
+```bash
+RESULT=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" phase add "${description}")
+```
+
+The CLI handles:
+- Finding the highest existing integer phase number
+- Calculating next phase number (max + 1)
+- Generating slug from description
+- Creating the phase directory (`${phases_dir}/{NN}-{slug}/`)
+- Inserting the phase entry into ROADMAP.md with Goal, Depends on, and Plans sections
+
+Extract from result: `phase_number`, `padded`, `name`, `slug`, `directory`.
+</step>
+
+<step name="update_project_state">
+Update STATE.md to reflect the new phase:
+
+1. Read STATE.md (via `${state_path}` from init)
+2. Under "## Accumulated Context" → "### Roadmap Evolution" add entry:
+   ```
+   - Phase {N} added: {description}
+   ```
+
+If "Roadmap Evolution" section doesn't exist, create it.
+</step>
+
+<step name="completion">
+Present completion summary:
+
+```
+Phase {N} added to current milestone:
+- Description: {description}
+- Directory: ${phases_dir}/{phase-num}-{slug}/
+- Status: Not planned yet
+
+Roadmap updated: ${roadmap_path}
+
+---
+
+## ▶ Next Up
+
+**Phase {N}: {description}**
+
+`/dgs:plan-phase {N}`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- `/dgs:add-phase <description>` — add another phase
+- Review roadmap
+
+---
+```
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] `dgs-tools phase add` executed successfully
+- [ ] Phase directory created
+- [ ] Roadmap updated with new phase entry
+- [ ] STATE.md updated with roadmap evolution note
+- [ ] User informed of next steps
+</success_criteria>