@silbaram/artifact-driven-agent 0.1.1 → 0.1.3

package/core/roles/qa.md

@@ -17,20 +17,20 @@
 
 ## 2. 입력 문서 (Mandatory)
 
-- artifacts/plan.md (요구사항 기준)
-- artifacts/project.md (품질 기준 참조)
-- artifacts/backlog.md (수용 조건)
-- artifacts/current-sprint.md (QA 대상 Task)
+- ai-dev-team/artifacts/plan.md (요구사항 기준)
+- ai-dev-team/artifacts/project.md (품질 기준 참조)
+- ai-dev-team/artifacts/backlog.md (수용 조건)
+- ai-dev-team/artifacts/current-sprint.md (QA 대상 Task)
 - 구현된 결과물
 
 (선택)
-- artifacts/review-report.md (Reviewer 의견 참고)
+- ai-dev-team/artifacts/review-report.md (Reviewer 의견 참고)
 
 ---
 
 ## 3. 산출물 (Output)
 
-- artifacts/qa-report.md
+- ai-dev-team/artifacts/qa-report.md
 
 ---
 
@@ -116,7 +116,12 @@
 - ❌ 기술적 구현 방식 지적 (Reviewer 영역)
 - ❌ 새로운 요구사항 추가
 - ❌ "더 좋을 것 같다"로 FAIL 판정
-- ❌ 코드 직접 수정
+- ❌ **코드 직접 수정/구현 (절대 금지)**
+- ❌ **기획/아키텍처 작업 (다른 역할)**
+- ❌ **코드 리뷰 수행 (Reviewer 역할)**
+
+> ⚠️ **중요**: QA는 오직 수용 조건 검증과 qa-report.md 작성만 수행합니다.
+> 코드 수정이나 다른 역할의 작업은 절대 수행하지 않습니다.
 
 ---
 
@@ -260,3 +265,42 @@ TASK-001 QA를 시작하겠습니다.
 ## 5. QA 코멘트 (사실만)
 - 
 ```
+
+
+---
+
+## 13. 멀티 세션 상태 관리
+
+> 📖 상세 규칙: `core/rules/role-state-protocol.md` 참조
+
+### 필수 동작
+
+| 시점 | 동작 |
+|------|------|
+| 세션 시작 | `.ada-status.json`에 자신 등록 |
+| QA 완료 | `taskProgress` 업데이트, 알림 전송 |
+| FAIL 시 | Developer에게 알림, 사유 전달 |
+| 세션 종료 | `activeSessions`에서 제거 |
+
+### QA 완료 알림
+
+```json
+{
+  "type": "complete",
+  "from": "qa",
+  "message": "T001 QA 완료 - PASS (Manager 승인 필요)"
+}
+```
+
+### 질문 예시
+
+```
+━━━━━━━━━━━━━━━━━━━━━━
+📨 질문 등록됨 [QQ001]
+━━━━━━━━━━━━━━━━━━━━━━
+질문: 수용 조건에 명시되지 않은 동작입니다. PASS 처리할까요?
+옵션: (y) PASS / (n) FAIL
+
+Manager 세션에서 응답 가능합니다.
+또는 이 터미널에서 응답: (y/n): _
+```

package/core/roles/reviewer.md

@@ -17,17 +17,17 @@ project.md 기준으로 코드를 검토하고,
 
 ## 2. 입력 문서 (Mandatory)
 
-- artifacts/plan.md
-- artifacts/project.md
-- artifacts/backlog.md (수용 조건 확인)
-- artifacts/current-sprint.md (리뷰 대상 Task)
+- ai-dev-team/artifacts/plan.md
+- ai-dev-team/artifacts/project.md
+- ai-dev-team/artifacts/backlog.md (수용 조건 확인)
+- ai-dev-team/artifacts/current-sprint.md (리뷰 대상 Task)
 - 소스 코드
 
 ---
 
 ## 3. 산출물 (Output)
 
-- artifacts/review-report.md
+- ai-dev-team/artifacts/review-report.md
 
 ---
 
@@ -149,7 +149,12 @@ project.md 규칙 준수?
 - ❌ 수용 조건 외 기능 요구
 - ❌ 개인 스타일 강요 (project.md에 없는)
 - ❌ 아키텍처 변경 요구 (Manager 승인 없이)
-- ❌ 코드 직접 수정
+- ❌ **코드 직접 수정/구현 (절대 금지)**
+- ❌ **기획/아키텍처 작업 (다른 역할)**
+- ❌ **QA 테스트 수행 (QA 역할)**
+
+> ⚠️ **중요**: Reviewer는 오직 코드 리뷰와 review-report.md 작성만 수행합니다.
+> 코드 수정이나 다른 역할의 작업은 절대 수행하지 않습니다.
 
 ---
 
@@ -278,3 +283,42 @@ TASK-001 리뷰부터 시작하겠습니다.
 ## 4. 종합 코멘트
 (사실 기반, 간결하게)
 ```
