# ROADCREW FREEMIUM PRINCIPLES - Complete Model

## Overview

Roadcrew's freemium model has **ONE consistent tier structure** that works in two deployment phases:
- **Pre-API Phase (v1.6.x):** Users download/clone and run locally
- **Post-API Phase (v1.7.0+):** Users validate license keys and access functionality via API servers

The tier structure, pricing, and value proposition remain **identical**. Only the validation mechanism and infrastructure change.

---

## Universal Tier Structure (All Phases)

| Dimension | FREE | STARTER | ENTERPRISE |
|-----------|------|---------|------------|
| **Price** | $0/month | $49/month | $999+/month |
| **Hands-Off Time** | 0 min | 1-15 min | Up to 60 min |
| **Repo Scope** | Single | Monorepo | Multi-repo |
| **User Presence** | 100% | 20-30% | <10% |

### Repo Scope Definition

**FREE: Single Repository**
- One repo at a time
- No cross-repo operations
- Focus: Single-team, single-codebase

**STARTER: Monorepo (One Repository, Multiple Packages)**
- Multiple packages/workspaces within one repo
- Inter-package dependency awareness
- Focus: Teams managing coordinated packages

**ENTERPRISE: Multi-Repo (Multiple Separate Repositories)**
- Orchestrate across separate repos
- Cross-repo dependencies
- Team-wide coordination
- Focus: Organizations with multiple repos/teams

---

## Universal Feature Set (All Phases)

All tiers get these features:

### AI-Assisted GitHub Automation (All Tiers)
- ✅ Auto-create issues from AI analysis
- ✅ Template auto-detection
- ✅ Epic creation
- ✅ Issue linking

**Differentiation by tier:**
- FREE: Single repo scope
- STARTER: Monorepo scope + optimization hints
- ENTERPRISE: Multi-repo scope + cross-repo linking + auto-assignment

### Resource Classification (STARTER+)
- FREE: ❌ Not available
- STARTER: ✅ Shows 1-10 scale + resource hints
- ENTERPRISE: ✅ Shows 1-10 scale + auto-assigns to team

### Pause Enforcement (Rate Limiting via User Interaction)
- FREE: No pauses (user controls workflow)
- STARTER: Every 3 items OR 5 min ("Review before continuing?")
- ENTERPRISE: Every 10 items OR 20 min ("Review orchestration plan?")
- Override: `--force` flag available in STARTER/ENTERPRISE

---

## PRE-API PHASE (v1.6.x) - Current Implementation

### Deployment Model
- Users download/clone from GitHub
- Run locally on their machine
- No backend infrastructure required
- Code is distributed (open source or compiled)

### Validation Mechanism
**Client-Side Only (Honor System)**
- Feature gates check `ROADCREW_LICENSE_KEY` environment variable
- Pause enforcement happens at CLI level
- Classification calculated locally
- No server calls for validation

### Feature Gates

| Flag | FREE | STARTER | ENTERPRISE |
|------|------|---------|------------|
| (none) | ✅ | ✅ | ✅ |
| --ai | ✅ | ✅ | ✅ |
| --monorepo | ❌ | ✅ | ✅ |
| --multi-repo | ❌ | ❌ | ✅ |
| --force | N/A | ✅ | ✅ |

**Validation:**
```bash
if (--monorepo flag):
  if (ROADCREW_LICENSE_KEY):
    # STARTER or ENTERPRISE
    proceed()
  else:
    error: "Monorepo requires STARTER tier ($49/month)"
```

### Pause Enforcement Implementation

**STARTER:**
```
Generate issue #1 → ✓ Created
Generate issue #2 → ✓ Created
Generate issue #3 → ⏸ PAUSE
"You've created 3 issues. Review before continuing? (y/n)"
↓
y → Continue to issue #4
--force → Skip pauses
```

**ENTERPRISE:**
```
Generate issues #1-5 → Continue
Generate issues #6-10 → ⏸ PAUSE
"You've created 10 issues. Review orchestration? (y/n)"
↓
y → Continue to issue #11
--force → Skip pause
```

### LLM API Management (Pre-API)
- Users provide their own LLM API key (OpenAI, Claude, etc.)
- Roadcrew has ZERO infrastructure costs for AI
- Users pay directly to their LLM provider
- Budgeting guidance provided (no enforcement)

---

## POST-API PHASE (v1.7.0+) - Future Implementation

### Deployment Model
- Users access Roadcrew via REST/GraphQL API
- Backend services run on Roadcrew infrastructure
- Authentication via API key or OAuth
- Distributed compute, centralized coordination

