---
type: prd
title: Roadcrew Freemium Product Requirements
feature_id: freemium
status: Draft
version: 1.0
related_brd: ../brds/freemium-brd.md
related_spec: ../specs/freemium-spec.md
roadcrew_last_updated: "2025-10-28"
---

# 📝 Product Requirements Document: Roadcrew Freemium Model

## 1. Business & User Goals

### Business Objectives
1. **Rapid Adoption**: Achieve 5K+ active users within 18 months through open/compiled distribution
2. **Low Friction**: Make FREE tier so valuable that users experience "aha moment" without paid features
3. **Natural Upgrade Path**: Tier structure (Single → Monorepo → Multi-repo) feels like intuitive growth, not paywall
4. **Community-Driven**: Build ecosystem where users want to contribute and extend

### User Goals
1. **Solo Developer**: "I want to automate my single-repo workflow locally without paying"
2. **Small Team**: "I want to coordinate my monorepo workflow without manually orchestrating"
3. **Enterprise**: "I want to manage multiple repos across our organization with team coordination"

## 2. Market & Customer Understanding

### Primary User Personas

| Persona | Pain Point | Desired Outcome | Tier Match |
|---------|-----------|-----------------|-----------|
| **Indie Dev** | Manual, repetitive GitHub work | Run automation locally, free | FREE |
| **Fast Founder** | Team coordination getting complex | Hands-off time for focus work | STARTER |
| **Enterprise Architect** | Multi-team, multi-repo chaos | Full orchestration + visibility | ENTERPRISE |

### Problem Statement (≤50 words)

Developers spend hours on manual tasks (GitHub issue creation, code review, testing setup) that AI could automate. Existing tools are either expensive SaaS or require infrastructure management. Roadcrew enables AI automation that runs locally, costs nothing (FREE), or minimal ($49/mo for teams).

## 3. Product Success Metrics

### Product/Customer Metrics
- **Active Users (Monthly)**: 5K by month 18
- **Tier Distribution**: 90% FREE, 7-8% STARTER, 2-3% ENTERPRISE (pre-API)
- **FREE→STARTER Conversion**: 3-5% by month 12
- **Command Adoption**: >60% of users run at least 2 commands/month

### Financial Metrics
- **STARTER ARR**: $29.4K (600 users)
- **ENTERPRISE ARR**: $24K (2 customers)
- **Gross Margin**: >75% (pre-API infrastructure costs minimal)

### Usage/Engagement Metrics
- **Command Success Rate**: >90% across all tiers
- **Pause Enforcement**: >95% compliance on STARTER/ENTERPRISE
- **Support Response Time**: <24 hours for blocking issues

## 4. Functional Requirements

### R1: Universal Tier Structure
All tiers (FREE, STARTER, ENTERPRISE) access the same 47 commands. Tier determines: (a) repo scope access (`--monorepo`, `--multi-repo`), (b) pause enforcement frequency, (c) hands-off time windows.

### R2: Repository Scope Gating
- **FREE**: Single repository only (no `--monorepo` or `--multi-repo` flags)
- **STARTER**: Monorepo support (`--monorepo` flag enabled)
- **ENTERPRISE**: Multi-repo support (`--multi-repo` flag enabled)

### R3: License Validation (Pre-API: Client-Side)
- Users set `ROADCREW_LICENSE_KEY` environment variable
- Validation happens at CLI runtime (local check, no server call)
- Invalid/expired keys show helpful error message with upgrade link

### R4: Pause Enforcement (Rate Limiting)
- **FREE**: No pauses (user controls workflow, instant execution)
- **STARTER**: Pause after 3 items OR 5 minutes (whichever comes first)
- **ENTERPRISE**: Pause after 10 items OR 20 minutes (whichever comes first)
- **Override**: `--force` flag skips pauses in STARTER/ENTERPRISE

### R5: Hands-Off Time Measurement
Commands must measure and track actual hands-off time (not estimates):
- Store metrics in `.roadcrew/metrics/commands/YYYY-MM-DD.jsonl`
- Track: hands-on time, hands-off time, decision points, pause durations
- Used for quarterly reviews to validate tier boundaries

### R6: LLM API Management
- **Pre-API (v1.6.x)**: Users provide own LLM API keys (OpenAI, Claude, etc.)
- **Post-API (v1.7.0+)**: Users can bring own API OR use optional Roadcrew budgets
- Roadcrew manages token budgeting and cost warnings

## 5. User Stories

| Story | Acceptance | Benefit |
|-------|-----------|---------|
| As a solo dev, I want to run Roadcrew locally WITHOUT licensing | I can clone repo, run `npm install && npm start`, automate my repo | No friction to try FREE tier |
| As a team lead, I want my team to work on one monorepo | STARTER flag unlocks monorepo mode, CLI shows scope limits | Clear "need this? Upgrade" message |
| As an enterprise architect, I want to coordinate 3 separate repos | ENTERPRISE flag unlocks multi-repo orchestration | Natural growth path |
| As a FREE user, I want to understand why I hit a pause | Clear pause message explains: "You've created 3 items. Review?" | Learning opportunity for STARTER conversion |
| As a STARTER user, I want to skip the pause review | I can use `--force` flag to override pause | Respects my autonomy |

## 6. User Journey (Happy Path)

