---
roadcrew_template_name: "create-spec.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"
---

# create-spec

<!-- Usage: /create-spec [path/to/source-document.md] [--output path/to/output-spec.md] -->

You are transforming a source document (BRD, PRD, or narrative spec) into a ruthlessly concise, AI-parseable Technical Specification following `templates/spec.template.md`.

**Input Documents:** BRDs, PRDs, existing specs, strategy documents
**Output:** Structured spec optimized for AI parsing and developer velocity
**Template:** `templates/spec.template.md`

**Core Principles:**
1. **Atomic over narrative** - bullets and tables, not paragraphs
2. **Strict length limits** - every field has max words/bullets
3. **Downstream awareness** - structure maps 1:1 to enhancement/epic/release templates
4. **Zero duplication** - reference PRD/BRD, don't repeat "what/why"
5. **Deep linkable** - every epic/issue has anchor for precise linking

---

## WORKFLOW

### 0. PRE-FLIGHT CHECKS

**Read required context:**
- Source document (provided by user)
- `templates/spec.template.md` (the output format)
- `templates/enhancement.template.md` (downstream requirements)
- `templates/epic.template.md` (downstream requirements)
- `templates/release.template.md` (downstream requirements)
- `.cursor/commands/implement-epic.md` (automation requirements)

**Validate source document:**
- Contains technical details (not just vision/strategy)
- Has identifiable requirements, architecture, or implementation details
- If pure BRD/vision: STOP and recommend creating PRD first
- If PRD: Good - extract technical details and create spec
- If existing spec: Good - reformat to new template structure

### 1. CHECK EXISTING OUTPUT FORMAT (NEW STEP)

**Predict output path:**
```
If user provides --output flag: Use that path
If not: Predict path as context/specs/[feature-id]-spec.md
```

**If output file already exists:**
```bash
# Check if file exists
if [ -f "$OUTPUT_PATH" ]; then
  echo "Checking existing spec format..."
  
  # Read type from frontmatter
  TYPE=$(head -20 "$OUTPUT_PATH" | grep "^type:" | sed 's/.*: //')
  VERSION=$(head -20 "$OUTPUT_PATH" | grep "^version:" | sed 's/.*: //')
  
  if [ "$TYPE" = "spec" ]; then
    echo "✓ Output file is already a properly formatted spec (v$VERSION)"
    echo ""
    echo "Options:"
    echo "1. Keep existing spec (skip transformation)"
    echo "2. Overwrite with new spec (from source document)"
    echo "3. Cancel"
    echo ""
    read -p "Choose [1/2/3]: " choice
    
    if [ "$choice" = "1" ]; then
      echo "Skipping transformation. Spec already up-to-date."
      exit 0
    elif [ "$choice" = "3" ]; then
      echo "Cancelled."
      exit 0
    fi
    # choice 2 continues to transformation
  else
    echo "⚠️  Output file exists but is NOT a spec (type: $TYPE)"
    echo "This will be overwritten. Proceed? (yes/no)"
    read -p "> " confirm
    if [ "$confirm" != "yes" ]; then
      exit 0
    fi
  fi
fi
```

**If output doesn't exist:**
```
Continue to transformation (new spec will be created)
```

### 2. EXTRACT METADATA

**From source document, extract:**
- Feature name (if not clear, derive from title)
- Feature ID (kebab-case: `feature-name`)
- Status (Draft by default)
- Version (1.0 by default)
- Related PRD path (if mentioned or can infer)
- Related Epic (if mentioned)
- Creation date (today if new, original date if reformatting)

**Populate YAML frontmatter:**
```yaml
---
type: spec
feature: [Feature Name]
feature_id: [feature-id]
status: Draft
version: 1.0
related_prd: ../prds/[feature-id]-prd.md
epic: [Epic link or TBD]
created: 2025-10-24
updated: 2025-10-24
---
```

### 3. CREATE PRD → SPEC MAPPING TABLE

**If source is a PRD:**
- Extract 4-6 key requirements from PRD
- Map each requirement to a future spec section (predict where it will be satisfied)

**If source is an existing spec or BRD:**
- Extract 4-6 key deliverables/outcomes
- Map each to a spec section

**Format:**
```markdown
| PRD Requirement  | Satisfied In Spec Section |
| ---------------- | ------------------------ |
| R1: [Brief]      | See: 2.1.1               |
| R2: [Brief]      | See: 3.2                 |
```

