maxsimcli 5.0.6 → 5.1.0

package/dist/assets/templates/workflows/progress.md

@@ -1,379 +1,145 @@
 <purpose>
-Check project progress, milestone status, and offer milestone completion when all phases are done. Reads status from live GitHub queries (always-live, no cached state). Detects phase gaps and intelligently routes to the next action.
+Show project status from GitHub Issues (sole source of truth) and recommend the next action based on live board state.
 </purpose>
 
-<required_reading>
-Read all files referenced by the invoking prompt's execution_context before starting.
-</required_reading>
-
 <process>
 
-<step name="init_context">
-**Load progress context (paths only):**
-
-```bash
-INIT=$(node ~/.claude/maxsim/bin/maxsim-tools.cjs init progress)
-```
-
-Extract from init JSON: `project_exists`, `roadmap_exists`, `state_exists`, `phases`, `current_phase`, `next_phase`, `milestone_version`, `completed_count`, `phase_count`, `paused_at`, `state_path`, `roadmap_path`, `project_path`, `config_path`.
-
-If `project_exists` is false (no `.planning/` directory):
-
-```
-No planning structure found.
-
-Run /maxsim:init to start a new project.
-```
-
-Exit.
-
-If missing STATE.md: suggest `/maxsim:init`.
-
-**If ROADMAP.md missing but PROJECT.md exists:**
-
-This means a milestone was completed and archived. Go to **Route F** (between milestones).
-
-If missing both ROADMAP.md and PROJECT.md: suggest `/maxsim:init`.
-</step>
-
-<step name="load">
-**Load local project context (always from local files per WIRE-02):**
-
-Use targeted tools to get data needed for the report:
-- `STATE=$(node ~/.claude/maxsim/bin/maxsim-tools.cjs state-snapshot)`
-
-Read local files for project context:
-- `.planning/config.json` — model profile, workflow flags
-- `.planning/PROJECT.md` — project name and vision
-- `.planning/REQUIREMENTS.md` — requirements context
-- `.planning/STATE.md` — decisions, blockers, metrics
-
-This minimizes orchestrator context usage.
-</step>
-
-<step name="live_github_phase_overview">
-**Get live phase status from GitHub (primary source — always-live, no cached state):**
-
-Run `github all-progress` to get progress for all phases. This returns live data from GitHub Issues:
-
-```bash
-node ~/.claude/maxsim/bin/maxsim-tools.cjs github all-progress
-```
-
-Returns: `phase_number`, `title`, `issue_number`, `total_tasks`, `completed_tasks`, `remaining_tasks`, `status` (the GitHub board column: To Do / In Progress / In Review / Done)
-
-Display as formatted table:
-
-```
-## GitHub Issues Progress (Live)
-
-| Phase | Title | Issue | Completed | Total | Remaining | Status |
-|-------|-------|-------|-----------|-------|-----------|--------|
-| 01    | ...   | #12   | 3         | 5     | 2         | In Progress |
-| 02    | ...   | #13   | 0         | 4     | 4         | To Do |
-```
-
-**Also get board column view:**
-
-Run `github query-board` with the project number (from init context / config). Group items by status column (To Do, In Progress, In Review, Done). Display column counts and issue details:
+## Step 1: Query GitHub Project Board
 
 ```bash
-node ~/.claude/maxsim/bin/maxsim-tools.cjs github query-board --project-number PROJECT_NUMBER
-```
-
-```
-## Board Status (Live)
-
-| Column      | Count | Issues |
-|-------------|-------|--------|
-| To Do       | 2     | #13, #14 |
-| In Progress | 1     | #12 |
-| In Review   | 0     | — |
-| Done        | 3     | #9, #10, #11 |
+node ~/.claude/maxsim/bin/maxsim-tools.cjs github status
 ```
 
-**Cross-reference with local ROADMAP.md (for phase ordering only -- GitHub is authoritative for status):**
-- Run `ROADMAP=$(node ~/.claude/maxsim/bin/maxsim-tools.cjs roadmap analyze)` to get local phase ordering data
-- If local ROADMAP phase list differs from GitHub Issues, note in Issues Detected section (GitHub is the source of truth)
-</step>
+Parse JSON response for:
+- `project_name` — project title
+- `phases[]` — array of `{ number, title, issue_number, status, tasks_total, tasks_done }`
+- `milestone` — `{ title, due_date, open_issues, closed_issues }`
+- `blockers[]` — open issues with label "type:blocker" or "type:bug"
 
