@litmers/cursorflow-orchestrator 0.1.9 → 0.1.13

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

@@ -3,87 +3,67 @@
 ## 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.
 
-## Steps
-
-1. **Launch the interactive dashboard**
-   ```bash
-   # Monitor the most recent run
-   cursorflow monitor latest
-   ```
-
-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/run-2025-12-21T10-00-00
-   ```
-
-## Key Views
-
-### 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).
+## Usage
 
-### Dependency Flow View
-A visual map of how tasks relate to each other. It shows which lanes must finish before others can start.
-
-### 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.
-
-### 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 `↓`.
+```bash
+# Monitor the most recent run
+cursorflow monitor latest
 
-### Heartbeat Logs
-During execution, CursorFlow outputs heartbeat messages every 30 seconds:
-```
-⏱ Heartbeat: 30s elapsed, 1234 bytes received
-⏱ Heartbeat: 60s elapsed, 5678 bytes received
+# Monitor a specific run directory
+cursorflow monitor _cursorflow/logs/runs/run-2025-12-21T10-00-00
 ```
 
-This helps you:
-- Track progress of long-running tasks
-- Identify stalled or hanging processes (0 bytes received)
-- Estimate completion time
+## Dashboard Controls
 
-## Troubleshooting
+### 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 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.
+### 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.
 
-### Intervention needed
-If the agent is making a mistake or needs clarification:
+### 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 |
 
-> ⚠️ **Note**: Intervention requires `enableIntervention: true` in your task configuration!
+### 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.
 
-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.
+### 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.
 
-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.
+## Troubleshooting
 
-**To enable intervention in your task JSON:**
-```json
-{
-  "enableIntervention": true,
-  "tasks": [...]
-}
-```
+### 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.
 
-## Next steps
-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.
+### 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.