@litmers/cursorflow-orchestrator 0.1.8 → 0.1.12

package/CHANGELOG.md

@@ -5,6 +5,61 @@ 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.12] - 2025-12-21
+
+### Added
+- **Preset Templates**: Three built-in task templates for common patterns:
+  - `--preset complex`: plan → implement → test (saves plan to `_cursorflow/PLAN_lane-{N}.md`)
+  - `--preset simple`: implement → test
+  - `--preset merge`: merge → test (auto-applied for dependent lanes)
+- **Plan Document Integration**: Complex preset saves implementation plans to dedicated files, which are referenced by subsequent tasks
+- **Single Task Mode**: Create simple tasks with just `--prompt` without specifying a preset
+- **Branch Validation in Doctor**: 
+  - Detects branch prefix collisions between lanes
+  - Warns about existing branches that may conflict
+  - Suggests consistent naming conventions
+- **Pre-resume Validation**: `cursorflow resume` now runs doctor checks before resuming (use `--skip-doctor` to bypass)
+- **Models Command**: `cursorflow models` to list available AI models
+- **Incremental Lane/Task Addition**: 
+  - `--add-lane` to add new lanes to existing task directories
+  - `--add-task` to append tasks to existing lane files
+
+### Changed
+- All documentation updated to English
+- Improved task generation with better prompts and acceptance criteria
+- Enhanced error messages for branch and dependency issues
+
+## [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,398 +9,192 @@
 [![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.
+- 📋 **Preset Templates**: Built-in templates for common patterns (complex, simple, merge).
+- 📊 **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.
+- 🔍 **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 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 & Prepare Tasks
 
 ```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
-
-```bash
-# Run example tasks
-cursorflow run _cursorflow/tasks/example/
-
-# Monitor from another terminal
-cursorflow monitor --watch
-```
-
-## 🧪 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
-
-1. **create-utils**: Creates `src/utils.js` with utility functions
-2. **add-tests**: Creates `src/utils.test.js` with simple tests
-
-Each task runs ~1-2 minutes, demonstrating the full CursorFlow workflow.
-
-**See**: `test-projects/demo-project/README.md` for detailed documentation.
-
-## 📚 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/
+# Simple task (single implement task)
+cursorflow prepare FixBug --prompt "Fix the login validation bug in auth.ts"
 
-# Monitor in real-time
-cursorflow monitor --watch
-```
-
-**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`
-
-## Cursor IDE Integration
+# Complex feature (plan → implement → test)
+cursorflow prepare AuthSystem --preset complex --prompt "Build user authentication with JWT"
 
-CursorFlow ships custom commands that are available directly inside Cursor IDE.
-
-### Install commands
-
-```bash
-# Installed automatically during init
-cursorflow init
-
-# Or install manually
-npx cursorflow-setup
+# Multiple parallel lanes
+cursorflow prepare FullStack --lanes 3 --sequential --preset complex \
+  --prompt "Build your layer of the full-stack feature"
 ```
 
-### Usage
-
-Type `/` in Cursor chat and use:
-
-- `/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
+### 3. Validate & Run
 
-## CLI Commands
-
-### Init
 ```bash
-cursorflow init [options]
-  --example          Create example tasks
-  --with-commands    Install Cursor commands (default: true)
-  --config-only      Generate config file only
-```
+# Check for issues before running
+cursorflow doctor --tasks-dir _cursorflow/tasks/2412211530_AuthSystem
 
-### Prepare tasks
-```bash
-cursorflow prepare <feature> [options]
-  --lanes <number>   Number of lanes
-  --template <path>  Template file path
-```
+# Start orchestration
+cursorflow run _cursorflow/tasks/2412211530_AuthSystem
 
-### Run
-```bash
-cursorflow run <tasks-dir> [options]
-  --dry-run          Show the execution plan only
-  --executor <type>  cursor-agent | cloud
+# Open the interactive dashboard
+cursorflow monitor latest
 ```
 
-### Monitor
-```bash
-cursorflow monitor [run-dir] [options]
-  --watch            Live monitoring
-  --interval <sec>   Refresh interval
-```
+## 📋 Preset Templates
 
-### Clean
-```bash
-cursorflow clean <type> [options]
-  branches          Clean branches
-  worktrees         Clean worktrees
-  logs              Clean logs
-  all               Clean everything
-```
+CursorFlow provides built-in task templates:
 
-### Resume
-```bash
-cursorflow resume <lane> [options]
-  --run-dir <path>   Specify run directory
-  --restart          Restart from task 1
-```
+| Preset | Tasks | Use Case |
+|--------|-------|----------|
+| `--preset complex` | plan → implement → test | Complex features (saves plan to `_cursorflow/PLAN_lane-{N}.md`) |
+| `--preset simple` | implement → test | Simple changes, bug fixes |
+| `--preset merge` | merge → test | Integration lanes (auto-applied with `--depends-on`) |
+| *(none)* | implement | Quick single task |
 
-### Doctor
 ```bash
-cursorflow doctor [options]
-  --tasks-dir <path> Validate specific lane tasks
-  --json             Output in JSON format
-```
+# Complex: Creates plan document that subsequent tasks reference
+cursorflow prepare Feature --preset complex --prompt "Build user dashboard"
 
-### Signal (Intervention)
-```bash
-cursorflow signal <lane> <message>
-  --run-dir <path>   Specify run directory
+# Simple: Just implement and test
+cursorflow prepare BugFix --preset simple --prompt "Fix null pointer in auth.ts"
+
+# Single task: Just the prompt
+cursorflow prepare QuickFix --prompt "Update README.md"
 ```
 
-## 🚀 Deployment & Updates
+## 🎮 Dashboard Controls
 
-### 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.
+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.
 
-### 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
-
-### 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,
-};
-```
+## ⚙️ Configuration
 
-### Task file (JSON)
+### Task Configuration Schema
 
 ```json
 {
-  "repository": "https://github.com/your-org/your-repo",
   "baseBranch": "main",
-  "branchPrefix": "feature/my-",
-  "executor": "cursor-agent",
-  "laneNumber": 1,
-  "devPort": 3001,
+  "branchPrefix": "feature/lane-1-",
+  "timeout": 300000,
+  "enableIntervention": false,
+  "dependsOn": ["01-lane-1"],
   "enableReview": true,
+  "reviewModel": "sonnet-4.5-thinking",
   "tasks": [
     {
       "name": "implement",
       "model": "sonnet-4.5",
-      "acceptanceCriteria": [
-        "No build errors",
-        "Key features implemented"
-      ],
-      "prompt": "Implementation instructions..."
+      "prompt": "Implement the user authentication...",
+      "acceptanceCriteria": ["Code complete", "Tests pass"]
     }
   ]
 }
 ```
 
-## Usage Examples
+### Key Options
 
-### Single feature development
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `timeout` | number | 300000 | Task timeout in milliseconds (5 min) |
+| `enableIntervention` | boolean | false | Enable stdin piping for intervention |
+| `model` | string | "sonnet-4.5" | AI model to use |
+| `dependsOn` | string[] | [] | Lane dependencies |
+| `enableReview` | boolean | true | Enable AI code review |
 
-```bash
-# 1. Prepare tasks
-cursorflow prepare AddUserAuth --lanes 1
+## 🔗 Task Dependencies
 
-# 2. Edit the task JSON
-# _cursorflow/tasks/2512191830_AddUserAuth/01-task.json
+Define dependencies between lanes. Dependent lanes wait for parents and auto-merge:
 
-# 3. Run
-cursorflow run _cursorflow/tasks/2512191830_AddUserAuth/
+```bash
+# Create 3 sequential lanes (1 → 2 → 3)
+cursorflow prepare Pipeline --lanes 3 --sequential --preset complex
 
-# 4. Monitor
-cursorflow monitor --watch
+# Add a merge lane that depends on multiple lanes
+cursorflow prepare --add-lane _cursorflow/tasks/2412211530_Pipeline \
+  --depends-on "01-lane-1,02-lane-2"
 ```
 
-### Multi-domain parallel development
+## 🩺 Pre-flight Checks
 
-```bash
-# 1. Prepare tasks (5 lanes)
-cursorflow prepare AdminDashboard --lanes 5
-
-# 2. Configure each lane
-# 01-dashboard.json, 02-clients.json, ...
+Doctor validates your configuration before running:
 
-# 3. Run in parallel
-cursorflow run _cursorflow/tasks/2512191830_AdminDashboard/
+```bash
+cursorflow doctor --tasks-dir _cursorflow/tasks/my-feature
 
-# 4. Live monitor
-cursorflow monitor --watch --interval 5
+# Checks performed:
+# ✓ Git repository and remote
+# ✓ Branch prefix collisions
+# ✓ Task structure validation
+# ✓ Circular dependency detection (DAG)
+# ✓ Existing branch conflicts
 ```
 
-## Architecture
+## 📚 Commands Reference
 
-```
-┌─────────────────────────────────────────────────────────┐
-│                    CursorFlow CLI                       │
-└──────────────────┬──────────────────────────────────────┘
-                   │
-        ┌──────────┴──────────┐
-        │                     │
-   ┌────▼────┐          ┌────▼────┐
-   │ Config  │          │  Core   │
-   │ System  │          │ Engine  │
-   └────┬────┘          └────┬────┘
-        │                    │
-        │         ┌──────────┼──────────┐
-        │         │          │          │
-   ┌────▼────┐ ┌─▼──┐  ┌────▼────┐  ┌─▼─────┐
-   │   Git   │ │Run │  │ Monitor │  │Review │
-   │ Utils   │ │ner │  │         │  │       │
-   └─────────┘ └─┬──┘  └─────────┘  └───────┘
-                 │
-        ┌────────┼────────┐
-        │        │        │
-   ┌────▼───┐ ┌─▼──────┐ │
-   │Worktree│ │ Cursor │ │
-   │        │ │ Agent  │ │
-   └────────┘ └────────┘ │
-                          │
-                     ┌────▼────┐
-                     │  Logs   │
-                     │  State  │
-                     └─────────┘
-```
+| Command | Description |
+|---------|-------------|
+| `cursorflow init` | Initialize CursorFlow in project |
+| `cursorflow prepare` | Generate task files (with presets) |
+| `cursorflow doctor` | Validate environment and tasks |
+| `cursorflow run` | Execute task orchestration |
+| `cursorflow monitor` | Interactive dashboard |
+| `cursorflow resume` | Resume interrupted lane |
+| `cursorflow clean` | Clean branches/worktrees |
+| `cursorflow signal` | Send message to running agent |
+| `cursorflow models` | List available AI models |
 
-## Documentation
+## 📖 Documentation
 
-- [📖 User Guide](docs/GUIDE.md) - Detailed usage instructions
-- [📋 API Reference](docs/API.md) - CLI and config API
-- [🎨 Command Guide](docs/COMMANDS.md) - Cursor command usage
-- [🏗️ Architecture](docs/ARCHITECTURE.md) - System structure
-- [🔧 Troubleshooting](docs/TROUBLESHOOTING.md) - Issue resolution
+- [📋 Prepare Command](commands/cursorflow-prepare.md) - Task generation with presets
+- [🏃 Run Command](commands/cursorflow-run.md) - Execution options
+- [🩺 Doctor Command](commands/cursorflow-doctor.md) - Validation details
+- [📊 Monitor Command](commands/cursorflow-monitor.md) - Dashboard usage
 - [📦 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**