kata-add-milestone

What this skill does

<objective>
Add a milestone to the project through unified flow: questioning → research (optional) → requirements → roadmap.

This works for both first milestone (after /kata-new-project) and subsequent milestones (after completing a milestone).

**Creates/Updates:**

- `.planning/PROJECT.md` — updated with new milestone goals
- `.planning/research/` — domain research (optional, focuses on NEW features)
- `.planning/REQUIREMENTS.md` — scoped requirements for this milestone
- `.planning/ROADMAP.md` — phase structure (creates if first, continues if subsequent)
- `.planning/STATE.md` — reset for new milestone (creates if first)

**After this command:** Run `/kata-plan-phase [N]` to start execution.
</objective>

<execution_context>
@./references/questioning.md
@./references/ui-brand.md
@./references/project-template.md
@./references/requirements-template.md
@./references/github-mapping.md
</execution_context>

<context>
Milestone name: $ARGUMENTS (optional - will prompt if not provided)

**Load project context:**
@.planning/PROJECT.md
@.planning/STATE.md
@.planning/MILESTONES.md
@.planning/config.json

**Load milestone context (if exists):**
@.planning/MILESTONE-CONTEXT.md
</context>

<process>

## Phase 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 (if exists)

## Phase 1.2: Pre-flight Roadmap Format Check

If ROADMAP.md exists, check format and auto-migrate if old:

```bash
if [ -f .planning/ROADMAP.md ]; then
  node "${CLAUDE_PLUGIN_ROOT}/skills/kata-add-milestone/scripts/kata-lib.cjs" check-roadmap 2>/dev/null
  FORMAT_EXIT=$?

  if [ $FORMAT_EXIT -eq 1 ]; then
    echo "Old roadmap format detected. Running auto-migration..."
  fi
fi
```

**If exit code 1 (old format):**

Invoke kata-doctor in auto mode:

```
Skill("kata-doctor", "--auto")
```

Continue after migration completes.

**If exit code 0 or 2:** Continue silently.

```bash
# Validate config
node "${CLAUDE_PLUGIN_ROOT}/skills/kata-add-milestone/scripts/kata-lib.cjs" check-config 2>/dev/null || true
```

## Phase 1.5: Optional Brainstorm

Use AskUserQuestion:

- header: "Brainstorm"
- question: "Brainstorm ideas before defining milestone goals?"
- options:
  - "Brainstorm first" — Run explorer/challenger brainstorm session
  - "Skip" — Continue without brainstorming

**If "Brainstorm first":**

Display:

```
Launching brainstorm session...
```

Run `/kata-brainstorm`

After brainstorm completes, continue to Phase 2.

**If "Skip":** Continue to Phase 2.

## Phase 2: Gather Milestone Goals

**If MILESTONE-CONTEXT.md exists:**

- Use features and scope from the context file
- 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
- Probe for priorities, constraints, scope

## Phase 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

## Phase 4: Update PROJECT.md

Add/update these sections:

```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 with new goals.

Update "Last updated" footer.

## Phase 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 (decisions, blockers) from previous milestone.

## Phase 5.5: Create GitHub Milestone (if enabled)

Read GitHub config:

```bash
GITHUB_ENABLED=$(node "${CLAUDE_PLUGIN_ROOT}/skills/kata-add-milestone/scripts/kata-lib.cjs" read-config "github.enabled" "false")
```

**If `GITHUB_ENABLED=true`:**

**Step 1: Validate GitHub remote exists**

```bash
HAS_GITHUB_REMOTE=$(git remote -v 2>/dev/null | grep -q 'github\.com' && echo "true" || echo "false")
```

**If `HAS_GITHUB_REMOTE=false`:**

Use AskUserQuestion to offer repo creation:

- header: "GitHub Repository"
- question: "GitHub tracking is enabled but no GitHub remote found. Create a repository now?"
- options:
  - "Yes, create private repo (Recommended)" — Create private repository and push
  - "Yes, create public repo" — Create public repository and push
  - "Skip for now" — Continue without GitHub integration

**If "Yes, create private repo":**

```bash
gh repo create --source=. --private --push
```

If successful, set `HAS_GITHUB_REMOTE=true` and continue to Step 2 (Check authentication).

**If "Yes, create public repo":**

```bash
gh repo create --source=. --public --push
```

If successful, set `HAS_GITHUB_REMOTE=true` and continue to Step 2 (Check authentication).

**If "Skip for now":**
Display brief note and continue with local milestone initialization:

```
Continuing without GitHub integration. Run `gh repo create` later to enable.
```

Do NOT set github.enabled=false in config - user may add remote later.

**If `HAS_GITHUB_REMOTE=true`:**

**Step 2: Check authentication (non-blocking)**

```bash
if ! gh auth status &>/dev/null; then
  echo "Warning: GitHub CLI not authenticated. Run 'gh auth login' to enable GitHub integration."
  # Continue without GitHub operations - local milestone still created
