AI-powered workflow management CLI for developers
npm install @gongfu/workflow-cliAI-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' 的任务即为当前任务
- 🤖 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
- 📁 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
- 🐛 Critical Bug Fix - Fixed package name spelling error in Claude Code hooks
- ⚠️ Action Required - Run workflow init --claude to update configuration
- 🆔 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
- 👥 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
- 🔄 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
- 📄 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
- 🎯 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
- 📋 Task Templates - 6 built-in templates for common development tasks
- 🔗 Dependency Visualization - Tree, graph, and mermaid diagram formats
- ⏱️ 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
``bashGlobal installation
npm install -g @gongfu/workflow-cli
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 filteringThe 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 initInitialize with Claude Code integration
workflow init --claudeRun project initialization protocol
workflow run initView and manage tasks
workflow run todoStart 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-runAutomatically 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.jsonExample 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
EOFworkflow 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" -dBatch analyze tasks from file
workflow complexity batch -f tasks.txtGenerate complexity report in JSON
workflow complexity batch -f tasks.txt --json -o report.jsonConfigure complexity thresholds
workflow complexity config --split-threshold 6 --complexity-threshold 60Use 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 urgentFilter tasks by tags
workflow task list --tags "backend,urgent"Group tasks by tags
workflow task list --groupGet 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 priorityComplete current task
workflow done # Interactive notes
workflow done -n "Fixed the bug" # With notes
workflow done --start-next # Complete and start nextShow current task status
workflow now # Basic info
workflow now -d # Detailed with complexity analysisToday's productivity dashboard
workflow today # Summary view
workflow today -v # Verbose with task listInteractive 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 --detailedGet 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 ganttSplit 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 previewStart in dry-run mode to test
workflow auto-dev start --dry-run --max-tasks 5Run automated development for 8 hours
workflow auto-dev start --max-hours 8 --pause 60Full auto mode with commits
workflow auto-dev start --auto-commit --log-file auto-dev.logCheck 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 dashboardAssign tasks intelligently
workflow task start "Implement OAuth2" --estimate
workflow team assign --suggest # AI recommends based on skillsUpdate your availability
workflow team status busy
workflow team status availableView 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 currentManual control
workflow orchestrate stop
workflow orchestrate check-progress
workflow orchestrate task-completedExample: 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 --autoClaude 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 permsWorkflow 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 --claudeWithout hooks (recommended initially)
workflow init --claude --no-hooksClaude 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 workflowCheck 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
MIT © CodePack Team