/add-release

<objective> Add a new integer release to the end of the current milestone in the roadmap.

This command appends sequential releases to the current milestone's release list, automatically calculating the next release number based on existing releases.

Purpose: Add planned work discovered during execution that belongs at the end of current milestone. </objective>

<execution_context> @.planning/ROADMAP.md @.planning/STATE.md </execution_context>

<process> <step name="parse_arguments"> Parse the command arguments: - All arguments become the release description - Example: `/cat:add-release Add authentication` → description = "Add authentication" - Example: `/cat:add-release Fix critical performance issues` → description = "Fix critical performance issues"

If no arguments provided:

ERROR: Release description required
Usage: /cat:add-release <description>
Example: /cat:add-release Add authentication system

Exit. </step>

<step name="load_roadmap"> Load the roadmap file:

if [ -f .planning/ROADMAP.md ]; then
  ROADMAP=".planning/ROADMAP.md"
else
  echo "ERROR: No roadmap found (.planning/ROADMAP.md)"
  exit 1
fi

Read roadmap content for parsing. </step>

<step name="find_current_milestone"> Parse the roadmap to find the current milestone section:

1. Locate the "## Current Milestone:" heading
2. Extract milestone name and version
3. Identify all releases under this milestone (before next "---" separator or next milestone heading)
4. Parse existing release numbers (including decimals if present)

Example structure:

## Current Milestone: v1.0 Foundation

### Release 4: Focused Command System
### Release 5: Path Routing & Validation
### Release 6: Documentation & Distribution

</step> <step name="calculate_next_phase"> Find the highest integer release number in the current milestone:

1. Extract all release numbers from release headings (### Release N:)
2. Filter to integer releases only (ignore decimals like 4.1, 4.2)
3. Find the maximum integer value
4. Add 1 to get the next release number

Example: If releases are 4, 5, 5.1, 6 → next is 7

Format as two-digit: printf "%02d" $next_phase </step>

<step name="generate_slug"> Convert the release description to a kebab-case slug:

# Example transformation:
# "Add authentication" → "add-authentication"
# "Fix critical performance issues" → "fix-critical-performance-issues"

slug=$(echo "$description" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//')

Release directory name: {two-digit-release}-{slug} Example: 07-add-authentication </step>

<step name="create_phase_directory"> Create the release directory structure:

phase_dir=".planning/releases/${phase_num}-${slug}"
mkdir -p "$phase_dir"

Confirm: "Created directory: $phase_dir" </step>

<step name="update_roadmap"> Add the new release entry to the roadmap:

1. Find the insertion point (after last release in current milestone, before "---" separator)

2. Insert new release heading:

   ### Release {N}: {Description}
   
   **Goal:** [To be planned]
   **Depends on:** Release {N-1}
   **Changes:** 0 changes
   
   Changes:
   - [ ] TBD (run /cat:change-release {N} to break down)
   
   **Details:**
   [To be added during planning]
   

3. Write updated roadmap back to file

Preserve all other content exactly (formatting, spacing, other releases). </step>

<step name="update_project_state"> Update STATE.md to reflect the new release:

1. Read .planning/STATE.md
2. Under "## Current Position" → "Next Release:" add reference to new release
3. Under "## Accumulated Context" → "### Roadmap Evolution" add entry:

   - Release {N} added: {description}
   

If "Roadmap Evolution" section doesn't exist, create it. </step>

<step name="completion"> Present completion summary:

Release {N} added to current milestone:
- Description: {description}
- Directory: .planning/releases/{release-num}-{slug}/
- Status: Not planned yet

Roadmap updated: {roadmap-path}
Project state updated: .planning/STATE.md

---

## ▶ Next Up

**Release {N}: {description}**

`/cat:change-release {N}`

<sub>`/clear` first → fresh context window</sub>

---

**Also available:**
- `/cat:add-release <description>` — add another release
- Review roadmap

---

</step> </process>

<anti_patterns>

• Don't modify releases outside current milestone
• Don't renumber existing releases
• Don't use decimal numbering (that's /cat:insert-release)
• Don't create changes yet (that's /cat:change-release)
• Don't commit changes (user decides when to commit) </anti_patterns>

<success_criteria> Release addition is complete when:

• Release directory created: .planning/releases/{NN}-{slug}/
• Roadmap updated with new release entry
• STATE.md updated with roadmap evolution note
• New release appears at end of current milestone
• Next release number calculated correctly (ignoring decimals)
• User informed of next steps </success_criteria>