@litmers/cursorflow-orchestrator 0.1.31 → 0.1.34

package/README.md

@@ -13,11 +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).
+- 🌊 **Flow Architecture**: Intuitive `new` + `add` commands to define Flows, Lanes, and Tasks.
 - 📊 **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.
 
@@ -29,75 +28,136 @@
 npm install -g @litmers/cursorflow-orchestrator
 ```
 
-### 2. Initialize & Prepare Tasks
+### 2. Create a Flow
 
 ```bash
 cd your-project
 cursorflow init
 
-# Simple task (single implement task)
-cursorflow prepare FixBug --prompt "Fix the login validation bug in auth.ts"
+# Create a Flow with two Lanes: backend and frontend
+cursorflow new ShopFeature --lanes "backend,frontend"
+```
 
-# Complex feature (plan → implement → test)
-cursorflow prepare AuthSystem --preset complex --prompt "Build user authentication with JWT"
+### 3. Add Tasks to Lanes
 
-# Multiple parallel lanes
-cursorflow prepare FullStack --lanes 3 --sequential --preset complex \
-  --prompt "Build your layer of the full-stack feature"
+```bash
+# Add tasks to backend lane (uses default model)
+cursorflow add ShopFeature backend \
+  --task "name=implement|prompt=상품 검색 API 구현"
+
+# Add tasks to frontend lane (waits for backend)
+cursorflow add ShopFeature frontend \
+  --task "name=ui|prompt=검색 UI 구현" \
+  --after "backend:implement"
 ```
 
-### 3. Validate & Run
+### 4. Run
 
 ```bash
-# Check for issues before running
-cursorflow doctor --tasks-dir _cursorflow/tasks/2412211530_AuthSystem
-
 # Start orchestration
-cursorflow run _cursorflow/tasks/2412211530_AuthSystem
+cursorflow run ShopFeature
 
-# Open the interactive dashboard
+# Monitor progress in real-time
 cursorflow monitor latest
 ```
 
-## 📋 Preset Templates
-
-CursorFlow provides built-in task templates:
+## 📋 Flow 커맨드 - 시나리오로 배우기
 
-| 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 |
+**시나리오**: "쇼핑몰" 프로젝트에서 백엔드 API와 프론트엔드를 동시에 개발
 
-### Using External Templates
+---
 
-You can use templates from a local file, a remote URL, or a built-in name:
+### Step 1: Flow와 Lane 생성 (`new`)
 
 ```bash
-# Using a built-in template name
-cursorflow prepare Feature --template basic
+cursorflow new SearchFeature --lanes "api,web,mobile"
+```
+
+**결과:**
+```
+_cursorflow/flows/001_SearchFeature/
+├── flow.meta.json       # Flow 메타데이터
+├── 01-api.json          # API 레인 (빈 상태)
+├── 02-web.json          # Web 레인 (빈 상태)
+└── 03-mobile.json       # Mobile 레인 (빈 상태)
+```
+
+---
 
-# Using a local template file
-cursorflow prepare Custom --template ./my-template.json
+### Step 2: 각 Lane에 Task 추가 (`add`)
 
-# Using a remote template URL
-cursorflow prepare Remote --template https://raw.githubusercontent.com/user/repo/main/template.json
+```bash
+# API 레인: 의존성 없음, 바로 시작
+cursorflow add SearchFeature api \
+  --task "name=plan|prompt=API 설계" \
+  --task "name=implement|prompt=검색 API 구현" \
+  --task "name=test|prompt=API 테스트 작성"
+
+# Web 레인: API의 implement 완료 후 시작
+cursorflow add SearchFeature web \
+  --task "name=ui|prompt=검색 UI 구현" \
+  --after "api:implement"
+
+# Mobile 레인: API 테스트까지 모두 끝나야 시작
+cursorflow add SearchFeature mobile \
+  --task "name=app|prompt=모바일 검색 화면 구현" \
+  --after "api:test"
 ```
 
-Templates support `{{featureName}}`, `{{laneNumber}}`, and `{{devPort}}` placeholders.
+---
+
+### Step 3: 실행
 
 ```bash
