@ktpartners/dgs-platform 2.6.2

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

@@ -0,0 +1,325 @@
+<purpose>
+Subagent-driven research workflow that investigates an idea's feasibility and technical landscape across five adaptive dimensions. Claude acts as an analyst -- purposeful and efficient, adapting depth to what the idea actually needs rather than running a checklist.
+
+Produces a structured research document at `${project_root}/docs/ideas/pending/{slug}-research.md` and appends a Research Log entry to the idea file. Commits both files together and suggests the next step based on findings.
+
+When re-researching a previously-researched idea, the document is overwritten with a "Changes from Prior Research" section highlighting what shifted. Each re-research appends a fresh Research Log entry.
+</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="initialize" priority="first">
+Load planning context:
+
+```bash
+INIT=$(node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs init milestone-op)
+```
+
+Extract: `project_root` as needed by the workflow.
+
+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)
+```
+</step>
+
+<step name="parse_arguments">
+Parse `$ARGUMENTS` for an idea ID.
+
+- First positional argument: treat as idea ID (e.g., `/dgs:research-idea 5` -> id=5)
+- Named flag: `--id N` (e.g., `/dgs:research-idea --id 5` -> id=5)
+
+If no ID provided, list pending ideas and prompt for selection:
+
+```bash
+PENDING=$(node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs ideas list --state pending --raw)
+```
+
+Parse the JSON `ideas` array.
+
+**If empty:**
+```
+No pending ideas to research. Run /dgs:add-idea to capture one.
+```
+Exit workflow.
+
+**If ideas exist:** Display them as a numbered list showing ID, title, and tags. Ask the user which idea they would like to research and extract the selected idea's ID.
+</step>
+
+<step name="load_idea">
+Load the full idea content by ID:
+
+```bash
+LIST=$(node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs ideas list --raw)
+```
+
+Find the idea in the JSON by matching `id`. If not found:
+```
+Idea #${id} not found.
+```
+Exit workflow.
+
+Read the idea file directly using the `path` from the list result to get the full content including Discussion Log, Research Log, Notes, and body.
+
+Set variables from the parsed content:
+- `id` -- idea ID
+- `title` -- idea title
+- `body` -- idea body/problem statement
+- `tags` -- tags array
+- `notes` -- Notes section content (if any)
+- `state` -- current state (pending, done, rejected)
+- `filename` -- file name
+- `path` -- file path
+- `discussionLog` -- Discussion Log section content (if any)
+- `researchLog` -- Research Log section content (if any)
+
+Also check for prior research document:
+```bash
+# Derive slug from filename (strip id prefix and .md suffix)
+SLUG=$(echo "${filename}" | sed 's/^[0-9]*-//' | sed 's/\.md$//')
+RESEARCH_DOC="${project_root}/docs/ideas/pending/${SLUG}-research.md"
+```
+If the research document file exists, read it for prior research context.
+
+**Load idea supporting documents:**
+
+Derive the idea's docs directory path from the idea's file path:
+```bash
+IDEA_DIR=$(dirname "${path}")
+IDEA_DOCS_DIR="${IDEA_DIR}/docs"
+```
+
+If a flat structure is used (ideas stored as files, not directories), derive from the filename:
+```bash
+IDEA_DOCS_DIR="${project_root}/docs/ideas/pending/${SLUG}"
+```
+
+Check both paths. Use whichever exists.
+
+If the docs/ directory exists, list its contents:
+```bash
+ls "${IDEA_DOCS_DIR}/" 2>/dev/null
+```
+
+For each file found, apply the standard docs/ loading pattern:
+- **Text files** (.md, .txt, .json, .yaml, .yml): Read using the Read tool.
+- **Image files** (.png, .jpg, .jpeg, .gif, .svg, .webp): Read using the Read tool directly for multimodal context. Cap at 5 images per idea.
+- **PDF files** (.pdf): Prefer .txt sidecar (same directory, same basename with .txt extension). If sidecar exists, read it. If no sidecar, read up to 5 pages via Read tool with `pages` parameter.
+- **Other files**: Skip silently.
+
+If the docs/ directory does not exist: silent skip -- no docs is normal, do not mention it.
+If any file is unreadable: skip silently -- do not mention files that cannot be read.
+
+Store loaded docs content as `ideaDocs` for use in the research.
+
+Also check for REPOS.md:
+```bash
+cat ${project_root}/REPOS.md 2>/dev/null
+```
+If REPOS.md exists and has entries, this is a multi-repo project -- research should be partitioned by repo where relevant.
+</step>
+
+<step name="research_context">
+Assess the idea and decide research strategy:
+
+1. **Announce focus**: Print one line explaining which dimensions matter most for this idea and why. E.g.: "Focusing on landscape survey and codebase analysis -- this idea involves integrating with existing patterns."
+
+2. **Read Discussion Log** if present -- use discussion insights (refined problem, approach, open questions) to guide research focus areas.
+
+3. **Read prior research** if present -- note what was found before. On re-research, Claude will overwrite the document but should note what changed.
+
+4. **Read supporting documents** if `ideaDocs` is not empty -- review loaded text files, diagrams, and other supporting materials. These may reveal additional context about the idea's scope, architecture requirements, or prior art that inform the research focus areas.
+
+5. **Determine repo scope**: If REPOS.md exists, identify which repos are relevant to this idea. If no REPOS.md, treat as single-repo research.
+</step>
+
+<step name="web_search">
+**Dimension 1: Web Search**
+
+Announce: "Searching web for prior art and technical landscape..."
+
+Use WebSearch and WebFetch to investigate:
+- How others have solved similar problems
+- Existing libraries, tools, or frameworks relevant to the idea
+- Common patterns and anti-patterns
+- Recent discussions or blog posts
+
+Adapt depth to what the idea needs -- a well-understood problem gets a quick scan, a novel idea gets broader exploration. If web search yields little, note the gap and move on.
+
+Web search is best-effort -- search what's findable, note gaps, move on. Don't burn time on thin topics.
+</step>
+
+<step name="codebase_analysis">
+**Dimension 2: Codebase Analysis**
+
+Announce: "Analyzing codebase for related implementations..."
+
+Use Grep and Glob to examine:
+- Existing code that relates to the idea's domain
+- Patterns already established that would apply
+- Potential conflicts or integration points
+- Code that would need to change
+
+For multi-repo projects: analyze each relevant repo separately, noting repo-specific patterns and concerns.
+</step>
+
+<step name="landscape_survey">
+**Dimension 3: Landscape Survey**
+
+Announce: "Surveying technical landscape..."
+
+Build comparison information for relevant tools/libraries/approaches:
+- For obvious choices (one clear winner): brief verdict with reasoning
+- For genuine tradeoffs: table with pros, cons, license, maintenance status, compatibility
+- Per repo stack for multi-repo projects
+
+Recommend when clear -- strong recommendation when one option is clearly better, present options neutrally when it's genuinely a toss-up.
+</step>
+
+<step name="approaches">
+**Dimension 4: Approaches & Patterns**
+
+Announce: "Identifying approaches and patterns..."
+
+Identify how similar problems have been solved:
+- Architectural patterns that apply
+- Implementation strategies
+- Sequencing (what to build first)
+- What to avoid and why
+</step>
+
+<step name="feasibility">
+**Dimension 5: Feasibility Assessment**
+
+Announce: "Assessing feasibility..."
+
+Assess:
+- **Stack fit**: How well does this fit the existing technology stack?
+- **Effort estimate**: T-shirt size (S/M/L/XL) + approximate phase count
+- **Key risks**: What could go wrong? What are the unknowns?
+- **New dependencies**: Any new libraries, services, or external integrations needed?
+- **Recommendation**: Overall go/no-go/conditional assessment
+</step>
+
+<step name="write_document">
+Create (or overwrite) the research document.
+
+Ensure directory exists:
+```bash
+mkdir -p ${project_root}/docs/ideas/pending
+```
+
+Write the research document to `${project_root}/docs/ideas/pending/${SLUG}-research.md` using the Write tool.
+
+**Document structure:**
+```markdown
+---
+type: research
+idea_id: {id}
+idea_title: "{title}"
+date: "{YYYY-MM-DD}"
+repos_analysed: ["{repo1}", "{repo2}"]
+---
+
+# Research: {title}
+
+{If re-research and meaningful changes exist:}
+## Changes from Prior Research
+
+{Bullet list of what's new, updated, or contradicted vs prior findings. Include when there are meaningful differences from prior research, skip when findings are similar.}
+
+## Web Search Findings
+
+{Findings from Dimension 1}
+
+## Codebase Analysis
+
+{Findings from Dimension 2. For multi-repo: subsections per repo.}
+
+## Landscape Survey
+
+{Findings from Dimension 3. Comparison tables where applicable.}
+
+## Approaches & Patterns
+
+{Findings from Dimension 4}
+
+## Feasibility Assessment
+
+**Stack Fit:** {assessment}
+**Effort:** {T-shirt size} -- {phase count estimate}
+**Key Risks:**
+{bullet list}
+**New Dependencies:**
+{bullet list or "None"}
+**Recommendation:** {go / no-go / conditional with conditions}
+
+---
+*Researched: {YYYY-MM-DD}*
+```
+
+For multi-repo projects, the Codebase Analysis and Landscape Survey sections should have `### {repo-name}` subsections.
+
+If repos_analysed is empty (no REPOS.md), omit the field from frontmatter or use an empty array.
+</step>
+
+<step name="save_research_log">
+Save the Research Log entry to the idea file via the CLI command.
+
+Build the entry JSON:
+```json
+{
+  "date": "YYYY-MM-DD",
+  "summary": "{Actionable summary paragraph -- findings, recommendation, key risks. Enough to act on without opening the full document.}",
+  "keyFindings": "- {finding 1}\n- {finding 2}\n- {finding 3}",
+  "recommendation": "{Strong recommendation or neutral options presentation}",
+  "documentLink": "${project_root}/docs/ideas/pending/${SLUG}-research.md",
+  "outcome": "{Recommended next step: 'Ready for spec', 'Needs more discussion', 'Not feasible', etc.}"
+}
+```
+
+Call:
+```bash
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs ideas research-save --id "${id}" --entry '${entryJson}'
+```
+
+Parse the JSON result to confirm success.
+</step>
+
+<step name="git_commit">
+Commit both the research document and the updated idea file:
+```bash
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "docs: research idea #${id} -- ${title}" --files ${project_root}/docs/ideas/pending/${SLUG}-research.md ${project_root}/ideas/${state}/${filename}
+```
+</step>
+
+<step name="suggest_next">
+Display the key finding and recommendation inline, then suggest the next action based on findings.
+
+- **Key Finding:** {the single most important finding}
+- **Recommendation:** {the overall recommendation}
+
+Suggest next step based on outcome:
+- **"Ready for spec"**: "Run `/dgs:write-spec` to create a formal spec from this idea."
+- **"Needs more discussion"**: "Run `/dgs:discuss-idea ${id}` to explore open questions before specifying."
+- **"Not feasible"**: "Consider `/dgs:reject-idea ${id}` or `/dgs:discuss-idea ${id}` to explore alternatives."
+- **Other**: "Run `/dgs:develop-idea ${id}` for a combined discussion-then-research flow."
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] Idea loaded with full context (body, tags, notes, discussion log, research log)
+- [ ] Research dimensions executed with progress announcements
+- [ ] Research document created at `${project_root}/docs/ideas/pending/{slug}-research.md` with frontmatter
+- [ ] Research Log entry saved to idea file via research-save CLI
+- [ ] Both files committed together
+- [ ] Key finding + recommendation + next step displayed
+</success_criteria>

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

