@ktpartners/dgs-platform 2.6.2

package/deliver-great-systems/workflows/check-todos.md

@@ -0,0 +1,181 @@
+<purpose>
+List all pending todos, allow selection, load full context for the selected todo, and route to appropriate action.
+</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="init_context">
+Load todo context:
+
+```bash
+INIT=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" init todos)
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+TIER_FILES=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" context load-tier lite --raw 2>/dev/null)
+```
+
+Extract from init JSON: `todo_count`, `todos`, `pending_dir`.
+Use `TIER_FILES` JSON `files` array for project context (PROJECT.md, STATE.md, config.json).
+
+If `todo_count` is 0:
+```
+No pending todos.
+
+Todos are captured during work sessions with /dgs:add-todo.
+
+---
+
+Would you like to:
+
+1. Continue with current phase (/dgs:progress)
+2. Add a todo now (/dgs:add-todo)
+```
+
+Exit.
+</step>
+
+<step name="parse_filter">
+Check for area filter in arguments:
+- `/dgs:check-todos` → show all
+- `/dgs:check-todos api` → filter to area:api only
+</step>
+
+<step name="list_todos">
+Use the `todos` array from init context (already filtered by area if specified).
+
+Parse and display as numbered list:
+
+```
+Pending Todos:
+
+1. Add auth token refresh (api, 2d ago)
+2. Fix modal z-index issue (ui, 1d ago)
+3. Refactor database connection pool (database, 5h ago)
+
+---
+
+Reply with a number to view details, or:
+- `/dgs:check-todos [area]` to filter by area
+- `q` to exit
+```
+
+Format age as relative time from created timestamp.
+</step>
+
+<step name="handle_selection">
+Wait for user to reply with a number.
+
+If valid: load selected todo, proceed.
+If invalid: "Invalid selection. Reply with a number (1-[N]) or `q` to exit."
+</step>
+
+<step name="load_context">
+Read the todo file completely. Display:
+
+```
+## [title]
+
+**Area:** [area]
+**Created:** [date] ([relative time] ago)
+**Files:** [list or "None"]
+
+### Problem
+[problem section content]
+
+### Solution
+[solution section content]
+```
+
+If `files` field has entries, read and briefly summarize each.
+</step>
+
+<step name="check_roadmap">
+Check for roadmap (can use init progress or directly check file existence):
+
+If ROADMAP.md exists (check `${roadmap_path}`):
+1. Check if todo's area matches an upcoming phase
+2. Check if todo's files overlap with a phase's scope
+3. Note any match for action options
+</step>
+
+<step name="offer_actions">
+**If todo maps to a roadmap phase:**
+
+Use AskUserQuestion:
+- header: "Action"
+- question: "This todo relates to Phase [N]: [name]. What would you like to do?"
+- options:
+  - "Work on it now" — move to done, start working
+  - "Add to phase plan" — include when planning Phase [N]
+  - "Brainstorm approach" — think through before deciding
+  - "Put it back" — return to list
+
+**If no roadmap match:**
+
+Use AskUserQuestion:
+- header: "Action"
+- question: "What would you like to do with this todo?"
+- options:
+  - "Work on it now" — move to done, start working
+  - "Create a phase" — /dgs:add-phase with this scope
+  - "Brainstorm approach" — think through before deciding
+  - "Put it back" — return to list
+</step>
+
+<step name="execute_action">
+**Work on it now:**
+```bash
+mv "${pending_dir}/[filename]" "${project_root}/todos/done/"
+```
+Update STATE.md todo count. Present problem/solution context. Begin work or ask how to proceed.
+
+**Add to phase plan:**
+Note todo reference in phase planning notes. Keep in pending. Return to list or exit.
+
+**Create a phase:**
+Display: `/dgs:add-phase [description from todo]`
+Keep in pending. User runs command in fresh context.
+
+**Brainstorm approach:**
+Keep in pending. Start discussion about problem and approaches.
+
+**Put it back:**
+Return to list_todos step.
+</step>
+
+<step name="update_state">
+After any action that changes todo count:
+
+Re-run `init todos` to get updated count, then update STATE.md "### Pending Todos" section if exists.
+</step>
+
+<step name="git_commit">
+If todo was moved to done/, commit the change:
+
+```bash
+git rm --cached ${pending_dir}/[filename] 2>/dev/null || true
+node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" commit "docs: start work on todo - [title]" --files ${project_root}/todos/done/[filename] ${state_path}
+```
+
+Tool respects `commit_docs` config and gitignore automatically.
+
+Confirm: "Committed: docs: start work on todo - [title]"
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] All pending todos listed with title, area, age
+- [ ] Area filter applied if specified
+- [ ] Selected todo's full context loaded
+- [ ] Roadmap context checked for phase match
+- [ ] Appropriate actions offered
+- [ ] Selected action executed
+- [ ] STATE.md updated if todo count changed
+- [ ] Changes committed to git (if todo moved to done/)
+</success_criteria>

