mindforge-cc 9.0.0 → 10.0.0

package/.agent/workflows/mindforge-transition.md

@@ -1,671 +0,0 @@
-<internal_workflow>
-
-**This is an INTERNAL workflow — NOT a user-facing command.**
-
-There is no `/mindforge-transition` command. This workflow is invoked automatically by
-`execute-phase` during auto-advance, or inline by the orchestrator after phase
-verification. Users should never be told to run `/mindforge-transition`.
-
-**Valid user commands for phase progression:**
-- `/mindforge-discuss-phase {N}` — discuss a phase before planning
-- `/mindforge-plan-phase {N}` — plan a phase
-- `/mindforge-execute-phase {N}` — execute a phase
-- `/mindforge-progress` — see roadmap progress
-
-</internal_workflow>
-
-<required_reading>
-
-**Read these files NOW:**
-
-1. `.planning/STATE.md`
-2. `.planning/PROJECT.md`
-3. `.planning/ROADMAP.md`
-4. Current phase's plan files (`*-PLAN.md`)
-5. Current phase's summary files (`*-SUMMARY.md`)
-
-</required_reading>
-
-<purpose>
-
-Mark current phase complete and advance to next. This is the natural point where progress tracking and PROJECT.md evolution happen.
-
-"Planning next phase" = "current phase is done"
-
-</purpose>
-
-<process>
-
-<step name="load_project_state" priority="first">
-
-Before transition, read project state:
-
-```bash
-cat .planning/STATE.md 2>/dev/null
-cat .planning/PROJECT.md 2>/dev/null
-```
-
-Parse current position to verify we're transitioning the right phase.
-Note accumulated context that may need updating after transition.
-
-</step>
-
-<step name="verify_completion">
-
-Check current phase has all plan summaries:
-
-```bash
-ls .planning/phases/XX-current/*-PLAN.md 2>/dev/null | sort
-ls .planning/phases/XX-current/*-SUMMARY.md 2>/dev/null | sort
-```
-
-**Verification logic:**
-
-- Count PLAN files
-- Count SUMMARY files
-- If counts match: all plans complete
-- If counts don't match: incomplete
-
-<config-check>
-
-```bash
-cat .planning/config.json 2>/dev/null
-```
-
-</config-check>
-
-**Check for verification debt in this phase:**
-
-```bash
-# Count outstanding items in current phase
-OUTSTANDING=""
-for f in .planning/phases/XX-current/*-UAT.md .planning/phases/XX-current/*-VERIFICATION.md; do
-  [ -f "$f" ] || continue
-  grep -q "result: pending\|result: blocked\|status: partial\|status: human_needed\|status: diagnosed" "$f" && OUTSTANDING="$OUTSTANDING\n$(basename $f)"
-done
-```
-
-**If OUTSTANDING is not empty:**
-
-Append to the completion confirmation message (regardless of mode):
-
-```
-Outstanding verification items in this phase:
-{list filenames}
-
-These will carry forward as debt. Review: `/mindforge-audit-uat`
-```
-
-This does NOT block transition — it ensures the user sees the debt before confirming.
-
-**If all plans complete:**
-
-<if mode="yolo">
-
-```
-⚡ Auto-approved: Transition Phase [X] → Phase [X+1]
-Phase [X] complete — all [Y] plans finished.
-
-Proceeding to mark done and advance...
-```
-
-Proceed directly to cleanup_handoff step.
-
-</if>
-
-<if mode="interactive" OR="custom with gates.confirm_transition true">
-
-Ask: "Phase [X] complete — all [Y] plans finished. Ready to mark done and move to Phase [X+1]?"
-
-Wait for confirmation before proceeding.
-
-</if>
-
-**If plans incomplete:**
-
-**SAFETY RAIL: always_confirm_destructive applies here.**
-Skipping incomplete plans is destructive — ALWAYS prompt regardless of mode.
-
-Present:
-
-```
-Phase [X] has incomplete plans:
-- {phase}-01-SUMMARY.md ✓ Complete
-- {phase}-02-SUMMARY.md ✗ Missing
-- {phase}-03-SUMMARY.md ✗ Missing
-
-⚠️ Safety rail: Skipping plans requires confirmation (destructive action)
-
-Options:
-1. Continue current phase (execute remaining plans)
-2. Mark complete anyway (skip remaining plans)
-3. Review what's left
-```
-
-Wait for user decision.
-
-</step>
-
-<step name="cleanup_handoff">
-
-Check for lingering handoffs:
-
-```bash
-ls .planning/phases/XX-current/.continue-here*.md 2>/dev/null
-```
-
-If found, delete them — phase is complete, handoffs are stale.
-
-</step>
-
-<step name="update_roadmap_and_state">
-
-**Delegate ROADMAP.md and STATE.md updates to mindforge-tools:**
-
-```bash
-TRANSITION=$(node ".agent/bin/mindforge-tools.cjs" phase complete "${current_phase}")
-```
-
-The CLI handles:
-- Marking the phase checkbox as `[x]` complete with today's date
-- Updating plan count to final (e.g., "3/3 plans complete")
-- Updating the Progress table (Status → Complete, adding date)
-- Advancing STATE.md to next phase (Current Phase, Status → Ready to plan, Current Plan → Not started)
-- Detecting if this is the last phase in the milestone
-
-Extract from result: `completed_phase`, `plans_executed`, `next_phase`, `next_phase_name`, `is_last_phase`.
-
-</step>
-
-<step name="archive_prompts">
-
-If prompts were generated for the phase, they stay in place.
-The `completed/` subfolder pattern from create-meta-prompts handles archival.
-
-</step>
-
-<step name="evolve_project">
-
-Evolve PROJECT.md to reflect learnings from completed phase.
-
-**Read phase summaries:**
-
-```bash
-cat .planning/phases/XX-current/*-SUMMARY.md
-```
-
-**Assess requirement changes:**
-
-1. **Requirements validated?**
-   - Any Active requirements shipped in this phase?
-   - Move to Validated with phase reference: `- ✓ [Requirement] — Phase X`
-
-2. **Requirements invalidated?**
-   - Any Active requirements discovered to be unnecessary or wrong?
-   - Move to Out of Scope with reason: `- [Requirement] — [why invalidated]`
-
-3. **Requirements emerged?**
-   - Any new requirements discovered during building?
-   - Add to Active: `- [ ] [New requirement]`
-
-4. **Decisions to log?**
-   - Extract decisions from SUMMARY.md files
-   - Add to Key Decisions table with outcome if known
-
-5. **"What This Is" still accurate?**
-   - If the product has meaningfully changed, update the description
-   - Keep it current and accurate
-
-**Update PROJECT.md:**
-
-Make the edits inline. Update "Last updated" footer:
-
-```markdown
----
-*Last updated: [date] after Phase [X]*
-```
-
-**Example evolution:**
-
-Before:
-
-```markdown
-### Active
-
-- [ ] JWT authentication
-- [ ] Real-time sync < 500ms
-- [ ] Offline mode
-
-### Out of Scope
-
-- OAuth2 — complexity not needed for v1
-```
-
-After (Phase 2 shipped JWT auth, discovered rate limiting needed):
-
-```markdown
-### Validated
-
-- ✓ JWT authentication — Phase 2
-
-### Active
-
-- [ ] Real-time sync < 500ms
-- [ ] Offline mode
-- [ ] Rate limiting on sync endpoint
-
-### Out of Scope
-
-- OAuth2 — complexity not needed for v1
-```
-
-**Step complete when:**
-
-- [ ] Phase summaries reviewed for learnings
-- [ ] Validated requirements moved from Active
-- [ ] Invalidated requirements moved to Out of Scope with reason
-- [ ] Emerged requirements added to Active
-- [ ] New decisions logged with rationale
-- [ ] "What This Is" updated if product changed
-- [ ] "Last updated" footer reflects this transition
-
-</step>
-
-<step name="update_current_position_after_transition">
-
-**Note:** Basic position updates (Current Phase, Status, Current Plan, Last Activity) were already handled by `mindforge-tools phase complete` in the update_roadmap_and_state step.
-
-Verify the updates are correct by reading STATE.md. If the progress bar needs updating, use:
-
-```bash
-PROGRESS=$(node ".agent/bin/mindforge-tools.cjs" progress bar --raw)
-```
-
-Update the progress bar line in STATE.md with the result.
-
-**Step complete when:**
-
-- [ ] Phase number incremented to next phase (done by phase complete)
-- [ ] Plan status reset to "Not started" (done by phase complete)
-- [ ] Status shows "Ready to plan" (done by phase complete)
-- [ ] Progress bar reflects total completed plans
-
-</step>
-
-<step name="update_project_reference">
-
-Update Project Reference section in STATE.md.
-
-```markdown
-## Project Reference
-
-See: .planning/PROJECT.md (updated [today])
-
-**Core value:** [Current core value from PROJECT.md]
-**Current focus:** [Next phase name]
-```
-
-Update the date and current focus to reflect the transition.
-
-</step>
-
-<step name="review_accumulated_context">
-
-Review and update Accumulated Context section in STATE.md.
-
-**Decisions:**
-
-- Note recent decisions from this phase (3-5 max)
-- Full log lives in PROJECT.md Key Decisions table
-
-**Blockers/Concerns:**
-
-- Review blockers from completed phase
-- If addressed in this phase: Remove from list
-- If still relevant for future: Keep with "Phase X" prefix
-- Add any new concerns from completed phase's summaries
-
-**Example:**
-
-Before:
-
-```markdown
-### Blockers/Concerns
-
-- ⚠️ [Phase 1] Database schema not indexed for common queries
-- ⚠️ [Phase 2] WebSocket reconnection behavior on flaky networks unknown
-```
-
-After (if database indexing was addressed in Phase 2):
-
-```markdown
-### Blockers/Concerns
-
-- ⚠️ [Phase 2] WebSocket reconnection behavior on flaky networks unknown
-```
-
-**Step complete when:**
-
-- [ ] Recent decisions noted (full log in PROJECT.md)
-- [ ] Resolved blockers removed from list
-- [ ] Unresolved blockers kept with phase prefix
-- [ ] New concerns from completed phase added
-
-</step>
-
-<step name="update_session_continuity_after_transition">
-
-Update Session Continuity section in STATE.md to reflect transition completion.
-
-**Format:**
-
-```markdown
-Last session: [today]
-Stopped at: Phase [X] complete, ready to plan Phase [X+1]
-Resume file: None
-```
-
-**Step complete when:**
-
-- [ ] Last session timestamp updated to current date and time
-- [ ] Stopped at describes phase completion and next phase
-- [ ] Resume file confirmed as None (transitions don't use resume files)
-
-</step>
-
-<step name="offer_next_phase">
-
-**MANDATORY: Verify milestone status before presenting next steps.**
-
-**Use the transition result from `mindforge-tools phase complete`:**
-
-The `is_last_phase` field from the phase complete result tells you directly:
-- `is_last_phase: false` → More phases remain → Go to **Route A**
-- `is_last_phase: true` → Last phase done → **Check for workstream collisions first**
-
-The `next_phase` and `next_phase_name` fields give you the next phase details.
-
-If you need additional context, use:
-```bash
-ROADMAP=$(node ".agent/bin/mindforge-tools.cjs" roadmap analyze)
-```
-
-This returns all phases with goals, disk status, and completion info.
-
----
-
-**Workstream collision check (when `is_last_phase: true`):**
-
-Before routing to Route B, check whether other workstreams are still active.
-This prevents one workstream from advancing or completing the milestone while
-other workstreams are still working on their phases.
-
-**Skip this check if NOT in workstream mode** (i.e., `MindForge_WORKSTREAM` is not set / flat mode).
-In flat mode, go directly to **Route B**.
-
-```bash
-# Only check if we're in workstream mode
-if [ -n "$MindForge_WORKSTREAM" ]; then
-  WS_LIST=$(node ".agent/bin/mindforge-tools.cjs" workstream list --raw)
-fi
-```
-
-Parse the JSON result. The output has `{ mode, workstreams: [...] }`.
-Each workstream entry has: `name`, `status`, `current_phase`, `phase_count`, `completed_phases`.
-
-Filter out the current workstream (`$MindForge_WORKSTREAM`) and any workstreams with
-status containing "milestone complete" or "archived" (case-insensitive).
-The remaining entries are **other active workstreams**.
-
-- **If other active workstreams exist** → Go to **Route B1**
-- **If NO other active workstreams** (or flat mode) → Go to **Route B**
-
----
-
-**Route A: More phases remain in milestone**
-
-Read ROADMAP.md to get the next phase's name and goal.
-
-**Check if next phase has CONTEXT.md:**
-
-```bash
-ls .planning/phases/*[X+1]*/*-CONTEXT.md 2>/dev/null
-```
-
-**If next phase exists:**
-
-<if mode="yolo">
-
-**If CONTEXT.md exists:**
-
-```
-Phase [X] marked complete.
-
-Next: Phase [X+1] — [Name]
-
-⚡ Auto-continuing: Plan Phase [X+1] in detail
-```
-
-Exit skill and invoke SlashCommand("/mindforge-plan-phase [X+1] --auto ${MindForge_WS}")
-
-**If CONTEXT.md does NOT exist:**
-
-```
-Phase [X] marked complete.
-
-Next: Phase [X+1] — [Name]
-
-⚡ Auto-continuing: Discuss Phase [X+1] first
-```
-
-Exit skill and invoke SlashCommand("/mindforge-discuss-phase [X+1] --auto ${MindForge_WS}")
-
-</if>
-
-<if mode="interactive" OR="custom with gates.confirm_transition true">
-
-**If CONTEXT.md does NOT exist:**
-
-```
-## ✓ Phase [X] Complete
-
----
-
-## ▶ Next Up
-
-**Phase [X+1]: [Name]** — [Goal from ROADMAP.md]
-
-`/mindforge-discuss-phase [X+1] ${MindForge_WS}` — gather context and clarify approach
-
-<sub>`/clear` first → fresh context window</sub>
-
----
-
-**Also available:**
-- `/mindforge-plan-phase [X+1] ${MindForge_WS}` — skip discussion, plan directly
-- `/mindforge-research-phase [X+1] ${MindForge_WS}` — investigate unknowns
-
----
-```
-
-**If CONTEXT.md exists:**
-
-```
-## ✓ Phase [X] Complete
-
----
-
-## ▶ Next Up
-
-**Phase [X+1]: [Name]** — [Goal from ROADMAP.md]
-<sub>✓ Context gathered, ready to plan</sub>
-
-`/mindforge-plan-phase [X+1] ${MindForge_WS}`
-
-<sub>`/clear` first → fresh context window</sub>
-
----
-
-**Also available:**
-- `/mindforge-discuss-phase [X+1] ${MindForge_WS}` — revisit context
-- `/mindforge-research-phase [X+1] ${MindForge_WS}` — investigate unknowns
-
----
-```
-
-</if>
-
----
-
-**Route B1: Workstream done, other workstreams still active**
-
-This route is reached when `is_last_phase: true` AND the collision check found
-other active workstreams. Do NOT suggest completing the milestone or advancing
-to the next milestone — other workstreams are still working.
-
-**Clear auto-advance chain flag** — workstream boundary is the natural stopping point:
-
-```bash
-node ".agent/bin/mindforge-tools.cjs" config-set workflow._auto_chain_active false
-```
-
-<if mode="yolo">
-
-Override auto-advance: do NOT auto-continue to milestone completion.
-Present the blocking information and stop.
-
-</if>
-
-Present (all modes):
-
-```
-## ✓ Phase {X}: {Phase Name} Complete
-
-This workstream's phases are complete. Other workstreams are still active:
-
-| Workstream | Status | Phase | Progress |
-|------------|--------|-------|----------|
-| {name}     | {status} | {current_phase} | {completed_phases}/{phase_count} |
-| ...        | ...    | ...   | ...      |
-
----
-
-## Next Steps
-
-Archive this workstream:
-
-`/mindforge-workstreams complete {current_ws_name} ${MindForge_WS}`
-
-See overall milestone progress:
-
-`/mindforge-workstreams progress ${MindForge_WS}`
-
-<sub>Milestone completion will be available once all workstreams finish.</sub>
-
----
-```
-
-Do NOT suggest `/mindforge-complete-milestone` or `/mindforge-new-milestone`.
-Do NOT auto-invoke any further slash commands.
-
-**Stop here.** The user must explicitly decide what to do next.
-
----
-
-**Route B: Milestone complete (all phases done)**
-
-**This route is only reached when:**
-- `is_last_phase: true` AND no other active workstreams exist (or flat mode)
-
-**Clear auto-advance chain flag** — milestone boundary is the natural stopping point:
-
-```bash
-node ".agent/bin/mindforge-tools.cjs" config-set workflow._auto_chain_active false
-```
-
-<if mode="yolo">
-
-```
-Phase {X} marked complete.
-
-🎉 Milestone {version} is 100% complete — all {N} phases finished!
-
-⚡ Auto-continuing: Complete milestone and archive
-```
-
-Exit skill and invoke SlashCommand("/mindforge-complete-milestone {version} ${MindForge_WS}")
-
-</if>
-
-<if mode="interactive" OR="custom with gates.confirm_transition true">
-
-```
-## ✓ Phase {X}: {Phase Name} Complete
-
-🎉 Milestone {version} is 100% complete — all {N} phases finished!
-
----
-
-## ▶ Next Up
-
-**Complete Milestone {version}** — archive and prepare for next
-
-`/mindforge-complete-milestone {version} ${MindForge_WS}`
-
-<sub>`/clear` first → fresh context window</sub>
-
----
-
-**Also available:**
-- Review accomplishments before archiving
-
----
-```
-
-</if>
-
-</step>
-
-</process>
-
-<implicit_tracking>
-Progress tracking is IMPLICIT: planning phase N implies phases 1-(N-1) complete. No separate progress step—forward motion IS progress.
-</implicit_tracking>
-
-<partial_completion>
-
-If user wants to move on but phase isn't fully complete:
-
-```
-Phase [X] has incomplete plans:
-- {phase}-02-PLAN.md (not executed)
-- {phase}-03-PLAN.md (not executed)
-
-Options:
-1. Mark complete anyway (plans weren't needed)
-2. Defer work to later phase
-3. Stay and finish current phase
-```
-
-Respect user judgment — they know if work matters.
-
-**If marking complete with incomplete plans:**
-
-- Update ROADMAP: "2/3 plans complete" (not "3/3")
-- Note in transition message which plans were skipped
-
-</partial_completion>
-
-<success_criteria>
-
-Transition is complete when:
-
-- [ ] Current phase plan summaries verified (all exist or user chose to skip)
-- [ ] Any stale handoffs deleted
-- [ ] ROADMAP.md updated with completion status and plan count
-- [ ] PROJECT.md evolved (requirements, decisions, description if needed)
-- [ ] STATE.md updated (position, project reference, context, session)
-- [ ] Progress table updated
-- [ ] User knows next steps
-
-</success_criteria>