-# Complex: Creates plan document that subsequent tasks reference
-cursorflow prepare Feature --preset complex --prompt "Build user dashboard"
+cursorflow run SearchFeature
+```
 
-# Simple: Just implement and test
-cursorflow prepare BugFix --preset simple --prompt "Fix null pointer in auth.ts"
+**실행 흐름:**
+```
+api:    [plan] → [implement] → [test]
+                     │            │
+web:                 └─→ [ui] ────┤
+                                  │
+mobile:                           └─→ [app]
+```
 
-# Single task: Just the prompt
-cursorflow prepare QuickFix --prompt "Update README.md"
+---
+
+### --task 형식
+
+```
+"name=<이름>|prompt=<프롬프트>"          # 기본 모델 사용
+"name=<이름>|model=<모델>|prompt=<프롬프트>"  # 모델 지정
 ```
 
+| 필드 | 필수 | 설명 |
+|------|------|------|
+| `name` | ✅ | 태스크 이름 (영문, 숫자, -, _) |
+| `prompt` | ✅ | 태스크 프롬프트 |
+| `model` | ❌ | AI 모델 (생략 시 기본 모델 사용) |
+
+기본 모델 설정: `cursorflow config defaultModel <model-name>`
+
+---
+
+### --after 형식 (의존성)
+
+```
+--after "lane:task"           # 특정 태스크 완료 후 시작
+--after "lane"                # 해당 레인의 마지막 태스크 완료 후
+--after "a:t1, b:t2"          # 여러 태스크 모두 완료 후 (콤마 구분)
+```
+
+---
+
+### 커맨드 요약
+
+| 커맨드 | 설명 | 예시 |
+|--------|------|------|
+| `new` | Flow와 Lane 생성 | `cursorflow new Feature --lanes "api,web"` |
+| `add` | Lane에 Task 추가 | `cursorflow add Feature api --task "..."` |
+| `run` | Flow 실행 | `cursorflow run Feature` |
+
 ## 🎮 Dashboard Controls
 
 Within the `cursorflow monitor` dashboard:
@@ -116,19 +176,23 @@ Within the `cursorflow monitor` dashboard:
 
 ```json
 {
-  "baseBranch": "main",
   "branchPrefix": "feature/lane-1-",
   "timeout": 600000,
   "enableIntervention": false,
-  "dependsOn": ["01-lane-1"],
   "enableReview": true,
   "reviewModel": "sonnet-4.5-thinking",
   "tasks": [
+    {
+      "name": "setup",
+      "model": "sonnet-4.5",
+      "prompt": "Set up the project structure..."
+    },
     {
       "name": "implement",
       "model": "sonnet-4.5",
       "prompt": "Implement the user authentication...",
-      "acceptanceCriteria": ["Code complete", "Tests pass"]
+      "acceptanceCriteria": ["Code complete", "Tests pass"],
+      "dependsOn": ["other-lane:setup"]
     }
   ]
 }
