# Command Use Case Patterns v1.6.x

**Goal:** Organize commands by use case patterns (workflows) rather than just tiers. Identify gaps and opportunities for new commands.

---

> **📌 IMPORTANT:** Pattern sections (1-8) describe workflow stages and philosophy. For authoritative tier and role assignments for each command, see **📊 COMMAND SUMMARY BY TIER** table at the end of this document. That table is the single source of truth.

## Executive Summary

Commands naturally cluster into **7 use case patterns** representing distinct workflows in a linear progression from codebase to production:

| Pattern | Purpose | Inputs | Outputs |
|---------|---------|--------|---------|
| **ANALYSIS** | Discover current state and produce requirements documents | Codebase, narratives/, past-releases.md, feedback | BRD, PRD, Spec |
| **PLANNING** | Convert findings into detailed release roadmap | ANALYSIS output, vision.md | current-release.md, future-releases.md |
| **RELEASE** | Transform roadmap into proper GitHub issues | Roadmap, phases, epics | GitHub epics + issues, classified, assigned |
| **IMPLEMENT** | Generate production-ready code with passing tests | GitHub epics + issues, PRDs, Specs | Working software + unit tests + passing CI |
| **CODE-ANALYSIS** | Ensure code meets quality standards and optimize | Generated code | Review feedback + optimization suggestions |
| **TESTING** | Maintain code coverage, automate testing | Working software + test feedback | Full test suite + automated tests |
| **PUBLISH** | Package and distribute to customers | Validated code, built artifacts | Customer-ready distribution, synced to public repo |

### Meta-Pattern: GUIDED WORKFLOWS (Vision)

Beyond the 7 base patterns, **Guided Workflows** are meta-orchestrators that span multiple stages sequentially, automating coordination and ensuring smooth handoffs:

| Workflow | Tier | Spans | Purpose |
|----------|------|-------|---------|
| **guide-release** | ENTERPRISE | RELEASE → IMPLEMENT → TESTING | Sequentially guide multi-epic releases through implementation and testing |
| **guide-planning** | STARTER | ANALYSIS → PLANNING | Guide roadmap creation from analysis findings (planned) |
| **guide-distribution** | STARTER | PUBLISH → Multi-Platform | Publish to multiple platforms sequentially (planned) |

**Vision:** As automation increases, guided workflows reduce manual coordination by intelligently orchestrating stages, validating handoffs, and handling inter-stage dependencies.

---

## Pattern 1: ANALYSIS

**Purpose:** Understand the *current state* of the codebase plus research-based narratives and past releases as context for the roadmap.

**Inputs:** Codebase, narratives/, milestones/past-releases.md

**Outputs:** BRDs, PRDs, Specs documents

**Parent Command:** `analyze-repo` (FREE)

**Workflow:**
```
Analyze Current Codebase State
  ↓
Review Past Releases & Context
  ↓
Gather Research-Based Narratives
  ↓
Document Findings
  ↓
Generate BRD/PRD/Spec Documents
```


### Status: ✅ FOUNDATIONAL
Current state analysis, cost analysis, and documentation generation covered. Becomes input to Planning and Release.

**See 📊 COMMAND SUMMARY BY TIER table for tier and role assignments.**

---

## Pattern 2: PLANNING

**Purpose:** Understand ANALYSIS findings + vision, generate next phase specs and create structured release documentation.

**Inputs:** ANALYSIS output (BRD/PRD/Spec), vision.md, completed current release

**Outputs:** Epic specifications with detailed structures, structured BRD/PRD/Spec documentation for next phase

**Parent Command:** `complete-release` (FREE) → `advance-release` (FREE)

**Workflow:**
```
Mark Current Release Complete
  ↓
Sync Release Status to Docs
  ↓
Archive Release & Pull Next Phase
  ↓
Run Codebase Analysis (analyze-repo)
  ↓
Generate Epic Specifications
  ↓
Create Release Documentation (BRD → PRD → Spec)
```


### Status: ✅ COMPLETE
Release completion, status tracking, version transition, and documentation generation covered. Feeds into RELEASE pattern.

**See 📊 COMMAND SUMMARY BY TIER table for tier and role assignments.**

---

## Pattern 3: RELEASE

