@litmers/cursorflow-orchestrator 0.1.36 → 0.1.39

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.

package/commands/cursorflow-triggers.md

@@ -1,250 +0,0 @@
-# CursorFlow Event Triggers & Webhooks
-
-## Overview
-
-CursorFlow emits various status changes during the orchestration process as **Events**. Through this event system, you can send notifications to external services (Webhooks) or execute custom logic to automate complex workflows.
-
-## Key Concepts
-
-### 1. Events
-Occurrences during the lifecycle of the orchestrator, lanes, tasks, agents, and reviewers. Each event has a unique type and payload.
-
-### 2. Webhooks
-A mechanism to send emitted events to external HTTP endpoints. Configured via `cursorflow.config.js`, allowing you to filter for specific events.
-
-### 3. Dependency Triggers
-Internally, when a lane completes, any subsequent lanes that depend on it are automatically executed (triggered). This is managed by the DAG (Directed Acyclic Graph) scheduler.
-
-## Supported Events
-
-| Category | Event Type | Occurrence |
-| :--- | :--- | :--- |
-| **Orchestration** | `orchestration.started` | When the entire workflow begins |
-| | `orchestration.completed` | When all lanes complete successfully |
-| | `orchestration.failed` | When an error occurs during the workflow |
-| **Lane** | `lane.started` | When an individual lane starts execution |
-| | `lane.completed` | When all tasks in a lane are finished |
-| | `lane.failed` | When an error occurs during lane execution |
-| | `lane.dependency_requested` | When an agent requests to modify external dependencies |
-| **Task** | `task.started` | When an individual task within a lane begins |
-| | `task.completed` | When a task succeeds |
-| | `task.failed` | When a task fails |
-| **Agent** | `agent.prompt_sent` | When a prompt is sent to the AI agent |
-| | `agent.response_received` | When a response is received from the AI agent |
-| **Review** | `review.started` | When the AI review process begins |
-| | `review.completed` | When the AI review completes (includes results) |
-| | `review.approved` | When a review is approved |
-| | `review.rejected` | When a review is rejected and a retry is determined |
-
-## Common Event Structure
-
-All events passed to listeners have the following common wrapper structure:
-
-```typescript
-{
-  "id": "evt_1734842400000_abc123", // Unique event ID
-  "type": "task.completed",           // Event type
-  "timestamp": "2024-12-22T10:00:00.000Z", // Timestamp (ISO 8601)
-  "runId": "run-1734842400000",       // Current orchestration run ID
-  "payload": { ... }                  // Event-specific data (see below)
-}
-```
-
-## Event Payload Details
-
-### 1. Orchestration
-
-#### `orchestration.started`
-- `runId`: Unique run ID
-- `tasksDir`: Path to the directory containing task configuration files
-- `laneCount`: Total number of lanes to be executed
-- `runRoot`: Root directory where logs and status files are stored
-
-#### `orchestration.completed`
-- `runId`: Unique run ID
-- `laneCount`: Total number of lanes
-- `completedCount`: Number of successfully completed lanes
-- `failedCount`: Number of failed lanes
-
-#### `orchestration.failed`
-- `error`: Error message
-- `blockedLanes`: (Optional) List of lane names that could not start due to dependency issues
-
-### 2. Lane
-
-#### `lane.started`
-- `laneName`: Name of the lane (filename)
-- `pid`: (Optional) Process ID of the child process running the lane
-- `logPath`: Path to the log file for this lane
-
-#### `lane.completed`
-- `laneName`: Name of the lane
-- `exitCode`: Exit code (0 for success)
-
-#### `lane.failed`
-- `laneName`: Name of the lane
-- `exitCode`: Exit code
-- `error`: Description of the failure cause
-
-#### `lane.dependency_requested`
-- `laneName`: Name of the lane that sent the request
-- `dependencyRequest`: Dependency modification plan (includes `reason`, `changes`, `commands`)
-
-### 3. Task
-
-#### `task.started`
-- `taskName`: Name of the task
-- `taskBranch`: Name of the Git branch being worked on
-- `index`: Task sequence index within the lane (starting from 0)
-- `timeout`: (Optional) Task-specific timeout in milliseconds
-
-#### `task.completed`
-- `taskName`: Name of the task
-- `taskBranch`: Name of the Git branch
-- `status`: Completion status (e.g., 'FINISHED')
-
-#### `task.failed`
-- `taskName`: Name of the task
-- `taskBranch`: Branch name
-- `error`: Error message from task execution
-
-### 4. Agent
-
-#### `agent.prompt_sent`
-- `taskName`: Current task name
-- `model`: AI model used
-- `promptLength`: Length of the sent prompt string
-
-#### `agent.response_received`
-- `taskName`: Task name
-- `ok`: Success flag (boolean)
-- `duration`: Time taken for AI response (milliseconds)
-- `responseLength`: Length of the received response string
-- `error`: (On failure) Error message
-
-### 5. Review
-
-#### `review.started`
-- `taskName`: Name of the task under review
-- `taskBranch`: Name of the branch under review
-
-#### `review.completed`
-- `taskName`: Task name
-- `status`: Review result (`'approved'` or `'needs_changes'`)
-- `issueCount`: Number of issues found
-- `summary`: Review summary content
-
-#### `review.approved`
-- `taskName`: Task name
-- `iterations`: Number of review iterations until final approval
-
-#### `review.rejected`
-- `taskName`: Task name
-- `reason`: Reason for rejection (summary of requested changes)
-- `iterations`: Current number of review iterations
-
-## Webhook Configuration
-
-Set up the `webhooks` array in your `cursorflow.config.js` file.
-
-```javascript
-module.exports = {
-  // ... other settings
-  webhooks: [
-    {
-      enabled: true,
-      url: 'https://your-api.com/webhooks/cursorflow',
-      secret: 'your-hmac-secret', // Secret for HMAC signature
-      events: ['lane.completed', 'orchestration.*'], // Event patterns to receive
-      headers: {
-        'X-Custom-Header': 'CursorFlow-Bot'
-      },
-      retries: 3,      // Number of retries on failure
-      timeoutMs: 5000  // Timeout setting
-    }
-  ]
-};
-```
-
-### Event Filtering Patterns
-- `*`: Receive all events
-- `lane.*`: Receive all lane-related events
-- `task.failed`: Receive only task failure events
-
-## Programmatic Event Listeners (Function Triggers)
-
-In addition to webhooks, you can register event listeners directly via Node.js code to execute custom logic. This is useful for running local scripts or complex conditional logic.
-
-### 1. Registering in `cursorflow.config.js`
-
-Since the `cursorflow run` command loads the configuration file, you can subscribe to events at this point.
-
-```javascript
-// cursorflow.config.js
-const { events } = require('@litmers/cursorflow-orchestrator');
-
-// Execute custom logic on task completion
-events.on('task.completed', (event) => {
-  const { taskName, taskBranch } = event.payload;
-  console.log(`[HOOK] Task completed: ${taskName} (Branch: ${taskBranch})`);
-  
-  // Example: Check if a specific file was created or update a local database
-});
-
-// Notify on entire orchestration failure
-events.on('orchestration.failed', (event) => {
-  console.error(`!!! Orchestration failed: ${event.payload.error}`);
-});
-
-module.exports = {
-  tasksDir: '_cursorflow/tasks',
-  // ... other configurations
-};
-```
-
-### 2. Usage in Custom Scripts
-
-If you are using CursorFlow as a library, you can call the `orchestrate` function directly and monitor events.
-
-```javascript
-const { orchestrate, events } = require('@litmers/cursorflow-orchestrator');
-
-async function runMyPipeline() {
-  // Register event listener
-  events.on('lane.started', (event) => {
-    console.log(`Lane started: ${event.payload.laneName}`);
-  });
-
-  // Execute orchestration
-  try {
-    await orchestrate('./my-tasks');
-    console.log('All tasks completed');
-  } catch (err) {
-    console.error('Error during orchestration', err);
-  }
-}
-
-runMyPipeline();
-```
-
-## Security & Verification
-
-When sending webhooks, you can verify the integrity of the payload using the `X-CursorFlow-Signature` header.
-
-- **Algorithm**: HMAC-SHA256
-- **Format**: `sha256=<hex_signature>`
-
-The receiver should hash the request body using the configured `secret` and verify it matches the signature in the header.
-
-## Use Cases
-
-1. **Slack/Discord Notifications**: Notify the team messenger on `orchestration.completed` or `lane.failed`.
-2. **Deployment Automation**: Execute an external script to deploy code to a staging environment once a specific lane completes.
-3. **Statistics Collection**: Record token usage or response times in a database via the `agent.response_received` event.
-4. **Dashboard Updates**: Reflect real-time status on an external monitoring dashboard.
-
-## Precautions
-
-- Webhook endpoints must support the `POST` method.
-- Payloads are sent in `application/json` format.
-- Consider network latency and set timeout and retry policies appropriately.