Breakdown

A powerful CLI tool for creating AI-optimized development instructions using TypeScript and JSON Schema. Convert markdown requirements into structured prompts for AI development agents.

🚀 Quick Start

Install Breakdown globally using JSR:

deno install --allow-read --allow-write --allow-run --allow-env --allow-net -f --global breakdown jsr:@tettuan/breakdown

Convert your markdown requirements to AI-optimized prompts:

breakdown to project requirements.md -o project_output/
breakdown to issue project_summary.md -o issues_output/
breakdown to task issue.md -o tasks_output/

Overview

Breakdown transforms human-written development requirements into AI-interpretable structured prompts using TypeScript and JSON Schema. It bridges the communication gap between developers and AI systems by providing standardized formats for expressing complex development requirements.

Key Benefits:

• 📝 Convert markdown specifications into structured AI prompts
• 🎯 3-tier breakdown hierarchy: Project → Issue → Task
• 🤖 Optimized for AI development agents (Claude, Cursor, etc.)
• 📊 JSON Schema-based structured output
• 🔧 Flexible output formats (Markdown/JSON/YAML)

📋 Core Commands

Breakdown provides three main command types for different workflow stages:

💡 Usage Examples

Basic Workflow: Requirements → Implementation

Transform unstructured requirements into implementation-ready tasks:

# 1. Convert requirements to project structure
echo "Build a user authentication system" | breakdown summary project -o auth_project.md

# 2. Break down project into issues
breakdown to issue auth_project.md -o issues/

# 3. Convert issues into actionable tasks
breakdown to task issues/user_management.md -o tasks/

Error Analysis & Fix Generation

Generate fix proposals from error logs and defect reports:

# Analyze error logs for project-level issues
tail -100 error.log | breakdown defect project -o project_fixes.md

# Create task-level fixes from bug reports
breakdown defect task --from=bug_report.md -o fix_tasks/

Project Breakdown

breakdown to project <written_project_summary.md> -o <project_dir>

Issue Breakdown

breakdown to issue <project_summary.md|written_issue.md> -o <issue_dir>

Task Breakdown

breakdown to task <issue.md|written_task.md> -o <tasks_dir>

Markdown Summary Generation

Project Summary Generate project overview from unorganized information:

echo "<messy_something>" | breakdown summary project -o <project_summary.md>

Issue Summary Generate issues from task groups:

breakdown summary issue --from=<aggregated_tasks.md> --input=task -o=<issue_markdown_dir>

Task Summary Generate organized tasks from unorganized task information:

breakdown summary task --from=<unorganized_tasks.md> -o=<task_markdown_dir>

Fix Generation from Defect Information

Project Level Defect Analysis

tail -100 "<error_log_file>" | breakdown defect project -o <project_defect.md>

Issue Level Defect Analysis

breakdown defect issue --from=<bug_report.md> -o=<issue_defect_dir>

Task Level Defect Analysis

breakdown defect task --from=<improvement_request.md> -o=<task_defect_dir>

Use Case Patterns

1. From Unorganized Information to Project Implementation

echo "<messy_something>" | breakdown summary project -o <project_summary.md>
breakdown to project <project_summary.md> -o <project_dir>
breakdown to issue <project_summary.md> -o <issue_dir>
breakdown to task <issue.md> -o <tasks_dir>

2. Creating Issues from Task Groups

breakdown summary issue --from=<aggregated_tasks.md> --input=task -o=<issue_markdown_dir>
# Edit generated issues if needed
breakdown to task <issue.md> -o <tasks_dir>

3. Fix Task Generation from Defect Information

tail -100 "<error_log_file>" | breakdown defect project -o <project_defect.md>
breakdown defect issue --from=<project_defect.md> -o=<issue_defect_dir>
breakdown defect task --from=<issue_defect.md> -o=<task_defect_dir>

4. Creating Fix Proposals from Improvement Requests

breakdown defect task --from=<improvement_request.md> -o=<task_defect_dir>

📦 Installation

Global Installation (Recommended)

Install Breakdown globally for system-wide access:

deno install --allow-read --allow-write --allow-run --allow-env --allow-net -f --global breakdown jsr:@tettuan/breakdown

Options explained:

• --allow-read: File reading permissions
• --allow-write: File writing permissions
• --allow-run: Subprocess execution permissions
• --allow-env: Environment variable access permissions
• --allow-net: Network access permissions
• -f: Force overwrite existing installation
• --global: Install globally for system-wide access

Verify Installation

breakdown --help
breakdown --version

Update to Latest Version

deno install --allow-read --allow-write --allow-run --allow-env --allow-net -f --global breakdown jsr:@tettuan/breakdown

Alternative Installation Methods

deno install --allow-read --allow-write --allow-run --allow-env --allow-net -f --root .deno -n breakdown jsr:@tettuan/breakdown
export PATH="$(pwd)/.deno/bin:$PATH"

deno add @tettuan/breakdown

import { runBreakdown } from "@tettuan/breakdown";

const result = await runBreakdown(["to", "project", "input.md", "-o", "output/"]);

mkdir -p .deno/bin
deno compile --allow-read --allow-write --allow-run --allow-env --allow-net -o .deno/bin/breakdown jsr:@tettuan/breakdown

Requirements

• Deno 2.0+ (recommended)
• Permissions: File system access required for reading/writing files

🏗️ Architecture

Breakdown leverages a powerful 4-package architecture for maximum modularity:

• @tettuan/breakdownconfig - Configuration management
• @tettuan/breakdownparams - CLI parameter parsing
• @tettuan/breakdownprompt - Core prompt generation engine
• @tettuan/breakdownlogger - Structured logging

📚 Documentation & Resources

🤝 Contributing

Contributions are welcome! Please check the documentation site for contribution guidelines.

📄 License

Published under the terms specified in the package configuration.