@litmers/cursorflow-orchestrator 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,78 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Initial package structure
+- Core utilities (config, logger, git, cursor-agent, state)
+- CLI commands (init, run, monitor, clean, resume)
+- Cursor IDE commands (7 commands)
+- Configuration system
+- Documentation
+
+## [1.0.0] - TBD
+
+### Added
+- Git worktree-based orchestration
+- Parallel lane execution
+- AI code review integration
+- Detailed logging (conversation, git operations, events)
+- Dependency management
+- Lane monitoring
+- Branch and worktree management
+- Cursor IDE integration
+- Configuration-based setup
+- CLI interface
+- Comprehensive documentation
+
+### Features
+- **Parallel Execution**: Multiple lanes running simultaneously
+- **Auto Review**: AI-based code review and feedback loop
+- **Detailed Logging**: Full conversation and operation logs
+- **Dependency Gate**: Automatic dependency change handling
+- **Lane Ports**: Unique dev server port per lane
+- **Cursor Integration**: Custom commands for IDE
+- **Config System**: Flexible project-based configuration
+
+### Documentation
+- README with quick start guide
+- Usage guide (GUIDE.md)
+- API reference (API.md)
+- Command guide (COMMANDS.md)
+- Architecture documentation (ARCHITECTURE.md)
+- Troubleshooting guide (TROUBLESHOOTING.md)
+- Examples
+
+### Dependencies
+- Node.js >= 18.0.0
+- Git with worktree support
+- cursor-agent CLI
+
+---
+
+## Release Notes Template
+
+### [X.Y.Z] - YYYY-MM-DD
+
+#### Added
+- New features
+
+#### Changed
+- Changes in existing functionality
+
+#### Deprecated
+- Soon-to-be removed features
+
+#### Removed
+- Removed features
+
+#### Fixed
+- Bug fixes
+
+#### Security
+- Security improvements

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Eugene Jin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,310 @@
+# CursorFlow
+
+> Git worktree 기반 병렬 AI 에이전트 오케스트레이션 시스템
+
+[![npm version](https://img.shields.io/npm/v/@cursorflow/orchestrator.svg)](https://www.npmjs.com/package/@cursorflow/orchestrator)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)
+
+## 주요 기능
+
+- 🚀 **병렬 실행**: Git worktree를 활용한 여러 레인 동시 실행
+- 🔍 **자동 리뷰**: AI 기반 코드 리뷰 및 피드백 루프
+- 📝 **상세 로깅**: 대화, 커밋, Git 작업 전문 기록
+- 🔀 **의존성 관리**: 자동 dependency gate 및 재개
+- 🎯 **레인별 포트**: 각 레인에 고유한 개발 서버 포트 할당
+- 💻 **Cursor 통합**: 커스텀 커맨드로 IDE 내에서 직접 관리
+- 🛠️ **설정 기반**: 프로젝트별 유연한 설정
+
+## 빠른 시작
+
+### 설치
+
+```bash
+# npm
+npm install -g @litmers/cursorflow-orchestrator
+
+# pnpm (권장)
+pnpm add -g @cursorflow/orchestrator
+
+# yarn
+yarn global add @cursorflow/orchestrator
+```
+
+### 요구사항
+
+- **Node.js** >= 18.0.0
+- **Git** with worktree support
+- **cursor-agent CLI**: `npm install -g @cursor/agent`
+
+### 프로젝트 초기화
+
+```bash
+cd your-project
+cursorflow init --example
+```
+
+이 명령은:
+1. `cursorflow.config.js` 설정 파일 생성
+2. `_cursorflow/tasks/` 및 `_cursorflow/logs/` 디렉토리 생성
+3. Cursor IDE 커맨드 설치
+4. 예제 태스크 생성 (--example 옵션 사용 시)
+
+### 예제 실행
+
+```bash
+# 예제 태스크 실행
+cursorflow run _cursorflow/tasks/example/
+
+# 다른 터미널에서 모니터링
+cursorflow monitor --watch
+```
+
+## Cursor IDE 통합
+
+CursorFlow는 Cursor IDE 내에서 사용할 수 있는 커스텀 커맨드를 제공합니다.
+
+### 커맨드 설치
+
+```bash
+# 초기화 시 자동 설치
+cursorflow init
+
+# 또는 수동 설치
+npx cursorflow-setup
+```
+
+### 사용법
+
+Cursor IDE 채팅에서 `/` 입력 후 다음 커맨드 사용:
+
+- `/cursorflow-init` - 프로젝트 초기화
+- `/cursorflow-prepare` - 태스크 준비
+- `/cursorflow-run` - 오케스트레이션 실행
+- `/cursorflow-monitor` - 실행 모니터링
+- `/cursorflow-clean` - 정리 작업
+- `/cursorflow-resume` - 중단된 레인 재개
+- `/cursorflow-review` - 리뷰 설정 및 확인
+
+## CLI 명령어
+
+### 초기화
+```bash
+cursorflow init [options]
+  --example          예제 태스크 생성
+  --with-commands    Cursor 커맨드 설치 (기본: true)
+  --config-only      설정 파일만 생성
+```
+
+### 태스크 준비
+```bash
+cursorflow prepare <feature> [options]
+  --lanes <number>   레인 개수
+  --template <path>  템플릿 파일 경로
+```
+
+### 실행
+```bash
+cursorflow run <tasks-dir> [options]
+  --dry-run         실행 계획만 확인
+  --executor <type>  cursor-agent | cloud
+```
+
+### 모니터링
+```bash
+cursorflow monitor [run-dir] [options]
+  --watch           실시간 모니터링
+  --interval <sec>  갱신 간격
+```
+
+### 정리
+```bash
+cursorflow clean <type> [options]
+  branches          브랜치 정리
+  worktrees         워크트리 정리
+  logs              로그 정리
+  all               모두 정리
+```
+
+### 재개
+```bash
+cursorflow resume <lane> [options]
+  --clean           브랜치 정리 후 재시작
+  --restart         처음부터 다시 시작
+```
+
+## 설정
+
+### 설정 파일 (cursorflow.config.js)
+
+```javascript
+module.exports = {
+  // 디렉토리 설정
+  tasksDir: '_cursorflow/tasks',
+  logsDir: '_cursorflow/logs',
+  
+  // Git 설정
+  baseBranch: 'main',
+  branchPrefix: 'feature/',
+  
+  // 실행 설정
+  executor: 'cursor-agent',  // 'cursor-agent' | 'cloud'
+  pollInterval: 60,
+  
+  // 의존성 관리
+  allowDependencyChange: false,
+  lockfileReadOnly: true,
+  
+  // 리뷰 설정
+  enableReview: true,
+  reviewModel: 'sonnet-4.5-thinking',
+  maxReviewIterations: 3,
+  
+  // 레인 기본 설정
+  defaultLaneConfig: {
+    devPort: 3001,
+    autoCreatePr: false,
+  },
+  
+  // 로깅
+  logLevel: 'info',
+  verboseGit: false,
+};
+```
+
+### 태스크 파일 (JSON)
+
+```json
+{
+  "repository": "https://github.com/your-org/your-repo",
+  "baseBranch": "main",
+  "branchPrefix": "feature/my-",
+  "executor": "cursor-agent",
+  "laneNumber": 1,
+  "devPort": 3001,
+  "enableReview": true,
+  "tasks": [
+    {
+      "name": "implement",
+      "model": "sonnet-4.5",
+      "acceptanceCriteria": [
+        "빌드 에러 없음",
+        "주요 기능 구현됨"
+      ],
+      "prompt": "구현 지시사항..."
+    }
+  ]
+}
+```
+
+## 사용 예시
+
+### 단일 기능 개발
+
+```bash
+# 1. 태스크 준비
+cursorflow prepare AddUserAuth --lanes 1
+
+# 2. 태스크 JSON 편집
+# _cursorflow/tasks/2512191830_AddUserAuth/01-task.json
+
+# 3. 실행
+cursorflow run _cursorflow/tasks/2512191830_AddUserAuth/
+
+# 4. 모니터링
+cursorflow monitor --watch
+```
+
+### 멀티 도메인 병렬 개발
+
+```bash
+# 1. 태스크 준비 (5개 레인)
+cursorflow prepare AdminDashboard --lanes 5
+
+# 2. 각 레인 설정
+# 01-dashboard.json, 02-clients.json, ...
+
+# 3. 병렬 실행
+cursorflow run _cursorflow/tasks/2512191830_AdminDashboard/
+
+# 4. 실시간 모니터링
+cursorflow monitor --watch --interval 5
+```
+
+## 아키텍처
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    CursorFlow CLI                       │
+└──────────────────┬──────────────────────────────────────┘
+                   │
+        ┌──────────┴──────────┐
+        │                     │
+   ┌────▼────┐          ┌────▼────┐
+   │ Config  │          │  Core   │
+   │ System  │          │ Engine  │
+   └────┬────┘          └────┬────┘
+        │                    │
+        │         ┌──────────┼──────────┐
+        │         │          │          │
+   ┌────▼────┐ ┌─▼──┐  ┌────▼────┐  ┌─▼─────┐
+   │   Git   │ │Run │  │ Monitor │  │Review │
+   │ Utils   │ │ner │  │         │  │       │
+   └─────────┘ └─┬──┘  └─────────┘  └───────┘
+                 │
+        ┌────────┼────────┐
+        │        │        │
+   ┌────▼───┐ ┌─▼──────┐ │
+   │Worktree│ │ Cursor │ │
+   │        │ │ Agent  │ │
+   └────────┘ └────────┘ │
+                          │
+                     ┌────▼────┐
+                     │  Logs   │
+                     │  State  │
+                     └─────────┘
+```
+
+## 문서
+
+- [📖 사용 가이드](docs/GUIDE.md) - 상세한 사용 방법
+- [📋 API 레퍼런스](docs/API.md) - CLI 및 설정 API
+- [🎨 커맨드 가이드](docs/COMMANDS.md) - Cursor 커맨드 사용법
+- [🏗️ 아키텍처](docs/ARCHITECTURE.md) - 시스템 구조
+- [🔧 트러블슈팅](docs/TROUBLESHOOTING.md) - 문제 해결
+- [📦 예제 모음](examples/) - 실전 예제
+
+## 로드맵
+
+- [ ] v1.0: 핵심 기능 및 기본 문서
+- [ ] v1.1: 향상된 리뷰 시스템
+- [ ] v1.2: 클라우드 실행 개선
+- [ ] v1.3: 플러그인 시스템
+- [ ] v2.0: GUI 도구
+
+## 기여하기
+
+기여는 환영합니다! [CONTRIBUTING.md](CONTRIBUTING.md)를 참조해주세요.
+
+### 개발 환경 설정
+
+```bash
+git clone https://github.com/eungjin-cigro/cursorflow.git
+cd cursorflow
+pnpm install
+pnpm test
+```
+
+## 라이선스
+
+MIT © Eugene Jin
+
+## 지원
+
+- 🐛 [Issue Tracker](https://github.com/eungjin-cigro/cursorflow/issues)
+- 💬 [Discussions](https://github.com/eungjin-cigro/cursorflow/discussions)
+- 📧 Email: eungjin.cigro@gmail.com
+
+---
+
+**Made with ❤️ for Cursor IDE users**

package/commands/cursorflow-clean.md

@@ -0,0 +1,162 @@
+# CursorFlow Clean
+
+## Overview
+브랜치, 워크트리, 로그 등을 정리합니다. 오래된 파일이나 실패한 실행의 잔여물을 제거합니다.
+
+## Steps
+
+1. **정리 타입 선택**
+   
+   | 타입 | 설명 |
+   |------|------|
+   | `branches` | Git 브랜치 정리 |
+   | `worktrees` | Git worktree 정리 |
+   | `logs` | 로그 파일 정리 |
+   | `all` | 모두 정리 |
+
+2. **브랜치 정리**
+   ```bash
+   cursorflow clean branches --pattern "feature/my-*"
+   ```
+
+3. **워크트리 정리**
+   ```bash
+   cursorflow clean worktrees --all
+   ```
+
+4. **로그 정리**
+   ```bash
+   cursorflow clean logs --older-than 30
+   ```
+
+5. **Dry run으로 확인**
+   ```bash
+   cursorflow clean all --dry-run
+   ```
+
+## 옵션
+
+| 옵션 | 설명 |
+|------|------|
+| `--pattern <pattern>` | 패턴 매칭 (예: "feature/*") |
+| `--older-than <days>` | N일 이상 된 항목만 (logs용) |
+| `--dry-run` | 삭제할 항목만 표시 |
+| `--force` | 확인 없이 삭제 |
+| `--local-only` | 로컬만 (브랜치용) |
+| `--remote-only` | 원격만 (브랜치용) |
+
+## 예제
+
+### 브랜치 정리
+
+#### 패턴 매칭으로 삭제
+```bash
+cursorflow clean branches --pattern "feature/dashboard-*"
+```
+
+#### 모든 CursorFlow 브랜치
+```bash
+cursorflow clean branches --pattern "feature/*" --dry-run
+```
+
+#### 로컬 브랜치만
+```bash
+cursorflow clean branches --pattern "feature/*" --local-only
+```
+
+### 워크트리 정리
+
+#### 모든 워크트리
+```bash
+cursorflow clean worktrees --all
+```
+
+#### 특정 패턴
+```bash
+cursorflow clean worktrees --pattern "*-dashboard-*"
+```
+
+### 로그 정리
+
+#### 30일 이상 된 로그
+```bash
+cursorflow clean logs --older-than 30
+```
+
+#### 모든 로그
+```bash
+cursorflow clean logs --all --force
+```
+
+### 전체 정리
+
+#### 모두 확인 후 삭제
+```bash
+cursorflow clean all --dry-run
+cursorflow clean all --force
+```
+
+## 정리 결과
+
+```
+🧹 Cleaning CursorFlow Resources
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Branches to delete:
+  - feature/dashboard-pipeline-abc123 (local)
+  - feature/dashboard-pipeline-abc123 (remote)
+  - feature/client-pipeline-def456 (local)
+
+Worktrees to remove:
+  - .cursorflow/logs/worktrees/01-dashboard-pipeline-abc123
+  - .cursorflow/logs/worktrees/02-client-pipeline-def456
+
+Logs to delete:
+  - _cursorflow/logs/runs/01-dashboard-2025-12-10T10-00-00 (9 days old)
+
+Total: 5 branches, 2 worktrees, 1 log directory
+
+Proceed? [y/N]
+```
+
+## 주의사항
+
+1. **백업**: 중요한 작업 중인 브랜치는 백업
+2. **확인**: `--dry-run`으로 먼저 확인
+3. **원격**: 원격 브랜치 삭제는 신중하게
+4. **복구**: 삭제된 항목은 복구 어려움
+
+## Checklist
+- [ ] 정리할 항목을 확인했는가?
+- [ ] 백업이 필요한가?
+- [ ] dry-run으로 먼저 확인했는가?
+- [ ] 다른 사람이 사용 중인 브랜치는 아닌가?
+- [ ] 원격 저장소에서도 삭제할 것인가?
+
+## 트러블슈팅
+
+### 브랜치 삭제 실패
+```bash
+# 강제 삭제
+git branch -D <branch-name>
+git push origin --delete <branch-name>
+```
+
+### 워크트리 제거 실패
+```bash
+# 강제 제거
+git worktree remove --force <worktree-path>
+```
+
+### 로그 디렉토리 권한 문제
+```bash
+# 권한 확인
+ls -la _cursorflow/logs/
+# 권한 수정
+chmod -R u+w _cursorflow/logs/
+```
+
+## Next Steps
+1. 정기적으로 로그 정리 (예: 월 1회)
+2. CI/CD에 자동 정리 스크립트 추가
+3. `.gitignore`에 로그 디렉토리 추가

package/commands/cursorflow-init.md

@@ -0,0 +1,67 @@
+# CursorFlow Init
+
+## Overview
+프로젝트에 CursorFlow를 초기화합니다. 설정 파일과 디렉토리 구조를 생성하고, 선택적으로 Cursor 커맨드와 예제 태스크를 설치합니다.
+
+## Steps
+
+1. **초기화 실행**
+   ```bash
+   cursorflow init
+   ```
+
+2. **옵션 선택**
+   - `--example`: 예제 태스크 생성
+   - `--config-only`: 설정 파일만 생성
+   - `--no-commands`: Cursor 커맨드 설치 건너뛰기
+   - `--force`: 기존 파일 덮어쓰기
+
+3. **생성 확인**
+   - `cursorflow.config.js` 파일 생성됨
+   - `_cursorflow/tasks/` 디렉토리 생성됨
+   - `_cursorflow/logs/` 디렉토리 생성됨
+   - `.cursor/commands/cursorflow/` 커맨드 설치됨 (선택)
+
+4. **설정 파일 검토**
+   ```javascript
+   // cursorflow.config.js
+   module.exports = {
+     tasksDir: '_cursorflow/tasks',
+     logsDir: '_cursorflow/logs',
+     baseBranch: 'main',
+     // ... 기타 설정
+   };
+   ```
+
+## 예제
+
+### 기본 초기화
+```bash
+cursorflow init
+```
+
+### 예제 태스크 포함
+```bash
+cursorflow init --example
+```
+
+### 설정 파일만 생성
+```bash
+cursorflow init --config-only
+```
+
+### 기존 파일 덮어쓰기
+```bash
+cursorflow init --force
+```
+
+## Checklist
+- [ ] 설정 파일이 프로젝트 루트에 생성되었는가?
+- [ ] 필요한 디렉토리가 생성되었는가?
+- [ ] Cursor 커맨드가 설치되었는가?
+- [ ] 설정 내용이 프로젝트에 맞게 조정되었는가?
+
+## Next Steps
+1. `cursorflow.config.js` 파일을 프로젝트에 맞게 수정
+2. Cursor IDE에서 `/` 입력하여 커맨드 확인
+3. `cursorflow prepare MyFeature`로 태스크 생성 시작