@litmers/cursorflow-orchestrator 0.1.37 → 0.1.39

package/commands/cursorflow-prepare.md

@@ -1,436 +1,243 @@
-# CursorFlow Prepare
+# cursorflow prepare
 
-## Core Philosophy: Think Like an Engineering Manager
+Flow 생성과 Task 추가를 위한 통합 가이드입니다.
 
-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
+┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
+│ 1. Flow 생성    │ ──▶ │ 2. Task 추가    │ ──▶ │ 3. 실행         │
+│ (new)           │     │ (add)           │     │ (run)           │
+└─────────────────┘     └─────────────────┘     └─────────────────┘
 ```
 
 ---
 
-## Command Reference
+## 🎯 설계 원칙: Lane과 Task 나누기
 
-### Usage
+> **핵심**: 엔지니어링 매니저가 개발자에게 업무를 할당하듯이 생각하세요.
 
-```bash
-# Create new feature
-cursorflow prepare <feature-name> [options]
-
-# Add lane to existing task directory
-cursorflow prepare --add-lane <task-dir> [options]
+### 1. Lane = 독립적인 개발자 1명
 
-# Add task to existing lane
-cursorflow prepare --add-task <lane-file> --task <spec>
-```
+| 원칙 | 설명 |
+|------|------|
+| **한 레인 = 한 영역** | 프론트엔드 개발자에게 DB 마이그레이션을 동시에 시키지 않듯이, 레인에 서로 다른 도메인을 섞지 마세요 |
+| **컨텍스트 유지** | 레인은 태스크 간 컨텍스트를 유지합니다. 도메인이 바뀌면 그 연속성이 끊깁니다 |
 
-### 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 |
-
----
+### 2. 언제 레인을 나눌까?
 
-## Preset Templates
+| 상황 | 레인 수 | 이유 |
+|------|---------|------|
+| Frontend + Backend | 2개 | 다른 파일 세트, 병렬 실행 가능 |
+| DB + API + UI | 3개 | 순차 의존성, 명확한 분리 |
+| 여러 마이크로서비스 | N개 | 완전히 독립된 코드베이스 |
+| 리팩토링 + 새 기능 | 2개 | 리팩토링 먼저, 기능은 의존 |
 
-CursorFlow provides 3 preset templates for common patterns:
+### 3. 언제 한 레인에 유지할까?
 
-### `--preset complex` (plan → implement → test)
+| 상황 | 이유 |
+|------|------|
+| 같은 파일들을 순차 작업 | 컨텍스트 연속성 |
+| Plan → Implement → Test | 단일 개발자 마인드셋 |
+| 밀접하게 결합된 변경 | 머지 복잡성 방지 |
 
-For complex features that need planning:
+### 4. 좋은 프롬프트 작성법
 
-```bash
-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"
+❌ 나쁜 예: "기능 구현해줘"
+✅ 좋은 예: "src/api/users.ts에 User 모델용 GET/POST/PUT/DELETE 엔드포인트 생성"
 ```
 
-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:
+| 원칙 | 설명 |
+|------|------|
+| **구체적으로** | WHAT, WHERE, HOW를 명시 |
+| **검증 포함** | "모든 엣지 케이스 처리 확인" 같은 검증 단계 추가 |
+| **의존 시 머지 안내** | "머지 후 충돌 해결하고 통합 검증" |
 
-```bash
-cursorflow prepare QuickFix --prompt "Fix typo in README.md"
-```
+### 5. 실패 대비 설계
 
-Generated: Single `implement` task with your prompt directly.
+- **verify 태스크 추가**: AI는 첫 시도에 엣지 케이스를 놓칠 수 있음
+- **의존 레인엔 머지 지시**: "이전 브랜치 머지 후 통합 확인"
 
-### `--preset merge` (merge → test)
+---
 
-For integration lanes with dependencies. **Auto-applied when `--depends-on` is set**:
+## Step 1: Flow와 Lane 생성 (`new`)
 
 ```bash
