---
roadcrew_template_name: "update-roadmap.md"
roadcrew_template_type: "command"
execution_mode: "auto-execute"
roadcrew_template_version: "v1.0"
roadcrew_last_updated: "2025-10-25"
roadcrew_min_version: "1.5.0"
roadcrew_license: "See LICENSE file in .roadcrew folder"
roadcrew_copyright: "Copyright (c) 2025 North Star Holdings, LLC"
spdx_license_identifier: "LicenseRef-RoadcrewLicense-1.0"
---
# update-roadmap

<!-- Usage: /update-roadmap <version> <scope-prefix> -->

You are adding a new release milestone to `memory-bank/releases/future-releases.md` based on generated BRD, PRD, and Spec documents.

**Input:** Release version (e.g., `v1.6.0`) and document prefix (e.g., `license-enforcements`)
**Output:** Updated `memory-bank/releases/future-releases.md` with new release section inserted in correct semantic version order
**Prerequisites:** Generated BRD, PRD, and Spec must exist in `memory-bank/requirements/brds/`, `memory-bank/requirements/prds/`, `memory-bank/requirements/specs/`

---

## WORKFLOW

### 0. PRE-FLIGHT CHECKS

**Validate inputs:**
- Release version format: `v\d+\.\d+\.\d+` (e.g., `v1.6.0`)
- Scope prefix: alphanumeric with hyphens (e.g., `license-enforcement`)

**Check release doesn't already exist:**
```bash
if grep -q "^## $VERSION:" memory-bank/releases/future-releases.md; then
  echo "❌ Error: Release $VERSION already exists in future-releases.md"
  exit 1
fi
```

**Validate required documents exist:**
```bash
BRD="memory-bank/requirements/brds/${PREFIX}-brd.md"
PRD="memory-bank/requirements/prds/${PREFIX}-prd.md"
SPEC="memory-bank/requirements/specs/${PREFIX}-spec.md"

for doc in "$BRD" "$PRD" "$SPEC"; do
  if [ ! -f "$doc" ]; then
    echo "❌ Error: Required document not found: $doc"
    echo "Generate with: /create-release-docs $PREFIX"
    exit 1
  fi
done
```

### 1. FIND INSERTION POINT

**Extract all versions from future-releases.md:**
```bash
VERSIONS=$(grep "^## v" memory-bank/releases/future-releases.md | sed 's/.*\(v[0-9.]*\).*/\1/' | sort -V)
```

**Find correct insertion point by semantic version:**
- Parse existing versions: v1.5.0, v2.0.0, v3.0.0, etc.
- Sort using version sort (not alphabetical)
- Determine insertion line:
  - If v1.6.0 provided and v1.5.0 exists but v2.0.0 doesn't: insert after v1.5.0
  - If v1.5.1 provided and v1.5.0 exists but v1.6.0 doesn't: insert after v1.5.0
  - Show: "✅ Inserting v1.6.0 between v1.5.0 and v2.0.0"

### 2. EXTRACT INFORMATION FROM DOCUMENTS

**Read BRD (memory-bank/requirements/brds/[prefix]-brd.md):**
- Extract: `title` from frontmatter
- Extract: Section 2 (Business Context) - segments, revenue, differentiators
- Extract: Section 3 (Business Goals) - 3-4 key goals
- Extract: Section 7 (Metrics) - success metrics

**Read PRD (memory-bank/requirements/prds/[prefix]-prd.md):**
- Extract: `feature` from frontmatter
- Extract: Section 2 (Problem Statement)
- Extract: Section 4.1 (Functional Requirements R1-R6)
- Extract: Section 6 (User Stories)

**Read Spec (memory-bank/requirements/specs/[prefix]-spec.md):**
- Extract: Section 2.1 (Functional Requirements)
- Extract: Section 5 (Architecture & Implementation)
- Extract: Section 8 (Issue Breakdown) - all issues with classifications
- Count total issues

### 3. GENERATE RELEASE SECTION

**Create new release section using template structure:**

