---
name: orchestrate-ptop-harness
description: >-
  ILSOS_PrismaticRD_PTOP 분석 팀의 오케스트레이터. 3명(ptop-lead, ptop-developer,
  build-devops-engineer)을 기동해 3계층 아키텍처·구현 상세·빌드 최적화를 분석하고
  (lead·build는 병렬, developer는 lead 완료 후 순차)
  통합 보고서를 만든다. "PTOP 프로젝트 종합 분석", "PTOP 전체 점검", "PTOP 하네스 시작",
  "PTOP 팀 조율", "PTOP 구조 파악", 그리고 **PTOP 분석에 대한** 후속 표현("PTOP 재분석",
  "PTOP 다시 점검", "아키텍처만 다시", "빌드 분석만 다시", "이전 분석 결과 기반으로") 시 이 스킬을 쓴다.
  구분 — 단일 영역만 필요하면 개별 스킬(analyze-ptop-architecture / analyze-ptop-implementation /
  optimize-ptop-build)을, **산출물 문서**를 만들거나 갱신하는 요청("산출물 업데이트/재생산")은
  ptop-deliverables·ubisam-deliverable-rebuild·ubisam-deliverables를, 코드를 실제로 고치는 작업은
  code_Agent를 쓴다. 맨손 "업데이트"·"다시 실행"만으로는 이 스킬을 고르지 않는다 — 대상을 먼저 확인한다.
---

# Orchestrate PTOP Harness

`ILSOS_PrismaticRD_PTOP`의 **아키텍처 · 구현 · 빌드**를 세 전문가가 병렬 분석해 통합 보고서를 만든다.
이 하네스는 **읽기·분석 전용**이다. 소스 코드를 수정하지 않는다.

## 실행 모드

**서브 에이전트 병렬 + 의존 순차.** 이 환경에는 `TeamCreate`/`TeamDelete` 도구가 **없으므로**
아래 도구로 팀을 구성한다.

| 목적 | 도구 |
|---|---|
| 팀원 기동 | `Agent` — `subagent_type`에 에이전트 이름, `model: "opus"`, 병렬 구간은 `run_in_background: true` |
| 팀원 간 소통 | `SendMessage` — `to`에 에이전트 **이름**, `summary`(5~10단어)는 **필수**, `message`는 본문 |
| 진행 공유 | `_workspace/_progress.md` (진실원) + `TaskCreate`/`TaskUpdate`(가용 시 보조) |
| 산출물 전달 | 파일 — `_workspace/` |

```
[오케스트레이터]
  Phase 1  컨텍스트 확인
  Phase 2  ptop-lead + build-devops-engineer 병렬 기동
  Phase 3  lead 산출 완료 → ptop-developer 기동 (아키텍처 결과 의존)
  Phase 4  결과 수집 · 상충 조정
  Phase 5  통합 보고서 작성
```

## 팀 구성

| 에이전트 | 담당 | 사용 스킬 | 산출 (에이전트 정의와 일치) |
|---|---|---|---|
| `ptop-lead` | 3계층 아키텍처·디바이스 스택·시퀀스 의존성 | `analyze-ptop-architecture` | `01_ptop_architecture.md` |
| `ptop-developer` | 시퀀스 상태머신·타이밍·Rx 체인·에러 처리 | `analyze-ptop-implementation` | `02_ptop_implementation.md`, `03_device_integration.md` |
| `build-devops-engineer` | 멀티 구성 빌드·의존성·CI/CD | `optimize-ptop-build` | `04_build_analysis.md`, `05_cicd_pipeline.yml`, `06_ptop_build_optimization.md` |

모두 `_workspace/` 하위이며 `model: "opus"`로 기동한다. 파일명은 각 에이전트 정의의
`입력/출력 프로토콜` 절이 진실원이며, 바꿀 때는 **에이전트 정의·담당 스킬·이 표를 함께** 고친다.

> **진행 원장은 `_workspace/_progress.md` 파일이다.** `TaskCreate`/`TaskUpdate`는 메인 루프에서는
> 쓸 수 있지만 **서브에이전트 컨텍스트에는 없을 수 있어**, 도구 가용 여부와 무관하게 동작하도록
> 파일을 진실원으로 둔다. 표 형식 → [references/data-protocol.md](references/data-protocol.md)

## Phase 1: 컨텍스트 확인