package/deliver-great-systems/workflows/cleanup.md

@@ -0,0 +1,247 @@
+<purpose>
+
+Archive accumulated phase directories from completed milestones into `${project_root}/milestones/v{X.Y}-phases/`, and clean up completed quick/fast task directories from `${project_root}/quick/`. Identifies which phases belong to each completed milestone, scans quick task directories for completion (SUMMARY.md presence), shows a combined dry-run summary, and executes on confirmation.
+
+</purpose>
+
+<context_tier>lite</context_tier>
+
+<required_reading>
+
+1. `${project_root}/MILESTONES.md`
+2. `${project_root}/milestones/` directory listing
+3. `${project_root}/phases/` directory listing
+4. `${project_root}/quick/` directory listing
+
+</required_reading>
+
+<process>
+
+<step name="initialize" priority="first">
+
+Load project context:
+
+```bash
+INIT=$(node "$HOME/.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)
+```
+
+Parse JSON for: `project_root`, `state_path`, `roadmap_path`. The phases base path is `${project_root}/phases/`.
+Use `TIER_FILES` JSON `files` array for project context (PROJECT.md, STATE.md, config.json).
+
+</step>
+
+<step name="identify_completed_milestones">
+
+Read `${project_root}/MILESTONES.md` to identify completed milestones and their versions.
+
+```bash
+cat ${project_root}/MILESTONES.md
+```
+
+Extract each milestone version (e.g., v1.0, v1.1, v2.0).
+
+Check which milestone archive dirs already exist:
+
+```bash
+ls -d ${project_root}/milestones/v*-phases 2>/dev/null
+```
+
+Filter to milestones that do NOT already have a `-phases` archive directory.
+
+If all milestones already have phase archives, note that milestone archival has nothing to do but continue to the next steps — quick task cleanup may still be needed.
+
+</step>
+
+<step name="determine_phase_membership">
+
+For each completed milestone without a `-phases` archive, read the archived ROADMAP snapshot to determine which phases belong to it:
+
+```bash
+cat ${project_root}/milestones/v{X.Y}-ROADMAP.md
+```
+
+Extract phase numbers and names from the archived roadmap (e.g., Phase 1: Foundation, Phase 2: Auth).
+
+Check which of those phase directories still exist in `${project_root}/phases/`:
+
+```bash
+ls -d ${project_root}/phases/*/ 2>/dev/null
+```
+
+Match phase directories to milestone membership. Only include directories that still exist in `${project_root}/phases/`.
+
+</step>
+
+<step name="identify_quick_tasks">
+
+Scan `${project_root}/quick/` for completed quick task directories.
+
+A quick task directory is "completed" if it contains a SUMMARY.md file (pattern: `*-SUMMARY.md`).
+
+**Important:** Skip the following special entries:
+- `HISTORY.md` (file, not directory -- the archival log)
+- Any file that is not a directory
+
+```bash
+ls -d ${project_root}/quick/*/ 2>/dev/null
+```
+
+For each directory found, check if it contains a SUMMARY.md:
+
+```bash
+ls ${project_root}/quick/${dir_name}/*-SUMMARY.md 2>/dev/null
+```
+
+Directories with a SUMMARY.md are candidates for deletion. Directories without SUMMARY.md are "in-progress" and must be skipped.
+
+</step>
+
+<step name="check_work_available">
+
+If BOTH milestone archival has nothing to do AND no completed quick task directories were found:
+
+```
+Nothing to clean up. All milestones already archived and no completed quick task directories found.
+```
+
+Stop here.
+
+If either milestone archival or quick task cleanup has work to do, continue.
+
+</step>
+
+<step name="show_dry_run">
+
+Present a combined dry-run summary covering milestone archival and quick task cleanup as applicable.
+
+**Milestone archival section** (if applicable):
+
+```
+## Cleanup Summary
+
+### Milestone Phase Archival
+
+#### v{X.Y} — {Milestone Name}
+These phase directories will be archived:
+- 01-foundation/
+- 02-auth/
+- 03-core-features/
+
+Destination: ${project_root}/milestones/v{X.Y}-phases/
+
+#### v{X.Z} — {Milestone Name}
+These phase directories will be archived:
+- 04-security/
+- 05-hardening/
+
+Destination: ${project_root}/milestones/v{X.Z}-phases/
+```
+
+If no phase directories remain to archive, omit the milestone section.
+
+**Quick task cleanup section** (if applicable):
+
+```
+### Quick Task Directories
+
+These completed quick task directories will be removed:
+- 260317-lv1-implement-req-04-implementation-tracking/
+- 46-fix-documentation-tier-annotation-accura/
+- ...
+
+({N} directories — HISTORY.md preserved)
+```
+
+If no completed quick task directories found, omit the quick task section.
+
+AskUserQuestion: "Proceed with cleanup?" with options: "Yes — execute listed cleanup actions" | "Cancel"
+
+If "Cancel": Stop.
+
+</step>
+
+<step name="archive_phases">
+
+For each milestone, move phase directories:
+
+```bash
+mkdir -p ${project_root}/milestones/v{X.Y}-phases
+```
+
+For each phase directory belonging to this milestone:
+
+```bash
+mv ${project_root}/phases/{dir} ${project_root}/milestones/v{X.Y}-phases/
+```
+
+Repeat for all milestones in the cleanup set.
+
+</step>
+
+<step name="cleanup_quick_tasks">
+
+For each completed quick task directory identified in the `identify_quick_tasks` step, delete the directory entirely. Quick task planning artifacts (PLAN.md, SUMMARY.md, CONTEXT.md, VERIFICATION.md) are ephemeral working documents. The permanent record lives in HISTORY.md and STATE.md's table.
+
+```bash
+rm -rf ${project_root}/quick/${dir_name}
+```
+
+**Preserve:** `${project_root}/quick/HISTORY.md` must NEVER be deleted. The cleanup step must explicitly skip this file — only process directories, never files.
+
+</step>
+
+<step name="commit">
+
+Commit the changes. The commit message and staged paths depend on what was cleaned up:
+
+**Both milestone archival and quick task cleanup:**
+
+```bash
+node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" commit "chore: archive phase directories and clean up quick tasks" --files ${project_root}/milestones/ ${project_root}/phases/ ${project_root}/quick/
+```
+
+**Milestone archival only (no quick task cleanup):**
+
+```bash
+node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" commit "chore: archive phase directories from completed milestones" --files ${project_root}/milestones/ ${project_root}/phases/
+```
+
+**Quick task cleanup only (no milestone archival):**
+
+```bash
+node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" commit "chore: clean up completed quick task directories" --files ${project_root}/quick/
+```
+
+</step>
+
+<step name="report">
+
+```
+Cleanup complete:
+
+{If milestone archival was performed:}
+Milestones archived:
+{For each milestone}
+- v{X.Y}: {N} phase directories → ${project_root}/milestones/v{X.Y}-phases/
+
+{If quick task cleanup was performed:}
+Quick tasks: {N} directories cleaned up (HISTORY.md preserved)
+```
+
+</step>
+
+</process>
+
+<success_criteria>
+
+- [ ] All completed milestones without existing phase archives identified
+- [ ] Phase membership determined from archived ROADMAP snapshots
+- [ ] Completed quick task directories identified (SUMMARY.md presence check)
+- [ ] HISTORY.md explicitly preserved — never deleted
+- [ ] Combined dry-run summary shown and user confirmed
+- [ ] Phase directories moved to `${project_root}/milestones/v{X.Y}-phases/`
+- [ ] Completed quick task directories deleted
+- [ ] Changes committed
+
+</success_criteria>