```markdown
## v[VERSION]: [Title from BRD] 📋 NEXT

**Goal:** [Synthesize from BRD executive summary + PRD problem statement]

**Prerequisites:**
- [Dependencies from previous releases]

**Estimated Timeline:** [Infer from issue count/complexity]

**Focus Metrics:**
- [From BRD § 7.1-7.3, 3-5 metrics]

**Key Use Cases:**
- [From PRD § 6 User Stories, convert to use cases]

**Scope:**
- [From Spec § 8 Issue Breakdown, group by epic/phase]

**Success Criteria:**
- [ ] [Acceptance criteria from PRD § 4.3]

**Epics:**
- **Epic 1: [Issue grouping]** - [Description]
- **Epic 2: [Issue grouping]** - [Description]

**Value:** [From BRD business impact]

---

### EPIC 1: [Title]

**Goal:** [Goal statement]

**Related Spec**: [Link to spec]
**Related PRD**: [Link to PRD]
**Related BRD**: [Link to BRD]

**Prerequisites:**
- [From spec dependencies]

**Estimated Timeline:** [Based on issues]

**Issues:**

[All issues from Spec § 8 Issue Breakdown formatted as:]

#### Issue 1.1: [Title]

**Classification**: [1-10 from spec]

**Overview:** [From spec Overview field]

**Acceptance Criteria:**
- [From spec Accepts field]

**Technical Implementation:**
- [From spec Tech Approach field]

**Dependencies:** [From spec Dependencies field]

**Files/Components:** [From spec Files/Components]

**Estimated Effort:** [Calculate from size/complexity]
```

### 4. INSERT INTO FUTURE-RELEASES.MD

**Find line number of next version section:**
```bash
# If inserting v1.6.0 before v2.0.0:
INSERT_LINE=$(grep -n "^## v2.0.0:" memory-bank/releases/future-releases.md | cut -d: -f1)

# Insert new section at that line
sed -i "${INSERT_LINE}i\\$NEW_SECTION" memory-bank/releases/future-releases.md
```

**Update NEXT marker:**
- Remove `📋 NEXT` from previous next release
- Add `📋 NEXT` to newly inserted release

### 5. VALIDATION & OUTPUT

**Verify insertion:**
```bash
if grep -q "^## $VERSION:" memory-bank/releases/future-releases.md; then
  echo "✅ Release section created: $VERSION"
else
  echo "❌ Failed to insert release section"
  exit 1
fi
```

**Display summary:**
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ Roadmap Updated: v1.6.0 - License Enforcement
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Release Position: After v1.5.0, Before v2.0.0

Documents Integrated:
📊 BRD: memory-bank/requirements/brds/license-enforcement-brd.md
- 3 market segments
- 4 business goals
- 6 metrics across 3 categories

📝 PRD: memory-bank/requirements/prds/license-enforcement-prd.md
- 6 functional requirements
- 5 user stories
- 5-step user journey

⚙️ Spec: memory-bank/requirements/specs/license-enforcement-spec.md
- 6 implementation issues
- 3 data models
- 6 API endpoints

Updated: memory-bank/releases/future-releases.md
- Version v1.6.0 inserted (📋 NEXT marker updated)
- Previous 📋 NEXT (v1.5.0) replaced with 📋 Complete

Next Steps:
1. Review: memory-bank/releases/future-releases.md
2. Run: /guide-release to validate alignment
3. Commit: git add memory-bank/releases/ && git commit -m "chore: add v1.6.0 roadmap"

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

---

## ERROR HANDLING

**Invalid version format:**
```
❌ Error: Invalid version format: "1.6.0"
   Expected format: v1.6.0 (v + semver)
```

**Version already exists:**
```
❌ Error: Release v1.6.0 already exists in future-releases.md
   Existing releases: v1.1.0, v1.5.0, v2.0.0
```

**Missing documents:**
```
❌ Error: Required document not found: memory-bank/requirements/brds/license-enforcement-brd.md
   Generate with: /create-release-docs license-enforcement
```

**Invalid prefix:**
```
❌ Error: Invalid prefix: "license_enforcement"
   Use hyphens: license-enforcement
```

---

## GUARDRAILS

1. **Version Validation:**
   - Must be valid semver (v\d+\.\d+\.\d+)
   - Must not already exist in future-releases.md
   - Must be properly sorted relative to existing versions

2. **Document Validation:**
   - All three documents (BRD, PRD, Spec) must exist
   - Documents must have proper frontmatter with type field
   - All required sections must be present

3. **Insertion Safety:**
   - Creates backup of future-releases.md before modification
   - Verifies insertion succeeded before marking complete
   - Preserves markdown formatting and structure

4. **NEXT Marker:**
   - Only one release has 📋 NEXT at a time
   - Previous NEXT automatically updated when new release inserted
   - Validates marker placement after insertion

---

**Behavior:**
- If invoked with version and prefix (e.g., `/update-roadmap v1.6.0 license-enforcement`), run workflow
- If no arguments provided, prompt for version and prefix
- If invalid arguments, show error and usage examples
- Always create backup before modifying future-releases.md
- Display summary with next steps upon completion