Roadcrew Internal Development

This is the internal development repository for Roadcrew - the AI-powered release management and automation framework.

⚠️ This is a private repository for Roadcrew team development only. Customers should use the public roadcrew distribution repository.

Features

Roadcrew provides AI-powered automation for:

• Spec-Driven Development: Write specifications, let AI implement code and tests
• Release Management: Automated release planning, scoping, and tracking
• Epic & Issue Generation: AI creates GitHub issues with proper structure and dependencies
• Code Analysis: Complexity, performance, security, and style audits
• Intelligent Assignment: AI recommends optimal team member assignments based on classification
• Pre-Publish Validation: Automated checks to ensure production readiness
• Multi-Tier Support: Free, Starter, and Enterprise tier commands
• Cursor Integration: Deep integration with Cursor AI for enhanced workflows

Installation

For detailed installation instructions, see Installation Guide or Submodule Setup Guide.

Roadcrew is designed to be installed as a git submodule for clean separation between your project and Roadcrew's distribution.

Quick Start for New Projects

npm install --save-dev roadcrew

The post-install script will automatically:

• Set up .roadcrew/ as a git submodule
• Initialize the submodule
• Run the project installer

Quick Start for Existing Projects

# Download and run the setup script
curl -O https://raw.githubusercontent.com/tailwind-ai/roadcrew/main/setup.sh
chmod +x setup.sh
./setup.sh

This will:

1. Add .roadcrew/ as a git submodule
2. Initialize the submodule
3. Set up your project structure with AI context

Manual Installation

# Initialize git (if needed)
git init

# Add Roadcrew as a submodule
git submodule add https://github.com/tailwind-ai/roadcrew.git .roadcrew
git submodule update --init --recursive

# Run installer
node .roadcrew/install.cjs

What Gets Installed

• ✅ .roadcrew/ - Git submodule with Roadcrew distribution
• ✅ .cursor/commands - Symlink to 57 workflow commands
• ✅ .cursorrules.md - Cursor AI workflow configuration
• ✅ ai-context.yml - AI context for your project
• ✅ memory-bank/techContext.md - Technology stack detection
• ✅ context/ - Project documentation templates

Updating Roadcrew

To update to the latest version:

/update-roadcrew

Or manually:

git submodule update --remote .roadcrew
git add .roadcrew
git commit -m "chore: update Roadcrew"

For more information, see Submodule Setup Guide.

Usage

Core Commands

Analysis & Planning:

• /analyze-repo - Comprehensive repository analysis
• /scope-release - Plan release with issues and assignments
• /create-epic - Create epic with properly scoped child issues

Implementation:

• /autopilot - Combined analysis + implementation
• /implement-issue - Implement single GitHub issue
• /advance-release - Advance release through workflow stages

Quality Assurance:

• /audit-complexity - Code complexity analysis
• /audit-security - Security and IP protection audit
• /audit-performance - Performance analysis
• /review-code - AI code review orchestration

Publishing:

• /pre-publish-audit - Validate publication readiness
• /validate-for-publish - Interactive pre-publish validation
• /pre-publish-checklist - Team approval checklist

See .cursor/commands/ for complete command documentation.

Workflow Stages

Roadcrew enforces a 7-stage workflow:

1. ANALYSIS - Understand requirements and scope
2. PLANNING - Create issues and assign work
3. RELEASE - Plan release and manage versions
4. IMPLEMENT - Write code following specs
5. CODE-ANALYSIS - Quality and security checks
6. TESTING - Verify functionality (TDD enforced)
7. PUBLISH - Release to customers

See docs/ for detailed workflow documentation.

Support

• Documentation: See docs/ directory for comprehensive guides
• Installation Issues: Check Installation Guide
• Publishing: See Publishing Guide
• Validation: See Audit & Validation Guide
• Commands: Review .cursor/commands/ for command patterns and usage

Contributing

Roadcrew development follows the Roadcrew workflow itself:

1. Analyze requirements in GitHub issues
2. Create implementation epics with scoped issues
3. Implement following TDD pattern
4. Submit quality checks and code reviews
5. Publish to customers via release process

See docs/PUBLISHING.md for the complete publication workflow.

Repository Structure

roadcrew-internal/
├── scripts/                    ← Development and build scripts
│   ├── roadcrew/              ← Compiled roadcrew scripts (37 files)
│   ├── utils/
│   │   ├── roadcrew/          ← Roadcrew utilities: sources + compiled (42 pairs)
│   │   │   ├── *.ts           ← TypeScript sources
│   │   │   ├── *.js           ← Compiled JavaScript
│   │   │   └── *.js.map       ← Source maps
│   │   └── __tests__/         ← Test files
│   ├── publish-distribution.ts ← Publish distribution script (TypeScript)
│   ├── publish-distribution.sh ← Publish distribution script (shell)
│   └── *.ts                   ← Main automation scripts
├── .cursor/commands/           ← Internal Cursor commands (r- prefixed)
├── templates/
│   ├── roadcrew/              ← Roadcrew document templates (26 files)
│   └── *.template.*           ← Customer-facing templates
├── commands/                   ← Cursor commands (source, all tiers)
│   ├── free/                  ← Free tier commands
│   ├── starter/               ← Starter tier commands
│   └── enterprise/            ← Enterprise tier commands
├── dist/                       ← Compiled JavaScript output
│   ├── scripts/
│   │   ├── roadcrew/          ← Compiled roadcrew scripts
│   │   └── utils/
│   │       └── roadcrew/      ← Compiled utilities
│   └── add-template-headers.js
├── context/                    ← Project specifications & documentation
│   ├── specs/                 ← Technical specifications
│   ├── prds/                  ← Product requirements documents
│   ├── brds/                  ← Business requirements documents
│   └── narratives/            ← Implementation narratives
├── milestones/                ← Release planning & roadmap
├── config/                    ← Configuration & schema
│   ├── schema/               ← Prisma schema and documentation
│   └── reports/              ← Analysis and validation reports
├── docs/                       ← Internal development documentation
├── install.cjs                  ← Installation script for customers
└── package.json               ← Dependencies (dev + build)

