maxsimcli 5.0.6 → 5.1.0

package/dist/assets/templates/workflows/new-milestone.md

@@ -1,404 +1,161 @@
 <purpose>
-
-Start a new milestone cycle for an existing project. Loads project context, gathers milestone goals (from MILESTONE-CONTEXT.md or conversation), updates PROJECT.md and STATE.md, optionally runs parallel research, defines scoped requirements with REQ-IDs, spawns the roadmapper to create phased execution plan, and commits all artifacts. Brownfield equivalent of new-project.
-
+Create a new GitHub Milestone with a structured phase breakdown. All state lives in GitHub Issues — no local planning files are created by this workflow.
 </purpose>
 
-<required_reading>
-
-Read all files referenced by the invoking prompt's execution_context before starting.
-
-</required_reading>
-
 <process>
 
-## 1. Load Context
-
-- Read PROJECT.md (existing project, validated requirements, decisions)
-- Read MILESTONES.md (what shipped previously)
-- Read STATE.md (blockers, decisions)
-- Check for MILESTONE-CONTEXT.md (from /maxsim:plan)
-
-## 2. Gather Milestone Goals
-
-**If MILESTONE-CONTEXT.md exists:**
-- Use features and scope from plan
-- Present summary for confirmation
-
-**If no context file:**
-- Present what shipped in last milestone
-- Ask: "What do you want to build next?"
-- Use AskUserQuestion to explore features, priorities, constraints, scope
-
-## 3. Determine Milestone Version
-
-- Parse last version from MILESTONES.md
-- Suggest next version (v1.0 → v1.1, or v2.0 for major)
-- Confirm with user
-
-## 4. Update PROJECT.md
-
-Add/update:
+## Step 1: Gather milestone details
 
-```markdown
-## Current Milestone: v[X.Y] [Name]
+Prompt user for milestone information:
 
-**Goal:** [One sentence describing milestone focus]
-
-**Target features:**
-- [Feature 1]
-- [Feature 2]
-- [Feature 3]
 ```
-
-Update Active requirements section and "Last updated" footer.
-
-## 5. Update STATE.md
-
-```markdown
-## Current Position
-
-Phase: Not started (defining requirements)
-Plan: —
-Status: Defining requirements
-Last activity: [today] — Milestone v[X.Y] started
+AskUserQuestion([
+  {
+    header: "Milestone Name",
+    question: "What is the name of this milestone?",
+    followUp: "e.g. v2.0 Authentication, Q2 Dashboard, Payments MVP"
+  },
+  {
+    header: "Milestone Description",
+    question: "Describe the goal of this milestone in 1-2 sentences."
+  },
+  {
+    header: "Due Date",
+    question: "Due date? (YYYY-MM-DD or leave blank for none)"
+  }
+])
 ```
 
-Keep Accumulated Context section from previous milestone.
-
-## 6. Cleanup and Commit
+Store as `$MILESTONE_NAME`, `$MILESTONE_DESCRIPTION`, `$MILESTONE_DUE`.
 
-Delete MILESTONE-CONTEXT.md if exists (consumed).
+---
 
-```bash
-node ~/.claude/maxsim/bin/maxsim-tools.cjs commit "docs: start milestone v[X.Y] [Name]" --files .planning/PROJECT.md .planning/STATE.md
-```
-
-## 7. Load Context and Resolve Models
+## Step 2: Create GitHub Milestone
 
 ```bash
-INIT=$(node ~/.claude/maxsim/bin/maxsim-tools.cjs init new-milestone)
+node ~/.claude/maxsim/bin/maxsim-tools.cjs github create-milestone \
+  --title "$MILESTONE_NAME" \
+  --description "$MILESTONE_DESCRIPTION" \
+  --due-date "$MILESTONE_DUE"
 ```
 
-Extract from init JSON: `researcher_model`, `synthesizer_model`, `roadmapper_model`, `commit_docs`, `research_enabled`, `current_milestone`, `project_exists`, `roadmap_exists`.
-
-## 8. Research Decision
-
-AskUserQuestion: "Research the domain ecosystem for new features before defining requirements?"
-- "Research first (Recommended)" — Discover patterns, features, architecture for NEW capabilities
-- "Skip research" — Go straight to requirements
-
-**Persist choice to config** (so future `/maxsim:plan` honors it):
+Parse response for `$MILESTONE_NUMBER`.
 
