---
roadcrew_template_name: "productContext.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: "productContext"
---

# Product Context

**Why this project exists, problems it solves, how it should work, and user experience goals**

Last Updated: November 3, 2025  
Primary Users: Technical PMs, AI Assistants, SaaS Teams

---

## Why This Exists

### Problem Statement

SaaS teams are trapped in a slow loop:
- Technical PMs spend time explaining requirements over and over
- AI assistants lack consistent guidance on what to build
- Teams iterate chaotically without clear specs or structure
- Shipping is unpredictable because specs and code drift apart
- Documentation is created once, updated never, always stale

### Motivation

The market has three broken states:

1. **Pure Manual:** Engineers and PMs hand-code everything
   - Slow (3-6 months per release)
   - Expensive (engineers doing documentation work)
   - Error-prone (miscommunication between roles)

2. **Pure AI:** Just giving AI a chat interface
   - Produces hallucinations (no specs to reference)
   - No structure (AI invents its own decisions)
   - Unpredictable quality (depends on prompt luck)

3. **Hybrid (Current):** AI + manual specs
   - Still slow (specs require manual writing)
   - AI doesn't follow structure (ignores templates)
   - No enforcement (skips steps when pressured)

### Vision

**Roadcrew enables founders and product teams to ship 10× faster** by creating a system where:
- Specs are automatically generated from vision
- AI has clear structure and constraints
- Every decision has explicit reasoning
- Teams move from chaotic iteration to intentional shipping

---

## Problems It Solves

### Problem 1: Specification Drift

**Current Pain Point:**
Specs are written once, then ignored. Code diverges from spec, spec becomes outdated, nobody trusts specs.

**How This Solves It:**
- `/create-spec` generates spec skeleton from epic
- Spec is the contract between requirements and implementation
- AI references spec in every implementation decision
- Changes trigger spec updates (not the reverse)

**Expected Impact:**
- Specs stay current (updated with every change)
- Implementation fidelity improves (80%+ compliance with spec)
- Team coordination improves (single source of truth)

---

### Problem 2: AI Lacks Guidance

**Current Pain Point:**
AI assistants hallucinate features, invent architecture decisions, produce unpredictable quality.

**How This Solves It:**
- AI gets explicit specs with acceptance criteria
- Commands guide AI through 8-stage workflow
- Cursor rules constrain AI behavior
- Memory Bank documents decisions (AI learns from history)

**Expected Impact:**
- AI implementation quality improves (60%+ first-time success rate)
- Reduced rework (spec clarity prevents misunderstandings)
- Predictable delivery (AI follows documented patterns)

---

### Problem 3: Documentation Chaos

**Current Pain Point:**
READMEs outdated, architecture docs missing, no single source of truth.

**How This Solves It:**
- Templates enforce consistency (no custom formats)
- {{VARIABLES}} prevent hardcoding (customer-safe)
- Memory Bank provides living documentation
- Commands auto-update docs (tech-stack.md, ai-context.yml)

**Expected Impact:**
- Documentation 70% smaller (no redundancy)
- Documentation 100% current (updated automatically)
- Onboarding 50% faster (clear, complete docs)

---

## How It Should Work

### User Flows

#### Primary User Flow: From Vision to Shipped Code

1. **Product Manager** writes vision in `memory-bank/activeContext.md (legacy: context/vision.md)`
2. **Team** runs `/scope-release` to generate epics
3. **PM** writes 2-3 sentence feature descriptions
4. **AI** runs `/create-spec` to auto-generate skeleton
5. **Team** fills in acceptance criteria and architecture
6. **AI** runs `/create-epic` linking epic to spec
7. **Engineers** implement against spec (not vision)
8. **Tests** validate against acceptance criteria
9. **Team** ships when tests pass (no guessing)
10. **Customer** uses via git submodule update

#### Secondary User Flow: Customer Installation

1. **Customer** adds submodule: `git submodule add ... .roadcrew`
2. **Customer** runs `/onboard` command
3. **Command** asks for project name, repo, tech stack
4. **Templates** get customized with {{VARIABLES}}
5. **Customer** commits customized configs
6. **Customer** starts using commands (`/create-spec`, etc.)
7. **Customer** updates: `git submodule update --remote .roadcrew`

---

### Key Interactions

#### Interaction 1: Command Guidance

**When it happens:** User types `/create-spec` in Cursor

**How it works:**
- Command loads context from current directory
- Command asks clarifying questions
- Command generates spec skeleton
- User customizes with domain knowledge
- Command validates all sections filled

**Expected outcome:** Complete spec ready for implementation

#### Interaction 2: Template Substitution

**When it happens:** `/onboard` runs, customer customizes config

**How it works:**
- Command identifies all {{VARIABLES}}
- Command asks for each variable value
- Command validates substitution
- Command prevents hardcoding

**Expected outcome:** Safe, complete, customized configs

#### Interaction 3: Publishing Distribution

**When it happens:** New Roadcrew version ready to release

**How it works:**
- Build: `npm run build` creates 640 files in dist/
- Publish: `publish-dist.mjs --push` copies to roadcrew repo (or GitHub API)
- Customer: `git submodule update --remote .roadcrew` gets updates
- Control: Customer decides when to update (version pinning)

**Expected outcome:** All customers on latest version (or specific version they pin)

---

## User Experience Goals

### UX Principles

- **Clarity over cleverness:** Make decisions explicit, not hidden
- **Structure over flexibility:** Enforce workflow, prevent shortcuts
- **Consistency over customization:** Standard templates, no variations
- **Automation over manual work:** Commands generate, don't require hand-writing

### Usability Requirements

- Onboard new team in <15 minutes (via `/onboard`)
- Generate first spec in <5 minutes (via `/create-spec`)
- Ship feature after spec in 2-3 days (structured workflow)
- Update Roadcrew in 1 click (git submodule update)

### Accessibility Requirements

- Command chat interface (no CLI expertise needed)
- Clear error messages (guide users toward solution)
- Documentation at every step (don't assume knowledge)
- Examples for every template (show correct format)

---

## Target Users

### User Persona 1: Technical Product Manager

**Role:** Define product vision, create specs, ship features

**Motivations:**
- Ship faster without engineering bottleneck
- Give clear guidance to AI assistants
- Reduce rework and misunderstandings

**Pain Points:**
- Explaining requirements repeatedly
- Specs ignored by engineers
- No structure (chaos iteration)

**Key Needs:**
- Automated spec generation
- Clear templates (don't start from blank)
- Version control for ideas

---

### User Persona 2: AI Assistant (Claude/GPT)

**Role:** Implement features, generate code, follow specs

**Motivations:**
- Clear requirements (prevent hallucination)
- Explicit constraints (know what not to do)
- Documented patterns (learn from history)

**Pain Points:**
- Vague specs (invent solutions)
- No structure (random architecture)
- No feedback (never improve)

**Key Needs:**
- Detailed acceptance criteria
- Examples of correct patterns
- Decision history (learn from past)

---

### User Persona 3: Engineering Team Lead

**Role:** Oversee implementation, ensure quality, release features

**Motivations:**
- Engineers focus on differentiated work
- AI handles standard patterns
- Predictable delivery

**Pain Points:**
- Template debt (custom docs everywhere)
- Knowledge silos (patterns not documented)
- Onboarding slow (no clear process)

**Key Needs:**
- Standard templates (consistency)
- Documented patterns (teachable)
- Reproducible workflow (scale team)

---

## Related Documents

- **Project Brief:** See `memory-bank/projectbrief.md` for scope and requirements
- **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 document explains the WHY behind the product. Reference this when making decisions about UX, features, and user flows.