@elyun/bylane 1.0.0

package/docs/superpowers/specs/2026-04-04-bylane-design.md

@@ -0,0 +1,324 @@
+# byLane — Frontend Development Harness for Claude Code
+
+**Date:** 2026-04-04  
+**Status:** Draft  
+
+---
+
+## 1. 목적
+
+byLane은 Claude Code 위에서 동작하는 프론트엔드 개발 자동화 하네스다. GitHub Issues(또는 Linear)에서 시작해 코드 구현, 테스트, 커밋, PR 생성, 리뷰, 리뷰 반영까지 전체 개발 워크플로우를 에이전트 기반으로 자동화한다.
+
+각 에이전트는 독립 실행도 가능하고, 타인의 원격 작업(이슈, PR, 리뷰 등)을 대상으로도 동작한다.
+
+---
+
+## 2. 핵심 결정 사항
+
+| 항목 | 결정 |
+|---|---|
+| 배포 형태 | Skills 파일 세트 (`~/.claude/` 하위), 별도 인프라 없음 |
+| 트리거 방식 | 혼합 — `/bylane [자연어]` slash command + 자연어 감지 |
+| 에이전트 아키텍처 | 오케스트레이터 + 워커 에이전트 패턴 |
+| 이슈 트래커 | GitHub Issues 주, Linear 선택적 |
+| 알림 | Slack / Telegram 선택 (설치 시 설정) |
+| Figma MCP | 선택적 활성화 — 이슈 분석 단계에서 스펙 추출 |
+| 피드백 루프 | 기본값 3회 + 사용자 설정 오버라이드 |
+| 모니터링 | `/bylane monitor` — 2열 그리드 터미널 TUI 대시보드 |
+
+---
+
+## 3. 전체 아키텍처
+
+```
+byLane/
+├── skills/
+│   ├── orchestrator.md          # 전체 워크플로우 총괄
+│   ├── setup.md                 # 최초 설치 셋업 위자드
+│   ├── monitor.md               # 실시간 터미널 대시보드
+│   │
+│   ├── issue-agent.md           # 이슈 생성/분석 (GitHub + Linear)
+│   ├── code-agent.md            # 코드 구현 (Figma MCP 선택적)
+│   ├── test-agent.md            # 테스트 실행 및 검증
+│   ├── commit-agent.md          # 커밋 생성
+│   ├── pr-agent.md              # PR 생성/관리
+│   ├── review-agent.md          # PR 리뷰 수행
+│   ├── respond-agent.md         # 리뷰 반박/반영
+│   └── notify-agent.md          # 최종 알림 (Slack/Telegram)
+│
+├── hooks/
+│   ├── post-tool-use.md         # 외부 이벤트 감지 (타인의 PR, 리뷰)
+│   └── natural-language.md      # 자연어 트리거 감지
+│
+├── config/
+│   └── bylane.json              # 설치 시 생성되는 설정 파일
+│
+└── commands/
+    ├── bylane.md                # /bylane 메인 커맨드
+    └── bylane-monitor.md        # /bylane-monitor 대시보드
+```
+
+---
+
+## 4. 워크플로우
+
+### 오케스트레이터 동작 방식
+
+`/bylane [자연어]` 실행 시 오케스트레이터가 의도를 파싱하여 어디서 시작하고 어디서 끝낼지 결정한다.
+
+```
+/bylane 다크모드 토글 추가해줘
+  → issue-agent (이슈 생성) → code-agent → test-agent → commit-agent
+  → pr-agent → review-agent → notify-agent
+
+/bylane issue #123 구현해줘
+  → issue-agent (분석만) → code-agent → ... → notify-agent
+
+/bylane PR #45 리뷰해줘
+  → review-agent만 실행
+
+/bylane 리뷰 #45 반영해줘
+  → respond-agent만 실행
+```
+
+### 전체 파이프라인
+
+```
+[진입점]
+  /bylane [자연어]  OR  자연어 감지  OR  외부 이벤트 (hooks)
+       │
+       ▼
+[orchestrator] ── 의도 파악 + bylane.json 설정 로드
+       │
+       ├─► [issue-agent]    이슈 분석, Figma 링크 있으면 스펙 추출
+       │         ↓
+       ├─► [code-agent]     구현 (Figma 스펙 참조)
+       │         ↓
+       ├─► [test-agent]     테스트 실행
+       │         ↕ FAIL 시 code-agent로 피드백 루프 (최대 maxRetries)
+       │         ↓ PASS
+       ├─► [commit-agent]   커밋 생성
+       │         ↓
+       ├─► [pr-agent]       PR 생성
+       │         ↓
+       ├─► [review-agent]   자동 리뷰
+       │         ↓
+       ├─► [respond-agent]  반박 or 반영 → LGTM까지 루프
+       │         ↓
+       └─► [notify-agent]   Slack/Telegram 완료 알림
+```
+
+### 에이전트 역할
+
+| 에이전트 | 트리거 | 입력 | 출력 |
+|---|---|---|---|
+| **orchestrator** | `/bylane`, 자연어 | 사용자 의도 | 에이전트 실행 계획 |
+| **issue-agent** | 수동 or 오케스트레이터 | 이슈 텍스트/번호 | 구현 스펙 JSON |
+| **code-agent** | 수동 or 오케스트레이터 | 스펙 + 코드베이스 | 변경된 파일들 |
+| **test-agent** | 수동 or 코드 완료 후 | 변경 파일들 | 통과/실패 + 피드백 |
+| **commit-agent** | 수동 or 테스트 통과 후 | 변경 파일들 | 커밋 SHA |
+| **pr-agent** | 수동 or 커밋 후 | 커밋 목록 | PR URL |
+| **review-agent** | 수동 or PR 오픈 후 | PR diff | 리뷰 코멘트 |
+| **respond-agent** | 수동 or 리뷰 수신 후 | 리뷰 코멘트 | 반박/수정 커밋 |
+| **notify-agent** | 수동 or 워크플로우 완료 | 결과 요약 | Slack/Telegram 메시지 |
+
+### 피드백 루프 규칙
+
+```
+루프 최대 횟수: bylane.json의 maxRetries (기본값: 3)
+에스컬레이션 조건:
+  - maxRetries 초과 시
+  - 에이전트가 "해결 불가" 판단 시
+에스컬레이션: notify-agent로 "개입 필요" 알림 후 대기
+```
+
+### 외부 이벤트 처리
+
+```
+hooks/post-tool-use → GitHub PR 오픈 감지    → review-agent 자동 실행
+                    → 리뷰 코멘트 수신 감지   → respond-agent 자동 실행
+                    → CI 실패 감지            → code-agent 재실행
+```
+
+---
+
+## 5. 슬래시 커맨드
+
+| 커맨드 | 동작 |
+|---|---|
+| `/bylane [자연어]` | 오케스트레이터 — 전체 워크플로우 자동 실행 |
+| `/bylane setup` | 셋업 위자드 (재실행 가능) |
+| `/bylane monitor` | 실시간 TUI 대시보드 |
+| `/bylane issue [#번호 or 텍스트]` | issue-agent 단독 실행 |
+| `/bylane code [#번호]` | code-agent 단독 실행 |
+| `/bylane test` | test-agent 단독 실행 |
+| `/bylane commit` | commit-agent 단독 실행 |
+| `/bylane pr` | pr-agent 단독 실행 |
+| `/bylane review [PR번호]` | review-agent 단독 실행 |
+| `/bylane respond [PR번호]` | respond-agent 단독 실행 |
+| `/bylane notify` | notify-agent 단독 실행 |
+| `/bylane status` | 현재 워크플로우 상태 한 줄 요약 |
+
+---
+
+## 6. 모니터링 대시보드 (`/bylane monitor`)
+
+2열 그리드 터미널 TUI. Node.js `blessed` 또는 `ink` 기반.
+
+```
+╔══════════════════════════════════════════════════════════════════════════════════╗
+║  byLane Monitor   Issue #123: "Add dark mode toggle"   Elapsed: 4m 31s  17:32:41║
+╠═══════════════════════════════════════╦════════════════════════════════════════ ║
+║  AGENT PIPELINE                       ║  AGENT LOG                    [LIVE]   ║
+║                                       ║                                         ║
+║  issue-agent   [✓] 완료    2m 12s    ║  17:32:38 code-agent                   ║
+║  code-agent    [▶] 실행중  ████░ 67% ║    → ThemeToggle.tsx 생성              ║
+║  test-agent    [○] 대기               ║  17:32:35 code-agent                   ║
+║  commit-agent  [○] 대기               ║    → useTheme hook 구현 중...          ║
+║  pr-agent      [○] 대기               ║  17:32:21 code-agent                   ║
+║  review-agent  [○] 대기               ║    → Figma color token 로드            ║
+║  respond-agent [○] 대기               ║  17:30:09 issue-agent                  ║
+║  notify-agent  [○] 대기               ║    → ✓ 완료 - spec.json 저장됨         ║
+║                                       ║  17:28:14 orchestrator                 ║
+║  Retries: 1/3   maxRetries: 3        ║    → workflow 시작 (Issue #123)        ║
+╠═══════════════════════════════════════╬════════════════════════════════════════╣
+║  QUEUE                                ║  SYSTEM STATUS                          ║
+║                                       ║                                         ║
+║  #  TYPE        TARGET    STATUS      ║  GitHub       ✓ 연결됨                 ║
+║  1  Issue #124  code      대기중      ║  Linear       ✗ 비활성                 ║
+║  2  PR #45      review    대기중      ║  Figma MCP    ✓ 활성                   ║
+║  3  Issue #125  full-flow 예약됨      ║  Slack        ✓ #dev-alerts            ║
+║                                       ║  Telegram     ✗ 미설정                 ║
+║                                       ║                                         ║
+║                                       ║  팀 모드      ✓ 활성 (3명)             ║
+║                                       ║  권한 범위    write (코드/PR)           ║
+╚═══════════════════════════════════════╩════════════════════════════════════════╝
+  [q]종료  [p]일시정지  [c]현재작업취소  [Tab]포커스전환  [↑↓]로그스크롤  [?]도움말
+```
+
+**패널 구성:**
+
+| 패널 | 위치 | 내용 |
+|---|---|---|
+| Header | 상단 전체 | 현재 작업명 + 경과시간 + 시각 |
+| Agent Pipeline | 좌상 | 파이프라인 상태 + 재시도 현황 |
+| Agent Log | 우상 | 실시간 로그 스크롤 (최근 50줄) |
+| Queue | 좌하 | 대기/예약 작업 목록 |
+| System Status | 우하 | 연동 서비스 상태 + 설정 요약 |
+| Footer | 하단 전체 | 키보드 단축키 |
+
+**데이터 소스:** `.bylane/state/*.json` 파일 폴링(1초 간격)
+
+---
+
+## 7. 셋업 위자드 (`/bylane setup`)
+
+최초 설치 또는 재설정 시 실행. 6단계 인터랙티브 프롬프트.
+
+```
+1/6  이슈 트래커       GitHub Issues (주) / Linear (선택) / 둘 다
+2/6  알림 채널         Slack / Telegram / 둘 다 / 건너뜀
+3/6  팀 모드           활성화 여부 + 팀원 GitHub 핸들 입력
+4/6  권한 범위         read-only / write(코드+PR) / full(머지 포함)
+5/6  고급 설정         maxRetries (기본 3), Figma MCP 활성화, 루프 타임아웃
+6/6  브랜치 네이밍     패턴 선택 또는 커스텀 토큰 조합
+```
+
+---
+
+## 8. 설정 파일 (`bylane.json`)
+
+```json
+{
+  "version": "1.0",
+  "trackers": {
+    "primary": "github",
+    "linear": { "enabled": false, "apiKey": "$LINEAR_API_KEY" }
+  },
+  "notifications": {
+    "slack": { "enabled": true, "channel": "#dev-alerts" },
+    "telegram": { "enabled": false, "chatId": "" }
+  },
+  "team": {
+    "enabled": true,
+    "members": ["@alice", "@bob"],
+    "reviewAssignment": "round-robin"
+  },
+  "permissions": {
+    "scope": "write",
+    "allowMerge": false,
+    "allowForceClose": false
+  },
+  "workflow": {
+    "maxRetries": 3,
+    "loopTimeoutMinutes": 30,
+    "autoEscalate": true
+  },
+  "branch": {
+    "pattern": "{tracker}-{issue-number}-{custom-id}",
+    "tokens": {
+      "tracker": "issues",
+      "type": "feature",
+      "custom-id": ""
+    },
+    "separator": "-",
+    "caseStyle": "kebab-case"
+  },
+  "extensions": {
+    "figma": {
+      "enabled": true,
+      "useAt": "issue-analysis"
+    }
+  }
+}
+```
+
+**브랜치 네이밍 토큰:**
+
+| 토큰 | 예시 |
+|---|---|
+| `{tracker}` | `issues`, `feat` |
+| `{issue-number}` | `32` |
+| `{custom-id}` | `C-12` (비어있으면 토큰 제외) |
+| `{type}` | `feature`, `fix` |
+| `{title-slug}` | `add-dark-mode` |
+| `{date}` | `20260404` |
+| `{username}` | `jhyoon` |
+
+**패턴 예시:**
+- `{tracker}-{issue-number}-{custom-id}` → `issues-32-C-12` 또는 `issues-32`
+- `{type}/{issue-number}-{title-slug}` → `feature/32-add-dark-mode`
+
+---
+
+## 9. 상태 관리
+
+각 에이전트는 작업 중 `.bylane/state/{agent-name}.json`에 상태를 기록한다.
+
+```json
+{
+  "agent": "code-agent",
+  "status": "in_progress",
+  "startedAt": "2026-04-04T17:28:10Z",
+  "progress": 67,
+  "currentTask": "ThemeToggle.tsx 구현 중",
+  "retries": 1,
+  "log": [
+    { "ts": "17:32:38", "msg": "ThemeToggle.tsx 생성" },
+    { "ts": "17:32:35", "msg": "useTheme hook 구현 중..." }
+  ]
+}
+```
+
+---
+
+## 10. 구현 스택
+
+| 항목 | 선택 |
+|---|---|
+| 하네스 형태 | Claude Code skills/agents/hooks 파일 세트 |
+| MCP 의존성 | GitHub MCP, Figma MCP (선택), Slack MCP, Telegram MCP |
+| 대시보드 | Node.js + `blessed` 또는 `ink` (터미널 TUI) |
+| 상태 저장 | `.bylane/state/*.json` (파일 기반) |
+| 설정 | `.bylane/bylane.json` |
+| 외부 인프라 | 없음 |

