fix: correct Agent Teams API usage in harness/zio-harness skills

The skills (and the harness orchestrator templates) invoked TeamCreate with an inline members[] array and TaskCreate with a tasks[] array plus assignee/depends_on — none of which match the real experimental Agent Teams API. Rewrite to the documented flow: - TeamCreate creates an empty team (team_name only) - teammates are spawned via the Agent tool (team_name + name + subagent_type) - tasks are created one-per-call (subject/description); ownership via TaskUpdate.owner, dependencies via TaskUpdate.blockedBy - zio-harness now uses custom agent/bot subagent types instead of general-purpose, and the orchestrator is the team lead (not a spawned member) - add shutdown_request + TeamDelete cleanup and note the CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 requirement Bump harness 1.3.0 -> 1.3.1, zio-harness 1.0.0 -> 1.0.1. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-17 17:27:39 +09:00 · 2026-06-17 17:27:39 +09:00 · 01d82a46f6
commit 01d82a46f6
parent cc46c4528e
7 changed files with 87 additions and 68 deletions
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@ -10,13 +10,13 @@
      "name": "harness",
      "source": "./",
      "description": "에이전트 팀 & 스킬 아키텍트. 도메인/프로젝트에 맞는 하네스를 구성하고, 전문 에이전트를 정의하며, 에이전트가 사용할 스킬을 생성하는 메타 스킬.",
