# 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](https://github.com/tailwind-ai/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](docs/INSTALLATION.md) or [Submodule Setup Guide](docs/SUBMODULE-SETUP.md).

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

```bash
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

```bash
# 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

```bash
# 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:

```bash
/update-roadcrew
```

Or manually:
```bash
git submodule update --remote .roadcrew
git add .roadcrew
git commit -m "chore: update Roadcrew"
```

For more information, see [Submodule Setup Guide](docs/SUBMODULE-SETUP.md).

## 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](docs/INSTALLATION.md#troubleshooting)
- **Publishing**: See [Publishing Guide](docs/PUBLISHING.md)
- **Validation**: See [Audit & Validation Guide](docs/AUDIT-GUIDE.md)
- **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:

```bash
# 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
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:**
```bash
npm run build  # Compiles scripts/*.ts and scripts/utils/roadcrew/*.ts to dist/
```

**Test locally:**
```bash
# Test installation script
node install.cjs

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

**Publish when ready:**
```bash
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](#complexity-classification) - Full system architecture
- 🎯 [Classification Guide](#classification-guide) - How to use TaskProfiles
- 🧪 [Training Materials](docs/TASKPROFILE-TRAINING.md) - Before/after examples from codebase
- 🪄 [Profile Wizard](scripts/cli/profile-wizard.ts) - 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
```bash
npm install
```

### Set Up Pre-commit Hooks (Optional)
```bash
# 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](./CONTRIBUTING.md) for details.

### Run Tests
```bash
npm test
```

### Build/Compile (if TypeScript updates)
```bash
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`