new-milestone

name	new-milestone
description	Set up a new milestone for development. Creates feature branch, updates current-story.md, and creates branch-specific next-prompt file with implementation guidance. TRIGGER when the user says "new milestone", "start a new milestone", "create milestone", "begin feature", "next milestone", "set up milestone", or any request to start a new development milestone.
argument-hint	<PREFIX-#.# brief description>

New Milestone Setup

Milestone: $ARGUMENTS

Step 0: Detect Identifier Format

Forager accepts two identifier formats (per docs/openspec-workflow-reference.md):

• Legacy M-format: M7.7, M9.16, M18.1.3 — historical work only (forward-only policy)
• New OpenSpec change-id: architecture-compliance-sweep, migrate-to-structured-logging — all new work

Normalize and validate the input via the shared utility:

bash .claude/skills/_shared/milestone-format.sh "$ARGUMENTS"
# Output: format=M|kebab  id=<identifier>  original=<identifier>
# Exit 2 if the input matches neither format

The skill's subsequent steps substitute <identifier> for the normalized ID regardless of format — branch names, PRD file names, next-prompt file names, and commit prefixes all use the identifier as-is.

Step 1: Verify Prerequisites

• Current branch: !git branch --show-current
• Main is up to date: !git log origin/main..main --oneline

If not on main, switch to main and pull:

git checkout main && git pull origin main

Step 2: Create Feature Branch

Branch naming:

• Legacy M-format: feature/M9.16-brief-kebab-case (3-5 words max)
• New OpenSpec change-id: feature/<change-id> (the change-id is already kebab-case; no extra suffix needed)

# Legacy example
git checkout -b feature/M9.16-grocery-list-item-service
git push -u origin feature/M9.16-grocery-list-item-service

# New OpenSpec example
git checkout -b feature/architecture-compliance-sweep
git push -u origin feature/architecture-compliance-sweep

Step 3: Update docs/current-story.md

• Add new milestone section with status ACTIVE
• Include: scope, estimated hours, sub-phases if known
• Update the priority queue

Step 4: Create Branch-Specific Next-Prompt File

The file name matches the milestone ID you pass (e.g., next-prompt-AUTH-1.md for AUTH-1, or next-prompt-AUTH-1.3.md for AUTH-1.3). Sub-tasks can share a parent file or have their own.

Create docs/next-prompt-[milestone].md:

# [milestone] — ACTIVE: [Title]

**PRD**: [path to PRD if exists]
**Branch**: feature/[milestone]-description
**Problem**: [What needs to be solved]

---

## What's Done
- [Completed items]

## What's Left
- [Remaining items]

## Key Design Decisions
1. [Decision and rationale]

## Key Files
- [file paths relevant to this work]

Then add a pointer line in docs/next-prompt.md under Active Milestones:

- [PREFIX-#: Title](next-prompt-PREFIX-#.md) — Branch: `feature/PREFIX-#-description` | Status: ACTIVE

Step 5: Check for PRD

• Search docs/prds/active/ for an existing PRD for this milestone
• If PRD exists and is >2 weeks old, audit it against current codebase
• If no PRD exists and milestone is >6 hours, consider creating one

Step 6: Write Status Line

Write the initial status label for the new branch. The status-line helper derives the branch-slug from the current branch, so no manual slugging needed:

bash .claude/skills/_shared/status-line.sh write "[<identifier>] setup"

Update with a more specific focus (e.g., "[<identifier>] phase 1 — scaffolding") as soon as work on the first phase begins.

Step 7: Initial Commit

git add docs/current-story.md docs/next-prompt.md docs/next-prompt-[milestone].md
git commit -m "PREFIX-#.#: Set up milestone - [description]"
git push

Verification

• On feature branch (not main)
• Branch name follows feature/PREFIX-#.#-description format
• current-story.md updated with ACTIVE status
• docs/next-prompt-[milestone].md created with implementation guidance
• docs/next-prompt.md has pointer to branch-specific file under Active Milestones
• Branch-keyed status file written via status-line.sh write
• Initial commit pushed to remote