**Rules:**
- Max 6 requirements
- Each requirement: ≤15 words
- Section references must match spec structure (2.1.1, 3.2, 4.1, etc.)

### 4. TECHNICAL REQUIREMENTS

#### 4.1 Functional Requirements (max 6 bullets)
**Extract from source:**
- Look for: features, capabilities, behaviors, outputs
- Convert narrative to bullet points
- Each bullet: ≤20 words
- Must map 1:1 to PRD requirements (if PRD exists)

**Example:**
```markdown
- Install script creates project directories and copies commands
- Mode detection identifies submodule/multi-repo/template deployment
- License validation gates premium features via API key check
```

#### 4.2 Non-Functional Requirements (≤20 words each)
**Extract or infer:**
- Performance: Speed, throughput, latency targets
- Security: Auth, encryption, data protection
- Reliability: Uptime, error handling, recovery
- Scalability: Growth limits, resource usage

**If not in source:** Use reasonable defaults based on feature type

**Example:**
```markdown
- **Performance:** Install completes in <10 seconds; command resolution <100ms
- **Security:** API keys stored in env vars only; never committed to git
- **Reliability:** Install script idempotent; safe to re-run without data loss
- **Scalability:** Supports repos up to 100k files; unlimited submodule updates
```

#### 4.3 Out of Scope (3 bullets max, ≤12 words each)
**Extract from source or infer:**
- Look for: "future work", "not included", "deferred"
- Limit to 3 most important exclusions

### 5. DESIGN OVERVIEW (≤100 words)

