@litmers/cursorflow-orchestrator 0.1.8 → 0.1.9

package/CHANGELOG.md

@@ -5,6 +5,37 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.1.9] - 2025-12-21
+
+### Added
+- **Configurable Timeout**: Support for `timeout` field in task JSON to handle complex tasks.
+- **Improved Stdio Handling**: Optimized child process spawning with `ignore` stdin by default to prevent buffering issues.
+- **Task Validation**: Robust pre-flight validation of task JSON configurations with helpful error messages.
+- **Heartbeat Monitoring**: Real-time progress logging (elapsed time and bytes received) for long-running tasks.
+- **Diagnostic Tools**: Added `scripts/patches/test-cursor-agent.js` for direct agent testing and `_cursorflow/tasks/minimal-test/` for isolation.
+- **Enhanced Documentation**: New `docs/API.md` and `docs/TROUBLESHOOTING.md` with detailed configuration guides.
+
+### Fixed
+- **Intervention Stability**: Redesigned intervention to be optional (`enableIntervention: true`) to ensure maximum stability for default runs.
+- **Environment Safety**: Smarter `NODE_OPTIONS` handling that preserves user settings while removing problematic debugging flags.
+
+## [0.1.8] - 2025-12-21
+
+### Added
+- **Interactive Dashboard**: Full-screen interactive terminal monitor with lane navigation.
+- **Live Terminal Streaming**: Real-time streaming of `cursor-agent` output with scrollback support.
+- **Human Intervention**: UI for sending manual prompts to running agents via `I` key.
+- **PID Control**: Tracking of process IDs and force-kill (`K` key) functionality for stuck agents.
+- **Improved Visualization**: Color-coded logs and "Next Action" status in monitor.
+
+## [0.1.7] - 2025-12-21
+
+### Added
+- **Task Dependencies**: Implemented DAG (Directed Acyclic Graph) scheduler for complex workflows.
+- **Automatic Branch Merging**: Dependent lanes now automatically merge their parents' branches before starting.
+- **Deadlock Detection**: Prevention of circular task dependencies at startup.
+- **Concurrency Control**: `maxConcurrentLanes` support in orchestrator.
+
 ## [0.1.6] - 2025-12-21
 
 ### Added

package/README.md

@@ -9,360 +9,148 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)
 
-## Key Features
+## 🚀 Key Features
 
-- 🚀 **Parallel execution**: Run multiple lanes concurrently with Git worktrees
-- 🔍 **Automatic review**: AI-powered code review with iterative feedback
-- 📝 **Detailed logging**: Capture conversations, commits, and Git operations
-- 🔀 **Dependency management**: Automatic dependency gating and resume support
-- 🎯 **Per-lane ports**: Unique dev server ports for each lane
-- 💻 **Cursor integration**: Manage workflows directly inside the IDE with custom commands
-- 🛠️ **Config-driven**: Flexible project-specific configuration
-- 🔒 **Security-first**: Multi-layer automated security scanning before deployment
+- ⚡ **Parallel Execution**: Run multiple AI agents concurrently using isolated Git worktrees.
+- 🔗 **Task Dependencies (DAG)**: Define complex workflows where tasks wait for and merge their dependencies automatically.
+- 📊 **Interactive Dashboard**: A powerful terminal-based monitor to track all lanes, progress, and dependencies in real-time.
+- 📺 **Live Terminal Streaming**: Watch the AI agent's output as it happens with scrollable history.
+- 🙋 **Human Intervention**: Send direct messages to running agents to guide them or fix issues on the fly (requires `enableIntervention: true`).
+- 🛡️ **PID Control**: Track and manage agent processes directly from the dashboard.
+- 🔍 **Automatic Review**: AI-powered code review with iterative feedback loops.
+- 🔀 **Smart Merging**: Automatically merge completed feature branches into subsequent dependent lanes.
+- 🔒 **Security-First**: Automated security scanning and dependency policy enforcement.
 
-## Quick Start
+## 🛠️ Quick Start
 
-### Install
+### 1. Install
 
 ```bash
-# npm
+# npm (recommended)
 npm install -g @litmers/cursorflow-orchestrator
-
-# pnpm (recommended)
-pnpm add -g @litmers/cursorflow-orchestrator
-
-# yarn
-yarn global add @litmers/cursorflow-orchestrator
 ```
 
-### Requirements
-
-- **Node.js** >= 18.0.0
-- **Git** with worktree support
-- **cursor-agent CLI**: `npm install -g @cursor/agent`
-
-### Initialize a project
+### 2. Initialize
 
 ```bash
 cd your-project
 cursorflow init --example
 ```
 
