CFN Epic Parser

Overview

The cfn-epic-parser skill converts natural language epic documents written in markdown format into structured JSON configurations suitable for execution in either MDAP or CFN Loop modes.

Pipeline context: The maxTaskSize: 50, consensusThreshold: 0.90, and gateThreshold: 0.95 values below are CLI-mode / MDAP defaults, not the only execution path. The current default execution path is cfn-loop-task (task mode, no Redis). Planning artifacts now come from cfn-megaplan, which emits planning/*.md (RESEARCH, SPEC, DECISIONS, DATA, ARCH, UX, DESIGN, TEST, OPS, MEGAPLAN); this parser consumes those markdown epics.

Usage

Basic Usage

# Parse with auto-detected mode
$HOME/.claude/skills/cfn-epic-parser/parse.sh planning/my-epic.md

# Force MDAP mode
$HOME/.claude/skills/cfn-epic-parser/parse.sh planning/my-epic.md --mode mdap

# Force CFN Loop mode with output file
$HOME/.claude/skills/cfn-epic-parser/parse.sh planning/my-epic.md --mode cfn-loop --output epic-config.json

# Validate epic structure without generating output
$HOME/.claude/skills/cfn-epic-parser/parse.sh planning/my-epic.md --validate

# Enable verbose logging
$HOME/.claude/skills/cfn-epic-parser/parse.sh planning/my-epic.md --verbose

Command Line Options

• <input.md>: Path to the epic markdown file to parse (required)
• -o, --output <file>: Output JSON file path (default: stdout)
• -m, --mode <mode>: Execution mode: mdap, cfn-loop, or auto (default: auto)
• -v, --validate: Validate epic structure without generating output
• -V, --verbose: Enable verbose logging
• -h, --help: Show help message

Mode Descriptions

• auto: Automatically detect mode based on epic content
  • Detects CFN Loop mode if multiple phases are defined
  • Defaults to MDAP mode for single-phase epics
• mdap: Generate MDAP-compatible configuration for atomic task execution
  • Creates task-based structure with maxTaskSize of 50 lines
  • Atomic execution with pre-loaded context injection
• cfn-loop: Generate CFN Loop configuration for phased execution
  • Creates phase-based structure with dependencies
  • Configures consensus and gate thresholds for validation

Epic Document Format

The parser expects markdown files with the following structure:

Required Sections

# Epic Title

**Epic ID**: `unique-epic-identifier`
**Status**: [Not Started | In Progress | Completed]
**Estimated Duration**: [X weeks]
**Owner**: [Team or individual]
**Priority**: [Low | Medium | High]

## Epic Description

Detailed description of the epic goals and scope.

## Strategic Goals

1. Goal one description
2. Goal two description
3. ...

## Phases (for CFN Loop)

### Phase 1: Phase Name
**Status**: Not Started
**Duration**: X weeks
**Dependencies**: [None | Phase X, Phase Y]

Description of phase goals.

### Phase 2: Phase Name
...

Optional Fields

• Agents: Number of agents involved (e.g., Agents: 50)
• File: Reference to phase file (e.g., File: planning/phase-1.md)
• Deliverables: List of expected deliverables
• Acceptance Criteria: Checklist of completion criteria

Output Format

MDAP Mode Output

{
  "executionMode": "mdap",
  "metadata": {
    "epicId": "unique-identifier",
    "name": "Epic Title",
    "description": "Epic description",
    "status": "not_started",
    "priority": "high",
    "estimatedDuration": "10 weeks",
    "owner": "Team Name"
  },
  "goals": ["Goal 1", "Goal 2", "Goal 3"],
  "tasks": [],
  "configuration": {
    "maxTaskSize": 50,
    "atomicExecution": true,
    "contextInjection": "pre-loaded"
  }
  // maxTaskSize 50 is the MDAP default; cfn-loop-task is the default execution path.
}

CFN Loop Mode Output

{
  "executionMode": "cfn-loop",
  "metadata": { ... },
  "phases": [
    {
      "phaseId": "phase-1",
      "name": "Phase Name",
      "description": "Phase description",
      "status": "not_started",
      "estimatedDuration": "5 weeks",
      "dependencies": []
    },
    ...
  ],
  "goals": ["Goal 1", "Goal 2", "Goal 3"],
  "configuration": {
    "loopMode": "standard",
    "consensusThreshold": 0.90,
    "gateThreshold": 0.95
  }
}

Testing

Run the test suite to verify parser functionality:

$HOME/.claude/skills/cfn-epic-parser/test-parser.sh

The test suite validates:

• Help output and error handling
• Metadata extraction (ID, status, priority, etc.)
• Phase parsing and dependency tracking
• Goal extraction from Strategic Goals section
• Mode auto-detection based on content
• Validation of epic structure
• File output generation

Dependencies

• jq: Required for JSON processing
  • Ubuntu/Debian: sudo apt-get install jq
  • macOS: brew install jq

Examples

Parse Marketing Epic

$HOME/.claude/skills/cfn-epic-parser/parse.sh \
  planning/global/marketing/EPIC_OVERVIEW.md \
  --mode cfn-loop \
  --output marketing-epic-config.json

Validate Epic Structure

$HOME/.claude/skills/cfn-epic-parser/parse.sh \
  planning/my-new-epic.md \
  --validate --verbose

Generate MDAP Configuration

$HOME/.claude/skills/cfn-epic-parser/parse.sh \
  planning/simple-feature-epic.md \
  --mode mdap \
  --output simple-feature-config.json

Error Handling

The parser provides clear error messages for:

• Missing input files
• Invalid execution modes
• Malformed epic structure
• Missing required fields
• JSON validation failures

Integration with CFN Workflows

The generated JSON configurations can be used by:

• CFN Loop orchestrator for phased execution
• MDAP decomposer for atomic task generation
• Epic management tools for tracking progress
• Validation agents for structure compliance

Best Practices

1. Consistent Epic IDs: Use lowercase with hyphens (e.g., user-authentication-v2)
2. Clear Phase Dependencies: Explicitly list dependencies in each phase
3. Specific Goals: Use numbered lists for strategic goals
4. Descriptive Phases: Include duration and clear deliverables
5. Status Tracking: Keep status updated for accurate reporting