@litmers/cursorflow-orchestrator 0.1.6 → 0.1.9

package/commands/cursorflow-monitor.md

@@ -1,131 +1,89 @@
 # 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
 
-1. **Monitor in real time**
+1. **Launch the interactive dashboard**
    ```bash
-   cursorflow monitor --watch
+   # Monitor the most recent run
+   cursorflow monitor latest
    ```
 
-2. **Monitor a specific run**
+2. **Dashboard Controls**
+   - **Navigation**: Use `↑` and `↓` to move between lanes.
+   - **Details**: Press `→` or `Enter` to see task progress, conversation history, and more.
+   - **Flow View**: Press `F` (from list view) to see the Directed Acyclic Graph (DAG) of task dependencies.
+   - **Live Terminal**: Press `T` (from lane detail) to stream the real-time output of the AI agent.
+   - **Intervention**: Press `I` (from lane detail) to send a manual prompt to a running agent.
+   - **Kill Process**: Press `K` (from lane detail) to forcefully terminate a stuck agent.
+   - **Back**: Use `←` or `Esc` to navigate back to previous screens.
+   - **Quit**: Press `Q` to exit.
+
+3. **Monitor a specific run directory**
    ```bash
-   cursorflow monitor _cursorflow/logs/runs/my-run/
+   cursorflow monitor _cursorflow/logs/runs/run-2025-12-21T10-00-00
    ```
 
-3. **Check status**
+## Key Views
 