### Validation Mechanism
**Server-Side (Authoritative)**
- API checks license tier for every request
- Feature gates enforced at server level
- Pause enforcement via rate limiting
- Classification calculated server-side (impacts quota)

### Feature Gates (Same as Pre-API, Different Mechanism)

| Flag | FREE | STARTER | ENTERPRISE |
|------|------|---------|------------|
| (none) | ✅ | ✅ | ✅ |
| --ai | ✅ | ✅ | ✅ |
| --monorepo | ❌ | ✅ | ✅ |
| --multi-repo | ❌ | ❌ | ✅ |
| --force | N/A | ✅ | ✅ |

**Validation:**
```typescript
POST /api/v1/generate-issues
Authorization: Bearer <api_key>
Body: { monorepo: true, ... }

Server checks:
  tier = lookup_tier_from_api_key(api_key)
  if (monorepo && tier === 'FREE'):
    return 403 "Monorepo requires STARTER tier"
```

### Pause Enforcement Implementation (API)

**STARTER Tier Rate Limiting:**
```
POST /api/v1/generate-issue #1 → 200 OK
POST /api/v1/generate-issue #2 → 200 OK
POST /api/v1/generate-issue #3 → 429 Rate Limited
  Response: "Created 3 issues. Review before continuing."
  Header: Retry-After: 300 (5 minutes)

Override: X-Force-Continue: true header
```

**ENTERPRISE Tier Rate Limiting:**
```
POST /api/v1/generate-issues (batch 1-5) → 200 OK
POST /api/v1/generate-issues (batch 6-10) → 429 Rate Limited
  Response: "Created 10 issues. Review orchestration plan."
  Header: Retry-After: 1200 (20 minutes)

Override: X-Force-Continue: true header
```

### LLM API Management (Post-API)
**Two Options:**

**Option A: Users Bring Their API**
- Users provide LLM API key (same as pre-API)
- Roadcrew routes through user's API
- Roadcrew charges for coordination/orchestration only
- Pricing: STARTER $49/mo, ENTERPRISE $999+/mo

**Option B: Roadcrew Provides API Budget**
- Roadcrew manages LLM API on backend
- Token quota enforced per tier
- Example: STARTER = 100k tokens/month (quota-enforcer.ts active)
- Pricing includes AI budget

