cfn-epic-parser

name	cfn-epic-parser
description	Convert markdown epic documents into structured JSON configs for MDAP or CFN Loop execution. Use when parsing epic documents, validating epic structure, or generating execution configs from planning docs.
version	1.0.0
tags	["epic","parser","mdap","cfn-loop","planning"]
status	production

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
./.claude/skills/cfn-epic-parser/parse.sh planning/my-epic.md

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

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

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

# Enable verbose logging
./.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:

./.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

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

Validate Epic Structure

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

Generate MDAP Configuration

./.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