AI Workflow Engine

# 1. Clone and install
git clone https://github.com/hanyki111/workflow-tool.git
cd workflow-tool
pip install -e .

# 2. Check it works
flow --help

# 3. Initialize workflow in your project
cd /path/to/your-project
flow init --template simple  # or "full" for advanced workflow

# 4. See current status
flow status

# 5. Start the tutorial
flow tutorial

flow status           # See current stage
flow check 1 2        # Mark items as done
flow next             # Move to next stage

# Clone the repository
git clone https://github.com/hanyki111/workflow-tool.git
cd workflow-tool

# Create virtual environment (recommended)
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install in editable mode
pip install -e .

# Verify installation
flow --help

pip install ai-workflow-engine

# Direct execution
python -m workflow --help

# Or set up an alias
alias flow='python -m workflow'

# Automatic installation
flow install-alias --name flow

# Or manually add to ~/.bashrc or ~/.zshrc:
alias flow='python -m workflow'

# Reload shell config
source ~/.bashrc  # or ~/.zshrc

# Should display version and help
flow --help

# Should show "Workflow Management Tool"
python -m workflow --help

# Initialize with simple 4-stage workflow (recommended for beginners)
flow init --template simple

# Initialize with full M0-M4, P1-P7 dual-track workflow
flow init --template full

# Specify project name
flow init --template simple --name my-project

# Skip CLAUDE.md generation
flow init --no-claude-md

# Force overwrite existing files
flow init --force

# List available templates
flow init --list-templates

# Full status display
flow status

# Output:
# Current Stage: M0 (Tech Debt Review)
# ========================================
# Active Module: core-engine
# ----------------------------------------
# 1. [x] Review existing tech debt
# 2. [x] Prioritize debt items
# 3. [ ] [USER-APPROVE] Approve debt plan

# Compact one-line format
flow status --oneline
# Output: M0 (Tech Debt Review) - 2/3

# Check single item (1-based index)
flow check 1

# Check multiple items
flow check 1 2 3

# Add evidence/justification
flow check 1 --evidence "Reviewed with team on 2024-01-15"

# Check USER-APPROVE item with token
flow check 3 --token "your-secret-phrase"

# Check with both
flow check 3 --token "secret" --evidence "Approved by @alice after security review"

# Pass arguments to action (for items with require_args: true)
flow check 5 --args "feat(auth): add login validation"

$ flow check 1
✅ Action executed: npm run lint
   Output: All files passed linting
Checked: Run linter

$ flow check 2
❌ Action failed for item 2: Tests failed with 3 errors

$ flow check 1
🔄 [RALPH MODE] Action failed (attempt 1/5)

Goal: Make `cat .workflow/code_review.md` succeed
Error: Fail pattern found in output: "**FAIL**"

📋 Instructions for Task subagent:
1. Analyze the error and fix the code
2. Run flow check 1 again
3. Repeat until success

# Uncheck items
flow uncheck 1 2

# Using alias
flow u 1

# Uncheck USER-APPROVE item (requires token)
flow u 3 --token "your-secret"

# Auto-detect next stage (uses first valid transition)
flow next

# Specify target stage explicitly
flow next M1

# Skip plugin conditions (shell, fs) but still require all items checked
flow next --skip-conditions

# Force transition (bypasses all conditions, requires token)
flow next --force --token "your-secret" --reason "Emergency hotfix required"

# Possible outputs:
# Success: "✅ Transitioned to M1: Planning"
# Skip:    "⚠️ [SKIP-CONDITIONS] Transitioned to P5"
# Blocked: "Cannot proceed. Unchecked items: ..."

# Set stage only
flow set M2

# Set stage and active module
flow set P3 --module inventory-system

# Useful for:
# - Resuming after state corruption
# - Jumping to a specific point
# - Testing specific stages

# Change module while keeping current stage
flow module set inventory-system

# Useful for:
# - Switching context at start of new phase (P1)
# - Working on different module without resetting checklist

# Create a parallel track
flow track create --id feat-auth --label "Authentication" --module auth

# Create with specific starting stage
flow track create --id feat-api --label "API Layer" --module api --stage P1

# List all tracks
flow track list

# Switch active track
flow track switch feat-auth

# Use --track flag with any command
flow check 1 2 --track feat-auth
flow status --track feat-auth
flow next --track feat-auth

# Join all completed tracks
flow track join

# Force join (even with incomplete tracks)
flow track join --force --token "your-secret"

# Delete a track
flow track delete feat-auth

# Add phases with dependencies
flow phase add --id auth --label "Authentication" --module auth
flow phase add --id api --label "API Layer" --module api --depends-on auth
flow phase add --id ui --label "UI Components" --module ui --depends-on auth

# View DAG as list
flow phase list

# View DAG level visualization
flow phase graph
# Output:
# Phase DAG (3 phases, 2 levels):
# Level 0: auth (Authentication) [pending]
# Level 1: api (API Layer) [pending], ui (UI Components) [pending]

# Remove a phase
flow phase remove --id ui

flow review --agent "code-reviewer" --summary "All SOLID principles followed, no blocking issues found"

# Record review for a specific track
flow review --agent "code-reviewer" --summary "Review passed" --track feat-auth

# This creates an audit log entry that can be verified later

# Instead of two commands:
flow review --agent plan-critic --summary "..."
flow check 1

