@elyun/bylane 1.17.0 → 1.18.0

package/README.md

@@ -1,32 +1,36 @@
 # byLane
 
-> Claude Code용 프론트엔드 개발 자동화 하네스
+> Claude Code용 개발 자동화 하네스
 
 GitHub Issues에서 시작해 코드 구현, 테스트, 커밋, PR 생성, 리뷰, 리뷰 반영까지 전체 개발 워크플로우를 에이전트 기반으로 자동화합니다.
 
-## 특징
-
-- **프로젝트 분석** — 코드 스타일·디자인 토큰·아키텍처를 자동 분석해 `.claude/instructions/`에 저장, CLAUDE.md에 자동 import
-- **전체 워크플로우 자동화** — `/bylane 다크모드 토글 추가해줘` 한 줄로 이슈 생성부터 PR까지
-- **개별 실행 가능** — 각 에이전트를 단독으로 실행 가능
-- **실시간 모니터링** — 2열 그리드 터미널 TUI 대시보드
-- **자동 리뷰 루프** — 5분 주기로 review 요청 PR 자동 리뷰
-- **자동 대응 루프** — 5분 주기로 내 PR 리뷰/코멘트 자동 대응 (accept/rebut)
-- **피드백 루프** — 테스트 실패 시 자동 재시도 (설정 가능)
-- **GitHub 접근 방법** — MCP / CLI(`gh`) / REST API 자동 감지
-- **리뷰 템플릿** — 코드 예시, 모델 명시, 커스텀 푸터 설정 가능
-- **에이전트별 모델 설정** — 에이전트마다 다른 AI 모델 지정 가능
-- **Figma MCP 연동** — 이슈의 Figma 링크에서 스펙 자동 추출 (선택적)
-- **Slack / Telegram 알림** — 완료 또는 개입 필요 시 알림
-- **pre-commit 보안 훅** — 시크릿/민감 파일/console.log 자동 검사
+---
+
+## 핵심 기능
+
+| 기능 | 설명 |
+|------|------|
+| **전체 워크플로우** | 자연어 한 줄로 이슈 → 코드 → 테스트 → 커밋 → PR 자동화 |
+| **프로젝트 분석** | 코드 스타일·디자인 토큰·아키텍처 자동 분석, `.claude/instructions/` 생성 |
+| **인라인 코드 리뷰** | 변경 라인마다 개별 코멘트 + GitHub suggestion 블록 자동 등록 |
+| **자동 리뷰 루프** | 5분 주기로 review 요청된 PR을 자동 감지 → 리뷰 실행 |
+| **자동 대응 루프** | 5분 주기로 내 PR 리뷰/코멘트 감지 → 자동 수정 반영 또는 반박 |
+| **실시간 모니터** | 터미널 TUI 대시보드 (에이전트 상태, 로그, 큐, 루프 모니터링) |
+| **에이전트별 모델** | 에이전트마다 다른 Claude 모델 지정 가능 |
+| **GitHub 자동 감지** | MCP → CLI(`gh`) → REST API 순서로 자동 시도 |
+| **보안 훅** | 커밋마다 시크릿/민감 파일/console.log 자동 검사 |
+
+---
 
 ## 요구사항
 
 - [Claude Code](https://claude.ai/code) CLI
 - Node.js 20+
-- GitHub MCP (Claude Code 기본 제공), `gh` CLI, 또는 `GITHUB_TOKEN` 중 하나
-- Slack MCP / Telegram (알림 사용 시)
-- Figma MCP (디자인 연동 사용 시)
+- GitHub MCP (Claude Code 기본 제공) / `gh` CLI / `GITHUB_TOKEN` 중 하나
+- Slack MCP 또는 Telegram (알림 사용 시, 선택사항)
+- Figma MCP (디자인 연동 사용 시, 선택사항)
+
+---
 
 ## 설치
 
@@ -36,10 +40,11 @@ GitHub Issues에서 시작해 코드 구현, 테스트, 커밋, PR 생성, 리
 npx @elyun/bylane
 ```
 
-Skills, Commands, Hooks 파일을 `~/.claude/` 하위 디렉토리에 자동으로 복사합니다.
-기존 파일이 있으면 `.bak`으로 백업 후 교체합니다.
+`~/.claude/commands/`와 `~/.claude/hooks/`에 파일을 자동 복사합니다.
+기존 파일은 `.bak`으로 백업 후 교체됩니다.
+`.bylane/bylane.json` 사용자 설정은 **절대 덮어쓰지 않습니다**.
 
-심볼릭 링크로 설치하면 레포 업데이트 시 자동으로 반영됩니다:
+심볼릭 링크 설치 (레포 업데이트 시 자동 반영):
 
 ```bash
 npx @elyun/bylane --symlink
@@ -50,34 +55,26 @@ npx @elyun/bylane --symlink
 ```bash
 git clone https://github.com/el-yun/byLane.git
 cd byLane
-npm install   # pre-commit 보안 훅 자동 등록
+npm install
 node src/cli.js install
 ```
 
-### 셋업 위자드 실행
+### 셋업 위자드
 
-Claude Code를 열고 프로젝트 디렉토리에서:
+설치 후 Claude Code에서 프로젝트 디렉토리로 이동:
 
 ```
 /bylane setup
 ```
 
-7단계 인터랙티브 설정:
-1. GitHub 접근 방법 (MCP / CLI / API / auto)
-2. 이슈 트래커 (GitHub Issues / Linear / 둘 다)
-3. 알림 채널 (Slack / Telegram / 둘 다)
-4. 팀 모드 설정
-5. 권한 범위 (read-only / write / full)
-6. 고급 설정 (재시도 횟수, 타임아웃, Figma MCP)
-7. 브랜치 네이밍 패턴
-8. 에이전트별 AI 모델
+인터랙티브 설정 (GitHub 접근 방법, 알림 채널, 브랜치 패턴, 에이전트 모델 등).
+
+---
 
 ## 사용법
 
 ### 전체 워크플로우
 
-자연어로 작업 내용을 설명하면 오케스트레이터가 적절한 에이전트를 자동으로 실행합니다.
-
 ```
 /bylane 다크모드 토글 버튼 추가해줘
 /bylane issue #123 구현해줘
@@ -94,84 +91,193 @@ Claude Code를 열고 프로젝트 디렉토리에서:
 /bylane test                     테스트 실행
 /bylane commit                   커밋 생성
 /bylane pr                       PR 생성
-/bylane review [PR번호]          PR 리뷰
-/bylane review-loop              5분 주기 자동 리뷰 루프
-/bylane respond [PR번호]         리뷰 반박/반영
-/bylane respond-loop             5분 주기 자동 대응 루프
+/bylane review [#PR번호] [scope] PR 인라인 리뷰
+/bylane respond [#PR번호] [모드] 리뷰 반박/반영
 /bylane notify                   알림 발송
 /bylane status                   현재 상태 요약
 ```
 
 ### 자동 루프
 
-두 루프를 동시에 실행하면 review 요청과 리뷰 대응을 모두 자동화합니다:
+두 루프를 동시에 실행하면 리뷰 요청과 리뷰 대응을 완전 자동화합니다:
 
 ```bash
-node src/review-loop.js &   # 내게 요청된 PR 자동 리뷰
-node src/respond-loop.js &  # 내 PR 리뷰 자동 대응
+node src/review-loop.js &   # 내게 요청된 PR 자동 리뷰 (5분 주기)
+node src/respond-loop.js &  # 내 PR 리뷰 자동 대응 (5분 주기)
 ```
 
-### 모니터 대시보드
+루프 종료:
 
 ```bash
-npm run monitor
-# 또는
-/bylane monitor
+kill $(pgrep -f review-loop.js)
+kill $(pgrep -f respond-loop.js)
+# 또는 모니터에서 [s]
 ```
 
+Claude Code에서 실행:
+
 ```
-+---------------------------+--------------------------------------+
-|  AGENT PIPELINE           |  AGENT LOG                 [LIVE]  |
-|                           |                                     |
-|  issue-agent  [v] 완료   |  17:32:38 code-agent               |
-|  code-agent   [>] 67%    |    > ThemeToggle.tsx 생성           |
-|  test-agent   [ ] 대기   |  17:30:09 issue-agent              |
-|  ...                      |    > spec.json 저장됨               |
-+---------------------------+--------------------------------------+
-|  QUEUE                    |  SYSTEM STATUS                      |
-|  1  Issue #124  대기중    |  GitHub    OK 연결됨                |
-|  2  PR #45  review        |  Slack     OK #dev-alerts           |
-+---------------------------+--------------------------------------+
+/bylane review-loop     자동 리뷰 루프 시작 (검사 범위 선택 후 시작)
+/bylane respond-loop    자동 대응 루프 시작
 ```
 
-## 프로젝트 분석 (analyze)
+---
 
-`/bylane analyze`를 실행하면 현재 프로젝트를 자동 분석하여 Claude Code가 참조할 수 있는 instruction 파일을 생성합니다.
+## 모니터 대시보드
 
-### 생성되는 파일
+```bash
+npx @elyun/bylane monitor
+```
 
-| 파일 | 내용 |
-|---|---|
-| `.claude/instructions/code-style.md` | 언어, 포맷팅, 네이밍 컨벤션, import 규칙, 금지 패턴 |
-| `.claude/instructions/design-tokens.md` | 색상 팔레트, 타이포그래피, 간격, 브레이크포인트, 다크모드 |
-| `.claude/instructions/architecture.md` | 프레임워크, 렌더링 전략, 상태관리, 데이터 페칭, 폴더 구조 |
+> `npx`를 사용하면 항상 최신 버전이 실행됩니다. 로컬 구버전이 실행되지 않습니다.
+
+```
++-----------------------------+--------------------------------------+
+|  AGENT PIPELINE             |  AGENT LOG                  [LIVE]  |
+|                             |                                      |
+|  [>] code-agent   12s  ##-- |  17:32:38 code-agent                |
+|  [ ] test-agent   대기      |    > ThemeToggle.tsx 생성            |
+|  [v] issue-agent            |  17:30:09 issue-agent               |
+|                             |    > spec.json 저장됨                |
+|  LOOPS                      |                                      |
+|  [>] review-loop  45s       |                                      |
+|  [-] respond-loop 미실행    |                                      |
+|                             |                                      |
+|  SUBAGENTS                  |                                      |
+|  [>] executor  8s  코드...  |                                      |
++-----------------------------+--------------------------------------+
+|  QUEUE                      |  SYSTEM STATUS                       |
+|  PR #45  review pending     |  GitHub    OK                        |
+|  PR #48  respond pending    |  Loops     1 running                 |
++-----------------------------+--------------------------------------+
+ [q]종료  [c]에이전트취소토글  [s]루프종료  [Tab]포커스  [j/k]로그스크롤
+```
+
+### 단축키
+
+| 키 | 동작 |
+|----|------|
+| `q` / `Ctrl+C` | 모니터 종료 |
+| `r` | 상태 정리 (권한 수정, 좀비 초기화, 큐 복구) |
+| `c` | 하위 에이전트 취소 플래그 토글 (새 Agent 호출 차단) |
+| `s` | 실행 중인 루프 선택 → SIGTERM 전송 |
+| `Tab` | 패널 포커스 이동 |
+| `j` / `k` | 로그 스크롤 |
+
+---
+
+## 코드 리뷰
+
+### 검사 범위 선택
+
+리뷰 실행 시 검사 항목을 선택합니다. 선택 없이 Enter → 전체 검사:
 
-### 동작 방식
+```
+검사 항목을 선택하세요 (쉼표 구분, Enter=전체):
+  1. grammar  — 문법, 오탈자, 주석/변수명 언어 일관성
+  2. domain   — 비즈니스 로직, 도메인 규칙 준수 여부
+  3. code     — 코드 스타일, 컨벤션, 중복, 복잡도
+  4. security — 보안 취약점, 시크릿 노출, 인증/인가 이슈
+```
+
+인자로도 지정 가능:
+```
+/bylane review #45 code,security
+```
+
+### 인라인 코멘트
+
+모든 리뷰 코멘트는 **해당 코드 라인에 직접** 등록됩니다. 수정 제안이 있으면 GitHub suggestion 블록으로 작성되어 "Apply suggestion" 버튼으로 바로 적용할 수 있습니다.
+
+```
+제목
+
+설명
 
-1. ESLint/Prettier/tsconfig, Tailwind config, CSS 변수, package.json 등 설정 파일을 자동 탐색
-2. 소스 파일을 샘플링하여 실제 사용 패턴 파악
-3. 분석 결과를 `.claude/instructions/`에 Markdown 파일로 저장
-4. `CLAUDE.md`에 `@.claude/instructions/*.md` import 구문 자동 추가
-   - `CLAUDE.md`가 없으면 `/init`으로 먼저 생성
+```suggestion
+// 수정 제안 코드
+```
+```
+
+### GitHub 리뷰 템플릿 우선 적용
+
+프로젝트에 아래 파일이 있으면 해당 형식을 **최우선**으로 따릅니다:
 
 ```
-/bylane analyze          # 분석 후 파일 생성 (기존 파일 확인 요청)
-/bylane analyze --force  # 기존 instruction 파일 강제 덮어쓰기
+.github/REVIEW_TEMPLATE.md
+.github/CODE_REVIEW_TEMPLATE.md
+docs/REVIEW_TEMPLATE.md
 ```
 
-커스텀 내용은 `.claude/instructions/structure.md`를 직접 작성하고 CLAUDE.md에 `@.claude/instructions/structure.md`를 추가하면 재분석 시에도 유지됩니다.
+없으면 `templates/review-template.md`를 사용합니다.
+
+---
 
-## 브랜치 네이밍 패턴
+## 리뷰 대응 (respond)
 
-| 패턴 | 예시 |
-|---|---|
-| `{tracker}-{issue-number}` | `issues-32` |
-| `{tracker}-{issue-number}-{custom-id}` | `issues-32-C-12` |
-| `{type}/{issue-number}-{title-slug}` | `feature/32-add-dark-mode` |
+| 모드 | 동작 |
+|------|------|
+| `auto` (기본) | 각 코멘트를 분석해 수정 반영 또는 반박을 자동 판단, 요약 확인 후 실행 |
+| `accept` | 모든 코멘트 수정 반영 |
+| `rebut` | 모든 코멘트 반박 |
+| `manual` | 코멘트별로 수정/반박/건너뜀 직접 선택 |
 
-사용 가능한 토큰: `{tracker}`, `{type}`, `{issue-number}`, `{custom-id}`, `{title-slug}`, `{date}`, `{username}`
+```
+/bylane respond #45           auto 모드 (기본)
+/bylane respond #45 manual    코멘트별 수동 선택
+/bylane respond #45 accept    전체 반영
+```
+
+auto 모드에서는 실행 전 요약을 먼저 보여주고 확인을 받습니다:
 
-빈 토큰은 자동으로 제외됩니다 (`{custom-id}` 없으면 `issues-32`).
+```
+코멘트 #1: [반영] null 체크 누락 → 코드 수정
+코멘트 #2: [반박] 의도된 설계 (이슈 #12 참조)
+진행할까요? (y/n)
+```
+
+---
+
+## 프로젝트 분석
+
+`/bylane analyze` 실행 시 현재 프로젝트를 자동 분석하여 Claude Code가 참조할 instruction 파일을 생성합니다.
+
+| 파일 | 내용 |
+|------|------|
+| `.claude/instructions/code-style.md` | 언어, 포맷팅, 네이밍 컨벤션, import 규칙 |
+| `.claude/instructions/design-tokens.md` | 색상, 타이포그래피, 간격, 다크모드 |
+| `.claude/instructions/architecture.md` | 프레임워크, 상태관리, 폴더 구조 |
+
+ESLint/Prettier/tsconfig, Tailwind config, CSS 변수 등 설정 파일을 자동 탐색하고 실제 소스 패턴을 샘플링합니다. 분석 후 `CLAUDE.md`에 import 구문을 자동 추가합니다.
+
+```
+/bylane analyze          기존 파일 있으면 확인 요청
+/bylane analyze --force  강제 덮어쓰기
+```
+
+---
+
+## 에이전트 파이프라인
+
+```
+orchestrator
+  → issue-agent    이슈 생성/분석, Figma 스펙 추출 (선택)
+  → code-agent     코드 구현
+  → test-agent     테스트 실행, 실패 시 code-agent 재시도
+  → commit-agent   브랜치 생성 + 커밋
+  → pr-agent       PR 생성
+  → review-agent   인라인 코드 리뷰
+  → respond-agent  리뷰 반박 또는 반영
+  → notify-agent   Slack/Telegram 알림
+
+analyze-agent   독립: 프로젝트 분석 → .claude/instructions/ 생성
+review-loop     독립: 5분 주기 review 요청 감지
+respond-loop    독립: 5분 주기 리뷰 코멘트 감지
+```
+
+각 에이전트는 `.bylane/state/{name}.json`에 상태를 기록합니다. 모니터가 1초마다 폴링합니다.
+
+---
 
 ## 설정 파일 (`.bylane/bylane.json`)
 
@@ -208,6 +314,7 @@ npm run monitor
     "code-agent": "claude-sonnet-4-6",
     "review-agent": "claude-sonnet-4-6",
     "respond-agent": "claude-opus-4-6",
+    "analyze-agent": "claude-opus-4-6",
     "test-agent": "claude-haiku-4-5-20251001",
     "commit-agent": "claude-haiku-4-5-20251001",
     "pr-agent": "claude-haiku-4-5-20251001",
@@ -216,10 +323,9 @@ npm run monitor
   "review": {
     "model": "claude-sonnet-4-6",
     "language": "ko",
-    "includeModel": true,
     "includeCodeExample": true,
     "templateFile": "",
-    "footer": "Reviewed by byLane · model: {model}"
+    "footer": "{model} · {date}"
   },
   "extensions": {
     "figma": { "enabled": false, "useAt": "issue-analysis" }
@@ -227,64 +333,99 @@ npm run monitor
 }
 ```
 
-## 에이전트 파이프라인
+### 브랜치 네이밍 토큰
+
+| 토큰 | 설명 |
+|------|------|
+| `{tracker}` | 트래커 종류 (예: `issues`) |
+| `{type}` | 작업 타입 (예: `feature`, `fix`) |
+| `{issue-number}` | 이슈 번호 |
+| `{custom-id}` | 커스텀 ID |
+| `{title-slug}` | 이슈 제목 슬러그 |
+| `{date}` | 날짜 (YYYYMMDD) |
+| `{username}` | GitHub 사용자명 |
 
+값이 없는 토큰은 자동으로 제외됩니다 (`{custom-id}` 없으면 `issues-32-add-dark-mode`).
+
+---
+
+## 주의사항
+
+### 업데이트 시 설정 보존
+
+```bash
+npx @elyun/bylane   # 재설치/업데이트
 ```
-orchestrator
-  → issue-agent    (이슈 생성/분석, Figma 스펙 추출)
-  → code-agent     (코드 구현)
-  → test-agent     (테스트 실행, 실패 시 code-agent 재시도)
-  → commit-agent   (브랜치 생성 + 커밋)
-  → pr-agent       (PR 생성)
-  → review-agent   (자동 리뷰)
-  → respond-agent  (리뷰 반박 또는 반영)
-  → notify-agent   (Slack/Telegram 알림)
 
-review-loop   (독립 실행: 5분 주기 리뷰 요청 감지)
-respond-loop  (독립 실행: 5분 주기 리뷰 코멘트 감지)
+`.bylane/bylane.json` 사용자 설정은 절대 덮어쓰지 않습니다. 나머지 파일은 `.bak`으로 백업 후 교체됩니다.
+
+### 모니터 버전 불일치
+
+프로젝트의 `node_modules`에 구버전이 설치된 경우 `npm run monitor`를 사용하면 구버전이 실행됩니다.
+항상 `npx @elyun/bylane monitor`를 사용하세요.
+
+### 루프 중복 실행
+
+review-loop / respond-loop는 PID를 상태 파일에 기록합니다. 모니터의 `[s]` 키 또는 `pgrep`으로 확인 후 종료하세요.
+
+### GitHub MCP vs CLI
+
+Claude Code 세션 내에서는 MCP가 자동 사용됩니다. 루프 폴러(`review-loop.js`, `respond-loop.js`)는 Claude 세션 외부에서 실행되므로 `gh` CLI 또는 `GITHUB_TOKEN`이 필요합니다.
+
+### 상태 정리 (cleanup)
+
+에이전트 크래시, 루프 강제 종료, 권한 문제 등으로 상태가 꼬인 경우 정리 명령을 실행합니다:
+
+```bash
+npx @elyun/bylane cleanup
 ```
 
-## GitHub 접근 방법
+또는 모니터에서 **`[r]`** 키를 누르면 즉시 실행됩니다.
 
-`github.method` 설정으로 제어:
+| 정리 항목 | 동작 |
+|-----------|------|
+| `.bylane/state/` 권한 | 디렉토리 755, 파일 644로 수정 |
+| 죽은 루프 프로세스 | PID 확인 → 없으면 `stopped`로 전환 |
+| 30분 초과 `in_progress` | `failed`로 초기화 |
+| `subagents.json` active | PID 없는 항목 제거 |
+| 큐의 `reviewing`/`responding` | `pending`으로 복구 (재처리 대기) |
 
-| 값 | 동작 |
-|----|------|
-| `"auto"` (기본) | MCP → CLI → API 순서로 자동 시도 |
-| `"mcp"` | GitHub MCP 도구만 사용 |
-| `"cli"` | `gh` CLI만 사용 |
-| `"api"` | REST API + `$GITHUB_TOKEN`만 사용 |
+정리 후 상태 파일이 갱신되면 chokidar가 감지하여 모니터에 즉시 반영됩니다.
 
-## 리뷰 템플릿
+### 하위 에이전트 제어
 
-`templates/review-template.md`를 복사해 커스터마이즈한 뒤 `review.templateFile`에 경로를 지정합니다.
+모니터에서 `[c]`를 누르면 `.bylane/state/cancel.json`이 생성되어 새 하위 에이전트 호출이 차단됩니다. 다시 `[c]`를 누르면 해제됩니다.
 
-기본 구성: 심각도 레이블 (CRITICAL/HIGH/MEDIUM/LOW), Before/After 코드 예시, 사용 모델 명시, 커스텀 푸터.
+---
 
 ## 보안
 
-`npm install` 시 pre-commit 훅이 자동 등록됩니다. 커밋마다 아래를 검사합니다:
+`npm install` 시 pre-commit 훅이 자동 등록됩니다.
 
-| 항목 | 심각도 |
-|------|--------|
-| AWS/OpenAI/GitHub/Slack/Google 키 패턴 | CRITICAL (차단) |
-| `.env`, `.pem`, `credentials` 등 민감 파일 | CRITICAL (차단) |
-| 하드코딩된 password/api_key | CRITICAL (차단) |
-| `node_modules` 실수 커밋 | CRITICAL (차단) |
-| `console.log` | WARN (경고만) |
+| 검사 항목 | 처리 |
+|-----------|------|
+| AWS/OpenAI/GitHub/Slack/Google 키 패턴 | 커밋 차단 |
+| `.env`, `.pem`, `credentials` 등 민감 파일 | 커밋 차단 |
+| 하드코딩된 password/api_key | 커밋 차단 |
+| `node_modules` 실수 커밋 | 커밋 차단 |
+| `console.log` | 경고 (차단 안 함) |
 
-우회: `git commit --no-verify`
+우회: `git commit --no-verify` (권장하지 않음)
+
+---
 
 ## 개발
 
 ```bash
 npm install          # 의존성 설치 + pre-commit 훅 등록
 npm test             # 테스트 실행 (19개)
-npm run monitor      # 모니터 대시보드
-npm version minor    # 버전 올리기
-npm run release      # npm 배포 (커밋/푸시 후 실행)
+npm run monitor      # 모니터 대시보드 (소스에서 직접 실행)
+npm version minor    # 버전 올리기 (커밋 + 태그 자동 생성)
+npm run release      # npm 배포 (커밋/푸시 완료 후 실행)
 ```
 
+---
+
 ## 라이선스
 
 MIT

package/commands/bylane-cleanup.md

@@ -0,0 +1,36 @@
+---
+name: bylane-cleanup
+description: 상태 파일 권한 수정, 좀비 에이전트/루프 초기화, 큐 복구를 한 번에 실행한다.
+---
+
+# /bylane cleanup
+
+## 중요
+
+cleanup은 **터미널 명령**으로 실행하세요. Claude가 직접 실행하지 않고 명령을 안내합니다.
+
+---
+
+아래 명령을 실행하면 상태 정리가 완료됩니다:
+
+```bash
+npx @elyun/bylane cleanup
+```
+
+또는 모니터가 실행 중이라면 **`[r]` 키**를 누르면 즉시 실행됩니다.
+
+---
+
+## 정리 항목
+
+| 항목 | 동작 |
+|------|------|
+| `.bylane/state/` 권한 | 디렉토리 755, 파일 644로 수정 |
+| 죽은 루프 프로세스 | PID 확인 → 없으면 `stopped`로 전환 |
+| 30분 초과 `in_progress` | `failed`로 초기화 |
+| `subagents.json` active | PID 없는 항목 제거 |
+| 큐의 `reviewing`/`responding` | `pending`으로 복구 (재처리 대기) |
+
+## 완료
+
+안내 후 이 스킬을 즉시 종료합니다.

package/commands/bylane-code-agent.md

@@ -12,18 +12,7 @@ description: issue-agent의 스펙을 기반으로 프론트엔드 코드를 구
 ## 실행 전 상태 기록
 
 ```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: []
-  })
-})
-"
+npx @elyun/bylane state write code-agent '{"status":"in_progress","startedAt":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","progress":0,"currentTask":"코드 구현 시작","retries":0,"log":[]}'
 ```
 
 ## 실행 흐름
@@ -36,21 +25,11 @@ import('./src/state.js').then(({writeState}) => {
 4. 기존 코드베이스 패턴 파악 후 동일 스타일로 작성 (TypeScript, 테스트 파일 위치 등)
 5. 각 파일 구현 후 `appendLog` 호출:
    ```bash
-   node -e "import('./src/state.js').then(({appendLog})=>appendLog('code-agent','FILENAME 구현 완료'))"
+   npx @elyun/bylane state append 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
-     })
-   })
-   "
+   npx @elyun/bylane state write code-agent '{"status":"completed","progress":100,"currentTask":"구현 완료","retries":0,"changedFiles":CHANGED_FILES_ARRAY}'
    ```
 
 ## 코딩 원칙

package/commands/bylane-commit-agent.md

@@ -14,7 +14,7 @@ description: 변경된 파일들을 conventional commit 형식으로 커밋한
 ## 실행 전 상태 기록
 
 ```bash
-node -e "import('./src/state.js').then(({writeState})=>writeState('commit-agent',{status:'in_progress',startedAt:new Date().toISOString(),progress:0,retries:0,log:[]}))"
+npx @elyun/bylane state write commit-agent '{"status":"in_progress","startedAt":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","progress":0,"retries":0,"log":[]}'
 ```
 
 ## GitHub 커밋 템플릿 탐지
@@ -36,16 +36,7 @@ ls .gitmessage .github/commit-template.txt .github/COMMIT_TEMPLATE.md 2>/dev/nul
 
 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)
-   })
-   "
+   npx @elyun/bylane branch ISSUE_NUMBER
    ```
 
 2. 브랜치 생성 및 체크아웃:
@@ -72,14 +63,7 @@ ls .gitmessage .github/commit-template.txt .github/COMMIT_TEMPLATE.md 2>/dev/nul
 
 6. 상태 업데이트:
    ```bash
-   node -e "
-   import('./src/state.js').then(({writeState})=>writeState('commit-agent',{
-     status:'completed',
-     progress:100,
-     branchName:'BRANCH_NAME',
-     commitSha:'COMMIT_SHA'
-   }))
-   "
+   npx @elyun/bylane state write commit-agent '{"status":"completed","progress":100,"branchName":"BRANCH_NAME","commitSha":"COMMIT_SHA"}'
    ```
 
 ## 출력

package/commands/bylane-issue-agent.md

@@ -102,7 +102,7 @@ Figma MCP `get_file` 또는 `get_node` 도구로 프레임/컴포넌트 분석.
 
 상태 기록:
 ```bash
-node -e "import('./src/state.js').then(({writeState})=>writeState('issue-agent',{status:'in_progress',startedAt:new Date().toISOString(),progress:0,retries:0}))"
+npx @elyun/bylane state write issue-agent '{"status":"in_progress","startedAt":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","progress":0,"retries":0}'
 ```
 
 ## 수동 실행

package/commands/bylane-notify-agent.md

@@ -14,7 +14,7 @@ description: 워크플로우 완료 또는 개입 필요 시 Slack/Telegram으
 ## 실행 전 상태 기록
 
 ```bash
-node -e "import('./src/state.js').then(({writeState})=>writeState('notify-agent',{status:'in_progress',startedAt:new Date().toISOString(),progress:0,retries:0,log:[]}))"
+npx @elyun/bylane state write notify-agent '{"status":"in_progress","startedAt":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","progress":0,"retries":0,"log":[]}'
 ```
 
 ## 실행 흐름

package/commands/bylane-orchestrator.md

@@ -19,19 +19,11 @@ description: byLane 메인 오케스트레이터. 자연어 의도를 파싱해
 각 에이전트 실행 전 사용할 모델을 config에서 읽는다:
 
 ```bash
-node -e "
-import('./src/config.js').then(({loadConfig, getAgentModel}) => {
-  const config = loadConfig()
-  const agents = [
-    'orchestrator','issue-agent','code-agent','test-agent',
-    'commit-agent','pr-agent','review-agent','respond-agent','notify-agent'
-  ]
-  agents.forEach(a => console.log(a + ': ' + getAgentModel(config, a)))
-  // analyze-agent는 항상 opus 사용 (config 무관)
-})
-"
+npx @elyun/bylane models
 ```
 
+출력 형식: `AGENT_NAME=MODEL_ID` (한 줄씩)
+
 에이전트 호출 시 해당 모델을 `model` 파라미터로 전달한다.
 
 ## 의도 파싱 규칙
@@ -57,18 +49,7 @@ import('./src/config.js').then(({loadConfig, getAgentModel}) => {
 
 상태 기록 (각 에이전트 시작 전):
 ```bash
-node -e "
-import('./src/state.js').then(({writeState}) => {
-  writeState('AGENT_NAME', {
-    status: 'in_progress',
-    startedAt: new Date().toISOString(),
-    progress: 0,
-    currentTask: 'TASK_DESCRIPTION',
-    retries: 0,
-    log: []
-  })
-})
-"
+npx @elyun/bylane state write AGENT_NAME '{"status":"in_progress","startedAt":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","progress":0,"currentTask":"TASK_DESCRIPTION","retries":0,"log":[]}'
 ```
 
 ## 피드백 루프

package/commands/bylane-pr-agent.md

@@ -43,7 +43,7 @@ ls .github/PULL_REQUEST_TEMPLATE/*.md 2>/dev/null | head -5
 ## 실행 전 상태 기록
 
 ```bash
-node -e "import('./src/state.js').then(({writeState})=>writeState('pr-agent',{status:'in_progress',startedAt:new Date().toISOString(),progress:0,retries:0,log:[]}))"
+npx @elyun/bylane state write pr-agent '{"status":"in_progress","startedAt":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","progress":0,"retries":0,"log":[]}'
 ```
 
 ## 실행 흐름
@@ -90,7 +90,7 @@ node -e "import('./src/state.js').then(({writeState})=>writeState('pr-agent',{st
 
 4. 상태 업데이트:
    ```bash
-   node -e "import('./src/state.js').then(({writeState})=>writeState('pr-agent',{status:'completed',progress:100,prNumber:PR_NUMBER,prUrl:'PR_URL'}))"
+   npx @elyun/bylane state write pr-agent '{"status":"completed","progress":100,"prNumber":PR_NUMBER,"prUrl":"PR_URL"}'
    ```
 
 ## 출력

package/commands/bylane-respond-agent.md

@@ -64,7 +64,7 @@ ls .github/REVIEW_RESPONSE_TEMPLATE.md \
 ## 실행 전 상태 기록
 
 ```bash
-node -e "import('./src/state.js').then(({writeState})=>writeState('respond-agent',{status:'in_progress',startedAt:new Date().toISOString(),progress:0,retries:0,log:[]}))"
+npx @elyun/bylane state write respond-agent '{"status":"in_progress","startedAt":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","progress":0,"retries":0,"log":[]}'
 ```
 
 ## 실행 흐름

package/commands/bylane-respond-loop.md

@@ -30,15 +30,12 @@ echo "폴러 PID: $!"
 pending PR이 생길 때마다 respond-agent를 실행한다:
 
 ```bash
-node -e "
-import('./src/state.js').then(({readState}) => {
-  const q = readState('respond-queue', '.bylane/state')
-  const pending = (q?.queue ?? []).filter(p => p.status === 'pending')
-  console.log(JSON.stringify(pending))
-})
-"
+# 큐 확인 (pending 항목 필터링)
+npx @elyun/bylane state read respond-queue
 ```
 
+출력된 JSON에서 `queue` 배열의 `status === "pending"` 항목을 선택한다.
+
 pending 항목이 있으면 각 PR에 대해:
 
 1. `hasChangesRequested` 여부 확인:
@@ -50,17 +47,8 @@ pending 항목이 있으면 각 PR에 대해:
 3. 완료 후 큐 항목을 `status: "responded"`로 업데이트:
 
 ```bash
-node -e "
-import('./src/state.js').then(({readState, writeState}) => {
-  const q = readState('respond-queue', '.bylane/state')
-  const queue = (q?.queue ?? []).map(p =>
-    p.number === PR_NUMBER
-      ? { ...p, status: 'responded', respondedAt: new Date().toISOString() }
-      : p
-  )
-  writeState('respond-queue', { status: 'running', queue }, '.bylane/state')
-})
-"
+# 현재 큐 읽기 후 PR_NUMBER 항목을 responded로 업데이트하여 다시 쓰기
+npx @elyun/bylane state write respond-queue '{"status":"running","queue":UPDATED_QUEUE_JSON}'
 ```
 
 4. 다음 pending 항목으로 반복. pending 없으면 5분 대기 후 재확인 (폴러 주기와 동일).

package/commands/bylane-review-agent.md

@@ -69,7 +69,7 @@ Enter 또는 아무것도 선택하지 않으면 → `all` (전체 검사)
 ## 실행 전 상태 기록
 
 ```bash
-node -e "import('./src/state.js').then(({writeState})=>writeState('review-agent',{status:'in_progress',startedAt:new Date().toISOString(),progress:0,retries:0,log:[]}))"
+npx @elyun/bylane state write review-agent '{"status":"in_progress","startedAt":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","progress":0,"retries":0,"log":[]}'
 ```
 
 ## 실행 흐름
@@ -180,7 +180,7 @@ curl -s -X POST \
 ### 5. 상태 업데이트
 
 ```bash
-node -e "import('./src/state.js').then(({writeState})=>writeState('review-agent',{status:'completed',progress:100,approved:APPROVED_BOOL,commentCount:COMMENT_COUNT}))"
+npx @elyun/bylane state write review-agent '{"status":"completed","progress":100,"approved":APPROVED_BOOL,"commentCount":COMMENT_COUNT}'
 ```
 
 ## 출력

package/commands/bylane-review-loop.md

@@ -47,30 +47,19 @@ node src/review-loop.js
 아래 루프를 실행하면서 pending PR이 생길 때마다 review-agent를 실행한다:
 
 ```bash
-# 큐 확인
-node -e "
-import('./src/state.js').then(({readState}) => {
-  const q = readState('review-queue', '.bylane/state')
-  const pending = (q?.queue ?? []).filter(p => p.status === 'pending')
-  console.log(JSON.stringify(pending))
-})
-"
+# 큐 확인 (pending 항목 필터링)
+npx @elyun/bylane state read review-queue
 ```
 
+출력된 JSON에서 `queue` 배열의 `status === "pending"` 항목을 선택한다.
+
 pending 항목이 있으면 각 PR에 대해:
 1. `bylane-review-agent` skill 실행 (PR 번호 전달)
 2. 리뷰 완료 후 큐 항목을 `status: "reviewed"`로 업데이트:
 
 ```bash
-node -e "
-import('./src/state.js').then(({readState, writeState}) => {
-  const q = readState('review-queue', '.bylane/state')
-  const queue = (q?.queue ?? []).map(p =>
-    p.number === PR_NUMBER ? { ...p, status: 'reviewed', reviewedAt: new Date().toISOString() } : p
-  )
-  writeState('review-queue', { status: 'running', queue }, '.bylane/state')
-})
-"
+# 현재 큐 읽기 후 PR_NUMBER 항목을 reviewed로 업데이트하여 다시 쓰기
+npx @elyun/bylane state write review-queue '{"status":"running","queue":UPDATED_QUEUE_JSON}'
 ```
 
 3. 다음 pending 항목으로 반복

package/commands/bylane-test-agent.md

@@ -12,7 +12,7 @@ description: 변경된 코드의 테스트를 실행하고 결과를 반환한
 ## 실행 전 상태 기록
 
 ```bash
-node -e "import('./src/state.js').then(({writeState})=>writeState('test-agent',{status:'in_progress',startedAt:new Date().toISOString(),progress:0,retries:0,log:[]}))"
+npx @elyun/bylane state write test-agent '{"status":"in_progress","startedAt":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","progress":0,"retries":0,"log":[]}'
 ```
 
 ## 실행 흐름

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elyun/bylane",
-  "version": "1.17.0",
+  "version": "1.18.0",
   "description": "Frontend development harness for Claude Code",
   "type": "module",
   "bin": {

package/src/cleanup.js

@@ -0,0 +1,152 @@
+/**
+ * cleanup.js
+ * 상태 파일 정리, 권한 수정, 좀비 프로세스/에이전트 초기화
+ * monitor [r] 키 또는 `npx @elyun/bylane cleanup`으로 실행
+ */
+import { readdirSync, chmodSync, existsSync, unlinkSync, readFileSync, writeFileSync, mkdirSync } from 'fs'
+import { join } from 'path'
+import { readState, writeState } from './state.js'
+
+const STATE_DIR = '.bylane/state'
+const STALE_MS = 30 * 60 * 1000   // 30분 이상 in_progress → 초기화
+const SUBAGENTS_FILE = join(STATE_DIR, 'subagents.json')
+
+/** 프로세스가 살아있는지 확인 (kill -0) */
+function isPidAlive(pid) {
+  try {
+    process.kill(Number(pid), 0)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/** subagents.json에서 죽은 PID 제거 */
+function cleanSubagents() {
+  if (!existsSync(SUBAGENTS_FILE)) return []
+  let data
+  try { data = JSON.parse(readFileSync(SUBAGENTS_FILE, 'utf8')) } catch { return [] }
+
+  const before = (data.active ?? []).length
+  const active = (data.active ?? []).filter(a => {
+    if (!a.pid) return false
+    return isPidAlive(a.pid)
+  })
+  const cleaned = before - active.length
+
+  if (cleaned > 0) {
+    writeFileSync(SUBAGENTS_FILE, JSON.stringify({ ...data, active }, null, 2))
+  }
+  return cleaned > 0 ? [`subagents.json: active ${before}개 → ${active.length}개 (${cleaned}개 제거)`] : []
+}
+
+/** 디렉토리 및 파일 권한 수정 */
+function fixPermissions() {
+  const fixed = []
+  try {
+    chmodSync(STATE_DIR, 0o755)
+  } catch {}
+
+  const files = existsSync(STATE_DIR)
+    ? readdirSync(STATE_DIR).filter(f => f.endsWith('.json'))
+    : []
+
+  for (const file of files) {
+    try {
+      chmodSync(join(STATE_DIR, file), 0o644)
+    } catch (e) {
+      fixed.push(`권한 수정 실패: ${file} — ${e.message}`)
+    }
+  }
+  return fixed
+}
+
+/**
+ * 전체 정리 실행
+ * @returns {{ fixed: string[], killed: string[], reset: string[], cleared: string[] }}
+ */
+export function runCleanup() {
+  const result = { fixed: [], killed: [], reset: [], cleared: [] }
+
+  if (!existsSync(STATE_DIR)) {
+    mkdirSync(STATE_DIR, { recursive: true })
+    return result
+  }
+
+  // 1. 파일 권한 수정
+  result.fixed.push(...fixPermissions())
+
+  // 2. 상태 파일 순회
+  const files = readdirSync(STATE_DIR).filter(f => f.endsWith('.json'))
+
+  for (const file of files) {
+    const name = file.replace('.json', '')
+
+    // 특수 파일 건너뜀
+    if (name === 'cancel') continue
+
+    // subagents 별도 처리
+    if (name === 'subagents') {
+      result.cleared.push(...cleanSubagents())
+      continue
+    }
+
+    const state = readState(name, STATE_DIR)
+    if (!state) continue
+
+    // 루프: PID가 죽었으면 stopped로 전환
+    if (name.endsWith('-loop') && state.pid && state.status === 'running') {
+      if (!isPidAlive(state.pid)) {
+        writeState(name, { ...state, status: 'stopped', stoppedAt: new Date().toISOString() }, STATE_DIR)
+        result.killed.push(`${name}: PID ${state.pid} 없음 → stopped`)
+      }
+    }
+
+    // in_progress 상태가 30분 이상 → failed로 초기화
+    if (state.status === 'in_progress' && state.startedAt) {
+      const age = Date.now() - new Date(state.startedAt).getTime()
+      if (age > STALE_MS) {
+        writeState(name, {
+          ...state,
+          status: 'failed',
+          error: `stale: ${Math.floor(age / 60000)}분 초과 in_progress`
+        }, STATE_DIR)
+        result.reset.push(`${name}: ${Math.floor(age / 60000)}분 in_progress → failed`)
+      }
+    }
+
+    // 큐 파일: responding/reviewing 상태가 남아있으면 pending으로 복구
+    if ((name === 'review-queue' || name === 'respond-queue') && Array.isArray(state.queue)) {
+      const fixed = state.queue.map(item =>
+        item.status === 'reviewing' || item.status === 'responding'
+          ? { ...item, status: 'pending', recoveredAt: new Date().toISOString() }
+          : item
+      )
+      const changedCount = fixed.filter((item, i) => item.status !== state.queue[i].status).length
+      if (changedCount > 0) {
+        writeState(name, { ...state, queue: fixed }, STATE_DIR)
+        result.reset.push(`${name}: ${changedCount}개 진행중 항목 → pending 복구`)
+      }
+    }
+  }
+
+  return result
+}
+
+/** 결과를 사람이 읽기 쉬운 문자열로 출력 */
+export function formatCleanupResult(result) {
+  const lines = []
+  const total = Object.values(result).reduce((s, arr) => s + arr.length, 0)
+
+  if (total === 0) {
+    lines.push('정리할 항목 없음.')
+    return lines.join('\n')
+  }
+
+  if (result.killed.length)  lines.push('  [종료]', ...result.killed.map(s => `    · ${s}`))
+  if (result.reset.length)   lines.push('  [초기화]', ...result.reset.map(s => `    · ${s}`))
+  if (result.cleared.length) lines.push('  [정리]', ...result.cleared.map(s => `    · ${s}`))
+  if (result.fixed.length)   lines.push('  [오류]', ...result.fixed.map(s => `    · ${s}`))
+
+  return lines.join('\n')
+}

package/src/cli.js

@@ -141,6 +141,45 @@ function install() {
 
 if (command === 'install') {
   install()
+} else if (command === 'models') {
+  // models → 에이전트별 모델 목록 출력 (KEY=VALUE 형식)
+  const { loadConfig, getAgentModel } = await import('./config.js')
+  const config = loadConfig()
+  const agents = ['orchestrator','issue-agent','code-agent','test-agent',
+    'commit-agent','pr-agent','review-agent','respond-agent','notify-agent','analyze-agent']
+  agents.forEach(a => console.log(`${a}=${getAgentModel(config, a)}`))
+} else if (command === 'branch') {
+  // branch ISSUE_NUMBER  → 브랜치명 출력
+  const issueNumber = Number(args[1])
+  if (!issueNumber) { console.error('사용법: bylane branch <issueNumber>'); process.exit(1) }
+  const { buildBranchNameFromConfig } = await import('./branch.js')
+  const { loadConfig } = await import('./config.js')
+  console.log(buildBranchNameFromConfig(loadConfig(), issueNumber))
+} else if (command === 'state') {
+  // state write AGENT '{"status":"in_progress",...}'
+  // state append AGENT "메시지"
+  // state read AGENT
+  const subCmd = args[1]
+  const agentName = args[2]
+  const payload = args[3]
+  const { writeState, appendLog, readState } = await import('./state.js')
+
+  if (subCmd === 'write' && agentName && payload) {
+    writeState(agentName, JSON.parse(payload))
+  } else if (subCmd === 'append' && agentName && payload) {
+    appendLog(agentName, payload)
+  } else if (subCmd === 'read' && agentName) {
+    console.log(JSON.stringify(readState(agentName), null, 2))
+  } else {
+    console.error('사용법: bylane state <write|append|read> <agentName> [payload]')
+    process.exit(1)
+  }
+} else if (command === 'cleanup') {
+  const { runCleanup, formatCleanupResult } = await import('./cleanup.js')
+  console.log('\n  byLane 상태 정리 중...\n')
+  const result = runCleanup()
+  console.log(formatCleanupResult(result))
+  console.log('\n  완료.\n')
 } else if (command === 'monitor') {
   // 항상 현재 패키지의 모니터 실행 (버전 일치 보장)
   const monitorPath = join(__dirname, 'monitor', 'index.js')

package/src/monitor/index.js

@@ -4,6 +4,7 @@ import { createLayout } from './layout.js'
 import { createPoller } from './poller.js'
 import { existsSync, readFileSync, writeFileSync, unlinkSync, mkdirSync } from 'fs'
 import { join } from 'path'
+import { runCleanup, formatCleanupResult } from '../cleanup.js'
 
 const { screen, header, pipeline, log, queue, status, onCleanup } = createLayout()
 const poller = createPoller()
@@ -101,6 +102,34 @@ screen.key('s', () => {
   })
 })
 
+// 'r' — 상태 정리 (권한 수정, 좀비 초기화, 큐 복구)
+screen.key('r', () => {
+  header.update({
+    workflowTitle: '상태 정리 중...',
+    time: new Date().toLocaleTimeString('ko-KR', { hour12: false }),
+    elapsed: `${Math.floor((Date.now() - startTime) / 1000)}s`
+  })
+  screen.render()
+
+  try {
+    const result = runCleanup()
+    const summary = formatCleanupResult(result)
+    const total = Object.values(result).reduce((s, a) => s + a.length, 0)
+    header.update({
+      workflowTitle: total > 0 ? `정리 완료 (${total}건)` : '정리 완료 — 이상 없음',
+      time: new Date().toLocaleTimeString('ko-KR', { hour12: false }),
+      elapsed: `${Math.floor((Date.now() - startTime) / 1000)}s`
+    })
+  } catch (e) {
+    header.update({
+      workflowTitle: `정리 실패: ${e.message}`,
+      time: new Date().toLocaleTimeString('ko-KR', { hour12: false }),
+      elapsed: `${Math.floor((Date.now() - startTime) / 1000)}s`
+    })
+  }
+  screen.render()
+})
+
 // 'c' — 하위 에이전트 취소 플래그 토글
 screen.key('c', () => {
   if (existsSync(CANCEL_FILE)) {

package/src/monitor/layout.js

@@ -62,7 +62,7 @@ export function createLayout() {
     left: 0,
     width: '100%',
     height: 1,
-    content: ' [q]종료  [c]에이전트취소토글  [s]루프종료  [Tab]포커스  [j/k]로그스크롤',
+    content: ' [q]종료  [r]상태정리  [c]에이전트취소토글  [s]루프종료  [Tab]포커스  [j/k]로그스크롤',
     style: { fg: 'black', bg: 'cyan' }
   })
   screen.append(footer)