-```bash
-# If "Research first": persist true
-node ~/.claude/maxsim/bin/maxsim-tools.cjs config-set workflow.research true
-
-# If "Skip research": persist false
-node ~/.claude/maxsim/bin/maxsim-tools.cjs config-set workflow.research false
-```
-
-**If "Research first":**
+Display:
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- MAXSIM ► RESEARCHING
+ MAXSIM ► MILESTONE CREATED
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-◆ Spawning 4 researchers in parallel...
-  → Stack, Features, Architecture, Pitfalls
-```
+Milestone #$MILESTONE_NUMBER: $MILESTONE_NAME
+Description: $MILESTONE_DESCRIPTION
+Due: $MILESTONE_DUE (or "No due date")
 
-```bash
-mkdir -p .planning/research
+Now define the phases for this milestone.
 ```
 
-Spawn 4 parallel researcher agents. Each uses this template with dimension-specific fields:
+---
 
-**Common structure for all 4 researchers:**
-```
-Task(prompt="
-<research_type>Project Research — {DIMENSION} for [new features].</research_type>
+## Step 3: Get phase breakdown from user
 
-<milestone_context>
-SUBSEQUENT MILESTONE — Adding [target features] to existing app.
-{EXISTING_CONTEXT}
-Focus ONLY on what's needed for the NEW features.
-</milestone_context>
+Ask user to describe the phases:
 
-<question>{QUESTION}</question>
-
-<files_to_read>
-- .planning/PROJECT.md (Project context)
-</files_to_read>
-
-<downstream_consumer>{CONSUMER}</downstream_consumer>
-
-<quality_gate>{GATES}</quality_gate>
-
-<output>
-Write to: .planning/research/{FILE}
-Use template: ~/.claude/maxsim/templates/research-project/{FILE}
-</output>
-", subagent_type="researcher", model="{researcher_model}", description="{DIMENSION} research")
 ```
-
-**Dimension-specific fields:**
-
-| Field | Stack | Features | Architecture | Pitfalls |
-|-------|-------|----------|-------------|----------|
-| EXISTING_CONTEXT | Existing validated capabilities (DO NOT re-research): [from PROJECT.md] | Existing features (already built): [from PROJECT.md] | Existing architecture: [from PROJECT.md or codebase map] | Focus on common mistakes when ADDING these features to existing system |
-| QUESTION | What stack additions/changes are needed for [new features]? | How do [target features] typically work? Expected behavior? | How do [target features] integrate with existing architecture? | Common mistakes when adding [target features] to [domain]? |
-| CONSUMER | Specific libraries with versions for NEW capabilities, integration points, what NOT to add | Table stakes vs differentiators vs anti-features, complexity noted, dependencies on existing | Integration points, new components, data flow changes, suggested build order | Warning signs, prevention strategy, which phase should address it |
-| GATES | Versions current (verify with Context7), rationale explains WHY, integration considered | Categories clear, complexity noted, dependencies identified | Integration points identified, new vs modified explicit, build order considers deps | Pitfalls specific to adding these features, integration pitfalls covered, prevention actionable |
-| FILE | STACK.md | FEATURES.md | ARCHITECTURE.md | PITFALLS.md |
-
-After all 4 complete, spawn synthesizer:
-
-```
-Task(prompt="
-Synthesize research outputs into SUMMARY.md.
-
-<files_to_read>
-- .planning/research/STACK.md
-- .planning/research/FEATURES.md
-- .planning/research/ARCHITECTURE.md
-- .planning/research/PITFALLS.md
-</files_to_read>
-
-Write to: .planning/research/SUMMARY.md
-Use template: ~/.claude/maxsim/templates/research-project/SUMMARY.md
-Commit after writing.
-", subagent_type="researcher", model="{synthesizer_model}", description="Synthesize research")
-```
-
-Display key findings from SUMMARY.md:
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- MAXSIM ► RESEARCH COMPLETE ✓
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-**Stack additions:** [from SUMMARY.md]
-**Feature table stakes:** [from SUMMARY.md]
-**Watch Out For:** [from SUMMARY.md]
+AskUserQuestion(
+  header: "Phase Breakdown",
+  question: "List the phases for this milestone. Provide each as: 'Phase Name: one-sentence goal'",
+  followUp: "Example:\nFoundation: Set up database schema and API layer\nUI: Build the core user interface\nIntegration: Connect frontend to backend APIs"
+)
 ```
 
-**If "Skip research":** Continue to Step 9.
+Parse the response into a list of `{ name, goal }` pairs.
 
-## 9. Define Requirements
+Display parsed phases for confirmation:
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- MAXSIM ► DEFINING REQUIREMENTS
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
+## Planned Phases
 
-Read PROJECT.md: core value, current milestone goals, validated requirements (what exists).
+| # | Name | Goal |
+|---|------|------|
+| 1 | Foundation | Set up database schema and API layer |
+| 2 | UI | Build the core user interface |
+| 3 | Integration | Connect frontend to backend APIs |
 
-**If research exists:** Read FEATURES.md, extract feature categories.
-
-Present features by category:
-```
-## [Category 1]
-**Table stakes:** Feature A, Feature B
-**Differentiators:** Feature C, Feature D
-**Research notes:** [any relevant notes]
+Are these phases correct?
 ```
 
-**If no research:** Gather requirements through conversation. Ask: "What are the main things users need to do with [new features]?" Clarify, probe for related capabilities, group into categories.
-
-**Scope each category** via AskUserQuestion (multiSelect: true, header max 12 chars):
-- "[Feature 1]" — [brief description]
-- "[Feature 2]" — [brief description]
-- "None for this milestone" — Defer entire category
-
-Track: Selected → this milestone. Unselected table stakes → future. Unselected differentiators → out of scope.
-
-**Identify gaps** via AskUserQuestion:
-- "No, research covered it" — Proceed
-- "Yes, let me add some" — Capture additions
-
-**Generate REQUIREMENTS.md:**
-- v1 Requirements grouped by category (checkboxes, REQ-IDs)
-- Future Requirements (deferred)
-- Out of Scope (explicit exclusions with reasoning)
-- Traceability section (empty, filled by roadmap)
-
-**REQ-ID format:** `[CATEGORY]-[NUMBER]` (AUTH-01, NOTIF-02). Continue numbering from existing.
-
-**Requirement quality criteria:**
-
-Good requirements are:
-- **Specific and testable:** "User can reset password via email link" (not "Handle password reset")
-- **User-centric:** "User can X" (not "System does Y")
-- **Atomic:** One capability per requirement (not "User can login and manage profile")
-- **Independent:** Minimal dependencies on other requirements
-
-Present FULL requirements list for confirmation:
-
 ```
-## Milestone v[X.Y] Requirements
-
-### [Category 1]
-- [ ] **CAT1-01**: User can do X
-- [ ] **CAT1-02**: User can do Y
-
-### [Category 2]
-- [ ] **CAT2-01**: User can do Z
-
-Does this capture what you're building? (yes / adjust)
-```
-
-If "adjust": Return to scoping.
-
-**Commit requirements:**
-```bash
-node ~/.claude/maxsim/bin/maxsim-tools.cjs commit "docs: define milestone v[X.Y] requirements" --files .planning/REQUIREMENTS.md
+AskUserQuestion(
+  header: "Confirm Phases",
+  question: "Proceed with these phases?",
+  options: [
+    { label: "Yes, create them" },
+    { label: "No, let me revise" }
+  ]
+)
 ```
 
-## 10. Create Roadmap
-
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- MAXSIM ► CREATING ROADMAP
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+If "No, let me revise": return to step 3 and re-prompt.
 
-◆ Spawning roadmapper...
-```
+---
 
-**Starting phase number:** Read MILESTONES.md for last phase number. Continue from there (v1.0 ended at phase 5 → v1.1 starts at phase 6).
+## Step 4: Create phase issues linked to milestone
 
-```
-Task(prompt="
-<planning_context>
-<files_to_read>
-- .planning/PROJECT.md
-- .planning/REQUIREMENTS.md
-- .planning/research/SUMMARY.md (if exists)
-- .planning/config.json
-- .planning/MILESTONES.md
-</files_to_read>
-</planning_context>
-
-<instructions>
-Create roadmap for milestone v[X.Y]:
-1. Start phase numbering from [N]
-2. Derive phases from THIS MILESTONE's requirements only
-3. Map every requirement to exactly one phase
-4. Derive 2-5 success criteria per phase (observable user behaviors)
-5. Validate 100% coverage
-6. Write files immediately (ROADMAP.md, STATE.md, update REQUIREMENTS.md traceability)
-7. Return ROADMAP CREATED with summary
-
-Write files first, then return.
-</instructions>
-", subagent_type="planner", model="{roadmapper_model}", description="Create roadmap")
-```
+For each phase, run `github create-phase` sequentially:
 
-**Handle return:**
-
-**If `## ROADMAP BLOCKED`:** Present blocker, work with user, re-spawn.
-
-**If `## ROADMAP CREATED`:** Read ROADMAP.md, present inline:
-
-```
-## Proposed Roadmap
-
-**[N] phases** | **[X] requirements mapped** | All covered ✓
-
-| # | Phase | Goal | Requirements | Success Criteria |
-|---|-------|------|--------------|------------------|
-| [N] | [Name] | [Goal] | [REQ-IDs] | [count] |
-
-### Phase Details
-
-**Phase [N]: [Name]**
-Goal: [goal]
-Requirements: [REQ-IDs]
-Success criteria:
-1. [criterion]
-2. [criterion]
-```
-
-**Ask for approval** via AskUserQuestion:
-- "Approve" — Commit and continue
-- "Adjust phases" — Tell me what to change
-- "Review full file" — Show raw ROADMAP.md
-
-**If "Adjust":** Get notes, re-spawn roadmapper with revision context, loop until approved.
-**If "Review":** Display raw ROADMAP.md, re-ask.
-
-**Commit roadmap** (after approval):
 ```bash
-node ~/.claude/maxsim/bin/maxsim-tools.cjs commit "docs: create milestone v[X.Y] roadmap ([N] phases)" --files .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md
-```
-
-## 10b. Create Phase Tracking Issues on GitHub
-
-**This step is MANDATORY — GitHub Issues are the single source of truth for phase tracking.**
-
-For each phase in the roadmap, run `github create-phase` to create a tracking issue:
-
-```bash
-# For each phase:
+# For each phase (1-indexed):
 node ~/.claude/maxsim/bin/maxsim-tools.cjs github create-phase \
   --phase-number "[N]" \
   --phase-name "[Phase Name]" \
-  --goal "[Phase Goal from ROADMAP.md]"
+  --goal "[Phase Goal]" \
+  --milestone-number $MILESTONE_NUMBER
 ```
 
-Track results. If any phase issue creation fails, warn and suggest manual creation.
+Track results. If any creation fails, warn and provide the manual creation command.
 
-```
-✓ Created {N} phase issues on GitHub Project Board
+After all phases are created, add each issue to the project board in the "To Do" column:
+
+```bash
+node ~/.claude/maxsim/bin/maxsim-tools.cjs github move-issue \
+  --issue-number [ISSUE_NUM] \
+  --status "To Do"
 ```
 
-## 11. Done
+---
+
+## Step 5: Display completion summary
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- MAXSIM ► MILESTONE INITIALIZED ✓
+ MAXSIM ► MILESTONE READY
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-**Milestone v[X.Y]: [Name]**
-
-| Artifact       | Location                    |
-|----------------|-----------------------------|
-| Project        | `.planning/PROJECT.md`      |
-| Research       | `.planning/research/`       |
-| Requirements   | `.planning/REQUIREMENTS.md` |
-| Roadmap        | `.planning/ROADMAP.md`      |
-| Phase Issues   | GitHub Project Board        |
-
-**[N] phases** | **[X] requirements** | **[N] GitHub issues** | Ready to build ✓
+Milestone #$MILESTONE_NUMBER: $MILESTONE_NAME
 
-## ▶ Next Up
+| # | Phase | Issue | Board Status |
+|---|-------|-------|--------------|
+| 1 | [Name] | #N | To Do |
+| 2 | [Name] | #N | To Do |
+| 3 | [Name] | #N | To Do |
 
-**Phase [N]: [Phase Name]** — [Goal]
+All [N] phases created and added to the project board.
 
-`/maxsim:plan [N]` — gather context and clarify approach
+## Next Steps
 
-<sub>`/clear` first → fresh context window</sub>
+Start planning the first phase:
 
-Also: `/maxsim:plan [N]` — skip discussion, plan directly
+/maxsim:plan 1   — begin discussion and planning for Phase 1
 ```
 
 </process>
 
 <success_criteria>
-- [ ] PROJECT.md updated with Current Milestone section
-- [ ] STATE.md reset for new milestone
-- [ ] MILESTONE-CONTEXT.md consumed and deleted (if existed)
-- [ ] Research completed (if selected) — 4 parallel agents, milestone-aware
-- [ ] Requirements gathered and scoped per category
-- [ ] REQUIREMENTS.md created with REQ-IDs
-- [ ] planner (roadmap mode) spawned with phase numbering context
-- [ ] Roadmap files written immediately (not draft)
-- [ ] User feedback incorporated (if any)
-- [ ] ROADMAP.md phases continue from previous milestone
-- [ ] `github create-phase` called for every phase — all issues on GitHub board
-- [ ] All commits made (if planning docs committed)
-- [ ] User knows next step: `/maxsim:plan [N]`
-
-**Atomic commits:** Each phase commits its artifacts immediately.
+- [ ] User provides milestone name, description, and optional due date
+- [ ] GitHub Milestone created via maxsim-tools
+- [ ] User provides phase breakdown and confirms it
+- [ ] Phase issues created and linked to the milestone
+- [ ] All phase issues added to project board as "To Do"
+- [ ] Summary displayed with issue numbers and next step
 </success_criteria>