npm - maxsimcli - Versions diffs - 4.7.1 → 4.9.0 - Mend

maxsimcli 4.7.1 → 4.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (161) hide show

package/dist/assets/templates/workflows/complete-milestone.md DELETED Viewed

@@ -1,701 +0,0 @@
-<purpose>
-Mark a shipped version (v1.0, v1.1, v2.0) as complete. Creates historical record in MILESTONES.md, performs full PROJECT.md evolution review, reorganizes ROADMAP.md with milestone groupings, and tags the release in git.
-</purpose>
-<required_reading>
-1. templates/milestone.md
-2. templates/milestone-archive.md
-3. `.planning/ROADMAP.md`
-4. `.planning/REQUIREMENTS.md`
-5. `.planning/PROJECT.md`
-@./references/dashboard-bridge.md
-</required_reading>
-<archival_behavior>
-When a milestone completes:
-1. Extract full milestone details to `.planning/milestones/v[X.Y]-ROADMAP.md`
-2. Archive requirements to `.planning/milestones/v[X.Y]-REQUIREMENTS.md`
-3. Update ROADMAP.md — replace milestone details with one-line summary
-4. Delete REQUIREMENTS.md (fresh one for next milestone)
-5. Perform full PROJECT.md evolution review
-6. Offer to create next milestone inline
-**Context Efficiency:** Archives keep ROADMAP.md constant-size and REQUIREMENTS.md milestone-scoped.
-**ROADMAP archive** uses `templates/milestone-archive.md` — includes milestone header (status, phases, date), full phase details, milestone summary (decisions, issues, tech debt).
-**REQUIREMENTS archive** contains all requirements marked complete with outcomes, traceability table with final status, notes on changed requirements.
-</archival_behavior>
-<process>
-<step name="verify_readiness">
-**Use `roadmap analyze` for comprehensive readiness check:**
-```bash
-ROADMAP=$(node ~/.claude/maxsim/bin/maxsim-tools.cjs roadmap analyze)
-```
-This returns all phases with plan/summary counts and disk status. Use this to verify:
-- Which phases belong to this milestone?
-- All phases complete (all plans have summaries)? Check `disk_status === 'complete'` for each.
-- `progress_percent` should be 100%.
-**Requirements completion check (REQUIRED before presenting):**
-Parse REQUIREMENTS.md traceability table:
-- Count total v1 requirements vs checked-off (`[x]`) requirements
-- Identify any non-Complete rows in the traceability table
-Present:
-```
-Milestone: [Name, e.g., "v1.0 MVP"]
-Includes:
-- Phase 1: Foundation (2/2 plans complete)
-- Phase 2: Authentication (2/2 plans complete)
-- Phase 3: Core Features (3/3 plans complete)
-- Phase 4: Polish (1/1 plan complete)
-Total: {phase_count} phases, {total_plans} plans, all complete
-Requirements: {N}/{M} v1 requirements checked off
-```
-**If requirements incomplete** (N < M):
-```
-⚠ Unchecked Requirements:
-- [ ] {REQ-ID}: {description} (Phase {X})
-- [ ] {REQ-ID}: {description} (Phase {Y})
-```
-MUST present 3 options:
-1. **Proceed anyway** — mark milestone complete with known gaps
-2. **Run audit first** — `/maxsim:audit-milestone` to assess gap severity
-3. **Abort** — return to development
-If user selects "Proceed anyway": note incomplete requirements in MILESTONES.md under `### Known Gaps` with REQ-IDs and descriptions.
-<config-check>
-```bash
-cat .planning/config.json 2>/dev/null
-```
-</config-check>
-<if mode="yolo">
-```
-⚡ Auto-approved: Milestone scope verification
-[Show breakdown summary without prompting]
-Proceeding to stats gathering...
-```
-Proceed to gather_stats.
-</if>
-<if mode="interactive" OR="custom with gates.confirm_milestone_scope true">
-```
-Ready to mark this milestone as shipped?
-(yes / wait / adjust scope)
-```
-Wait for confirmation.
-- "adjust scope": Ask which phases to include.
-- "wait": Stop, user returns when ready.
-</if>
-</step>
-<step name="gather_stats">
-Calculate milestone statistics:
-```bash
-git log --oneline --grep="feat(" | head -20
-git diff --stat FIRST_COMMIT..LAST_COMMIT | tail -1
-git ls-files --cached --exclude-standard -- "*.swift" "*.ts" "*.py" | xargs wc -l 2>/dev/null
-git log --format="%ai" FIRST_COMMIT | tail -1
-git log --format="%ai" LAST_COMMIT | head -1
-```
-Present:
-```
-Milestone Stats:
-- Phases: [X-Y]
-- Plans: [Z] total
-- Tasks: [N] total (from phase summaries)
-- Files modified: [M]
-- Lines of code: [LOC] [language]
-- Timeline: [Days] days ([Start] → [End])
-- Git range: feat(XX-XX) → feat(YY-YY)
-```
-</step>
-<step name="extract_accomplishments">
-Extract one-liners from SUMMARY.md files using summary-extract:
-```bash
-# For each phase in milestone, extract one-liner
-for summary in .planning/phases/*-*/*-SUMMARY.md; do
-  node ~/.claude/maxsim/bin/maxsim-tools.cjs summary-extract "$summary" --fields one_liner | jq -r '.one_liner'
-done
-```
-Extract 4-6 key accomplishments. Present:
-```
-Key accomplishments for this milestone:
-1. [Achievement from phase 1]
-2. [Achievement from phase 2]
-3. [Achievement from phase 3]
-4. [Achievement from phase 4]
-5. [Achievement from phase 5]
-```
-</step>
-<step name="create_milestone_entry">
-**Note:** MILESTONES.md entry is now created automatically by `maxsim-tools milestone complete` in the archive_milestone step. The entry includes version, date, phase/plan/task counts, and accomplishments extracted from SUMMARY.md files.
-If additional details are needed (e.g., user-provided "Delivered" summary, git range, LOC stats), add them manually after the CLI creates the base entry.
-</step>
-<step name="evolve_project_full_review">
-Full PROJECT.md evolution review at milestone completion.
-Read all phase summaries:
-```bash
-cat .planning/phases/*-*/*-SUMMARY.md
-```
-**Full review checklist:**
-1. **"What This Is" accuracy:**
-   - Compare current description to what was built
-   - Update if product has meaningfully changed
-2. **Core Value check:**
-   - Still the right priority? Did shipping reveal a different core value?
-   - Update if the ONE thing has shifted
-3. **Requirements audit:**
-   **Validated section:**
-   - All Active requirements shipped this milestone → Move to Validated
-   - Format: `- ✓ [Requirement] — v[X.Y]`
-   **Active section:**
-   - Remove requirements moved to Validated
-   - Add new requirements for next milestone
-   - Keep unaddressed requirements
-   **Out of Scope audit:**
-   - Review each item — reasoning still valid?
-   - Remove irrelevant items
-   - Add requirements invalidated during milestone
-4. **Context update:**
-   - Current codebase state (LOC, tech stack)
-   - User feedback themes (if any)
-   - Known issues or technical debt
-5. **Key Decisions audit:**
-   - Extract all decisions from milestone phase summaries
-   - Add to Key Decisions table with outcomes
-   - Mark ✓ Good, ⚠️ Revisit, or — Pending
-6. **Constraints check:**
-   - Any constraints changed during development? Update as needed
-Update PROJECT.md inline. Update "Last updated" footer:
-```markdown
----
-*Last updated: [date] after v[X.Y] milestone*
-```
-**Example full evolution (v1.0 → v1.1 prep):**
-Before:
-```markdown
-## What This Is
-A real-time collaborative whiteboard for remote teams.
-## Core Value
-Real-time sync that feels instant.
-## Requirements
-### Validated
-(None yet — ship to validate)
-### Active
-- [ ] Canvas drawing tools
-- [ ] Real-time sync < 500ms
-- [ ] User authentication
-- [ ] Export to PNG
-### Out of Scope
-- Mobile app — web-first approach
-- Video chat — use external tools
-```
-After v1.0:
-```markdown
-## What This Is
-A real-time collaborative whiteboard for remote teams with instant sync and drawing tools.
-## Core Value
-Real-time sync that feels instant.
-## Requirements
-### Validated
-- ✓ Canvas drawing tools — v1.0
-- ✓ Real-time sync < 500ms — v1.0 (achieved 200ms avg)
-- ✓ User authentication — v1.0
-### Active
-- [ ] Export to PNG
-- [ ] Undo/redo history
-- [ ] Shape tools (rectangles, circles)
-### Out of Scope
-- Mobile app — web-first approach, PWA works well
-- Video chat — use external tools
-- Offline mode — real-time is core value
-## Context
-Shipped v1.0 with 2,400 LOC TypeScript.
-Tech stack: Next.js, Supabase, Canvas API.
-Initial user testing showed demand for shape tools.
-```
-**Step complete when:**
-- [ ] "What This Is" reviewed and updated if needed
-- [ ] Core Value verified as still correct
-- [ ] All shipped requirements moved to Validated
-- [ ] New requirements added to Active for next milestone
-- [ ] Out of Scope reasoning audited
-- [ ] Context updated with current state
-- [ ] All milestone decisions added to Key Decisions
-- [ ] "Last updated" footer reflects milestone completion
-</step>
-<step name="reorganize_roadmap">
-Update `.planning/ROADMAP.md` — group completed milestone phases:
-```markdown
-# Roadmap: [Project Name]
-## Milestones
-- ✅ **v1.0 MVP** — Phases 1-4 (shipped YYYY-MM-DD)
-- 🚧 **v1.1 Security** — Phases 5-6 (in progress)
-- 📋 **v2.0 Redesign** — Phases 7-10 (planned)
-## Phases
-<details>
-<summary>✅ v1.0 MVP (Phases 1-4) — SHIPPED YYYY-MM-DD</summary>
-- [x] Phase 1: Foundation (2/2 plans) — completed YYYY-MM-DD
-- [x] Phase 2: Authentication (2/2 plans) — completed YYYY-MM-DD
-- [x] Phase 3: Core Features (3/3 plans) — completed YYYY-MM-DD
-- [x] Phase 4: Polish (1/1 plan) — completed YYYY-MM-DD
-</details>
-### 🚧 v[Next] [Name] (In Progress / Planned)
-- [ ] Phase 5: [Name] ([N] plans)
-- [ ] Phase 6: [Name] ([N] plans)
-## Progress
-| Phase             | Milestone | Plans Complete | Status      | Completed  |
-| ----------------- | --------- | -------------- | ----------- | ---------- |
-| 1. Foundation     | v1.0      | 2/2            | Complete    | YYYY-MM-DD |
-| 2. Authentication | v1.0      | 2/2            | Complete    | YYYY-MM-DD |
-| 3. Core Features  | v1.0      | 3/3            | Complete    | YYYY-MM-DD |
-| 4. Polish         | v1.0      | 1/1            | Complete    | YYYY-MM-DD |
-| 5. Security Audit | v1.1      | 0/1            | Not started | -          |
-| 6. Hardening      | v1.1      | 0/2            | Not started | -          |
-```
-</step>
-<step name="archive_milestone">
-**Delegate archival to maxsim-tools:**
-```bash
-ARCHIVE=$(node ~/.claude/maxsim/bin/maxsim-tools.cjs milestone complete "v[X.Y]" --name "[Milestone Name]")
-```
-The CLI handles:
-- Creating `.planning/milestones/` directory
-- Archiving ROADMAP.md to `milestones/v[X.Y]-ROADMAP.md`
-- Archiving REQUIREMENTS.md to `milestones/v[X.Y]-REQUIREMENTS.md` with archive header
-- Moving audit file to milestones if it exists
-- Creating/appending MILESTONES.md entry with accomplishments from SUMMARY.md files
-- Updating STATE.md (status, last activity)
-Extract from result: `version`, `date`, `phases`, `plans`, `tasks`, `accomplishments`, `archived`.
-Verify: `✅ Milestone archived to .planning/milestones/`
-**Phase archival (optional):** After archival completes, ask the user:
-AskUserQuestion(header="Archive Phases", question="Archive phase directories to milestones/?", options: "Yes — move to milestones/v[X.Y]-phases/" | "Skip — keep phases in place")
-If "Yes": move phase directories to the milestone archive:
-```bash
-mkdir -p .planning/milestones/v[X.Y]-phases
-# For each phase directory in .planning/phases/:
-mv .planning/phases/{phase-dir} .planning/milestones/v[X.Y]-phases/
-```
-Verify: `✅ Phase directories archived to .planning/milestones/v[X.Y]-phases/`
-If "Skip": Phase directories remain in `.planning/phases/` as raw execution history. Use `/maxsim:cleanup` later to archive retroactively.
-After archival, the AI still handles:
-- Reorganizing ROADMAP.md with milestone grouping (requires judgment)
-- Full PROJECT.md evolution review (requires understanding)
-- Deleting original ROADMAP.md and REQUIREMENTS.md
-- These are NOT fully delegated because they require AI interpretation of content
-</step>
-<step name="reorganize_roadmap_and_delete_originals">
-After `milestone complete` has archived, reorganize ROADMAP.md with milestone groupings, then delete originals:
-**Reorganize ROADMAP.md** — group completed milestone phases:
-```markdown
-# Roadmap: [Project Name]
-## Milestones
-- ✅ **v1.0 MVP** — Phases 1-4 (shipped YYYY-MM-DD)
-- 🚧 **v1.1 Security** — Phases 5-6 (in progress)
-## Phases
-<details>
-<summary>✅ v1.0 MVP (Phases 1-4) — SHIPPED YYYY-MM-DD</summary>
-- [x] Phase 1: Foundation (2/2 plans) — completed YYYY-MM-DD
-- [x] Phase 2: Authentication (2/2 plans) — completed YYYY-MM-DD
-</details>
-```
-**Then delete originals:**
-```bash
-rm .planning/ROADMAP.md
-rm .planning/REQUIREMENTS.md
-```
-</step>
-<step name="update_state">
-Most STATE.md updates were handled by `milestone complete`, but verify and update remaining fields:
-**Project Reference:**
-```markdown
-## Project Reference
-See: .planning/PROJECT.md (updated [today])
-**Core value:** [Current core value from PROJECT.md]
-**Current focus:** [Next milestone or "Planning next milestone"]
-```
-**Accumulated Context:**
-- Clear decisions summary (full log in PROJECT.md)
-- Clear resolved blockers
-- Keep open blockers for next milestone
-</step>
-<step name="handle_branches">
-Check branching strategy and offer merge options.
-Use `init milestone-op` for context, or load config directly:
-```bash
-INIT=$(node ~/.claude/maxsim/bin/maxsim-tools.cjs init execute-phase "1")
-```
-Extract `branching_strategy`, `phase_branch_template`, `milestone_branch_template`, and `commit_docs` from init JSON.
-**If "none":** Skip to git_tag.
-**For "phase" strategy:**
-```bash
-BRANCH_PREFIX=$(echo "$PHASE_BRANCH_TEMPLATE" | sed 's/{.*//')
-PHASE_BRANCHES=$(git branch --list "${BRANCH_PREFIX}*" 2>/dev/null | sed 's/^\*//' | tr -d ' ')
-```
-**For "milestone" strategy:**
-```bash
-BRANCH_PREFIX=$(echo "$MILESTONE_BRANCH_TEMPLATE" | sed 's/{.*//')
-MILESTONE_BRANCH=$(git branch --list "${BRANCH_PREFIX}*" 2>/dev/null | sed 's/^\*//' | tr -d ' ' | head -1)
-```
-**If no branches found:** Skip to git_tag.
-**If branches exist:**
-```
-## Git Branches Detected
-Branching strategy: {phase/milestone}
-Branches: {list}
-Options:
-1. **Merge to main** — Merge branch(es) to main
-2. **Delete without merging** — Already merged or not needed
-3. **Keep branches** — Leave for manual handling
-```
-AskUserQuestion with options: Squash merge (Recommended), Merge with history, Delete without merging, Keep branches.
-**Squash merge:**
-```bash
-CURRENT_BRANCH=$(git branch --show-current)
-git checkout main
-if [ "$BRANCHING_STRATEGY" = "phase" ]; then
-  for branch in $PHASE_BRANCHES; do
-    git merge --squash "$branch"
-    # Strip .planning/ from staging if commit_docs is false
-    if [ "$COMMIT_DOCS" = "false" ]; then
-      git reset HEAD .planning/ 2>/dev/null || true
-    fi
-    git commit -m "feat: $branch for v[X.Y]"
-  done
-fi
-if [ "$BRANCHING_STRATEGY" = "milestone" ]; then
-  git merge --squash "$MILESTONE_BRANCH"
-  # Strip .planning/ from staging if commit_docs is false
-  if [ "$COMMIT_DOCS" = "false" ]; then
-    git reset HEAD .planning/ 2>/dev/null || true
-  fi
-  git commit -m "feat: $MILESTONE_BRANCH for v[X.Y]"
-fi
-git checkout "$CURRENT_BRANCH"
-```
-**Merge with history:**
-```bash
-CURRENT_BRANCH=$(git branch --show-current)
-git checkout main
-if [ "$BRANCHING_STRATEGY" = "phase" ]; then
-  for branch in $PHASE_BRANCHES; do
-    git merge --no-ff --no-commit "$branch"
-    # Strip .planning/ from staging if commit_docs is false
-    if [ "$COMMIT_DOCS" = "false" ]; then
-      git reset HEAD .planning/ 2>/dev/null || true
-    fi
-    git commit -m "Merge branch '$branch' for v[X.Y]"
-  done
-fi
-if [ "$BRANCHING_STRATEGY" = "milestone" ]; then
-  git merge --no-ff --no-commit "$MILESTONE_BRANCH"
-  # Strip .planning/ from staging if commit_docs is false
-  if [ "$COMMIT_DOCS" = "false" ]; then
-    git reset HEAD .planning/ 2>/dev/null || true
-  fi
-  git commit -m "Merge branch '$MILESTONE_BRANCH' for v[X.Y]"
-fi
-git checkout "$CURRENT_BRANCH"
-```
-**Delete without merging:**
-```bash
-if [ "$BRANCHING_STRATEGY" = "phase" ]; then
-  for branch in $PHASE_BRANCHES; do
-    git branch -d "$branch" 2>/dev/null || git branch -D "$branch"
-  done
-fi
-if [ "$BRANCHING_STRATEGY" = "milestone" ]; then
-  git branch -d "$MILESTONE_BRANCH" 2>/dev/null || git branch -D "$MILESTONE_BRANCH"
-fi
-```
-**Keep branches:** Report "Branches preserved for manual handling"
-</step>
-<step name="git_tag">
-Create git tag:
-```bash
-git tag -a v[X.Y] -m "v[X.Y] [Name]
-Delivered: [One sentence]
-Key accomplishments:
-- [Item 1]
-- [Item 2]
-- [Item 3]
-See .planning/MILESTONES.md for full details."
-```
-Confirm: "Tagged: v[X.Y]"
-Ask: "Push tag to remote? (y/n)"
-If yes:
-```bash
-git push origin v[X.Y]
-```
-</step>
-<step name="git_commit_milestone">
-Commit milestone completion.
-```bash
-node ~/.claude/maxsim/bin/maxsim-tools.cjs commit "chore: complete v[X.Y] milestone" --files .planning/milestones/v[X.Y]-ROADMAP.md .planning/milestones/v[X.Y]-REQUIREMENTS.md .planning/milestones/v[X.Y]-MILESTONE-AUDIT.md .planning/MILESTONES.md .planning/PROJECT.md .planning/STATE.md
-```
-```
-Confirm: "Committed: chore: complete v[X.Y] milestone"
-</step>
-<step name="offer_next">
-```
-✅ Milestone v[X.Y] [Name] complete
-Shipped:
-- [N] phases ([M] plans, [P] tasks)
-- [One sentence of what shipped]
-Archived:
-- milestones/v[X.Y]-ROADMAP.md
-- milestones/v[X.Y]-REQUIREMENTS.md
-Summary: .planning/MILESTONES.md
-Tag: v[X.Y]
----
-## ▶ Next Up
-**Start Next Milestone** — questioning → research → requirements → roadmap
-`/maxsim:new-milestone`
-<sub>`/clear` first → fresh context window</sub>
----
-```
-</step>
-</process>
-<milestone_naming>
-**Version conventions:**
-- **v1.0** — Initial MVP
-- **v1.1, v1.2** — Minor updates, new features, fixes
-- **v2.0, v3.0** — Major rewrites, breaking changes, new direction
-**Names:** Short 1-2 words (v1.0 MVP, v1.1 Security, v1.2 Performance, v2.0 Redesign).
-</milestone_naming>
-<what_qualifies>
-**Create milestones for:** Initial release, public releases, major feature sets shipped, before archiving planning.
-**Don't create milestones for:** Every phase completion (too granular), work in progress, internal dev iterations (unless truly shipped).
-Heuristic: "Is this deployed/usable/shipped?" If yes → milestone. If no → keep working.
-</what_qualifies>
-<success_criteria>
-Milestone completion is successful when:
-- [ ] MILESTONES.md entry created with stats and accomplishments
-- [ ] PROJECT.md full evolution review completed
-- [ ] All shipped requirements moved to Validated in PROJECT.md
-- [ ] Key Decisions updated with outcomes
-- [ ] ROADMAP.md reorganized with milestone grouping
-- [ ] Roadmap archive created (milestones/v[X.Y]-ROADMAP.md)
-- [ ] Requirements archive created (milestones/v[X.Y]-REQUIREMENTS.md)
-- [ ] REQUIREMENTS.md deleted (fresh for next milestone)
-- [ ] STATE.md updated with fresh project reference
-- [ ] Git tag created (v[X.Y])
-- [ ] Milestone commit made (includes archive files and deletion)
-- [ ] Requirements completion checked against REQUIREMENTS.md traceability table
-- [ ] Incomplete requirements surfaced with proceed/audit/abort options
-- [ ] Known gaps recorded in MILESTONES.md if user proceeded with incomplete requirements
-- [ ] User knows next step (/maxsim:new-milestone)
-</success_criteria>