---
roadcrew_template_name: "guide-release.md"
roadcrew_template_type: "command"
roadcrew_template_version: "v1.0"
roadcrew_last_updated: "2025-10-29"
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"
execution_mode: "auto-execute"
---

# guide-release

Guide end-to-end release process: scope → release PR → tagging → validation. Orchestrates RELEASE phase with confirmation checkpoints and auto-remediation.

> **Execution:** Runs immediately. Confirmation checkpoints at critical gates only (merge/tag/release).

**Cost Optimization:** Concise, action-first responses with automatic file updates and script validation.

## Usage

```
/guide-release
```

## What This Command Does

This command creates a TODO list with both human 👤 and AI 🤖 tasks in the proper order to ensure:
1. All documentation is properly structured
2. All documents are properly aligned with each other
3. All information is accurate before advancing releases
4. Proper workflow: review → update → validate → advance → scope

**Cost Optimization:**
- AI responses use concise, structured format
- Multiple analysis tasks consolidated
- Scripts used instead of AI when possible
- Typical savings: 65-70% token costs vs verbose mode

## Steps

### Phase 1: Pre-Flight Checks 🔍

**📁 Context Setup:** Close all files except `memory-bank/releases/current-release.md`

#### Task 1: Check Current Release Completion 👤

**Human Action Required:**
- Review `memory-bank/releases/current-release.md`
- Check all "Release Criteria" checkboxes at the top
- Verify all Epic and Issue checkboxes are complete (✅)
- Count incomplete items

**Questions to Answer:**
- Is current release complete?
- Do any issues need to be closed manually?
- Should we run `/complete-release [version]` to tag and version?

**Output:** Proceed if current release is complete OR user decides to abandon/move incomplete work to next release

---

#### Task 2-3: Review Changes & Analyze Repo 🤖 (Consolidated)

**AI Action (Single Request):**
```bash
# Run both analyses in parallel:
1. git log --oneline --since="30 days ago"
2. /analyze-repo (or read memory-bank/techContext.md if recent)
```

**Concise Output Format:**
```
📊 Last 30 Days:
- [N] commits
- Major features: [list]
- Bug fixes: [count]
- Undocumented work: [list]

📋 Repo State:
- Tech stack: [key items]
- Recent changes: [list]
- Action items: [list if any]
```

**Cost Optimization:** Consolidated into single AI conversation, concise bullet format
**Output:** Combined analysis of recent changes and current repo state

---

### Phase 2: Vision Alignment 📋

**📁 Context Setup:** Close previous files. Only open `memory-bank/releases/future-releases.md` for review.

#### Task 4: Review Proposed Work 👤

**Human Action Required:**
- Review `memory-bank/releases/future-releases.md` to see what work is planned next
- Read related BRDs, PRDs, or Specs in `context/` that define the work:
  - `memory-bank/requirements/brds/` - Business requirements and strategy
  - `memory-bank/requirements/prds/` - Product requirements for features
  - `memory-bank/requirements/specs/` - Technical specifications
- Understand scope, goals, and business impact
- Determine which release phase this belongs in

**Questions to Answer:**
- Does this work represent a new release phase (e.g., v1.5.0, v2.0.0)?
- Is this part of existing roadmap or new addition?
- What's the business priority and timeline?
- Do we have all necessary PRDs/specs to implement this?

**Output:** Clear decision on release version and phase name for this work

**💡 Cost Tip:** Close specs/BRDs after reading. Don't keep them open for subsequent tasks.

---

#### Task 5: Update Vision PRD - Phases Section 👤

**Human Action Required:**
- Open `memory-bank/activeContext.md`
- Navigate to "## Phases & Use Cases" section
- Add new phase section if this is a new release (e.g., v1.5.0)
- Follow existing phase format:
  - **Goal:** One-sentence objective
  - **Focus Metrics:** 3-5 measurable outcomes
  - **Key Use Cases:** Numbered list
  - **Scope:** Epic breakdown
  - **Value:** Business impact statement

