@silbaram/artifact-driven-agent 0.1.6 → 0.1.9

package/ai-dev-team/rules/iteration.md

@@ -0,0 +1,236 @@
+# Iteration Rules (스프린트/Task 단위 작업 규칙)
+
+> 이 문서는 Task 단위 반복 개발의 규칙을 정의한다.
+> 모든 역할이 이 규칙을 따른다.
+> Manager가 스프린트를 관리한다.
+
+---
+
+## 1. 핵심 원칙
+
+### 1.1 Task 단위 개발
+
+```
+❌ 잘못된 방식 (Waterfall)
+전체 기획 → 전체 설계 → 전체 개발 → 전체 테스트
+
+✅ 올바른 방식 (Iterative)
+Task 1 완성 → Task 2 완성 → Task 3 완성 → ...
+```
+
+### 1.2 작업 범위 제한
+
+- 각 역할은 **sprints/sprint-N/meta.md에 정의된 Task만** 작업한다
+- 스프린트 외 작업은 금지 (Manager 승인 없이)
+- "김에" 작업 금지
+
+### 1.3 완료의 정의
+
+Task는 다음을 모두 충족해야 DONE:
+- [ ] 수용 조건 100% 충족
+- [ ] 구현 완료
+- [ ] 문서 반영 완료
+- [ ] Reviewer PASS
+- [ ] Reviewer PASS
+- [ ] Manager 승인
+
+---
+
+## 2. 스프린트 라이프사이클
+
+### 2.1 스프린트 시작
+
+**트리거:** Manager가 스프린트 시작 선언
+
+**절차:**
+1. Manager가 backlog/task-NNN.md에서 READY 상태 Task 선택
+2. 선택된 Task를 IN_SPRINT로 변경
+3. sprints/sprint-N/meta.md 생성/갱신
+4. 스프린트 목표 정의
+5. 역할별 작업 배정
+
+**산출물:**
+- sprints/sprint-N/meta.md 갱신
+- backlog/task-NNN.md 상태 갱신
+
+### 2.2 스프린트 진행
+
+**Task 상태 흐름:**
+```
+IN_SPRINT → IN_DEV → IN_REVIEW → IN_REVIEW → DONE
+               ↑          ↓          ↓
+               └──────────┴──────────┘
+                  (REJECT/FAIL 시)
+```
+
+**일일 확인 사항:**
+- 각 Task 상태
+- 차단 사항 (Blockers)
+- 예상 완료 여부
+
+### 2.3 스프린트 종료
+
+**트리거:** 
+- 모든 Task DONE, 또는
+- 스프린트 종료일 도달
+
+**절차:**
+1. 완료/미완료 Task 정리
+2. 미완료 Task 처리 결정 (이월/취소)
+3. sprints/sprint-N/meta.md 회고 작성
+4. backlog/task-NNN.md 상태 갱신
+5. 다음 스프린트 준비
+
+---
+
+## 3. 역할별 이터레이션 규칙
+
+### 3.1 Planner
+
+- 스프린트 중 새 요구사항 → backlog에 BACKLOG 상태로 추가
+- 현재 스프린트의 Task 변경 금지 (Manager 승인 없이)
+- 진행 중(IN_DEV+) Task의 수용 조건 변경 금지
+
+### 3.2 Developer
+
+- sprints/sprint-N/meta.md의 내 Task만 작업
+- Task 완료 후 다음 Task로 이동
+- 스프린트 외 작업 금지
+- 수용 조건 외 기능 추가 금지
+
+### 3.3 Reviewer
+
+- IN_REVIEW 상태 Task만 리뷰
+- 해당 Task 범위 내 코드만 리뷰
+- 스프린트 외 코드 리뷰 금지
+- 수용 조건 외 요구 금지
+
+### 3.4 Reviewer
+
+- IN_REVIEW 상태 Task만 검증
+- 해당 Task 수용 조건만 검증
+- 스프린트 외 기능 검증 금지
+- 수용 조건 외 기준으로 FAIL 금지
+
+### 3.5 Manager
+
+- 스프린트 시작/종료 결정
+- Task 상태 전환 승인 (→ DONE)
+- 긴급 Task 추가 승인
+- 스프린트 범위 변경 승인
+
+---
+
+## 4. Task 단위 문서 갱신
+
+### 4.1 갱신 시점
+
+| 문서 | 갱신 시점 | 담당 |
+|------|----------|------|
+| backlog/task-NNN.md | Task 상태 변경 시 | 해당 역할 |
+| sprints/sprint-N/meta.md | 매일 / 상태 변경 시 | Manager |
+| 인터페이스 문서 | Task 완료 시 | Developer |
+| review-reports/task-NNN.md | 리뷰 완료 시 | Reviewer |
+| review-reports/task-NNN.md | Reviewer 완료 시 | Reviewer |
+| decision.md | 판단 발생 시 | Manager |
+
+### 4.2 Task 태그
+
+문서 변경 시 관련 Task ID를 태그:
+
+```markdown
+## 변경 이력
+| Task | 날짜 | 변경 내용 |
+|------|------|----------|
+| [TASK-001] | 2024-01-15 | 초기 구현 |
+```
+
+---
+
+## 5. 예외 상황 처리
+
+### 5.1 긴급 Task 추가
+
+```
+긴급 요청 발생
+    ↓
+Planner: backlog에 P0로 추가
+    ↓
+C0acC6a9C790: 긴급성 판단
+    ├── 긴급 아님 → 다음 스프린트
+    └── 긴급 맞음 ↓
+        ↓
+C0acC6a9C790: 현재 스프린트에 추가
+    ↓
+필요시 다른 Task 조정
+    ↓
+decision.md에 예외 기록
+```
+
+### 5.2 요구사항 변경
+
+- 진행 중 Task: 현재 수용 조건으로 완료 후 새 Task 생성
+- 미시작 Task: 수용 조건 수정 가능 (Manager 승인)
+
+### 5.3 차단 (Blocker) 발생
+
+```
+차단 발생
+    ↓
+Task 상태 → BLOCKED
+    ↓
+Manager에게 즉시 보고
+    ↓
+해결 방안 결정
+    ↓
+해결 후 원래 상태로 복귀
+```
+
+---
+
+## 6. 스프린트 체크리스트
+
+### 스프린트 시작 체크리스트
+
+- [ ] backlog/task-NNN.md에 READY Task 있음
+- [ ] 스프린트 목표 정의됨
+- [ ] sprints/sprint-N/meta.md 생성됨
+- [ ] Task 담당자 배정됨
+- [ ] 의존성 확인됨
+
+### 스프린트 종료 체크리스트
+
+- [ ] 모든 Task 상태 확인
+- [ ] 미완료 Task 처리 결정됨
+- [ ] 회고 작성됨
+- [ ] backlog/task-NNN.md 갱신됨
+- [ ] 스프린트 히스토리 기록됨
+
+---
+
+## 7. 문서 참조 관계
+
+```
+backlog/task-NNN.md (전체 Task)
+    │
+    ├── sprints/sprint-N/meta.md (현재 범위)
+    │       │
+    │       ├── 인터페이스 문서 (Task별 변경)
+    │       └── 소스 코드
+    │
+    ├── plan.md (요구사항 출처)
+    └── project.md (기술 기준)
+```
+
+---
+
+## 8. 금지 사항 요약
+
+| 역할 | 금지 사항 |
+|------|----------|
+| 전체 | 스프린트 외 작업 |
+| 전체 | 수용 조건 외 기능 추가 |
+| Developer | "김에" 리팩토링 |
+| Reviewer | 스프린트 외 코드 리뷰 |
+| Reviewer | 스프린트 외 기능 검증 |
+| Planner | 진행 중 Task 변경 |

