@litmers/cursorflow-orchestrator 0.1.31 → 0.1.36

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/commands/cursorflow-run.md

@@ -2,62 +2,66 @@
 
 ## Overview
 
-Execute AI agent orchestration using task configurations generated by `prepare`. CursorFlow uses a DAG (Directed Acyclic Graph) scheduler to handle lane dependencies and automatic branch merging.
+Execute AI agent orchestration using Flow configurations. CursorFlow uses a DAG (Directed Acyclic Graph) scheduler to handle task dependencies and automatic branch merging.
 
 ## Workflow
 
 ```
 ┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
-│ 1. Create Lanes │ ──▶ │ 2. Add Tasks    │ ──▶ │ 3. Validate     │ ──▶ │ 4. Run          │
-│ (prepare)       │     │ (prepare)       │     │ (doctor)        │     │ (run)           │
+│ 1. Create Flow  │ ──▶ │ 2. Add Tasks    │ ──▶ │ 3. Validate     │ ──▶ │ 4. Run          │
+│ (new)           │     │ (add)           │     │ (doctor)        │     │ (run)           │
 └─────────────────┘     └─────────────────┘     └─────────────────┘     └─────────────────┘
 ```
 
 ## Usage
 
 ```bash
-cursorflow run <tasks-dir> [options]
+cursorflow run <flow-name> [options]
+cursorflow run <flow-path> [options]
 ```
 
 ### Quick Start
 
 ```bash
-# Step 1: Create lanes
-cursorflow prepare AddAPI --prompt "Create REST API for users" --criteria "CRUD works,Tests pass"
+# Step 1: Create flow and lanes
+cursorflow new AddAPI --lanes "backend,frontend"
 
-# Step 2: (Optional) Add more lanes or tasks
-cursorflow prepare --add-lane _cursorflow/tasks/2412211530_AddAPI \
-  --prompt "Add authentication" --depends-on "01-lane-1"
+# Step 2: Add tasks to lanes
+cursorflow add AddAPI backend \
+  --task "name=implement|prompt=Create REST API for users"
+
+cursorflow add AddAPI frontend \
+  --task "name=ui|prompt=Create frontend UI" \
+  --after "backend:implement"
 
 # Step 3: Validate configuration
-cursorflow doctor --tasks-dir _cursorflow/tasks/2412211530_AddAPI
+cursorflow doctor AddAPI
 
 # Step 4: Run
-cursorflow run _cursorflow/tasks/2412211530_AddAPI
-
-# Or run the latest prepared task
-cursorflow run latest
+cursorflow run AddAPI
 ```
 
 ## How It Works
 
-1. **Load**: Read all JSON files from the tasks directory
+1. **Load**: Read all JSON files from the flow directory (excluding `flow.meta.json`)
 2. **Validate**: Check `tasks` array, required fields (`name`, `prompt`)
 3. **Resolve**: Build execution order from `dependsOn` dependencies
 4. **Execute**:
    - Start lanes with no dependencies in parallel
-   - When a lane completes, unlock dependent lanes
-   - **Dependent lanes auto-merge predecessor branches before starting**
+   - When a task completes, unlock dependent tasks
+   - **Dependent tasks auto-merge predecessor branches before starting**
 5. **Monitor**: Heartbeat logs every 30 seconds
 
 ## Options
 
 | Option | Description |
 |--------|-------------|
-| `<tasks-dir>` | Directory containing JSON task files |
+| `<flow-name>` | Flow name (e.g., `AddAPI`) |
+| `<flow-path>` | Flow directory path (e.g., `_cursorflow/flows/001_AddAPI`) |
 | `--max-concurrent <num>` | Limit concurrent lane execution |
 | `--executor <type>` | `cursor-agent` (default) or `cloud` |
 | `--skip-doctor` | Skip environment checks (not recommended) |
+| `--no-git` | Skip Git operations (worktree, commits, push) |
 | `--dry-run` | Show execution plan without running |
 
 ## Execution Flow