**Purpose:** Translate roadmap into properly formatted GitHub issues. Focus on scope, dependencies, complexity classification, and resource assignment.

**Inputs:** current-release.md, detailed roadmap from PLANNING

**Outputs:** GitHub epics with child issues, classified and assigned

**Parent Command:** `scope-release` (STARTER)

**Workflow:**
```
Parse Roadmap & Epics
  ↓
Classify Scope & Dependencies
  ↓
Analyze Complexity of Each Issue
  ↓
Assign Resources (classifying each issue 1-10)
  ↓
Create Formatted GitHub Issues
```


### Status: ✅ COMPLETE
Full release planning and GitHub coordination covered.

**See 📊 COMMAND SUMMARY BY TIER table for tier and role assignments.**

---

## Pattern 4: IMPLEMENT

**Purpose:** Generate code that meets all epic and issue details for the current release. Write unit tests and pass CI tests.

**Inputs:** GitHub epics and issues (from RELEASE), requirements, acceptance criteria

**Outputs:** Production-ready code with passing CI tests

**Parent Command:** `autopilot` (STARTER)

**Workflow:**
```
Parse GitHub Issues & Requirements
  ↓
Generate Code Modules & Functions
  ↓
Write Unit Tests
  ↓
Run CI Tests
  ↓
Code Ready for Review
```


### Gaps & Opportunities

| Gap | Suggested Command | Tier | Purpose |
|-----|-------------------|------|---------|
| **No scaffolding** | `/scaffold-project` | STARTER | Generate project structure (directories, configs) |
| **No code generation** | `/generate-module` | STARTER | AI-generate code modules/functions from specs |

### Status: ⚠️ NEEDS EXPANSION
Have orchestrators, missing granular builders.

**See 📊 COMMAND SUMMARY BY TIER table for tier and role assignments.**

---

## Pattern 5: CODE-ANALYSIS

**Purpose:** Check that code quality meets architectural and coding standards. Identify opportunities to improve performance, efficiency, costs, or security.

**Inputs:** Generated code from IMPLEMENT

**Outputs:** Code review feedback, optimization suggestions, security/cost/performance improvements

**Parent Command:** `review-code` (FREE)

**Workflow:**
```
Review Code Structure & Patterns
  ↓
Check Style & Architectural Standards
  ↓
Identify Anti-Patterns & Issues
  ↓
Analyze Performance, Cost, Security
  ↓
Generate Improvement Plan
```


### Status: ✅ GOOD COVERAGE
Code review and command optimization covered.

**See 📊 COMMAND SUMMARY BY TIER table for tier and role assignments.**

---

## Gaps & Opportunities

| Gap | Suggested Command | Tier | Purpose |
|-----|-------------------|------|---------|
| **No security analysis** | `/audit-security` | STARTER | Identify security vulnerabilities, auth issues, data safety |
| **No performance profiling** | `/audit-performance` | STARTER | Analyze slow functions, memory leaks, optimization opportunities |
| **No complexity analysis** | `/audit-complexity` | STARTER | Measure cyclomatic complexity, function size, nesting depth |

---

## Pattern 6: TESTING

**Purpose:** Improve code coverage and testing automation. Make manual testing easier and less time-consuming for humans.

**Parent Command:** `start-testing` (STARTER)

**Workflow:**
```
Analyze Code Coverage Gaps
  ↓
Generate Missing Test Cases
  ↓
Optimize Test Suite for Speed
  ↓
Automate Manual Test Scenarios
  ↓
Tests Ready for CI/CD
```


### Gaps & Opportunities

| Gap | Suggested Command | Tier | Purpose |
|-----|-------------------|------|---------|
| **No coverage analysis** | `/analyze-test-coverage` | STARTER | Identify untested code paths, dead code |
| **No test generation** | `/generate-test-cases` | STARTER | AI-generate missing test cases from code |

### Status: ⚠️ MINIMAL
Only initialization and validation covered. Missing coverage analysis, generation, optimization, automation.

**See 📊 COMMAND SUMMARY BY TIER table for tier and role assignments.**

---

## Pattern 7: PUBLISH

**Purpose:** Package and distribute production-ready code to customers. Build distribution artifacts and sync to public repositories.

**Inputs:** Validated code from TESTING, built dist/ artifacts