0. **대상 확인.** 발화에 **PTOP 분석 대상이 명시돼 있지 않으면** 어떤 Phase도 시작하지 말고 되묻는다.
   맨손 "다시 실행"·"업데이트"·"보완"처럼 대상 없는 발화와, "산출물" 같은 타 하네스 어휘가 섞인
   발화가 **각각 독립적으로** 걸린다(둘 다일 필요 없다). 그냥 진행하면 기존 산출물이 이동될 수 있다.
1. `_workspace/`(**저장소 루트 기준.** Ubisam 하네스의 `docs/[Ubisam산출물]/_workspace/`와 다른 곳)의
   **산출물 `01`~`06` 존재 여부**와 **요청 범위** 두 축으로 판별한다(폴더만 보면 오판정한다):
   없음→**`초기`** / 일부+전체요청→**`이어서`** / 특정영역요청→**`부분`** / "처음부터 다시"→**`전면`**

   네 모드의 이름은 **`초기` / `이어서` / `부분` / `전면`** 이며, 이 문자열 그대로 전달한다(§Phase 2).
   **판별 기준·기동 범위·생략의 파급 → [references/mode-rules.md](references/mode-rules.md)**
2. **에이전트 가용성 확인.** `ptop-lead` / `ptop-developer` / `build-devops-engineer`가
   `Agent` 도구의 subagent_type 목록에 있는지 먼저 본다. 없으면 **어떤 Phase도 시작하지 말고**
   "프로젝트 에이전트 미등록 — 세션 재시작 필요"를 사용자에게 보고하고 중단한다.
   `.claude/agents/`에 파일을 새로 추가·이동한 직후에는 **세션이 재시작돼야 등록된다.**
   파일이 있다는 것과 호출 가능하다는 것은 다르다.
