@litmers/cursorflow-orchestrator 0.1.9 → 0.1.12

package/CHANGELOG.md

@@ -5,6 +5,30 @@ 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

package/README.md

@@ -13,10 +13,10 @@
 
 - ⚡ **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 (requires `enableIntervention: true`).
-- 🛡️ **PID Control**: Track and manage agent processes directly from the dashboard.
+- 🙋 **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.
@@ -26,27 +26,61 @@
 ### 1. Install
 
 ```bash
-# npm (recommended)
 npm install -g @litmers/cursorflow-orchestrator
 ```
 
-### 2. Initialize
+### 2. Initialize & Prepare Tasks
 
 ```bash
 cd your-project
-cursorflow init --example
+cursorflow init
+
+# Simple task (single implement task)
+cursorflow prepare FixBug --prompt "Fix the login validation bug in auth.ts"
+
+# Complex feature (plan → implement → test)
+cursorflow prepare AuthSystem --preset complex --prompt "Build user authentication with JWT"
+
+# Multiple parallel lanes
+cursorflow prepare FullStack --lanes 3 --sequential --preset complex \
+  --prompt "Build your layer of the full-stack feature"
 ```
 
-### 3. Run & Monitor
+### 3. Validate & Run
 
 ```bash
+# Check for issues before running
+cursorflow doctor --tasks-dir _cursorflow/tasks/2412211530_AuthSystem
+
 # Start orchestration
-cursorflow run _cursorflow/tasks/example/
+cursorflow run _cursorflow/tasks/2412211530_AuthSystem
 
-# Open the interactive dashboard (highly recommended!)
+# Open the interactive dashboard
 cursorflow monitor latest
 ```
 
+## 📋 Preset Templates
+
+CursorFlow provides built-in task templates:
+
+| 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 |
+
+```bash
+# Complex: Creates plan document that subsequent tasks reference
+cursorflow prepare Feature --preset complex --prompt "Build user dashboard"
+
+# 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"
+```
+
 ## 🎮 Dashboard Controls
 
 Within the `cursorflow monitor` dashboard:
@@ -66,19 +100,18 @@ Within the `cursorflow monitor` dashboard:
 ```json
 {
   "baseBranch": "main",
-  "branchPrefix": "cursorflow/feature-",
-  "model": "sonnet-4.5",
+  "branchPrefix": "feature/lane-1-",
   "timeout": 300000,
   "enableIntervention": false,
-  "dependsOn": ["other-lane"],
-  "dependencyPolicy": {
-    "allowDependencyChange": false,
-    "lockfileReadOnly": true
-  },
+  "dependsOn": ["01-lane-1"],
+  "enableReview": true,
+  "reviewModel": "sonnet-4.5-thinking",
   "tasks": [
     {
-      "name": "implement-feature",
-      "prompt": "Implement the user authentication..."
+      "name": "implement",
+      "model": "sonnet-4.5",
+      "prompt": "Implement the user authentication...",
+      "acceptanceCriteria": ["Code complete", "Tests pass"]
     }
   ]
 }
@@ -88,75 +121,60 @@ Within the `cursorflow monitor` dashboard:
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `timeout` | number | 300000 | Task timeout in milliseconds (5 min default) |
+| `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 |
-
-### Timeout Configuration
-
-Set custom timeouts based on task complexity:
-
-```json
-{
-  "timeout": 60000,
-  "tasks": [{ "name": "simple-task", "prompt": "..." }]
-}
-```
-
-- **Simple tasks**: `60000` (1 minute)
-- **Medium tasks**: `300000` (5 minutes) - default
-- **Complex tasks**: `600000` (10 minutes)
-
-### Task Validation
-
-CursorFlow automatically validates your task configuration before execution:
-
-- ✅ Required `name` and `prompt` fields
-- ✅ Valid task name format (letters, numbers, `-`, `_` only)
-- ✅ Proper timeout values
-- ✅ Helpful error messages with fix suggestions
-
-### Progress Monitoring (Heartbeat)
-
-During execution, CursorFlow logs progress every 30 seconds:
-
-```
-⏱ Heartbeat: 30s elapsed, 1234 bytes received
-⏱ Heartbeat: 60s elapsed, 5678 bytes received
-```
+| `enableReview` | boolean | true | Enable AI code review |
 
 ## 🔗 Task Dependencies
 
-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.
+Define dependencies between lanes. Dependent lanes wait for parents and auto-merge:
 
