epcispec

name: epci:spec description: >- Create comprehensive technical specifications from CDC (Cahier des Charges) or brief output. Decomposes features into 1-2h atomic tasks with 15-30min steps. Generates Markdown specs (index.md + task-XXX.md), machine-readable PRD.json, and Ralph execution artifacts. Uses project-memory for calibration and @decompose-validator for DAG validation. Use when: transforming brainstorm output, writing technical specs, preparing Ralph batch. Triggers: write spec, create specification, spec from brief, decompose feature, technical breakdown. Not for: ideation (use /brainstorm), direct implementation (use /implement). user-invocable: true argument-hint: " [@brief-path | @text-description]" allowed-tools: Read, Write, Glob, Grep, Task, AskUserQuestion

Spec — Technical Specification Generator

Transform CDC/brief documents into executable technical specifications with Ralph-ready artifacts.

Quick Start

/spec auth-oauth                                    # From description
/spec auth-oauth @docs/briefs/auth/brief.md         # From brief file
/spec auth-oauth @"OAuth integration for users"    # From inline description

MANDATORY EXECUTION RULES (READ FIRST):

• 🔴 NEVER generate specs without understanding the source
• 🔴 NEVER skip @decompose-validator before generation
• 🔴 NEVER create circular dependencies in task DAG
• 🔴 NEVER exceed granularity limits (tasks 1-2h, steps 15-30min)
• ✅ ALWAYS start with step-00-init.md
• ✅ ALWAYS follow next_step from each step
• ✅ ALWAYS present breakpoints at phase transitions
• ✅ ALWAYS validate with @decompose-validator before generation
• ⛔ FORBIDDEN generating PRD.json with missing acceptance criteria
• 🔵 YOU ARE A METHODICAL SPECIFICATION WRITER following EPCI discipline
• 💭 FOCUS on one phase at a time, complete before proceeding

EXECUTION PROTOCOLS:

1. Load step-00-init.md
2. Execute current step protocols completely
3. Present breakpoint if specified in step
4. Evaluate next step trigger conditions
5. Proceed to next_step or conditional_next

CONTEXT BOUNDARIES:

• IN scope: Transforming CDC/briefs into specs, task decomposition, Ralph artifacts
• OUT scope: Ideation (use /brainstorm), implementation (use /implement or /quick)

Input Detection

INPUT
├── @docs/briefs/*.md → BRIEF-FIRST workflow
│   └─ Parse CDC sections, extract requirements
├── @"text description" → TEXT workflow
│   └─ Clarify with clarification-engine, then proceed
└── feature-slug only → DISCOVERY workflow
    └─ Search for existing brief, else ask for input

Workflow Overview

┌─────────────────────────────────────────────────────────────────────┐
│                    SPEC WORKFLOW (3 Phases)                          │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  Step 00: INIT                                                       │
│  └─ Parse input, detect source type                                  │
│  └─ Load project context via project-memory                          │
│     └─ If no source → ask for brief/description                      │
│                                                                      │
│  Step 01: ANALYZE & DECOMPOSE                                        │
│  └─ Parse CDC/brief structure                                        │
│  └─ Calculate complexity via complexity-calculator                   │
│  └─ Decompose into tasks (1-2h) with steps (15-30min)                │
│  └─ Build DAG (dependency graph)                                     │
│  └─ Validate with @decompose-validator                               │
│     └─ BREAKPOINT: Decomposition review                              │
│                                                                      │
│  Step 02: GENERATE SPECS                                             │
│  └─ Create docs/specs/{slug}/ directory                              │
│  └─ Generate index.md (orchestrator)                                 │
│  └─ Generate task-XXX.md for each task                               │
│  └─ Generate {slug}.prd.json (machine-readable)                      │
│     └─ BREAKPOINT: Specs review                                      │
│                                                                      │
│  Step 03: GENERATE RALPH                                             │
│  └─ Detect project stack                                             │
│  └─ Create .ralph/{slug}/ directory                                  │
│  └─ Generate PROMPT.md (stack-aware)                                 │
│  └─ Generate MEMORY.md (template)                                    │
│  └─ Generate ralph.sh (runner)                                       │
│  └─ Update .ralph/index.json                                         │
│     └─ BREAKPOINT: Completion summary with routing                   │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘

Steps

Granularity Rules

Task Structure

Each task-XXX.md contains:

• YAML frontmatter (id, title, deps, complexity, effort)
• Objective section
• Acceptance Criteria (Given-When-Then or checklist)
• Steps section (numbered 15-30min steps)
• Files to modify/create
• Test approach

Step Structure

Each step within a task:

• Action verb title
• Expected duration
• Input requirements
• Output deliverable
• Validation criteria

Decision Tree

IF source is brief (@*.md):
  → Parse sections, extract requirements
  → Calculate complexity
  → Proceed to decomposition
ELSE IF source is text (@"..."):
  → Clarify with clarification-engine if needed
  → Convert to structured requirements
  → Proceed to decomposition
ELSE IF no source:
  → Search for existing brief in docs/briefs/{slug}/
  → If found → use it
  → If not found → ask user for input

Step Files

• steps/step-00-init.md — Initialization
• steps/step-01-analyze.md — Analysis & Decomposition
• steps/step-02-generate-specs.md — Specs Generation
• steps/step-03-generate-ralph.md — Ralph Generation

Reference Files

• references/task-format.md — Task file format
• references/prd-schema.md — PRD.json schema
• references/ralph-generation.md — Ralph artifacts guide

Templates

• templates/index.md.template — Index template
• templates/task.md.template — Task template
• templates/prompt.md.template — Ralph PROMPT template

Output Structure

docs/specs/{feature-slug}/
├── index.md                    # Orchestrator (table + Mermaid DAG + context)
├── task-001-{slug}.md          # Task 1 (1-2h, with Steps)
├── task-002-{slug}.md          # Task 2
├── ...
└── {feature-slug}.prd.json     # Machine version (Ralph-ready)

.ralph/{feature-slug}/
├── PROMPT.md                   # Claude Code instructions (stack-aware)
├── MEMORY.md                   # Persistent context (template)
└── ralph.sh                    # Runner script

Shared Components Used

• epci:complexity-calculator — Scope estimation for routing
• epci:project-memory — Velocity calibration, conventions
• epci:clarification-engine — Input clarification if needed
• epci:breakpoint-system — Phase checkpoints
• @decompose-validator — DAG validation

Subagents

Breakpoints

This skill uses these breakpoint types:

• decomposition: Task table + DAG review (Step 01)
• plan-review: Specs preview (Step 02)
• validation: Completion summary with routing (Step 03)

Complexity Routing (at completion)

Error Handling

Constraints

Limitations

This skill does NOT:

• Ideate or explore (use /brainstorm)
• Implement code (use /implement or /quick)
• Debug existing code (use /debug)
• Create new skills (use /factory)
• Execute Ralph batches (use ralph.sh directly)