@gongfu/workflow-cli

AI-powered workflow management CLI for developers. A unified tool that combines task management, format conversion, API services, and AI integration to streamline your development workflow.

⚠️ 重要说明：任务存储架构

从 v0.3.0 开始，所有任务统一存储在 .workflow/tasks.json 文件中。

• ✅ 使用 tasks.json：所有任务数据的单一事实来源
• ❌ 废弃 task-state.json：不再使用，如果存在可以安全删除
• 🔄 状态管理：任务状态通过 status 字段管理（todo, in_progress, done 等）
• 📌 当前任务：status === 'in_progress' 的任务即为当前任务

Features

• 🤖 AI-Powered Task Management - Intelligent task prioritization and recommendations
• 🔄 Universal Format Support - Seamlessly work with YAML (Gongfu) and JSON (Workflow) formats
• 🌐 RESTful API + SSE - Built-in API server with real-time event streaming
• 🖥️ Web UI Integration - One-command launch of web interface with auto-discovery
• 🤝 MCP Protocol Support - Direct integration with Claude Desktop and AI tools
• 🧠 Context Engineering - Advanced context building, optimization, and compression
• 📋 Dynamic Task Syncing - Automatically sync with your project's TODO files
• 🔄 Smart Workflow Templates - 10+ pre-defined workflows with intelligent selection
• 📚 Knowledge Base - Built-in system for capturing patterns, decisions, and solutions
• ⚡ Workflow Optimization - Automatic parallelization and execution optimization
• 📊 Real-time Monitoring - Track workflow execution with detailed metrics
• 🔗 Claude Code Integration - Enhanced integration with automatic setup and commands
• 🚀 Framework Agnostic - Works with any project, any language, any framework

New in v0.3.3 🚀

• 📁 Single Source of Truth - Tasks now stored exclusively in .workflow/tasks.json
• 📄 Auto-exported TODO.md - Beautiful, formatted TODO.md automatically generated on task updates
• 🚫 No More Sync Errors - Removed TODO.md reading functionality to eliminate sync conflicts
• 📊 Enhanced Export Format - TODO.md includes statistics, progress bars, and timeline

New in v0.3.2 🔧

• 🐛 Critical Bug Fix - Fixed package name spelling error in Claude Code hooks
• ⚠️ Action Required - Run workflow init --claude to update configuration

New in v0.3.0 🎉