-<step name="live_github_detail">
-**Per-phase detail (when user requests or for current phase):**
+If the command fails (GitHub unreachable), display:
 
-For the current active phase (or any phase requested by user):
-- Run `github phase-progress` with the phase issue number to get task-level progress
-- Run `github list-sub-issues` to get individual task status with sub-issue details
-- Display task breakdown with status indicators (✓ done / ⏳ in progress / ○ to do)
-
-```bash
-node ~/.claude/maxsim/bin/maxsim-tools.cjs github phase-progress --phase-issue-number N
-node ~/.claude/maxsim/bin/maxsim-tools.cjs github list-sub-issues --phase-issue-number N
 ```
-
-**Detect external edits:**
-
-After reading phase data from GitHub, run `github detect-external-edits` for each phase with the stored `body_hash`. Warn in the Issues Detected section if modifications were detected outside the normal workflow.
-
-```bash
-node ~/.claude/maxsim/bin/maxsim-tools.cjs github detect-external-edits --phase-number "XX"
+GitHub is unavailable. Cannot show progress.
+Run: gh auth status   — to check authentication
 ```
-</step>
 
-<step name="position">
-**Parse current position from init context and live GitHub data:**
+Stop. Do not fall back to local files.
 
-- Use `current_phase` and `next_phase` from `$ROADMAP` (local) cross-referenced with GitHub board status
-- Note `paused_at` if work was paused (from `$STATE`)
-- Check for interrupted phases via `github detect-interrupted`
+---
 
-```bash
-node ~/.claude/maxsim/bin/maxsim-tools.cjs github detect-interrupted --phase-issue-number N
-```
-</step>
+## Step 2: Get milestone progress
 
-<step name="report">
-**Generate progress bar from maxsim-tools, then present rich status report:**
+Calculate from phases:
 
-```bash
-# Get formatted progress bar (local computation)
-PROGRESS_BAR=$(node ~/.claude/maxsim/bin/maxsim-tools.cjs progress phase-bars --raw)
 ```
+total_phases   = phases.length
+done_phases    = phases where status == "Done"
+overall_pct    = (done_phases / total_phases) * 100
 
-Present (GitHub Issues is the primary progress source; local ROADMAP is cross-validation):
-
+milestone_open   = milestone.open_issues
+milestone_closed = milestone.closed_issues
+milestone_pct    = (milestone_closed / (milestone_open + milestone_closed)) * 100
 ```
-# [Project Name]
-
-**Progress:** {PROGRESS_BAR}
-**Profile:** [quality/balanced/budget]
-
-## GitHub Issues Progress (Live)
-[formatted table from github all-progress — see live_github_phase_overview step]
-
-## Board Status (Live)
-[column view from github query-board — see live_github_phase_overview step]
-
-## Current Position
-Phase [N] of [total]: [phase-name]
-GitHub Status: [board column from live data]
-CONTEXT: [✓ if has_context | - if not]
-
-## Key Decisions Made
-- [extract from $STATE.decisions[]]
-- [e.g. jq -r '.decisions[].decision' from state-snapshot]
 
-## Blockers/Concerns
-- [extract from $STATE.blockers[]]
-- [e.g. jq -r '.blockers[].text' from state-snapshot]
+---
 
-## Issues Detected
-(Only show if gaps found during analysis)
-- Phase [N]: [issue description, e.g., "External edit detected — body_hash mismatch"]
-- Phase [M]: [issue description, e.g., "Local: complete, GitHub: In Progress — discrepancy"]
+## Step 3: Display summary
 
-## What's Next
-[Next phase/plan objective from live GitHub data and local roadmap]
 ```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ MAXSIM ► $project_name
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-**Performance metrics table truncation:**
-
-When displaying the performance metrics table from STATE.md (the `## Performance Metrics` section):
-- Show only the **last 20 entries** (most recent) by default.
-- If there are more than 20 metric entries in STATE.md, add a note above the table: `Showing last 20 of {total} metrics entries.`
-- This is a **display-time truncation only** — STATE.md retains all metrics as the source of truth. Do not modify or remove older entries from STATE.md.
-- If there are 20 or fewer entries, show all without any truncation note.
+Overall: [$overall_pct%] $done_phases of $total_phases phases complete
 