@@ -65,15 +69,16 @@ cursorflow run latest
 ### Single Lane
 
 ```bash
-cursorflow prepare SimpleFix --prompt "Fix the bug"
-cursorflow run _cursorflow/tasks/2412211530_SimpleFix
+cursorflow new SimpleFix --lanes "main"
+cursorflow add SimpleFix main --task "name=fix|prompt=Fix the bug"
+cursorflow run SimpleFix
 ```
 
 ```
 ┌─────────────────────────────────────────────────────────┐
-│  01-lane-1                                              │
+│  main                                                   │
 │  ┌─────────┐                                            │
-│  │implement│ → AI executes → Review → Complete          │
+│  │   fix   │ → AI executes → Complete                   │
 │  └─────────┘                                            │
 └─────────────────────────────────────────────────────────┘
 ```
@@ -81,108 +86,67 @@ cursorflow run _cursorflow/tasks/2412211530_SimpleFix
 ### Multiple Tasks in Lane
 
 ```bash
-cursorflow prepare Feature \
-  --task "plan|sonnet-4.5-thinking|Create plan|Plan ready" \
-  --task "implement|sonnet-4.5|Build feature|Code done"
+cursorflow add Feature api \
+  --task "name=plan|prompt=Create plan" \
+  --task "name=implement|prompt=Build feature"
 ```
 
 ```
 ┌─────────────────────────────────────────────────────────┐
-│  01-lane-1                                              │
+│  api                                                    │
 │  ┌────┐     ┌─────────┐                                 │
-│  │plan│ ──▶ │implement│ → Review → Complete             │
+│  │plan│ ──▶ │implement│ → Complete                      │
 │  └────┘     └─────────┘                                 │
 └─────────────────────────────────────────────────────────┘
 ```
 
-### Sequential Lanes (with `--sequential`)
+### Sequential Lanes (with dependencies)
 
 ```bash
-cursorflow prepare FullStack --lanes 3 --sequential \
-  --prompt "Implement your layer"
+cursorflow new FullStack --lanes "backend,api,frontend"
+
+cursorflow add FullStack backend --task "name=db|prompt=Setup database"
+cursorflow add FullStack api --task "name=impl|prompt=Create API" --after "backend"
+cursorflow add FullStack frontend --task "name=ui|prompt=Create UI" --after "api"
 ```
 
 ```
 ┌───────────┐     ┌───────────┐     ┌───────────┐
-│ 01-lane-1 │ ──▶ │ 02-lane-2 │ ──▶ │ 03-lane-3 │
-│ (DB)      │     │ (API)     │     │ (UI)      │
+│  backend  │ ──▶ │    api    │ ──▶ │ frontend  │
+│   (db)    │     │  (impl)   │     │   (ui)    │
 └───────────┘     └───────────┘     └───────────┘
                         │                 │
-                    merges 01         merges 01,02
+                   merges            merges
+                   backend          backend,api
 ```
 
 ### Parallel Lanes
 
 ```bash
-cursorflow prepare FrontBack --lanes 2 \
-  --prompt "Implement your layer"
+cursorflow new FrontBack --lanes "frontend,backend"
+
+cursorflow add FrontBack frontend --task "name=ui|prompt=Create UI"
+cursorflow add FrontBack backend --task "name=api|prompt=Create API"
 ```
 
 ```
 ┌───────────┐
-│ 01-lane-1 │  (Frontend)
+│ frontend  │  (UI)
 └───────────┘
               ─── both run in parallel
 ┌───────────┐
-│ 02-lane-2 │  (Backend)
+│  backend  │  (API)
 └───────────┘
 ```
 