-This command:
-1. Creates the `cursorflow.config.js` config file
-2. Creates `_cursorflow/tasks/` and `_cursorflow/logs/` directories
-3. Installs Cursor IDE commands
-4. Generates example tasks when `--example` is provided
-
-### Run the example
+### 3. Run & Monitor
 
 ```bash
-# Run example tasks
+# Start orchestration
 cursorflow run _cursorflow/tasks/example/
 
-# Monitor from another terminal
-cursorflow monitor --watch
+# Open the interactive dashboard (highly recommended!)
+cursorflow monitor latest
 ```
 
-## 🧪 Testing CursorFlow
-
-A complete demo project is included for testing with real LLM execution.
-
-### Quick Test
-
-```bash
-# From the CursorFlow repository root
-./test-cursorflow.sh setup   # Verify prerequisites
-./test-cursorflow.sh run     # Run demo with LLM
-./test-cursorflow.sh watch   # Monitor in real-time
-./test-cursorflow.sh clean   # Clean up after test
-```
-
-### What Gets Tested
-
-- ✅ Task orchestration with 2 parallel lanes
-- ✅ Git worktree creation and management
-- ✅ Real LLM execution (Claude Sonnet 4.5 via cursor-agent)
-- ✅ Branch creation and commits
-- ✅ Real-time monitoring with status updates
-- ✅ Complete log capture (conversation + terminal)
-
-### Demo Tasks
+## 🎮 Dashboard Controls
 
-1. **create-utils**: Creates `src/utils.js` with utility functions
-2. **add-tests**: Creates `src/utils.test.js` with simple tests
+Within the `cursorflow monitor` dashboard:
+- `↑/↓`: Navigate between lanes or scroll through logs.
+- `→ / Enter`: Enter detailed lane view.
+- `← / Esc`: Go back.
+- `F`: Toggle **Dependency Flow** view.
+- `T`: Open **Live Terminal Streaming**.
+- `I`: **Intervene** (send a message to the agent).
+- `K`: **Kill** the current agent process.
+- `Q`: Quit monitor.
 
-Each task runs ~1-2 minutes, demonstrating the full CursorFlow workflow.
+## ⚙️ Configuration
 
-**See**: `test-projects/demo-project/README.md` for detailed documentation.
+### Task Configuration Schema
 
-## 📚 Examples
-
-Ready-to-use examples are included in the `examples/` directory.
-
-### Demo Project
-
-A complete example demonstrating CursorFlow's core features:
-
-```bash
-# Copy example tasks to your project
-cd your-project
-cursorflow init
-cp -r /path/to/cursorflow/examples/demo-project/_cursorflow/tasks/demo-test _cursorflow/tasks/
-
-# Run the demo
-cursorflow run _cursorflow/tasks/demo-test/
-
-# Monitor in real-time
-cursorflow monitor --watch
+```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",
+      "prompt": "Implement the user authentication..."
+    }
+  ]
+}
 ```
 
-**Includes:**
-- 2 parallel tasks with real LLM execution
-- Complete documentation and setup instructions
-- Expected results and troubleshooting guide
-
-**See**: `examples/demo-project/README.md` for detailed instructions.
-
-**Browse more examples**: `examples/README.md`
+### Key Options
 
-## Cursor IDE Integration
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `timeout` | number | 300000 | Task timeout in milliseconds (5 min default) |
+| `enableIntervention` | boolean | false | Enable stdin piping for intervention |
+| `model` | string | "sonnet-4.5" | AI model to use |
+| `dependsOn` | string[] | [] | Lane dependencies |
 
-CursorFlow ships custom commands that are available directly inside Cursor IDE.
+### Timeout Configuration
 
-### Install commands
+Set custom timeouts based on task complexity:
 
-```bash
-# Installed automatically during init
-cursorflow init
-
-# Or install manually
-npx cursorflow-setup
+```json
+{
+  "timeout": 60000,
+  "tasks": [{ "name": "simple-task", "prompt": "..." }]
+}
 ```
 
-### Usage
+- **Simple tasks**: `60000` (1 minute)
+- **Medium tasks**: `300000` (5 minutes) - default
+- **Complex tasks**: `600000` (10 minutes)
 
-Type `/` in Cursor chat and use:
+### Task Validation
 
-- `/cursorflow-init` - initialize a project
-- `/cursorflow-prepare` - prepare tasks
-- `/cursorflow-run` - run orchestration
-- `/cursorflow-monitor` - monitor runs
-- `/cursorflow-clean` - clean resources
-- `/cursorflow-resume` - resume a lane
-- `/cursorflow-doctor` - verify environment
-- `/cursorflow-signal` - intervene in a lane
-- `/cursorflow-review` - configure or check reviews
+CursorFlow automatically validates your task configuration before execution:
 
-## CLI Commands
+- ✅ Required `name` and `prompt` fields
+- ✅ Valid task name format (letters, numbers, `-`, `_` only)
+- ✅ Proper timeout values
+- ✅ Helpful error messages with fix suggestions
 