-   Lane status values:
-   - pending: waiting
-   - running: in progress
-   - completed: finished
-   - failed: failed
-   - blocked_dependency: waiting on dependencies
+### List View
+Shows an overview of all lanes, their status (pending, running, completed, failed, blocked), progress percentage, elapsed time, and "Next Action" (what it's waiting for or what it unlocks).
 
-4. **Inspect logs**
+### Dependency Flow View
+A visual map of how tasks relate to each other. It shows which lanes must finish before others can start.
 
-   Per-lane log files:
-   - `state.json`: current status
-   - `conversation.jsonl`: agent conversation
-   - `git-operations.jsonl`: Git activity
-   - `events.jsonl`: event log
+### Lane Detail View
+Displays:
+- **Status & Progress**: Current task index and total tasks.
+- **PID**: The process ID of the running `cursor-agent`.
+- **Live Terminal (Preview)**: The last few lines of the agent's output.
+- **Conversation History**: A scrollable list of messages between the system and the agent. Select a message to see its full content.
 
-## Options
+### Full Terminal View
+A dedicated view that acts like `tail -f` for the agent's log. You can scroll up/down through the history using `↑` and `↓`.
 
-| 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
+### Heartbeat Logs
+During execution, CursorFlow outputs heartbeat messages every 30 seconds:
 ```
-
-## Sample output
-
+⏱ Heartbeat: 30s elapsed, 1234 bytes received
+⏱ Heartbeat: 60s elapsed, 5678 bytes received
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-  📡 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)
-```
+This helps you:
+- Track progress of long-running tasks
+- Identify stalled or hanging processes (0 bytes received)
+- Estimate completion time
 
-## Viewing logs
+## Troubleshooting
 
-### Conversation history
-```bash
-cat _cursorflow/logs/runs/01-dashboard-xxx/conversation.jsonl | jq
-```
+### Lane is stuck (Thinking too long)
+1. Enter the lane detail view.
+2. Check the **PID** to ensure the process is still alive.
+3. Check the **Live Terminal** to see if it's producing output.
+4. If it's truly stuck, press `K` to kill the process and then use `cursorflow resume` to restart it.
 
-### Git activity log
-```bash
-cat _cursorflow/logs/runs/01-dashboard-xxx/git-operations.jsonl | jq
-```
+### Intervention needed
+If the agent is making a mistake or needs clarification:
 
-### Event log
-```bash
-cat _cursorflow/logs/runs/01-dashboard-xxx/events.jsonl | jq
-```
+> ⚠️ **Note**: Intervention requires `enableIntervention: true` in your task configuration!
 
-## Status analysis
+1. Enter the lane detail view.
+2. Press `I`.
+3. Type your instructions (e.g., "Don't change the package.json, just fix the bug in utils.ts").
+4. Press `Enter` to send.
 
-### 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
-```
+If `enableIntervention` is enabled in your task JSON, the agent receives this as its next prompt. If not, the message is logged but not injected.
 
-### 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" {}' \;
+**To enable intervention in your task JSON:**
+```json
+{
+  "enableIntervention": true,
+  "tasks": [...]
+}
 ```
 
-## Checklist
-- [ ] Are lane states healthy?
-- [ ] Did any errors occur?
-- [ ] Have the logs been reviewed?
-- [ ] Are any lanes blocked?
-- [ ] Are there dependency issues?
-
-## 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. Once all lanes reach `completed`, you can review the generated branches.
+2. Use `cursorflow clean` to remove temporary worktrees after you've merged the changes.

package/commands/cursorflow-prepare.md

@@ -46,9 +46,15 @@ Prepare task files for a new feature by gathering requirements and generating la
      "branchPrefix": "<feature>/<lane>-",
      "executor": "cursor-agent",
      "autoCreatePr": false,
-     "allowDependencyChange": false,
-     "lockfileReadOnly": true,
      "pollInterval": 60,
+     
+     "timeout": 300000,
+     "enableIntervention": false,
+
+     "dependencyPolicy": {
+       "allowDependencyChange": false,
+       "lockfileReadOnly": true
+     },
 
      "laneNumber": 1,
      "devPort": 3001,
@@ -70,6 +76,19 @@ Prepare task files for a new feature by gathering requirements and generating la
    }
    ```
 
+   **Key Configuration Options:**
+
+   | Option | Type | Default | Description |
+   |--------|------|---------|-------------|
+   | `timeout` | number | 300000 | Task timeout in milliseconds |
+   | `enableIntervention` | boolean | false | Enable stdin piping for intervention |
+   | `dependsOn` | string[] | [] | Lane dependencies |
+
+   **Timeout Guidelines:**
+   - Simple tasks: `60000` (1 min)
+   - Medium tasks: `300000` (5 min) - default
+   - Complex tasks: `600000` (10 min)
+
 4. **Model selection guide**
 
    | Model | Purpose | Notes |
@@ -121,12 +140,16 @@ cursorflow prepare MyFeature --template ./my-template.json
 - [ ] Have dependency changes been confirmed?
 - [ ] Are the acceptance criteria clear?
 - [ ] Have the generated files been reviewed?
+- [ ] Are task names valid (letters, numbers, `-`, `_` only)?
+- [ ] Is the timeout appropriate for task complexity?
 
 ## Notes
 1. **Model names**: Use only valid models (check with the `models` command).
 2. **Paths**: Always create tasks under `_cursorflow/tasks/`.
 3. **Branch prefix**: Make it unique to avoid collisions.
 4. **devPort**: Use unique ports per lane (3001, 3002, ...).
+5. **Task names**: Must only contain letters, numbers, `-`, `_`. No spaces or special characters.
+6. **Timeout**: Set based on task complexity. See timeout guidelines above.
 
 ## Next steps
 1. Tailor the generated JSON files to the project.

package/commands/cursorflow-resume.md

@@ -163,6 +163,17 @@ git commit -m "fix: build error"
 cursorflow resume 01-dashboard
 ```
 
+### Scenario 5: Timeout errors
+If the lane failed due to timeout:
+1. Increase the timeout in your task JSON:
+   ```json
+   { "timeout": 600000 }
+   ```
+2. Resume the lane:
+   ```bash
+   cursorflow resume 01-dashboard
+   ```
+
 ### Scenario 3: Branch conflicts
 ```bash
 # Clean branches then restart

package/commands/cursorflow-run.md

@@ -1,129 +1,138 @@
 # CursorFlow Run
 
 ## Overview
-Execute prepared tasks with single-lane or multi-lane orchestration.
+Execute the AI agent orchestration for a set of tasks. CursorFlow uses a sophisticated DAG (Directed Acyclic Graph) scheduler to handle dependencies between tasks and ensure they run in the correct order.
 
-## Steps
+## Usage
 
-1. **Check the task directory**
-   ```bash
-   ls _cursorflow/tasks/
-   ```
-
-2. **Run multiple lanes**
-   ```bash
-   cursorflow run _cursorflow/tasks/MyFeature/
-   ```
-
-3. **Run a single lane**
-   ```bash
-   cursorflow lane _cursorflow/tasks/MyFeature/01-task.json
-   ```
-
-4. **Dry run (preview the plan)**
-   ```bash
-   cursorflow run _cursorflow/tasks/MyFeature/ --dry-run
-   ```
+```bash
+cursorflow run <tasks-dir> [options]
+```
 
-5. **Monitor execution**
+## How it works
 
-   Watch progress from another terminal while the run is in progress:
-   ```bash
-   cursorflow monitor --watch
-   ```
+1. **Validation**: CursorFlow validates all task configurations before starting.
+2. **Task Loading**: Scans the specified directory for `.json` task files.
+3. **Dependency Resolution**: Builds a graph based on the `dependsOn` field in each task.
+4. **Execution**:
+   - Lanes with no unmet dependencies are started first.
+   - When a lane completes, it unlocks dependent lanes.
+   - Dependent lanes automatically merge the parent's branch before starting their first task.
+5. **Monitoring**: Heartbeat logs every 30 seconds show progress.
+6. **Concurrency**: Respects `maxConcurrentLanes` (set in `cursorflow.config.js`) to prevent overloading system resources.
 
 ## Options
 
 | Option | Description |
 |------|------|
-| `--dry-run` | Preview the plan without executing |
-| `--executor <type>` | Execution mode (`cursor-agent` \| `cloud`) |
-| `--no-review` | Disable code review |
-| `--config <path>` | Use a custom config file |
-
-## Examples
-
-### Standard run
-```bash
-cursorflow run _cursorflow/tasks/2512191700_MyFeature/
-```
-
-### Cloud run (requires API key)
-```bash
-export CURSOR_API_KEY=your_key
-cursorflow run _cursorflow/tasks/MyFeature/ --executor cloud
+| `<tasks-dir>` | Directory containing task JSON files (e.g., `_cursorflow/tasks/feature-x/`) |
+| `--max-concurrent <num>` | Limit the number of parallel agents (overrides config) |
+| `--dry-run` | Show the execution plan and dependency graph without starting agents |
+
+## Task Definition (JSON)
+
+### Full Configuration Schema
+
+```json
+{
+  "baseBranch": "main",
+  "branchPrefix": "cursorflow/feature-",
+  "model": "sonnet-4.5",
+  "timeout": 300000,
+  "enableIntervention": false,
+  "dependsOn": ["other-lane"],
+  "dependencyPolicy": {
+    "allowDependencyChange": false,
+    "lockfileReadOnly": true
+  },
+  "tasks": [
+    {
+      "name": "implement-feature",
+      "model": "gemini-3-flash",
+      "prompt": "Create a reusable button component..."
+    }
+  ]
+}
 ```
 
-### Fast run without review
-```bash
-cursorflow run _cursorflow/tasks/MyFeature/ --no-review
+### Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `timeout` | number | 300000 | Task timeout in milliseconds |
+| `enableIntervention` | boolean | false | Enable stdin piping for intervention feature |
+| `model` | string | "sonnet-4.5" | Default AI model for all tasks |
+| `dependsOn` | string[] | [] | Lane dependencies to merge before starting |
+| `baseBranch` | string | "main" | Base branch for worktree |
+| `branchPrefix` | string | "cursorflow/" | Prefix for created branches |
+
+### Task Options
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `name` | string | ✅ | Unique task identifier (alphanumeric, `-`, `_` only) |
+| `prompt` | string | ✅ | Task prompt for the AI agent |
+| `model` | string | ❌ | Override model for this specific task |
+
+### Example with Dependencies
+
+```json
+{
+  "name": "ui-components",
+  "dependsOn": ["theme-engine", "common-utils"],
+  "timeout": 600000,
+  "tasks": [
+    {
+      "name": "implement-button",
+      "prompt": "Create a reusable button component using the theme engine..."
+    }
+  ]
+}
 ```
 
-## Execution process
+## Validation Errors
 
-1. **Initialization**
-   - Load configuration
-   - Verify the `cursor-agent` CLI
-   - Confirm Git repository status
+CursorFlow validates task files before execution and provides helpful error messages:
 
-2. **Prepare lanes**
-   - Create worktrees
-   - Check out branches
-   - Configure the environment
+| Error | Solution |
+|-------|----------|
+| `Task N missing required "name" field` | Add `"name": "task-name"` to each task |
+| `Task name contains invalid characters` | Use only letters, numbers, `-`, `_` |
+| `"timeout" must be a positive number` | Provide timeout as milliseconds (e.g., `60000`) |
 
-3. **Run tasks**
-   - Execute tasks sequentially
-   - Commit after each task
-   - Trigger automatic review when enabled
+## Progress Monitoring
 
-4. **Complete**
-   - Push changes
-   - Create a PR (depending on settings)
-   - Store logs
-
-## Log location
-
-Run logs are stored in `_cursorflow/logs/runs/`:
+During execution, CursorFlow outputs heartbeat logs every 30 seconds:
 
 ```
-_cursorflow/logs/runs/<lane>-<timestamp>/
-├── state.json              # Lane status
-├── results.json            # Task results
-├── conversation.jsonl      # Agent conversation
-├── git-operations.jsonl    # Git activity log
-└── events.jsonl            # Event log
+⏱ Heartbeat: 30s elapsed, 1234 bytes received
+⏱ Heartbeat: 60s elapsed, 5678 bytes received
 ```
 
-## Checklist
-- [ ] Is the `cursor-agent` CLI installed?
-- [ ] Are Git worktrees available?
-- [ ] Are the task files valid?
-- [ ] Do branch names avoid collisions?
-- [ ] Are required environment variables set? (for cloud runs)
+This helps identify:
+- Long-running tasks
+- Stalled or hanging processes
+- Network issues (0 bytes received)
 
-## Troubleshooting
+## Best Practices
 
-### Branch conflicts
-```bash
-# Clean up existing branches
-cursorflow clean branches --pattern "feature/my-*"
-```
+### Sequential Workflows
+For tasks that must happen one after another, chain them using `dependsOn`. CursorFlow will handle the branch merges automatically.
 
-### Worktree conflicts
-```bash
-# Clean up existing worktrees
-cursorflow clean worktrees --all
-```
+### Parallel Workflows
+Tasks that don't depend on each other will run in parallel up to the `maxConcurrentLanes` limit.
 
-### Run failures
-```bash
-# Inspect logs
-cursorflow monitor
-# or
-cat _cursorflow/logs/runs/latest/*/state.json
-```
+### Monitoring
+Always use `cursorflow monitor latest` in a separate terminal to keep track of the run.
+
+## Troubleshooting
+
+### Deadlocks
+If you create circular dependencies (e.g., A depends on B, and B depends on A), CursorFlow will detect the deadlock at startup and refuse to run.
 
-## Next steps
-1. Monitor progress with `cursorflow monitor --watch`.
-2. Review the PR when the run completes.
-3. If a run fails, resume with `cursorflow resume <lane>`.
+### Merge Conflicts
+If a parent lane and a child lane modify the same lines, a merge conflict might occur when the child starts.
+1. The monitor will show the lane as `failed` with a merge error.
+2. Go to the lane's worktree (found in the monitor detail).
+3. Manually resolve the conflict.
+4. Run `cursorflow resume <lane>` to continue.

package/commands/cursorflow-signal.md

@@ -1,19 +1,90 @@
-# /cursorflow-signal
+# CursorFlow Signal & Intervention
 
-## Goal
-Directly intervene in a running lane to provide guidance, corrections, or emergency stops.
+## Overview
+Directly intervene in a running lane to provide guidance, corrections, or mid-task instructions. This is one of CursorFlow's most powerful features for "human-in-the-loop" AI orchestration.
 
-## Usage
-1. Type `/cursorflow-signal <lane-name> <your-message>` in the chat.
-2. The message will be injected into the lane's conversation as a high-priority system instruction.
+## ⚠️ Prerequisites
 
-## Context
-Use this command when:
-- You see an agent making a repeated mistake in the monitor.
-- You want to provide specific implementation guidance mid-task.
-- You need to tell the agent to stop or change direction without killing the process.
+**Intervention requires `enableIntervention: true` in your task configuration!**
 
-## Example
-"Send a signal to lane-1: 'Stop using library X, use library Y instead.'"
-"Intervene in backend-lane: 'The database schema changed, please pull the latest main branch.'"
+```json
+{
+  "enableIntervention": true,
+  "tasks": [...]
+}
+```
 
+> **Note**: Enabling intervention uses stdin piping, which may cause stdout buffering issues on some systems. If you experience timeout issues, try disabling intervention.
+
+## Methods of Intervention
+
+### 1. via Interactive Monitor (Recommended)
+The easiest way to intervene is through the dashboard:
+1. Run `cursorflow monitor latest`.
+2. Enter the lane detail view (`→`).
+3. Press **`I`**.
+4. Type your message and press **Enter**.
+
+### 2. via CLI / Cursor Command
+You can also send a signal from any terminal or via the Cursor chat:
+```bash
+cursorflow signal <lane-name> "Your message here"
+```
+
+## When to use it
+- **Guidance**: "Focus on the `utils/` directory first."
+- **Correction**: "You are using the wrong API version. Use v2 instead."
+- **Emergency**: "Stop! I just found a critical bug in the base branch."
+- **Clarification**: If the agent is stuck or asking a question in its log.
+
+## How it works
+1. Your message is written to an `intervention.txt` file in the lane's log directory.
+2. The CursorFlow runner, which is watching this file, detects the change.
+3. **If `enableIntervention: true`**: It immediately injects your message into the `cursor-agent`'s standard input (stdin).
+4. **If `enableIntervention: false`**: The message is logged but cannot be injected (warning displayed).
+
+## Configuration
+
+### Enable Intervention
+
+```json
+{
+  "enableIntervention": true,
+  "timeout": 300000,
+  "tasks": [
+    {
+      "name": "my-task",
+      "prompt": "..."
+    }
+  ]
+}
+```
+
+### Default Behavior (Intervention Disabled)
+
+By default, `enableIntervention` is `false` to avoid potential buffering issues. When disabled:
+- Signal commands will still work but messages are **logged only**
+- The agent will **not receive** the injected message
+- A warning will be shown: `Intervention requested but stdin not available`
+
+## PID Control (Emergency Stop)
+If an intervention isn't enough and the agent is "looping" or stuck:
+- In the monitor, press **`K`** to kill the process via its PID.
+- This is a hard stop and will immediately terminate the `cursor-agent` for that lane.
+
+## Troubleshooting
+
+### "Intervention requested but stdin not available"
+
+This means `enableIntervention` is not set to `true` in your task JSON.
+
+**Solution**: Add `"enableIntervention": true` to your task configuration.
+
+### Intervention causes timeout
+
+On some systems, enabling stdin piping can cause stdout buffering issues.
+
+**Solution**: 
+1. Disable intervention: `"enableIntervention": false`
+2. Increase timeout: `"timeout": 600000`
+3. Use `K` (Kill) in monitor for emergency stops instead

package/dist/cli/clean.d.ts

@@ -1,5 +1,7 @@
 /**
- * CursorFlow clean command (stub)
+ * CursorFlow clean command
+ *
+ * Clean up worktrees, branches, and logs created by CursorFlow
  */
 declare function clean(args: string[]): Promise<void>;
 export = clean;