else
  # Proceed with milestone creation
fi
```

**Step 3: Check if milestone exists (idempotent)**

```bash
MILESTONE_EXISTS=$(gh api /repos/:owner/:repo/milestones 2>/dev/null | jq -r ".[] | select(.title==\"v${VERSION}\") | .number" 2>/dev/null)
```

**Step 4: Create milestone if doesn't exist**

```bash
if [ -z "$MILESTONE_EXISTS" ]; then
  # Extract milestone description (first paragraph of goal, truncated to 500 chars)
  MILESTONE_DESC=$(echo "$MILESTONE_GOALS" | head -1 | cut -c1-500)

  gh api \
    --method POST \
    -H "Accept: application/vnd.github.v3+json" \
    /repos/:owner/:repo/milestones \
    -f title="v${VERSION}" \
    -f state='open' \
    -f description="${MILESTONE_DESC}" \
    2>/dev/null && echo "GitHub Milestone v${VERSION} created" || echo "Warning: Failed to create GitHub Milestone (continuing)"
else
  echo "GitHub Milestone v${VERSION} already exists (#${MILESTONE_EXISTS})"
fi
```

**If `GITHUB_ENABLED=false`:**

Skip GitHub operations silently (no warning needed - user opted out).

**Error handling principle:**

- All GitHub operations are non-blocking
- Missing remote warns but does not stop milestone initialization
- Auth failures warn but do not stop milestone initialization
- Planning files always persist locally regardless of GitHub status

## Phase 6: Cleanup and Commit

Delete MILESTONE-CONTEXT.md if exists (consumed).

Check planning config:

```bash
COMMIT_PLANNING_DOCS=$(node "${CLAUDE_PLUGIN_ROOT}/skills/kata-add-milestone/scripts/kata-lib.cjs" read-config "commit_docs" "true")
git check-ignore -q .planning 2>/dev/null && COMMIT_PLANNING_DOCS=false
```

If `COMMIT_PLANNING_DOCS=false`: Skip git operations

If `COMMIT_PLANNING_DOCS=true` (default):

```bash
git add .planning/PROJECT.md .planning/STATE.md
git commit -m "docs: start milestone v[X.Y] [Name]"
```

## Phase 6.5: Resolve Model Profile

Read model profile for agent spawning:

```bash
MODEL_PROFILE=$(node "${CLAUDE_PLUGIN_ROOT}/skills/kata-add-milestone/scripts/kata-lib.cjs" read-config "model_profile" "balanced")
```

Default to "balanced" if not set.

**Model lookup table:**

| Agent                     | quality | balanced | budget |
| ------------------------- | ------- | -------- | ------ |
| kata-project-researcher   | opus    | sonnet   | haiku  |
| kata-research-synthesizer | sonnet  | sonnet   | haiku  |
| kata-roadmapper           | opus    | sonnet   | sonnet |

Store resolved models for use in Task calls below.

## Phase 7: Research Decision

Use AskUserQuestion:

- header: "Resea