LGES-OC5-PtoP-Welder/.claude/skills/orchestrate-ptop-harness/SKILL.md

name

description

orchestrate-ptop-harness

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

Phase 1: 컨텍스트 확인

0. 대상 확인. 발화에 PTOP 분석 대상이 명시돼 있지 않으면 어떤 Phase도 시작하지 말고 되묻는다. 맨손 "다시 실행"·"업데이트"·"보완"처럼 대상 없는 발화와, "산출물" 같은 타 하네스 어휘가 섞인 발화가 각각 독립적으로 걸린다(둘 다일 필요 없다). 그냥 진행하면 기존 산출물이 이동될 수 있다.

1. _workspace/(저장소 루트 기준. Ubisam 하네스의 docs/[Ubisam산출물]/_workspace/와 다른 곳)의 산출물 01~06 존재 여부와 요청 범위 두 축으로 판별한다(폴더만 보면 오판정한다): 없음→초기 / 일부+전체요청→이어서 / 특정영역요청→부분 / "처음부터 다시"→전면

   네 모드의 이름은 초기 / 이어서 / 부분 / 전면 이며, 이 문자열 그대로 전달한다(§Phase 2). 판별 기준·기동 범위·생략의 파급 → 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

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

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

Phase 5: 통합 보고서

_workspace/00_PTOP_HARNESS_SUMMARY.md를 작성한다. 필수 섹션 7종·표기 규약·중단 시 선작성 규칙 → 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 · error-handling.md

에러 핵심 3가지:

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

테스트 시나리오

정상 · 에러 · 부분 재실행 · 전원 실패 4흐름 → 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
• 부분 재실행에서는 _workspace_prev/로 옮기지 않는다(전면 재실행일 때만). 갱신 대상 파일만 덮어쓴다.
• 주요 코드 변경 후 영향도 분석 필요 시 전면 재실행 (기존은 _workspace_prev/로 보존)