@litmers/cursorflow-orchestrator 0.1.0 → 0.1.1

package/commands/cursorflow-monitor.md

@@ -1,131 +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. 로그 분석으로 개선점 파악
+# CursorFlow Monitor
+
+## Overview
+Monitor lane execution status. Track progress in real time and inspect logs.
+
+## Steps
+
+1. **Monitor in real time**
+   ```bash
+   cursorflow monitor --watch
+   ```
+
+2. **Monitor a specific run**
+   ```bash
+   cursorflow monitor _cursorflow/logs/runs/my-run/
+   ```
+
+3. **Check status**
+
+   Lane status values:
+   - pending: waiting
+   - running: in progress
+   - completed: finished
+   - failed: failed
+   - blocked_dependency: waiting on dependencies
+
+4. **Inspect logs**
+
+   Per-lane log files:
+   - `state.json`: current status
+   - `conversation.jsonl`: agent conversation
+   - `git-operations.jsonl`: Git activity
+   - `events.jsonl`: event log
+
+## Options
+
+| Option | Description |
+|------|------|
+| `--watch` | Refresh in real time (every 2 seconds) |
+| `--interval <sec>` | Refresh interval in seconds |
+| `--json` | Output in JSON format |
+
+## Examples
+
+### Monitor the latest run
+```bash
+cursorflow monitor
+```
+
+### Real-time monitoring (5-second interval)
+```bash
+cursorflow monitor --watch --interval 5
+```
+
+### JSON output
+```bash
+cursorflow monitor --json | jq
+```
+
+## Sample output
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  📡 Lane Status Monitoring
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Run: 01-dashboard-2025-12-19T18-30-00
+
+- 01-dashboard: running (2/3)
+- 02-client: completed (3/3)
+- 03-projects: blocked_dependency (1/2)
+```
+
+## Viewing logs
+
+### Conversation history
+```bash
+cat _cursorflow/logs/runs/01-dashboard-xxx/conversation.jsonl | jq
+```
+
+### Git activity log
+```bash
+cat _cursorflow/logs/runs/01-dashboard-xxx/git-operations.jsonl | jq
+```
+
+### Event log
+```bash
+cat _cursorflow/logs/runs/01-dashboard-xxx/events.jsonl | jq
+```
+
+## Status analysis
+
+### Progress per lane
+```bash
+# Inspect state.json for all lanes
+for state in _cursorflow/logs/runs/*/lanes/*/state.json; do
+  echo "$(dirname $state):"
+  jq '.status, .currentTaskIndex, .totalTasks' $state
+done
+```
+
+### Find failed lanes
+```bash
+# Lanes where status is failed
+find _cursorflow/logs/runs -name "state.json" -exec sh -c \
+  'jq -r "select(.status==\"failed\") | .label" {}' \;
+```
+
+## Checklist
+- [ ] Are lane states healthy?
+- [ ] Did any errors occur?
+- [ ] Have the logs been reviewed?
+- [ ] Are any lanes blocked?
+- [ ] Are there dependency issues?
+
+## Troubleshooting
+
+### Lane is stuck
+1. Check status in `state.json`.
+2. Inspect the last conversation in `conversation.jsonl`.
+3. Resume if needed with `cursorflow resume <lane>`.
+
+### Logs are missing
+1. Confirm the run actually started.
+2. Check log directory permissions.
+3. Verify the `logsDir` path in the config file.
+
+## Next steps
+1. If you find issues, resume with `cursorflow resume`.
+2. Review PRs for completed lanes.
+3. Analyze logs to identify improvements.

package/commands/cursorflow-prepare.md

@@ -1,134 +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`으로 태스크 실행
+# 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,
+     "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": [
+           "Plan document created"
+         ],
+         "prompt": "..."
+       }
+     ]
+   }
+   ```
+
+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
+```
+
+### Multi-lane task
+```bash
+cursorflow prepare AdminDashboard --lanes 5
+```
+
+### Using a custom template
+```bash
+cursorflow prepare MyFeature --template ./my-template.json
+```
+
+## 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?
+
+## 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, ...).
+
+## Next steps
+1. Tailor the generated JSON files to the project.
+2. Write detailed prompts.
+3. Run the tasks with `cursorflow run`.