-</step>
+## Phases
 
-<step name="route">
-**Determine next action based on live GitHub data.**
+| # | Title | Issue | Status | Tasks |
+|---|-------|-------|--------|-------|
+| 01 | [name] | #12 | Done | 5/5 |
+| 02 | [name] | #13 | In Progress | 3/5 |
+| 03 | [name] | #14 | To Do | 0/4 |
 
-**Step 1: Get live phase state from GitHub**
+## Milestone: $milestone.title
 
-Use `github all-progress` output (already fetched above). Identify:
-- Phases with status "In Progress" that have remaining tasks
-- Phases with status "To Do" (not yet started)
-- Phases with status "Done"
+Completion: $milestone_pct% ($milestone_closed closed / $milestone_open open)
+Due: $milestone.due_date (or "No due date")
 
-**Step 1.5: Check for interrupted or external edit issues**
+## Blockers
 
-Run `github detect-interrupted` to check for any phases that were interrupted mid-execution. If any are found, note them — they take priority over new work.
-
-```bash
-node ~/.claude/maxsim/bin/maxsim-tools.cjs github detect-interrupted --phase-issue-number N
+[List each item from blockers[] as: - #N: title]
+(If empty: "None")
 ```
 
-**Step 2: Route based on live GitHub status**
-
-| Condition | Meaning | Action |
-|-----------|---------|--------|
-| Interrupted phase detected | Work was cut off | Go to **Route A** (resume) |
-| Phase "In Progress" with remaining tasks | Unfinished execution | Go to **Route A** (continue) |
-| Phase "To Do" | Phase not yet started | Go to **Route B** |
-| All phases "Done" | Milestone complete | Go to **Route D** |
-
----
-
-**Route A: Phase in progress or interrupted — continue execution**
-
-Identify the in-progress or interrupted phase (from `github all-progress` or `github detect-interrupted`).
+Board column breakdown (from `github status` output):
 
 ```
----
-
-## ▶ Next Up
-
-**Phase {N}: [Phase Name]** — resuming execution
-
-`/maxsim:execute {phase}`
-
-<sub>`/clear` first → fresh context window</sub>
-
----
+| Column      | Count |
+|-------------|-------|
+| To Do       | N     |
+| In Progress | N     |
+| In Review   | N     |
+| Done        | N     |
 ```
 
 ---
 
-**Route B: Phase needs planning**
-
-Check if a `<!-- maxsim:type=context -->` comment exists on the phase GitHub Issue.
+## Step 4: Recommend next action
 
-**If context comment exists:**
+Evaluate phase statuses in order:
 
+**If any phase is "In Progress":**
 ```
----
-
-## ▶ Next Up
+## Next Action
 
-**Phase {N}: {Name}** — {Goal from ROADMAP.md}
-<sub>✓ Context gathered, ready to plan</sub>
+Phase [N] — [Title] is in progress.
 
-`/maxsim:plan {phase-number}`
-
-<sub>`/clear` first → fresh context window</sub>
-
----
+/maxsim:execute [N]   — continue execution
+/maxsim:plan [N]      — review or revise plans
 ```
 
-**If no context comment exists:**
-
+**If all phases are "To Do" (nothing started):**
 ```
----
-
-## ▶ Next Up
-
-**Phase {N}: {Name}** — {Goal from ROADMAP.md}
-<sub>No context comment yet — /maxsim:plan will start with discussion</sub>
+## Next Action
 
-`/maxsim:plan {phase}`
+No phases started yet.
 
-<sub>`/clear` first → fresh context window</sub>
-
----
+/maxsim:plan 1   — begin planning the first phase
 ```
 
