# Task Delegation Types (작업 위임 타입) Design Specification

이 문서는 `multi-agent-mux-delegate-job` 스킬에 **작업 위임 타입 (Task Delegation Types)**을 정의하고, 단일 에이전트 실행을 넘어 에이전트 협업 구조(루프, 토론 등)를 체계적으로 오케스트레이션하기 위한 설계 명세입니다.

---

## 1. 개요 및 필요성

기존의 잡 위임 시스템은 단일 에이전트에 지시사항(Prompt)을 전달하고 완료(`completed`) 또는 에러(`error`) 이벤트를 수신하면 작업을 종료하는 **단방향 직접 위임(Direct)** 구조였습니다.

하지만 실제 협업 환경에서는 다음과 같은 유형의 고도화된 협업 흐름이 필요합니다:
1. **자료조사 및 토론 (Research & Discussion)**: 계획 수립 또는 개념 검토를 위해 여러 에이전트가 협의에 이를 때까지 논의를 주고받음.
2. **작업자-리뷰어 루프 (Worker-Reviewer Loop)**: 작업자(Worker)가 코드를 수정하면, 리뷰어(Reviewer)가 검토하여 `PASS`를 줄 때까지 피드백 반영 및 수정을 반복함.

이러한 협업 워크플로우를 개별 에이전트의 내부 코드 수정 없이 **오케스트레이터(위임 스크립트) 레이어에서 제어**할 수 있도록 작업 타입을 도입합니다.

---

## 2. 작업 위임 타입 정의

| 타입명 (`--type`) | 설명 | 워크플로우 흐름 |
|------------------|------|----------------|
| `direct` (기본값) | 단일 에이전트에 대한 직접 위임 | 지시 → 에이전트 수행 → 완료/에러 수신 후 종료 |
| `loop` | 작업자-리뷰어 피드백 루프 | 작업자 실행 → 완료 시 리뷰어 자동 호출 → 리뷰 통과 시 종료, 실패 시 피드백과 함께 작업자 재호출 (반복) |
| `discuss` | 자료조사 및 상호 토론 | 에이전트 A(초안 작성) → 에이전트 B(검토 및 의견 제시) → 에이전트 A(반영 및 수정) → 합의 도달 시 종료 |

---

## 3. CLI 명세 확장

`multi-agent-mux-delegate-job submit` 명령어에 다음 옵션들이 추가됩니다.

```bash
multi-agent-mux-delegate-job submit \
  --prompt <text> \
  --agent <worker_agent> \
  --agent-session <worker_session> \
  [--type <direct|loop|discuss>] \
  [--reviewer <reviewer_agent>] \
  [--reviewer-session <reviewer_session>] \
  [--max-iterations <count>] \
  [--validate <script>]
```

### 신규 옵션 상세:
*   `--type`: 작업 위임 타입을 지정합니다. (`direct`, `loop`, `discuss`)
*   `--reviewer`: 리뷰를 담당할 에이전트 이름입니다 (기본값: `hermes`).
*   `--reviewer-session`: 리뷰어 에이전트가 돌고 있는 herdr 세션 이름입니다 (기본값: `herdr:hermes`).
*   `--max-iterations`: 루프 또는 토론의 최대 반복 횟수입니다 (기본값: `5`).

---

## 4. 작업자-리뷰어 루프 (`loop`) 상태 머신

오케스트레이터는 다음 상태 다이어그램에 따라 작업을 순차적으로 위임하고 이벤트를 구독합니다.

```mermaid
stateDiagram-v2
    [*] --> Worker_Pending : Submit Job
    Worker_Pending --> Worker_Running : Worker picks job
    Worker_Running --> Reviewer_Pending : Worker emits "completed"
    Worker_Running --> Error_Terminal : Worker emits "error"
    
    Reviewer_Pending --> Reviewer_Running : Reviewer picks job
    Reviewer_Running --> Success_Terminal : Reviewer emits "completed" (PASS)
    Reviewer_Running --> Worker_Pending : Reviewer emits "error" / "completed" (Feedback) / Increment Iteration
    Reviewer_Running --> Error_Terminal : Reviewer emits "error" & Iteration > Max
    
    Success_Terminal --> [*]
    Error_Terminal --> [*]
```