+
+
+---
+
+## 14. 멀티 세션 상태 관리
+
+> 📖 상세 규칙: `core/rules/role-state-protocol.md` 참조
+
+### 필수 동작
+
+| 시점 | 동작 |
+|------|------|
+| 세션 시작 | `.ada-status.json`에 자신 등록 |
+| 리뷰 완료 | `taskProgress` 업데이트, 알림 전송 |
+| REJECT 시 | Developer에게 알림, 질문 등록 (필요시) |
+| 세션 종료 | `activeSessions`에서 제거 |
+
+### 리뷰 완료 알림
+
+```json
+{
+  "type": "complete",
+  "from": "reviewer",
+  "message": "T001 리뷰 완료 - PASS"
+}
+```
+
+### 질문 예시
+
+```
+━━━━━━━━━━━━━━━━━━━━━━
+📨 질문 등록됨 [QR001]
+━━━━━━━━━━━━━━━━━━━━━━
+질문: 이 패턴은 project.md에 없는데, 허용할까요?
+옵션: (y) 허용 / (n) REJECT
+
+Manager 세션에서 응답 가능합니다.
+또는 이 터미널에서 응답: (y/n): _
+```

package/core/rules/role-state-protocol.md

@@ -0,0 +1,281 @@
+# Rule: 역할별 상태 관리 (Role State Protocol)
+
+모든 역할이 따라야 하는 상태 관리 규칙.
+멀티 터미널 환경에서 세션 간 통신을 위해 사용.
+
+---
+
+## 1. 세션 시작 시
+
+모든 역할은 세션 시작 시 다음을 수행:
+
+```
+1. .ada-status.json 확인 (없으면 템플릿으로 생성)
+2. activeSessions에 자신 등록
+3. 파일 저장
+4. CLI에 등록 완료 표시
+```
+
+### 등록 예시
+
+```json
+{
+  "role": "developer",
+  "tool": "codex",
+  "startedAt": "2024-01-15T10:00:00Z",
+  "status": "active"
+}
+```
+
+### CLI 출력
+
+```
+📡 세션 등록됨 (Developer/codex)
+   Manager 모니터링 시 표시됩니다.
+```
+
+---
+
+## 2. 질문 등록
+
+사용자에게 중요한 결정을 물어야 할 때:
+
+### 절차
+
+```
+1. 질문 생성
+2. pendingQuestions에 추가
+3. notifications에 알림 추가
+4. 파일 저장
+5. 응답 대기 또는 현재 터미널에서 직접 응답 받기
+```
+
+### 질문 형식
+
+```json
+{
+  "id": "Q[역할약자][순번]",
+  "from": "역할명",
+  "to": "user",
+  "question": "질문 내용",
+  "options": ["옵션1", "옵션2"],
+  "context": "추가 설명 (선택)",
+  "priority": "normal",
+  "status": "waiting",
+  "createdAt": "ISO8601"
+}
+```
+
+### CLI 출력 (질문 등록 후)
+
+```
+━━━━━━━━━━━━━━━━━━━━━━
+📨 질문 등록됨 [QD001]
+━━━━━━━━━━━━━━━━━━━━━━
+질문: Redis 캐시를 적용할까요?
+옵션: (y) 적용 / (n) 미적용
+
+Manager 세션에서 응답 가능합니다.
+또는 이 터미널에서 응답: (y/n): _
+```
+
+---
+
+## 3. 응답 확인
+
+질문 등록 후 응답을 기다리는 방법:
+
+### 옵션 A: 현재 터미널에서 직접 응답
+
+```
+사용자가 바로 응답 입력
+→ pendingQuestions 업데이트
+→ 작업 계속 진행
+```
+
+### 옵션 B: Manager 세션에서 응답 대기
+
+```
+1. 주기적으로 .ada-status.json 확인 (5초 간격)
+2. 자신의 질문 상태 확인
+3. status가 "answered"면 answer 읽기
+4. 작업 계속 진행
+```
+
+### CLI 출력 (대기 중)
+
+```
+⏳ Manager 응답 대기 중... (Ctrl+C로 취소)
+   또는 여기서 직접 응답: _
+```
+
+### CLI 출력 (응답 수신)
+
+```
+✅ 응답 수신: "y" (Manager)
+   → Redis 캐시 적용으로 진행합니다.
+```
+
+---
+
+## 4. Task 진행 상황 업데이트
+
+작업 진행 시 상태 갱신:
+
+### 업데이트 시점
+
+- 작업 시작 시
+- 주요 마일스톤 도달 시
+- 작업 완료 시
+- 문제 발생 시
+
+### 형식
+
+```json
+{
+  "T001": {
+    "status": "IN_DEV",
+    "assignee": "developer",
+    "progress": 50,
+    "lastUpdate": "ISO8601",
+    "note": "API 구현 완료, DB 연동 중"
+  }
+}
+```
+
+### CLI 출력
+
+```
+📊 진행 상황 업데이트: T001 (50%)
+```
+
+---
+
+## 5. 알림 전송
+
+다른 세션에 알림을 보내야 할 때:
+
+### 알림 유형
+
+| 타입 | 용도 |
+|------|------|
+| info | 일반 정보 (작업 시작/완료) |
+| warning | 주의 필요 (30초 잠금 초과) |
+| error | 오류 발생 (파일 충돌) |
+| question | 질문 등록됨 |
+| complete | 단계 완료 (Review PASS 등) |
+
+### 형식
+
+```json
+{
+  "id": "N001",
+  "type": "complete",
+  "from": "reviewer",
+  "message": "T001 리뷰 완료 - PASS",
+  "read": false,
+  "createdAt": "ISO8601"
+}
+```
+
+---
+
+## 6. 파일 잠금
+
+동시 수정 방지:
+
+### 잠금 필요 파일
+
+- `current-sprint.md`
+- `backlog.md`
+- `decision.md`
+
+### 잠금 절차
+
+```
+1. locks에 파일 등록
+2. 작업 수행
+3. 잠금 해제
+```
+
+### 형식
+
+```json
+{
+  "ai-dev-team/artifacts/current-sprint.md": {
+    "holder": "developer",
+    "acquiredAt": "ISO8601"
+  }
+}
+```
+
+### 충돌 시
+
+```
+⚠️ 파일 잠금 충돌
+   current-sprint.md가 Manager에 의해 잠겨 있습니다.
+   대기 중... (10초)
+```
+
+---
+
+## 7. 세션 종료 시
+
+```
+1. activeSessions에서 자신 제거
+2. 미응답 질문 처리:
+   - 취소 표시 또는
+   - 다음 세션에서 응답 가능하도록 유지
+3. 잠금 해제
+4. 파일 저장
+```
+
+### CLI 출력
+
+```
+📡 세션 종료됨 (Developer/codex)
+   작업 시간: 45분
+   완료 Task: T001
+```
+
+---
+
+## 8. 에러 처리
+
+### 상태 파일 읽기 실패
+
+```
+⚠️ .ada-status.json 읽기 실패
+   → 새 파일 생성
+```
+
+### 동시 쓰기 충돌
+
+```
+⚠️ 상태 파일 충돌 감지
+   → 재시도 (3회)
+   → 실패 시 강제 갱신
+```
+
+---
+
+## 9. CLI 공통 표시
+
+### 세션 시작 헤더
+
+```
+━━━━━━━━━━━━━━━━━━━━━━
+🔧 Developer 세션 시작
+━━━━━━━━━━━━━━━━━━━━━━
+📡 세션 등록: Developer/codex
+🔗 활성 세션: Manager(claude), Reviewer(gemini)
+```
+
+### 다른 세션 알림 수신
+
+```
+━━━━━━━━━━━━━━━━━━━━━━
+🔔 알림 [Manager]
+━━━━━━━━━━━━━━━━━━━━━━
+T002가 스프린트에 추가되었습니다.
+```