• 🆔 Project Identification - Every project now has a unique ID
• 📊 Stats Command - Complete project statistics and analytics
• 📝 Document Management - Full lifecycle management with workflow doc
• 🚀 Enhanced API - New /api/v2/project/* endpoints with automatic project info

New in v0.2.4

• 👥 Team Collaboration - Multi-user support with real-time sync
• 📋 Task Assignment - Intelligent task distribution based on skills
• 🔄 Real-time Sync - Team state synchronization with conflict resolution
• 📊 Team Dashboard - Comprehensive overview of team activities

New Integration Features 🎉

• 🔄 Format Conversion - Convert between Gongfu YAML and Workflow JSON formats
• 🌐 Built-in API Server - RESTful API with versioning, SSE events, and CORS support
• 🖥️ Web UI Launcher - One-command web interface with automatic setup
• 🤝 Enhanced MCP Support - STDIO mode for Claude Desktop, SSE mode for web apps
• ✅ Comprehensive Testing - Full test coverage with Vitest and Supertest

New in v0.2.6 🚀

• 📄 PRD Parser - Automatically generate tasks from Product Requirements Documents
• 🧠 Enhanced Complexity Analysis - Multi-factor task estimation with 13 analysis dimensions
• 🏷️ Task Tagging System - Flexible tags with smart suggestions and group management
• ⚡ Quick Commands - Fast task navigation with next, done, now, today, and quick
• 🔍 Smart Task Search - Find tasks by content, tags, or metadata

New in v0.2.5

• 🎯 Task Orchestrator - Hook-based task orchestration for Claude Code
• 🔄 Automatic Task Assignment - Claude Code receives tasks automatically
• 📝 Task Instructions - Generated with UTOPIA cycle guidance
• 🪝 Deep Hook Integration - Progress tracking and completion detection
• 🔐 Permission Management - Automatic Claude Code permission configuration

New in v0.2.3

• 📋 Task Templates - 6 built-in templates for common development tasks
• 🔗 Dependency Visualization - Tree, graph, and mermaid diagram formats

New in v0.2.2

• ⏱️ Task Time Estimation - Intelligent time prediction based on complexity
• 📊 Task Splitting - Break down large tasks with dependency management
• 🤖 24-Hour Auto-Dev Mode - Automated continuous development capability

Installation

# Global installation
npm install -g @gongfu/workflow-cli

# Or use with npx
npx @gongfu/workflow-cli init

Task Storage (Updated in v0.3.3)

The workflow CLI now uses .workflow/tasks.json as the single source of truth for all tasks:

• No more TODO.md sync conflicts - Tasks are stored only in .workflow/tasks.json
• Automatic TODO.md export - A beautifully formatted TODO.md is generated whenever tasks change
• Better data integrity - JSON format ensures consistent structure and prevents parsing errors
• Enhanced TODO.md format includes:
  • 📊 Task statistics with progress bar
  • 🚀 Tasks grouped by status and priority
  • 📅 Recent activity timeline
  • 🏷️ Tag support and filtering

The exported TODO.md is read-only and for viewing purposes only. All task modifications should be done through the CLI commands.

Quick Start

# Initialize workflow system in your project
workflow init

# Initialize with Claude Code integration
workflow init --claude

# Run project initialization protocol
workflow run init

# View and manage tasks
workflow run todo

# Start a new feature workflow
workflow start feature "Add user authentication"

# Search knowledge base
workflow kb search "authentication"

# Parse PRD to generate tasks (New!)
workflow parse-prd requirements.md --auto-create

New Features Examples (v0.2.6)

PRD Parsing - From Requirements to Tasks

# Parse a PRD document and preview tasks
workflow parse-prd requirements.md --dry-run

# Automatically create tasks with tags
workflow parse-prd PRD.md --auto-create --tag "mvp" --prefix "[FEAT]"

# Parse and export to JSON for review
workflow parse-prd specs.md --output tasks.json

# Example PRD format:
cat > requirements.md << 'EOF'
# Project Requirements

## Features
- [high][feature] User authentication with JWT
- [medium][feature] Profile management
- [high][bug] Fix login redirect issue
- [low][task] Update documentation
EOF

workflow parse-prd requirements.md
# Generates tasks with proper priority and complexity analysis

Enhanced Complexity Analysis

# Analyze single task complexity with detailed factors
workflow complexity analyze "Implement OAuth2 authentication" -d

# Batch analyze tasks from file
workflow complexity batch -f tasks.txt

# Generate complexity report in JSON
workflow complexity batch -f tasks.txt --json -o report.json

# Configure complexity thresholds
workflow complexity config --split-threshold 6 --complexity-threshold 60

# Use enhanced analyzer in task estimation
workflow task estimate "Build real-time chat system" --complexity -d
# Shows: complexity score, confidence level, risks, and splitting suggestions

Task Tagging System

# Add tags to tasks
workflow tags add <taskId> backend urgent

# Filter tasks by tags
workflow task list --tags "backend,urgent"

# Group tasks by tags
workflow task list --group

# Get tag suggestions
workflow tags suggest <taskId>

# Create tag groups
workflow tags group create "Sprint-1" -d "Sprint 1 tasks" -t "sprint1,mvp"

# View tag statistics
workflow tags list

Quick Commands (New!)

# Start next recommended task
workflow next           # Interactive mode
workflow next --auto    # Auto-start without confirmation
workflow next -t urgent # Filter by tags
workflow next -p high   # Filter by priority

# Complete current task
workflow done                      # Interactive notes
workflow done -n "Fixed the bug"   # With notes
workflow done --start-next         # Complete and start next

# Show current task status
workflow now           # Basic info
workflow now -d        # Detailed with complexity analysis

# Today's productivity dashboard
workflow today         # Summary view
workflow today -v      # Verbose with task list

# Interactive quick menu
workflow quick         # Or workflow q
# Access all commands from one menu

New Features Examples (v0.2.2)

Task Time Estimation

# Estimate time before starting a task
workflow task start "Implement user authentication" --estimate
# Output: Complexity: 75/100, Estimated time: 3 hours 36 minutes

# Batch estimate tasks
echo "Create REST API\nAdd database migrations\nWrite tests" > tasks.txt
workflow task estimate -f tasks.txt --detailed

# Get JSON output for integration
workflow task estimate "Refactor payment module" --format json

Task Splitting

# Split a large task into manageable subtasks
workflow task split "Build e-commerce checkout system"
# Output: 6 subtasks with dependencies and critical path

# Use sequential strategy with Gantt chart
workflow task split "Migrate to microservices" --strategy sequential --format gantt

# Split and save for execution
workflow task split "Implement real-time chat" --save --max-hours 2

24-Hour Auto-Dev Mode

# Preview what will be automated
workflow auto-dev preview

# Start in dry-run mode to test
workflow auto-dev start --dry-run --max-tasks 5

# Run automated development for 8 hours
workflow auto-dev start --max-hours 8 --pause 60

# Full auto mode with commits
workflow auto-dev start --auto-commit --log-file auto-dev.log

# Check status while running
workflow auto-dev status

Team Collaboration (New in v0.2.4!)

# Initialize team for your project
workflow team init --name "Dev Team"

# Add team members
workflow team add
# Interactive prompt for member details

# Check team status
workflow team list
workflow team dashboard

# Assign tasks intelligently
workflow task start "Implement OAuth2" --estimate
workflow team assign --suggest  # AI recommends based on skills

# Update your availability
workflow team status busy
workflow team status available

# View team activity
workflow team activity

Task Orchestration (New in v0.2.5!)

# Start orchestrating tasks for Claude Code
workflow orchestrate start
# Claude Code will automatically receive tasks via .claude/current-task.md

# Configure orchestration
workflow orchestrate config
# Set timeout, auto-assignment, and priority strategy

# View current task instruction
workflow orchestrate current

# Manual control
workflow orchestrate stop
workflow orchestrate check-progress
workflow orchestrate task-completed

# Example: 24-hour development
workflow task start "Build authentication system" --priority high
workflow task start "Add unit tests" --priority medium
workflow task start "Create documentation" --priority low
workflow orchestrate start --timeout 120 --auto

# Claude Code will work through tasks automatically!

Commands

Core Commands

• workflow init - Initialize workflow system in current project
  • --claude - Enable Claude Code integration
  • --no-hooks - Skip hooks configuration
  • --force - Force reinitialize
• workflow run <command> - Run workflow commands (init, todo, context, review)
• workflow sync - View task synchronization status (tasks are now stored in .workflow/tasks.json)
• workflow status - Show current workflow status

Task Management

• workflow task list - List current and recent tasks
• workflow task status - Show current task status and duration
• workflow task start <task> - Start a new task with phase tracking
  • --estimate - Show time estimation before starting
  • --priority <level> - Set task priority (high/medium/low)
• workflow task complete - Mark current task as complete
• workflow task recommend - Get AI-powered task recommendations
• workflow task estimate <task> - Estimate time for tasks
  • -f, --file <file> - Estimate tasks from file
  • -d, --detailed - Show detailed analysis
  • --format <format> - Output format (text/json)
  • --complexity - Use enhanced complexity analyzer (default: true, New in v0.2.6!)
• workflow task split <task> - Split large tasks into subtasks (New in v0.2.2!)
  • --max-hours <hours> - Maximum hours per subtask
  • --strategy <type> - Split strategy (balanced/sequential/parallel)
  • --format <format> - Output format (text/json/gantt)
  • --save - Save subtasks to workflow
• workflow parse-prd <file> - Parse PRD and generate tasks (New in v0.2.6!)
  • --auto-create - Automatically create tasks without confirmation
  • --priority <level> - Default priority for tasks
  • --tag <tag> - Add tag to all generated tasks
  • --prefix <prefix> - Add prefix to task titles
  • --dry-run - Preview tasks without creating
  • --output <file> - Save tasks to JSON file
• workflow complexity - Advanced task complexity analysis (New in v0.2.6!)
  • analyze <task> - Analyze single task complexity
    • -d, --detailed - Show all 13 complexity factors
    • -s, --split - Show task breakdown suggestions
  • batch - Batch analyze multiple tasks
    • -f, --file <file> - Analyze tasks from file
    • -c, --current - Analyze current workflow tasks
    • -o, --output <file> - Save report to file
    • --json - Output as JSON
  • config - Configure complexity thresholds
• Shorthand: Use workflow t or wf t for task commands

Quick Commands (New in v0.2.6!)

• workflow next - Start the next recommended task
  • -a, --auto - Auto-start without confirmation
  • -t, --tags <tags> - Filter by tags
  • -p, --priority <priority> - Filter by priority
  • Alias: workflow nx or wf nx
• workflow done - Complete the current task
  • -n, --notes <notes> - Add completion notes
  • -s, --start-next - Start next task immediately
  • Alias: workflow dn or wf dn
• workflow now - Show current task status
  • -d, --detailed - Show detailed information
• workflow today - Show today's task summary
  • -v, --verbose - Show detailed task list
• workflow quick - Interactive quick action menu
  • Alias: workflow q or wf q

Workflow Management

• workflow start <type> - Start a workflow (feature, bugfix, refactor)
• workflow list - List available workflows
• workflow complete - Complete current workflow

Knowledge Base

• workflow kb search <term> - Search knowledge base
• workflow kb add <type> - Add to knowledge base (pattern, decision, troubleshooting)
• workflow kb list - List knowledge base entries

Configuration

• workflow config - View current configuration
• workflow config set <key> <value> - Set configuration value

Auto-Dev Mode (New in v0.2.2!)

• workflow auto-dev start - Start 24-hour automated development
  • --max-tasks <number> - Maximum tasks to process
  • --max-hours <hours> - Maximum hours to run (default: 24)
  • --pause <seconds> - Pause between tasks
  • --auto-commit - Auto-commit after tasks
  • --dry-run - Preview mode
• workflow auto-dev status - Show auto-dev status
• workflow auto-dev preview - Preview tasks to be processed
• Shorthand: Use workflow ad or wf ad for auto-dev commands

Team Collaboration (New in v0.2.4!)

• workflow team init - Initialize team for project
  • --name <name> - Team name
• workflow team add - Add team member interactively
• workflow team list - List all team members
• workflow team me [memberId] - Set/show current user
• workflow team status <status> - Update availability (available/busy/away/offline)
• workflow team assign [memberId] - Assign current task
  • --suggest - AI-powered assignment recommendation
• workflow team activity - Show recent team activity
  • -n <number> - Number of activities to show
• workflow team dashboard - Team overview with current tasks
• workflow team settings - Configure team settings
• Shorthand: Use workflow tm or wf tm for team commands

Task Templates (New in v0.2.3!)

• workflow template list - List available templates
• workflow template show <id> - Show template details
• workflow template use <id> - Create task from template
  • --start - Start task immediately
• workflow template create - Create custom template
• workflow template search <query> - Search templates

Task Orchestration

• workflow orchestrate start - Start task orchestration
  • --auto - Automatically assign next tasks (default: true)
  • --timeout <minutes> - Task timeout (default: 120)
• workflow orchestrate stop - Stop orchestration
• workflow orchestrate current - Show current task instruction
• workflow orchestrate config - Configure orchestration settings
• Hook callbacks (automatically called):
  • check-progress - Check task progress
  • task-completed - Mark task as completed
  • session-start - Handle session start
• Shorthand: Use workflow orch or wf orch

Permissions Management

• workflow check-permissions - Check Claude Code permissions
  • --fix - Automatically fix missing permissions
• Shorthand: Use workflow perms or wf perms

Workflow System

The workflow system follows the UTOPIA cycle:

• Understand - Analyze requirements and context
• Think - Deep analysis and planning
• Organize - Task breakdown and prioritization
• Program - Incremental implementation
• Inspect - Testing and review
• Archive - Documentation and knowledge capture

Configuration

Configuration is stored in .workflow/config.json:

{
  "project": {
    "name": "my-project",
    "type": "library",
    "framework": ["react", "typescript"],
    "language": "typescript"
  },
  "settings": {
    "autoSync": true,
    "syncInterval": 300000,
    "enableAI": true,
    "checkMode": "quick"
  }
}

Claude Code Integration

Starting from v0.2.0, workflow-cli provides seamless integration with Claude Code:

Features

• Automatic Detection - Detects .claude directory and configures automatically
• Permission Setup - Adds required permissions to settings.local.json
• Command Shortcuts - Creates /task, /kb, and /workflow-init commands
• Safe Hooks - Optional hooks with performance optimization
• Directory Symlink - Links .workflow to .claude/workflow

Usage

# Initialize with Claude Code integration
workflow init --claude

# Without hooks (recommended initially)
workflow init --claude --no-hooks

# Claude Code commands
/task start "Implement new feature"
/task status
/kb search "authentication"

See CLAUDE-INTEGRATION.md for detailed documentation.

Directory Structure

.workflow/
├── commands/        # Workflow command definitions
├── workflows/       # Workflow templates
├── knowledge/       # Knowledge base
│   ├── patterns/   # Best practices
│   ├── decisions/  # Architecture decisions
│   └── troubleshooting/
├── logs/           # Activity logs
└── config.json     # Configuration

API Usage

import {
  WorkflowEngine,
  WorkflowTemplateLibrary,
  SmartWorkflowSelector,
  WorkflowOptimizer,
  WorkflowMonitor,
  ContextBuilder,
  ConfigManager,
  ServiceRegistry,
} from '@gongfu/workflow-cli';

// Initialize core services
const configManager = new ConfigManager();
const serviceRegistry = new ServiceRegistry();
const contextBuilder = new ContextBuilder(serviceRegistry);
const engine = new WorkflowEngine(configManager);
const templateLibrary = new WorkflowTemplateLibrary();
const selector = new SmartWorkflowSelector(configManager, contextBuilder);
const optimizer = new WorkflowOptimizer();
const monitor = new WorkflowMonitor(engine, configManager);

await serviceRegistry.start();

// Smart workflow selection based on context
const recommendations = await selector.selectWorkflow({
  description: 'Fix login validation not working on mobile devices',
  type: 'auto',
  context: { priority: 'high' },
});

// Use the recommended workflow
const selectedWorkflow = recommendations[0];
const definition = templateLibrary.createFromTemplate(
  selectedWorkflow.template.id,
  selectedWorkflow.parameters
);

// Optimize workflow execution
const optimizationResult = await optimizer.optimize(definition, undefined, {
  enableParallelization: true,
  enableStepSkipping: true,
  maxParallelSteps: 5,
});

// Register and start workflow
engine.registerDefinition(optimizationResult.optimizedDefinition);
const instance = await engine.start(optimizationResult.optimizedDefinition.id);

// Monitor workflow execution
monitor.on('event', event => {
  if (event.type === 'workflow_completed') {
    console.log('Workflow completed:', event.data);
  }
});

// Generate execution report
const report = monitor.generateReport({
  start: instance.startedAt,
  end: Date.now(),
});

Workflow Templates

Built-in templates for common development scenarios:

Available Templates

• feature - Feature development workflow
• bugfix - Bug fixing workflow
• hotfix - Emergency hotfix workflow
• refactor - Code refactoring workflow
• release - Release preparation workflow
• testing - Testing workflow
• documentation - Documentation workflow
• performance - Performance optimization workflow
• security - Security audit workflow
• migration - Data/code migration workflow

Example Scenarios

Check out the examples/workflows directory for real-world workflow scenarios:

• Bug Fix Workflow - Complete bug reproduction, analysis, and fixing process
• Feature Development - From research to deployment with testing
• Code Refactoring - Systematic refactoring with quality gates
• Emergency Hotfix - Rapid response for production incidents

License

MIT © CodePack Team