# [INFRASTRUCTURE] Create /create-command for AI-guided command generation

## Enhancement: Create /create-command

### Purpose
Automate command creation following Roadcrew principles: minimize AI command text, maximize script usage, ensure consistent structure and quality.

### Context
Currently, command creation is manual and inconsistent. Commands range from lightweight orchestrators (calling scripts) to monolithic AI-heavy implementations. Need systematic approach to:
1. Enforce script-first philosophy
2. Generate consistent command structure
3. Ask clarifying questions before generating
4. Create supporting scripts automatically
5. Ensure proper tier placement and documentation

### What This Command Does

**User Workflow:**
```bash
/create-command new-command-name

<Description of what the command should do>
```

**Command AI Behavior:**
1. Parse command name and description
2. Ask clarifying questions to understand requirements
3. Identify required scripts vs inline logic
4. Determine command tier (FREE/STARTER/ENTERPRISE)
5. Identify parameters and flags
6. Generate command file with proper structure
7. Generate supporting scripts (if needed)
8. Create unit tests
9. Output summary and next steps

### Clarifying Questions Framework

Based on description, ask relevant questions:

**Analysis Questions:**
- What codebase/repository will this command analyze?
- What specific patterns or metrics should it detect?
- Should it support --repo flag for external repos?
- What should the output look like (report, files, console)?

**Creation Questions:**
- Should this command generate code, configuration, or documentation?
- What frameworks/languages will generated code target?
- Should output be committed to repo or shown for review?
- Are there existing commands this should build on?

**Automation Questions:**
- Can this command be fully automated or does it need user approval steps?
- What validation/checks should run before/after?
- Should it support batch processing or single-item focus?
- Are there prerequisite checks needed?

**Scope Questions:**
- Should this support multiple repositories/projects?
- Is this a single-repo (FREE), monorepo (STARTER), or multi-repo (ENTERPRISE) command?
- Should it integrate with GitHub issues/PRs?
- Does this fit an existing use case pattern (ANALYSIS, PLANNING, RELEASE, IMPLEMENT, CODE-ANALYSIS, TESTING, PUBLISH)?

### Decision Framework

**Tier Determination:**
- FREE: Single repo, no external coordination, local-only
- STARTER: Monorepo, optional cloud coordination
- ENTERPRISE: Multi-repo, required cloud coordination

**Script Strategy:**
- Identify extractable logic → create dedicated scripts
- Keep orchestration logic in command
- Command text should be 30-50% of total tokens
- Scripts should be 70% of logic

**Structure Template:**
```markdown
# [Command Title]

[One-line description]

## What This Command Does

[Bulleted workflow]

## Usage

[When to run + examples with flags]

## Parameters

[Optional/required flags with descriptions]

## Process

[Step-by-step breakdown with pre-flight checks]

## Scripts Called

[List of supporting scripts with purposes]

## Related Commands

[Links to similar commands]
```

### Implementation Details

**Phase 1: Requirement Gathering**
- Parse initial command name and description
- Ask 3-5 clarifying questions based on description content
- User provides answers
- Generate summary of requirements
- Confirm with user before proceeding

**Phase 2: Architecture Analysis**
- Identify use case pattern (ANALYSIS, PLANNING, RELEASE, IMPLEMENT, CODE-ANALYSIS, TESTING, PUBLISH)
- Determine tier based on repo scope
- Identify extractable scripts
- Map to existing scripts/patterns where possible
- Suggest reuse opportunities

**Phase 3: Generate Command File**
- Create proper frontmatter (template metadata)
- Generate command structure sections
- Write usage examples with flags
- Document parameters
- Add pre-flight checks
- Include script references
- Link related commands
- Add copyright/license info

**Phase 4: Generate Supporting Scripts**
- Create TypeScript scripts for extracted logic
- Add proper JSDoc comments
- Create unit test stubs
- Place in scripts/utils/roadcrew/

**Phase 5: Generate Tests**
- Create command test stub
- Create script test stubs
- Output test execution guide

### Key Requirements

**Script-First Philosophy:**
- ✅ Extract all non-orchestration logic to scripts
- ✅ Command text should be lean (50-70% smaller than monolithic)
- ✅ Scripts must be distributable via dist branch
- ✅ Reuse existing scripts wherever possible

**Consistency:**
- ✅ All commands follow same structure and frontmatter
- ✅ All commands have consistent parameter handling
- ✅ All commands link to related commands
- ✅ All commands include pre-flight checks

**Quality:**
- ✅ Commands include decision points and clarifying questions
- ✅ Commands have comprehensive examples
- ✅ Commands list all scripts called with purposes
- ✅ Commands include troubleshooting section

**Documentation:**
- ✅ Clear purpose statement
- ✅ Usage guidelines (when to run)
- ✅ Step-by-step process
- ✅ Parameter documentation
- ✅ Script dependencies listed

### Decision Points

**Decision 1: Should /create-command be interactive or batch?**
- Option A: Fully interactive (ask all questions in conversation)
- Option B: Mixed (ask some, then generate partial, then ask more)
- Option C: Template-based (provide template structure, fill in)
- **Recommendation: Option A** - Interactive provides best UX for command design