@@ -0,0 +1,81 @@
+<purpose>
+Research how to implement a phase. Spawns dgs-phase-researcher with phase context.
+
+Standalone research command. For most workflows, use `/dgs:plan-phase` which integrates research automatically.
+</purpose>
+
+<context_tier>planning</context_tier>
+
+<process>
+
+## Step 0: Resolve Model Profile
+
+@~/.claude/deliver-great-systems/references/model-profile-resolution.md
+
+Resolve model for:
+- `dgs-phase-researcher`
+
+## Step 1: Normalize and Validate Phase
+
+@~/.claude/deliver-great-systems/references/phase-argument-parsing.md
+
+```bash
+PHASE_INFO=$(node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs roadmap get-phase "${PHASE}")
+```
+
+If `found` is false: Error and exit.
+
+## Step 2: Check Existing Research
+
+```bash
+ls ${phase_dir}/*-RESEARCH.md 2>/dev/null
+```
+
+If exists: Offer update/view/skip options.
+
+## Step 3: Gather Phase Context
+
+```bash
+INIT=$(node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs init phase-op "${PHASE}")
+# Extract: phase_dir, padded_phase, phase_number, state_path, requirements_path, context_path
+```
+
+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)
+```
+
+## Step 4: Spawn Researcher
+
+```
+Task(
+  prompt="<objective>
+Research implementation approach for Phase {phase}: {name}
+</objective>
+
+<files_to_read>
+- {context_path} (USER DECISIONS from /dgs:discuss-phase)
+- {requirements_path} (Project requirements)
+- {state_path} (Project decisions and history)
+</files_to_read>
+
+<additional_context>
+Phase description: {description}
+</additional_context>
+
+<output>
+Write to: ${phase_dir}/${padded_phase}-RESEARCH.md
+</output>",
+  subagent_type="dgs-phase-researcher",
+  model="{researcher_model}"
+)
+```
+
+## Step 5: Handle Return
+
+- `## RESEARCH COMPLETE` — Display summary, offer: Plan/Dig deeper/Review/Done
+- `## CHECKPOINT REACHED` — Present to user, spawn continuation
+- `## RESEARCH INCONCLUSIVE` — Show attempts, offer: Add context/Try different mode/Manual
+
+</process>

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

