@codepack/workflow-cli/README.md

AI-powered workflow management CLI for developers

# @codepack/workflow-cli

AI-powered workflow management CLI for developers. Framework-agnostic tool that helps you manage tasks, organize projects, and automate development workflows.

## Features

- 🤖 **AI-Powered Task Management** - Intelligent task prioritization and recommendations
- 🧠 **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
- 🎯 **MCP Integration** - Model Context Protocol support for AI collaboration
- 🔗 **Claude Code Integration** - Enhanced integration with automatic setup and commands
- 🚀 **Framework Agnostic** - Works with any project, any language, any framework

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

### 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 @codepack/workflow-cli

# Or use with npx
npx @codepack/workflow-cli init
```

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

## 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` - Sync tasks from project TODO files
- `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 (New in v0.2.2!)
  - `-f, --file <file>` - Estimate tasks from file
  - `-d, --detailed` - Show detailed analysis
  - `--format <format>` - Output format (text/json)
- `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
- Shorthand: Use `workflow t` or `wf t` for task commands

### 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 '@codepack/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