/milestone

description: Create, manage, and ship milestones — the top-level planning layer for feature development
argument-hint: "[create <name> [--plan <file>] [--greenfield] [--spike <path>] | status | ship <slug> | sync <slug>]"
install: extras

<!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios --> <!-- SPDX-License-Identifier: AGPL-3.0-or-later -->

/milestone — Milestone Lifecycle Manager

> **Skill names**: `{FORGE_SKILL_PREFIX}` is `forgedock:` (plugin install) or empty (`install.sh`), resolved once per run by `commands/work-on.md` § Skill Name Resolution. If the skill is not found under either name, STOP and report "skill not found" — never run the phase inline.

**Input**: $ARGUMENTS

Milestones are the top-level planning unit. They group related issues into a shippable feature set. Each milestone gets its own long-lived Git branch (`milestone/{slug}`) where feature PRs accumulate. When the milestone is ready, it ships to `main` as a single reviewed merge.

**Hierarchy**: Milestone → Issues → Sub-issues (optional decomposition)

**NEVER use plan mode (EnterPlanMode).** **NEVER use the Agent tool for issue work** — milestone dispatches issue work via `Skill(skill="{FORGE_SKILL_PREFIX}work-on", ...)` only. Agent bypasses the Skill pipeline's label state machine, FORGE annotations and structured review; use it only to coordinate milestone planning (e.g. parallel issue-list queries), never for /work-on sub-dispatch.

<!-- FORGE:SPEC_LOADED — milestone.md loaded and active. Agent is bound by this spec. -->

**You have access to Task, Skill, and Bash tools** for milestone coordination.

Config Resolution

Read `forge.yaml` at the project root to resolve all project-specific variables before running any commands:

# Parse forge.yaml for project context
CONFIG_FILE="${FORGE_CONFIG:-forge.yaml}"
GH_REPO=$(yq '.project.owner + "/" + .project.repo' "$CONFIG_FILE")
GH_FLAG="-R $GH_REPO"
REPO_PATH=$(yq '.paths.root' "$CONFIG_FILE")
PROJECT_NAME=$(yq '.project.name' "$CONFIG_FILE")
STAGING_BRANCH=$(yq '.branches.staging' "$CONFIG_FILE")
DEFAULT_BRANCH=$(yq '.branches.default' "$CONFIG_FILE")
PROJECT_BOARD_OWNER=$(yq '.project_board.owner // .project.owner' "$CONFIG_FILE")
PROJECT_NUMBER=$(yq '.project_board.project_number // empty' "$CONFIG_FILE" 2>/dev/null || echo "")
PROJECT_ID=$(yq '.project_board.project_id // empty' "$CONFIG_FILE" 2>/dev/null || echo "")
# Project board field and option IDs — empty string when project_board section is absent
STATUS_FIELD_ID=$(yq '.project_board.field_ids.status // ""' "$CONFIG_FILE" 2>/dev/null || echo "")
LANE_FIELD_ID=$(yq '.project_board.field_ids.lane // ""' "$CONFIG_FILE" 2>/dev/null || echo "")
COMPONENT_FIELD_ID=$(yq '.project_board.field_ids.component // ""' "$CONFIG_FILE" 2>/dev/null || echo "")
PRIORITY_FIELD_ID=$(yq '.project_board.field_ids.priority // ""' "$CONFIG_FILE" 2>/dev/null || echo "")
STATUS_TODO_OPTION_ID=$(yq '.project_board.option_ids.status.todo // ""' "$CONFIG_FILE" 2>/dev/null || echo "")
LANE_FEATURE_OPTION_ID=$(yq '.project_board.option_ids.lane.feature // ""' "$CONFIG_FILE" 2>/dev/null || echo "")
PRIORITY_OPTION_ID=""  # Resolved per-issue from the issue's priority label — see Step 6B
# Build satellite repo map from repos.satellites list
# Each satellite: { prefix, repo, staging_branch }

All `{GH_REPO}`, `{GH_FLAG}`, `{REPO_PATH}`, `{PROJECT_NAME}`, `{STAGING_BRANCH}`, `{DEFAULT_BRANCH}`, `{PROJECT_BOARD_OWNER}`, `{PROJECT_NUMBER}`, `{PROJECT_ID}`, `{STATUS_FIELD_ID}`, `{LANE_FIELD_ID}`, `{COMPONENT_FIELD_ID}`, `{PRIORITY_FIELD_ID}`, `{STATUS_TODO_OPTION_ID}`, and `{LANE_FEATURE_OPTION_ID}` references below are populated from `forge.yaml`.

---

Multi-Repo Support

Milestones can span multiple repositories. Project context (repo map, paths, conventions) comes from `forge.yaml`.

Cross-Repo Milestones

Some milestones require changes across multiple repos — the platform, SDKs, satellite services, etc. For these:

• **The milestone is created in the primary repo** (`{GH_REPO}` — the default repo from `forge.yaml`)
• **Issues are created in the repo where the code lives** — satellite repos come from `forge.yaml → repos.satellites`
• **Each repo gets its own milestone branch** (`milestone/{slug}`) if it has issues in the milestone
• **Issues reference the parent milestone** in their body: `Part of cross-repo milestone: **{TITLE}** (primary: {GH_REPO})`

Repo Prefixes (same as `/work-on`)

Prefixes and repos are defined in `forge.yaml → repos.satellites`. Read the config to build the routing table:

| Prefix | Repo | |--------|------| | _(none)_ | `{GH_REPO}` (default) | | `{SATELLITE_PREFIX}:` | `{SATELLITE_REPO}` (from `forge.yaml → repos.satellites`) |

When decomposing a milestone, tag each proposed issue with its target repo. Use `-R {SATELLITE_REPO}` flag for non-default repos.

---

Command Router

Parse `$ARGUMENTS` to determine which action to take:

| Input Pattern | Action | |--------------|--------| | `create <name>` or just a descriptive phrase | → **Create Milestone** | | `create <name> --plan <file>` / `--greenfield` / `--spike <path>` | → **Create Milestone**, greenfield mode (Step 4G) | | `status` (no args, or "status") | → **Show All Milestones** | | `status <slug>` | → **Show Milestone Detail** | | `ship <slug>` | → **Ship Milestone** | | `sync <slug>` | → **Sync Milestone Branch** | | `drift <slug>` | → **Milestone Drift** | | `close <slug>` | → **Close Milestone** |

---

Action: Create Milestone

Step 1: Parse the milestone scope

The user provides a name or description. Extract:

• **Title**: Short, descriptive (e.g., "LLM Extraction Platform", "API Expansion v1")
• **Slug**: Lowercase, hyphenated, max 40 chars (e.g., `llm-extraction-platform`)
• **Description**: What this milestone delivers, extracted from user's input

Optional greenfield flags (strip them from the name before deriving title and slug): <!-- Added: forge#4175 -->

| Flag | Meaning | |-----