@ktpartners/dgs-platform 2.6.2

package/deliver-great-systems/workflows/resume-project.md

@@ -0,0 +1,311 @@
+<trigger>
+Use this workflow when:
+- Starting a new session on an existing project
+- User says "continue", "what's next", "where were we", "resume"
+- Any planning operation when planning structure already exists
+- User returns after time away from project
+</trigger>
+
+<purpose>
+Instantly restore full project context so "Where were we?" has an immediate, complete answer.
+</purpose>
+
+<context_tier>lite</context_tier>
+
+<required_reading>
+@~/.claude/deliver-great-systems/references/continuation-format.md
+</required_reading>
+
+<process>
+
+<step name="initialize">
+Load all context in one call:
+
+```bash
+INIT=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" init resume)
+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)
+```
+
+Parse JSON for: `state_exists`, `roadmap_exists`, `project_exists`, `planning_exists`, `has_interrupted_agent`, `interrupted_agent_id`, `commit_docs`.
+Use `TIER_FILES` JSON `files` array for project context (PROJECT.md, STATE.md, config.json).
+
+**If `state_exists` is true:** Proceed to load_state
+**If `state_exists` is false but `roadmap_exists` or `project_exists` is true:** Offer to reconstruct STATE.md
+**If `planning_exists` is false:** This is a new project - route to /dgs:new-project
+</step>
+
+<step name="load_state">
+
+Read and parse STATE.md, then PROJECT.md:
+
+```bash
+cat ${state_path}
+cat ${project_path}
+```
+
+**From STATE.md extract:**
+
+- **Project Reference**: Core value and current focus
+- **Current Position**: Phase X of Y, Plan A of B, Status
+- **Progress**: Visual progress bar
+- **Recent Decisions**: Key decisions affecting current work
+- **Pending Todos**: Ideas captured during sessions
+- **Blockers/Concerns**: Issues carried forward
+- **Session Continuity**: Where we left off, any resume files
+
+**From PROJECT.md extract:**
+
+- **What This Is**: Current accurate description
+- **Requirements**: Validated, Active, Out of Scope
+- **Key Decisions**: Full decision log with outcomes
+- **Constraints**: Hard limits on implementation
+
+</step>
+
+<step name="check_incomplete_work">
+Look for incomplete work that needs attention:
+
+```bash
+# Check for continue-here files (mid-plan resumption)
+ls ${project_root}/phases/*/.continue-here*.md 2>/dev/null
+
+# Check for plans without summaries (incomplete execution)
+for plan in ${project_root}/phases/*/*-PLAN.md; do
+  summary="${plan/PLAN/SUMMARY}"
+  [ ! -f "$summary" ] && echo "Incomplete: $plan"
+done 2>/dev/null
+
+# Check for interrupted agents (use has_interrupted_agent and interrupted_agent_id from init)
+if [ "$has_interrupted_agent" = "true" ]; then
+  echo "Interrupted agent: $interrupted_agent_id"
+fi
+```
+
+**If .continue-here file exists:**
+
+- This is a mid-plan resumption point
+- Read the file for specific resumption context
+- Flag: "Found mid-plan checkpoint"
+
+**If PLAN without SUMMARY exists:**
+
+- Execution was started but not completed
+- Flag: "Found incomplete plan execution"
+
+**If interrupted agent found:**
+
+- Subagent was spawned but session ended before completion
+- Read agent-history.json for task details
+- Flag: "Found interrupted agent"
+  </step>
+
+<step name="present_status">
+Present complete project status to user:
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  PROJECT STATUS                                               ║
+╠══════════════════════════════════════════════════════════════╣
+║  Building: [one-liner from PROJECT.md "What This Is"]         ║
+║                                                               ║
+║  Phase: [X] of [Y] - [Phase name]                            ║
+║  Plan:  [A] of [B] - [Status]                                ║
+║  Progress: [██████░░░░] XX%                                  ║
+║                                                               ║
+║  Last activity: [date] - [what happened]                     ║
+╚══════════════════════════════════════════════════════════════╝
+
+[If incomplete work found:]
+⚠️  Incomplete work detected:
+    - [.continue-here file or incomplete plan]
+
+[If interrupted agent found:]
+⚠️  Interrupted agent detected:
+    Agent ID: [id]
+    Task: [task description from agent-history.json]
+    Interrupted: [timestamp]
+
+    Resume with: Task tool (resume parameter with agent ID)
+
+[If pending todos exist:]
+📋 [N] pending todos — /dgs:check-todos to review
+
+[If blockers exist:]
+⚠️  Carried concerns:
+    - [blocker 1]
+    - [blocker 2]
+
+[If alignment is not ✓:]
+⚠️  Brief alignment: [status] - [assessment]
+```
+
+</step>
+
+<step name="determine_next_action">
+Based on project state, determine the most logical next action:
+
+**If interrupted agent exists:**
+→ Primary: Resume interrupted agent (Task tool with resume parameter)
+→ Option: Start fresh (abandon agent work)
+
+**If .continue-here file exists:**
+→ Primary: Resume from checkpoint
+→ Option: Start fresh on current plan
+
+**If incomplete plan (PLAN without SUMMARY):**
+→ Primary: Complete the incomplete plan
+→ Option: Abandon and move on
+
+**If phase in progress, all plans complete:**
+→ Primary: Transition to next phase
+→ Option: Review completed work
+
+**If phase ready to plan:**
+→ Check if CONTEXT.md exists for this phase:
+
+- If CONTEXT.md missing:
+  → Primary: Discuss phase vision (how user imagines it working)
+  → Secondary: Plan directly (skip context gathering)
+- If CONTEXT.md exists:
+  → Primary: Plan the phase
+  → Option: Review roadmap
+
+**If phase ready to execute:**
+→ Primary: Execute next plan
+→ Option: Review the plan first
+</step>
+
+<step name="offer_options">
+Present contextual options based on project state:
+
+```
+What would you like to do?
+
+[Primary action based on state - e.g.:]
+1. Resume interrupted agent [if interrupted agent found]
+   OR
+1. Execute phase (/dgs:execute-phase {phase})
+   OR
+1. Discuss Phase 3 context (/dgs:discuss-phase 3) [if CONTEXT.md missing]
+   OR
+1. Plan Phase 3 (/dgs:plan-phase 3) [if CONTEXT.md exists or discuss option declined]
+
+[Secondary options:]
+2. Review current phase status
+3. Check pending todos ([N] pending)
+4. Review brief alignment
+5. Something else
+```
+
+**Note:** When offering phase planning, check for CONTEXT.md existence first:
+
+```bash
+ls ${project_root}/phases/XX-name/*-CONTEXT.md 2>/dev/null
+```
+
+If missing, suggest discuss-phase before plan. If exists, offer plan directly.
+
+Wait for user selection.
+</step>
+
+<step name="route_to_workflow">
+Based on user selection, route to appropriate workflow:
+
+- **Execute plan** → Show command for user to run after clearing:
+  ```
+  ---
+
+  ## ▶ Next Up
+
+  **{phase}-{plan}: [Plan Name]** — [objective from PLAN.md]
+
+  `/dgs:execute-phase {phase}`
+
+  <sub>`/clear` first → fresh context window</sub>
+
+  ---
+  ```
+- **Plan phase** → Show command for user to run after clearing:
+  ```
+  ---
+
+  ## ▶ Next Up
+
+  **Phase [N]: [Name]** — [Goal from ROADMAP.md]
+
+  `/dgs:plan-phase [phase-number]`
+
+  <sub>`/clear` first → fresh context window</sub>
+
+  ---
+
+  **Also available:**
+  - `/dgs:discuss-phase [N]` — gather context first
+  - `/dgs:research-phase [N]` — investigate unknowns
+
+  ---
+  ```
+- **Transition** → ./transition.md
+- **Check todos** → Read ${project_root}/todos/pending/, present summary
+- **Review alignment** → Read PROJECT.md, compare to current state
+- **Something else** → Ask what they need
+</step>
+
+<step name="update_session">
+Before proceeding to routed workflow, update session continuity:
+
+Update STATE.md:
+
+```markdown
+## Session Continuity
+
+Last session: [now]
+Stopped at: Session resumed, proceeding to [action]
+Resume file: [updated if applicable]
+```
+
+This ensures if session ends unexpectedly, next resume knows the state.
+</step>
+
+</process>
+
+<reconstruction>
+If STATE.md is missing but other artifacts exist:
+
+"STATE.md missing. Reconstructing from artifacts..."
+
+1. Read PROJECT.md → Extract "What This Is" and Core Value
+2. Read ROADMAP.md → Determine phases, find current position
+3. Scan \*-SUMMARY.md files → Extract decisions, concerns
+4. Count pending todos in ${project_root}/todos/pending/
+5. Check for .continue-here files → Session continuity
+
+Reconstruct and write STATE.md, then proceed normally.
+
+This handles cases where:
+
+- Project predates STATE.md introduction
+- File was accidentally deleted
+- Cloning repo without full planning state
+  </reconstruction>
+
+<quick_resume>
+If user says "continue" or "go":
+- Load state silently
+- Determine primary action
+- Execute immediately without presenting options
+
+"Continuing from [state]... [action]"
+</quick_resume>
+
+<success_criteria>
+Resume is complete when:
+
+- [ ] STATE.md loaded (or reconstructed)
+- [ ] Incomplete work detected and flagged
+- [ ] Clear status presented to user
+- [ ] Contextual next actions offered
+- [ ] User knows exactly where project stands
+- [ ] Session continuity updated
+      </success_criteria>

package/deliver-great-systems/workflows/rollback-job.md

@@ -0,0 +1,130 @@
+<purpose>
+Roll back all code changes made by a milestone job. Reads the job file for starting commit SHAs, shows a preview of what will be rolled back (repos + phases), confirms with the user (this is destructive), resets CODE repos only (NOT the planning repo), deletes SUMMARY.md files for phases that were executed by the job, and marks the job status as "rolled_back".
+</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 version from `$ARGUMENTS`.
+
+```
+VERSION = first argument from $ARGUMENTS
+```
+
+**If no version provided:**
+```
+Error: Version argument required. Usage: /dgs:rollback-job <version>
+```
+</step>
+
+<step name="locate_and_preview">
+Find the job file:
+
+```bash
+RESULT=$(node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs jobs find-job "$VERSION")
+```
+
+If not found, display error:
+```
+Error: No job found for version {VERSION}. Run /dgs:list-jobs to see available jobs.
+```
+
+Parse the job file:
+
+```bash
+JOB=$(node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs jobs parse "$JOB_PATH")
+```
+
+Check for `startShas` in the parsed result. If null/missing:
+```
+Error: Job {version} has no recorded starting SHAs. Only jobs run with SHA-recording enabled can be rolled back.
+```
+
+Display preview:
+
+```
+=== Rollback Preview: {version} ===
+
+Code repos that will be reset:
+{for each repo in startShas (skip _planning):}
+  - {repoName}: HEAD will be reset to {sha}
+
+Planning repo will NOT be modified.
+
+Phases whose SUMMARY.md files will be deleted:
+{list phases from completed execute-phase steps}
+
+WARNING: This is destructive. Code changes in the above repos will be permanently lost.
+```
+</step>
+
+<step name="confirm">
+Ask user for confirmation:
+
+```
+Type "rollback" to confirm, or anything else to cancel.
+```
+
+If user does not type exactly "rollback", display `Rollback cancelled.` and halt.
+</step>
+
+<step name="execute_rollback">
+Call the rollback CLI:
+
+```bash
+RESULT=$(node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs jobs rollback "$VERSION")
+```
+</step>
+
+<step name="display_result">
+Based on result:
+
+**If `rolledBack: true`:**
+```
+=== Rollback Complete: {version} ===
+
+Repos reset:
+{for each repo in repos_reset:}
+  - {name}: reset to {sha}
+
+SUMMARY files deleted:
+{for each file in summaries_deleted:}
+  - {file}
+
+Job status updated to: rolled_back
+```
+
+**If `rolledBack: false`:**
+Display the reason:
+- `not_found`: `No job found for version {version}.`
+- `no_start_shas`: `Job {version} has no recorded starting SHAs.`
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] Version extracted from arguments with error on missing
+- [ ] Job file located and parsed for startShas
+- [ ] Preview shows repos, SHAs, and phases that will be affected
+- [ ] User must type "rollback" to confirm (destructive operation)
+- [ ] Code repos reset via `git reset --hard` to recorded SHAs
+- [ ] Planning repo NOT touched
+- [ ] SUMMARY.md files deleted for executed phases
+- [ ] Job status updated to "rolled_back"
+</success_criteria>