package/core/rules/session-state.md

@@ -0,0 +1,255 @@
+# Rule: 세션 상태 관리 (Session State Management)
+
+멀티 터미널 환경에서 여러 역할이 동시에 작업할 때의 상태 관리 규칙.
+
+---
+
+## 1. 상태 파일
+
+### 위치
+```
+ai-dev-team/.ada-status.json
+```
+
+### 스키마
+
+```json
+{
+  "version": "1.0",
+  "updatedAt": "ISO8601 timestamp",
+  "currentPhase": "planning|architecture|development|review|qa|done",
+  "activeSessions": [
+    {
+      "role": "역할명",
+      "tool": "claude|codex|gemini|copilot",
+      "pid": "프로세스ID (선택)",
+      "startedAt": "ISO8601 timestamp",
+      "status": "active|idle|waiting"
+    }
+  ],
+  "pendingQuestions": [
+    {
+      "id": "Q001",
+      "from": "역할명",
+      "to": "user|manager|역할명",
+      "question": "질문 내용",
+      "options": ["옵션1", "옵션2"],
+      "priority": "high|normal|low",
+      "status": "waiting|answered|timeout",
+      "createdAt": "ISO8601 timestamp",
+      "answeredAt": "ISO8601 timestamp (선택)",
+      "answer": "응답 (선택)"
+    }
+  ],
+  "taskProgress": {
+    "T001": {
+      "status": "READY|IN_DEV|IN_REVIEW|IN_QA|DONE",
+      "assignee": "역할명",
+      "progress": 0-100,
+      "lastUpdate": "ISO8601 timestamp"
+    }
+  },
+  "notifications": [
+    {
+      "id": "N001",
+      "type": "info|warning|error|question",
+      "from": "역할명",
+      "message": "알림 내용",
+      "read": false,
+      "createdAt": "ISO8601 timestamp"
+    }
+  ],
+  "locks": {
+    "파일경로": {
+      "holder": "역할명",
+      "acquiredAt": "ISO8601 timestamp"
+    }
+  }
+}
+```
+
+---
+
+## 2. 역할별 상태 업데이트 규칙
+
+### 세션 시작 시
+```
+1. .ada-status.json 읽기 (없으면 생성)
+2. activeSessions에 자신 추가
+3. 파일 저장
+```
+
+### 질문 발생 시
+```
+1. pendingQuestions에 질문 추가
+2. status: "waiting"
+3. notifications에 알림 추가
+4. 파일 저장
+5. CLI에 "[질문 등록됨] Manager에게 알림 전송" 출력
+```
+
+### 작업 진행 시
+```
+1. taskProgress 업데이트
+2. progress 값 갱신
+3. 파일 저장
+```
+
+### 세션 종료 시
+```
+1. activeSessions에서 자신 제거
+2. 미응답 질문 정리
+3. 파일 저장
+```
+
+---
+
+## 3. Manager 모니터링 모드
+
+Manager는 두 가지 모드로 동작:
+
+### 일반 모드
+```
+기존 스프린트 관리 기능
+```
+
+### 모니터링 모드 (--watch)
+```
+1. .ada-status.json 주기적 감시 (2초 간격)
+2. 변경 감지 시 화면 업데이트
+3. pendingQuestions 발생 시 알림
+4. 여기서 직접 응답 가능
+```
+
+---
+
+## 4. 파일 잠금 규칙
+
+### 잠금이 필요한 파일
+```
+- current-sprint.md (동시 수정 방지)
+- backlog.md (Task 상태 변경 시)
+```
+
+### 잠금 절차
+```
+1. locks에 파일 경로와 역할 등록
+2. 작업 수행
+3. 완료 후 잠금 해제
+4. 30초 이상 잠금 유지 시 경고
+```
+
+### 충돌 발생 시
+```
+1. 잠금 보유자 확인
+2. notifications로 알림
+3. 대기 또는 Manager에게 에스컬레이션
+```
+
+---
+
+## 5. 질문/응답 프로토콜
+
+### 질문 등록 (역할 → Manager)
+
+```json
+{
+  "id": "Q001",
+  "from": "developer",
+  "to": "manager",
+  "question": "Redis 캐시를 적용할까요?",
+  "options": ["y: 적용", "n: 미적용"],
+  "priority": "normal",
+  "status": "waiting",
+  "createdAt": "2024-01-15T10:30:00Z"
+}
+```
+
+### 응답 (Manager → 역할)
+
+```json
+{
+  "id": "Q001",
+  "status": "answered",
+  "answeredAt": "2024-01-15T10:32:00Z",
+  "answer": "y"
+}
+```
+
+### 역할에서 응답 확인
+
+```
+1. pendingQuestions에서 자신의 질문 확인
+2. status가 "answered"면 answer 읽기
+3. 질문 항목 삭제 또는 archived로 이동
+4. 작업 계속 진행
+```
+
+---
+
+## 6. 알림 타입
+
+| 타입 | 용도 | 예시 |
+|------|------|------|
+| info | 정보 전달 | "Developer가 T001 작업 시작" |
+| warning | 주의 필요 | "파일 잠금 30초 초과" |
+| error | 오류 발생 | "current-sprint.md 충돌" |
+| question | 응답 필요 | "Architect 질문 대기 중" |
+
+---
+
+## 7. CLI 출력 형식
+
+### 다른 세션에 질문 전달 시
+```
+━━━━━━━━━━━━━━━━━━━━━━
+📨 질문 등록됨
+━━━━━━━━━━━━━━━━━━━━━━
+질문: Redis 캐시를 적용할까요?
+옵션: (y) 적용 / (n) 미적용
+
+Manager 세션에서 응답 대기 중...
+또는 이 터미널에서 응답: (y/n): _
+```
+
+### Manager에서 질문 수신 시
+```
+━━━━━━━━━━━━━━━━━━━━━━
+⚠️ 새 질문 [Developer]
+━━━━━━━━━━━━━━━━━━━━━━
+Q001: Redis 캐시를 적용할까요?
+옵션: (y) 적용 / (n) 미적용
+
+응답: _
+```
+
+---
+
+## 8. 상태 초기화
+
+### 전체 초기화
+```bash
+ada reset --status
+```
+
+### 좀비 세션 정리
+```bash
+ada status --clean
+```
+
+---
+
+## 9. 에러 처리
+
+### 상태 파일 손상 시
+```
+1. .ada-status.json.bak에서 복구 시도
+2. 실패 시 초기화
+3. 모든 세션에 알림
+```
+
+### 네트워크 파일시스템 주의
+```
+- NFS, SMB 등에서는 파일 잠금 불안정
+- 로컬 파일시스템 권장
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@silbaram/artifact-driven-agent",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "CLI 기반 멀티 AI 에이전트 개발 프레임워크 - AI가 규칙을 어기지 못하게 하는 문서 기반 개발",
   "type": "module",
   "bin": {
@@ -11,7 +11,6 @@
     "src",
     "core",
     "templates",
-    "docs",
     "examples",
     "ai-dev-team"
   ],