-```json
-{
-  "name": "api-implementation",
-  "dependsOn": ["database-schema", "common-utils"],
-  "tasks": [ ... ]
-}
+```bash
+# Create 3 sequential lanes (1 → 2 → 3)
+cursorflow prepare Pipeline --lanes 3 --sequential --preset complex
+
+# 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"
 ```
 
-## 🧪 Advanced Testing
+## 🩺 Pre-flight Checks
 
-A complete test suite for dependency orchestration is included.
+Doctor validates your configuration before running:
 
 ```bash
-# Run a complex dependency test (6 interdependent lanes)
-cursorflow run test-projects/advanced-orchestration/_cursorflow/tasks/full-stack/
-
-# Monitor the flow
-cursorflow monitor latest
+cursorflow doctor --tasks-dir _cursorflow/tasks/my-feature
+
+# Checks performed:
+# ✓ Git repository and remote
+# ✓ Branch prefix collisions
+# ✓ Task structure validation
+# ✓ Circular dependency detection (DAG)
+# ✓ Existing branch conflicts
 ```
 
-## 📚 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
+## 📚 Commands Reference
+
+| 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
+
+- [📋 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
 
 ## 🚀 Deployment & Updates

package/commands/cursorflow-clean.md

@@ -1,162 +1,51 @@
 # CursorFlow Clean
 
 ## Overview
-Clean up branches, worktrees, and logs. Remove stale files or remnants from failed runs.
+Clean up temporary resources created by CursorFlow, including Git worktrees, feature branches, and log files.
 
-## Steps
+## Usage
 
-1. **Choose what to clean**
-
-   | Type | Description |
-   |------|------|
-   | `branches` | Clean Git branches |
-   | `worktrees` | Clean Git worktrees |
-   | `logs` | Clean log files |
-   | `all` | Clean everything |
-
-2. **Clean branches**
-   ```bash
-   cursorflow clean branches --pattern "feature/my-*"
-   ```
-
-3. **Clean worktrees**
-   ```bash
-   cursorflow clean worktrees --all
-   ```
+```bash
+cursorflow clean <type> [options]
+```
 
-4. **Clean logs**
-   ```bash
-   cursorflow clean logs --older-than 30
-   ```
+## Clean Types
 
-5. **Verify with a dry run**
-   ```bash
-   cursorflow clean all --dry-run
-   ```
+| Type | Description |
+|------|------|
+| `branches` | Remove local feature branches created by CursorFlow |
+| `worktrees` | Remove temporary Git worktrees |
+| `logs` | Clear all run and terminal logs |
+| `all` | Clean everything (branches, worktrees, and logs) |
 
 ## Options
 
 | Option | Description |
 |------|------|
-| `--pattern <pattern>` | Pattern match (e.g., "feature/*") |
-| `--older-than <days>` | Items older than N days (for logs) |
-| `--dry-run` | Show items to delete without removing |
-| `--force` | Delete without confirmation |
-| `--local-only` | Local only (branches) |
-| `--remote-only` | Remote only (branches) |
+| `--dry-run` | Show what would be removed without actually deleting anything |
+| `--force` | Force removal (ignore uncommitted changes in worktrees) |
+| `--help`, `-h` | Show help |
 
 ## Examples
 
-### Branch cleanup
-
-#### Delete by pattern
-```bash
-cursorflow clean branches --pattern "feature/dashboard-*"
-```
-
-#### All CursorFlow branches
-```bash
-cursorflow clean branches --pattern "feature/*" --dry-run
-```
-
-#### Local branches only
-```bash
-cursorflow clean branches --pattern "feature/*" --local-only
-```
-
-### Worktree cleanup
-
-#### All worktrees
-```bash
-cursorflow clean worktrees --all
-```
-
-#### Specific pattern
-```bash
-cursorflow clean worktrees --pattern "*-dashboard-*"
-```
-
-### Log cleanup
-
-#### Logs older than 30 days
+### Review before deleting
 ```bash
-cursorflow clean logs --older-than 30
+cursorflow clean all --dry-run
 ```
 
-#### All logs
+### Clean only worktrees
 ```bash
-cursorflow clean logs --all --force
+cursorflow clean worktrees
 ```
 
-### Full cleanup
-
-#### Review then delete
+### Force clean everything
 ```bash