**Template for New Phase:**
```markdown
### **vX.Y.Z: [Phase Name] - [Short Description]** 🎯 NEXT

**Goal:** [One sentence goal]

**Focus Metrics:**
- [Metric 1]: [Target]
- [Metric 2]: [Target]
- [Metric 3]: [Target]

**Key Use Cases:**
1. **[Use Case 1]** - [Description]
2. **[Use Case 2]** - [Description]

**Scope:**
- Epic 1: [Name]
- Epic 2: [Name]

**Value:** [Business impact]
```

**Output:** Vision PRD updated with new phase OR confirmation existing phase is correct

---

#### Task 6: Check Vision PRD Top Sections Alignment 👤

**Human Action Required:**
- Review top sections of `memory-bank/activeContext.md`:
  - Vision Statement
  - Business Outcomes
  - System Overview
  - Capability Ladder
- Determine if the new epic/phase fundamentally changes these sections
- Update if necessary (major architectural changes, new capabilities, significant business impact shifts)

**Questions to Ask:**
- Does this work add a new capability level?
- Does it change core business outcomes?
- Does it alter the system's fundamental purpose?
- Does it change the vision statement?

**Output:** Top sections updated OR confirmed as unchanged

---

#### Task 7: AI Reviews Vision PRD Consistency 🤖

**AI Action:**
- Read `memory-bank/activeContext.md`
- Check for internal consistency:
  - Does Capability Ladder match Phases?
  - Do Business Outcomes align with phase goals?
  - Are focus metrics consistent across phases?
  - Do phase numbers follow logical progression?

**Concise Output Format:**
```
✅ Vision consistency check:

Issues found:
- [Issue 1 with location]
- [Issue 2 with location]

OR

✅ All sections aligned. No issues.
```

**Cost Optimization:** Report issues only. Skip explanations of what's correct.
**Output:** Consistency report (issues only)

---

### Phase 3: Release Documentation 📝

**📁 Context Setup:** Close vision.md. Only keep `memory-bank/releases/current-release.md` open.

#### Task 8: Run Advance Release 👤

**Human Action Required:**
```bash
/advance-release
```

**What This Does:**
- Moves `memory-bank/releases/current-release.md` to `past-releases.md`
- Copies `memory-bank/releases/future-releases.md` (or minor-release) to new `current-release.md`
- Prompts for release name
- May close completed GitHub issues

**Expected Outcome:** New `current-release.md` created as blank template for next release

---

#### Task 9: Enrich Current Release 🤖

**AI Action:**
```bash
/enrich-release
```

**What This Does:**
- Reads spec files linked in each epic
- Analyzes codebase using `analyze-repo` output
- Researches each issue's requirements
- Generates comprehensive details for implementation
- Fills all `<!-- TODO: enrich -->` placeholders

