@litmers/cursorflow-orchestrator 0.1.8 → 0.1.12

package/commands/cursorflow-clean.md

@@ -1,162 +1,51 @@
 # CursorFlow Clean
 
 ## Overview
-Clean up branches, worktrees, and logs. Remove stale files or remnants from failed runs.
+Clean up temporary resources created by CursorFlow, including Git worktrees, feature branches, and log files.
 
-## Steps
+## Usage
 
-1. **Choose what to clean**
-
-   | Type | Description |
-   |------|------|
-   | `branches` | Clean Git branches |
-   | `worktrees` | Clean Git worktrees |
-   | `logs` | Clean log files |
-   | `all` | Clean everything |
-
-2. **Clean branches**
-   ```bash
-   cursorflow clean branches --pattern "feature/my-*"
-   ```
-
-3. **Clean worktrees**
-   ```bash
-   cursorflow clean worktrees --all
-   ```
+```bash
+cursorflow clean <type> [options]
+```
 
-4. **Clean logs**
-   ```bash
-   cursorflow clean logs --older-than 30
-   ```
+## Clean Types
 
-5. **Verify with a dry run**
-   ```bash
-   cursorflow clean all --dry-run
-   ```
+| Type | Description |
+|------|------|
+| `branches` | Remove local feature branches created by CursorFlow |
+| `worktrees` | Remove temporary Git worktrees |
+| `logs` | Clear all run and terminal logs |
+| `all` | Clean everything (branches, worktrees, and logs) |
 
 ## Options
 
 | Option | Description |
 |------|------|
-| `--pattern <pattern>` | Pattern match (e.g., "feature/*") |
-| `--older-than <days>` | Items older than N days (for logs) |
-| `--dry-run` | Show items to delete without removing |
-| `--force` | Delete without confirmation |
-| `--local-only` | Local only (branches) |
-| `--remote-only` | Remote only (branches) |
+| `--dry-run` | Show what would be removed without actually deleting anything |
+| `--force` | Force removal (ignore uncommitted changes in worktrees) |
+| `--help`, `-h` | Show help |
 
 ## Examples
 
-### Branch cleanup
-
-#### Delete by pattern
-```bash
-cursorflow clean branches --pattern "feature/dashboard-*"
-```
-
-#### All CursorFlow branches
-```bash
-cursorflow clean branches --pattern "feature/*" --dry-run
-```
-
-#### Local branches only
-```bash
-cursorflow clean branches --pattern "feature/*" --local-only
-```
-
-### Worktree cleanup
-
-#### All worktrees
-```bash
-cursorflow clean worktrees --all
-```
-
-#### Specific pattern
-```bash
-cursorflow clean worktrees --pattern "*-dashboard-*"
-```
-
-### Log cleanup
-
-#### Logs older than 30 days
+### Review before deleting
 ```bash
-cursorflow clean logs --older-than 30
+cursorflow clean all --dry-run
 ```
 
-#### All logs
+### Clean only worktrees
 ```bash
-cursorflow clean logs --all --force
+cursorflow clean worktrees
 ```
 
-### Full cleanup
-
-#### Review then delete
+### Force clean everything
 ```bash
-cursorflow clean all --dry-run
 cursorflow clean all --force
 ```
 
-## Sample output
-
-```
-🧹 Cleaning CursorFlow Resources
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Branches to delete:
-  - feature/dashboard-pipeline-abc123 (local)
-  - feature/dashboard-pipeline-abc123 (remote)
-  - feature/client-pipeline-def456 (local)
-
-Worktrees to remove:
-  - .cursorflow/logs/worktrees/01-dashboard-pipeline-abc123
-  - .cursorflow/logs/worktrees/02-client-pipeline-def456
-
-Logs to delete:
-  - _cursorflow/logs/runs/01-dashboard-2025-12-10T10-00-00 (9 days old)
-
-Total: 5 branches, 2 worktrees, 1 log directory
-
-Proceed? [y/N]
-```
-
 ## Notes
 
-1. **Back up**: Save important branches before deleting.
-2. **Confirm**: Start with `--dry-run` to review changes.
-3. **Remote caution**: Be careful when deleting remote branches.
-4. **Irreversible**: Deleted items are hard to recover.
-
-## Checklist
-- [ ] Have you reviewed items to clean?
-- [ ] Do you need backups?
-- [ ] Did you run a dry run first?
-- [ ] Are other teammates using these branches?
-- [ ] Do you also need to delete from the remote?
-
-## Troubleshooting
-
-### Branch deletion failed
-```bash
-# Force delete
-git branch -D <branch-name>
-git push origin --delete <branch-name>
-```
-
-### Worktree removal failed
-```bash
-# Force remove
-git worktree remove --force <worktree-path>
-```
-
-### Log directory permission issues
-```bash
-# Check permissions
-ls -la _cursorflow/logs/
-# Fix permissions
-chmod -R u+w _cursorflow/logs/
-```
-
-## Next steps
-1. Clean logs regularly (e.g., monthly).
-2. Add an automated cleanup script to CI/CD.
-3. Add log directories to `.gitignore`.
+1. **Safety**: It is highly recommended to run with `--dry-run` first to see exactly what will be deleted.
+2. **Worktrees**: The command identifies CursorFlow worktrees by their location (usually in `_cursorflow/worktrees/`) or their prefix.
+3. **Branches**: Only branches starting with the configured `branchPrefix` (default: `cursorflow/`) are targeted.
+4. **Irreversible**: Once logs are deleted, they cannot be recovered.

