@litmers/cursorflow-orchestrator 0.1.9 → 0.1.12

package/commands/cursorflow-prepare.md

@@ -1,157 +1,436 @@
 # CursorFlow Prepare
 
-## Overview
-Prepare task files for a new feature by gathering requirements and generating lane-specific JSON files.
-
-## Required references
-- Package docs: `node_modules/@litmers/cursorflow-orchestrator/docs/GUIDE.md`
-- Model list: run `cursorflow models --list` in the terminal
-
-## Steps
-
-1. **Collect feature information**
-
-   Confirm the following details with the requester:
-   ```
-   📋 Task Preparation Info
-   =======================
-
-   1. Feature name: [e.g., SchemaUpdate, AdminDashboard]
-   2. Number of lanes: [e.g., 3]
-   3. Work per lane:
-      - Lane 1: [description]
-      - Lane 2: [description]
-      - ...
-   4. Need dependency changes? [Y/N]
-   5. Existing task to reference (optional): [path or N]
-   ```
-
-2. **Create the task folder**
-   ```bash
-   # Timestamp-based folder name (YYMMDDHHMM - 10 digits)
-   TIMESTAMP=$(date +%y%m%d%H%M)
-   FEATURE_NAME="<user input>"
-   TASK_DIR="_cursorflow/tasks/${TIMESTAMP}_${FEATURE_NAME}"
-
-   mkdir -p "$TASK_DIR"
-   ```
-
-3. **Task JSON template**
-
-   Create one JSON file per lane using this structure:
-   ```json
-   {
-     "repository": "https://github.com/org/repo",
-     "baseBranch": "main",
-     "branchPrefix": "<feature>/<lane>-",
-     "executor": "cursor-agent",
-     "autoCreatePr": false,
-     "pollInterval": 60,
-     
-     "timeout": 300000,
-     "enableIntervention": false,
-
-     "dependencyPolicy": {
-       "allowDependencyChange": false,
-       "lockfileReadOnly": true
-     },
-
-     "laneNumber": 1,
-     "devPort": 3001,
-
-     "enableReview": true,
-     "reviewModel": "sonnet-4.5-thinking",
-     "maxReviewIterations": 3,
-
-     "tasks": [
-       {
-         "name": "plan",
-         "model": "opus-4.5-thinking",
-         "acceptanceCriteria": [
-           "Plan document created"
-         ],
-         "prompt": "..."
-       }
-     ]
-   }
-   ```
-
-   **Key Configuration Options:**
-
-   | Option | Type | Default | Description |
-   |--------|------|---------|-------------|
-   | `timeout` | number | 300000 | Task timeout in milliseconds |
-   | `enableIntervention` | boolean | false | Enable stdin piping for intervention |
-   | `dependsOn` | string[] | [] | Lane dependencies |
-
-   **Timeout Guidelines:**
-   - Simple tasks: `60000` (1 min)
-   - Medium tasks: `300000` (5 min) - default
-   - Complex tasks: `600000` (10 min)
-
-4. **Model selection guide**
-
-   | Model | Purpose | Notes |
-   |------|------|------|
-   | `sonnet-4.5` | General implementation, fast work | Most versatile |
-   | `sonnet-4.5-thinking` | Code review, deeper reasoning | Thinking model |
-   | `opus-4.5` | Complex tasks, high quality | Advanced |
-   | `opus-4.5-thinking` | Architecture design | Premium |
-   | `gpt-5.2` | General tasks | OpenAI |
-   | `gpt-5.2-high` | Advanced reasoning | High performance |
-
-5. **Verify the output**
-   ```
-   ✅ Task preparation complete
-   ===========================
-
-   Folder: _cursorflow/tasks/<timestamp>_<feature>/
-   Files created:
-     - 01-<lane1>.json
-     - 02-<lane2>.json
-     - ...
-     - README.md
-
-   Run with:
-     cursorflow run _cursorflow/tasks/<timestamp>_<feature>/
-   ```
-
-## Examples
-
-### Single-lane task
-```bash
-cursorflow prepare MyFeature --lanes 1
-```
+## Core Philosophy: Think Like an Engineering Manager
+
+Before writing any command, adopt the mindset of an engineering manager assigning work to developers:
+
+### 1. Each Lane is a Developer
+- **One developer = One area of responsibility**
+- Just as you wouldn't assign a frontend developer to work on database migrations while simultaneously building UI components, don't mix unrelated concerns in a single lane
+- A lane maintains context across its tasks—switching domains mid-lane loses that continuity
+
+### 2. Separation of Concerns
+- **Different domains → Different lanes**: Backend API and Frontend UI should be separate lanes
+- **Same domain, sequential work → Multiple tasks in one lane**: Planning, implementing, and testing the same feature stays in one lane
+- **Shared dependencies → Use `dependsOn`**: If the UI needs the API to exist first, make the UI lane depend on the API lane
+
+### 3. Clear Boundaries, Clear Prompts
+- Each task prompt should be specific enough that a developer could execute it without asking questions
+- If your prompt says "implement the feature," that's too vague—specify WHAT, WHERE, and HOW
+- Include verification steps: "Double-check that all edge cases are handled"
+
+### 4. Fail-Safe Design
+- **Expect incomplete work**: AI agents sometimes miss edge cases. Add a "verify" task at the end
+- **Post-merge validation**: When a lane depends on another, include instructions to "merge, resolve conflicts, then verify integration"
+
+---
+
+## Terminal-First Workflow
+
+CursorFlow follows a **terminal-first** approach. Everything is defined via CLI commands.
+
+```
+┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
+│ 1. Create Lanes │ ──▶ │ 2. Add Tasks    │ ──▶ │ 3. Validate     │ ──▶ │ 4. Run          │
+│ (prepare)       │     │ (prepare)       │     │ (doctor)        │     │ (run)           │
+└─────────────────┘     └─────────────────┘     └─────────────────┘     └─────────────────┘
+```
+
+### Step-by-Step Workflow
+
+```bash
+# Step 1: Create lanes with preset templates
+# Complex feature: plan → implement → test
+cursorflow prepare AuthSystem --preset complex --prompt "Build authentication system"
+
+# Or simple fix: implement → test
+cursorflow prepare BugFix --preset simple --prompt "Fix login bug"
+
+# Or multi-lane with auto-merge for dependent lanes
+cursorflow prepare FullStack --lanes 3 --sequential --preset complex \
+  --prompt "Build your layer"
+
+# Step 2: Add more lanes if needed (merge preset auto-applied)
+cursorflow prepare --add-lane _cursorflow/tasks/2412211530_AuthSystem \
+  --depends-on "01-lane-1,02-lane-2"  # Uses merge preset automatically
+
+# Step 3: Add tasks to existing lanes
+cursorflow prepare --add-task _cursorflow/tasks/2412211530_AuthSystem/01-lane-1.json \
+  --task "verify|sonnet-4.5|Double-check all requirements|All criteria met"
+
+# Step 4: Validate configuration
+cursorflow doctor --tasks-dir _cursorflow/tasks/2412211530_AuthSystem
+
+# Step 5: Run
+cursorflow run _cursorflow/tasks/2412211530_AuthSystem
+```
+
+---
+
+## Command Reference
+
+### Usage
 