3. `docs/architecture.md`로 프로젝트 사실을 확보한다.
4. **승인 게이트.** 아래 **넷을 한 번에** 제시하고 승인받는다 (`rules.md` #2) —
   ① **이동·삭제분**(전면 재실행이면 `_workspace/` → `_workspace_prev/` 이동. 1번에서 스스로
   "되돌리기 어려운 이동"이라 경고한 그 동작이다) ② 덮어쓰기분 ③ 생성분
   ④ **작업공간 관리 파일**(`_workspace/` 폴더 생성, `_progress.md`, 단계별 중간 로그,
   **재사용 산출물의 stale 첫 줄 편집** — §후속 작업의 표기 의무가 기존 파일을 고치므로 승인 대상이다).
   ④를 빼면 에이전트가 자기 작업 로그조차 승인 범위 밖이 되어 쓸 수 없다.
   모드 판별을 승인보다 먼저 하는 이유는, 그러지 않으면 승인 목록이 실제 변경 범위와 어긋나기 때문이다.
   생성분 목록은 —
   통합 산출 `01~06` + `00_PTOP_HARNESS_SUMMARY.md` + **부산출물** `01a~01e`(analyze-ptop-architecture)·
   `04a_dependency_analysis.csv`(optimize-ptop-build) —
   승인을 받은 뒤 Phase 2로 간다 (`rules.md` #2 — 수정은 무조건 승인받기).
5. `_workspace/_progress.md`를 만들고 **에이전트 3인 전원의 행**을 초기화한다. 상태 enum은
   **`진행중`/`완료`/`실패`/`생략` 4종**(정의 → `references/data-protocol.md` §진행 원장).
   **이번 실행에서 기동하지 않는 에이전트는 모드와 무관하게 `생략 — 이전 산출물 재사용`** 으로
   적는다 — `이어서`의 건너뜀도, `부분`에서 지목되지 않은 것도 같다(§Phase 2·3·4가 이 값을 읽는다).
   `TaskCreate`가 가용하면 함께 등록하고 02는 01에 `addBlockedBy`를 건다 — 미지원이면
   **Phase 3의 파일 존재 판정으로 대체**한다(의존성 표현이 없어도 완료 판정은 관측 가능하다).

## Phase 2: 병렬 분석 (lead + build)

`ptop-lead`와 `build-devops-engineer`는 서로 의존이 없다 → `run_in_background: true`로 **동시** 기동.

먼저 `_workspace/`가 없으면 만든다. 각 에이전트에 전달할 것:
- 담당 스킬을 **저장소 루트 기준 절대경로**로 전달한다 — `<REPO>/.claude/skills/<스킬명>/SKILL.md`.
  이름만 주면 서브에이전트가 경로를 스스로 찾아야 한다.
- **산출 파일 경로**와 **진행 원장 `_workspace/_progress.md`** 를 모두 **저장소 루트 기준 절대경로**로 전달 —
  서브에이전트 셸 cwd는 호출마다 초기화되므로 상대경로는 엉뚱한 곳에 떨어진다. 산출물이 유실되면
  Phase 3 완료 판정이 "파일 없음 → 실패"로 오판하고, 원장이 흩어지면 "최대 2회" 상한이 무력화된다.
- "모든 주장에 `파일:라인` 근거를 붙일 것"
- **실행 모드(초기 / 이어서 / 부분 / 전면 — 4종).** 팀원은 이 값을 **기존 산출물을 재사용할지**
  판단에만 쓴다. **`_workspace_prev/` 이동은 오케스트레이터 전담이며 Phase 1에서 이미 끝났다** —
  팀원이 한 번 더 옮기면 병렬로 쓰이던 산출물이 딸려간다.

> **기동 축소 기준은 모드마다 다르다**(원장에 `생략` 을 적는 것은 §Phase 1-5 대로 공통):
> **`이어서`**=담당 산출물이 이미 있으면 / **`부분`**=지목되지 않았으면 / **`초기`·`전면`**=전원 기동.
> ⚠ `부분` 에서 **산출물 유무는 기준이 아니다** — 있다는 이유로 생략하면 재기동 대상이 곧 생략
> 대상이 되어 **아무도 기동되지 않는다**.
>
> **생략한 에이전트는 완료 알림을 보내지 않으므로** `_progress.md`에 `생략 — 이전 산출물 재사용` 으로
> 기록하고 §Phase 3·4의 판정을 바꾼다 → [references/mode-rules.md](references/mode-rules.md)

## Phase 3: 의존 분석 (developer)

`ptop-lead`의 `01_ptop_architecture.md` 완성 후 `ptop-developer`를 기동한다.
구현 분석이 아키텍처가 정의한 계층 경계를 기준으로 이뤄져야 하기 때문이다.
**단 developer 자신이 생략 대상이면 기동하지 않는다 — 아래 "developer 자신을 생략하는 경우"를 먼저 판정한다.**

**완료 판정(관측 가능해야 한다):** 먼저 lead의 **백그라운드 완료 알림을 기다린다.**
알림이 온 뒤 `_workspace/01_ptop_architecture.md`가 존재하고 "불명확 — 확인 필요" 절까지
채워져 있으면 완료로 본다. 알림은 왔는데 파일이 없으면 1회만 재확인하고, 그래도 없으면 실패로 처리한다.
**알림 전에 파일 유무만으로 미완을 단정하지 않는다.**

> **예외 — lead를 생략한 경우**(`§Phase 2` 축소 규칙, `_progress.md`에 `생략` 으로 기록됨).
> 생략된 에이전트는 **알림을 보내지 않는다.** 이때는 알림을 기다리지 말고 `01`의 **파일 존재만으로
> 완료 판정**하고 곧바로 developer를 기동한다. 이 예외가 없으면 오지 않을 알림을 무기한 대기한다.

> **developer 자신을 생략하는 경우.** `이어서` 이고 `02`·`03`이 **둘 다 이미 있으면** developer를
> 기동하지 않는다. `부분` 이면 developer가 **지목됐을 때만** 기동한다("아키텍처만 다시" → 기동 안 함).
> 기동하지 않기로 했으면 `_progress.md`의 developer 행을 `생략 — 이전 산출물 재사용` 으로 적고
> Phase 4로 넘어간다. 이 판단을 하지 않으면 재사용 대상인 `02`·`03`을 덮어쓴다
> (`mode-rules.md` §기동 범위가 이 문장을 수신처로 지목한다).

developer에게도 **Phase 2와 동일한 항목 일체**를 전달한다(담당 스킬 = `analyze-ptop-implementation`, 산출 = `02`·`03`).
**`run_in_background: true` 로 기동한다** — 순차 구간이라 불필요해 보이지만 `SendMessage`의
`to: "main"` 회신은 **백그라운드 전용**이라, 전경으로 띄우면 Phase 4 회신 경로가 막힌다.

**폴백:** lead가 **2회 실패로 확정되면**(지연은 실패가 아니다 — `references/error-handling.md`)
developer를 **소스 직접 참조 모드**로 기동하고 "아키텍처 선행 없이 수행됨"을 보고서에 명시한다.
기동은 **오케스트레이터만** 한다 — `ptop-lead`는 범위 전달만 하고 팀원을 띄우지 않는다.

## Phase 4: 결과 수집 · 상충 조정

**이번 실행에서 기동한** 에이전트의 완료 알림을 받은 뒤 산출 파일 완성을 확인한다
(알림 전 파일 유무로 실패를 단정하지 않는다). 그 다음 `SendMessage`로 핵심 발견 3건씩을 요청한다.

**원장 상태에 따라 3분기다** — `완료`=보낸다 / `실패`=`미검증` / **`생략`=산출물을 직접 읽어 답을 채운다**
(`미검증`이 아니다). 둘을 묶으면 `부분`·`이어서` 실행이 매번 교차 질문을 통째로 잃는다.
**대상 판별·교차 확인 질문 2건 → [references/collection-rules.md](references/collection-rules.md)**

상충하는 답이 나오면 어느 쪽도 지우지 않고 양쪽을 **근거(파일:라인)와 함께 병기**한다.

## Phase 5: 통합 보고서

`_workspace/00_PTOP_HARNESS_SUMMARY.md`를 작성한다.
**필수 섹션 7종·표기 규약·중단 시 선작성 규칙 → [references/summary-template.md](references/summary-template.md)**
(수치 추정 금지, `[추론]` 표기 `rules.md` #15·#16, `미검증·불명확` 절이 모든 누락의 종착지).

**보고 규약** — Phase 전환마다 진행 1줄 보고(`rules.md` #10), 출력 형식은 #11~13(수정 줄=초록
화살표, 단어=주황, 미변경=기본색), 끝에 `docs/harness-ptop.md` 갱신 여부를 묻는다(#6).

## 데이터 전달 · 에러 핸들링

전달 = 파일(`_workspace/`) + `SendMessage`(이름) + `_progress.md`(진행 원장).
상세 → [data-protocol.md](references/data-protocol.md) · [error-handling.md](references/error-handling.md)

**에러 핵심 3가지:**
- 실패 = ①에러 종료 ②산출 파일 미생성 ③빈 파일·헤더만. **지연은 실패가 아니다.**
- 재시도는 같은 `Agent` 재호출이며 `SendMessage` 독촉이 아니다. 횟수는 `_progress.md`에 `시도 N/2` 기록.
- 1회 재시도 후 재실패하면 해당 영역 없이 진행하고 **누락을 `00_PTOP_HARNESS_SUMMARY.md`에 명시**한다.

## 테스트 시나리오

정상 · 에러 · 부분 재실행 · 전원 실패 **4흐름** → [references/test-scenarios.md](references/test-scenarios.md)

## 성공 기준

- [ ] 통합 산출 6건(01~06)이 존재하거나, 없으면 누락 사유가 보고서에 명시됨
      (부산출물 `01a~01e`, `04a_dependency_analysis.csv`는 각 스킬이 만들며 필수는 아님)
- [ ] 모든 발견에 `파일:라인` 근거가 붙어 있음
- [ ] 측정하지 않은 수치가 보고서에 없음
- [ ] 검증 전 서술이 전부 `[추론]`으로 표기됨 (`rules.md` #16)
- [ ] 교차 확인 질문 2건에 답이 기록됨 — 답할 에이전트가 **실패**했으면 `미검증`과 사유로,
      **`생략`(미기동)** 이면 그 산출물을 읽어 `이전 실행 산출물에서 확인(YYYY-MM-DD)` 으로 대체 가능
- [ ] 상충 사항이 양쪽 근거와 함께 병기됨
- [ ] 권장사항이 P0/P1/P2로 분류됨
- [ ] 부분 재실행이면 각 산출 파일과 보고서에 **stale 표기**가 있고, 연쇄 무효화 여부가 기록됨
- [ ] 소스 코드가 수정되지 않음 (분석 전용)

## 후속 작업

- "아키텍처만 다시" → `ptop-lead`만 재기동, 나머지는 기존 `_workspace/` 파일 재사용
- **stale 표기 의무.** 각 산출 파일(`01`~`06`)의 **첫 줄**과 보고서 각 영역 절 머리 **양쪽에**
  `이번 실행에서 갱신됨(YYYY-MM-DD)` / `이전 실행 결과 재사용(YYYY-MM-DD)` 를 적는다(§Phase 1-4 ④ 승인 대상).
  `01`을 갱신하면 의존하는 `02`·`03`은 재사용이 아니라 **정합성 미확인** — 함께 재실행할지 묻고
  거절하면 사유까지 표기한다. 날짜 규칙·문구 3종 → [data-protocol.md](references/data-protocol.md)
- 부분 재실행에서는 `_workspace_prev/`로 옮기지 않는다(전면 재실행일 때만). 갱신 대상 파일만 덮어쓴다.
- 주요 코드 변경 후 영향도 분석 필요 시 전면 재실행 (기존은 `_workspace_prev/`로 보존)