@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

$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

$3

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

$3

- 🆔 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

$3

- 👥 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

$3

- 🔄 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

$3

- 📄 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

$3

- 🎯 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

$3

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

$3

- ⏱️ 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

``bash


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

`bash


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)

$3

`bash


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

`

$3

`bash


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

`

$3

`bash


Add tags to tasks

workflow tags add 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

Create tag groups

workflow tags group create "Sprint-1" -d "Sprint 1 tasks" -t "sprint1,mvp"

View tag statistics

workflow tags list
`

$3

`bash


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)

$3

`bash


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
`

$3

`bash


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
`

$3

`bash


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
`

$3

`bash


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
`

$3

`bash


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

$3

- workflow init - Initialize workflow system in current project
- --claude - Enable Claude Code integration
- --no-hooks - Skip hooks configuration
- --force - Force reinitialize
- workflow run - 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

$3

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

$3

- workflow next - Start the next recommended task
- -a, --auto - Auto-start without confirmation
- -t, --tags - Filter by tags
- -p, --priority - Filter by priority
- Alias: workflow nx or wf nx
- workflow done - Complete the current task
- -n, --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

$3

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

$3

- workflow kb search - Search knowledge base
- workflow kb add - Add to knowledge base (pattern, decision, troubleshooting)
- workflow kb list - List knowledge base entries

$3

- workflow config - View current configuration
- workflow config set - Set configuration value

$3

- workflow auto-dev start - Start 24-hour automated development
- --max-tasks - Maximum tasks to process
- --max-hours - Maximum hours to run (default: 24)
- --pause - 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

$3

- workflow team init - Initialize team for project
- --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 - 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 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

$3

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

$3

- workflow orchestrate start - Start task orchestration
- --auto - Automatically assign next tasks (default: true)
- --timeout - 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

$3

- 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:

`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:

$3

- 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

$3

`bash


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

`typescript
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:

$3

- 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

$3

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