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. Read all files referenced by the invoking prompt's execution_context before starting. ## 1. Load Context - Read project.md (existing project, validated requirements, decisions) - Read milestones.md (what shipped previously) - Read state.md (pending todos, blockers) - Check for MILESTONE-context.md (from /pan:discuss-milestone) ## 2. Gather Milestone Goals **If MILESTONE-context.md exists:** - Use features and scope from discuss-milestone - 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: ```markdown ## Current Milestone: v[X.Y] [Name] **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 ``` Keep Accumulated Context section from previous milestone. ## 6. Cleanup and Commit Delete MILESTONE-context.md if exists (consumed). ```bash node ~/.claude/pan-wizard-core/bin/pan-tools.cjs commit "docs: start milestone v[X.Y] [Name]" --files .planning/project.md .planning/state.md ``` ## 7. Load Context and Resolve Models ```bash INIT=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs init new-milestone) ``` 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 `/pan:plan-phase` honors it): ```bash # If "Research first": persist true node ~/.claude/pan-wizard-core/bin/pan-tools.cjs config-set workflow.research true # If "Skip research": persist false node ~/.claude/pan-wizard-core/bin/pan-tools.cjs config-set workflow.research false ``` **If "Research first":** ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ PAN ► RESEARCHING ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ◆ Spawning 4 researchers in parallel... → Stack, Features, Architecture, Pitfalls ``` ```bash mkdir -p .planning/research ``` Spawn 4 parallel pan-project-researcher agents. Each uses this template with dimension-specific fields: **Common structure for all 4 researchers:** ``` Task(prompt=" Project Research — {DIMENSION} for [new features]. SUBSEQUENT MILESTONE — Adding [target features] to existing app. {EXISTING_CONTEXT} Focus ONLY on what's needed for the NEW features. {QUESTION} - .planning/project.md (Project context) {CONSUMER} {GATES} Write to: .planning/research/{FILE} Use template: ~/.claude/pan-wizard-core/templates/research-project/{FILE} ", subagent_type="pan-project-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. - .planning/research/stack.md - .planning/research/features.md - .planning/research/architecture.md - .planning/research/pitfalls.md Write to: .planning/research/summary.md Use template: ~/.claude/pan-wizard-core/templates/research-project/summary.md Commit after writing. ", subagent_type="pan-research-synthesizer", model="{synthesizer_model}", description="Synthesize research") ``` Display key findings from summary.md: ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ PAN ► RESEARCH COMPLETE ✓ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ **Stack additions:** [from summary.md] **Feature table stakes:** [from summary.md] **Watch Out For:** [from summary.md] ``` **If "Skip research":** Continue to Step 9. ## 9. Define Requirements ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ PAN ► DEFINING REQUIREMENTS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ``` Read project.md: core value, current milestone goals, validated requirements (what exists). **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] ``` **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/pan-wizard-core/bin/pan-tools.cjs commit "docs: define milestone v[X.Y] requirements" --files .planning/requirements.md ``` ## 10. Create Roadmap ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ PAN ► CREATING ROADMAP ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ◆ 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). ``` Task(prompt=" - .planning/project.md - .planning/requirements.md - .planning/research/summary.md (if exists) - .planning/config.json - .planning/milestones.md 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. ", subagent_type="pan-roadmapper", model="{roadmapper_model}", description="Create roadmap") ``` **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/pan-wizard-core/bin/pan-tools.cjs commit "docs: create milestone v[X.Y] roadmap ([N] phases)" --files .planning/roadmap.md .planning/state.md .planning/requirements.md ``` ## 11. Done ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ PAN ► MILESTONE INITIALIZED ✓ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ **Milestone v[X.Y]: [Name]** | Artifact | Location | |----------------|-----------------------------| | Project | `.planning/project.md` | | Research | `.planning/research/` | | Requirements | `.planning/requirements.md` | | Roadmap | `.planning/roadmap.md` | **[N] phases** | **[X] requirements** | Ready to build ✓ ## ▶ Next Up **Phase [N]: [Phase Name]** — [Goal] `/pan:discuss-phase [N]` — gather context and clarify approach `/clear` first → fresh context window Also: `/pan:plan-phase [N]` — skip discussion, plan directly ``` - [ ] 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 - [ ] pan-roadmapper spawned with phase numbering context - [ ] Roadmap files written immediately (not draft) - [ ] User feedback incorporated (if any) - [ ] roadmap.md phases continue from previous milestone - [ ] All commits made (if planning docs committed) - [ ] User knows next step: `/pan:discuss-phase [N]` **Atomic commits:** Each phase commits its artifacts immediately.