**Cost Optimization:** 
- AI will @ mention spec files as needed (don't open all specs preemptively)
- Uses cached analyze-repo output if recent
- Concise enrichment text (clear but not verbose)

**Output:** `current-release.md` fully enriched with detailed issue specifications

---

#### Task 10: Review Epics Breakdown 🤖

**AI Action:**
- Read epic documents referenced in current-release.md (@ mention as needed)
- Verify structure: Overview, Goals, Child issues, Dependencies, Success metrics
- Check completeness

**Concise Output Format:**
```
📋 Epic Review:

Issues found:
- Epic [name]: Missing acceptance criteria for issue [X]
- Epic [name]: No success metrics defined

OR

✅ All epics properly structured.
```

**Cost Optimization:** Report issues only, skip confirming correct structure
**Output:** Epic quality report (issues only)

---

#### Task 11: Human Reviews and Adjusts Epics 👤

**Human Action Required:**
- Review AI's epic analysis (if issues found)
- Adjust epic documents as needed
- Ensure proper scoping and dependencies
- Confirm classification scores reasonable

**Output:** Epics finalized and ready for scope-release

---

#### Task 12: Validate Release Structure 🤖

**Script-First Approach:**
```bash
npm run validate-release
```

**AI Action:** Only if validation fails
- Review error output
- Identify issues
- Suggest fixes

**Concise Output Format:**
```
✅ Validation passed

OR

❌ Validation failed:
- [Error 1 with location]
- [Error 2 with location]

Suggested fixes: [concise list]
```

**Cost Optimization:** Skip AI entirely if validation passes. Use script output.
**Output:** Validation report - must pass before scope-release

---

#### Task 13: Run Scope Release 👤

**Human Action Required:**
```bash
/scope-release --current
```

**What This Does:**
- Parses `memory-bank/releases/current-release.md`
- Creates GitHub issues for all epics and child issues
- Applies classification-based assignment (if configured)
- Links issues with dependencies
- Adds appropriate labels/types

**Expected Outcome:** All release work items created as GitHub issues

---

### Phase 4: Implementation 🚀

#### Task 14: Run Autopilot for Each Epic 👤

**Human Action Required:**

Get epic numbers from `/scope-release` output, then run for each:

```bash
/autopilot 675
```

Wait for completion, then:
```bash
/autopilot 676
```

Repeat for all epics in release.

**Alternative (More Control):**
```bash
/analyze-epic 675
# Review analysis, then:
/implement-epic 675
```

**What Autopilot Does:**
- **Automatically references** @.cursorrules.md and @ai-context.yml before implementation
- Combines analyze + implement in single conversation
- Maintains full context throughout
- Uses minimize-cost patterns (concise output, auto-proceed)
- Creates PR automatically

**Cost Optimization:**
- All epic commands (analyze-epic, implement-epic, autopilot) have minimize-cost patterns built-in
- They automatically review @.cursorrules.md and @ai-context.yml during context review
- Close unrelated files before running to reduce token usage

**Expected Outcome:** Each epic implemented, PRs created

---

### Phase 5: Post-Implementation Validation ✅

#### Task 15: Verify GitHub Issues Created 🤖

**Script-First Approach:**
```bash
npm run sync-release-status  # Uses cached GitHub data
```

**AI Action:** Only if sync shows anomalies
- Compare expected vs actual issue count
- Check missing issues or duplicates

**Concise Output Format:**
```
✅ Issue verification:
- Expected: 28 issues
- Created: 28 issues
- All epics linked ✓

OR

⚠️  Issues found:
- Missing: [list]
- Duplicates: [list]
```

**Cost Optimization:** Use sync-release-status script (cached data, ~5 API calls vs 30)
**Output:** Issue creation verification report

---

#### Task 16: Final Human Review 👤

**Human Action Required:**
- Review created GitHub issues in browser
- Verify titles, descriptions, acceptance criteria correct
- Check dependencies and blocking relationships
- Confirm assignments make sense
- Make any manual adjustments needed

**Output:** Confirmation that release is ready to implement

---

#### Task 17: Create Release Tracking Issue 🤖

**AI Action - Using Unified Module:**
```typescript
import { createReleaseIssue } from './core/github-issue-creator.js';

// Create a master Release issue that tracks all epics
const releaseIssueResult = await createReleaseIssue(
  `Release: v[X.Y.Z] - [Release Name]`,
  `[Release checklist with all epic links]`,
  {
    owner: 'org',
    repo: 'repo'
  }
);

console.log(`✅ Created Release tracking issue #${releaseIssueResult.number}`);
```

**What the Unified Module Handles:**
- ✅ Template population for release tracking
- ✅ Automatic label assignment ("release")
- ✅ GitHub API with CLI fallback
- ✅ Issue number extraction
- ✅ Security and shell escaping

**Output:** Master release tracking issue created with proper linking

---

## Summary Workflow

```
📁 Context Management: Close unrelated files at each phase
⚡ Cost Optimizations: Tasks 2-3 consolidated, scripts preferred over AI

1. 👤 Check current release complete
2-3. 🤖 Review code changes + Analyze repo (consolidated)
4. 👤 Review proposed epic/work
5. 👤 Update vision phases
6. 👤 Check vision top sections
7. 🤖 Review vision consistency (issues only)
8. 👤 Run /advance-release
9. 🤖 Run /enrich-release (@ mention files as needed)
10. 🤖 Review epics breakdown (issues only)
11. 👤 Review and adjust epics (if issues found)
12. 🤖 Validate release (script-first, AI only if fails)
13. 👤 Run /scope-release
14. 👤 Run /autopilot for each epic
15. 🤖 Verify issues (script-first: sync-release-status)
16. 👤 Final review
17. 🤖 Create release tracking issue (optional)
```

**Typical Cost Savings:** 65-70% fewer tokens vs verbose mode

## When to Use This Command

Use `/guide-release` when:
- Starting a new release cycle
- Transitioning from one release to another
- Need to ensure documentation alignment
- Want guided process with human decision points
- Working on first few releases and learning workflow

Skip `/guide-release` when:
- You're experienced with the workflow
- Documentation already aligned
- Small hotfix or patch release
- Following documented runbook for specific release type

## Example Session (Optimized)

```
User: /guide-release

AI: 📋 Release Guide (Cost-Optimized)

TODO (17 tasks, 2-3 consolidated):
- [ ] 👤 Task 1: Check current release
- [ ] 🤖 Task 2-3: Code changes + repo analysis (consolidated)
- [ ] 👤 Task 4-6: Vision alignment  
- [ ] 🤖 Task 7: Vision consistency check
- [ ] 👤 Task 8: /advance-release
- [ ] 🤖 Task 9: /enrich-release
- [ ] 🤖 Task 10: Epic review
- [ ] 👤 Task 11: Adjust epics (if needed)
- [ ] 🤖 Task 12: Validate (script-first)
- [ ] 👤 Task 13: /scope-release
- [ ] 👤 Task 14: /autopilot epics
- [ ] 🤖 Task 15: Verify issues (script-first)
- [ ] 👤 Task 16: Final review
- [ ] 🤖 Task 17: Tracking issue (optional)

📁 Close unrelated files. Keep only current-release.md open.

Task 1 status?

---

User: Current release complete.

AI: ✅ Task 1 complete

Task 2-3: [runs git log + reads tech-stack.md]

📊 Last 30 Days:
- 52 commits
- Major: Auth v2, Dashboard refactor, API optimization
- Undocumented: Real-time notifications

📋 Repo State:
- Node 18, TypeScript 5, Prisma
- No config changes

Task 4: Review future-releases.md

---

User: Planning v1.4 - API Enhancement

AI: Task 5-6: Update vision phases?

User: [updates vision.md]

AI: Task 7: [reads vision.md]

✅ Vision consistency check:

Issues found:
- Phase 3 lists v1.3, should be v1.4
- Capability Ladder missing "Real-time Events"

Fix?
```

## Notes

**Task Types:**
- Human tasks (👤) require decisions, judgment, or approval
- AI tasks (🤖) are analysis, validation, or automation
- Some tasks consolidated for efficiency (e.g., Tasks 2-3)

**Cost Optimizations Built-In:**
- AI uses concise, structured output format
- Scripts preferred over AI analysis when possible
- Context management: Close unrelated files at each phase
- "Report issues only" - skip confirming what's correct
- Consolidated tasks reduce conversational overhead

**Process:**
- Human should approve AI actions before proceeding to next phase
- Entire process typically takes 2-4 hours for medium-sized release
- Can pause/resume at any task boundary
- Save TODO list state to track progress across sessions

**Expected Cost Savings:**
- 65-70% fewer tokens compared to verbose mode
- 40-50% fewer GitHub API calls (script-first + caching)
- Similar quality, significantly lower resource usage