-### Multi-lane task
 ```bash
-cursorflow prepare AdminDashboard --lanes 5
+# Create new feature
+cursorflow prepare <feature-name> [options]
+
+# Add lane to existing task directory
+cursorflow prepare --add-lane <task-dir> [options]
+
+# Add task to existing lane
+cursorflow prepare --add-task <lane-file> --task <spec>
 ```
 
-### Using a custom template
+### Options
+
+| Option | Description |
+|--------|-------------|
+| **Core** ||
+| `<feature-name>` | Feature name (for new task directories) |
+| `--lanes <num>` | Number of lanes to create (default: 1) |
+| `--preset <type>` | Use preset template: `complex` \| `simple` \| `merge` |
+| **Task Definition** ||
+| `--prompt <text>` | Task prompt (context for preset or single task) |
+| `--criteria <list>` | Comma-separated acceptance criteria |
+| `--model <model>` | Model to use (default: `sonnet-4.5`) |
+| `--task <spec>` | Full task spec: `"name\|model\|prompt\|criteria"` (repeatable) |
+| **Dependencies** ||
+| `--sequential` | Chain lanes: 1 → 2 → 3 (auto-merge between lanes) |
+| `--deps <spec>` | Custom dependency graph: `"2:1;3:1,2"` |
+| `--depends-on <lanes>` | Dependencies for `--add-lane`: `"01-lane-1,02-lane-2"` |
+| **Incremental** ||
+| `--add-lane <dir>` | Add a new lane to existing task directory |
+| `--add-task <file>` | Append task(s) to existing lane JSON file |
+| **Advanced** ||
+| `--template <path>` | Custom JSON template |
+| `--force` | Overwrite existing files |
+
+---
+
+## Preset Templates
+
+CursorFlow provides 3 preset templates for common patterns:
+
+### `--preset complex` (plan → implement → test)
+
+For complex features that need planning:
+
 ```bash
-cursorflow prepare MyFeature --template ./my-template.json
+cursorflow prepare FeatureName --preset complex --prompt "Implement user authentication"
+```
+
+Generated tasks:
+1. **plan** (sonnet-4.5-thinking): Analyze requirements, **save plan to `_cursorflow/PLAN_lane-{N}.md`**
+2. **implement** (sonnet-4.5): **Read plan from `_cursorflow/PLAN_lane-{N}.md`**, build feature
+3. **test** (sonnet-4.5): **Refer to plan document** for test requirements
+
+**Plan Document Path**: Each lane saves its plan to `_cursorflow/PLAN_lane-{N}.md` where `{N}` is the lane number. The implement and test tasks explicitly reference this document.
+
+### `--preset simple` (implement → test)
+
+For simple changes or bug fixes:
+
+```bash
+cursorflow prepare BugFix --preset simple --prompt "Fix login validation bug"
+```
+
+Generated tasks:
+1. **implement** (sonnet-4.5): Make the required changes
+2. **test** (sonnet-4.5): Write/update tests
+
+### No Preset (Single Task)
+
+For quick, simple changes you can omit the preset entirely:
+
+```bash
+cursorflow prepare QuickFix --prompt "Fix typo in README.md"
+```
+
+Generated: Single `implement` task with your prompt directly.
+
+### `--preset merge` (merge → test)
+
+For integration lanes with dependencies. **Auto-applied when `--depends-on` is set**:
+
+```bash
+cursorflow prepare --add-lane _cursorflow/tasks/2412211530_Feature \
+  --preset merge --depends-on "01-lane-1,02-lane-2"
+```
+
+Generated tasks:
+1. **merge** (sonnet-4.5): Resolve conflicts, verify integration
+2. **test** (sonnet-4.5): Run integration tests
+
+### Auto-Detection
+
+When a lane has dependencies (`--depends-on` or via `--sequential`), the `merge` preset is automatically applied unless you explicitly specify another preset.
+
+### Task Spec Format (`--task`)
+
+```
+"name|model|prompt|criteria1,criteria2"
+```
+
+- **name**: Task identifier (alphanumeric, `-`, `_`)
+- **model**: AI model (`sonnet-4.5`, `sonnet-4.5-thinking`, etc.)
+- **prompt**: Instructions for the AI
+- **criteria**: Comma-separated acceptance criteria (optional)
+
+---
+
+## Quick Examples
+
+### 1. Simple Single-Lane Feature
+
+```bash
+cursorflow prepare FixBug --prompt "Fix null pointer in auth.ts line 42"
+```
+
+### 2. Single Lane with Multiple Tasks
+
+```bash
+cursorflow prepare AddAPI \
+  --task "plan|sonnet-4.5-thinking|Create REST API design|Design documented" \
+  --task "implement|sonnet-4.5|Build the API endpoints|All endpoints work" \
+  --task "verify|sonnet-4.5|Test all edge cases|All tests pass"
+```
+
+### 3. Multiple Parallel Lanes
+
+```bash
+cursorflow prepare Dashboard --lanes 2 \
+  --prompt "Implement dashboard for your layer"
+
+# Lane 1: Frontend developer
+# Lane 2: Backend developer
+# Both work in parallel
 ```
 