**Outputs:** Customer-ready distribution on dist branch, synced to public roadcrew repo

**Parent Command:** `build-distribution` (FREE)

**Workflow:**
```
Build Distribution Artifacts
  ↓
Prepare Dist Branch
  ↓
Sync to Public Repository
  ↓
Update Customer Installation
```


### Gaps & Opportunities

| Gap | Suggested Command | Tier | Purpose |
|-----|-------------------|------|---------|
| **No publication sync** | `publish-distribution` | STARTER | Sync dist branch to public roadcrew repo |
| **No customer guidance** | `update-roadcrew-customer` | STARTER | Help customers update their roadcrew installation |

### Status: ⏳ IN PROGRESS
Basic distribution building covered. Missing publication sync and customer update guidance.

**See 📊 COMMAND SUMMARY BY TIER table for tier and role assignments.**

---

## Pattern 8: VALIDATION (Cross-Cutting)

**Purpose:** Ensure smooth handoffs and quality gates at all major stage transitions. Validation is horizontal across all patterns—not a separate stage, but a gate that unlocks progression.

**Philosophy:** Higher automation = more validation required. Validation ensures humans can trust automated decisions at critical handoffs.

**Validation Checkpoint Map:**

| Transition | Gate | Validates | Current Commands |
|-----------|------|-----------|------------------|
| ANALYSIS → PLANNING | Release specs approved | BRD/PRD/Spec quality, completeness | validate-release-docs |
| PLANNING → RELEASE | Roadmap structured | Roadmap structure, dependencies, effort estimates | validate-release |
| RELEASE → IMPLEMENT | Issues well-formed | Epic/issue structure, acceptance criteria, classification | validate-release |
| IMPLEMENT → CODE-ANALYSIS | Code compiled | TypeScript compilation, dependencies installed | build-project |
| CODE-ANALYSIS → TESTING | Quality gates met | Performance, security, complexity scores | (planned) |
| TESTING → PUBLISH | Coverage requirements | Test coverage %, automated test suite completeness | (planned) |


### Status: ✅ FOUNDATIONAL
Core handoff validation at PLANNING→RELEASE and RELEASE→IMPLEMENT covered. Candidate for expansion at CODE-ANALYSIS→TESTING and TESTING→PUBLISH transitions with coverage and performance validation.

**See 📊 COMMAND SUMMARY BY TIER table for tier and role assignments.**

---

## Workflow Integration

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                         VALIDATION LAYER (Cross-Cutting)                    │
│  Ensures smooth handoffs at all stage transitions with quality gates        │
└─────────────────────────────────────────────────────────────────────────────┘
       ↓validate specs       ↓validate roadmap    ↓validate issues
       
ANALYSIS (Current State)
  ↓ Outputs: BRD, PRD, Spec
  ↓
PLANNING (Roadmap)
  ↓ Outputs: current-release.md, future-releases.md
  ↓
RELEASE (Issues)
  ↓ Outputs: GitHub epics + classified issues
  ↓
       ┌────────────────────────────────────────────────────────────────┐
       │ GUIDED WORKFLOW: guide-release (ENTERPRISE)                   │
       │ Spans: RELEASE → IMPLEMENT → TESTING (sequential)             │
       │ Automates coordination & validation across 3 stages           │
       └────────────────────────────────────────────────────────────────┘
       ↓
IMPLEMENT (Code)
  ↓ Outputs: Production-ready code + passing tests
  ↓
CODE-ANALYSIS (Quality)
  ↓ Outputs: Review feedback + optimization suggestions
  ↓
TESTING (Coverage)
  ↓ Outputs: Full test suite, automated tests
  ↓
PUBLISH (Distribution)
  ↓ Outputs: Customer-ready distribution, synced to public repo
  ↓
       ┌────────────────────────────────────────────────────────────────┐
       │ GUIDED WORKFLOW: guide-distribution (planned)                 │
       │ Spans: PUBLISH → Multi-Platform Distribution (sequential)     │
       │ Publish to multiple platforms to reach more users             │
       └────────────────────────────────────────────────────────────────┘
