@ktpartners/dgs-platform 2.6.2

package/deliver-great-systems/workflows/consolidate-ideas.md

@@ -0,0 +1,365 @@
+<purpose>
+Consolidate two or more related pending ideas into a single AI-synthesised idea. Reads all source ideas in full, generates a coherent body that captures the combined intent, merges discussion/research/notes logs with source attribution, presents the result for user review, and delegates to dgs-tools.cjs for the atomic data operation (file creation, source annotation, source moves, git commit).
+</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="load_context" priority="first">
+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 idea IDs and optional flags.
+
+- Extract all numeric positional arguments as idea IDs (e.g., `/dgs:consolidate-ideas 1 3 17` -> ids=[1, 3, 17])
+- Check for `--title "..."` flag. If present, extract the title string.
+
+If no IDs 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 consolidate. Run /dgs:add-idea to capture ideas first.
+```
+Exit workflow.
+
+**If fewer than 2 pending ideas:**
+```
+Only 1 pending idea found. Consolidation requires at least 2 ideas.
+```
+Exit workflow.
+
+**If ideas exist:** Display them as a numbered list showing ID, title, and tags:
+
+```
+## Pending Ideas
+
+| # | ID | Title | Tags |
+|---|-----|-------|------|
+| 1 | 001 | Add retry logic | api, reliability |
+| 2 | 003 | Handle timeouts | api |
+| 3 | 017 | Circuit breaker | api, reliability |
+```
+
+Use AskUserQuestion: "Which ideas would you like to consolidate? (enter IDs, comma-separated, e.g. 1,3,17 -- minimum 2)"
+
+Parse response into idea IDs. Validate at least 2 IDs were provided.
+</step>
+
+<step name="validate_sources">
+Validate all source IDs exist and are in pending state:
+
+```bash
+ALL_IDEAS=$(node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs ideas list --all --raw)
+```
+
+Parse JSON result. For each provided ID:
+1. Find the idea in the list by matching `id`
+2. Verify the idea exists. If not found: error "Idea #${id} not found." and exit.
+3. Verify the idea is in `pending` state. If not: error "Idea #${id} is in ${state} state. Only pending ideas can be consolidated." and exit.
+
+Store the validated ideas with their full metadata (id, title, tags, state, filename, path).
+</step>
+
+<step name="load_source_content">
+Read the full content of each source idea file to extract body, notes, discussion log, and research log.
+
+For each validated source idea, use the Read tool to load the file at the `path` from the list result.
+
+For each idea, extract:
+- `body` -- the main content between frontmatter and first section heading
+- `notes` -- content under `## Notes` heading (if present)
+- `discussionLog` -- content under `## Discussion Log` heading (if present)
+- `researchLog` -- content under `## Research Log` heading (if present)
+- `tags` -- from frontmatter
+- `title` -- from frontmatter
+- `id` -- from frontmatter
+
+Store all extracted content per idea for use in synthesis steps.
+</step>
+
+<step name="synthesise_body">
+Generate a coherent AI-synthesised body that captures the combined intent of all source ideas.
+
+**This is the core creative step.** Do NOT mechanically concatenate the source idea bodies. Instead, read all source bodies and write a fresh, unified description that:
+- Captures the full scope of work implied by all source ideas combined
+- Identifies the common theme or goal that links the ideas
+- Preserves specific technical details, constraints, and requirements from each source
+- Reads as a single cohesive idea description, not as a merged document
+
+After the synthesised body, append a provenance line:
+
+```
+---
+*Consolidated from ideas: #001 (Add retry logic), #003 (Handle timeouts), #017 (Circuit breaker)*
+```
+
+The provenance line lists each source idea ID and title for traceability.
+
+Store the synthesised body (including provenance line) as `synthesised_body`.
+</step>
+
+<step name="generate_title">
+Determine the title for the new consolidated idea.
+
+**If `--title` was provided in arguments:** Use that title directly.
+
+**If no title provided:** Generate a title from the synthesised body and source ideas.
+The title should:
+- Be concise (under 80 characters)
+- Capture the unified theme of all source ideas
+- Not be a mechanical join of source titles (e.g., NOT "Add retry logic and handle timeouts and circuit breaker")
+- Read as a standalone idea title
+
+Store as `consolidated_title`.
+</step>
+
+<step name="merge_tags">
+Build the deduplicated union of all source idea tags.
+
+Collect all tags from all source ideas into a single set. Remove duplicates. Sort alphabetically.
+
+Store as `merged_tags` (comma-separated string for CLI, e.g., "api,reliability,error-handling").
+</step>
+
+<step name="merge_discussion_logs">
+Merge discussion logs from all source ideas with source attribution and chronological ordering.
+
+For each source idea that has a non-empty discussion log:
+1. Parse the discussion log into individual entries (each entry starts with a `### ` heading)
+2. Prefix each entry heading with `[from #ID]` where ID is the source idea's ID (zero-padded to 3 digits)
+   - Example: `### 2026-02-15 --- API timeout patterns` becomes `### [from #003] 2026-02-15 --- API timeout patterns`
+3. Extract the date from each entry heading for chronological sorting
+
+Sort all entries from all sources chronologically (oldest first).
+
+Concatenate all attributed, sorted entries into a single string.
+
+If no source ideas have discussion logs, store an empty string.
+
+Store as `merged_discussion`.
+</step>
+
+<step name="merge_research_logs">
+Merge research logs from all source ideas with source attribution and chronological ordering.
+
+Follow the exact same process as merge_discussion_logs:
+1. Parse each source's research log into individual entries (each starts with `### `)
+2. Prefix each heading with `[from #ID]`
+3. Sort chronologically (oldest first)
+4. Concatenate into a single string
+
+If no source ideas have research logs, store an empty string.
+
+Store as `merged_research`.
+</step>
+
+<step name="merge_notes">
+Merge notes from all source ideas with source attribution.
+
+For each source idea that has non-empty notes content:
+1. Prefix the notes block with a source attribution line: `**From #ID --- {title}:**`
+2. Append the notes content
+
+Concatenate all attributed note blocks, separated by blank lines.
+
+If no source ideas have notes, store an empty string.
+
+Store as `merged_notes`.
+
+Note: The `merged_notes` content is informational for the review display. The CLI command does not accept a `--notes` parameter -- notes are NOT passed to the CLI. The consolidation note appended to each source idea is handled automatically by `cmdIdeasConsolidate` via `appendConsolidationNote`. The merged notes from sources are included in the synthesised body's provenance section to preserve context, or mentioned in the review for user awareness. If the user wants notes content preserved, they can request it be woven into the synthesised body.
+</step>
+
+<step name="present_for_review">
+Present a diff-style comparison of source ideas alongside the synthesised result so the user can make an informed approval decision.
+
+Display the preview in this format:
+
+```
+## Consolidation Preview: These {N} ideas will become 1 idea
+
+### Source Ideas (will be consolidated)
+```
+
+For each source idea, display:
+
+```
+---
+
+**#{id} --- {title}**
+**Tags:** {tags}
+
+{body excerpt -- first 200 characters or full body if shorter}
+
+---
+```
+
+(Repeat for each source idea)
+
+Then display the synthesised result:
+
+```
+### Synthesised Result (new idea)
+
+**Title:** {consolidated_title}
+**Tags:** {merged_tags}
+**Sources:** #{id1}, #{id2}, #{id3}
+
+{synthesised_body}
+```
+
+If merged_discussion is non-empty:
+```
+### Discussion Log (merged from sources)
+
+{merged_discussion}
+```
+
+If merged_research is non-empty:
+```
+### Research Log (merged from sources)
+
+{merged_research}
+```
+
+If merged_notes is non-empty:
+```
+### Notes (from sources, for reference)
+
+{merged_notes}
+```
+
+Use AskUserQuestion:
+- header: "Review Consolidated Idea"
+- question: "Review the synthesised idea above. Choose an action:\n- **approve** -- create this consolidated idea\n- **edit** -- describe changes you'd like\n- **cancel** -- abort consolidation"
+
+**If approve:** Proceed to execute step.
+
+**If edit:** The user describes what they want changed. Claude applies the edits to the synthesised body, title, and/or tags as requested. Then re-display the updated preview and ask for approval again. Loop until approved or cancelled.
+
+**If cancel:**
+```
+Consolidation cancelled. No changes made.
+```
+Exit workflow.
+</step>
+
+<step name="execute_consolidation">
+Call the CLI to perform the atomic consolidation operation.
+
+Build the CLI command with all parameters. The discussion and research content may contain special characters, so pass them via files to avoid shell escaping issues.
+
+**1. Write temporary content files if needed:**
+
+If `merged_discussion` is non-empty, write it to a temporary file. Similarly for `merged_research`.
+
+**2. Build and run the CLI command:**
+
+The most reliable approach is using a node script that calls the CLI via execFileSync to avoid shell escaping:
+
+```bash
+node -e "
+const { execFileSync } = require('child_process');
+const fs = require('fs');
+
+// Read content from temp files written by the Write tool
+const body = fs.readFileSync('/tmp/dgs-consolidate-body.tmp', 'utf-8').trim();
+const discussion = fs.readFileSync('/tmp/dgs-consolidate-discussion.tmp', 'utf-8').trim();
+const research = fs.readFileSync('/tmp/dgs-consolidate-research.tmp', 'utf-8').trim();
+
+const args = [
+  './.claude/deliver-great-systems/bin/dgs-tools.cjs',
+  'ideas', 'consolidate',
+  '--ids', '${ids_csv}',
+  '--title', body ? '${consolidated_title}' : undefined,
+  '--body', body,
+  '--tags', '${merged_tags}',
+  '--raw'
+].filter(Boolean);
+
+if (discussion) args.push('--discussion', discussion);
+if (research) args.push('--research', research);
+
+const result = execFileSync('node', args, { encoding: 'utf-8' });
+console.log(result);
+"
+```
+
+Write multi-line parameters (body, discussion, research) to temporary files using the Write tool before running the node command.
+
+**Parse the JSON result.** The CLI returns:
+```json
+{
+  "id": 5,
+  "filename": "005-improve-api-resilience.md",
+  "path": ".planning/ideas/pending/005-improve-api-resilience.md",
+  "title": "Improve API resilience",
+  "consolidated_from": ["001", "003", "017"],
+  "moved_files": [
+    { "id": 1, "filename": "001-add-retry-logic.md", "from": "pending", "to": "consolidated" },
+    { "id": 3, "filename": "003-handle-timeouts.md", "from": "pending", "to": "consolidated" },
+    { "id": 17, "filename": "017-circuit-breaker.md", "from": "pending", "to": "consolidated" }
+  ]
+}
+```
+
+If the CLI returns an error, display it and exit.
+</step>
+
+<step name="confirm_output">
+Display a summary of the consolidation:
+
+```
+## Consolidation Complete
+
+**New idea:** #{new_id} --- {title}
+**File:** {path}
+**Sources consolidated:** #{id1}, #{id2}, #{id3} -> moved to consolidated/
+**Tags:** {tags}
+**Git commit:** ideas: consolidate #{id1}, #{id2}, #{id3} -> #{new_id} - {title}
+
+The source ideas are now in `consolidated/` state with references back to #{new_id}.
+You can view the new idea with `/dgs:list-ideas` or read it directly.
+```
+
+If discussion or research logs were merged, mention it:
+```
+**Merged:** {N} discussion entries, {M} research entries from source ideas
+```
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] Arguments parsed correctly (idea IDs from positional args, --title flag)
+- [ ] Interactive selection works when no IDs provided
+- [ ] All source IDs validated as existing and in pending state
+- [ ] Full content loaded from each source idea (body, notes, discussion log, research log)
+- [ ] Synthesised body is coherent and captures combined intent (not mechanical concatenation)
+- [ ] Provenance line appended to body listing all source ideas with titles
+- [ ] Title either from --title flag or AI-generated from source content
+- [ ] Tags are deduplicated union of all source tags
+- [ ] Discussion logs merged with [from #ID] attribution, chronologically ordered
+- [ ] Research logs merged with [from #ID] attribution, chronologically ordered
+- [ ] Notes merged with source attribution
+- [ ] User sees synthesised idea for review before commit
+- [ ] User can approve, request edits, or cancel
+- [ ] CLI called with all parameters for atomic operation
+- [ ] Confirmation output shows new idea ID, path, and source disposition
+- [ ] Preview shows source ideas alongside synthesised result for comparison
+</success_criteria>

package/deliver-great-systems/workflows/create-milestone-job.md

@@ -0,0 +1,177 @@
+<purpose>
+Generate a milestone build job with interactive approval. Reads the roadmap to determine remaining phases, generates the step sequence, displays it for user review, and writes the job file only after approval.
+</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">
+Parse `$ARGUMENTS` to extract version and flags.
+
+- **Version:** First non-flag argument (e.g., `v6`, `v6.0`). If omitted, auto-detection happens in the preview step.
+- **--no-check flag:** If present, omit audit-milestone and complete-milestone steps from the generated job.
+
+```bash
+# Pseudocode for argument parsing:
+# VERSION = first arg that doesn't start with --
+# CHECK = true (default)
+# If --no-check in args: CHECK = false
+```
+
+Set `VERSION` (or null for auto-detect) and `CHECK` (true/false).
+</step>
+
+<step name="generate_preview">
+Call the milestone-preview subcommand to get the step list without writing any files.
+
+```bash
+# Build command with parsed arguments
+# If VERSION is set and CHECK is true:
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs jobs milestone-preview VERSION
+
+# If VERSION is set and CHECK is false:
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs jobs milestone-preview VERSION --no-check
+
+# If VERSION is null (auto-detect) and CHECK is true:
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs jobs milestone-preview
+
+# If VERSION is null and CHECK is false:
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs jobs milestone-preview --no-check
+```
+
+Parse the JSON output. The response contains:
+```json
+{
+  "preview": true,
+  "version": "v6.0",
+  "check": true,
+  "step_count": 12,
+  "phase_count": 5,
+  "steps_preview": ["/dgs:plan-phase 51 --auto", "/dgs:execute-phase 51 --auto", ...],
+  "content": "..."
+}
+```
+
+Extract: `version`, `step_count`, `phase_count`, `steps_preview`.
+
+**If step_count is 0:** Go to `handle_empty`.
+</step>
+
+<step name="display_steps">
+Present the step list for user approval. Transform the raw `steps_preview` array for clean display:
+
+**Display format rules:**
+1. Strip the `/dgs:` prefix from each command
+2. Strip any `--auto` flags from display
+3. Trim trailing whitespace from each line
+4. Number each step sequentially
+
+Present in this format:
+
+```
+## Milestone Job: {version}
+
+{step_count} steps across {phase_count} phases
+
+### Steps
+
+1. plan-phase 51
+2. execute-phase 51
+3. verify-work 51
+4. plan-phase 52
+5. execute-phase 52
+6. verify-work 52
+...
+N. complete-milestone v6.0
+
+Create this job? (yes/no)
+```
+
+Wait for user response.
+</step>
+
+<step name="handle_approval">
+Process the user's response to the approval prompt.
+
+**If user approves** (responds with "yes", "y", "approve", "approved", or similar affirmative):
+
+1. Call the create-milestone subcommand to write the job file:
+
+```bash
+# With version and check:
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs jobs create-milestone VERSION
+
+# With --no-check:
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs jobs create-milestone VERSION --no-check
+```
+
+2. Commit the job file:
+
+```bash
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "docs(50): create milestone job {version}" --files .planning/jobs/pending/milestone-{version}.md
+```
+
+3. Display success and next steps:
+
+```
+Job created: .planning/jobs/pending/milestone-{version}.md
+
+---
+
+## Next Up
+
+**Run the job** -- execute all steps sequentially
+
+`/dgs:run-job {version}`
+
+---
+```
+
+**If user rejects** (responds with "no", "n", "reject", "cancel", or similar negative):
+
+Display:
+```
+Job not created.
+```
+
+Exit cleanly. No error, no file written.
+</step>
+
+<step name="handle_empty">
+If `step_count` is 0 (all phases complete and --no-check was passed):
+
+Display:
+```
+All phases are complete. Nothing to do.
+```
+
+Exit cleanly. No job file created, no approval prompt shown.
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] Arguments parsed correctly (version auto-detected if omitted)
+- [ ] Preview generated via `jobs milestone-preview` (no side effects)
+- [ ] Step list displayed with minimal format (no --auto, no /dgs: prefix)
+- [ ] Summary line shows step count and phase count
+- [ ] User approval required before file creation
+- [ ] Approved: job file written via `jobs create-milestone` and committed
+- [ ] Rejected: clean exit with "Job not created"
+- [ ] Empty job: clean exit with "All phases are complete"
+</success_criteria>