+### 4. Sequential Lanes with Dependencies
+
+```bash
+cursorflow prepare AuthSystem --lanes 3 --sequential \
+  --prompt "Implement your authentication layer"
+
+# Lane 1: DB Schema (starts immediately)
+# Lane 2: Backend API (waits for Lane 1, auto-merges)
+# Lane 3: Frontend (waits for Lane 2, auto-merges)
+```
+
+### 5. Adding Lanes Incrementally
+
+```bash
+# Create initial feature
+cursorflow prepare PaymentFlow --lanes 2 --sequential \
+  --prompt "Implement payment processing"
+
+# Later: Add integration test lane that depends on both
+cursorflow prepare --add-lane _cursorflow/tasks/2412211530_PaymentFlow \
+  --prompt "Run integration tests for payment flow" \
+  --criteria "All payment flows tested,Error handling verified" \
+  --depends-on "01-lane-1,02-lane-2"
+```
+
+### 6. Adding Tasks to Existing Lane
+
+```bash
+# Add verification task to lane 1
+cursorflow prepare --add-task _cursorflow/tasks/2412211530_PaymentFlow/01-lane-1.json \
+  --task "verify|sonnet-4.5|Double-check payment validation|All validations work"
+```
+
+---
+
+## Understanding `dependsOn`
+
+`dependsOn` is not just ordering—it triggers **automatic branch merging**.
+
+### How It Works
+
+1. Lane 1 completes and creates branch `feature/lane-1-abc123`
+2. Lane 2 starts, `runner.ts` **merges Lane 1's branch** into Lane 2's worktree
+3. Lane 2 now has all of Lane 1's code changes and can build upon them
+
+### Dependency Patterns
+
+```bash
+# Sequential: 1 → 2 → 3
+cursorflow prepare Feature --lanes 3 --sequential
+
+# Diamond: 1 → 2, 1 → 3, 2+3 → 4
+cursorflow prepare Feature --lanes 4 --deps "2:1;3:1;4:2,3"
+
+# Parallel then merge: 1, 2 (parallel) → 3
+cursorflow prepare Feature --lanes 3 --deps "3:1,2"
+```
+
+### Example: 3-Lane Authentication System
+
+```bash
+cursorflow prepare AuthSystem --lanes 3 --deps "2:1;3:1,2" \
+  --prompt "Implement your assigned component"
+```
+
+| Lane | Role | dependsOn | When It Starts |
+|------|------|-----------|----------------|
+| 01-lane-1 | DB Schema | (none) | Immediately |
+| 02-lane-2 | Backend API | 01-lane-1 | After DB done, merges DB branch |
+| 03-lane-3 | Integration Tests | 01-lane-1, 02-lane-2 | After both, merges both branches |
+
+---
+
+## Task Design Patterns
+
+### Standard Patterns
+
+**Complex Feature (recommended):**
+```bash
+cursorflow prepare ComplexFeature \
+  --task "plan|sonnet-4.5-thinking|Analyze requirements and create plan|Plan documented" \
+  --task "implement|sonnet-4.5|Implement according to plan|Code complete" \
+  --task "verify|sonnet-4.5|Double-check all requirements are met|All tests pass"
+```
+
+**Simple Change:**
+```bash
+cursorflow prepare SimpleFix \
+  --task "implement|sonnet-4.5|Fix the bug and add test|Bug fixed,Test added" \
+  --task "verify|sonnet-4.5|Verify fix works in all cases|All cases handled"
+```
+
+**Merge Lane (for dependent lanes):**
+```bash
+# Create as 4th lane depending on 2 and 3
+cursorflow prepare --add-lane _cursorflow/tasks/2412211530_Feature \
+  --depends-on "02-lane-2,03-lane-3" \
+  --task "merge|sonnet-4.5|Merge branches and resolve conflicts|Clean merge" \
+  --task "integrate|sonnet-4.5|Verify integration|Tests pass"
+```
+
+### Best Practices
+
+1. **Be Specific**
+   - ❌ "Implement the feature"
+   - ✅ "Create `src/api/users.ts` with GET/POST/PUT/DELETE endpoints for User model"
+
+2. **Include Verification**
+   - Always add a final "verify" task
+   - AI agents often miss edge cases on first pass
+
+3. **Scope Post-Merge Tasks**
+   - When `dependsOn` is set, include: "After merging, resolve any conflicts and verify integration"
+
+4. **Use Thinking Models for Planning**
+   - Use `sonnet-4.5-thinking` for `plan` tasks (deeper reasoning)
+   - Use `sonnet-4.5` for `implement` tasks (faster execution)
+
+---
+
+## When to Use Multiple Lanes
+
+### Good Use Cases for Separate Lanes
+
+| Scenario | Lanes | Why |
+|----------|-------|-----|
+| Frontend + Backend | 2 | Different file sets, can run in parallel |
+| Database + API + UI | 3 | Sequential dependency, clean separation |
+| Multiple microservices | N | Completely isolated codebases |
+| Refactor + New Feature | 2 | Refactor first, feature depends on it |
+
+### Keep in Single Lane
+
+| Scenario | Why |
+|----------|-----|
+| Sequential tasks on same files | Context continuity |
+| Plan → Implement → Test same feature | Single developer mindset |
+| Tightly coupled changes | Avoid merge complexity |
+
+---
+
+## Validation with Doctor
+
+Before running, always validate your configuration:
+
+```bash
+cursorflow doctor --tasks-dir _cursorflow/tasks/2412211530_FeatureName
+```
+
+The doctor command checks:
+- Required fields (`tasks`, `name`, `prompt`)
+- Valid task name format
+- Correct dependency graph (no circular dependencies)
+- Configuration value types
+
+---
+
+## Generated File Structure
+
+```
+_cursorflow/tasks/2412211530_FeatureName/
+├── 01-lane-1.json     # Lane 1 configuration
+├── 02-lane-2.json     # Lane 2 configuration
+├── 03-lane-3.json     # Lane 3 configuration (if added)
+└── README.md          # Auto-generated instructions
+```
+
+### JSON Schema
+
+```json
+{
+  "baseBranch": "main",
+  "branchPrefix": "featurename/lane-1-",
+  "timeout": 300000,
+  "enableIntervention": false,
+  "dependencyPolicy": {
+    "allowDependencyChange": false,
+    "lockfileReadOnly": true
+  },
+  "enableReview": true,
+  "reviewModel": "sonnet-4.5-thinking",
+  "maxReviewIterations": 3,
+  "laneNumber": 1,
+  "devPort": 3001,
+  "dependsOn": ["01-lane-1"],
+  "tasks": [
+    {
+      "name": "implement",
+      "model": "sonnet-4.5",
+      "prompt": "Your task instructions here",
+      "acceptanceCriteria": ["Criterion 1", "Criterion 2"]
+    }
+  ]
+}
+```
+
+### Key Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `tasks` | Yes | Array of task objects |
+| `tasks[].name` | Yes | Task identifier |
+| `tasks[].prompt` | Yes | Instructions for AI agent |
+| `tasks[].model` | No | Model override |
+| `tasks[].acceptanceCriteria` | No | Criteria for AI review |
+| `dependsOn` | No | Array of lane names to wait for |
+| `baseBranch` | Yes | Branch to create worktree from |
+| `branchPrefix` | Yes | Prefix for the feature branch |
+
+---
+
 ## Checklist