package/hooks/post-tool-use.md

@@ -0,0 +1,40 @@
+---
+name: bylane-post-tool-use
+description: GitHub 이벤트 감지 후 적절한 byLane 에이전트를 자동 트리거한다.
+trigger: post-tool-use
+---
+
+# byLane External Event Hook
+
+GitHub MCP 도구 사용 후 결과를 분석하여 자동으로 에이전트를 트리거한다.
+
+## 비활성화 조건
+
+`.bylane/bylane.json`에 `"hookAutoTrigger": false`가 있으면 이 hook을 실행하지 않는다.
+
+## 감지 규칙
+
+### PR 오픈 감지
+
+GitHub MCP 도구 결과에서 다음 조건이 모두 충족될 때:
+- `state: "open"`인 PR 존재
+- `user.login`이 `.bylane/bylane.json`의 `team.members` 중 하나
+- `team.enabled: true`
+
+→ `bylane-review-agent` 스킬 실행 (PR 번호 전달)
+
+### 리뷰 코멘트 수신 감지
+
+GitHub MCP 결과에서 다음 조건이 충족될 때:
+- 내 PR에 `review_state: "changes_requested"` 발견
+
+→ `bylane-respond-agent` 스킬 실행 (PR 번호 전달)
+
+### CI 실패 감지
+
+GitHub MCP `get_pull_request_status` 결과에서:
+- `state: "failure"` 발견
+
+→ `.bylane/state/code-agent.json`의 `retries` 확인
+→ `retries < config.workflow.maxRetries`이면 `bylane-code-agent` 재실행
+→ 초과 시 `bylane-notify-agent`로 에스컬레이션

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@elyun/bylane",
+  "version": "1.0.0",
+  "description": "Frontend development harness for Claude Code",
+  "type": "module",
+  "bin": {
+    "bylane": "./src/cli.js",
+    "bylane-monitor": "./src/monitor/index.js"
+  },
+  "scripts": {
+    "monitor": "node src/monitor/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "blessed": "^0.1.81",
+    "chokidar": "^3.6.0"
+  },
+  "devDependencies": {
+    "vitest": "^1.6.0"
+  }
+}