**Decision 2: Should generated commands use cursor native or scripts?**
- Option A: Prefer cursor native (@-references, built-in abilities)
- Option B: Prefer TypeScript scripts (reusable, versionable)
- Option C: Hybrid (use native for simple checks, scripts for complex logic)
- **Recommendation: Option C** - Hybrid approach balances simplicity and reusability

**Decision 3: Should it auto-create scripts or suggest?**
- Option A: Auto-create scripts with code templates
- Option B: Suggest scripts, user confirms before creating
- Option C: Generate script stubs (empty shells) for user to implement
- **Recommendation: Option B** - Balance automation with user control

**Decision 4: Where should generated commands go?**
- Option A: Create in appropriate tier folder (free/, starter/, enterprise/)
- Option B: Create in temp location, user moves after review
- Option C: Create in new pattern folder (e.g., analysis/, release-management/)
- **Recommendation: Option A** - Proper organization from start

**Decision 5: Should it generate tests automatically?**
- Option A: Generate full unit + integration tests
- Option B: Generate test stubs (empty test files)
- Option C: Generate test templates only
- **Recommendation: Option B** - Stubs with guidance for user to implement

### Acceptance Criteria

- [ ] /create-command command created and functional
- [ ] Interactive clarifying question framework working
- [ ] Correctly identifies use case patterns
- [ ] Correctly determines tier based on requirements
- [ ] Generates valid command files with proper frontmatter
- [ ] Identifies extractable logic → suggests scripts
- [ ] Auto-creates suggested scripts (with user approval)
- [ ] Generates test stubs and test guide
- [ ] Output summary shows:
    - Generated command file location
    - Generated script files (if any)
    - Test stubs created
    - Next steps for user
    - Links to related commands
- [ ] All generated commands follow Roadcrew structure
- [ ] All generated scripts are distributable
- [ ] Unit tests for /create-command itself
- [ ] Documentation for /create-command

### Success Metrics

- ✅ New commands can be created in <5 minutes
- ✅ Script extraction happens automatically
- ✅ Generated commands are production-ready
- ✅ Generated scripts follow project standards
- ✅ 70% reduction in manual command creation work
- ✅ Commands automatically placed in correct tiers

### Example Scenarios

**Scenario 1: Lightweight Orchestrator**
```
User: /create-command validate-pr
      Check PR for code quality, tests, and template compliance

AI asks:
  - What should this validate? (code quality, tests, templates, all?)
  - Should it check GitHub templates or local templates?
  - Single repo or multi-repo support?
  - Should it auto-fix issues or just report?
  - Tier: STARTER (single repo)
  - Result: Lean command calling 3 scripts (validator, linter, checker)
```

**Scenario 2: Analysis Command**
```
User: /create-command detect-architecture
      Analyze code structure and suggest architectural improvements

AI asks:
  - What languages/frameworks to analyze?
  - What architectural patterns to look for?
  - Output format (report file, JSON, console)?
  - Should it compare to standards or just analyze?
  - Tier: STARTER (single repo analysis)
  - Result: Command calling architecture-analyzer script + reporting script
```

**Scenario 3: Multi-Repo Command**
```
User: /create-command sync-monorepo-versions
      Keep all workspace package versions consistent

AI asks:
  - How to detect version mismatches?
  - Should it auto-fix or report only?
  - What repos/workspaces included?
  - Requires GitHub coordination?
  - Tier: ENTERPRISE (multi-repo)
  - Result: Command with multi-repo support + version-sync script
```

### Related Work

- Roadcrew command structure (all commands in commands/roadcrew/)
- Script organization (scripts/utils/roadcrew/)
- Pattern definitions (COMMAND-USE-CASE-PATTERNS.md)
- Freemium principles (FREEMIUM-PRINCIPLES.md)
- Command decomposition (COMMAND-DECOMPOSITION-ANALYSIS.md)

### Implementation Notes

**Command Should:**
- Ask questions that reveal user intent
- Suggest patterns/scripts based on answers
- Show reasoning for tier placement
- Explain why scripts are extracted
- Provide clear next steps
- Generate valid, testable output

**Command Should NOT:**
- Generate monolithic AI-heavy commands
- Create scripts without user awareness
- Skip tier determination
- Miss existing related commands
- Generate untestable code

### Rollout

1. Create /create-command infrastructure command (FREE tier)
2. Use it to create new commands going forward
3. Gradually refactor existing commands using it
4. Iterate on questions based on feedback

### Ties To Product Goals

This command directly supports:
- ✅ **Minimize AI:** By enforcing script extraction
- ✅ **Maximize Scripts:** By identifying reuse opportunities
- ✅ **Reduce Tokens:** By generating lean commands (30-50% smaller)
- ✅ **Consistency:** By enforcing same structure across all commands
- ✅ **Quality:** By automating best practices
- ✅ **User Freedom:** By making command creation self-service

---

**Labels:** enhancement, infrastructure, command-generation, automation

**Type:** Enhancement

**Priority:** High (foundational for command consistency)