# 신호등 체계 설계 계획서

> 작성일: 2026-04-23
> 상태: 구현 완료 (task-2126, task-2129)

## 1. 목적

팀원(에이전트)의 현재 작업 상태를 실시간으로 시각화하여, 제이회장님이 대시보드에서 누가 일하고 있고, 누가 대기 중이며, 누가 유휴 상태인지 즉시 파악할 수 있게 한다.

## 2. 상태 정의

- **유휴 (idle)** — 회색: 팀에 할당된 작업 없음
- **대기 (standby)** — 노란색: 팀에 작업 할당됨, 아직 이 멤버가 호출되지 않음
- **작업중 (working)** — 초록색: 팀장이 이 멤버를 호출하여 실제 작업 수행 중

## 3. 전이 규칙 (제이회장님 직접 정의)

1. dispatch.py로 팀에 작업 위임 → **팀장: 작업중(초록), 팀원 전원: 대기(노란)**
2. 팀장이 sub agent(팀원) 호출 → **해당 팀원: 작업중(초록)**
3. 팀원 개별 작업 완료 → **해당 팀원: 대기(노란) 복귀**
4. 팀 전체 작업 완료 (.done 생성) → **팀장 + 팀원 전원: 유휴(회색)**

## 4. 아키텍처

### 4.1 백엔드 데이터 흐름

```
dispatch.py → member-status.json 업데이트 (즉시)
                     ↓
data_loader.py → _enrich_member_status() → task-timers.json과 교차 보강
                     ↓
API 응답 → /api/member-status
```

### 4.2 프론트엔드 렌더링

```
/api/member-status → App.js → MemberRow (utils.js)
                                   ↓
                              StatusDot 색상 결정
                              working → 초록 (emerald-400)
                              standby → 노란 (amber-400)
                              idle    → 회색 (gray-400)
```

### 4.3 논리적 팀 차용 (Borrowed Tasks)

marketing, content, design, consulting, publishing 등 논리적 팀은 자체 봇이 없어 dev팀 봇을 차용(borrow)하여 사용. 차용 task는 보라색 도트(`bg-violet-400`)로 구분.

## 5. 핵심 파일

- `dispatch.py` — `_update_member_status_on_dispatch()`: dispatch 시 즉시 상태 업데이트
- `dashboard/data_loader.py` — `_enrich_member_status()`: task-timers.json 기반 보강
- `dashboard/static/utils.js` — `StatusDot`, `MemberRow`: 프론트엔드 렌더링
- `memory/events/member-status.json` — 상태 데이터 저장소
- `memory/specs/traffic-light-spec.md` — 단일 소스 (Single Source of Truth)

## 6. 조직 구조 고려사항

개발실(development-office)은 `sub_teams` 구조를 사용하므로, dev1~8팀은 `columns.teams[].sub_teams[]`에 위치. 모든 탐색 함수는 최상위 팀뿐 아니라 sub_teams도 재귀적으로 탐색해야 함.