@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

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

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

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"

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

• 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 '@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 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