-cursorflow clean all --dry-run
 cursorflow clean all --force
 ```
 
-## Sample output
-
-```
-🧹 Cleaning CursorFlow Resources
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Branches to delete:
-  - feature/dashboard-pipeline-abc123 (local)
-  - feature/dashboard-pipeline-abc123 (remote)
-  - feature/client-pipeline-def456 (local)
-
-Worktrees to remove:
-  - .cursorflow/logs/worktrees/01-dashboard-pipeline-abc123
-  - .cursorflow/logs/worktrees/02-client-pipeline-def456
-
-Logs to delete:
-  - _cursorflow/logs/runs/01-dashboard-2025-12-10T10-00-00 (9 days old)
-
-Total: 5 branches, 2 worktrees, 1 log directory
-
-Proceed? [y/N]
-```
-
 ## Notes
 
-1. **Back up**: Save important branches before deleting.
-2. **Confirm**: Start with `--dry-run` to review changes.
-3. **Remote caution**: Be careful when deleting remote branches.
-4. **Irreversible**: Deleted items are hard to recover.
-
-## Checklist
-- [ ] Have you reviewed items to clean?
-- [ ] Do you need backups?
-- [ ] Did you run a dry run first?
-- [ ] Are other teammates using these branches?
-- [ ] Do you also need to delete from the remote?
-
-## Troubleshooting
-
-### Branch deletion failed
-```bash
-# Force delete
-git branch -D <branch-name>
-git push origin --delete <branch-name>
-```
-
-### Worktree removal failed
-```bash
-# Force remove
-git worktree remove --force <worktree-path>
-```
-
-### Log directory permission issues
-```bash
-# Check permissions
-ls -la _cursorflow/logs/
-# Fix permissions
-chmod -R u+w _cursorflow/logs/
-```
-
-## Next steps
-1. Clean logs regularly (e.g., monthly).
-2. Add an automated cleanup script to CI/CD.
-3. Add log directories to `.gitignore`.
+1. **Safety**: It is highly recommended to run with `--dry-run` first to see exactly what will be deleted.
+2. **Worktrees**: The command identifies CursorFlow worktrees by their location (usually in `_cursorflow/worktrees/`) or their prefix.
+3. **Branches**: Only branches starting with the configured `branchPrefix` (default: `cursorflow/`) are targeted.
+4. **Irreversible**: Once logs are deleted, they cannot be recovered.

package/commands/cursorflow-doctor.md

@@ -1,52 +1,80 @@
-# /cursorflow-doctor
+# CursorFlow Doctor
 
-## Goal
-Verify that the current environment is properly configured for CursorFlow.
+## Overview
+Verify that your environment and task configurations are properly set up for CursorFlow.
 
 ## Usage
-1. Type `/cursorflow-doctor` in the chat.
-2. The agent will check:
-   - Git repository status
-   - 'origin' remote availability
-   - Git worktree support
-   - Cursor Agent installation and authentication
-   - Task directory and lane file validity (if a path is provided)
-
-## Context
-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.
+
+```bash
+cursorflow doctor [options]
+```
+
+## Checks Performed
+- **Environment**: Git repository status, remote availability, and worktree support.
+- **Cursor IDE**: Verifies `cursor-agent` is installed and authenticated.
+- **Tasks**: (Optional) Validates task JSON files for schema errors or missing fields.
+
+## Options
+
+| Option | Description |
+|------|------|
+| `--tasks-dir <path>` | Validate lane files in a specific directory |
+| `--executor <type>` | Check environment for `cursor-agent` \| `cloud` |
+| `--test-agent` | Run an interactive agent test (to approve permissions) |
+| `--no-cursor` | Skip Cursor Agent installation and auth checks |
+| `--json` | Output the report in machine-readable JSON format |
 
 ## Task Validation
 
-When a task directory is provided, CursorFlow validates:
+When `--tasks-dir` is provided, the doctor performs comprehensive validation:
 
-### Required Fields
-- ✅ `tasks` array exists and is not empty
-- ✅ Each task has a `name` field
-- ✅ Each task has a `prompt` field
+### Structure Validation
+- **tasks array**: Must exist and be non-empty
+- **task.name**: Required, must be alphanumeric with `-` and `_` only, unique within lane
+- **task.prompt**: Required, should be descriptive (warns if < 10 chars)
+- **task.model**: Optional, must be string if provided
+- **task.acceptanceCriteria**: Optional, must be non-empty array if provided
 
-### Task Name Format
-- ✅ Only letters, numbers, `-`, `_` allowed
-- ❌ Spaces not allowed
-- ❌ Special characters not allowed
+### Dependency Validation (DAG)
+- **Unknown dependencies**: Reports if `dependsOn` references non-existent lanes
+- **Circular dependencies**: Detects cycles (e.g., A→B→A) that would cause deadlock
+- Reports the exact cycle path for easy debugging
 
-### Configuration Values
-- ✅ `timeout` is a positive number (if provided)
-- ✅ `enableIntervention` is a boolean (if provided)
+### Branch Validation
+- **Prefix collision**: Warns if multiple lanes use the same `branchPrefix`
+- **Existing branch conflicts**: Detects if existing branches match a lane's prefix
+- **Duplicate lane names**: Ensures each lane file has a unique name
+- **Naming suggestions**: Recommends using lane numbers in branch prefixes for consistency
 
-## Common Validation Errors
+Example errors:
+```
+❌ Branch prefix collision
+   Multiple lanes use the same branchPrefix "feature/lane-1-": 01-lane-1, 02-lane-2
+   Fix: Update the branchPrefix in each lane JSON file to be unique
 