**Synthesize from source into single paragraph:**
- Core technical solution
- Major system changes
- Key architectural decisions
- NO rationale, NO "what/why" (that's in PRD)

**Structure:** "This spec implements [X] by [approach]. The system changes include [changes]. [Key decision] enables [capability]."

### 6. ARCHITECTURE & IMPLEMENTATION

#### 6.1 New/Modified Services (bullets, each ≤20 words)
**Extract from source:**
- New services, components, modules, scripts
- Modified existing systems
- Format: `**Service:** [Name] – [Brief change]`

#### 6.2 Data Model Changes (table)
**Extract from source:**
- New database tables, fields, schemas
- Modified existing data structures
- If Prisma/SQL schemas in source: preserve structure
- If none: Note "No data model changes"

#### 6.3 API Changes (table)
**Extract from source:**
- New endpoints, modified endpoints
- Method, endpoint, purpose, notes
- If none: Note "No API changes"

#### 6.4 Env/Config (table)
**Extract from source:**
- New environment variables
- Config files, feature flags
- Variable name, default, description, required (Y/N)

### 7. EXECUTION PLAN & ISSUES

#### 7.1 Implementation Plan (≤60 words each phase)
**Extract from source or synthesize:**
- Break into 3-5 phases
- Each phase: clear objective, key deliverables
- Phases should map to epics (if multi-epic feature)

#### 7.2 Issues (reference anchors)
**Extract from source or synthesize:**
- List each implementation issue
- Format: `[Issue {{EPIC}}.N](#issue-{{EPIC}}-N): [Brief]`
- These will be detailed in Section 8

#### 7.3 Risks & Mitigations (table)
**Extract from source:**
- Technical risks only (not business/product risks)
- 3-5 key risks with concrete mitigations

### 8. TESTING & VALIDATION

#### 8.1 Acceptance Criteria (1 line each, pass/fail)
**Extract from source or synthesize:**
- Technical validation points
- Must be testable, binary (pass/fail)
- Format: Simple bullet statements

#### 8.2 Test Plan (≤100 words OR checklist)
**Extract from source or create:**
- Testing approach (unit, integration, e2e)
- Key test scenarios
- Manual testing steps if needed

### 9. ISSUE BREAKDOWN (CRITICAL - DOWNSTREAM MAPPING)

**This section feeds directly into `enhancement.template.md` and `implement-epic.md`**

For each issue:

```markdown
### Issue {{EPIC}}.N: {{ISSUE_TITLE}} {#issue-{{EPIC}}-N}
- **Overview:** [≤50 words, AI-parseable for enhancement.template.md]
- **Accepts:** [≤5 bullets, pass/fail, ≤12 words each, maps to enhancement.template.md]
- **Tech Approach:** [≤6 bullets, maps to enhancement.template.md Technical Implementation]
- **Files/Components:** [List of files/components to modify]
- **Dependencies:** [Issue numbers this depends on: #N, #M or "None"]
- **Classification:** [1-10 scale for TOC routing]
- **Size/Complexity:** [S/M/L]/[S/M/L] (effort/technical complexity)
```

**CRITICAL MAPPING RULES:**

**Overview (≤50 words):**
- Becomes `enhancement.template.md` "Overview & User Story"
- Should be clear enough to stand alone
- Can use "As a [role], I want to [action], so that [benefit]" format when applicable

**Accepts (≤5 bullets, ≤12 words each):**
- Becomes `enhancement.template.md` "Acceptance Criteria"
- Must be pass/fail testable
- Can use "Given/When/Then" format when helpful

**Tech Approach (≤6 bullets):**
- Becomes `enhancement.template.md` "Technical Implementation"
- Should list: files to modify, key functions/components, implementation approach

**Dependencies:**
- Must be explicit issue numbers: `#77, #78` or `"None"`
- Used by `implement-epic.md` for dependency ordering
- If circular dependencies detected, break into separate epics

**Classification (1-10 scale):**
- Used by `scope-release.md` for TOC routing and auto-assignment
- 1-3: 🟢 ai-solo (AI-autonomous)
- 4-6: 🟡 ai-led (AI-led, human validates)
- 7-8: 🟠 ai-assisted (Human-led, AI assists)
- 9-10: 🔴 ai-limited (Human-owned)

**Size/Complexity:**
- Size: S (1-2 hrs), M (3-5 hrs), L (6-8 hrs)
- Complexity: S (simple), M (moderate), L (complex)
- Appears in `enhancement.template.md` title

**How to synthesize from source:**
1. Look for explicit issue descriptions in source
2. If source has "implementation steps" or "tasks" → convert to issues
3. If source is narrative → decompose into logical units of work
4. Each issue should be independently implementable (with dependencies)
5. Aim for 5-10 issues per epic (if >10, suggest splitting epic)

### 10. EDITOR INSTRUCTIONS

**Always include at bottom:**
```markdown
## 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-{{EPIC}}-{{N}}`
- Classification (1-10) drives assignment in scope-release.
- Any deviation, ambiguity, or overrun invalidates this doc for automation.
```

### 11. VALIDATION & OUTPUT

**Before outputting, validate:**
- [ ] All length limits respected (no field exceeds max)
- [ ] Issue breakdowns have all 7 required fields
- [ ] Dependencies are explicit issue numbers or "None"
- [ ] Classifications are 1-10 scale
- [ ] Anchors follow format: `{#issue-{{EPIC}}-N}`
- [ ] Tables are properly formatted
- [ ] PRD mapping table references actual spec sections

**Output format:**
- If `--output` flag provided: Write to that path
- If no flag: Write to `context/specs/[feature-id]-spec.md`
- Display summary: "Created spec with N issues, M epics, [feature-id]-spec.md"

---

## EXAMPLE TRANSFORMATIONS

### Input: BRD (Monetization Strategy)
**Approach:**
- Extract: Premium features, pricing tiers, gating mechanisms
- Synthesize: Technical requirements for license validation, API integration
- Create issues: License validator, API client, feature gates, usage tracking

### Input: PRD (Submodule Isolation)
**Approach:**
- Extract: Deployment modes, installation process, command behavior
- Map requirements to spec sections
- Create issues: install.js, mode detection, path resolution, license validation

### Input: Existing Spec (Submodule Isolation)
**Approach:**
- Reformat to new template structure
- Condense narrative sections to bullets/tables
- Add strict length limits
- Add classification and size/complexity to issues
- Add explicit dependencies

---

## COST OPTIMIZATION

**Concise output patterns:**
- Tables over paragraphs
- Bullets over prose
- Anchors over repeated text
- "See: [section]" over duplication

**Expected savings:** 60-70% fewer tokens vs narrative specs

---

## GUARDRAILS

1. **Length Enforcement:**
   - If field exceeds limit: Truncate intelligently and warn
   - Better to be concise than verbose

2. **Dependency Validation:**
   - Check for circular dependencies
   - Warn if detected, suggest resolution

3. **Classification Accuracy:**
   - If unsure: Default to middle (5-6 range)
   - Prefer higher classification for complex/risky work

4. **Issue Granularity:**
   - Too large (>8 hrs): Suggest splitting
   - Too small (<1 hr): Suggest combining
   - Target: 2-5 hrs per issue

---

**Behavior:**
- If invoked with file path (e.g., `/create-spec context/prds/feature-prd.md`), read that file and proceed
- If no path provided, ask user for source document path
- If `--output` flag provided, write to that path
- Always validate output against template structure before presenting