--- type: prd feature: Roadcrew Submodule Isolation & Multi-Repo Support feature_id: submodule-isolation status: Draft version: 1.0 created: 2025-01-24 updated: 2025-01-24 related_brd: ../brds/submodule-isolation-brd.md related_spec: ../specs/submodule-isolation-spec.md epic: TBD approvers: [product-owner, tech-lead] --- # 📝 Roadcrew Submodule Isolation & Multi-Repo Support – Product Requirements Document {#prd-submodule-isolation} > This document defines **what** will be delivered and **why**. The technical implementation ("how") is documented in the spec. ## 1. Business & User Goals ### 1.1 Business Objectives (≤3, each ≤15 words) > See [BRD § 3 Business Goals](../brds/submodule-isolation-brd.md#3-business-goals) for full business context. - Eliminate namespace conflicts causing customer churn (taxbuddy case) - Enable freemium-to-premium conversion through clear feature gating - Support multi-repo orchestration for Enterprise tier revenue growth ### 1.2 User Goals (≤4, each ≤15 words) - Install Roadcrew without conflicts with existing project folder structures - Update Roadcrew commands without overwriting project-specific customizations - Manage multiple service repos from single centralized planning repository - Clearly understand free vs premium feature boundaries before purchasing ### 1.3 Non-Goals / Out of Scope (≤3, each ≤12 words) - npm package distribution (defer to future release) - Auto-installation on git clone (requires manual install step) - Windows-specific features (cross-platform Node.js only) ## 2. Problem Statement (≤50 words) Roadcrew creates folders (context/, config/, milestones/) that collide with user projects, causing real churn (taxbuddy uninstalled). Commands invisible in .roadcrew/ submodule. No boundary between upstream vs user files. Premium features undefined, blocking monetization. ## 3. Success Metrics ### 3.1 User Metrics (≤2, each ≤15 words) > See [BRD § 7.1 Product/Customer Metrics](../brds/submodule-isolation-brd.md#71-productcustomer-metrics) for business KPIs. - Installation success rate: 95%+ without manual intervention - Update success rate: 95%+ with zero user content overwrites ### 3.2 Business Metrics (≤2, each ≤15 words) > See [BRD § 7.2 Financial Metrics](../brds/submodule-isolation-brd.md#72-financial-metrics) for revenue targets. - Churn rate: <5% monthly (down from namespace conflicts) - Free-to-paid conversion: 5% within 90 days ### 3.3 Technical Metrics (≤2, each ≤15 words) > See [BRD § 7.3 Usage/Technical Metrics](../brds/submodule-isolation-brd.md#73-usagetechnical-metrics) for usage data. - Command resolution time: <100ms for path lookups - Multi-repo API issue creation: <2 seconds per issue ## 4. Requirements ### 4.1 Functional Requirements (max 6, ≤15 words each) - R1: Install Roadcrew as git submodule to .roadcrew/ without namespace conflicts - R2: Copy commands to .cursor/commands/ for Cursor IDE slash command visibility - R3: Detect deployment mode (Mode 0/1/2) and resolve paths dynamically - R4: Gate premium features (--ai, --toc flags) via license key validation (awareness only) - R5: Support multi-repo orchestration with config/repos.yml project mappings - R6: Update submodule and reinstall commands without overwriting user content - R7: Log token usage locally when ROADCREW_TELEMETRY_ENABLED=true (no hard blocking in v1.6.0) ### 4.2 Non-Functional Constraints (≤4, each ≤15 words) - Installation must complete in <10 seconds on standard hardware - Path resolution must work across macOS, Linux, Windows via Node.js - Premium API validation must timeout after 5 seconds, fail gracefully - Submodule updates must preserve all user-created files (context/, milestones/) - License validation must work across Mode 0 (dev), Mode 1 (submodule), Mode 2 (multi-repo) ### 4.3 Acceptance Criteria (product validation, ≤5, each ≤12 words) - AC1: Clean installation on empty project succeeds without errors - AC2: Installation on taxbuddy resolves previous namespace conflicts - AC3: /enrich-release --ai requires valid API key, shows upgrade prompt - AC3.1: Trial license allows 30-day premium access with 100k token quota - AC4: Multi-repo mode creates issues in correct remote repositories - AC5: Update preserves user customizations, overwrites only .cursor/commands/ --- ## 5. User Stories || ID | As a | I want to | So that I can | ||-----|--------------------|----------------------------------------|-------------------------------------------| || US1 | Solo founder | Install Roadcrew without conflicts | Use spec-driven workflow in existing app | || US2 | Small team lead | Try premium AI features via 30-day trial with 100k tokens | Evaluate value before $49/mo commitment | || US3 | Enterprise admin | Coordinate releases across 5 services | Manage microservices from central repo | || US4 | Open source user | Update Roadcrew to latest version | Get new features without breaking project | || US5 | Consulting client | Override templates with custom ones | Maintain industry-specific workflows | --- ## 6. User Journey (≤5 steps, each step ≤15 words) || Step | Action | Expected Result | ||------|---------------------------------------------|--------------------------------------------------| || 1 | Add .roadcrew submodule to project | Submodule cloned, no conflicts with existing folders | || 2 | Run node .roadcrew/install.js | Commands installed, context/ folders created | || 3 | Use /analyze-repo in Cursor chat | Tech stack detected, memory-bank/techContext.md created | || 4 | Try /enrich-release --ai without key | Upgrade prompt shown, trial link provided | || 5 | Set ROADCREW_LICENSE_KEY, run --ai flag | Premium feature executes, token usage tracked | --- ## 7. Non-Goals (within this release, ≤3, each ≤12 words) - Autonomous AI agents (defer to future release) - Self-hosted Enterprise deployment (defer to Phase 3) - Custom AI model fine-tuning (defer to Enterprise Phase 4) --- ## 8. Impact & Dependencies - **Affected Systems:** .cursor/commands/ (all command files), install scripts, path resolution utilities, premium script license validation - **Dependencies:** Git submodule support, Node.js >=16, GitHub API access (multi-repo mode), license validation API (premium features) - **Risks:** User edits .roadcrew/ directly (mitigate with docs), install fails mid-execution (make idempotent) - **Related Links:** [Monetization Strategy](../../memory-bank/requirements/source-docs/submodule-isolation/monetization-strategy.md) --- ## 9. Mapping to Spec | Functional Requirement | Spec Section | |---------------------------------------|--------------| | R1: Install as submodule | 2.1 Mode 1 | | R2: Copy commands to .cursor/commands | 2.1 install.js | | R3: Detect mode and resolve paths | 2.2 Mode Detection | | R4: Gate premium features | 4.1, 8.4 (API-based validation) | | R5: Multi-repo orchestration | 2.4 Mode 2 | | R6: Update without overwriting | 2.5 Update Process | | R7: Log token usage locally | 4.1, 8.4 (Awareness only, v1.6.0 adds enforcement) | --- ## Editor Instructions: - Use bullets and tables exclusively; paragraphs only for Problem Statement (≤50 words). - Each functional requirement (4.1) must map to spec section (9). - Do not exceed length limits; AI and reviewers will reject oversized content. - No implementation details—reference spec for all "how" questions. - PRD answers "what/why", Spec answers "how". - User stories and journeys provide context for spec issue breakdown.