| Step | Action | Expected Result | Experience |
|------|--------|-----------------|------------|
| 1 | Clone `git clone roadcrew` | Code downloaded locally | "Aha! I can run this" |
| 2 | Run `npm install && npm start` | Commands available immediately | "It works out-of-box" |
| 3 | Try `/analyze-repo` | Single repo analyzed, BRD/PRD/Spec generated | "Wow, this is powerful" |
| 4 | Try `/scope-release` | GitHub issues created, running on single repo | "This saves hours" |
| 5 | Try with `--monorepo` flag | Error: "Monorepo requires STARTER ($49/mo)" | "I might upgrade" |
| 6 | Set `ROADCREW_LICENSE_KEY` (STARTER) | Monorepo features unlock | "Great, coordination works" |
| 7 | Use for team releases | Batch processing with pauses | "3-5 min hands-off time" |

## 7. Product Acceptance Criteria

- [ ] User can download code and run FREE tier without licensing or setup
- [ ] Repo scope enforcement works: FREE blocks `--monorepo`, STARTER blocks `--multi-repo`
- [ ] Pause enforcement happens: STARTER pauses at 3 items, ENTERPRISE at 10
- [ ] Hands-off time measurement is empirical (not estimated)
- [ ] Error messages educate users about tier differences
- [ ] `--force` override flag works in STARTER/ENTERPRISE (respects autonomy)
- [ ] Migration path from v1.6.x to v1.7.0+ preserves user satisfaction

## 8. Non-Functional Requirements

| Requirement | Target | Rationale |
|-------------|--------|-----------|
| **Local Execution (FREE)** | 100% runs locally | Zero infrastructure = easy adoption |
| **Command Latency** | <5s for setup, <60s for execution | Keeps hands-on time minimal |
| **Reliability** | >90% success rate | Prevents user frustration |
| **Documentation** | "No code = no docs needed" | Open source clarity |
| **Backward Compatibility** | v1.6.x→v1.7.0 transition smooth | Users update, not replaced |

## 9. Mapping to Technical Specification

| Product Requirement | Spec Section | Technical Implementation |
|-------------------|--------------|-------------------------|
| R1: Universal Tier Structure | 2.1 | All 47 commands in every tier; flags determine access |
| R2: Repository Scope Gating | 2.2 | License validator checks flags; blocks invalid scopes |
| R3: License Validation | 3.1 | Client-side ROADCREW_LICENSE_KEY env var check |
| R4: Pause Enforcement | 3.2 | Pause tracker counts items/time; prompts user at limit |
| R5: Hands-Off Time | 3.3 | Timer instrumentation records actual durations |
| R6: LLM API Management | 4.1 (Pre-API), 4.2 (Post-API) | User's own API or Roadcrew-managed budget |

---

## Out of Scope (v1.6.x Pre-API Phase)

- ❌ Server-side API (comes in v1.7.0+)
- ❌ Roadcrew-managed LLM budgets (comes in v1.7.0+)
- ❌ Team management features (comes in v1.7.0+)
- ❌ Audit logs (comes in v1.7.0+)
- ❌ SSO/RBAC enterprise features (comes later)

---

## Phase-Specific Product Scopes

### Pre-API Phase (v1.6.x) - Current
- Client-side validation (honor system)
- CLI-level pause enforcement
- User-provided LLM APIs
- Timer instrumentation (prepare for v1.7.0)
- Classification display (STARTER+)

### Post-API Phase (v1.7.0+) - Coming Mid-2026
- Server-side license validation (authoritative)
- API rate limiting (pause enforcement)
- Optional Roadcrew LLM budgets
- Team audit logs
- Parallel processing for faster execution

---

## Tier Value Proposition

### FREE Tier
**What users get:**
- All 47 Roadcrew commands
- Single-repository automation
- 0 hands-off time (must stay present)
- Use user's own LLM API
- Full code access (understand how it works)

**Cost:** $0
**User:** Solo developers, hobbyists, evaluators

### STARTER Tier  
**What users get:**
- All 47 Roadcrew commands (same as FREE)
- Monorepo support (coordinate multiple packages)
- 1-15 min hands-off time (quick break possible)
- Pause after 3 items or 5 min (review point)
- `--force` flag to skip pauses
- Same LLM API model (user's own)

**Cost:** $49/month
**User:** Small teams, fast founders, growing projects

### ENTERPRISE Tier
**What users get:**
- All 47 Roadcrew commands (same as FREE)
- Multi-repo support (coordinate 3+ separate repos)
- Up to 60 min hands-off time (full break possible)
- Pause after 10 items or 20 min (review orchestration)
- `--force` flag to skip pauses
- Optional future: Roadcrew-managed LLM budgets

**Cost:** $999+/month
**User:** Large organizations, enterprises, compliance-focused teams

---

## Key Features by Tier

| Feature | FREE | STARTER | ENTERPRISE |
|---------|------|---------|-----------|
| **Core Commands (47)** | ✅ All | ✅ All | ✅ All |
| **Single-Repo Automation** | ✅ | ✅ | ✅ |
| **Monorepo Coordination** | ❌ | ✅ | ✅ |
| **Multi-Repo Orchestration** | ❌ | ❌ | ✅ |
| **Hands-Off Time** | 0 min | 1-15 min | 1-60 min |
| **Pause Enforcement** | None | Every 3 items/5 min | Every 10 items/20 min |
| **LLM Cost Control** | User's API | User's API | User's API (later: Roadcrew budgets) |
| **Classification Display** | ❌ | ✅ | ✅ |

---

## Success Definition

Product is successful when:
1. ✅ 5K+ active users by month 18 (adoption metric)
2. ✅ 90%+ users stay on FREE, don't feel rushed to upgrade
3. ✅ 3-5% of FREE users convert to STARTER in first year
4. ✅ Hands-off time metrics align with tier promises (±10%)
5. ✅ ENTERPRISE customers see value in multi-repo coordination
6. ✅ Community contributions grow month-over-month
7. ✅ v1.6.x→v1.7.0+ transition is smooth (no user churn)