### 단계별 상세 동작 프로토콜:

1.  **작업자(Worker) 실행**:
    *   오케스트레이터는 작업을 `pending`으로 등록하고, `agent_session`을 작업자 세션(예: `herdr:claude`)으로 설정하여 전달합니다.
    *   작업자가 수행을 완료하고 `completed` 이벤트를 발행하면 오케스트레이터가 이를 가로챕니다.
2.  **리뷰어(Reviewer)로 스위칭**:
    *   오케스트레이터는 전체 작업을 종료하지 않고, 작업 레코드의 `agent_session`을 리뷰어 세션(예: `herdr:hermes`)으로 변경합니다.
    *   리뷰어에게 전달할 프롬프트를 자동으로 조립합니다:
        > *"Review the changes/artifacts generated for job $JOB_ID. Check if they meet the requirements. If correct, publish completed event with 'PASS'. If there are issues, publish error event with detailed feedback/nits."*
    *   상태를 다시 `pending`으로 리셋하여 리뷰어 세션이 잡을 집어갈 수 있도록 합니다.
3.  **리뷰 결과 판정**:
    *   **PASS인 경우**: 리뷰어가 `completed` 이벤트와 함께 `"PASS"` 메시지를 주면 잡이 최종 `completed` 처리되며 오케스트레이터가 종료됩니다.
    *   **피드백 발생 시**: 리뷰어가 `error` 또는 일반 `completed`와 함께 피드백 내용을 발행하면, 오케스트레이터는 반복 횟수(`iteration`)를 1 증가시킵니다.
        *   최대 반복 횟수(`max-iterations`)를 초과한 경우 최종 `error` 종료됩니다.
        *   그렇지 않다면, 다시 `agent_session`을 작업자 세션으로 돌리고 프롬프트를 조립하여 `pending` 상태로 돌려보냅니다:
            > *"The reviewer provided the following feedback for job $JOB_ID: <리뷰어 피드백>. Please modify the code/artifacts to address these comments."*

---

## 5. 토론 및 협의 (`discuss`) 상태 머신

토론 타입은 작업자와 리뷰어가 동등한 관계(예: PM/기획 에이전트와 설계 에이전트)에서 상호 계획안을 다듬어 나가는 구조입니다.

1.  **초안 작성 (PM/Researcher)**:
    *   PM 세션에 최초 프롬프트를 보냅니다. PM은 요구사항 분석 및 초안을 파일(예: `draft_plan.md`)로 작성하고 `completed`를 발행합니다.
2.  **의견 검토 (Designer/Developer)**:
    *   작업을 설계자 세션으로 전환하고 다음 프롬프트를 줍니다:
        > *"Read draft_plan.md. Review its technical feasibility. Write your feedback/objections to draft_plan.md or comments.md. If you agree with the plan, reply with 'AGREE'."*
3.  **합의 도달 여부 검토**:
    *   상대방이 `"AGREE"`를 보내면 토론 합의가 성립되어 최종 완료됩니다.
    *   반대 의견이 있으면 PM 세션으로 다시 넘겨 계획을 개정하도록 유도합니다.

---

## 6. 구현 계획

1.  **`registry.py` 확장**:
    *   `job_type` (기본값 `"direct"`), `reviewer`, `reviewer_session`, `max_iterations`, `iteration` 필드를 잡 레코드 모델에 추가합니다.
    *   `register_job` 함수와 CLI 파서에 신규 매개변수를 등록합니다.
2.  **`multi-agent-mux-delegate-job` 래퍼 스크립트 수정**:
    *   `cmd_submit`에서 위임 타입(`--type`)을 받아 루프를 도는 셸 스크립트 상태 기계를 작성합니다.
    *   각 에피소드가 끝날 때마다 상태를 변경하여 작업자/리뷰어 간에 소유권을 주고받도록 구현합니다.
3.  **검증**:
    *   가상의 worker/reviewer 시나리오를 만들거나 claude/hermes 세션에서 직접 상호 검증 루프를 돌려 정상 수렴하는지 테스트합니다.