package/skills/code-agent.md

@@ -0,0 +1,69 @@
+---
+name: bylane-code-agent
+description: issue-agent의 스펙을 기반으로 프론트엔드 코드를 구현한다.
+---
+
+# Code Agent
+
+## 입력
+
+`.bylane/state/issue-agent.json`에서 `spec` 읽기. 없으면 사용자에게 스펙 텍스트 직접 입력 요청.
+
+## 실행 전 상태 기록
+
+```bash
+node -e "
+import('./src/state.js').then(({writeState}) => {
+  writeState('code-agent', {
+    status: 'in_progress',
+    startedAt: new Date().toISOString(),
+    progress: 0,
+    currentTask: '코드 구현 시작',
+    retries: 0,
+    log: []
+  })
+})
+"
+```
+
+## 실행 흐름
+
+1. `.bylane/state/issue-agent.json` 로드하여 `spec` 추출
+2. `spec.checklist` 항목을 순서대로 구현
+3. Figma 스펙이 있으면 (`spec.figmaSpec.enabled === true`):
+   - `colorTokens`를 CSS 변수 또는 Tailwind config 값으로 변환
+   - 컴포넌트 구조를 Figma 계층에 맞게 구현
+4. 기존 코드베이스 패턴 파악 후 동일 스타일로 작성 (TypeScript, 테스트 파일 위치 등)
+5. 각 파일 구현 후 `appendLog` 호출:
+   ```bash
+   node -e "import('./src/state.js').then(({appendLog})=>appendLog('code-agent','FILENAME 구현 완료'))"
+   ```
+6. 구현 완료 후 상태 업데이트:
+   ```bash
+   node -e "
+   import('./src/state.js').then(({writeState}) => {
+     writeState('code-agent', {
+       status: 'completed',
+       progress: 100,
+       currentTask: '구현 완료',
+       retries: 0,
+       changedFiles: CHANGED_FILES_ARRAY
+     })
+   })
+   "
+   ```
+
+## 코딩 원칙
+
+- 함수형 컴포넌트 + hooks 우선
+- 파일당 단일 책임
+- 200줄 초과 시 분리 고려
+- 불변성 패턴 유지 (객체 직접 수정 금지)
+
+## 출력
+
+`.bylane/state/code-agent.json`의 `changedFiles`: 변경된 파일 경로 배열
+
+## 수동 실행
+
+`/bylane code #123`

