--- type: spec feature: Roadcrew Submodule Isolation & Multi-Repo Support feature_id: submodule-isolation status: Draft version: 1.0 related_brd: ../brds/submodule-isolation-brd.md related_prd: ../prds/submodule-isolation-prd.md epic: TBD created: 2025-01-24 updated: 2025-01-24 --- # ⚙️ Roadcrew Submodule Isolation & Multi-Repo Support – Technical Specification {#spec-submodule-isolation} > This document defines **how** to implement the feature. All "what/why" lives in PRD. ## 1. Mapping: PRD → Spec | PRD Requirement | Satisfied In Spec Section | |---------------------------------------|---------------------------| | R1: Install as submodule | See: 2.1, 8.1 | | R2: Copy commands to .cursor/commands | See: 2.1, 8.2 | | R3: Detect mode and resolve paths | See: 4.1, 8.3 | | R4: Gate premium features | See: 4.2, 8.4 | | R5: Multi-repo orchestration | See: 4.3, 8.5 | | R6: Update without overwriting | See: 2.1, 8.6 | ## 2. Technical Requirements ### 2.1 Functional Requirements (max 6 bullets—must map PRD 1:1) - Submodule structure: .submodule/ in Mode 0 deploys as .roadcrew/ in Mode 1 - Install script: Node.js install.js creates folders, copies commands, updates .gitignore - Mode detection: Auto-detect Mode 0/1/2 via folder presence checks - License validation: API-based feature gating with 5-second timeout - Multi-repo config: YAML-based repos.yml maps projects to GitHub repositories - Update mechanism: git submodule update + reinstall preserves user content ### 2.2 Non-Functional Requirements (≤20 words each) - **Performance:** Mode detection <100ms, install completes <10 seconds, API validation <5 seconds timeout - **Security:** API keys in environment vars, never committed, server-side validation prevents local bypass - **Reliability:** Install script idempotent, safe to re-run, validates prerequisites before execution - **Scalability:** Supports unlimited projects in Mode 2, batch GitHub API calls with rate limiting ### 2.3 Out of Scope (3 bullets max, ≤12 words each) - npm package distribution (submodule-first approach) - Autonomous AI agents (defer to future release) - Self-hosted Enterprise deployment (Phase 3 feature) ## 3. Design Overview (≤100 words) Three deployment modes: Mode 0 (template repo with .submodule/ for distribution), Mode 1 (submodule installation as .roadcrew/ in user projects), Mode 2 (multi-repo orchestration from central repo). Install script copies commands from .roadcrew/commands/ to .cursor/commands/ (Cursor IDE requirement). Path resolution abstraction detects mode and returns correct paths. Premium features gated via API validation against ROADCREW_API_KEY. Multi-repo mode uses config/repos.yml to map release files to GitHub repositories via API. ## 4. Architecture & Implementation ### 4.1 New/Modified Services (bullets, each ≤20 words) - **install.js:** Creates directories, copies commands, instantiates templates, updates .gitignore, displays next steps - **mode-detector.ts:** Detects Mode 0/1/2 via folder checks, returns path configuration object - **path-resolver.ts:** Resolves template/script/context/milestone paths based on detected mode - **license-validator.ts:** Validates ROADCREW_API_KEY against API, enforces tier restrictions, shows upgrade prompts - **project-resolver.ts:** Resolves multi-repo project config from repos.yml, maps release files to repositories - **update.sh:** Pulls latest submodule, reinstalls commands, preserves user content ### 4.2 Data Model Changes (table: field, type, description, notes) **config/repos.yml (Multi-Repo Mode):** | Field | Type | Description | Notes | |------------------------|--------|-----------------------------------------|-------------------------| | organization | string | GitHub org name | Required for Mode 2 | | github.token_env | string | Environment variable for GitHub token | Default: GH_TOKEN | | projects.*.repo | string | GitHub repo (org/repo format) | Target for issue creation | | projects.*.release_file| string | Release file path in roadcrew repo | Maps to target repo | | projects.*.tech_stack | string | Tech stack file path | Per-project tech stack | | projects.*.default_labels| array | Default labels for created issues | Optional | ### 4.3 API Changes (table: method, endpoint, purpose, affected systems) | Method | Endpoint | Purpose | Notes | |--------|-----------------------------|--------------------------------|---------------------------------| | POST | /v1/validate | Validate API key, check tier | Returns tier, features, quota | | POST | /v1/enrich | AI-powered issue enrichment | Starter tier, consumes tokens | | POST | /v1/classify | AI classification + TOC routing| Starter tier, returns 1-10 score| ### 4.4 Env/Config (table: var, default, description, required) | Variable | Default | Description | Required | |-----------------------|----------------------------|----------------------------------|----------| | ROADCREW_API_KEY | None | API key for premium features | Premium only | | ROADCREW_API_URL | https://api.roadcrew.dev | API base URL | No | | GH_TOKEN | None | GitHub API token | Mode 2 | | GITHUB_TOKEN | None | GitHub API token (fallback) | Mode 2 | ## 5. Execution Plan & Issues ### 5.1 Implementation Plan (≤60 words each phase) > See [BRD § 6 GTM Roadmap](../brds/submodule-isolation-brd.md#6-gtm-roadmap) for business phasing. - **Phase 1 (Week 1):** Implement install.js, mode detection, path resolution. Test on clean project and taxbuddy migration. - **Phase 2 (Week 2):** Build license validation system, gate --ai and --toc flags, create upgrade prompts. - **Phase 3 (Week 3):** Add multi-repo support, repos.yml config, GitHub API integration, cross-repo issue creation. ### 5.2 Issues (reference anchors) - [Issue 1](#issue-1): Create install.js installation script - [Issue 2](#issue-2): Implement mode detection logic - [Issue 3](#issue-3): Build path resolution system - [Issue 4](#issue-4): Add license validation API client - [Issue 5](#issue-5): Gate premium command flags - [Issue 6](#issue-6): Implement multi-repo project resolver - [Issue 7](#issue-7): Create update script - [Issue 8](#issue-8): Write migration guide and documentation ### 5.3 Risks & Mitigations (simple table) | Risk | Mitigation | |---------------------------------------|-------------------------------------------------| | Users edit .roadcrew/ files directly | Clear docs warning, use overrides in templates/ | | Install fails mid-execution | Idempotent script, safe to re-run | | Premium features bypassed locally | Server-side validation, can't bypass | | Multi-repo targets wrong repository | Validation prompt before creating issues | ## 6. Testing & Validation ### 6.1 Acceptance Criteria (1 line per acceptance, pass/fail) > Maps to [PRD § 4.3 Acceptance Criteria](../prds/submodule-isolation-prd.md#43-acceptance-criteria-product-validation-5-each-12-words) - Clean installation on empty project succeeds without errors - Installation on taxbuddy resolves previous namespace conflicts - /enrich-release --ai without key shows upgrade prompt and trial link - Multi-repo mode creates issues in correct remote repositories via API - Update preserves user customizations, overwrites only .cursor/commands/ ### 6.2 Test Plan (≤100 words OR checklist bullets) - [ ] Install on empty project (macOS, Linux, Windows) - [ ] Install on taxbuddy (verify namespace conflict resolution) - [ ] Install on ai-launch-kit (verify no file overwrites) - [ ] Test update process (preserves context/, milestones/) - [ ] Test free tier commands (no API key required) - [ ] Test premium flags without API key (shows upgrade prompt) - [ ] Test premium flags with valid API key (executes successfully) - [ ] Test multi-repo mode (3-repo org: frontend, backend, database) - [ ] Test mode detection (Mode 0, 1, 2 correctly identified) ## 7. Dependencies & Links - **Depends On:** Git submodule support, Node.js >=16, GitHub API (Mode 2) - **Blocks:** Future releases requiring clean installation (all depend on this) - **Related:** [Monetization Strategy](../narratives/submodule-isolation/monetization-strategy.md), [Vision](../vision.md) ## 8. Issue Breakdown ### Issue 1: Create install.js installation script {#issue-1} - **Overview:** Node.js script that installs Roadcrew by creating directories, copying commands, instantiating templates, updating .gitignore, and displaying next steps. - **Accepts:** - Creates context/, milestones/, config/, .cursor/commands/ directories - Copies all .md files from .roadcrew/commands/ to .cursor/commands/ - Instantiates vision.template.md and current-release.template.md - Updates .gitignore with .analysis/ and config/reports/ - Displays success message with next steps - **Tech Approach:** - Use Node.js fs module for file operations - Verify .roadcrew/ submodule exists before proceeding - Check if directories exist before creating (idempotent) - Replace {{PLACEHOLDERS}} in templates with project-specific values - Append to .gitignore safely (check for duplicates) - Exit with clear error if prerequisites missing - **Files/Components:** .submodule/install.js, .submodule/templates/* - **Dependencies:** None - **Classification:** 4/10 (medium complexity, well-defined scope) - **Size/Complexity:** M (200-300 lines, file operations, error handling) ### Issue 2: Implement mode detection logic {#issue-2} - **Overview:** TypeScript utility that detects deployment mode (Mode 0/1/2) by checking for indicator files/folders and returns path configuration. - **Accepts:** - Detects Mode 0 when .submodule/ exists - Detects Mode 1 when .roadcrew/ exists - Detects Mode 2 when config/repos.yml exists - Returns ModeConfig object with correct paths - Returns 'unknown' mode when no indicators present - **Tech Approach:** - Check for config/repos.yml first (Mode 2 priority) - Check for .roadcrew/ second (Mode 1) - Check for .submodule/ third (Mode 0) - Return configuration object with paths for each mode - Export requireMode() function for mode validation - Add comprehensive unit tests - **Files/Components:** .submodule/scripts/utils/mode-detector.ts - **Dependencies:** None - **Classification:** 3/10 (straightforward logic, well-defined) - **Size/Complexity:** S (80-100 lines, simple conditional logic) ### Issue 3: Build path resolution system {#issue-3} - **Overview:** TypeScript class that resolves file paths based on detected mode, providing abstraction for template, script, context, and milestone paths. - **Accepts:** - Resolves template paths correctly in all modes - Resolves script paths correctly in all modes - Resolves context paths correctly in all modes - Resolves milestone paths correctly in all modes - Provides singleton instance for global use - **Tech Approach:** - Use mode-detector to get current mode configuration - Implement template(), script(), context(), milestone() methods - Join paths using path.join() for cross-platform compatibility - Cache mode detection result for performance - Export singleton instance - Add integration tests with all three modes - **Files/Components:** .submodule/scripts/utils/path-resolver.ts - **Dependencies:** Issue 2 (mode-detector.ts) - **Classification:** 4/10 (requires mode detection integration) - **Size/Complexity:** S (100-120 lines, path manipulation) ### Issue 4: Add license validation API client {#issue-4} - **Overview:** TypeScript module that validates ROADCREW_API_KEY against API server, checks feature access, enforces tier restrictions, and handles network errors gracefully. - **Accepts:** - Returns free tier when no API key present - Validates API key with server (POST /v1/validate) - Returns tier, features, token quota in response - Handles network errors gracefully (5-second timeout) - requireFeature() exits with upgrade prompt on failure - **Tech Approach:** - Use node-fetch for API calls - Read ROADCREW_API_KEY from environment variable - Implement 5-second timeout on API requests - Handle 401 (invalid key), 403 (insufficient tier), network errors - Return LicenseValidationResponse interface - Export requireFeature(), hasFeature(), getLicenseInfo() functions - **Files/Components:** .submodule/scripts/utils/license-validator.ts - **Dependencies:** None (standalone API client) - **Classification:** 5/10 (network calls, error handling, security) - **Size/Complexity:** M (200-250 lines, API integration) ### Issue 5: Gate premium command flags {#issue-5} - **Overview:** Update enrich-release and scope-release commands to check for premium flags (--ai, --toc) and enforce license validation before execution. - **Accepts:** - /enrich-release --ai requires license validation - /scope-release --toc requires license validation - Shows upgrade prompt with pricing and trial link - Executes premium features when valid key present - Free tier behavior works without API key - **Tech Approach:** - Import requireFeature() from license-validator - Check for --ai or --toc flags in argv - Call requireFeature() with appropriate tier requirement - Display free tier message when premium flag not used - Track token usage when premium features executed - Update command documentation with premium flag info - **Files/Components:** .cursor/commands/enrich-release.md, .cursor/commands/scope-release.md - **Dependencies:** Issue 4 (license-validator.ts) - **Classification:** 6/10 (command integration, user experience) - **Size/Complexity:** M (modify 2 commands, add validation logic) ### Issue 6: Implement multi-repo project resolver {#issue-6} - **Overview:** TypeScript module that resolves project configuration in multi-repo mode by reading config/repos.yml and mapping projects to GitHub repositories. - **Accepts:** - Loads and parses config/repos.yml file - Returns ProjectConfig for specified project - Validates project exists in configuration - Returns local config for submodule mode - Shows available projects in error messages - **Tech Approach:** - Use js-yaml to parse repos.yml configuration - Integrate with mode-detector to determine mode - Return local config for Mode 1 (ignores --project flag) - Require --project flag for Mode 2 - Validate project exists in config before proceeding - Return repo, release_file, tech_stack, default_labels - **Files/Components:** .submodule/scripts/utils/project-resolver.ts, config/repos.yml (template) - **Dependencies:** Issue 2 (mode-detector.ts) - **Classification:** 5/10 (YAML parsing, config validation) - **Size/Complexity:** M (150-200 lines, config management) ### Issue 7: Create update script {#issue-7} - **Overview:** Bash script that updates Roadcrew submodule to latest version and reinstalls commands without overwriting user content. - **Accepts:** - Pulls latest .roadcrew/ submodule via git - Reinstalls commands to .cursor/commands/ - Preserves context/, milestones/ user content - Shows recent commits in update summary - Provides npm script wrapper - **Tech Approach:** - Run git submodule update --remote .roadcrew - Call node .roadcrew/install.js --update flag - Add --update flag to skip template instantiation - Display git log of recent changes - Create npm script: "roadcrew:update" - Test on project with existing user content - **Files/Components:** .submodule/scripts/update.sh, package.json (npm script) - **Dependencies:** Issue 1 (install.js must support --update flag) - **Classification:** 3/10 (straightforward bash + npm script) - **Size/Complexity:** S (30-50 lines bash script) ### Issue 8: Write migration guide and documentation {#issue-8} - **Overview:** Create comprehensive documentation for migrating existing projects to submodule model and using new multi-repo features. - **Accepts:** - Migration guide for taxbuddy and ai-launch-kit - Getting started guide for new installations - Multi-repo configuration examples - Premium feature documentation - Troubleshooting section - **Tech Approach:** - Document step-by-step migration process - Include backup instructions before migration - Provide example config/repos.yml configurations - Document all premium flags and tiers - Create troubleshooting section for common issues - Update README.md with installation instructions - **Files/Components:** docs/migration.md, docs/multi-repo.md, README.md - **Dependencies:** Issues 1-7 (document completed features) - **Classification:** 2/10 (documentation, no code) - **Size/Complexity:** M (comprehensive documentation) --- ## Editor Instructions: - Write as atomic, non-narrative items wherever possible. - Never exceed field length limits. - All mapping tables must match PRD keys exactly. - Issue breakdowns must map 1:1 to enhancement.template.md structure. - Anchors enable deep linking: `#issue-{{N}}` - Classification (1-10) drives assignment in scope-release. - Any deviation, ambiguity, or overrun invalidates this doc for automation.