Folder Organization (Epic #21)

The project uses a clean folder structure to separate Roadcrew-managed code from project code:

Roadcrew Artifacts (installed into customer projects):

• scripts/roadcrew/ - Compiled roadcrew scripts
• scripts/utils/roadcrew/ - Roadcrew utility functions (TypeScript sources + compiled JavaScript)
• templates/roadcrew/ - Roadcrew document templates

Purpose: Keeps Roadcrew dependencies isolated and easy to identify/maintain within customer projects.

Key Workflows

1. Publishing Distribution (Customers Get Updates)

When you update commands, utilities, or templates, publish them to the public roadcrew repo:

# From roadcrew-internal/
bash scripts/publish-distribution.sh

What it does:

• Syncs commands/, dist/, templates/, and root files to ../roadcrew/
• Shows changes with git status --short
• Allows review before committing

To publish AND push to GitHub:

bash scripts/publish-distribution.sh --push

This automatically:

1. Copies all distribution files to the public roadcrew repo
2. Commits changes: "chore: sync distribution from roadcrew-internal"
3. Pushes to GitHub main branch
4. Customers get updates automatically when they update their submodule

2. Development Workflow

Edit files in roadcrew-internal:

- Main scripts: scripts/*.ts
- Roadcrew scripts: scripts/roadcrew/*.js (compiled)
- Roadcrew utilities: scripts/utils/roadcrew/*.ts (sources)
- Commands: commands/
- Templates: templates/roadcrew/
- Documentation: context/, docs/

Build/compile TypeScript:

npm run build  # Compiles scripts/*.ts and scripts/utils/roadcrew/*.ts to dist/

Test locally:

# Test installation script
node install.cjs

# Build and test utilities
npm run build
npm run ensure-built

Publish when ready:

bash scripts/publish-distribution.sh --push

3. Repository Synchronization

Two separate repositories:

| Repository | Purpose | Audience | Files | |-----------|---------|----------|-------| | roadcrew-internal | Development | Tailwind AI team | Everything: source code, specs, build tools | | roadcrew (public) | Distribution | Customers | Only: commands/, dist/, templates/, install.cjs, legal docs |

Sync direction: roadcrew-internal → publish-distribution.sh → roadcrew

Never push directly to the public roadcrew repo from here. Always use publish-distribution.sh to maintain a clean distribution package.

Task Complexity Framework

Roadcrew uses an Objective Task Complexity Framework for classifying development work:

• Four Dimensions: Determinism, Context Breadth, Verification Cost, Domain Knowledge
• Derived Classification: 1-10 score calculated from dimensions
• Assignment Zones: ai-solo, ai-led, ai-assisted, ai-limited

Learn More:

• 📖 Complete Technical Specification - Full system architecture
• 🎯 Classification Guide - How to use TaskProfiles
• 🧪 Training Materials - Before/after examples from codebase
• 🪄 Profile Wizard - Interactive CLI tool (npm run profile-wizard)

Distribution Files Published

These files/directories are copied to the public roadcrew repo:

Directories

• commands/ - Cursor commands
• dist/ - Pre-compiled JavaScript utilities
• templates/ - Document templates (PRD, spec, vision, etc.)

Files

• install.cjs - Installation script for customers
• package.json - Minimal customer-facing version
• setup.sh - One-command setup automation
• README.md - Customer documentation
• LICENSE - Apache 2.0 license
• CLA.md - Contributor License Agreement
• CONTRIBUTING.md - Contribution guidelines
• LICENSE-COMMERCIAL - Commercial license

Development Setup

Prerequisites

• Node.js 18+
• Git
• SSH key configured for GitHub (for push-to-remote operations)

Install Dependencies

npm install

Set Up Pre-commit Hooks (Optional)

# Install pre-commit framework (requires Python)
pip install pre-commit

# Install git hooks
pre-commit install
pre-commit install --hook-type commit-msg

Pre-commit hooks automatically validate code quality before commits. See CONTRIBUTING.md for details.

Run Tests

npm test

Build/Compile (if TypeScript updates)

npm run build

Common Tasks

Add a New Command

1. Create markdown file in commands/free/ or commands/enterprise/
2. Follow template format from existing commands
3. Commit to roadcrew-internal
4. Run bash scripts/publish-distribution.sh --push
5. Customers get the new command next time they update the submodule

Update Utilities/Scripts

1. Edit TypeScript files in scripts/utils/
2. Build: npm run build (compiles to dist/)
3. Commit to roadcrew-internal
4. Run bash scripts/publish-distribution.sh --push
5. Pre-compiled utilities are synced to dist/ in public repo

Update Templates

1. Edit files in templates/
2. Commit to roadcrew-internal
3. Run bash scripts/publish-distribution.sh --push
4. Customers get new templates in their templates/ directory

Fix install.cjs

1. Edit install.cjs in roadcrew-internal
2. Test: node install.cjs in a fresh directory
3. Commit to roadcrew-internal
4. Run bash scripts/publish-distribution.sh --push