-### Init
-```bash
-cursorflow init [options]
-  --example          Create example tasks
-  --with-commands    Install Cursor commands (default: true)
-  --config-only      Generate config file only
-```
-
-### Prepare tasks
-```bash
-cursorflow prepare <feature> [options]
-  --lanes <number>   Number of lanes
-  --template <path>  Template file path
-```
-
-### Run
-```bash
-cursorflow run <tasks-dir> [options]
-  --dry-run          Show the execution plan only
-  --executor <type>  cursor-agent | cloud
-```
-
-### Monitor
-```bash
-cursorflow monitor [run-dir] [options]
-  --watch            Live monitoring
-  --interval <sec>   Refresh interval
-```
-
-### Clean
-```bash
-cursorflow clean <type> [options]
-  branches          Clean branches
-  worktrees         Clean worktrees
-  logs              Clean logs
-  all               Clean everything
-```
+### Progress Monitoring (Heartbeat)
 
-### Resume
-```bash
-cursorflow resume <lane> [options]
-  --run-dir <path>   Specify run directory
-  --restart          Restart from task 1
-```
+During execution, CursorFlow logs progress every 30 seconds:
 
-### Doctor
-```bash
-cursorflow doctor [options]
-  --tasks-dir <path> Validate specific lane tasks
-  --json             Output in JSON format
 ```
-
-### Signal (Intervention)
-```bash
-cursorflow signal <lane> <message>
-  --run-dir <path>   Specify run directory
+⏱ Heartbeat: 30s elapsed, 1234 bytes received
+⏱ Heartbeat: 60s elapsed, 5678 bytes received
 ```
 
-## 🚀 Deployment & Updates
-
-### For Maintainers
-To release a new version to NPM:
-1. Ensure your working directory is clean on the `main` branch.
-2. Run the release script:
-   ```bash
-   ./scripts/release.sh [patch|minor|major]
-   ```
-3. The script will bump the version, update CHANGELOG, and push a tag to trigger GitHub Actions.
-
-### For Users
-To update to the latest version and refresh IDE commands:
-1. Update the package: `npm install -g @litmers/cursorflow-orchestrator`
-2. Refresh Cursor commands: `cursorflow-setup --force`
-
-## Configuration
+## 🔗 Task Dependencies
 
-### Config file (cursorflow.config.js)
-
-```javascript
-module.exports = {
-  // Directories
-  tasksDir: '_cursorflow/tasks',
-  logsDir: '_cursorflow/logs',
-
-  // Git settings
-  baseBranch: 'main',
-  branchPrefix: 'feature/',
-
-  // Run settings
-  executor: 'cursor-agent', // 'cursor-agent' | 'cloud'
-  pollInterval: 60,
-
-  // Dependency management
-  allowDependencyChange: false,
-  lockfileReadOnly: true,
-
-  // Review settings
-  enableReview: true,
-  reviewModel: 'sonnet-4.5-thinking',
-  maxReviewIterations: 3,
-
-  // Default lane settings
-  defaultLaneConfig: {
-    devPort: 3001,
-    autoCreatePr: false,
-  },
-
-  // Logging
-  logLevel: 'info',
-  verboseGit: false,
-};
-```
-
-### Task file (JSON)
+You can define dependencies between lanes in your task JSON files. Dependent lanes will wait for their parents to complete and then automatically merge the parent's work before starting.
 
 ```json
 {
-  "repository": "https://github.com/your-org/your-repo",
-  "baseBranch": "main",
-  "branchPrefix": "feature/my-",
-  "executor": "cursor-agent",
-  "laneNumber": 1,
-  "devPort": 3001,
-  "enableReview": true,
-  "tasks": [
-    {
-      "name": "implement",
-      "model": "sonnet-4.5",
-      "acceptanceCriteria": [
-        "No build errors",
-        "Key features implemented"
-      ],
-      "prompt": "Implementation instructions..."
-    }
-  ]
+  "name": "api-implementation",
+  "dependsOn": ["database-schema", "common-utils"],
+  "tasks": [ ... ]
 }
 ```
 
-## Usage Examples
+## 🧪 Advanced Testing
 
-### Single feature development
+A complete test suite for dependency orchestration is included.
 
 ```bash
-# 1. Prepare tasks
-cursorflow prepare AddUserAuth --lanes 1
-
-# 2. Edit the task JSON
-# _cursorflow/tasks/2512191830_AddUserAuth/01-task.json
+# Run a complex dependency test (6 interdependent lanes)
+cursorflow run test-projects/advanced-orchestration/_cursorflow/tasks/full-stack/
 
-# 3. Run
-cursorflow run _cursorflow/tasks/2512191830_AddUserAuth/
-
-# 4. Monitor
-cursorflow monitor --watch
+# Monitor the flow
+cursorflow monitor latest
 ```
 
