---
roadcrew_template_name: "generate-module.md"
roadcrew_template_type: "command"
execution_mode: "auto-execute"
roadcrew_template_version: "v1.0"
roadcrew_last_updated: "2025-10-25"
roadcrew_min_version: "1.5.0"
roadcrew_license: "See LICENSE file in .roadcrew folder"
roadcrew_copyright: "Copyright (c) 2025 North Star Holdings, LLC"
spdx_license_identifier: "LicenseRef-RoadcrewLicense-1.0"
---

# generate-module

Intelligently generate new modules and components with proper structure, type annotations, and test-ready stubs.

## Usage

```bash
/generate-module --type class|function|interface|service|component \
                 --template controller|service|handler|middleware \
                 --name MyModule \
                 --path src/modules/
```

## What This Command Does

Creates well-structured modules including:
- **Type Definitions** - TypeScript interfaces and types
- **Implementation Stubs** - Scaffolding with error handling
- **Proper Imports** - Dependencies and internal modules
- **Test-Ready Structure** - Setup for testing
- **Documentation** - JSDoc comments and inline docs

Generated code:
- Follows project conventions and style
- Includes proper type annotations
- Has error handling patterns
- Ready for immediate testing

## Module Types

### 1. Service Class
```typescript
export class MyService {
  constructor() {}
  
  async execute(data: Input): Promise<Output> {
    try {
      // Implementation
      return result;
    } catch (error) {
      throw new Error(`Failed to execute: ${error.message}`);
    }
  }
}
```

### 2. Controller Class
```typescript
export class MyController {
  constructor(private service: MyService) {}
  
  async handle(req, res) {
    try {
      const result = await this.service.execute(req.body);
      res.json(result);
    } catch (error) {
      res.status(500).json({ error: error.message });
    }
  }
}
```

### 3. Utility Function
```typescript
/**
 * Process input data
 * @param input - Input data to process
 * @returns Processed result
 * @throws Error if input invalid
 */
export function processData(input: unknown): ProcessedData {
  if (!input) {
    throw new Error('Input is required');
  }
  
  // Implementation
  return result;
}
```

### 4. Handler Middleware
```typescript
export async function handleRequest(req, res, next) {
  try {
    // Middleware logic
    next();
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
}
```

## Generation Process

### Phase 1: Setup
1. Detect project structure from tech-stack.md
2. Read existing code patterns
3. Determine naming conventions

### Phase 2: Generation
1. Create TypeScript/JavaScript file with:
   - Proper imports (based on template)
   - Class/function definition
   - Type annotations
   - Error handling
   - JSDoc documentation

2. Create companion test file with:
   - Test imports
   - Describe block
   - Setup/teardown
   - Test stubs for each public method

### Phase 3: Output
- Create files in specified path
- Report file locations
- Show test commands

## Output Format

```bash
$ /generate-module --type service --template service --name IssueParser --path src/services/

🏗️  Module Generator: roadcrew-internal

Module Type: Service Class
Template: Service
Location: src/services/issue-parser.ts

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ FILES CREATED
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[+] src/services/issue-parser.ts (142 lines)
    - IssueParser class
    - parse() method
    - validate() method

[+] tests/services/issue-parser.test.ts (89 lines)
    - Test suite setup
    - Test stubs for all methods

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📝 NEXT STEPS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

1. Review generated code:
   - Check imports and dependencies
   - Verify type annotations
   - Adjust to project specifics

2. Write tests:
   npm test -- tests/services/issue-parser.test.ts

3. Implement logic:
   - Replace method stubs with actual code
   - Run tests iteratively (TDD)
```

## Flags & Options

```bash
--type class|function|interface|service|component    # Module type
--template pattern                                    # Template pattern
--name ModuleName                                     # Module name
--path src/modules/                                   # Output path
--with-tests                                          # Generate test file
--with-docs                                           # Add detailed JSDoc
--no-files                                            # Dry-run (show what would create)
```

## Integration Points

Used by other commands:
- `/implement-issue` - Generate modules when implementing new features
- `/implement-epic` - Generate multiple modules for epic implementation
- `/autopilot` - Auto-generate modules based on epic requirements

## When to Use

- Creating new service/controller classes
- Adding utility functions
- Generating interface definitions
- Starting new feature modules
- Scaffold and test with TDD approach