---
roadcrew_template_name: "projectbrief.template.md"
roadcrew_template_type: "memory-bank"
roadcrew_template_version: "1.0"
roadcrew_last_updated: "2025-11-03"
roadcrew_min_version: "1.6.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"
cline_memory_bank: "projectbrief"
---

# Project Brief

**Foundation document that defines core requirements and goals as the source of truth for project scope**

Last Updated: November 3, 2025  
Current Phase: Post-Launch Optimization (v1.6.0)  
Status: Distribution Published, In Optimization Phase

---

## Overview

**Roadcrew** is a spec-driven development system that helps technical PMs and AI assistants build SaaS products systematically and predictably.

### What It Is

A unified framework combining:
- **8-stage workflow** that maps product vision → working software
- **40+ composable commands** for automated spec generation and planning
- **Template system** ensuring consistency across all documentation
- **Dual publishing** for flexible customer distribution
- **AI-first architecture** designed for human-AI collaboration

### What It Does

Roadcrew transforms chaotic iteration into intentional shipping by:
1. Enforcing spec-driven development (specs before code)
2. Automating routine documentation and planning
3. Organizing AI context for optimal assistance
4. Publishing updates customers can control
5. Reducing time from vision to shipped code

---

## Core Requirements

### Functional Requirements

- ✅ 8-stage workflow (ANALYSIS → PLANNING → RELEASE → IMPLEMENTATION → CODE ANALYSIS → TESTING → PUBLISHING → VALIDATION)
- ✅ 40+ composable commands (each command is atomic and testable)
- ✅ 8 template types (BRD, PRD, Spec, Release, Epic, Enhancement, etc.)
- ✅ Git submodule distribution (`.roadcrew/` in customer projects)
- ✅ Dual publishing (file sync + GitHub API)
- ✅ {{VARIABLES}} in all templates (customer-safe, no hardcoding)
- ✅ Memory Bank documentation (6 files, living docs)
- ✅ Cursor rules for AI guidance (6 rules, auto-applied)

### Non-Functional Requirements

- **Spec-driven:** All features must start with written spec
- **AI-compatible:** Context organized for AI consumption
- **Customer-controlled:** Version pinning, update timing
- **Testable:** Commands have unit tests, workflows repeatable
- **Documented:** Every decision has explicit rationale

---

## Goals

### Business Goals

- Enable technical PMs to ship SaaS 10× faster without engineering bottlenecks
- Establish Roadcrew as standard orchestration layer for spec-driven development
- Create sustainable business through tiered pricing (FREE/STARTER/ENTERPRISE)

### Technical Goals

- Maintain 100% type safety (TypeScript strict mode)
- Achieve 80%+ test coverage across all modules
- Keep build time <30s (target: <10s in v1.7.0)
- Optimize AI context loading <5s (target: <2s in v1.7.0)

### Product Goals

- Every customer can generate specs and epics without manual formatting
- AI can execute 60-80% of routine development work
- Teams reduce "documentation churn" by 70% through templates
- Customers feel confident delegating to AI with Roadcrew structure

---

## Scope

### In Scope

Features and deliverables that are core to Roadcrew:

- **8-stage workflow:** Clear, measurable development pipeline
- **Command system:** 40+ commands for automation and guidance
- **Template system:** Consistent documentation across all docs
- **Publishing:** Dual-approach distribution to customers
- **Memory Bank:** 6 files of living documentation
- **Cursor integration:** Rules + commands for AI guidance
- **GitHub integration:** Issue creation, PR management, release tracking
- **Version control:** Git submodule for customer installations

**Boundaries Defined:**
- Internal development: `roadcrew-internal` repository
- Customer-facing: `roadcrew` public repository + git submodule
- v1.6.0 shipped with 640 files, 4.46MB distribution
- Supports Node.js 18+ with TypeScript 5.9.3

### Out of Scope

What Roadcrew will NOT do:

- ❌ Provide hosting (customers host their own projects)
- ❌ Manage databases (customers own their data layer)
- ❌ Generate deployment scripts (framework-agnostic)
- ❌ Provide SaaS UI (command-line + Cursor chat only)
- ❌ Handle authentication (GitHub OAuth only)
- ❌ Multi-repo orchestration (future v2.0.0 feature)

---

## Success Criteria

### Measurable Outcomes

- ✅ **Distribution published:** 640 files to customers (completed Nov 2)
- ✅ **Customer adoption:** Enable teams to use `/onboard` command
- ✅ **Build performance:** 85% faster (180-200s → 0-30s) via PR #1108 fixes
- ✅ **AI context:** 75% faster parsing (20s → 5s) via template optimization
- ✅ **Test coverage:** 78% achieved, target 80%+
- ⏳ **v1.7.0 release:** Target end-of-year (Dec 31, 2025)

### Validation Approach

- **Customer feedback:** Gather from first 50 installations
- **Performance metrics:** Build time, AI parse time, command execution
- **Quality metrics:** Test coverage, type safety, lint errors
- **Adoption metrics:** Commands run, specs generated, releases shipped

---

## Key Philosophy

Roadcrew is built on five core principles:

1. **Specs First.** AI needs clarity. Written specs prevent ambiguity and rework.

2. **Commands Over Chaos.** Structure over flexibility. Enforced workflow prevents iteration mistakes.

3. **Templates Over Customization.** Consistency over flexibility. Standard templates reduce cognitive load.

4. **AI as Partner.** Not a magic button. AI is a team member who needs clear guidance and constraints.

5. **Publish Once, Customers Fetch.** Not pushing to every customer. Git submodule gives customers control.

---

## Core Capabilities

### 1. Spec-Driven Workflow (8 Stages)

```
ANALYSIS → PLANNING → RELEASE → IMPLEMENTATION
    ↓         ↓          ↓           ↓
  Specs    Decisions   Versioning   Code

CODE ANALYSIS → TESTING → PUBLISHING → VALIDATION
     ↓            ↓          ↓            ↓
  Quality      Coverage   Distribution   Live
```

Each stage has explicit inputs, outputs, and success criteria.

### 2. Composable Commands (40+ Commands)

- Commands are atomic (each solves one problem)
- Commands don't assume previous commands ran
- Commands can be chained or used independently
- Each command updates specific project state files

### 3. Template System

All templates use `{{VARIABLES}}` for customer customization:
- Planning: BRD, PRD, Spec
- Execution: Release, Epic, Enhancement
- Memory Bank: 6 documentation files
- Cursor Rules: 6 rules for AI guidance

### 4. Dual Publishing

**File Sync (--push):**
- Production releases (proven, reliable)
- Direct copy from `dist/` to `roadcrew` repo

**GitHub API (5-phase):**
- CI/CD automation
- Programmatic workflow with rate limit handling

### 5. AI-First Architecture

- Context organized for AI consumption
- Every decision has explicit reasoning
- Commands generate outputs AI understands
- Memory Bank provides living documentation

---

## Related Documents

- **Product Context:** See `memory-bank/productContext.md` for problems and UX goals
- **System Patterns:** See `memory-bank/systemPatterns.md` for architecture and design patterns
- **Tech Context:** See `memory-bank/techContext.md` for technology stack
- **Active Context:** See `memory-bank/activeContext.md` for current work
- **Progress:** See `memory-bank/progress.md` for status and milestones

---

**Note:** This is the foundation document. All other memory bank files build upon the scope and requirements defined here.