-| 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`) |
+⚠️ Existing branches may conflict with 01-lane-1
+   Found 2 existing branch(es) matching prefix "feature/lane-1-": feature/lane-1-abc, feature/lane-1-xyz
+   Fix: Delete conflicting branches or change the branchPrefix
+```
 
 ## 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/."
 
+```bash
+# Basic environment check
+cursorflow doctor
+
+# Test agent permissions
+cursorflow doctor --test-agent
+
+# Validate a specific task set
+cursorflow doctor --tasks-dir _cursorflow/tasks/my-feature/
+```
+
+## Common Issues & Fixes
+
+| Issue | Potential Fix |
+|-------|---------------|
+| `Cursor Agent not found` | Ensure Cursor IDE is installed and `cursor` command is in PATH. |
+| `Not authenticated` | Open Cursor IDE and log in to your account. |
+| `Worktree not supported` | Upgrade your Git version (requires Git >= 2.5). |
+| `Circular dependency` | Check the `dependsOn` fields in your task JSON files. |

package/commands/cursorflow-init.md

@@ -1,67 +1,50 @@
 # CursorFlow Init
 
 ## Overview
-Initialize CursorFlow in your project. Create the config file and directory structure, and optionally install Cursor commands and example tasks.
+Initialize CursorFlow in your project. This command creates the default configuration file, sets up the required directory structure, and prepares the environment for parallel AI orchestration.
 
-## Steps
+## Usage
 
-1. **Run initialization**
-   ```bash
-   cursorflow init
-   ```
+```bash
+cursorflow init [options]
+```
 
-2. **Choose options**
-   - `--example`: create example tasks
-   - `--config-only`: create only the config file
-   - `--no-commands`: skip installing Cursor commands
-   - `--force`: overwrite existing files
+## Options
 
-3. **Verify created files**
-   - `cursorflow.config.js` created
-   - `_cursorflow/tasks/` directory created
-   - `_cursorflow/logs/` directory created
-   - `.cursor/commands/cursorflow/` commands installed (optional)
+| Option | Description |
+|------|------|
+| `--example` | Create an example task to help you get started |
+| `--config-only` | Only create the `cursorflow.config.js` file |
+| `--no-commands` | Skip installing Cursor IDE custom commands |
+| `--no-gitignore` | Skip adding `_cursorflow/` to your `.gitignore` |
+| `--force` | Overwrite existing configuration or directories |
 
-4. **Review the config file**
-   ```javascript
-   // cursorflow.config.js
-   module.exports = {
-     tasksDir: '_cursorflow/tasks',
-     logsDir: '_cursorflow/logs',
-     baseBranch: 'main',
-     // ... other settings
-   };
-   ```
+## What's Created?
 
-## Examples
+1. **`cursorflow.config.js`**: Central configuration for the project.
+2. **`_cursorflow/tasks/`**: Directory where you define your task JSON files.
+3. **`_cursorflow/logs/`**: Directory for run logs and terminal outputs.
+4. **`.cursor/commands/cursorflow/`**: (Optional) Integrated Cursor IDE commands.
+5. **`.gitignore` update**: Adds `_cursorflow/` to prevent committing logs.
 
-### Basic initialization
-```bash
-cursorflow init
-```
+## Example
 
-### Include example tasks
 ```bash
+# Standard initialization with an example task
 cursorflow init --example
-```
 
-### Generate only the config
-```bash
-cursorflow init --config-only
-```
-
-### Overwrite existing files
-```bash
-cursorflow init --force
+# Minimal initialization
+cursorflow init --no-commands --no-gitignore
 ```
 
-## Checklist
-- [ ] Was the config file created at the project root?
-- [ ] Were the required directories created?
-- [ ] Were Cursor commands installed?
-- [ ] Is the configuration adjusted for the project?
+## Next Steps
 
-## Next steps
-1. Update `cursorflow.config.js` for your project.
-2. In Cursor IDE, type `/` to confirm the commands are available.
-3. Start generating tasks with `cursorflow prepare MyFeature`.
+1. **Configure**: Review `cursorflow.config.js` and adjust settings like `baseBranch` or `maxConcurrentLanes`.
+2. **Explore**: If you used `--example`, run it with:
+   ```bash
+   cursorflow run _cursorflow/tasks/example/
+   ```
+3. **Create**: Start your own feature tasks with:
+   ```bash
+   cursorflow prepare MyFeature
+   ```