# Use one command:
flow check 1 --agent plan-critic

flow secret-generate

# Interactive prompts:
# Enter your secret phrase: ********
# Confirm secret phrase: ********
# Secret hash saved to .workflow/secret

# Install wrappers for auto-detected shell
flow install-wrappers

# Specify shell
flow install-wrappers --shell bash
flow install-wrappers --shell powershell

# Preview wrappers without installing
flow install-wrappers --list

# Dry run - show changes without applying
flow install-wrappers --dry-run

# Remove wrappers
flow install-wrappers --uninstall

pytest() {
    command pytest "$@"
    local result=$?
    [ $result -eq 0 ] && flow check --tag "CMD:pytest" 2>/dev/null
    return $result
}

# List all sections
flow tutorial --list

# View specific section
flow tutorial --section 0

# Start interactive tutorial
flow tutorial

# Use alias
flow guide --section 2

# Install with default name 'flow'
flow install-alias

# Install with custom name
flow install-alias --name wf

# Set display language
flow --lang ko status
flow --lang en --help

# Get help
flow --help
flow status --help

flow track create --id feat-auth --label "Auth Module" --module auth
flow track create --id feat-api --label "API Module" --module api
flow track switch feat-auth    # Work on auth
flow check 1 2 3               # Check items in auth track
flow track switch feat-api     # Switch to api
flow next                      # Advance api track
flow track join                # Merge when all complete

# 2. Add phases at runtime
flow phase add --id auth --label "Authentication" --module auth
flow phase add --id api --label "API" --module api --depends-on auth
flow phase add --id ui --label "UI" --module ui --depends-on auth
flow phase add --id deploy --label "Deploy" --module deploy --depends-on api,ui

# List all tutorial sections
flow tutorial --list

# Output:
# 0. Introduction
# 1. Installation & Setup
# 2. Basic Commands
# 3. Security & Secrets
# 4. Advanced Features
# 5. Best Practices

# View a specific section
flow tutorial --section 0

# Start interactive mode
flow tutorial

cd examples/simple
flow status

cd examples/full-project
flow status

cd examples/custom-plugins
flow status

# Simple item - just marks as done
flow check 1

# Action item - executes command, then marks as done (if successful)
flow check 2
# ✅ Action executed: pytest -v
#    Output: 15 passed in 2.34s
# Checked: Run tests

# Item requiring arguments
flow check 3 --args "feat(auth): add login validation"
# ✅ Action executed: git add . && git commit -m "feat(auth): add login validation"
# Checked: Git commit

# If action fails, item is NOT checked
flow check 2
# ❌ Action failed for item 2: 3 tests failed
#    → Use --skip-action to mark as done without running action

# Skip action and mark as done manually
flow check 2 --skip-action
# ⚠️ Action skipped for item 2: pytest -v
# Checked: Run tests

mkdir -p .claude/hooks
cp examples/hooks/auto-review.sh .claude/hooks/
chmod +x .claude/hooks/auto-review.sh

mkdir -p .gemini/hooks
cp examples/hooks/auto-review.sh .gemini/hooks/
chmod +x .gemini/hooks/auto-review.sh

# After agent delegation completes
flow check 1 --agent code-reviewer

# pytest wrapper
pytest() {
    command pytest "$@"
    [ $? -eq 0 ] && flow check --tag "CMD:pytest" 2>/dev/null
}

# Subcommand-aware wrapper
memory_tool() {
    command memory_tool "$@"
    [ $? -eq 0 ] && case "$1" in
        write|save) flow check --tag "CMD:memory-write" ;;
    esac
}

pytest tests/        # ✅ Auto-checks "[CMD:pytest] Run tests"
memory_tool write x  # ✅ Auto-checks "[CMD:memory-write] Save documentation"
memory_tool read x   # (no check - read is not mapped)

# Via command line flag
flow --lang ko status

# Via environment variable
export FLOW_LANG=ko
flow status

# Language detection priority:
# 1. --lang flag
# 2. FLOW_LANG environment variable
# 3. System locale
# 4. Default (English)

# Error: Configuration file not found: workflow.yaml

# Solution: Create workflow.yaml in project root
# Or specify path: flow --config path/to/workflow.yaml status

# Error: Cannot transition: All checklist items must be completed

# Solution: Check remaining items
flow status

# Complete missing items
flow check 3 4

# Try again
flow next

# Error: Invalid token for USER-APPROVE

# Solution 1: Check if secret is generated
ls .workflow/secret

# Solution 2: Regenerate secret
flow secret-generate

# Solution 3: Use correct phrase
flow check 2 --token "your-actual-secret"

# Error: Failed to load plugin: my_plugin

# Solution: Check plugin path in workflow.yaml
# Ensure the module is importable:
python -c "from my_project.validators import MyValidator"

# If state.json is corrupted:

# Option 1: Reset to a known stage
flow set M0

# Option 2: Delete and reinitialize
rm .workflow/state.json
flow status  # Creates fresh state

# Set Python debug
PYTHONDEBUG=1 flow status

# Check state file directly
cat .workflow/state.json | python -m json.tool

# Validate YAML config
python -c "import yaml; yaml.safe_load(open('workflow.yaml'))"

# Clone repository
git clone https://github.com/hanyki111/workflow-tool.git
cd workflow-tool

# Create virtual environment
python -m venv .venv
source .venv/bin/activate

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest tests/ -v