@gongfu/workflow-cli/README.md

AI-powered workflow management CLI for developers

# @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

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

### PRD Parsing - From Requirements to Tasks

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

### Enhanced Complexity Analysis

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

### Task Tagging System

```bash
# 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!)

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

### Task Time Estimation

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

### Task Splitting

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

### 24-Hour Auto-Dev Mode

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

### Team Collaboration (New in v0.2.4!)

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

### Task Orchestration (New in v0.2.5!)

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

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

- **U**nderstand - Analyze requirements and context
- **T**hink - Deep analysis and planning
- **O**rganize - Task breakdown and prioritization
- **P**rogram - Incremental implementation
- **I**nspect - Testing and review
- **A**rchive - 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:

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

```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](docs/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:

### 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](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