ijfw-new-milestone

name	ijfw-new-milestone
description	Use when the user says: 'new milestone', 'next milestone', 'plan milestone', 'start milestone', 'begin v1.2', 'kick off next release', 'next chapter', 'next campaign wave', 'next design tier', /ijfw-new-milestone
since	1.5.0

IJFW New Milestone

Kick off a new milestone cycle on an existing project. Brownfield equivalent of project bootstrap: project exists, prior milestones shipped, you need a scoped plan for the next iteration.

Domain-agnostic. Works for software releases (v1.2 → v1.3), book chapters (Ch 4 → Ch 5), campaign waves (Wave 2 → Wave 3), design-system tiers (Foundation → Components → Patterns).

Optional $ARGUMENTS: milestone name (e.g. v1.6 Notifications, Chapter 5: Adversarial Models). Ask inline if absent.

1 — Load prior context

Read in order:

• .planning/PROJECT.md — core value, validated outcomes, decisions
• .planning/ROADMAP.md — what shipped, last milestone number/name
• .planning/MILESTONES.md — historical log (if present)
• .planning/STATE.md — pending todos, blockers carried forward
• Latest .planning/<prior-milestone>/LEARNINGS.md (if present) — dispatch ijfw-extract-learnings agent on the prior milestone first if missing; learnings inform what to do differently this cycle.

If .planning/ROADMAP.md is absent, dispatch ijfw-roadmapper agent to scaffold one from PROJECT.md, then resume here.

2 — Determine next milestone identifier

Parse the last milestone from MILESTONES.md or ROADMAP.md. Suggest the next per project convention:

• Semver: v1.5 → v1.6 (minor) / v1.5 → v2.0 (major)
• Chapter / Wave: N → N+1
• Free-form: ask the user

Confirm before writing anything.

3 — Gather scope (adaptive)

Ask one open question: What do you want to ship in this milestone? (one sentence)

Then probe by domain bucket (pick what fits, skip the rest):

• Capabilities — new functionality / features / chapters / campaign assets
• Quality — coverage, perf, accessibility, edit passes, brand consistency
• Trust — security, audits, fact-checks, compliance, source alignment
• Ecosystem — integrations, partners, distribution channels, platform support
• Reduction — deprecations, cuts, tightening, scope-creep kills

Per activated bucket ask: Table stakes vs differentiators? Table stakes go in; differentiators debated.

If prior LEARNINGS.md exists, surface its top 3 "do differently" items and ask which to act on.

4 — Verify understanding before writing

Present a summary block and ask for confirmation:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 IJFW ► MILESTONE SUMMARY
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Milestone: <identifier> — <name>

Goal: <one sentence>

In scope:
  - <bucket>: <item 1>, <item 2>
  - <bucket>: <item 3>

Out of scope (explicit):
  - <thing user declined>

Learnings applied:
  - <from prior LEARNINGS.md>

Success criteria (top-level):
  1. <observable outcome>
  2. <observable outcome>
  3. <observable outcome>

Ask: "Does this capture it? (looks good / adjust)". Loop until confirmed.

5 — Write artifacts

Atomically create/update:

• .planning/<milestone>/HANDOFF.md — skeleton with: identifier, goal, scope buckets, success criteria, "what shipped last", "what's deferred from last", initial plan-item list. This is the durable per-milestone home.
• .planning/PROJECT.md — append ## Current Milestone: <id> block with goal + target buckets. Update the footer timestamp.
• .planning/STATE.md — reset status to planning, zero progress counters, preserve accumulated context (decisions, blockers, todos).
• .planning/ROADMAP.md — append milestone entry with placeholder phase list (filled in step 6).

HANDOFF.md skeleton:

# Handoff — <Milestone Identifier>

Updated: <ISO date>
Goal: <one sentence>

## Inputs
- Prior milestone: <id> (LEARNINGS: <path or "n/a">)
- Carried forward: <pending blockers from prior STATE.md>

## Scope (in)
- <bucket>: <item>, <item>
- <bucket>: <item>

## Out of scope (explicit)
- <item> — <reason>

## Success criteria
1. <observable>
2. <observable>
3. <observable>

## Plan items (filled by ijfw-spec-phase + ijfw-discuss-phase per item)
- [ ] <item-id>: <title> — status: pending
- [ ] <item-id>: <title> — status: pending

## Resume protocol
Next session: read this file, run `/ijfw-execute <item-id>` for the first
pending item. Each item completes atomically with its own commit.

6 — Per-item clarification (dispatch downstream)

For each scope item that is non-trivial, route through:

1. ijfw-spec-phase skill — clarify WHAT the item delivers (success-vs-ambiguity check). Writes per-item SPEC.md.
2. ijfw-discuss-phase agent — gather context on HOW (constraints, approach, edge cases). Updates the SPEC and/or writes per-item DISCUSS.md.

Trivial items (one-line task, low ambiguity, no cross-cutting risk) skip both and go straight into HANDOFF.md as plan items.

Do not plan execution here. That belongs to ijfw-plan for each item once spec + discuss land.

7 — Commit

Two commits, atomic per concern:

git add .planning/PROJECT.md .planning/STATE.md
git commit -m "docs(<milestone>): start milestone — goal + scope"

git add .planning/<milestone>/HANDOFF.md .planning/ROADMAP.md
git commit -m "docs(<milestone>): handoff skeleton + roadmap entry"

If any SPEC.md / DISCUSS.md files landed in step 6, commit those per-item with their own atomic commits (the dispatched skill/agent handles its own commit).

8 — Hand off, emit:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 IJFW ► MILESTONE <id> INITIALIZED
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Milestone: <id> — <name>
Items: <N> planned (<M> spec'd, <K> discussed)
Artifacts:
  - .planning/<milestone>/HANDOFF.md
  - .planning/PROJECT.md (updated)
  - .planning/ROADMAP.md (updated)
  - .planning/STATE.md (reset)

Next: `/ijfw-plan <first-item-id>` to plan execution of the first item.

Invariants

• Never overwrite a non-empty HANDOFF.md without explicit "yes, overwrite"; use it as input if present.
• Never delete prior milestone directories — they're historical record; archival is separate explicit action.
• Domain words (phase / chapter / wave / tier) come from PROJECT.md's "Project type" — never hardcoded.
• All artifacts plain markdown. Positive framing: "Ready to plan" not "nothing planned yet".

Downstream skills/agents referenced

• ijfw-roadmapper (agent, W12-B C03) — scaffolds initial ROADMAP.md when absent
• ijfw-spec-phase (skill, W12-B C05) — per-item WHAT clarification
• ijfw-discuss-phase (agent, W12-B C05) — per-item HOW context
• ijfw-extract-learnings (agent, W12-B C06) — prior-milestone learnings
• ijfw-plan (existing) — per-item execution planning (user calls after this skill exits)