```

**Other Guided Workflows (Future):**
- **guide-planning** (STARTER): ANALYSIS → PLANNING - Guide roadmap creation from findings

---

## 📊 COMMAND SUMMARY BY TIER

| Command | FREE | STARTER | ENTERPRISE | Role |
|---------|------|---------|------------|------|
| **ANALYSIS** | | | | |
| analyze-repo | ✓ | ✓ | ✓ | Orchestrator |
| create-spec | ✓ | ✓ | ✓ | Atomic |
| create-prd | ✓ | ✓ | ✓ | Atomic |
| create-brd | ✓ | ✓ | ✓ | Atomic |
| minimize-cost | ✓ | ✓ | ✓ | Atomic |
| analyze-multiplatform | | ✓ | ✓ | Orchestrator |
| ⚠️ guide-planning | | ✓ | ✓ | Guided Workflow (Planned) |
| collect-feedback (setup + process + validate) | | | ✓ | Atomic |
| classify-feedback | | | ✓ | Atomic |
| **PLANNING** | | | | |
| update-roadmap | ✓ | ✓ | ✓ | Atomic |
| complete-release | | ✓ | ✓ | Parent |
| advance-release | | ✓ | ✓ | Parent |
| sync-release-status | | ✓ | ✓ | Atomic |
| create-release-docs | | ✓ | ✓ | Atomic |
| sync-roadmap | | ✓ | ✓ | Atomic |
| **RELEASE** | | | | |
| create-release-pr | ✓ | ✓ | ✓ | Atomic |
| tag-release | ✓ | ✓ | ✓ | Atomic |
| scope-release | | ✓ | ✓ | Orchestrator |
| enrich-release | | ✓ | ✓ | Atomic |
| guide-release | | | ✓ | Guided Workflow |
| **IMPLEMENT** | | | | |
| implement-issue | ✓ | ✓ | ✓ | Atomic |
| implement-epic | | ✓ | ✓ | Orchestrator |
| analyze-epic | | ✓ | ✓ | Atomic |
| plan-implementation | | ✓ | ✓ | Atomic |
| write-tests | | ✓ | ✓ | Atomic |
| create-epic | | ✓ | ✓ | Atomic |
| usage-report | | ✓ | ✓ | Atomic |
| minimize-manual-steps | | ✓ | ✓ | Atomic |
| autopilot | | | ✓ | Orchestrator |
| **TESTING** | | | | |
| update-roadcrew | ✓ | ✓ | ✓ | Atomic |
| uninstall-roadcrew | ✓ | ✓ | ✓ | Atomic |
| code-cleanup | ✓ | ✓ | ✓ | Atomic |
| triage-pr | ✓ | ✓ | ✓ | Atomic |
| create-release-pr | ✓ | ✓ | ✓ | Atomic |
| start-testing | | ✓ | ✓ | Orchestrator |
| validate-github-templates | | ✓ | ✓ | Atomic |
| **CODE-ANALYSIS** | | | | |
| audit-security | ✓ | ✓ | ✓ | Atomic (Planned) |
| audit-performance | ✓ | ✓ | ✓ | Atomic (Planned) |
| review-code | | ✓ | ✓ | Orchestrator |
| minimize-tokens | | ✓ | ✓ | Atomic |
| optimize-command | | ✓ | ✓ | Atomic |
| **PUBLISH** | | | | |
| build-project | ✓ | ✓ | ✓ | Atomic |
| build-distribution | | ✓ | ✓ | Orchestrator |
| publish-distribution | | ✓ | ✓ | Atomic |
| update-roadcrew-customer | | ✓ | ✓ | Atomic |
| verify-install | | ✓ | ✓ | Atomic |
| ⚠️ guide-distribution | | ✓ | ✓ | Guided Workflow (Planned) |
| **VALIDATION (Cross-Cutting)** | | | | |
| build-project | ✓ | ✓ | ✓ | Atomic (Build Gate) |
| validate-release | | ✓ | ✓ | Orchestrator (Gate) |
| validate-release-docs | | ✓ | ✓ | Orchestrator (Gate) |

**Tier Summary (Hierarchical - Cumulative):**
- **FREE:** 24 commands (also available in STARTER and ENTERPRISE)
- **STARTER:** 19 commands (also available in ENTERPRISE)
- **ENTERPRISE:** 3 commands (premium only)
- **Total unique commands:** 46 commands