package/skills/commit-agent.md

@@ -0,0 +1,85 @@
+---
+name: bylane-commit-agent
+description: 변경된 파일들을 conventional commit 형식으로 커밋한다.
+---
+
+# Commit Agent
+
+## 입력
+
+- `.bylane/state/code-agent.json`의 `changedFiles`
+- `.bylane/state/issue-agent.json`의 `spec.title`, `issueNumber`
+- `.bylane/bylane.json`의 `branch` 설정
+
+## 실행 전 상태 기록
+
+```bash
+node -e "import('./src/state.js').then(({writeState})=>writeState('commit-agent',{status:'in_progress',startedAt:new Date().toISOString(),progress:0,retries:0,log:[]}))"
+```
+
+## 실행 흐름
+
+1. 브랜치명 생성:
+   ```bash
+   node -e "
+   Promise.all([
+     import('./src/branch.js'),
+     import('./src/config.js')
+   ]).then(([{buildBranchNameFromConfig},{loadConfig}]) => {
+     const config = loadConfig()
+     const branch = buildBranchNameFromConfig(config, ISSUE_NUMBER)
+     console.log(branch)
+   })
+   "
+   ```
+
+2. 브랜치 생성 및 체크아웃:
+   ```bash
+   git checkout -b BRANCH_NAME
+   ```
+
+3. 변경 파일 스테이징:
+   ```bash
+   git add CHANGED_FILES
+   ```
+
+4. 커밋 타입 결정:
+   - 새 기능: `feat:`
+   - 버그 수정: `fix:`
+   - 리팩토링: `refactor:`
+
+5. 커밋 실행:
+   ```bash
+   git commit -m "feat: SPEC_TITLE
+
+   Closes #ISSUE_NUMBER"
+   ```
+
+6. 상태 업데이트:
+   ```bash
+   node -e "
+   import('./src/state.js').then(({writeState})=>writeState('commit-agent',{
+     status:'completed',
+     progress:100,
+     branchName:'BRANCH_NAME',
+     commitSha:'COMMIT_SHA'
+   }))
+   "
+   ```
+
+## 출력
+
+`.bylane/state/commit-agent.json`:
+```json
+{
+  "agent": "commit-agent",
+  "status": "completed",
+  "progress": 100,
+  "branchName": "issues-123-add-dark-mode",
+  "commitSha": "abc1234"
+}
+```
+
+## 수동 실행
+
+`/bylane commit`