-cursorflow prepare --add-lane _cursorflow/tasks/2412211530_Feature \
-  --preset merge --depends-on "01-lane-1,02-lane-2"
+cursorflow new <FlowName> --lanes "lane1,lane2,..."
 ```
 
-Generated tasks:
-1. **merge** (sonnet-4.5): Resolve conflicts, verify integration
-2. **test** (sonnet-4.5): Run integration tests
+### 예시
 
-### Auto-Detection
+```bash
+# 백엔드와 프론트엔드 2개 레인 생성
+cursorflow new ShopFeature --lanes "backend,frontend"
 
-When a lane has dependencies (`--depends-on` or via `--sequential`), the `merge` preset is automatically applied unless you explicitly specify another preset.
+# API, Web, Mobile 3개 레인 생성
+cursorflow new SearchFeature --lanes "api,web,mobile"
+```
 
-### Task Spec Format (`--task`)
+### 생성 결과
 
 ```
-"name|model|prompt|criteria1,criteria2"
+_cursorflow/flows/001_ShopFeature/
+├── flow.meta.json       # Flow 메타데이터
+├── backend.json         # Lane (빈 상태)
+└── frontend.json        # Lane (빈 상태)
 ```
 
-- **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
+## Step 2: Task 추가 (`add`)
 
 ```bash
-cursorflow prepare FixBug --prompt "Fix null pointer in auth.ts line 42"
+cursorflow add <FlowName> <LaneName> --task "name=...|prompt=..." [--after ...]
 ```
 
-### 2. Single Lane with Multiple Tasks
+### --task 형식
 
-```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
+"name=<이름>|prompt=<프롬프트>"          # 기본 모델 사용
+"name=<이름>|model=<모델>|prompt=<프롬프트>"  # 모델 지정
 ```
 
-### 4. Sequential Lanes with Dependencies
+| 필드 | 필수 | 설명 |
+|------|------|------|
+| `name` | ✅ | 태스크 이름 (영문, 숫자, -, _) |
+| `prompt` | ✅ | 태스크 프롬프트/지시사항 |
+| `model` | ❌ | AI 모델 (생략 시 기본 모델 사용) |
 
-```bash
-cursorflow prepare AuthSystem --lanes 3 --sequential \
-  --prompt "Implement your authentication layer"
+### --after 형식 (의존성)
 
-# 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)
-```
+| 형식 | 설명 |
+|------|------|
+| `"lane"` | 해당 레인의 **마지막 태스크** 완료 후 시작 |
+| `"lane:task"` | 특정 태스크 완료 후 시작 |
+| `"a:t1, b:t2"` | **여러 태스크가 모두 완료**된 후 시작 |
 
-### 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"
-```
+# 단일 태스크 추가
+cursorflow add SearchFeature api \
+  --task "name=implement|prompt=검색 API 구현"
 
-### 6. Adding Tasks to Existing Lane
+# 여러 태스크 추가
+cursorflow add SearchFeature api \
+  --task "name=plan|prompt=API 설계" \
+  --task "name=implement|prompt=검색 API 구현" \
+  --task "name=test|prompt=테스트 코드 작성"
 
-```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"
+# 의존성 설정
+cursorflow add SearchFeature web \
+  --task "name=ui|prompt=검색 UI 구현" \
+  --after "api:implement"
 ```
 
 ---
 
-## 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
+## 전체 예시: 3-Lane 프로젝트
 
 ```bash
-# Sequential: 1 → 2 → 3
-cursorflow prepare Feature --lanes 3 --sequential
+# 1. Flow 생성
+cursorflow new SearchFeature --lanes "api,web,mobile"
 
-# Diamond: 1 → 2, 1 → 3, 2+3 → 4
-cursorflow prepare Feature --lanes 4 --deps "2:1;3:1;4:2,3"
+# 2. API 레인: 의존성 없음, 바로 시작
+cursorflow add SearchFeature api \
+  --task "name=plan|prompt=API 설계" \
+  --task "name=implement|prompt=검색 API 구현" \
+  --task "name=test|prompt=API 테스트 작성"
 
-# Parallel then merge: 1, 2 (parallel) → 3
-cursorflow prepare Feature --lanes 3 --deps "3:1,2"
-```
+# 3. Web 레인: API implement 완료 후 시작
+cursorflow add SearchFeature web \
+  --task "name=ui|prompt=검색 UI 구현" \
+  --after "api:implement"
 