----
-
-**Route C: Phase complete, more phases remain**
-
-Read ROADMAP.md to get the next phase's name and goal.
-
+**If first unstarted phase exists (some phases Done, next is To Do):**
 ```
----
-
-## ✓ Phase {Z} Complete
-
-## ▶ Next Up
-
-**Phase {Z+1}: {Name}** — {Goal from ROADMAP.md}
+## Next Action
 
-`/maxsim:plan {Z+1}` — starts with discussion, then plans
+Phase [N] — [Title] is next.
 
-<sub>`/clear` first → fresh context window</sub>
-
----
+/maxsim:plan [N]   — plan this phase
 ```
 
----
-
-**Route D: Milestone complete**
-
-All phases are "Done" on the GitHub board. Offer milestone completion interactively:
-
+**If all phases are "Done":**
 ```
----
-
-## Milestone Complete!
+## Next Action
 
-All {N} phases are complete (all "Done" on GitHub board). Ready to wrap up?
+All phases complete! Ready to wrap up the milestone.
 
-1. Complete milestone (archive, create release notes) → `/maxsim:init` (detects milestone completion)
-2. Start new milestone → `/maxsim:init` (starts new milestone flow)
-3. Just show me the progress (stay on this screen)
-
-<sub>`/clear` first → fresh context window</sub>
-
----
+/maxsim:init   — close milestone and start the next
 ```
 
-If user chooses option 1 or 2: route to `/maxsim:init` which handles milestone lifecycle interactively.
-If user chooses option 3: display progress report only, no routing.
-
----
-
-**Route F: Between milestones (ROADMAP.md missing, PROJECT.md exists)**
-
-A milestone was completed and archived. Ready to start the next milestone cycle.
-
-Read MILESTONES.md to find the last completed milestone version.
-
+**If blockers exist:** Prepend to next-action section:
 ```
----
-
-## ✓ Milestone v{X.Y} Complete
-
-Ready to plan the next milestone.
-
-## ▶ Next Up
-
-**Start Next Milestone** — questioning → research → requirements → roadmap
+## Blockers to Resolve First
 
-`/maxsim:init`
-
-<sub>`/clear` first → fresh context window</sub>
-
----
+- #N: [title] — resolve before continuing
 ```
 
-</step>
-
-<step name="edge_cases">
-**Handle edge cases:**
-
-- Phase complete but next phase not planned → offer `/maxsim:plan [next]`
-- All work complete → offer milestone completion via `/maxsim:init`
-- Blockers present → highlight before offering to continue
-- External edits detected → surface in Issues Detected section before routing
-- Discrepancy between local ROADMAP and GitHub board → surface in Issues Detected (GitHub is authoritative)
-- GitHub not available (CLI calls fail) → show error: "GitHub integration required for progress tracking. Run `/maxsim:init` to configure GitHub." Do NOT fall back to local file scanning.
-  </step>
-
 </process>
 
 <success_criteria>
-
-- [ ] Rich context provided (decisions, blockers, issues)
-- [ ] GitHub Issues progress shown as primary source (always-live reads via `github all-progress`)
-- [ ] Board column view shown via `github query-board`
-- [ ] Per-phase task detail available via `github phase-progress` and `github list-sub-issues`
-- [ ] External edit detection via `github detect-external-edits`
-- [ ] Cross-reference local ROADMAP.md for phase ordering (GitHub is authoritative for status)
-- [ ] Phase gaps and discrepancies detected and surfaced in Issues Detected section
-- [ ] Current position clear with visual progress
-- [ ] What's next clearly explained
-- [ ] Smart routing: /maxsim:execute if in progress, /maxsim:plan if not started
-- [ ] Milestone completion offered when all phases done
-- [ ] User confirms before any action
-- [ ] Seamless handoff to appropriate maxsim command
-      </success_criteria>
-</output>
+- [ ] GitHub project board queried via maxsim-tools (not local files)
+- [ ] Overall progress percentage shown
+- [ ] Phases displayed by status (To Do / In Progress / In Review / Done)
+- [ ] Current milestone and its completion % shown
+- [ ] Open blockers/bugs listed
+- [ ] Next action recommended based on live board state
+- [ ] Graceful error if GitHub is unavailable
+</success_criteria>