**Likely:** Hybrid approach (users can bring their own or use Roadcrew's budget)

---

## Migration Path: v1.6.x → v1.7.0+

### For Existing FREE Tier Users
**Pre-API (v1.6.x):**
- Download code, run locally
- No ROADCREW_LICENSE_KEY needed
- Full access to all repo scopes locally

**Migration to Post-API (v1.7.0+):**
```
Option 1: Stay on v1.6.x
  ✅ Continue using local version
  ✅ No breaking changes
  ✅ No API interaction

Option 2: Upgrade to v1.7.0+ API
  ✅ Move to Roadcrew-hosted service
  ⚠️  Need API key (free tier available)
  ⚠️  Same features, hosted by us
```

### For Existing STARTER Tier Users
**Pre-API (v1.6.x):**
- Download code
- Set ROADCREW_LICENSE_KEY
- Access --monorepo features
- Use their own LLM API

**Migration to Post-API (v1.7.0+):**
```
Automatic:
  1. Provide API key (replace ROADCREW_LICENSE_KEY)
  2. API routes requests to Roadcrew servers
  3. Same tier features (monorepo coordination)
  4. Same pricing ($49/month)
  
Optional:
  - Continue using v1.6.x CLI locally
  - Or switch to v1.7.0+ API-based CLI
```

### For Existing ENTERPRISE Tier Users
**Pre-API (v1.6.x):**
- Download code
- Set ROADCREW_LICENSE_KEY
- Access --multi-repo features
- Use their own LLM API
- Configure roadcrew.yml for team

**Migration to Post-API (v1.7.0+):**
```
Smooth transition:
  1. Provide API key
  2. Migrate roadcrew.yml to server-side configuration
  3. Same tier features (multi-repo orchestration)
  4. Same pricing ($999+/month)
  
Benefit:
  - Faster orchestration (parallel on server)
  - Better resource coordination
  - Audit logs and team tracking
  - Optional: Roadcrew manages LLM API budget
```

---

## Validation Timeline

### Pre-API Phase (v1.6.x - Now)
- **Validation:** Client-side only (compile + license key check)
- **Quota:** None (user controls their own API)
- **Enforcement:** Honor system with compiled code
- **Focus:** Adoption and distribution

### Post-API Phase (v1.7.0+ - Future)
- **Validation:** Server-side (authoritative)
- **Quota:** Optional (per-tier token budgets)
- **Enforcement:** API rate limiting + hard blocks
- **Focus:** Infrastructure efficiency and revenue

---

## Decision Framework for Tier Placement

When deciding where to place a feature, ask:

**1. What's the resource consumption?**
   - FREE: Zero infrastructure cost (user's machine/API)
   - STARTER: Moderate coordination cost (monorepo analysis)
   - ENTERPRISE: High coordination cost (multi-repo orchestration)

**2. What's the scope limitation?**
   - FREE: Single repo only
   - STARTER: One repo, multiple packages
   - ENTERPRISE: Multiple repos

**3. What's the automation level?**
   - FREE: User provides LLM API, no Roadcrew overhead
   - STARTER: Coordinated batch processing
   - ENTERPRISE: Full orchestration with team coordination

---

## Summary Table: Pre-API vs Post-API

| Aspect | Pre-API (v1.6.x) | Post-API (v1.7.0+) |
|--------|------------------|-------------------|
| **User Experience** | CLI, local | API + CLI |
| **Tier Structure** | Same (FREE/STARTER/ENTERPRISE) | Same (FREE/STARTER/ENTERPRISE) |
| **Validation** | Client-side | Server-side |
| **Pause Enforcement** | CLI level | API rate limiting |
| **LLM API** | User's own | User's own (or Roadcrew's) |
| **Token Quota** | None | Optional (per-tier budgets) |
| **Infrastructure Cost** | Zero | Scaling with users |
| **Revenue Model** | License key sales | API subscriptions |
| **User Data** | Local only | Server-stored |
| **Audit Logs** | None | Full history |

---

## Key Principles (Both Phases)

1. **One tier structure, two deployment models**
   - Not "different freemium models," just "different infrastructure"

2. **Pause enforcement, not feature removal**
   - Users can always override with `--force`
   - Respects autonomy while preventing chaos

3. **Repo scope is the boundary**
   - Single → Monorepo → Multi-repo is intuitive upgrade path

4. **Users control LLM costs (pre-API) or choose budget model (post-API)**
   - Transparent relationship with pricing

5. **Hands-off time is what users pay for**
   - Freedom from supervision is the real value

6. **Classification is STARTER+ (knowledge work)**
   - FREE tier focuses on automation

---

## Implementation Roadmap

### Phase 1: Pre-API Stability (v1.6.x)
- ✅ Pause enforcement at CLI level
- ✅ License key gates (--monorepo, --multi-repo)
- ✅ Classification display in STARTER+
- ✅ User-provided LLM APIs

### Phase 2: Post-API Launch (v1.7.0+)
- 🔄 Server-side validation
- 🔄 API rate limiting (pause enforcement)
- 🔄 Optional Roadcrew LLM budgets
- 🔄 Team audit logs
- 🔄 Parallel processing (faster multi-repo)

### Phase 3: Monetization Optimization (v1.8.0+)
- 📅 Dynamic pricing based on resource usage
- 📅 Volume discounts for ENTERPRISE
- 📅 Custom tier support

---

## Questions?

- For tier structure details: See [COMPLETE-TIER-FRAMEWORK.md](COMPLETE-TIER-FRAMEWORK.md)
- For implementation quick reference: See [QUICK-TIER-REFERENCE.txt](QUICK-TIER-REFERENCE.txt)
- For what changed from old model: See [FRAMEWORK-CHANGES-SUMMARY.md](FRAMEWORK-CHANGES-SUMMARY.md)
- For phase-specific details: See `pre-API-freemium.md` (v1.6.x) or `post-API-freemium.md` (v1.7.0+)

## Current Command Audit (49 Total)

| # | Command Name | Current Tier | # Commands Called | # Scripts Called | Estimated Input Tokens |
|---|--------------|--------------|-------------------|------------------|------------------------|
| 1 | analyze-multiplatform | ENTERPRISE | 23 | 3 | 4596 |
| 2 | analyze-repo | FREE | 16 | 2 | 6746 |
| 3 | guide-release | FREE | 15 | 2 | 3725 |
| 4 | autopilot | STARTER | 15 | 2 | 7171 |
| 5 | implement-epic | STARTER | 14 | 1 | 4922 |
| 6 | create-spec | FREE | 13 | 0 | 3352 |
| 7 | create-prd | FREE | 12 | 0 | 4038 |
| 8 | minimize-cost | ENTERPRISE | 12 | 3 | 6186 |
| 9 | create-brd | FREE | 11 | 0 | 4052 |
| 10 | optimize-command | FREE | 10 | 4 | 3237 |
| 11 | scope-release | STARTER | 10 | 2 | 10554 |
| 12 | create-release-docs | FREE | 9 | 0 | 5198 |
| 13 | code-cleanup | FREE | 8 | 0 | 2956 |
| 14 | sync-release-status | FREE | 8 | 0 | 2871 |
| 15 | analyze-epic | STARTER | 8 | 1 | 4120 |
| 16 | minimize-manual-steps | STARTER | 8 | 10 | 3946 |
| 17 | start-testing | STARTER | 8 | 3 | 3321 |
| 18 | analyze-multiplatform | ENTERPRISE | 8 | 0 | 8133 |
| 19 | review-code | FREE | 7 | 0 | 1995 |
| 20 | enrich-release | STARTER | 7 | 1 | 3229 |
| 21 | validate-release-docs | FREE | 6 | 2 | 3023 |
| 22 | advance-release | FREE | 6 | 0 | 5233 |
| 23 | build-distribution | FREE | 6 | 0 | 2110 |
| 24 | update-roadcrew | FREE | 6 | 0 | 3074 |
| 25 | implement-issue | STARTER | 6 | 0 | 1103 |
| 26 | classify-feedback | FREE | 5 | 0 | 3227 |
| 27 | triage-pr | FREE | 5 | 0 | 1052 |
| 28 | optimize-all-commands | FREE | 4 | 5 | 2872 |
| 29 | validate-release | FREE | 4 | 1 | 1592 |
| 30 | usage-report | STARTER | 4 | 1 | 706 |
| 31 | validate-github-templates | STARTER | 4 | 3 | 1686 |
| 32 | create-release-pr | FREE | 3 | 0 | 1940 |
| 33 | update-roadmap | FREE | 3 | 0 | 1880 |
| 34 | create-epic | STARTER | 3 | 1 | 2045 |
| 35 | build-project | ENTERPRISE | 2 | 6 | 1929 |
| 36 | uninstall-roadcrew | FREE | 1 | 0 | 153 |
| 37 | complete-release | FREE | 1 | 0 | 1598 |
| 38 | update-my-documents | FREE | 1 | 0 | 2587 |
| 39 | sync-roadmap | FREE | 0 | 0 | 978 |

### Tier Distribution Summary

- **FREE:** 24 commands (63%) — **Total: ~75,000 tokens**
- **STARTER:** 11 commands (29%) — **Total: ~42,000 tokens**
- **ENTERPRISE:** 3 commands (8%) — **Total: ~15,000 tokens**

**Overall Stats:**
- Total tokens across all 49 commands: **~132,000 tokens**
- Average tokens per command: **~3,470 tokens**
- Highest: `scope-release` (STARTER) with 10,554 tokens
- Lowest: `uninstall-roadcrew` (FREE) with 153 tokens

---

## Functional Decomposition & Core Primitives

### Tier 1: Core Primitives (Called by 5+ Commands)

These load-bearing functions are the foundation of the system:

| Command | Tier | Called By (Count) | Direct Calls | Reusability Score |
|---------|------|-------------------|--------------|-------------------|
| **scope-release** | STARTER | 12 | 10 | **110** |
| **analyze-repo** | FREE | 10 | 16 | **84** |
| **implement-epic** | STARTER | 9 | 14 | **76** |
| advance-release | FREE | 6 | 6 | 54 |
| enrich-release | STARTER | 6 | 7 | 53 |
| analyze-epic | STARTER | 6 | 8 | 52 |
| autopilot | STARTER | 6 | 15 | 45 |

**Key Insight:** Optimizing `scope-release`, `analyze-repo`, and `implement-epic` would have the highest impact on system efficiency.

---

## Functional Overlap Patterns

### Identified Duplication Opportunities

**Pattern 1: Release Coordination (4 commands)**
- `advance-release`, `complete-release`, `sync-release-status`, `create-release-pr`
- **Opportunity:** Extract `release-state-manager` function (~800 tokens saved)

**Pattern 2: Epic/Issue Analysis (3 commands)**
- `analyze-epic`, `implement-epic`, `analyze-repo`
- **Opportunity:** Extract `scope-analyzer` function (~2K tokens saved)

**Pattern 3: Documentation Generation (6 commands)**
- `create-brd`, `create-prd`, `create-spec`, `create-release-docs`
- **Opportunity:** Extract `doc-generator` function (~1.2K tokens saved)

**Pattern 4: Code Analysis (3 commands)**
- `review-code`, `code-cleanup`, `validate-release-docs`
- **Opportunity:** Extract `code-analyzer` function (~900 tokens saved)

**Total Potential Savings:** ~15-20K tokens (~12-15% reduction) through focused refactoring

---

## Cross-Tier Dependency Violations

**Constraint Violation Found:**
- Some FREE commands call STARTER commands, violating subset/superset hierarchy
- Must be fixed during refactoring phase