package/ai-dev-team/rules/rfc.md

@@ -0,0 +1,31 @@
+# RFC (Request for Change) 규칙
+
+> Frozen 문서 변경을 위한 공식 절차
+
+## RFC가 필요한 경우
+
+- project.md 변경
+- plan.md의 확정된 기능 범위 변경
+- 승인된 decision.md 항목 번복
+
+## RFC 절차
+
+1. RFC 문서 작성 (`rfc/RFC-NNNN-title.md`)
+2. 사용자 리뷰
+3. 승인/거부 결정
+4. 승인 시: 문서 업데이트 + decision.md 기록
+
+## RFC 상태
+
+| 상태 | 설명 |
+|------|------|
+| Draft | 작성 중 |
+| Under Review | 리뷰 중 |
+| Approved | 승인됨 |
+| Rejected | 거부됨 |
+
+## 긴급 변경
+
+- 보안 취약점, 심각한 버그 등
+- 구두 승인 후 적용
+- 24시간 내 RFC 사후 작성

package/ai-dev-team/rules/rollback.md

@@ -0,0 +1,218 @@
+# Rollback Rules (되돌림 규칙)
+
+> 이 문서는 REJECT/FAIL 발생 시 되돌림 절차를 정의한다.
+> Manager가 되돌림을 관리한다.
+
+---
+
+## 1. 되돌림 원칙
+
+- REJECT/FAIL은 정상적인 피드백
+- 되돌림은 품질 보장 과정
+- 되돌림 시 원인 분석 필수
+- 반복 되돌림 시 프로세스 점검
+
+---
+
+## 2. Reviewer REJECT 시 되돌림
+
+### 2.1 REJECT 유형별 처리
+
+| REJECT 유형 | 되돌림 대상 | Manager 개입 |
+|-------------|------------|:------------:|
+| 수용 조건 미충족 | Developer | 불필요 |
+| project.md 규칙 위반 | Developer | 불필요 |
+| 구조적 문제 | Architect | 필요 |
+| 설계 수준 문제 | Architect | 필요 |
+
+### 2.2 REJECT 처리 절차
+
+```
+Reviewer REJECT
+    ↓
+Task 상태: IN_REVIEW → IN_DEV
+    ↓
+review-report.md에 REJECT 사유 기록
+    ↓
+Developer가 수정
+    ↓
+Task 상태: IN_DEV → IN_REVIEW
+    ↓
+Reviewer 재리뷰
+```
+
+### 2.3 구조적 REJECT 시
+
+```
+Reviewer: 구조적 문제로 REJECT
+    ↓
+Manager에게 에스컬레이션
+    ↓
+Manager: Architect 재검토 결정
+    ↓
+C0acC6a9C790: project.md 또는 설계 수정
+    ↓
+Developer: 수정된 설계로 재구현
+```
+
+---
+
+## 3. Reviewer REJECT 시 되돌림
+
+### 3.1 FAIL 유형별 처리
+
+| FAIL 유형 | 되돌림 대상 | 조치 |
+|-----------|------------|------|
+| 구현 누락 | Developer | 누락 기능 구현 |
+| 버그 | Developer | 버그 수정 |
+| 조건 모호 | Planner | 조건 명확화 |
+| 기술적 불가 | Architect | 설계 재검토 |
+
+### 3.2 FAIL 처리 절차
+
+```
+Reviewer REJECT
+    ↓
+Task 상태: IN_REVIEW → IN_DEV
+    ↓
+review-report.md에 FAIL 사유 기록
+    ↓
+원인에 따라 담당자 결정
+    ↓
+수정 후 재리뷰
+```
+
+---
+
+## 4. BLOCK 시 되돌림
+
+### 4.1 BLOCK 상황
+
+| 상황 | 처리 |
+|------|------|
+| 기술적 불가 | Architect 재검토 |
+| 요구사항 불명확 | Planner 명확화 |
+| 외부 의존성 | 대기 또는 우회 |
+
+### 4.2 BLOCK 처리 절차
+
+```
+BLOCK 발생
+    ↓
+Task 상태 → BLOCKED
+    ↓
+Manager에게 에스컬레이션
+    ↓
+Manager: 원인 분석 및 대상 결정
+    ↓
+해당 역할이 문제 해결
+    ↓
+Task 상태 복원 → 재진행
+```
+
+---
+
+## 5. 문서 수정 시 연쇄 영향
+
+### 5.1 plan.md 수정 시
+
+| 영향 | 조치 |
+|------|------|
+| 기존 Task 영향 | backlog.md 수용 조건 검토 |
+| 새 기능 추가 | 새 Task 생성 |
+| 기능 삭제 | 관련 Task 취소 검토 |
+
+### 5.2 project.md 수정 시
+
+| 영향 | 조치 |
+|------|------|
+| 기술 스택 변경 | 전체 코드 검토 필요 |
+| 규칙 변경 | 영향받는 Task 재리뷰 |
+| 구조 변경 | 영향받는 코드 수정 |
+
+> ⚠️ project.md는 Frozen이므로 수정 시 Manager 승인 필수
+
+### 5.3 연쇄 영향 흐름
+
+```
+상위 문서 수정
+    ↓
+영향받는 하위 문서 식별
+    ↓
+영향받는 Task 식별
+    ↓
+Task 상태에 따른 처리:
+├── DONE → 재검증 필요 여부 판단
+├── IN_REVIEW → 재검증
+├── IN_DEV → 수정 반영
+└── IN_SPRINT/READY → 문서만 갱신
+```
+
+---
+
+## 6. 되돌림 제한 규칙
+
+### 6.1 반복 되돌림
+
+| 횟수 | 조치 |
+|:----:|------|
+| 1-2회 | 정상 피드백 |
+| 3회 | Manager 개입, 원인 분석 |
+| 4회+ | 프로세스/역량 점검 |
+
+### 6.2 되돌림 제한
+
+- 같은 사유로 3회 이상 되돌림 금지
+- 3회 도달 시 근본 원인 해결 필수
+- Manager가 되돌림 패턴 모니터링
+
+---
+
+## 7. 되돌림 기록 형식
+
+### decision.md 기록
+
+```markdown
+## Rollback #[번호]
+
+| 항목 | 값 |
+|------|-----|
+| 일시 | YYYY-MM-DD |
+| Task | TASK-XXX |
+| 유형 | REJECT / FAIL / BLOCK |
+| 원인 | [원인] |
+
+### 상세
+- 문제: [문제 설명]
+- 원인 분석: [원인]
+- 되돌림 대상: [역할]
+- 조치: [조치 내용]
+
+### 재발 방지
+- [방지 조치]
+```
+
+---
+
+## 8. 되돌림 흐름 요약
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                                                                 │
+│  REJECT / FAIL / BLOCK 발생                                     │
+│         ↓                                                       │
+│  원인 분석                                                      │
+│         ↓                                                       │
+│  되돌림 대상 결정                                               │
+│  (Developer / Planner / Architect)                              │
+│         ↓                                                       │
+│  decision.md 기록                                               │
+│         ↓                                                       │
+│  수정 수행                                                      │
+│         ↓                                                       │
+│  재검증 (영향받는 단계부터)                                     │
+│         ↓                                                       │
+│  완료 또는 재되돌림                                             │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```

package/bin/cli.js

@@ -8,8 +8,12 @@ import { validate } from '../src/commands/validate.js';
 import { sessions } from '../src/commands/sessions.js';
 import { logs } from '../src/commands/logs.js';
 import { run } from '../src/commands/run.js';
+import { config } from '../src/commands/config.js';
 import { interactive } from '../src/commands/interactive.js';
+import { upgrade } from '../src/commands/upgrade.js';
+import { monitor } from '../src/commands/monitor.js';
 import sprint from '../src/commands/sprint.js';
+import docs from '../src/commands/docs.js';
 import { createRequire } from 'node:module';
 
 const require = createRequire(import.meta.url);
@@ -17,7 +21,8 @@ const { version } = require('../package.json');
 program
   .name('ada')
   .description('Artifact-Driven AI Agent Framework\nAI가 규칙을 어기지 못하게 하는 문서 기반 개발')
-  .version(version);
+  .version(version)
+  .option('-m, --monitor', 'UI 모드 실행 (인터랙티브 인터페이스)');
 
 // Setup command
 program
@@ -38,6 +43,15 @@ program
   .option('-f, --force', '확인 없이 강제 초기화')
   .action(reset);
 
+// Upgrade command
+program
+  .command('upgrade')
+  .description('작업공간을 최신 버전으로 업그레이드')
+  .option('-f, --force', '확인 없이 강제 업그레이드')
+  .option('--dry-run', '변경 사항 미리보기 (실제 변경 없음)')
+  .option('--rollback', '이전 백업으로 롤백')
+  .action(upgrade);
+
 // Validate command
 program
   .command('validate [doc]')
@@ -49,6 +63,7 @@ program
   .command('sessions')
   .description('AI 실행 세션 목록')
   .option('-w, --watch', '실시간 모니터링 모드')
+  .option('-c, --clean', '완료된 세션 정리')
   .action(sessions);
 
 // Logs command
@@ -63,21 +78,50 @@ program
   .description('스프린트 관리 (create, add, close, list)')
   .action(sprint);
 
+// Docs command
+program
+  .command('docs <action>')
+  .description('문서 관리 (init, generate, publish, serve)')
+  .option('-g, --generator <type>', '문서 생성기 (mkdocs, jekyll)')
+  .action(docs);
+
+// Monitor command (UI 모드)
+program
+  .command('monitor')
+  .alias('m')
+  .description('UI 모드 (인터랙티브 인터페이스)')
+  .action(monitor);
+
+// Config command
+program
+  .command('config [action] [key] [value]')
+  .description('설정 조회/변경 (대화형), show, get <key>, set <key> <value>')
+  .action(config);
+
 // Run command
 program
-  .command('run <role> <tool>')
-  .description('AI 에이전트 실행 (예: run backend claude)')
+  .command('run <role> [tool]')
+  .description('AI 에이전트 실행 (예: run backend [claude])')
   .action(run);
 
 // Parse arguments
 const args = process.argv.slice(2);
 
+// 명령어 목록
+const COMMANDS = ['setup', 'status', 'reset', 'upgrade', 'validate', 'sessions', 'logs', 'run', 'sprint', 'docs', 'config', 'monitor', 'm'];
+
 if (args.length === 0) {
   // 인자 없으면 대화형 모드
   interactive();
-} else if (args.length === 2 && !args[0].startsWith('-') && !['setup', 'status', 'reset', 'validate', 'sessions', 'logs', 'run', 'sprint'].includes(args[0])) {
-  // 두 개의 인자가 명령어가 아니면 role tool로 간주
+} else if (args.includes('-m') || args.includes('--monitor')) {
+  // -m 또는 --monitor 옵션이 있으면 대시보드 실행
+  monitor();
+} else if (args.length === 2 && !args[0].startsWith('-') && !COMMANDS.includes(args[0])) {
+  // 두 개의 인자가 명령어가 아니면 role tool로 간주 (간편 실행)
   run(args[0], args[1]);
+} else if (args.length === 1 && !args[0].startsWith('-') && !COMMANDS.includes(args[0])) {
+  // 인자가 하나면 role로 간주하고 도구는 자동 선택
+  run(args[0]);
 } else {
   program.parse();
 }

package/core/artifacts/sprints/_template/meta.md

@@ -8,11 +8,11 @@
 | 종료 예정 | YYYY-MM-DD (또는 완료일) |
 | 목표 | [스프린트 목표 설명] |
 
-## Task 요약
+## Task 목록
 
-| Task | 상태 | 담당 | 우선순위 | 크기 |
-|------|:----:|------|:--------:|:----:|
-| task-NNN | BACKLOG | - | P0/P1/P2 | S/M/L |
+| Task | 제목 | 상태 | 우선순위 | 크기 |
+|------|------|:----:|:--------:|:----:|
+| task-NNN | [Task 제목] | BACKLOG | P0/P1/P2 | S/M/L |
 
 **상태 범례:**
 - BACKLOG: 스프린트에 할당됨, 작업 미시작

package/core/docs-templates/mkdocs/docs/architecture/overview.md

@@ -0,0 +1,29 @@
+# 아키텍처 개요
+
+## 시스템 아키텍처
+
+[고수준 아키텍처 다이어그램 및 설명]
+
+## 구성 요소
+
+### 구성 요소 1
+**목적:** [설명]
+**책임:**
+- 책임 1
+- 책임 2
+
+### 구성 요소 2
+**목적:** [설명]
+**책임:**
+- 책임 1
+- 책임 2
+
+## 데이터 흐름
+
+```
+사용자 → 프론트엔드 → API → 백엔드 → 데이터베이스
+```
+
+## 기술 스택
+
+자세한 정보는 [기술 스택](tech-stack.md)을 참고하세요.

package/core/docs-templates/mkdocs/docs/changelog.md

@@ -0,0 +1,36 @@
+# 변경 이력
+
+이 프로젝트의 모든 주목할 만한 변경사항이 이 파일에 문서화됩니다.
+
+형식은 [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)를 기반으로 하며,
+이 프로젝트는 [Semantic Versioning](https://semver.org/spec/v2.0.0.html)을 따릅니다.
+
+## [Unreleased]
+
+### Added (추가)
+- 개발 중인 새로운 기능
+
+### Changed (변경)
+- 기존 기능의 변경사항
+
+### Deprecated (중단 예정)
+- 곧 제거될 예정인 기능
+
+### Removed (제거)
+- 제거된 기능
+
+### Fixed (수정)
+- 버그 수정
+
+### Security (보안)
+- 보안 업데이트
+
+## [1.0.0] - YYYY-MM-DD
+
+### Added (추가)
+- 최초 릴리스
+- 기능 1
+- 기능 2
+
+[Unreleased]: https://github.com/username/repo/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/username/repo/releases/tag/v1.0.0