-### Multi-domain parallel development
-
-```bash
-# 1. Prepare tasks (5 lanes)
-cursorflow prepare AdminDashboard --lanes 5
-
-# 2. Configure each lane
-# 01-dashboard.json, 02-clients.json, ...
-
-# 3. Run in parallel
-cursorflow run _cursorflow/tasks/2512191830_AdminDashboard/
-
-# 4. Live monitor
-cursorflow monitor --watch --interval 5
-```
-
-## Architecture
-
-```
-┌─────────────────────────────────────────────────────────┐
-│                    CursorFlow CLI                       │
-└──────────────────┬──────────────────────────────────────┘
-                   │
-        ┌──────────┴──────────┐
-        │                     │
-   ┌────▼────┐          ┌────▼────┐
-   │ Config  │          │  Core   │
-   │ System  │          │ Engine  │
-   └────┬────┘          └────┬────┘
-        │                    │
-        │         ┌──────────┼──────────┐
-        │         │          │          │
-   ┌────▼────┐ ┌─▼──┐  ┌────▼────┐  ┌─▼─────┐
-   │   Git   │ │Run │  │ Monitor │  │Review │
-   │ Utils   │ │ner │  │         │  │       │
-   └─────────┘ └─┬──┘  └─────────┘  └───────┘
-                 │
-        ┌────────┼────────┐
-        │        │        │
-   ┌────▼───┐ ┌─▼──────┐ │
-   │Worktree│ │ Cursor │ │
-   │        │ │ Agent  │ │
-   └────────┘ └────────┘ │
-                          │
-                     ┌────▼────┐
-                     │  Logs   │
-                     │  State  │
-                     └─────────┘
-```
-
-## Documentation
+## 📚 Documentation
 
 - [📖 User Guide](docs/GUIDE.md) - Detailed usage instructions
 - [📋 API Reference](docs/API.md) - CLI and config API
@@ -371,36 +159,24 @@ cursorflow monitor --watch --interval 5
 - [🔧 Troubleshooting](docs/TROUBLESHOOTING.md) - Issue resolution
 - [📦 Examples](examples/) - Practical examples
 
-## Roadmap
-
-- [ ] v1.0: Core features and base docs
-- [ ] v1.1: Enhanced review system
-- [ ] v1.2: Improved cloud execution
-- [ ] v1.3: Plugin system
-- [ ] v2.0: GUI tool
-
-## Contributing
+## 🚀 Deployment & Updates
 
-Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md).
+### For Maintainers
+To release a new version to NPM:
+1. Run the release script: `./scripts/release.sh [patch|minor|major]`
+2. The script handles versioning, changelog, and triggers GitHub Actions.
 
-### Set up dev environment
+### For Users
+Update and refresh commands:
 ```bash
-git clone https://github.com/eungjin-cigro/cursorflow.git
-cd cursorflow
-pnpm install
-pnpm test
+npm install -g @litmers/cursorflow-orchestrator
+cursorflow-setup --force
 ```
 
 ## License
 
 MIT © Eugene Jin
 
-## Support
-
-- 🐛 [Issue Tracker](https://github.com/eungjin-cigro/cursorflow/issues)
-- 💬 [Discussions](https://github.com/eungjin-cigro/cursorflow/discussions)
-- 📧 Email: eungjin.cigro@gmail.com
-
 ---
 
 **Made with ❤️ for Cursor IDE users**

package/commands/cursorflow-doctor.md

@@ -17,8 +17,36 @@ 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.
+- You want to validate task configuration before running.
+
+## Task Validation
+
+When a task directory is provided, CursorFlow validates:
+
+### Required Fields
+- ✅ `tasks` array exists and is not empty
+- ✅ Each task has a `name` field
+- ✅ Each task has a `prompt` field
+
+### Task Name Format
+- ✅ Only letters, numbers, `-`, `_` allowed
+- ❌ Spaces not allowed
+- ❌ Special characters not allowed
+
+### Configuration Values
+- ✅ `timeout` is a positive number (if provided)
+- ✅ `enableIntervention` is a boolean (if provided)
+
+## Common Validation Errors
+
+| Error | Solution |
+|-------|----------|
+| `Task N missing required "name" field` | Add `"name": "task-name"` to each task object |
+| `Task name contains invalid characters` | Use only letters, numbers, `-`, `_` |
+| `"timeout" must be a positive number` | Provide timeout in milliseconds (e.g., `60000`) |
 
 ## Example
 "Check if my environment is ready for CursorFlow."
 "Run cursorflow doctor on the _cursorflow/tasks/my-feature/ directory."
+"Validate my task configuration in _cursorflow/tasks/api-lane/."