@@ -141,20 +205,48 @@ Within the `cursorflow monitor` dashboard:
 | `timeout` | number | 600000 | Task timeout in milliseconds (10 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 |
 
-## 🔗 Task Dependencies
+## 🔗 태스크 의존성 (dependsOn)
 
-Define dependencies between lanes. Dependent lanes wait for parents and auto-merge:
+**언제 사용?** 프론트엔드가 백엔드 API 완성 후에 시작해야 할 때
 
-```bash
-# Create 3 sequential lanes (1 → 2 → 3)
-cursorflow prepare Pipeline --lanes 3 --sequential --preset complex
+### 사용법
+
+JSON 파일에서 `dependsOn` 필드 추가:
+
+```json
+{
+  "tasks": [
+    { "name": "setup", "prompt": "초기 설정..." },
+    { 
+      "name": "integrate", 
+      "prompt": "API 연동...",
+      "dependsOn": ["01-backend:implement"]  // ← 이 태스크 완료 후 시작
+    }
+  ]
+}
+```
+
+형식: `"레인파일명:태스크명"` (확장자 `.json` 제외)
+
+### 실행 흐름 예시
 
-# 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"
+```
+01-backend: [setup] → [implement] → [test]
+                          ↓ 완료!
+02-frontend: [setup] ─────┴─ 대기 → [integrate] → [test]
+```
+
+- 백엔드와 프론트엔드 **동시 시작**
+- 프론트의 `integrate`는 백엔드 `implement` 완료까지 대기
+- 완료되면 백엔드 브랜치 **자동 머지** 후 시작
+
+### 순환 의존성 검사
+
+```bash
+cursorflow doctor --tasks-dir _cursorflow/tasks/MyFeature
+# ❌ Cyclic dependency: 01-a:task1 → 02-b:task2 → 01-a:task1
 ```
 
 ## 🩺 Pre-flight Checks

package/commands/cursorflow-add.md

@@ -0,0 +1,159 @@
+# cursorflow add
+
+Lane에 Task를 추가합니다.
+
+## 사용법
+
+```bash
+cursorflow add <FlowName> <LaneName> --task "name=...|model=...|prompt=..." [--after ...]
+```
+
+## 설명
+
+지정된 Flow의 Lane에 Task를 추가합니다.
+`--task` 옵션은 여러 번 사용하여 여러 태스크를 순차적으로 추가할 수 있습니다.
+
+## --task 형식
+
+```
+"name=<이름>|model=<모델>|prompt=<프롬프트>"
+```
+
+### 필수 필드
+
+| 필드 | 설명 | 예시 |
+|------|------|------|
+| `name` | 태스크 이름 (영문, 숫자, -, _) | `name=implement` |
+| `prompt` | 태스크 프롬프트/지시사항 | `prompt=API 구현` |
+
+### 선택 필드
+
+| 필드 | 설명 | 예시 |
+|------|------|------|
+| `model` | AI 모델 (생략 시 기본 모델 사용) | `model=<your-model>` |
+
+기본 모델 설정: `cursorflow config defaultModel <model-name>`
+
+## --after 형식 (의존성 설정)
+
+첫 번째 태스크가 시작되기 전에 완료되어야 할 태스크를 지정합니다.
+
+| 형식 | 설명 |
+|------|------|
+| `"lane"` | 해당 레인의 **마지막 태스크** 완료 후 시작 |
+| `"lane:task"` | 특정 태스크 완료 후 시작 |
+| `"a:t1, b:t2"` | **여러 태스크가 모두 완료**된 후 시작 |
+
+## 예시
+
+### 기본 사용: 단일 태스크 추가 (기본 모델 사용)
+
+```bash
+cursorflow add SearchFeature api \
+  --task "name=implement|prompt=검색 API 구현"
+```
+
+### 여러 태스크 추가
+
+```bash
+cursorflow add SearchFeature api \
+  --task "name=plan|prompt=API 설계" \
+  --task "name=implement|prompt=검색 API 구현" \
+  --task "name=test|prompt=테스트 코드 작성"
+```
+
+### 의존성 설정: 특정 태스크 완료 후 시작
+
+```bash
+# api 레인의 implement 태스크 완료 후 시작
+cursorflow add SearchFeature web \
+  --task "name=ui|prompt=검색 UI 구현" \
+  --after "api:implement"
+```
+
+### 의존성 설정: 레인 전체 완료 후 시작
+
+```bash
+# api 레인의 마지막 태스크 완료 후 시작
+cursorflow add SearchFeature web \
+  --task "name=ui|prompt=검색 UI 구현" \
+  --after "api"
+```
+
+### 다중 의존성: 여러 태스크 완료 후 시작
+
+```bash
+# web과 mobile 모두 완료된 후 시작
+cursorflow add SearchFeature e2e \
+  --task "name=verify|prompt=E2E 테스트" \
+  --after "web:ui, mobile:app"
+```
+
+## 출력 예시
+
+```
+✅ 3개 태스크 추가 완료
+
+  📄 01-api.json
+
+  ├── plan (<default-model>)
+  ├── implement (<default-model>)
+  └── test (<default-model>)
+
+전체 태스크 목록:
+  1. plan (new)
+  2. implement (new)
+  3. test (new)
+
+다음 단계:
+  cursorflow run SearchFeature    # Flow 실행
+  cursorflow doctor SearchFeature # 설정 검증
+```
+
+## 생성되는 Lane 파일 구조
+
+```json
+{
+  "laneName": "api",
+  "tasks": [
+    {
+      "name": "plan",
+      "model": "<your-model>",
+      "prompt": "API 설계"
+    },
+    {
+      "name": "implement",
+      "model": "<your-model>",
+      "prompt": "검색 API 구현"
+    },
+    {
+      "name": "test",
+      "model": "<your-model>",
+      "prompt": "테스트 코드 작성"
+    }
+  ]
+}
+```
+
+### 의존성이 있는 경우
+
+```json
+{
+  "laneName": "web",
+  "tasks": [
+    {
+      "name": "ui",
+      "model": "<your-model>",
+      "prompt": "검색 UI 구현",
+      "dependsOn": ["01-api:implement"]
+    }
+  ]
+}
+```
+
+## 관련 명령어
+
+- [cursorflow new](cursorflow-new.md) - Flow와 Lane 생성
+- [cursorflow run](cursorflow-run.md) - Flow 실행
+- [cursorflow doctor](cursorflow-doctor.md) - 설정 검증
+

package/commands/cursorflow-monitor.md

@@ -7,20 +7,41 @@ The `cursorflow monitor` command provides a powerful, interactive terminal-based
 
 ```bash
 # Monitor the most recent run
-cursorflow monitor latest
+cursorflow monitor
+
+# List all runs (Multiple Flows Dashboard)
+cursorflow monitor --list
 
 # Monitor a specific run directory
-cursorflow monitor _cursorflow/logs/runs/run-2025-12-21T10-00-00
+cursorflow monitor run-2025-12-21T10-00-00
 ```
 
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `[run-dir]` | Run directory or ID to monitor (default: latest) |
+| `--list`, `-l` | Show all runs dashboard (interactive list) |
+| `--interval <n>` | Refresh interval in seconds (default: 2) |
+| `--help`, `-h` | Show help |
+
 ## Dashboard Controls
 
 ### List View (Main)
 - **Navigation**: Use `↑` and `↓` to move between lanes.
 - **Details**: Press `→` or `Enter` to enter the **Lane Detail View**.
 - **Flow View**: Press `F` to see the task dependency graph (DAG).
+- **All Runs**: Press `M` to switch to the **All Flows Dashboard**.
+- **Unified Logs**: Press `U` to see a merged log stream of all lanes.
 - **Quit**: Press `Q` to exit.
 
+### All Flows Dashboard
+- **Navigation**: Use `↑` and `↓` to select a flow.
+- **Switch**: Press `→` or `Enter` to switch the monitor to the selected flow.
+- **Delete**: Press `D` to delete a completed flow's logs (requires confirmation).
+- **Refresh**: Press `R` to refresh the list of flows.
+- **Back**: Press `M` or `Esc` to return to the List View.
+
 ### Lane Detail View
 - **History Browsing**: Use `↑` and `↓` to scroll through conversation history.
 - **Message Detail**: Press `→` or `Enter` on a message to see its full content.

package/commands/cursorflow-new.md

@@ -0,0 +1,87 @@
+# cursorflow new
+
+Flow와 Lane을 생성합니다.
+
+## 사용법
+
+```bash
+cursorflow new <FlowName> --lanes "lane1,lane2,..."
+```
+
+## 설명
+
+새로운 Flow 디렉토리를 생성하고, 지정된 Lane 파일들의 뼈대를 만듭니다.
+각 Lane에 실제 Task를 추가하려면 `cursorflow add` 명령을 사용하세요.
+
+## 옵션
+
+| 옵션 | 설명 | 예시 |
+|------|------|------|
+| `--lanes <names>` | 콤마로 구분된 레인 이름 목록 (필수) | `--lanes "backend,frontend"` |
+
+## 예시
+
+### 기본 사용
+
+```bash
+# 백엔드와 프론트엔드 2개 레인 생성
+cursorflow new ShopFeature --lanes "backend,frontend"
+```
+
+### 3개 레인 생성
+
+```bash
+# API, Web, Mobile 3개 레인 생성
+cursorflow new SearchFeature --lanes "api,web,mobile"
+```
+
+## 생성 결과
+
+```
+_cursorflow/flows/001_ShopFeature/
+├── flow.meta.json       # Flow 메타데이터
+├── 01-backend.json      # Lane 1 (빈 상태)
+└── 02-frontend.json     # Lane 2 (빈 상태)
+```
+
+### flow.meta.json 스키마
+
+```json
+{
+  "id": "001",
+  "name": "ShopFeature",
+  "createdAt": "2024-12-25T10:30:00Z",
+  "createdBy": "user",
+  "baseBranch": "main",
+  "status": "pending",
+  "lanes": ["backend", "frontend"]
+}
+```
+
+### Lane 파일 스키마 (빈 상태)
+
+```json
+{
+  "laneName": "backend",
+  "tasks": []
+}
+```
+
+## 다음 단계
+
+Flow 생성 후, 각 Lane에 Task를 추가합니다:
+
+```bash
+cursorflow add ShopFeature backend \
+  --task "name=implement|prompt=API 구현"
+
+cursorflow add ShopFeature frontend \
+  --task "name=ui|prompt=UI 구현" \
+  --after "backend:implement"
+```
+
+## 관련 명령어
+
+- [cursorflow add](cursorflow-add.md) - Lane에 Task 추가
+- [cursorflow run](cursorflow-run.md) - Flow 실행
+

package/dist/cli/add.d.ts

@@ -0,0 +1,7 @@
+/**
+ * CursorFlow 'add' command
+ *
+ * Adds tasks to an existing Lane in a Flow
+ */
+declare function addTasks(args: string[]): Promise<void>;
+export = addTasks;