@litmers/cursorflow-orchestrator 0.1.37 → 0.1.40

package/commands/cursorflow-doctor.md

@@ -1,102 +0,0 @@
-# CursorFlow Doctor
-
-## Overview
-Verify that your environment and flow configurations are properly set up for CursorFlow.
-
-## Usage
-
-```bash
-cursorflow doctor [flow-name] [options]
-```
-
-## Checks Performed
-- **Environment**: Git repository status, remote availability, and worktree support.
-- **Cursor IDE**: Verifies `cursor-agent` is installed and authenticated.
-- **Flow/Tasks**: (Optional) Validates flow JSON files for schema errors or missing fields.
-
-## Options
-
-| Option | Description |
-|------|------|
-| `[flow-name]` | Flow name to validate (e.g., `SearchFeature`) |
-| `--tasks-dir <path>` | Validate flow/tasks in a specific directory (legacy) |
-| `--executor <type>` | Check environment for `cursor-agent` \| `cloud` |
-| `--test-agent` | Run an interactive agent test (to approve permissions) |
-| `--no-cursor` | Skip Cursor Agent installation and auth checks |
-| `--json` | Output the report in machine-readable JSON format |
-
-## Flow Validation
-
-When a flow name or `--tasks-dir` is provided, the doctor performs comprehensive validation:
-
-### Structure Validation
-- **tasks array**: Must exist and be non-empty
-- **task.name**: Required, must be alphanumeric with `-` and `_` only, unique within lane
-- **task.prompt**: Required, should be descriptive (warns if < 10 chars)
-- **task.model**: Optional, must be string if provided
-- **task.dependsOn**: Optional, task-level dependencies
-
-### Dependency Validation (DAG)
-- **Unknown dependencies**: Reports if `dependsOn` references non-existent lanes/tasks
-- **Circular dependencies**: Detects cycles (e.g., A→B→A) that would cause deadlock
-- Reports the exact cycle path for easy debugging
-
-### Branch Validation
-- **Prefix collision**: Warns if multiple lanes use the same `branchPrefix`
-- **Existing branch conflicts**: Detects if existing branches match a lane's prefix
-- **Duplicate lane names**: Ensures each lane file has a unique name
-
-## Examples
-
-```bash
-# Basic environment check
-cursorflow doctor
-
-# Validate a specific flow by name
-cursorflow doctor SearchFeature
-
-# Test agent permissions
-cursorflow doctor --test-agent
-
-# Validate a specific flow directory
-cursorflow doctor --tasks-dir _cursorflow/flows/001_SearchFeature
-
-# Skip cursor checks (faster)
-cursorflow doctor SearchFeature --no-cursor
-
-# Output as JSON
-cursorflow doctor SearchFeature --json
-```
-
-## Example Output
-
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-  🩺 CursorFlow Doctor
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-cwd: /home/user/project
-repo: /home/user/project
-tasks: /home/user/project/_cursorflow/flows/001_SearchFeature
-
-✅ All checks passed
-
-💡 Tip: If this is your first run, we recommend running:
-   cursorflow doctor --test-agent
-```
-
-## Common Issues & Fixes
-
-| Issue | Potential Fix |
-|-------|---------------|
-| `Cursor Agent not found` | Ensure Cursor IDE is installed and `cursor` command is in PATH. |
-| `Not authenticated` | Open Cursor IDE and log in to your account. |
-| `Worktree not supported` | Upgrade your Git version (requires Git >= 2.5). |
-| `Circular dependency` | Check the `dependsOn` fields in your task JSON files. |
-| `Flow not found` | Verify flow name or create with `cursorflow new`. |
-
-## Related Commands
-
-- [cursorflow new](cursorflow-new.md) - Create Flow and Lanes
-- [cursorflow add](cursorflow-add.md) - Add Tasks to Lanes
-- [cursorflow run](cursorflow-run.md) - Run Flow

package/commands/cursorflow-models.md

@@ -1,51 +0,0 @@
-# CursorFlow Models
-
-## Overview
-List available AI models supported by CursorFlow and their recommended use cases. These models are discovered from your local `cursor-agent` installation.
-
-## Usage
-
-```bash
-cursorflow models [options]
-```
-
-## Options
-
-| Option | Description |
-|------|------|
-| `--list`, `-l` | List models in a table (default) |
-| `--json` | Output model list as JSON |
-
-## Available Models
-
-| ID | Name | Provider | Recommended Use |
-|----|------|----------|-----------------|
-| `sonnet-4.5` | Claude 3.7 Sonnet | Anthropic | General implementation, fast work (Most versatile) |
-| `sonnet-4.5-thinking` | Claude 3.7 Sonnet (Thinking) | Anthropic | Code review, deeper reasoning (Thinking model) |
-| `opus-4.5` | Claude 4.0 Opus | Anthropic | Complex tasks, high quality (Advanced) |
-| `opus-4.5-thinking` | Claude 4.0 Opus (Thinking) | Anthropic | Architecture design (Premium) |
-| `gpt-5.2` | GPT-5.2 | OpenAI | General tasks |
-| `gpt-5.2-high` | GPT-5.2 High Reasoning | OpenAI | Advanced reasoning (High performance) |
-
-## Model Configuration
-
-In your task `.json` files, specify the model like this:
-
-```json
-{
-  "model": "sonnet-4.5",
-  "tasks": [
-    {
-      "name": "implement",
-      "prompt": "..."
-    }
-  ]
-}
-```
-
-## Tips
-
-- Use the `ID` from the `cursorflow models` output in your JSON files.
-- You can set a default model in `cursorflow.config.js`.
-- Individual tasks within a lane can override the lane-level model.
-

package/commands/cursorflow-monitor.md

@@ -1,90 +0,0 @@
-# CursorFlow Monitor
-
-## Overview
-The `cursorflow monitor` command provides a powerful, interactive terminal-based dashboard to track the execution status of all lanes in real-time. It allows you to visualize dependencies, stream live terminal output, and intervene in running tasks.
-
-## Usage
-
-```bash
-# Monitor the most recent run
-cursorflow monitor
-
-# List all runs (Multiple Flows Dashboard)
-cursorflow monitor --list
-
-# Monitor a specific run directory
-cursorflow monitor run-2025-12-21T10-00-00
-```
-
-## Options
-
-| Option | Description |
-|--------|-------------|
-| `[run-dir]` | Run directory or ID to monitor (default: latest) |
-| `--list`, `-l` | Show all runs dashboard (interactive list) |
-| `--interval <n>` | Refresh interval in seconds (default: 2) |
-| `--help`, `-h` | Show help |
-
-## Dashboard Controls
-
-### List View (Main)
-- **Navigation**: Use `↑` and `↓` to move between lanes.
-- **Details**: Press `→` or `Enter` to enter the **Lane Detail View**.
-- **Flow View**: Press `F` to see the task dependency graph (DAG).
-- **All Runs**: Press `M` to switch to the **All Flows Dashboard**.
-- **Unified Logs**: Press `U` to see a merged log stream of all lanes.
-- **Quit**: Press `Q` to exit.
-
-### All Flows Dashboard
-- **Navigation**: Use `↑` and `↓` to select a flow.
-- **Switch**: Press `→` or `Enter` to switch the monitor to the selected flow.
-- **Delete**: Press `D` to delete a completed flow's logs (requires confirmation).
-- **Refresh**: Press `R` to refresh the list of flows.
-- **Back**: Press `M` or `Esc` to return to the List View.
-
-### Lane Detail View
-- **History Browsing**: Use `↑` and `↓` to scroll through conversation history.
-- **Message Detail**: Press `→` or `Enter` on a message to see its full content.
-- **Live Terminal**: Press `T` to enter the **Full Terminal View**.
-- **Intervention**: Press `I` to send a manual prompt to the agent (requires `enableIntervention: true`).
-- **Kill Process**: Press `K` to forcefully terminate a stuck agent process.
-- **Back**: Press `←` or `Esc` to return to the List View.
-
-### Full Terminal View
-- **Scrolling**: Use `↑` and `↓` to scroll through the entire agent output log.
-- **Back**: Press `T`, `←`, or `Esc` to return to the Lane Detail View.
-
-### Intervention View
-- **Typing**: Type your message directly.
-- **Send**: Press `Enter` to send the intervention message.
-- **Cancel**: Press `Esc` to cancel and return.
-
-## Key Concepts
-
-### Lane Statuses
-| Status | Icon | Description |
-|--------|------|-------------|
-| `pending` | ⚪ | Lane is waiting to start |
-| `waiting` | ⏳ | Waiting for parent dependencies to complete |
-| `running` | 🔄 | Agent is currently executing tasks |
-| `reviewing` | 👀 | AI Reviewer is checking the task results |
-| `completed` | ✅ | All tasks and reviews finished successfully |
-| `failed` | ❌ | A task or review failed with an error |
-| `blocked` | 🚫 | Blocked by a failed dependency |
-
-### Dependency Flow View
-A visual representation of the Directed Acyclic Graph (DAG). It shows which lanes must finish before others can start, helping you understand the execution pipeline.
-
-### Heartbeat Logs
-CursorFlow monitors agent activity and logs status every few seconds. If a lane shows `0 bytes received` for a long period, it may be stuck or thinking deeply.
-
-## Troubleshooting
-
-### Lane is stuck
-1. Enter the **Lane Detail View**.
-2. Check the **PID** to ensure the process is still alive.
-3. Check the **Live Terminal** preview or enter **Full Terminal View (T)**.
-4. If it's truly stuck, press `K` to kill it, then use `cursorflow resume <lane>` to restart.
-
-### Sending Instructions
-If the agent is heading in the wrong direction, use the **Intervention (I)** feature to guide it without stopping the run. Note that this requires `enableIntervention: true` in the task's JSON configuration.

package/commands/cursorflow-new.md

@@ -1,87 +0,0 @@
-# cursorflow new
-
-Flow와 Lane을 생성합니다.
-
-## 사용법
-
-```bash
-cursorflow new <FlowName> --lanes "lane1,lane2,..."
-```
-
-## 설명
-
-새로운 Flow 디렉토리를 생성하고, 지정된 Lane 파일들의 뼈대를 만듭니다.
-각 Lane에 실제 Task를 추가하려면 `cursorflow add` 명령을 사용하세요.
-
-## 옵션
-
-| 옵션 | 설명 | 예시 |
-|------|------|------|
-| `--lanes <names>` | 콤마로 구분된 레인 이름 목록 (필수) | `--lanes "backend,frontend"` |
-
-## 예시
-
-### 기본 사용
-
-```bash
-# 백엔드와 프론트엔드 2개 레인 생성
-cursorflow new ShopFeature --lanes "backend,frontend"
-```
-
-### 3개 레인 생성
-
-```bash
-# API, Web, Mobile 3개 레인 생성
-cursorflow new SearchFeature --lanes "api,web,mobile"
-```
-
-## 생성 결과
-
-```
-_cursorflow/flows/001_ShopFeature/
-├── flow.meta.json       # Flow 메타데이터
-├── 01-backend.json      # Lane 1 (빈 상태)
-└── 02-frontend.json     # Lane 2 (빈 상태)
-```
-
-### flow.meta.json 스키마
-
-```json
-{
-  "id": "001",
-  "name": "ShopFeature",
-  "createdAt": "2024-12-25T10:30:00Z",
-  "createdBy": "user",
-  "baseBranch": "main",
-  "status": "pending",
-  "lanes": ["backend", "frontend"]
-}
-```
-
-### Lane 파일 스키마 (빈 상태)
-
-```json
-{
-  "laneName": "backend",
-  "tasks": []
-}
-```
-
-## 다음 단계
-
-Flow 생성 후, 각 Lane에 Task를 추가합니다:
-
-```bash
-cursorflow add ShopFeature backend \
-  --task "name=implement|prompt=API 구현"
-
-cursorflow add ShopFeature frontend \
-  --task "name=ui|prompt=UI 구현" \
-  --after "backend:implement"
-```
-
-## 관련 명령어
-
-- [cursorflow add](cursorflow-add.md) - Lane에 Task 추가
-- [cursorflow run](cursorflow-run.md) - Flow 실행
-

package/commands/cursorflow-resume.md

@@ -1,205 +0,0 @@
-# CursorFlow Resume
-
-## Overview
-Resume lanes that were interrupted or failed. CursorFlow allows you to continue from where the agent left off, restart from the first task, or resume all incomplete lanes at once.
-
-## Usage
-
-```bash
-cursorflow resume [lane-name] [options]
-cursorflow resume --status              # Check status of all lanes
-cursorflow resume --all                 # Resume all incomplete lanes
-```
-
-## Options
-
-| Option | Description |
-|------|------|
-| `<lane-name>` | The name of the lane to resume (e.g., `lane-1`) |
-| `--status` | Show status of all lanes in the run (no resume) |
-| `--all` | Resume ALL incomplete/failed lanes automatically |
-| `--run-dir <path>` | Use a specific run directory (default: latest) |
-| `--max-concurrent <n>` | Max lanes to run in parallel when using `--all` (default: 3) |
-| `--restart` | Restart from the first task (index 0) |
-| `--clean` | Clean up the existing worktree before resuming |
-| `--skip-doctor` | Skip pre-resume checks (not recommended) |
-
-## Checking Lane Status
-
-Before resuming, you can check the status of all lanes:
-
-```bash
-cursorflow resume --status
-```
-
-This displays a table showing:
-- Lane name
-- Current status (completed, failed, running, paused, etc.)
-- Progress (current task / total tasks)
-- Whether the lane needs to be resumed
-
-Example output:
-```
-📊 Lane Status (run-1703145600000)
-
-  Lane                     Status      Progress    Needs Resume
-  ------------------------------------------------------------
-  01-lane-auth             completed   3/3         
-  02-lane-api              failed      1/3         ✓
-   └─ Error: cursor-agent timed out...
-  03-lane-ui               running     2/3         ✓
-
-  Total: 3 | Completed: 1 | Needs Resume: 2
-
-  Tip: Run cursorflow resume --all to resume all incomplete lanes
-```
-
-## Resuming All Incomplete Lanes
-
-The most common use case after interruption:
-
-```bash
-# Check what needs to be resumed
-cursorflow resume --status
-
-# Resume all incomplete lanes
-cursorflow resume --all
-
-# Resume with custom concurrency
-cursorflow resume --all --max-concurrent 2
-
-# Restart all incomplete lanes from the beginning
-cursorflow resume --all --restart
-```
-
-## How it works
-
-### Single Lane Resume
-1. **Pre-flight Checks**: Runs doctor validation to check for branch conflicts and Git issues.
-2. **State Loading**: Reads the `state.json` for the specified lane to find the last successful task.
-3. **Environment Restore**: Verifies the Git worktree and branch for the lane.
-4. **Execution**: Spawns a new runner that starts either from the current task index or from index 0 if `--restart` is used.
-
-### Resume All (`--all`)
-1. **Status Check**: Scans all lanes in the run directory.
-2. **Filter**: Identifies lanes that need resuming (failed, paused, interrupted).
-3. **Dependency Analysis**: 
-   - Checks each lane's `dependsOn` field
-   - Skips lanes with unresolvable dependencies (deps not completed and not in resume list)
-   - Orders execution so lanes wait for their dependencies to complete first
-4. **Pre-flight Checks**: Runs doctor validation once for the entire run.
-5. **Parallel Execution**: Spawns runners for multiple lanes with concurrency control.
-6. **Dependency-Aware Scheduling**: Only starts a lane when all its dependencies have completed.
-7. **Progress Tracking**: Reports success/failure/skipped for each lane.
-
-## Pre-resume Validation
-
-Before resuming, CursorFlow automatically runs validation checks:
-- **Branch conflicts**: Ensures no existing branches conflict with the lane's prefix
-- **Git status**: Verifies repository state and remote connectivity
-- **Task configuration**: Validates the task JSON files are still valid
-
-To skip these checks (not recommended):
-```bash
-cursorflow resume lane-1 --skip-doctor
-cursorflow resume --all --skip-doctor
-```
-
-## Examples
-
-### Check status of all lanes
-```bash
-cursorflow resume --status
-```
-
-### Resume all incomplete lanes
-```bash
-cursorflow resume --all
-```
-
-### Resume a single failed lane
-```bash
-cursorflow resume 01-lane-1
-```
-
-### Restart a lane from scratch
-```bash
-cursorflow resume 02-lane-2 --restart
-```
-
-### Resume from an older run
-```bash
-cursorflow resume --status --run-dir _cursorflow/logs/runs/run-123456789/
-cursorflow resume --all --run-dir _cursorflow/logs/runs/run-123456789/
-```
-
-### Resume with limited parallelism
-```bash
-cursorflow resume --all --max-concurrent 1  # One at a time
-```
-
-## Dependency Handling
-
-When using `--all`, CursorFlow respects the `dependsOn` field in each lane's configuration:
-
-- **Automatic ordering**: Lanes will wait for their dependencies to complete before starting
-- **Skipped lanes**: If a lane depends on another that isn't completed and isn't in the resume queue, it will be skipped
-- **Parallel with deps**: Independent lanes run in parallel; dependent lanes wait
-
-Example status output with dependencies:
-```
-📊 Lane Status (run-1703145600000)
-
-  Lane                     Status      Progress    DependsOn      Resumable
-  ---------------------------------------------------------------------------
-  01-lane-core             completed   3/3         -              
-  02-lane-api              failed      1/3         01-lane-core   ✓
-  03-lane-ui               failed      0/3         02-lane-api    ⏳ waiting
-   └─ waiting for: 02-lane-api
-
-  Total: 3 | Completed: 1 | Needs Resume: 2
-
-  Tip: Run cursorflow resume --all to resume all incomplete lanes
-       Lanes with dependencies will wait until their dependencies complete.
-```
-
-In this example:
-- `01-lane-core` is already completed
-- `02-lane-api` can start immediately (its dependency `01-lane-core` is completed)
-- `03-lane-ui` will wait until `02-lane-api` completes
-
-## Troubleshooting
-
-### State not found
-If the command fails because the state is missing, ensure you are providing the correct lane name. Use `cursorflow resume --status` to see the names of the lanes in the latest run.
-
-### Worktree issues
-If the worktree directory was manually deleted, use the `--clean` or `--restart` flag to allow CursorFlow to recreate the environment.
-
-### Branch conflicts
-If resume fails due to branch conflicts:
-
-```bash
-# Check what branches exist
-git branch --list "feature/*"
-
-# Clean up old CursorFlow branches
-cursorflow clean branches --dry-run
-cursorflow clean branches
-
-# Or manually delete specific branches
-git branch -D feature/lane-1-old-branch
-```
-
-### Changed branch prefix
-If the task JSON file's `branchPrefix` was changed after the initial run:
-1. Either restore the original prefix in the JSON
-2. Or use `--restart` to start fresh with the new prefix
-3. Or manually clean up old branches with `cursorflow clean branches`
-
-### Some lanes still failing after `--all`
-If some lanes continue to fail after using `--all`:
-1. Check the specific error with `cursorflow resume --status`
-2. Try resuming the problematic lane individually with more visibility
-3. Use `cursorflow monitor` to watch the lane in real-time
-4. Check the lane's terminal log in `_cursorflow/logs/runs/<run>/lanes/<lane>/`

package/commands/cursorflow-signal.md

@@ -1,52 +0,0 @@
-# CursorFlow Signal
-
-## Overview
-Directly intervene in a running lane by sending a message to the agent. This is useful for providing immediate feedback or corrections during long-running tasks.
-
-## Usage
-
-```bash
-cursorflow signal <lane-name> "<message>" [options]
-cursorflow signal <lane-name> --timeout <ms>
-```
-
-## Options
-
-| Option | Description |
-|------|------|
-| `<lane-name>` | The name of the lane to signal |
-| `"<message>"` | The text message to send to the agent |
-| `--timeout <ms>` | Update the execution timeout (in milliseconds) |
-| `--run-dir <path>` | Use a specific run directory (default: latest) |
-
-## How it works
-1. **Logging**: Intervention messages are recorded in the lane's conversation history.
-2. **Injection**: If `enableIntervention: true`, messages are injected into the agent's input stream.
-3. **Dynamic Timeout**: If `--timeout` is used, the active runner receives a signal to reset its internal timer to the new value.
-
-## Examples
-
-```bash
-# Provide a hint to a running agent
-cursorflow signal 01-lane-1 "Make sure to export the new function from index.ts"
-
-# Increase timeout to 10 minutes mid-execution
-cursorflow signal 01-lane-1 --timeout 600000
-```
-
-## Dashboard Alternative
-You can also use the interactive monitor to send signals:
-1. Run `cursorflow monitor latest`.
-2. Select a lane and enter details (`→`).
-3. Press `I` to send an intervention message.
-4. Press `O` to update the execution timeout.
-
-## Note on Intervention
-For the agent to receive the signal immediately, the task must be configured with:
-```json
-{
-  "enableIntervention": true,
-  "tasks": [...]
-}
-```
-If disabled, the signal will be logged but the agent will not be interrupted.

package/commands/cursorflow-stop.md

@@ -1,55 +0,0 @@
-# CursorFlow Stop
-
-## Overview
-Stop running CursorFlow workflows or specific lanes by killing their associated processes.
-
-## Usage
-
-```bash
-cursorflow stop [run-id] [options]
-```
-
-## Options
-
-| Option | Description |
-|--------|-------------|
-| `[run-id]` | Stop a specific run |
-| `--lane <name>` | Stop only a specific lane |
-| `--force` | Use `SIGKILL` instead of `SIGTERM` (immediate termination) |
-| `--yes`, `-y` | Skip confirmation prompt |
-| `--help`, `-h` | Show help |
-
-## Examples
-
-### Stop all running workflows
-```bash
-cursorflow stop
-```
-
-### Stop a specific run
-```bash
-cursorflow stop run-20251222-153012
-```
-
-### Stop only one lane
-```bash
-cursorflow stop --lane api-setup
-```
-
-### Force stop everything without confirmation
-```bash
-cursorflow stop --force --yes
-```
-
-## Execution Flow
-
-1. **Detection**: identifies active runs and their associated PIDs.
-2. **Confirmation**: Unless `--yes` is used, it lists running workflows and asks for confirmation.
-3. **Termination**: Sends termination signals to all active lane processes.
-4. **Verification**: Displays which lanes were successfully stopped.
-
-## Notes
-
-1. **Signals**: By default, it sends `SIGTERM` to allow processes to clean up. Use `--force` for `SIGKILL` if a process is stuck.
-2. **Persistence**: Stopping a run doesn't delete any logs or worktrees. You can resume later using `cursorflow resume`.
-3. **PIDs**: The command relies on PIDs stored in the lane state files.