package/commands/cursorflow-doctor.md

@@ -1,24 +1,80 @@
-# /cursorflow-doctor
+# CursorFlow Doctor
 
-## Goal
-Verify that the current environment is properly configured for CursorFlow.
+## Overview
+Verify that your environment and task configurations are properly set up for CursorFlow.
 
 ## Usage
-1. Type `/cursorflow-doctor` in the chat.
-2. The agent will check:
-   - Git repository status
-   - 'origin' remote availability
-   - Git worktree support
-   - Cursor Agent installation and authentication
-   - Task directory and lane file validity (if a path is provided)
-
-## Context
-Use this command whenever:
-- You are setting up a new project with CursorFlow.
-- A `cursorflow run` fails with environment-related errors.
-- You want to verify your Cursor authentication status.
+
+```bash
+cursorflow doctor [options]
+```
+
+## Checks Performed
+- **Environment**: Git repository status, remote availability, and worktree support.
+- **Cursor IDE**: Verifies `cursor-agent` is installed and authenticated.
+- **Tasks**: (Optional) Validates task JSON files for schema errors or missing fields.
+
+## Options
+
+| Option | Description |
+|------|------|
+| `--tasks-dir <path>` | Validate lane files in a specific directory |
+| `--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 |
+
+## Task Validation
+
+When `--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.acceptanceCriteria**: Optional, must be non-empty array if provided
+
+### Dependency Validation (DAG)
+- **Unknown dependencies**: Reports if `dependsOn` references non-existent lanes
+- **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
+- **Naming suggestions**: Recommends using lane numbers in branch prefixes for consistency
+
+Example errors:
+```
+❌ Branch prefix collision
+   Multiple lanes use the same branchPrefix "feature/lane-1-": 01-lane-1, 02-lane-2
+   Fix: Update the branchPrefix in each lane JSON file to be unique
+
+⚠️ Existing branches may conflict with 01-lane-1
+   Found 2 existing branch(es) matching prefix "feature/lane-1-": feature/lane-1-abc, feature/lane-1-xyz
+   Fix: Delete conflicting branches or change the branchPrefix
+```
 
 ## Example
-"Check if my environment is ready for CursorFlow."
-"Run cursorflow doctor on the _cursorflow/tasks/my-feature/ directory."
 
+```bash
+# Basic environment check
+cursorflow doctor
+
+# Test agent permissions
+cursorflow doctor --test-agent
+
+# Validate a specific task set
+cursorflow doctor --tasks-dir _cursorflow/tasks/my-feature/
+```
+
+## 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. |

package/commands/cursorflow-init.md

@@ -1,67 +1,50 @@
 # CursorFlow Init
 
 ## Overview
-Initialize CursorFlow in your project. Create the config file and directory structure, and optionally install Cursor commands and example tasks.
+Initialize CursorFlow in your project. This command creates the default configuration file, sets up the required directory structure, and prepares the environment for parallel AI orchestration.
 
-## Steps
+## Usage
 
-1. **Run initialization**
-   ```bash
-   cursorflow init
-   ```
+```bash
+cursorflow init [options]
+```
 
-2. **Choose options**
-   - `--example`: create example tasks
-   - `--config-only`: create only the config file
-   - `--no-commands`: skip installing Cursor commands
-   - `--force`: overwrite existing files
+## Options
 
-3. **Verify created files**
-   - `cursorflow.config.js` created
-   - `_cursorflow/tasks/` directory created
-   - `_cursorflow/logs/` directory created
-   - `.cursor/commands/cursorflow/` commands installed (optional)
+| Option | Description |
+|------|------|
+| `--example` | Create an example task to help you get started |
+| `--config-only` | Only create the `cursorflow.config.js` file |
+| `--no-commands` | Skip installing Cursor IDE custom commands |
+| `--no-gitignore` | Skip adding `_cursorflow/` to your `.gitignore` |
+| `--force` | Overwrite existing configuration or directories |
 
-4. **Review the config file**
-   ```javascript
-   // cursorflow.config.js
-   module.exports = {
-     tasksDir: '_cursorflow/tasks',
-     logsDir: '_cursorflow/logs',
-     baseBranch: 'main',
-     // ... other settings
-   };
-   ```
+## What's Created?
 
-## Examples
+1. **`cursorflow.config.js`**: Central configuration for the project.
+2. **`_cursorflow/tasks/`**: Directory where you define your task JSON files.
+3. **`_cursorflow/logs/`**: Directory for run logs and terminal outputs.
+4. **`.cursor/commands/cursorflow/`**: (Optional) Integrated Cursor IDE commands.
+5. **`.gitignore` update**: Adds `_cursorflow/` to prevent committing logs.
 