-### Example: 3-Lane Authentication System
+# 4. Mobile 레인: API 전체 완료 후 시작
+cursorflow add SearchFeature mobile \
+  --task "name=app|prompt=모바일 검색 화면 구현" \
+  --after "api"
 
-```bash
-cursorflow prepare AuthSystem --lanes 3 --deps "2:1;3:1,2" \
-  --prompt "Implement your assigned component"
+# 5. 검증 및 실행
+cursorflow doctor SearchFeature
+cursorflow run SearchFeature
 ```
 
-| 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"
+api:    [plan] → [implement] → [test]
+                     │            │
+web:                 └─→ [ui] ────┤
+                                  │
+mobile:                           └─→ [app]
 ```
 
-### 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 |
+```bash
+# 기본 모델 확인
+cursorflow config defaultModel
 
-### Keep in Single Lane
+# 기본 모델 변경
+cursorflow config defaultModel gemini-2.5-flash
 
-| Scenario | Why |
-|----------|-----|
-| Sequential tasks on same files | Context continuity |
-| Plan → Implement → Test same feature | Single developer mindset |
-| Tightly coupled changes | Avoid merge complexity |
+# 사용 가능한 모델 목록
+cursorflow models
+```
 
 ---
 
-## Validation with Doctor
+## 생성되는 파일 구조
 
-Before running, always validate your configuration:
+### flow.meta.json
 
-```bash
-cursorflow doctor --tasks-dir _cursorflow/tasks/2412211530_FeatureName
+```json
+{
+  "id": "001",
+  "name": "SearchFeature",
+  "createdAt": "2024-12-26T10:30:00Z",
+  "baseBranch": "main",
+  "status": "pending",
+  "lanes": ["api", "web", "mobile"]
+}
 ```
 
-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
+### Lane 파일 (api.json)
 
-```
-_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
+{
+  "laneName": "api",
+  "tasks": [
+    { "name": "plan", "model": "sonnet-4.5", "prompt": "API 설계" },
+    { "name": "implement", "model": "sonnet-4.5", "prompt": "검색 API 구현" },
+    { "name": "test", "model": "sonnet-4.5", "prompt": "API 테스트 작성" }
+  ]
+}
 ```
 
-### JSON Schema
+### 의존성이 있는 Lane (web.json)
 
 ```json
 {
-  "baseBranch": "main",
-  "branchPrefix": "featurename/lane-1-",
-  "timeout": 600000,
-  "enableIntervention": false,
-  "dependencyPolicy": {
-    "allowDependencyChange": false,
-    "lockfileReadOnly": true
-  },
-  "enableReview": true,
-  "reviewModel": "sonnet-4.5-thinking",
-  "maxReviewIterations": 3,
-  "laneNumber": 1,
-  "devPort": 3001,
-  "dependsOn": ["01-lane-1"],
+  "laneName": "web",
   "tasks": [
     {
-      "name": "implement",
+      "name": "ui",
       "model": "sonnet-4.5",
-      "prompt": "Your task instructions here",
-      "acceptanceCriteria": ["Criterion 1", "Criterion 2"]
+      "prompt": "검색 UI 구현",
+      "dependsOn": ["api:implement"]
     }
   ]
 }
 ```
 
-### 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
-
-### 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
+- `cursorflow doctor <FlowName>` - 설정 검증
+- `cursorflow run <FlowName>` - Flow 실행
+- `cursorflow monitor latest` - 실행 모니터링