@@ -0,0 +1,101 @@
+<purpose>
+Restore a rejected, done, or consolidated idea back to pending state for reconsideration. For consolidated ideas, the consolidated_into field is automatically removed. Confirmation is always required. Rejection reasons are preserved in the file as history (not removed on restore).
+</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="parse_arguments">
+Extract idea ID from arguments (first positional arg).
+
+If no ID provided, list rejected, done, and consolidated ideas and prompt user to select one:
+```bash
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs ideas list --all --raw
+```
+Parse JSON result and display rejected, done, and consolidated ideas only. Use AskUserQuestion to let user pick an idea by ID.
+</step>
+
+<step name="find_and_display_idea">
+Find the idea by ID across all states:
+```bash
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs ideas list
+```
+
+Parse the JSON result and locate the idea matching the provided ID.
+
+Determine the idea's current state:
+- If found in **rejected**, **done**, or **consolidated**: proceed with restore
+- If found in **pending**: error and stop:
+  ```
+  Idea #${id} is already pending.
+  ```
+- If not found at all: error and stop:
+  ```
+  Idea #${id} not found in rejected, done, or consolidated ideas. Only rejected, done, and consolidated ideas can be restored.
+  ```
+
+Read the idea file to get its title, current state, and any rejection reason:
+```bash
+cat ${path}
+```
+
+Display the idea title, current state, and rejection reason (if any) so the user has full context.
+</step>
+
+<step name="confirm">
+Confirmation is always required.
+
+Use AskUserQuestion:
+- header: "Restore Idea #${id}?"
+- question: "Restore '${title}' from ${state} to pending?"
+- options: "Yes, restore it", "No, cancel"
+
+For consolidated ideas, add context: "Note: the consolidated_into reference will be removed from this idea."
+
+If user selects "No, cancel":
+Output: `Cancelled.`
+Stop execution.
+</step>
+
+<step name="execute_restore">
+Execute the restore via dgs-tools:
+```bash
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs ideas restore --id "${id}"
+```
+
+The ideas.cjs module handles:
+- Moving the file from rejected/, done/, or consolidated/ to pending/ via git mv
+- For consolidated ideas, removing the consolidated_into field from frontmatter
+- Creating an auto-commit for the state transition
+- Rejection reason is NOT removed from the file -- it is kept as history per project convention
+</step>
+
+<step name="confirm_output">
+Output: `Idea #${id} restored to pending.`
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] Confirmation required before restore
+- [ ] File moved from rejected/, done/, or consolidated/ to pending/ via git mv
+- [ ] For consolidated ideas, consolidated_into field removed from frontmatter
+- [ ] Rejection reason preserved in file (not removed)
+- [ ] Git commit created automatically for the state transition
+- [ ] Handles "already pending" and "not found" errors gracefully
+</success_criteria>