@litmers/cursorflow-orchestrator 0.1.0

package/commands/cursorflow-monitor.md

@@ -0,0 +1,131 @@
+# CursorFlow Monitor
+
+## Overview
+레인 실행 상태를 모니터링합니다. 실시간으로 진행 상황을 확인하고 로그를 조회할 수 있습니다.
+
+## Steps
+
+1. **실시간 모니터링**
+   ```bash
+   cursorflow monitor --watch
+   ```
+
+2. **특정 run 모니터링**
+   ```bash
+   cursorflow monitor _cursorflow/logs/runs/my-run/
+   ```
+
+3. **상태 확인**
+   
+   레인별 상태 정보:
+   - pending: 대기 중
+   - running: 실행 중
+   - completed: 완료
+   - failed: 실패
+   - blocked_dependency: 의존성 대기
+
+4. **로그 확인**
+   
+   각 레인의 로그 파일:
+   - `state.json`: 현재 상태
+   - `conversation.jsonl`: 에이전트 대화
+   - `git-operations.jsonl`: Git 작업
+   - `events.jsonl`: 이벤트 로그
+
+## 옵션
+
+| 옵션 | 설명 |
+|------|------|
+| `--watch` | 실시간 갱신 (2초 간격) |
+| `--interval <sec>` | 갱신 간격 (초) |
+| `--json` | JSON 형식으로 출력 |
+
+## 예제
+
+### 최신 run 모니터링
+```bash
+cursorflow monitor
+```
+
+### 실시간 모니터링 (5초 간격)
+```bash
+cursorflow monitor --watch --interval 5
+```
+
+### JSON 출력
+```bash
+cursorflow monitor --json | jq
+```
+
+## 출력 예시
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  📡 Lane 상태 모니터링
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Run: 01-dashboard-2025-12-19T18-30-00
+
+- 01-dashboard: running (2/3)
+- 02-client: completed (3/3)
+- 03-projects: blocked_dependency (1/2)
+```
+
+## 로그 조회
+
+### 대화 기록
+```bash
+cat _cursorflow/logs/runs/01-dashboard-xxx/conversation.jsonl | jq
+```
+
+### Git 작업 로그
+```bash
+cat _cursorflow/logs/runs/01-dashboard-xxx/git-operations.jsonl | jq
+```
+
+### 이벤트 로그
+```bash
+cat _cursorflow/logs/runs/01-dashboard-xxx/events.jsonl | jq
+```
+
+## 상태 분석
+
+### 레인별 진행률
+```bash
+# 모든 레인의 state.json 확인
+for state in _cursorflow/logs/runs/*/lanes/*/state.json; do
+  echo "$(dirname $state):"
+  jq '.status, .currentTaskIndex, .totalTasks' $state
+done
+```
+
+### 실패한 레인 찾기
+```bash
+# status가 failed인 레인
+find _cursorflow/logs/runs -name "state.json" -exec sh -c \
+  'jq -r "select(.status==\"failed\") | .label" {}' \;
+```
+
+## Checklist
+- [ ] 레인 상태가 정상인가?
+- [ ] 에러가 발생했는가?
+- [ ] 로그를 확인했는가?
+- [ ] Blocked lane이 있는가?
+- [ ] 의존성 문제는 없는가?
+
+## 트러블슈팅
+
+### 레인이 멈춘 경우
+1. `state.json`에서 상태 확인
+2. `conversation.jsonl`에서 마지막 대화 확인
+3. 필요시 `cursorflow resume <lane>`로 재개
+
+### 로그가 없는 경우
+1. 실행이 시작되었는지 확인
+2. 로그 디렉토리 권한 확인
+3. 설정 파일의 logsDir 경로 확인
+
+## Next Steps
+1. 문제 발견 시 `cursorflow resume`로 재개
+2. 완료된 레인의 PR 확인
+3. 로그 분석으로 개선점 파악

package/commands/cursorflow-prepare.md

@@ -0,0 +1,134 @@
+# CursorFlow Prepare
+
+## Overview
+새 Feature에 대한 태스크 파일을 준비합니다. Feature 정보를 수집하고 레인별 JSON 파일을 생성합니다.
+
+## 필수 참조
+- 패키지 문서: `node_modules/@cursorflow/orchestrator/docs/GUIDE.md`
+- 모델 목록: 터미널에서 `cursorflow models --list` 실행
+
+## Steps
+
+1. **Feature 정보 수집**
+   
+   사용자에게 다음 정보를 확인합니다:
+   ```
+   📋 태스크 준비 정보
+   ================
+   
+   1. Feature 이름: [예: SchemaUpdate, AdminDashboard]
+   2. 레인 개수: [예: 3]
+   3. 레인별 작업 내용:
+      - Lane 1: [작업 설명]
+      - Lane 2: [작업 설명]
+      - ...
+   4. 의존성 변경 필요 여부: [Y/N]
+   5. 참조할 기존 태스크 (선택): [경로 또는 N]
+   ```
+
+2. **태스크 폴더 생성**
+   ```bash
+   # 타임스탬프 기반 폴더명 생성 (YYMMDDHHMM - 10자리)
+   TIMESTAMP=$(date +%y%m%d%H%M)
+   FEATURE_NAME="<사용자 입력>"
+   TASK_DIR="_cursorflow/tasks/${TIMESTAMP}_${FEATURE_NAME}"
+   
+   mkdir -p "$TASK_DIR"
+   ```
+
+3. **태스크 JSON 템플릿**
+   
+   각 레인마다 다음 구조의 JSON 파일을 생성합니다:
+   ```json
+   {
+     "repository": "https://github.com/org/repo",
+     "baseBranch": "main",
+     "branchPrefix": "<feature>/<lane>-",
+     "executor": "cursor-agent",
+     "autoCreatePr": false,
+     "allowDependencyChange": false,
+     "lockfileReadOnly": true,
+     "pollInterval": 60,
+     
+     "laneNumber": 1,
+     "devPort": 3001,
+     
+     "enableReview": true,
+     "reviewModel": "sonnet-4.5-thinking",
+     "maxReviewIterations": 3,
+     
+     "tasks": [
+       {
+         "name": "plan",
+         "model": "opus-4.5-thinking",
+         "acceptanceCriteria": [
+           "계획서 파일 생성됨"
+         ],
+         "prompt": "..."
+       }
+     ]
+   }
+   ```
+
+4. **모델 선택 가이드**
+   
+   | 모델 | 용도 | 비고 |
+   |------|------|------|
+   | `sonnet-4.5` | 일반 구현, 빠른 작업 | 가장 범용적 |
+   | `sonnet-4.5-thinking` | 코드 리뷰, 추론 강화 | Thinking 모델 |
+   | `opus-4.5` | 복잡한 작업, 고품질 | 고급 모델 |
+   | `opus-4.5-thinking` | 아키텍처 설계 | 최고급 |
+   | `gpt-5.2` | 일반 작업용 | OpenAI |
+   | `gpt-5.2-high` | 고급 추론 | 고성능 |
+
+5. **생성 결과 확인**
+   ```
+   ✅ 태스크 준비 완료
+   =================
+   
+   폴더: _cursorflow/tasks/<timestamp>_<feature>/
+   생성된 파일:
+     - 01-<lane1>.json
+     - 02-<lane2>.json
+     - ...
+     - README.md
+   
+   다음 명령어로 실행:
+     cursorflow run _cursorflow/tasks/<timestamp>_<feature>/
+   ```
+
+## 예제
+
+### 단일 레인 태스크
+```bash
+cursorflow prepare MyFeature --lanes 1
+```
+
+### 멀티 레인 태스크
+```bash
+cursorflow prepare AdminDashboard --lanes 5
+```
+
+### 커스텀 템플릿 사용
+```bash
+cursorflow prepare MyFeature --template ./my-template.json
+```
+
+## Checklist
+- [ ] Feature 이름이 명확한가?
+- [ ] 레인별 작업이 정의되었는가?
+- [ ] 모델 선택이 적절한가?
+- [ ] 의존성 변경 필요 여부를 확인했는가?
+- [ ] Acceptance Criteria가 명확한가?
+- [ ] 생성된 파일들을 검토했는가?
+
+## 주의사항
+1. **모델명**: 유효한 모델만 사용 (models 명령으로 확인)
+2. **경로**: 태스크는 항상 `_cursorflow/tasks/`에 생성
+3. **브랜치 프리픽스**: 충돌하지 않도록 고유하게 설정
+4. **devPort**: 레인마다 고유한 포트 (3001, 3002, ...)
+
+## Next Steps
+1. 생성된 JSON 파일들을 프로젝트에 맞게 수정
+2. 프롬프트 내용을 상세하게 작성
+3. `cursorflow run`으로 태스크 실행

package/commands/cursorflow-resume.md

@@ -0,0 +1,181 @@
+# CursorFlow Resume
+
+## Overview
+중단되거나 실패한 레인을 재개합니다. 상태를 복구하거나 처음부터 다시 시작할 수 있습니다.
+
+## Steps
+
+1. **레인 상태 확인**
+   ```bash
+   cursorflow monitor
+   ```
+
+2. **레인 재개**
+   ```bash
+   cursorflow resume <lane-name>
+   ```
+
+3. **브랜치 정리 후 재시작**
+   ```bash
+   cursorflow resume <lane-name> --clean
+   ```
+
+4. **처음부터 다시 시작**
+   ```bash
+   cursorflow resume <lane-name> --restart
+   ```
+
+## 옵션
+
+| 옵션 | 설명 |
+|------|------|
+| `--run-dir <path>` | 특정 run 디렉토리 지정 |
+| `--clean` | 브랜치 정리 후 재시작 |
+| `--restart` | 처음부터 다시 시작 |
+| `--force` | 확인 없이 진행 |
+
+## 예제
+
+### 기본 재개
+```bash
+# 최신 run에서 해당 레인 재개
+cursorflow resume 01-dashboard
+```
+
+### 특정 run에서 재개
+```bash
+cursorflow resume --run-dir _cursorflow/logs/runs/my-run/ 01-dashboard
+```
+
+### 브랜치 충돌 해결 후 재개
+```bash
+# 기존 브랜치 정리 후 재시작
+cursorflow resume 01-dashboard --clean
+```
+
+### 완전히 새로 시작
+```bash
+# 모든 상태 초기화 후 재시작
+cursorflow resume 01-dashboard --restart
+```
+
+## 재개 프로세스
+
+1. **상태 확인**
+   - `state.json` 파일 로드
+   - 마지막 태스크 위치 확인
+   - Worktree 상태 확인
+
+2. **환경 복구**
+   - Worktree 접근 가능 여부 확인
+   - 브랜치 체크아웃
+   - 미커밋 변경사항 확인
+
+3. **실행 재개**
+   - 중단된 태스크부터 계속
+   - 또는 새로 시작 (--restart)
+
+4. **완료**
+   - 남은 태스크 모두 수행
+   - 변경사항 커밋 및 푸시
+
+## 상태 파일 예시
+
+```json
+{
+  "label": "01-dashboard",
+  "status": "failed",
+  "currentTaskIndex": 1,
+  "totalTasks": 3,
+  "worktreeDir": ".cursorflow/logs/worktrees/01-dashboard-abc123",
+  "pipelineBranch": "feature/dashboard-abc123",
+  "error": "Build failed",
+  "startTime": 1734567890000,
+  "endTime": null
+}
+```
+
+## Checklist
+- [ ] 레인이 실제로 중단되었는가?
+- [ ] 상태 파일이 존재하는가?
+- [ ] 브랜치 충돌은 없는가?
+- [ ] Worktree가 존재하는가?
+- [ ] 미커밋 변경사항이 있는가?
+
+## 트러블슈팅
+
+### 상태 파일이 없는 경우
+```bash
+# 최신 run 디렉토리 확인
+ls -lt _cursorflow/logs/runs/
+
+# 특정 run 지정
+cursorflow resume --run-dir _cursorflow/logs/runs/latest/ 01-dashboard
+```
+
+### 브랜치 충돌
+```bash
+# 기존 브랜치 확인
+git branch | grep dashboard
+
+# 정리 후 재개
+cursorflow resume 01-dashboard --clean
+```
+
+### Worktree 문제
+```bash
+# Worktree 목록 확인
+git worktree list
+
+# 문제 있는 worktree 제거
+git worktree remove <path> --force
+
+# 재개
+cursorflow resume 01-dashboard --restart
+```
+
+### 의존성 블록
+```bash
+# 의존성이 해결되었는지 확인
+cursorflow monitor
+
+# 의존성 해결 후 재개
+cursorflow resume 01-dashboard
+```
+
+## 재개 시나리오
+
+### 시나리오 1: 네트워크 오류로 중단
+```bash
+# 단순 재개 (같은 위치부터 계속)
+cursorflow resume 01-dashboard
+```
+
+### 시나리오 2: 빌드 에러로 실패
+```bash
+# 코드 수정 후
+cd .cursorflow/logs/worktrees/01-dashboard-xxx/
+# ... 코드 수정 ...
+git add -A
+git commit -m "fix: build error"
+
+# 다음 태스크부터 계속
+cursorflow resume 01-dashboard
+```
+
+### 시나리오 3: 브랜치 충돌
+```bash
+# 브랜치 정리 후 새로 시작
+cursorflow resume 01-dashboard --clean
+```
+
+### 시나리오 4: 처음부터 다시
+```bash
+# 모든 상태 초기화
+cursorflow resume 01-dashboard --restart
+```
+
+## Next Steps
+1. 재개 후 `cursorflow monitor --watch`로 모니터링
+2. 완료 시 PR 확인
+3. 반복 실패 시 태스크 설정 검토

package/commands/cursorflow-review.md

@@ -0,0 +1,220 @@
+# CursorFlow Review
+
+## Overview
+코드 리뷰 기능을 설정하고 리뷰 결과를 확인합니다. AI 기반 자동 리뷰로 코드 품질을 향상시킵니다.
+
+## Steps
+
+1. **리뷰 활성화**
+   
+   `cursorflow.config.js` 파일에서 설정:
+   ```javascript
+   module.exports = {
+     enableReview: true,
+     reviewModel: 'sonnet-4.5-thinking',
+     maxReviewIterations: 3,
+     // ...
+   };
+   ```
+
+2. **Acceptance Criteria 정의**
+   
+   태스크 JSON 파일에 검증 기준 추가:
+   ```json
+   {
+     "tasks": [
+       {
+         "name": "implement",
+         "model": "sonnet-4.5",
+         "acceptanceCriteria": [
+           "빌드 에러 없음",
+           "TypeScript 타입 에러 없음",
+           "주요 기능 구현됨",
+           "테스트 통과"
+         ],
+         "prompt": "..."
+       }
+     ]
+   }
+   ```
+
+3. **리뷰 실행**
+   
+   리뷰는 태스크 완료 후 자동으로 실행됩니다.
+
+4. **리뷰 결과 확인**
+   ```bash
+   # 리뷰 결과 파일 확인
+   cat _cursorflow/logs/runs/<lane>/review-results.json
+   ```
+
+## 리뷰 모델
+
+| 모델 | 특징 | 권장 용도 |
+|------|------|-----------|
+| `sonnet-4.5-thinking` | 추론 강화, 정확한 분석 | 일반 코드 리뷰 (권장) |
+| `opus-4.5-thinking` | 최고 품질, 상세 리뷰 | 중요한 코드, 아키텍처 리뷰 |
+| `sonnet-4.5` | 빠른 리뷰 | 간단한 변경사항 |
+
+## 리뷰 프로세스
+
+1. **태스크 완료**
+   - 코드 구현 완료
+   - 커밋 생성
+
+2. **자동 리뷰 시작**
+   - 리뷰 모델로 에이전트 실행
+   - Acceptance Criteria 확인
+   - 빌드 및 타입 검증
+
+3. **리뷰 결과**
+   - `approved`: 다음 태스크로 진행
+   - `needs_changes`: 피드백 전달 → 재작업
+
+4. **피드백 루프**
+   - 수정 사항 구현
+   - 재리뷰
+   - 최대 반복 횟수까지 반복
+
+## 리뷰 결과 형식
+
+```json
+{
+  "status": "approved",
+  "buildSuccess": true,
+  "typeCheckSuccess": true,
+  "issues": [
+    {
+      "severity": "warning",
+      "description": "Consider adding error handling",
+      "file": "src/utils/api.js",
+      "line": 42,
+      "suggestion": "Add try-catch block"
+    }
+  ],
+  "suggestions": [
+    "Add unit tests for edge cases",
+    "Improve error messages"
+  ],
+  "summary": "Code quality is good, minor improvements suggested",
+  "reviewedBy": "sonnet-4.5-thinking",
+  "reviewedAt": "2025-12-19T18:30:00Z"
+}
+```
+
+## 예제
+
+### 기본 리뷰 설정
+```javascript
+// cursorflow.config.js
+{
+  enableReview: true,
+  reviewModel: 'sonnet-4.5-thinking',
+  maxReviewIterations: 3
+}
+```
+
+### 엄격한 리뷰
+```javascript
+{
+  enableReview: true,
+  reviewModel: 'opus-4.5-thinking',
+  maxReviewIterations: 5
+}
+```
+
+### 빠른 리뷰
+```javascript
+{
+  enableReview: true,
+  reviewModel: 'sonnet-4.5',
+  maxReviewIterations: 1
+}
+```
+
+## Acceptance Criteria 작성 가이드
+
+### 좋은 예시
+```json
+{
+  "acceptanceCriteria": [
+    "빌드 에러 없음 (pnpm build 성공)",
+    "TypeScript 타입 에러 없음 (pnpm type-check)",
+    "모든 기존 테스트 통과",
+    "새 API 엔드포인트 3개 구현됨",
+    "에러 처리 로직 포함됨",
+    "로그 추가됨"
+  ]
+}
+```
+
+### 나쁜 예시
+```json
+{
+  "acceptanceCriteria": [
+    "잘 작동함",
+    "코드가 좋음"
+  ]
+}
+```
+
+## 리뷰 결과 분석
+
+### 승인된 경우
+```bash
+# 다음 태스크 자동 진행
+# 로그에서 확인
+cursorflow monitor
+```
+
+### 수정 필요 시
+```bash
+# 피드백이 자동으로 에이전트에 전달됨
+# 재작업 후 자동 재리뷰
+# 로그에서 피드백 확인
+cat _cursorflow/logs/runs/<lane>/conversation.jsonl | \
+  jq 'select(.role=="reviewer")'
+```
+
+### 최대 반복 도달 시
+```bash
+# 경고 메시지와 함께 진행
+# 수동 리뷰 필요
+```
+
+## Checklist
+- [ ] 리뷰가 활성화되었는가?
+- [ ] 리뷰 모델이 적절한가?
+- [ ] Acceptance Criteria가 명확한가?
+- [ ] 최대 반복 횟수가 적절한가?
+- [ ] 리뷰 결과를 확인했는가?
+
+## 트러블슈팅
+
+### 리뷰가 실행되지 않음
+1. `enableReview: true` 확인
+2. 리뷰 모델이 유효한지 확인
+3. 로그에서 에러 확인
+
+### 무한 리뷰 루프
+1. `maxReviewIterations` 설정 확인
+2. Acceptance Criteria가 달성 가능한지 검토
+3. 태스크 프롬프트 개선
+
+### 리뷰가 너무 엄격함
+1. 리뷰 모델을 더 관대한 것으로 변경
+2. Acceptance Criteria 조정
+3. `maxReviewIterations` 증가
+
+## 모범 사례
+
+1. **명확한 기준**: Acceptance Criteria를 구체적으로 작성
+2. **적절한 모델**: 작업 복잡도에 맞는 리뷰 모델 선택
+3. **점진적 개선**: 첫 반복에서 모든 것을 완벽하게 하려 하지 말기
+4. **피드백 활용**: 리뷰 피드백을 다음 태스크 개선에 활용
+
+## Next Steps
+1. 리뷰 결과 분석
+2. 반복되는 이슈 패턴 파악
+3. 태스크 프롬프트 및 Criteria 개선
+4. 리뷰 모델 조정