package/skills/issue-agent.md

@@ -0,0 +1,91 @@
+---
+name: bylane-issue-agent
+description: GitHub Issue 생성 및 분석. Figma 링크 감지 시 스펙 추출.
+---
+
+# Issue Agent
+
+## 입력
+
+- 자유 텍스트 (새 이슈 생성용) OR GitHub Issue 번호 (#N)
+
+## 실행 흐름
+
+### 새 이슈 생성 모드 (텍스트 입력)
+
+1. 입력 텍스트에서 다음을 추출:
+   - 제목 (50자 이내)
+   - 상세 설명
+   - 구현 체크리스트 (예상 가능한 경우)
+   - Figma URL (있는 경우)
+
+2. GitHub MCP로 이슈 생성:
+   - `title`: 추출된 제목
+   - `body`: Markdown 형식 설명 + 체크리스트
+   - `labels`: `bylane-auto` 라벨 추가 (라벨이 없으면 생성)
+
+3. Figma MCP 활성화 여부 확인 (`.bylane/bylane.json` → `extensions.figma.enabled`):
+   - `true`이고 Figma URL이 있으면 → **Figma 분석** 단계 실행
+   - `false`이면 → 텍스트 기반 스펙만 생성
+
+### 기존 이슈 분석 모드 (Issue 번호 입력)
+
+1. GitHub MCP로 이슈 내용 로드
+2. 본문에서 Figma URL 추출 시도
+3. 스펙 생성 (아래 참조)
+
+### Figma 분석 (활성화된 경우)
+
+Figma MCP `get_file` 또는 `get_node` 도구로 해당 프레임/컴포넌트 분석:
+- 컴포넌트 계층 구조
+- 색상 토큰
+- 타이포그래피
+- 스페이싱 값
+
+추출 결과를 스펙에 포함.
+
+**Figma 분석 실패 시 fallback:**
+- MCP 미설치 또는 URL 유효하지 않은 경우: 경고 로그 기록 후 텍스트 기반 스펙만 사용
+- `figmaSpec.enabled = false`로 출력
+
+## 출력: 구현 스펙
+
+`.bylane/state/issue-agent.json`에 저장:
+
+```json
+{
+  "agent": "issue-agent",
+  "status": "completed",
+  "progress": 100,
+  "issueNumber": 123,
+  "issueUrl": "https://github.com/...",
+  "spec": {
+    "title": "다크모드 토글 버튼 추가",
+    "description": "...",
+    "checklist": ["ThemeToggle 컴포넌트 생성", "useTheme hook 구현"],
+    "figmaSpec": {
+      "enabled": false,
+      "components": [],
+      "colorTokens": {}
+    }
+  }
+}
+```
+
+상태 기록:
+```bash
+node -e "
+import('./src/state.js').then(({writeState, appendLog}) => {
+  writeState('issue-agent', {
+    status: 'in_progress',
+    startedAt: new Date().toISOString(),
+    progress: 0,
+    retries: 0
+  })
+})
+"
+```
+
+## 수동 실행
+
+`/bylane issue #123` 또는 `/bylane issue 다크모드 토글 추가해줘`