-      "version": "1.3.0"
+      "version": "1.3.1"
    },
    {
      "name": "zio-harness",
      "source": "./plugins/zio-harness",
      "description": "React + Spring Boot + Mobile App 풀스택 개발 하네스. orchestrator·analyst·bot·agent 에이전트 팀이 기능 개발·테스트·배포를 파이프라인으로 처리. PROJECT_MAP.md로 폴더 구조를 세션 간 기억.",
-      "version": "1.0.0"
+      "version": "1.0.1"
    }
  ]
 }
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@ -1,7 +1,7 @@
 {
  "name": "harness",
  "description": "The team-architecture factory for Claude Code — a meta-skill that turns a domain description into an agent team and the skills they use, with six pre-defined team-architecture patterns (Pipeline, Fan-out/Fan-in, Expert Pool, Producer-Reviewer, Supervisor, Hierarchical Delegation). Claude Code용 팀 아키텍처 팩토리: 도메인 한 문장을 에이전트 팀과 스킬 세트로 변환하는 메타 스킬.",
-  "version": "1.3.0",
+  "version": "1.3.1",
  "author": {
    "name": "ythong",
    "url": "https://git.zioinfo.co.kr/ythong"
--- a/plugins/zio-harness/.claude-plugin/plugin.json
+++ b/plugins/zio-harness/.claude-plugin/plugin.json
@ -1,7 +1,7 @@
 {
  "name": "zio-harness",
  "description": "React + Spring Boot + Mobile App 풀스택 개발 하네스. orchestrator·analyst·bot·agent 에이전트 팀이 기능 개발·테스트·배포를 파이프라인으로 처리. PROJECT_MAP.md로 폴더 구조를 세션 간 기억.",
-  "version": "1.0.0",
+  "version": "1.0.1",
  "author": {
    "name": "ythong",
    "url": "https://git.zioinfo.co.kr/ythong"
--- a/plugins/zio-harness/skills/zio-harness/SKILL.md
+++ b/plugins/zio-harness/skills/zio-harness/SKILL.md
@ -66,50 +66,61 @@ _workspace/ 존재 여부 확인

 ### Phase 2: 팀 구성

+> **요구사항:** 팀 도구(`TeamCreate`/`SendMessage`/`TaskCreate`)는 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` 플래그가 켜진 세션에서만 사용 가능하다.
+
+`TeamCreate`는 **빈 팀**을 만든다(`members` 인자 없음). 팀원은 `Agent` 도구로 `team_name`·`name`·`subagent_type`을 지정해 spawn한다. 오케스트레이터(이 스킬 세션)가 곧 팀 리더이며, 별도 팀원으로 만들지 않는다.
+
+1) 빈 팀 생성:
+
 ```
-TeamCreate(
-  team_name: "zio-dev-team",
-  members: [
-    { name: "analyst", agent_type: "analyst", model: "opus",
-      prompt: "PROJECT_MAP.md를 읽고 요청 분석 후 _workspace/00_analysis.md 작성. 구현 계획과 영향 파일 목록 포함." },
-    { name: "agent", agent_type: "general-purpose", model: "opus",
-      prompt: "analyst의 계획을 읽고 코드 구현. React/Spring Boot/Mobile 스택에 맞는 컨벤션 준수." },
-    { name: "bot", agent_type: "general-purpose", model: "opus",
-      prompt: "구현 완료 후 테스트 실행, 린트, 빌드 검증. 결과를 _workspace/02_bot_report.md에 기록." }
-  ]
-)
+TeamCreate(team_name: "zio-dev-team", description: "React+Spring Boot+Mobile 풀스택 개발")
+```
+
+2) 팀원 spawn (커스텀 에이전트 타입 analyst/agent/bot 사용):
+
+```
+Agent(subagent_type: "analyst", team_name: "zio-dev-team", name: "analyst",
+      prompt: "PROJECT_MAP.md를 읽고 요청 분석 후 _workspace/00_analysis.md 작성. 구현 계획과 영향 파일 목록 포함.")
+Agent(subagent_type: "agent",   team_name: "zio-dev-team", name: "agent",
+      prompt: "analyst의 계획을 읽고 코드 구현. React/Spring Boot/Mobile 스택에 맞는 컨벤션 준수.")
+Agent(subagent_type: "bot",     team_name: "zio-dev-team", name: "bot",
+      prompt: "구현 완료 후 테스트 실행·린트·빌드 검증. 결과를 _workspace/02_bot_report.md에 기록.")
 ```

 작업 유형별 팀 조정:
- **Analysis/DocMap**: analyst만 실행 (팀 불필요)
- **Test**: bot만 실행
+- **Analysis/DocMap**: analyst만 spawn (팀 불필요)
+- **Test**: bot만 spawn
 - **Feature/Bug**: 전체 팀 파이프라인

 ### Phase 3: 작업 등록 및 실행

+태스크는 **한 번에 하나씩** 생성한다(`subject`/`description`). 소유자는 `TaskUpdate`의 `owner`로, 의존성은 `blockedBy`로 지정한다:
+
 ```
-TaskCreate(tasks: [
-  { title: "프로젝트 분석 및 구현 계획 수립", assignee: "analyst",
-    description: "PROJECT_MAP.md 기반으로 영향 범위 파악. _workspace/00_analysis.md 작성." },
-  { title: "코드 구현", assignee: "agent",
-    description: "_workspace/00_analysis.md 읽고 해당 스택 컨벤션으로 구현.",
-    depends_on: ["프로젝트 분석 및 구현 계획 수립"] },
-  { title: "테스트 및 검증", assignee: "bot",
-    description: "구현 코드 테스트 실행. _workspace/02_bot_report.md 작성.",
-    depends_on: ["코드 구현"] }
-])
+t1 = TaskCreate(subject: "프로젝트 분석 및 구현 계획 수립",
+                description: "PROJECT_MAP.md 기반으로 영향 범위 파악. _workspace/00_analysis.md 작성.")
+TaskUpdate(task: t1, owner: "analyst")
+
+t2 = TaskCreate(subject: "코드 구현",
+                description: "_workspace/00_analysis.md 읽고 해당 스택 컨벤션으로 구현.")
+TaskUpdate(task: t2, owner: "agent", blockedBy: [t1])
+
+t3 = TaskCreate(subject: "테스트 및 검증",
+                description: "구현 코드 테스트 실행. _workspace/02_bot_report.md 작성.")
+TaskUpdate(task: t3, owner: "bot", blockedBy: [t2])
 ```

-팀원 간 통신 프로토콜:
- analyst → agent: `SendMessage` ("분석 완료. `_workspace/00_analysis.md` 참조. 구현 시작.")
- agent → bot: `SendMessage` ("구현 완료. 테스트 실행 요청.")
- bot → orchestrator: `SendMessage` ("검증 완료. `_workspace/02_bot_report.md` 참조.")
+팀원 간 통신 프로토콜 — `SendMessage`는 `{to, summary, message}` 형식이며, 작업 완료는 `TaskUpdate`로 `completed` 처리하면 리더에게 자동 통지된다:
+- analyst → agent: `SendMessage(to: "agent", summary: "분석 완료", message: "_workspace/00_analysis.md 참조. 구현 시작.")`
+- agent → bot: `SendMessage(to: "bot", summary: "구현 완료", message: "테스트 실행 요청.")`
+- 각 팀원: 작업 끝나면 `TaskUpdate(task, status: "completed")` → 리더(오케스트레이터)가 태스크 완료 알림과 `_workspace/` 파일로 진행 파악 (별도 보고 메시지 불필요)

 ### Phase 4: 결과 종합 및 PROJECT_MAP 업데이트

-1. `_workspace/02_bot_report.md` 확인 — 실패 항목 있으면 agent에 재작업 지시
+1. `_workspace/02_bot_report.md` 확인 — 실패 항목 있으면 agent에 재작업 지시(`SendMessage`)
 2. 새 파일·폴더가 생성된 경우 `PROJECT_MAP.md` 업데이트 (`references/folder-map.md` 참조)
 3. 변경 사항 요약을 사용자에게 보고
+4. 모든 작업 완료 후 팀원 종료(`SendMessage(to, message: {type: "shutdown_request"})`) → `TeamDelete`로 팀·태스크 정리

 ---

--- a/skills/harness/SKILL.md
+++ b/skills/harness/SKILL.md
@ -189,15 +189,16 @@ Phase 2-1에서 선택한 실행 모드에 따라 오케스트레이터 패턴
 #### 5-0. 오케스트레이터 패턴 (모드별)

 **에이전트 팀 패턴 (기본):**
-오케스트레이터가 `TeamCreate`로 팀을 구성하고, `TaskCreate`로 작업을 할당한다. 팀원들은 `SendMessage`로 직접 통신하며 자체 조율한다. 리더(오케스트레이터)는 진행 상황을 모니터링하고 결과를 종합한다.
+오케스트레이터가 `TeamCreate`로 **빈 팀**을 만들고(`members` 인자 없음), `Agent` 도구로 `team_name`·`name`·`subagent_type`을 지정해 팀원을 spawn한다. 작업은 `TaskCreate`(개별 `subject`)로 만들고 `TaskUpdate`의 `owner`로 할당, `blockedBy`로 의존성을 건다. 팀원들은 `SendMessage`로 직접 통신하며 자체 조율한다. 리더(오케스트레이터)는 진행 상황을 모니터링하고 결과를 종합한다. (팀 도구는 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` 필요.)

 ```
 [오케스트레이터/리더]
-    ├── TeamCreate(team_name, members)
-    ├── TaskCreate(tasks with dependencies)
+    ├── TeamCreate(team_name)                         # 빈 팀 생성
+    ├── Agent(subagent_type, team_name, name) ×N      # 팀원 spawn
+    ├── TaskCreate(subject) + TaskUpdate(owner, blockedBy)  # 작업 생성·할당·의존성
    ├── 팀원들이 자체 조율 (SendMessage)
    ├── 결과 수집 및 종합
-    └── 팀 정리
+    └── SendMessage(shutdown_request) → TeamDelete    # 팀 정리
 ```

 **서브 에이전트 패턴 (대안):**
--- a/skills/harness/references/orchestrator-template.md
+++ b/skills/harness/references/orchestrator-template.md
@ -54,29 +54,37 @@ description: "{도메인} 에이전트 팀을 조율하는 오케스트레이터

 ### Phase 2: 팀 구성

-1. 팀 생성:
+   > **요구사항:** 팀 도구는 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` 세션에서만 사용 가능.
+
+1. 빈 팀 생성 (`TeamCreate`는 `members` 인자를 받지 않음):
   ```
-   TeamCreate(
-     team_name: "{domain}-team",
-     members: [
-       { name: "{teammate-1}", agent_type: "{type}", model: "opus", prompt: "{역할 설명 및 작업 지시}" },
-       { name: "{teammate-2}", agent_type: "{type}", model: "opus", prompt: "{역할 설명 및 작업 지시}" },
-       ...
-     ]
-   )
+   TeamCreate(team_name: "{domain}-team", description: "{팀 목적}")
   ```

-2. 작업 등록:
+2. 팀원 spawn (`Agent` 도구에 `team_name`·`name`·`subagent_type` 지정):
   ```
-   TaskCreate(tasks: [
-     { title: "{작업1}", description: "{상세}", assignee: "{teammate-1}" },
-     { title: "{작업2}", description: "{상세}", assignee: "{teammate-2}" },
-     { title: "{작업3}", description: "{상세}", depends_on: ["{작업1}"] },
-     ...
-   ])
+   Agent(subagent_type: "{type}", team_name: "{domain}-team", name: "{teammate-1}",
+         prompt: "{역할 설명 및 작업 지시}")
+   Agent(subagent_type: "{type}", team_name: "{domain}-team", name: "{teammate-2}",
+         prompt: "{역할 설명 및 작업 지시}")
+   ...
+   ```
+   > 오케스트레이터 자신이 팀 리더이므로 팀원으로 spawn하지 않는다.
+
+3. 작업 등록 — **한 번에 하나씩** 생성하고, 소유자는 `TaskUpdate.owner`, 의존성은 `TaskUpdate.blockedBy`로 지정:
+   ```
+   t1 = TaskCreate(subject: "{작업1}", description: "{상세}")
+   TaskUpdate(task: t1, owner: "{teammate-1}")
+
+   t2 = TaskCreate(subject: "{작업2}", description: "{상세}")
+   TaskUpdate(task: t2, owner: "{teammate-2}")
+
+   t3 = TaskCreate(subject: "{작업3}", description: "{상세}")
+   TaskUpdate(task: t3, owner: "{teammate-1}", blockedBy: [t1])
+   ...
   ```

-   > 팀원당 5~6개 작업이 적정. 의존성이 있는 작업은 `depends_on`으로 명시.
+   > 팀원당 5~6개 작업이 적정. 의존성은 `TaskUpdate`의 `blockedBy`로 명시.

 ### Phase 3: {주요 작업 — 예: 조사/생성/분석}

--- a/skills/harness/references/team-examples.md
+++ b/skills/harness/references/team-examples.md
@ -36,18 +36,16 @@ Phase 1: 준비
  - _workspace/ 생성

 Phase 2: 팀 구성
-  - TeamCreate(team_name: "research-team", members: [
-      { name: "official", prompt: "공식 채널 조사..." },
-      { name: "media", prompt: "미디어/투자 동향 조사..." },
-      { name: "community", prompt: "커뮤니티 반응 조사..." },
-      { name: "background", prompt: "배경/경쟁 환경 조사..." }
-    ])
-  - TaskCreate(tasks: [
-      { title: "공식 채널 조사", assignee: "official" },
-      { title: "미디어 동향 조사", assignee: "media" },
-      { title: "커뮤니티 반응 조사", assignee: "community" },
-      { title: "배경 환경 조사", assignee: "background" }
-    ])
+  - TeamCreate(team_name: "research-team", description: "다각도 리서치")   # 빈 팀
+  - Agent(subagent_type: "Explore", team_name: "research-team", name: "official",   prompt: "공식 채널 조사...")
+    Agent(subagent_type: "Explore", team_name: "research-team", name: "media",      prompt: "미디어/투자 동향 조사...")
+    Agent(subagent_type: "Explore", team_name: "research-team", name: "community",  prompt: "커뮤니티 반응 조사...")
+    Agent(subagent_type: "Explore", team_name: "research-team", name: "background", prompt: "배경/경쟁 환경 조사...")
+  - 작업은 하나씩 생성 후 owner로 할당:
+      t = TaskCreate(subject: "공식 채널 조사");   TaskUpdate(task: t, owner: "official")
+      t = TaskCreate(subject: "미디어 동향 조사"); TaskUpdate(task: t, owner: "media")
+      t = TaskCreate(subject: "커뮤니티 반응 조사"); TaskUpdate(task: t, owner: "community")
+      t = TaskCreate(subject: "배경 환경 조사");   TaskUpdate(task: t, owner: "background")

 Phase 3: 조사 수행
  - 4명의 팀원이 독립적으로 조사
@ -151,8 +149,9 @@ description: "SF 소설의 세계관을 구축하는 전문가. 물리 법칙,
 ### 팀 워크플로우 상세

 ```
-Phase 1: TeamCreate(team_name: "novel-team", members: [worldbuilder, character-designer, plot-architect])
-         TaskCreate([세계관 구축, 캐릭터 설계, 플롯 구조])
+Phase 1: TeamCreate(team_name: "novel-team")   # 빈 팀
+         → Agent로 worldbuilder/character-designer/plot-architect spawn (team_name·name·subagent_type)
+         → 작업을 하나씩 TaskCreate(subject) + TaskUpdate(owner)로 등록 (세계관 구축/캐릭터 설계/플롯 구조)
         → 팀원들이 자체 조율하며 병렬 작업
         → worldbuilder가 사회 구조 완성 시 character-designer에게 SendMessage
         → character-designer가 주인공 설정 시 plot-architect에게 SendMessage
@ -161,7 +160,7 @@ Phase 2: Phase 1 팀 정리 → prose-stylist를 서브 에이전트로 호출 (
         prose-stylist가 _workspace/의 3개 산출물을 Read하여 집필
         → 결과를 _workspace/02_prose_draft.md에 저장

-Phase 3: 새 팀 생성 — TeamCreate(team_name: "review-team", members: [science-consultant, continuity-manager])
+Phase 3: 새 팀 생성 — TeamCreate(team_name: "review-team") → Agent로 science-consultant·continuity-manager spawn
         (세션당 한 팀만 활성이지만, Phase 1 팀을 정리했으므로 새 팀 생성 가능)
         → 두 리뷰어가 draft를 검토, 서로 발견을 공유
         → science-consultant가 물리 오류 발견 시 continuity-manager에게도 알림