prd2fizzy

Convert Product Requirements Documents (PRDs) to Fizzy cards using Claude AI.

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  PRD.md     │────▶│  Claude CLI │────▶│  JSON Tasks │────▶│ Fizzy Cards │
│  (input)    │     │  (analyze)  │     │  (parsed)   │     │  (output)   │
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘

Dependencies

Required

Tool	Description	Installation
Claude CLI	Anthropic's CLI tool	npm install -g @anthropic-ai/claude-code
Fizzy CLI	Fizzy board management	See releases
jq	JSON processor	brew install jq (macOS) or apt install jq (Linux)

Optional (for HTML formatting)

Tool	Description	Installation
cmark	CommonMark parser (recommended)	brew install cmark (macOS) or apt install cmark (Linux)
pandoc	Universal document converter	brew install pandoc (macOS) or apt install pandoc (Linux)

If neither cmark nor pandoc is installed, card descriptions will be created as plain text (markdown syntax visible but not rendered).

Setup

1. Ensure all required dependencies are installed
2. Authenticate with Fizzy:

   fizzy auth login YOUR_TOKEN

3. Optionally set your default Fizzy account:

   export FIZZY_ACCOUNT=your_account_id

Usage

prd2fizzy --file PRD.md --board BOARD_ID [OPTIONS]

Required Arguments

Argument	Short	Description
--file	-f	Path to PRD markdown file
--board	-b	Fizzy board ID

Options

Option	Short	Description	Default
--account	-a	Fizzy account ID	$FIZZY_ACCOUNT
--column	-c	Target column ID	Triage
--model	-m	Claude model to use	Claude CLI default
--dry-run		Preview without creating cards	false
--verbose	-v	Show detailed output	false
--help	-h	Show help

Examples

# Basic usage
prd2fizzy -f ./specs/feature.md -b 12345

# Preview what cards would be created
prd2fizzy -f PRD.md -b 12345 --dry-run

# Verbose output with specific model
prd2fizzy -f PRD.md -b 12345 --verbose --model claude-sonnet-4-20250514

# Specify account and target column
prd2fizzy -f PRD.md -b 12345 -a my_account -c column_id

How It Works

1. Reads your PRD - Parses the markdown file
2. Analyzes with Claude - Sends the PRD to Claude with a structured prompt
3. Extracts phases and tasks - Claude returns JSON with phases and tasks
4. Creates Fizzy cards - Each task becomes a card with:
   • Title: [Phase N] Task title
   • Description: Phase context, task details, and acceptance criteria (as HTML if converter available)

Output Format

Cards are created with titles like:

• [Phase 1] Create dashboard route and controller
• [Phase 2] Implement project count widget
• [Phase 3] Add quick action buttons

Each card description includes:

• Phase name for context
• Detailed task description
• Acceptance criteria as a checklist

Exit Codes

Code	Meaning
0	Success
1	General error / Claude error
2	Invalid arguments
3	Missing dependencies

License

MIT