-## JSON Schema (RunnerConfig)
-
-Each JSON file in the tasks directory follows this schema:
-
-```json
-{
-  "baseBranch": "main",
-  "branchPrefix": "feature/lane-1-",
-  "timeout": 600000,
-  "enableIntervention": false,
-  "dependsOn": ["01-lane-1"],
-  "dependencyPolicy": {
-    "allowDependencyChange": false,
-    "lockfileReadOnly": true
-  },
-  "enableReview": true,
-  "reviewModel": "sonnet-4.5-thinking",
-  "maxReviewIterations": 3,
-  "tasks": [
-    {
-      "name": "implement",
-      "prompt": "Create a reusable button component...",
-      "model": "sonnet-4.5",
-      "acceptanceCriteria": ["Build passes", "Tests pass"]
-    }
-  ]
-}
-```
-
-### Configuration Reference
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `baseBranch` | string | Yes | Branch to create worktree from |
-| `branchPrefix` | string | Yes | Prefix for feature branch naming |
-| `tasks` | Task[] | Yes | Array of task objects to execute |
-| `dependsOn` | string[] | No | Lane names to wait for and merge |
-| `timeout` | number | No | Task timeout in ms (default: 600000) |
-| `enableIntervention` | boolean | No | Allow stdin injection during execution |
-| `dependencyPolicy.allowDependencyChange` | boolean | No | Allow package.json modifications |
-| `dependencyPolicy.lockfileReadOnly` | boolean | No | Keep lockfile read-only |
-| `enableReview` | boolean | No | Enable AI code review (default: true) |
-| `reviewModel` | string | No | Model for code review |
-| `maxReviewIterations` | number | No | Max review cycles (default: 3) |
-
-### Task Object
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `name` | string | Yes | Task identifier (alphanumeric, `-`, `_`) |
-| `prompt` | string | Yes | Instructions for the AI agent |
-| `model` | string | No | Model override for this task |
-| `acceptanceCriteria` | string[] | No | Criteria for AI reviewer validation |
-| `dependsOn` | string[] | No | Task-level dependencies (lane:task) |
-| `timeout` | number | No | Task-specific timeout in ms |
+## Log Format
+
+Logs use the format `[L{n}-T{t}-{lanename}]`:
+- `L{n}`: Lane number (1-indexed)
+- `T{t}`: Task number (1-indexed)
+- `{lanename}`: First 10 characters of lane name
+
+Example: `[L1-T2-backend]` = Lane 1, Task 2, lane name "backend"
 
 ## Monitoring During Execution
 
@@ -190,8 +154,8 @@ Each JSON file in the tasks directory follows this schema:
 # In another terminal
 cursorflow monitor latest
 
-# Or specify the task directory
-cursorflow monitor _cursorflow/tasks/2412211530_AddAPI
+# Or specify the run directory
+cursorflow monitor _cursorflow/logs/runs/run-xxxxx
 ```
 
 The monitor shows:
@@ -221,33 +185,18 @@ Circular dependency detected
 ```
 → Check your `dependsOn` fields for cycles (A→B, B→A)
 
-```
-Unknown dependency: 01-lane-99
-```
-→ Verify the lane name in `dependsOn` matches an actual JSON filename
-
-### Merge Conflicts
-
-When a dependent lane's auto-merge fails:
-
-1. Find the worktree path in `cursorflow monitor`
-2. Navigate to the worktree directory
-3. Resolve conflicts manually and commit
-4. Resume with `cursorflow resume <lane-name>`
-
 ### Lane Stuck
 
 If a lane stops responding:
 
 1. Check the agent window in Cursor IDE
 2. Use `cursorflow signal <lane-name> --message "continue"` to nudge
-3. Or terminate and restart with `cursorflow run --resume`
+3. Or use `cursorflow resume --all` to resume
 
 ## Best Practices
 
-1. **Always Validate First**: Run `cursorflow doctor --tasks-dir <dir>` before `run`
+1. **Always Validate First**: Run `cursorflow doctor <flow-name>` before `run`
 2. **Start Small**: Test with a single lane before scaling up
 3. **Use `--dry-run`**: Preview execution plan before committing
 4. **Monitor Actively**: Keep `cursorflow monitor` running in a separate terminal
 5. **Plan Dependencies**: Draw out the DAG before running complex workflows
-6. **Include Verification**: Add verify tasks to catch edge cases

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;