-- [ ] Is the feature name clear?
-- [ ] Is the work for each lane defined?
-- [ ] Is the model selection appropriate?
-- [ ] Have dependency changes been confirmed?
-- [ ] Are the acceptance criteria clear?
-- [ ] Have the generated files been reviewed?
-- [ ] Are task names valid (letters, numbers, `-`, `_` only)?
-- [ ] Is the timeout appropriate for task complexity?
-
-## Notes
-1. **Model names**: Use only valid models (check with the `models` command).
-2. **Paths**: Always create tasks under `_cursorflow/tasks/`.
-3. **Branch prefix**: Make it unique to avoid collisions.
-4. **devPort**: Use unique ports per lane (3001, 3002, ...).
-5. **Task names**: Must only contain letters, numbers, `-`, `_`. No spaces or special characters.
-6. **Timeout**: Set based on task complexity. See timeout guidelines above.
-
-## Next steps
-1. Tailor the generated JSON files to the project.
-2. Write detailed prompts.
-3. Run the tasks with `cursorflow run`.
+
+### Before Creating Tasks
+- [ ] Requirements are clearly understood
+- [ ] Work is divided by domain (one lane = one area of responsibility)
+- [ ] Dependencies between lanes are identified
+
+### After Creating Tasks
+- [ ] Each task has a specific, actionable prompt
+- [ ] Acceptance criteria are measurable
+- [ ] Dependent lanes include merge/integration instructions
+- [ ] Final task includes verification step
+
+### Before Running
+- [ ] `cursorflow doctor --tasks-dir <dir>` passes with no errors
+- [ ] JSON files reviewed for any issues