-### Basic initialization
-```bash
-cursorflow init
-```
+## Example
 
-### Include example tasks
 ```bash
+# Standard initialization with an example task
 cursorflow init --example
-```
 
-### Generate only the config
-```bash
-cursorflow init --config-only
-```
-
-### Overwrite existing files
-```bash
-cursorflow init --force
+# Minimal initialization
+cursorflow init --no-commands --no-gitignore
 ```
 
-## Checklist
-- [ ] Was the config file created at the project root?
-- [ ] Were the required directories created?
-- [ ] Were Cursor commands installed?
-- [ ] Is the configuration adjusted for the project?
+## Next Steps
 
-## Next steps
-1. Update `cursorflow.config.js` for your project.
-2. In Cursor IDE, type `/` to confirm the commands are available.
-3. Start generating tasks with `cursorflow prepare MyFeature`.
+1. **Configure**: Review `cursorflow.config.js` and adjust settings like `baseBranch` or `maxConcurrentLanes`.
+2. **Explore**: If you used `--example`, run it with:
+   ```bash
+   cursorflow run _cursorflow/tasks/example/
+   ```
+3. **Create**: Start your own feature tasks with:
+   ```bash
+   cursorflow prepare MyFeature
+   ```

package/commands/cursorflow-models.md

@@ -0,0 +1,51 @@
+# 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,131 +1,69 @@
 # CursorFlow Monitor
 
 ## Overview
-Monitor lane execution status. Track progress in real time and inspect logs.
+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.
 
-## Steps
+## Usage
 
-1. **Monitor in real time**
-   ```bash
-   cursorflow monitor --watch
-   ```
-
-2. **Monitor a specific run**
-   ```bash
-   cursorflow monitor _cursorflow/logs/runs/my-run/
-   ```
-
-3. **Check status**
-
-   Lane status values:
-   - pending: waiting
-   - running: in progress
-   - completed: finished
-   - failed: failed
-   - blocked_dependency: waiting on dependencies
-
-4. **Inspect logs**
-
-   Per-lane log files:
-   - `state.json`: current status
-   - `conversation.jsonl`: agent conversation
-   - `git-operations.jsonl`: Git activity
-   - `events.jsonl`: event log
-
-## Options
-
-| Option | Description |
-|------|------|
-| `--watch` | Refresh in real time (every 2 seconds) |
-| `--interval <sec>` | Refresh interval in seconds |
-| `--json` | Output in JSON format |
-
-## Examples
-
-### Monitor the latest run
-```bash
-cursorflow monitor
-```
-
-### Real-time monitoring (5-second interval)
-```bash
-cursorflow monitor --watch --interval 5
-```
-
-### JSON output
-```bash
-cursorflow monitor --json | jq
-```
-
-## Sample output
-
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-  📡 Lane Status Monitoring
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Run: 01-dashboard-2025-12-19T18-30-00
-
-- 01-dashboard: running (2/3)
-- 02-client: completed (3/3)
-- 03-projects: blocked_dependency (1/2)
-```
-
-## Viewing logs
-
-### Conversation history
 ```bash
-cat _cursorflow/logs/runs/01-dashboard-xxx/conversation.jsonl | jq
-```
+# Monitor the most recent run
+cursorflow monitor latest
 
-### Git activity log
-```bash
-cat _cursorflow/logs/runs/01-dashboard-xxx/git-operations.jsonl | jq
+# Monitor a specific run directory
+cursorflow monitor _cursorflow/logs/runs/run-2025-12-21T10-00-00
 ```
 
-### Event log
-```bash
-cat _cursorflow/logs/runs/01-dashboard-xxx/events.jsonl | jq
-```
-
-## Status analysis
-
-### Progress per lane
-```bash
-# Inspect state.json for all lanes
-for state in _cursorflow/logs/runs/*/lanes/*/state.json; do
-  echo "$(dirname $state):"
-  jq '.status, .currentTaskIndex, .totalTasks' $state
-done
-```
-
-### Find failed lanes
-```bash
-# Lanes where status is failed
-find _cursorflow/logs/runs -name "state.json" -exec sh -c \
-  'jq -r "select(.status==\"failed\") | .label" {}' \;
-```
-
-## Checklist
-- [ ] Are lane states healthy?
-- [ ] Did any errors occur?
-- [ ] Have the logs been reviewed?
-- [ ] Are any lanes blocked?
-- [ ] Are there dependency issues?
+## 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).
+- **Quit**: Press `Q` to exit.
+
+### 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. Check status in `state.json`.
-2. Inspect the last conversation in `conversation.jsonl`.
-3. Resume if needed with `cursorflow resume <lane>`.
-
-### Logs are missing
-1. Confirm the run actually started.
-2. Check log directory permissions.
-3. Verify the `logsDir` path in the config file.
-
-## Next steps
-1. If you find issues, resume with `cursorflow resume`.
-2. Review PRs for completed lanes.
-3. Analyze logs to identify improvements.
+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.