@hanzlaa/rcode 3.6.15 → 4.0.0

package/rcode/workflows/new-milestone.md

@@ -0,0 +1,644 @@
+<purpose>
+Start a new milestone cycle for an existing project. Loads project context, gathers milestone goals interactively, updates PROJECT.md and STATE.md in-place, optionally runs parallel research, defines scoped requirements with REQ-IDs, spawns rcode-roadmapper to create the phased execution plan, and commits all artifacts. Brownfield equivalent of new-project.
+</purpose>
+
+<required_reading>
+@.rcode/references/output-format.md
+@.rcode/references/commit-conventions.md
+Read all files referenced by the invoking prompt's execution_context before starting.
+</required_reading>
+
+<available_agent_types>
+Valid rcode subagent types (use exact names — do not fall back to 'general-purpose'):
+- rcode-project-researcher — Researches project-level technical decisions
+- rcode-research-synthesizer — Synthesizes findings from parallel research agents
+- rcode-roadmapper — Creates phased execution roadmaps
+</available_agent_types>
+
+<process>
+
+## 1. Parse arguments and load context
+
+Parse `$ARGUMENTS` before anything else:
+- `--reset-phase-numbers` flag → restart roadmap phase numbering at `1`
+- `--dry-run` flag → show what would be written, do not commit
+- `--from-draft <path>` flag → use an existing MILESTONE-CONTEXT.md or ROADMAP draft as the milestone definition (closes #740). When present, set `DRAFT_FILE=<path>` and `FROM_DRAFT_MODE=true`.
+- Remaining text → milestone name (optional)
+
+If `--from-draft` is absent, continue phase numbering from the previous milestone.
+
+**From-draft mode (closes #740):**
+
+When `FROM_DRAFT_MODE=true`:
+1. Read the draft file at `DRAFT_FILE`. Accept any markdown file — MILESTONE-CONTEXT.md, a scratch doc, or a ROADMAP partial.
+2. Extract milestone name (first `# Heading` or the filename stem), goals list, and any explicit phase list.
+3. Skip the interactive goal-gathering interview (steps 2–4). Jump directly to step 5 (Requirements scoping) using the draft as the source of truth.
+4. Surface a one-line banner:
+   ```
+   ◆ From-draft mode: using {DRAFT_FILE} as milestone definition (skipping goal interview)
+   ```
+5. If `DRAFT_FILE` does not exist, abort:
+   ```
+   Error: --from-draft file not found: {DRAFT_FILE}
+   ```
+
+Read these files in parallel:
+- `.planning/PROJECT.md` — existing project, validated requirements, decisions
+- `.planning/MILESTONES.md` — what shipped previously (may not exist on first milestone)
+- `.planning/STATE.md` — pending todos, blockers
+- `.planning/MILESTONE-CONTEXT.md` — if it exists (from a prior `/rcode-discuss` about the next milestone)
+- `{DRAFT_FILE}` (if `FROM_DRAFT_MODE=true`)
+
+If `.planning/PROJECT.md` does not exist, STOP and redirect:
+
+```
+⚠ No project initialized. Run /rcode-new-project first.
+```
+
+## 2. Gather milestone goals
+
+**If `MILESTONE-CONTEXT.md` exists:**
+- Summarize its features + scope
+- Present for confirmation via AskUserQuestion: "Use this context?" → Yes / Revise
+
+**If no context file:**
+- Read `MILESTONES.md` (or tail of PROJECT.md history) and present a summary of what shipped last:
+
+```
+Here's what shipped in the last milestone:
+
+---
+v[X.Y] [Name] (shipped [date])
+- [feature 1]
+- [feature 2]
+- [feature 3]
+---
+
+What do you want to build next?
+```
+
+- Wait for freeform user reply (NOT AskUserQuestion for the open-ended "what next" — raw text is higher signal). Then probe specifics with AskUserQuestion where needed.
+
+## 3. Determine milestone version
+
+- Parse the last version from `MILESTONES.md` (or PROJECT.md history section).
+- Suggest the next version (v1.7 → v1.8 for minor; v1.x → v2.0 for major — ask the user which).
+- Confirm via AskUserQuestion:
+  - "v[X.Y+1] (minor)" — default
+  - "v[X+1].0 (major)"
+  - "Custom" → ask plain text
+
+## 3.5 Verify milestone understanding (mandatory — loop until confirmed)
+
+Before writing any files, present a summary and require explicit confirmation:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ rcode ► MILESTONE SUMMARY
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Milestone v[X.Y]: [Name]**
+
+**Goal:** [one sentence]
+
+**Target features:**
+- [feature 1]
+- [feature 2]
+- [feature 3]
+
+**Key context:** [constraints, decisions, notes from questioning]
+```
+
+AskUserQuestion:
+- header: "Confirm?"
+- question: "Does this capture what you want to build in this milestone?"
+- options:
+  - "Looks good" → proceed to Step 4
+  - "Adjust" → collect changes and re-present
+
+**If "Adjust":** ask for the delta as plain text, fold it in, re-present the summary. Loop until "Looks good".
+
+## 4. Update PROJECT.md
+
+Edit `.planning/PROJECT.md` in place. Add or update the `## Current Milestone` section:
+
+```markdown
+## Current Milestone: v[X.Y] [Name]
+
+**Goal:** [one sentence]
+
+**Target features:**
+- [feature 1]
+- [feature 2]
+- [feature 3]
+```
+
+Update the "Last updated" footer to today's date and milestone name.
+
+Ensure the `## Evolution` section exists. If missing, insert before the footer:
+
+```markdown
+## Evolution
+
+This document evolves at phase transitions and milestone boundaries.
+
+**After each phase transition:**
+1. Requirements invalidated? → move to Out of Scope with reason
+2. Requirements validated? → move to Validated with phase reference
+3. New requirements emerged? → add to Active
+4. Decisions to log? → add to Key Decisions
+5. "What This Is" still accurate? → update if drifted
+
+**After each milestone (via `/rcode-complete-milestone`):**
+1. Full review of all sections
+2. Core Value check
+3. Audit Out of Scope — reasons still valid?
+4. Update Context with current state
+```
+
+## 5. Update STATE.md
+
+Edit `.planning/STATE.md` in place. Set header + Current Position:
+
+```yaml
+---
+rcode_state_version: 1.0
+milestone: v[X.Y]
+milestone_name: [Name]
+status: defining_requirements
+stopped_at: —
+last_updated: "[ISO timestamp]"
+last_activity: [YYYY-MM-DD]
+progress:
+  total_phases: 0
+  completed_phases: 0
+  total_plans: 0
+  completed_plans: 0
+  percent: 0
+---
+```
+
+Current Position block:
+
+```markdown
+## Current Position
+
+Phase: Not started (defining requirements)
+Plan: —
+Status: Defining requirements
+Last activity: [YYYY-MM-DD] — Milestone v[X.Y] started
+```
+
+Keep the Accumulated Context section from the previous milestone intact.
+
+## 6. Cleanup and commit
+
+Delete `MILESTONE-CONTEXT.md` if it exists (consumed):
+
+```bash
+rm -f .planning/MILESTONE-CONTEXT.md
+```
+
+Clear leftover phase directories from the previous milestone only if the previous milestone was archived (check `.planning/archive/` exists and contains the prior milestone's dir). If not archived, do NOT delete — prompt user to run `/rcode-complete-milestone` on the prior milestone first.
+
+Load commit conventions (see `@.rcode/references/commit-conventions.md` — run the project-local scan before writing the commit message):
+
+```bash
+git add .planning/PROJECT.md .planning/STATE.md
+git commit -m "docs: start milestone v[X.Y] [Name]"
+```
+
+If `.planning/` is gitignored (common case), print:
+
+```
+ℹ .planning/ is gitignored — state updated locally, no commit made.
+```
+
+and continue.
+
+## 7. Load context and resolve models
+
+```bash
+INIT=$(node ".rcode/bin/rcode-tools.cjs" init new-milestone 2>/dev/null)
+AGENT_SKILLS_RESEARCHER=$(node ".rcode/bin/rcode-tools.cjs" agent-info rcode-project-researcher 2>/dev/null || echo "")
+AGENT_SKILLS_SYNTHESIZER=$(node ".rcode/bin/rcode-tools.cjs" agent-info rcode-research-synthesizer 2>/dev/null || echo "")
+AGENT_SKILLS_ROADMAPPER=$(node ".rcode/bin/rcode-tools.cjs" agent-info rcode-roadmapper 2>/dev/null || echo "")
+```
+
+Extract from `INIT` JSON (where available): `research_enabled`, `current_milestone`, `project_exists`, `roadmap_exists`, `latest_completed_milestone`, `phase_dir_count`.
+
+Resolve models per agent:
+
+```bash
+RESEARCHER_MODEL=$(node ".rcode/bin/rcode-tools.cjs" resolve-model rcode-project-researcher 2>/dev/null)
+SYNTHESIZER_MODEL=$(node ".rcode/bin/rcode-tools.cjs" resolve-model rcode-research-synthesizer 2>/dev/null)
+ROADMAPPER_MODEL=$(node ".rcode/bin/rcode-tools.cjs" resolve-model rcode-roadmapper 2>/dev/null)
+```
+
+## 7.5 Reset-phase safety (only when `--reset-phase-numbers`)
+
+If `--reset-phase-numbers` is active:
+
+1. Set starting phase number to `1` for the upcoming roadmap.
+2. If `.planning/phases/` still contains directories from the previous milestone, archive them before roadmapping so new `01-*` / `02-*` directories cannot collide:
+
+```bash
+ARCHIVE_DIR=".planning/archive/v[prev-version]"
+if [ -d .planning/phases ] && [ "$(ls -A .planning/phases 2>/dev/null)" ]; then
+  mkdir -p "$ARCHIVE_DIR"
+  find .planning/phases -mindepth 1 -maxdepth 1 -type d -exec mv {} "$ARCHIVE_DIR/" \;
+fi
+```
+
+If the previous milestone has not been completed/archived, STOP:
+
+```
+⚠ Prior milestone not archived. Run /rcode-complete-milestone v[prev] before --reset-phase-numbers.
+```
+
+## 8. Research decision
+
+Check `research_enabled` from init JSON.
+
+AskUserQuestion: "Research the domain ecosystem for new features before defining requirements?"
+
+If `research_enabled=true`:
+- "Research first (recommended)" — discover patterns, features, architecture for NEW capabilities
+- "Skip research for this milestone" — go straight to requirements (does not change project default)
+
+If `research_enabled=false`:
+- "Skip research (current default)" — go straight to requirements
+- "Research first" — discover patterns, features, architecture for NEW capabilities
+
+**Do NOT persist this choice.** To change the default, the user runs `/rcode-settings`.
+
+**If "Research first":**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ rcode ► RESEARCHING
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+◆ Spawning 4 researchers in parallel...
+  → Stack, Features, Architecture, Pitfalls
+```
+
+```bash
+mkdir -p .planning/research
+```
+
+Spawn 4 parallel `rcode-project-researcher` Task calls in a single assistant response. Each produces one file in `.planning/research/`.
+
+Per-researcher prompt template:
+
+```
+<research_type>Project Research — {DIMENSION} for [milestone features].</research_type>
+
+<milestone_context>
+SUBSEQUENT MILESTONE — Adding [target features] to existing app.
+{EXISTING_CONTEXT}
+Focus ONLY on what's needed for the NEW features.
+</milestone_context>
+
+<question>{QUESTION}</question>
+
+<files_to_read>
+- .planning/PROJECT.md
+- .planning/MILESTONES.md (if exists)
+</files_to_read>
+
+${AGENT_SKILLS_RESEARCHER}
+
+<downstream_consumer>{CONSUMER}</downstream_consumer>
+
+<quality_gate>{GATES}</quality_gate>
+
+<output>
+Write to: .planning/research/{FILE}
+</output>
+```
+
+Dimension-specific fields:
+
+| Field | Stack | Features | Architecture | Pitfalls |
+|-------|-------|----------|--------------|----------|
+| EXISTING_CONTEXT | Existing validated stack (DO NOT re-research): [from PROJECT.md] | Existing features already built: [from PROJECT.md] | Existing architecture: [from PROJECT.md or codebase map] | 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 | Libraries w/ versions for NEW capabilities, integration points, what NOT to add | Table stakes vs differentiators vs anti-features, complexity, 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 via Context7), rationale WHY, integration considered | Categories clear, complexity noted, deps identified | Integration points identified, new vs modified explicit, build order considers deps | Pitfalls specific to these features, integration pitfalls covered, prevention actionable |
+| FILE | STACK.md | FEATURES.md | ARCHITECTURE.md | PITFALLS.md |
+
+After all 4 complete, spawn `rcode-research-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>
+
+${AGENT_SKILLS_SYNTHESIZER}
+
+Write to: .planning/research/SUMMARY.md
+", subagent_type='rcode-research-synthesizer', model='${SYNTHESIZER_MODEL}', description='Synthesize research')
+```
+
+Display:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ rcode ► 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
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ rcode ► DEFINING REQUIREMENTS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Read PROJECT.md: core value, current milestone goal, validated requirements (what exists).
+
+**If research exists:** read `FEATURES.md`, extract categories. Present:
+
+```
+## [Category 1]
+**Table stakes:** Feature A, Feature B
+**Differentiators:** Feature C, Feature D
+**Research notes:** [any]
+```
+
+**If no research:** gather 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 ≤12 chars):
+
+- "[Feature 1]" — [brief]
+- "[Feature 2]" — [brief]
+- "None for this milestone" — defer whole 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 `.planning/REQUIREMENTS.md`** with this structure:
+
+```markdown
+# Requirements — v[X.Y] [Name]
+
+**Source:** [origin — e.g. roadmap doc name or "Conversation with Hanzla on [date]"]
+**Scope:** [one-line scope statement]
+
+**Quality constraint (applies to all requirements):** [any cross-cutting constraint the user named, e.g. "Every change must add value without degrading existing UX."]
+
+---
+
+## [Category 1] ([PREFIX])
+
+- [ ] **[PREFIX]-01**: User can do X
+- [ ] **[PREFIX]-02**: User can do Y
+
+## [Category 2] ([PREFIX2])
+
+- [ ] **[PREFIX2]-01**: User can do Z
+
+---
+
+## Future (Deferred)
+
+- [item carried forward]
+
+## Out of Scope
+
+- [explicit exclusion with reason]
+
+---
+
+## Traceability
+
+| Requirement | Phase | Status |
+|-------------|-------|--------|
+| [PREFIX]-01 | TBD | Pending |
+| [PREFIX]-02 | TBD | Pending |
+| [PREFIX2]-01 | TBD | Pending |
+
+**Total:** [N] requirements across [M] categories — 0/[N] mapped ✓
+```
+
+**REQ-ID format:** `[CATEGORY-PREFIX]-[NUMBER]`. Pick a short, distinct prefix per category (SRV = Sequence Recipient Visibility, RNV = Record Navigation, AUTH = Auth, etc.). Do NOT reuse prefixes from a prior milestone.
+
+**Requirement quality criteria:**
+- **Specific + testable:** "User can reset password via email link" ≠ "Handle password reset"
+- **User-centric:** "User can X" — not "System does Y"
+- **Atomic:** one capability per line
+- **Independent:** minimal cross-requirement deps
+
+Present the FULL 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 loop.
+
+**Commit requirements:**
+
+```bash
+git add .planning/REQUIREMENTS.md 2>/dev/null && \
+  git commit -m "docs: define milestone v[X.Y] requirements" 2>/dev/null || \
+  echo "ℹ .planning/ gitignored — REQUIREMENTS.md written, not committed"
+```
+
+## 10. Create roadmap
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ rcode ► CREATING ROADMAP
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+◆ Spawning rcode-roadmapper...
+```
+
+**Starting phase number:**
+- If `--reset-phase-numbers` is active, start at **Phase 1**
+- Otherwise, continue from the previous milestone's last phase number (v1.7 ended at phase 67 → v1.8 starts at phase 68)
+
+Spawn `rcode-roadmapper` via Task tool:
+
+```
+<planning_context>
+<files_to_read>
+- .planning/PROJECT.md
+- .planning/REQUIREMENTS.md
+- .planning/research/SUMMARY.md (if exists)
+- .planning/MILESTONES.md (if exists)
+- .rcode/config.yaml
+</files_to_read>
+
+${AGENT_SKILLS_ROADMAPPER}
+</planning_context>
+
+<instructions>
+Create roadmap for milestone v[X.Y]:
+1. Respect the selected numbering mode:
+   - `--reset-phase-numbers` → start at Phase 1
+   - default → continue from the previous milestone's last phase number ([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% requirement coverage
+6. Write files immediately:
+   - .planning/ROADMAP.md
+   - .planning/STATE.md (update with new phase count)
+   - .planning/REQUIREMENTS.md (fill traceability matrix)
+7. Return "## ROADMAP CREATED" with summary, OR "## ROADMAP BLOCKED" with reason.
+
+Write files first, then return.
+</instructions>
+```
+
+**Handle return:**
+
+**If `## ROADMAP BLOCKED`:** present the blocker, collect resolution from user, re-spawn the roadmapper with revision context.
+
+**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" → collect notes, re-spawn
+- "Review full file" → print raw ROADMAP.md, re-ask
+
+**If "Adjust":** capture the delta as plain text, re-spawn roadmapper with revision context, loop.
+**If "Review":** cat ROADMAP.md, re-ask.
+
+**Commit roadmap (after approval):**
+
+```bash
+git add .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md 2>/dev/null && \
+  git commit -m "docs: create milestone v[X.Y] roadmap ([N] phases)" 2>/dev/null || \
+  echo "ℹ .planning/ gitignored — roadmap written, not committed"
+```
+
+Also record the milestone start in state and sync roadmapper phases:
+
+```bash
+node ".rcode/bin/rcode-tools.cjs" state add-decision \
+  --summary "Started milestone v[X.Y] [Name]: [N] phases, [X] requirements" 2>/dev/null || true
+
+# Sync all roadmapper-created phases into state.json.
+# rcode-roadmapper writes ROADMAP.md as text — it never calls `phase add` — so
+# state.json has no phase entries until this runs. Closes #504.
+node ".rcode/bin/rcode-tools.cjs" state sync --from-disk 2>/dev/null || true
+```
+
+## 11. Done
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ rcode ► 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]
+
+`/clear` then:
+
+`/rcode-discuss-phase [N]` — gather context and clarify approach
+or
+`/rcode-plan [N]` — skip discussion, plan directly
+```
+
+</process>
+
+<success_criteria>
+- [ ] PROJECT.md updated in-place with Current Milestone section
+- [ ] STATE.md reset for new milestone (status = defining_requirements)
+- [ ] MILESTONE-CONTEXT.md consumed and deleted (if existed)
+- [ ] Version number determined (v[X.Y+1] or v[X+1].0)
+- [ ] Milestone-summary confirmation loop ran until "Looks good"
+- [ ] Research completed (if selected) — 4 parallel researchers + synthesizer
+- [ ] Requirements gathered and scoped per category
+- [ ] REQUIREMENTS.md created with category-prefixed REQ-IDs
+- [ ] rcode-roadmapper spawned with correct phase numbering context
+- [ ] Roadmap files written immediately (not draft)
+- [ ] User approval captured before commit
+- [ ] Phase numbering mode respected (continued or reset)
+- [ ] All commits made (or gracefully skipped if .planning/ gitignored)
+- [ ] User shown next command: `/rcode-discuss-phase [N]`
+</success_criteria>
+
+<on_error>
+- **Empty `$ARGUMENTS` with no conversational context:** ask for milestone name; do not invent one.
+- **No `.planning/PROJECT.md`:** redirect to `/rcode-new-project`.
+- **Prior milestone not archived + `--reset-phase-numbers`:** stop, tell user to run `/rcode-complete-milestone` first.
+- **Roadmapper returns ROADMAP BLOCKED:** surface the blocker, collect resolution, re-spawn.
+- **`rcode-tools.cjs state` fails:** continue — state tracking is optional, file artifacts are mandatory.
+- **`.planning/` is gitignored:** write files, print ℹ notice, do not error.
+- **Phase archive completes but state.json write fails mid-sequence:** do NOT re-archive. Tell the user: "Phase archive completed but milestone state was not recorded. Recovery: run `node .rcode/bin/rcode-tools.cjs state sync --from-disk` then re-run `/rcode-new-milestone` — it will detect the existing archive and skip re-archiving."
+</on_error>
+</content>
+</invoke>
+
+## Next Up
+
+- `/rcode-plan-milestone` — plan all phases in the new milestone
+- `/rcode-discuss-phase` — discuss the first phase before planning