team-level

Donchitos ｜ 遊戲開發 ｜ 原文 ｜ MIT

統籌關卡團隊，從敘事、配置、系統到 QA 規劃完成整個區域

---
name: team-level
description: "統籌關卡團隊（level-designer、narrative-director、world-builder、art-director、systems-designer、qa-tester），完成整個區域的製作。"
argument-hint: "[level name or area to design] [--review full|lean|solo]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Edit, Agent, AskUserQuestion, TaskCreate, TaskGet, TaskList, TaskUpdate, Bash(bash "*/.claude/skills/team-level/../../hooks/yaml-helper.sh" resolve_config *)
model: sonnet
---

# Team Level

如果沒有帶參數，就輸出使用說明並結束，不要 spawn 任何 agent，也不要讀任何設計文件：
> 用法：`/team-level [level name or area to design] [--review full|lean|solo]` — 指定要設計的關卡或區域（例如 `forest temple`、`tutorial village`、`final boss arena`）。這裡不要用 `AskUserQuestion`，直接輸出說明。

呼叫這個 skill 時：

**決策點：** 每個步驟轉換時，用 `AskUserQuestion` 把 subagent 的提案做成可選項目給使用者選。先在對話中寫出 agent 的完整分析，再用簡短的標籤收下決定。
在 `collaborative` 模式下，使用者核准後才能進下一步。
在 `guided` 模式下，pipeline 會自動往下走，除非某個步驟 BLOCKED；
在 `autonomous` 模式下會從頭跑到尾，每個步驟的結果用 `log_decision` 記錄下來。
屬於 `automation_always_ask` 類別的決策（`is_always_ask_category` helper）不管什麼模式一律要問。參見 `.claude/docs/automation-modes.md`。

## Phase 0: Resolve Config

!`bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys review_mode,automation,team.size`

上面已經解析好了，直接用；`--review` 會覆蓋 `review_mode`。沒有這個區塊的話，就用 `.claude/docs/config-resolution.md` 裡的預設值。

`review_mode` 決定 director gate 的深度，而這條 pipeline 沒有 director gate：
下面任何 phase 在任何 `review_mode` 下，都不會 spawn CD-、TD-、PR- 或 AD-PHASE-GATE。它的 phase gate 就是 pipeline 自己的決策點（定義在下面的 `team.size` 底下），在這些點上工作的 agent 是團隊成員，不是 director gate。

`automation` 決定上面「決策點」那段的行為。各模式如何改變 pipeline 的行為，見上面的決策點說明和 `.claude/docs/automation-modes.md`。

**`team.size`**：哪些 agent 啟用（跟 review_mode 的 gate 深度和 workflow docs 互相獨立）。
- **`individual`**（預設）：只有 `level-designer`。其他 agent 透過 level-designer 諮詢，不會另外 spawn。
- **`small`**：加上 `systems-designer` + `art-director` + `qa-tester`。
- **`studio`**：再加上 `narrative-director` + `world-builder` + `accessibility-specialist`（也就是文件中寫的完整 pipeline）。
在 `individual` 下需要用到的非核心 agent，會改由最接近的核心 agent 處理，並附一則說明。**「Phase gate」指的是這條 pipeline 自己列出、以 `AskUserQuestion` 決策點收尾的任何 phase**：可能是上面「決策點」底下的某個轉換，也可能是下面 pipeline 裡寫明的 **Gate** 步驟，**不管 `automation` 是哪個模式都一樣。** `guided` 和 `autonomous` 改變的是 gate 怎麼通過（自動往下走，或用 `log_decision` 記錄），不是它算不算 gate，所以下面的有界例外條件 (3) 在每個模式下的 gate 都成立。被限制成「只在 phase gate 出場」的 agent，只會在這些時點 spawn，其他時候不會。這個「依啟用名單縮小範圍」的規則適用於下面整條 pipeline：任何 phase 只要點名了啟用名單以外的 agent，就改由最接近的核心 agent 處理，不 spawn 它。

**在 Step 1 之前先公布啟用名單，絕對不准讓縮減悄悄發生。**
spawn 任何東西之前，先用一行講清楚這次實際會 spawn 哪些 agent，以及下面 pipeline 有點名、但在目前 `team.size` 下**不會** spawn 的有哪些。例如：

> `Active set (team.size: <resolved>): <the agents listed for that size above>.`
> `Not spawned this run: <every other agent this pipeline names> — consulted`
> `through <nearest active core agent>. Raise team.size (or modes.rigor) to widen.`

內容要直接從上面的 `team.size` 清單和這個檔案自己的 pipeline 所點名的 agent 填，不要照抄範例。每個 orchestrator 這兩組名單都不一樣。

下面這條 pipeline 看起來像多 agent 的 fan-out，但在預設值下其實只有一兩個 agent：`team-release` 點名了十個、只跑一個，`team-narrative` 在五個 phase 裡點名了六個、只跑 `writer` 一個。**這樣縮減是對的**：`team.size` 是以嚴謹度為前提的，預設收窄就是用來省 token 的。
如果不明講，讀的人就分不出「正確縮減過的 run」和「壞掉的 pipeline」，而上面那條「由最接近的核心 agent 處理並附說明」的規則是在路由當下才觸發，從來不會交代整個 run 的樣子。

這跟這個檔案其他地方的「略過的檢查要回報」是同一條規則：**一個有被執行、卻從沒被講出來的限制，對讀輸出的人來說，跟從來沒執行過的限制看起來一模一樣。**

1. **讀取參數**，取得目標關卡或區域（例如 `tutorial`、
   `forest dungeon`、`hub town`、`final boss arena`）。

2. **蒐集 context**（每份設計文件都要分段讀：用 Grep 工具以 content mode 搜尋 pattern `^#` 找出需要的標題，再用 offset 和 limit 讀那些範圍）：
   - 如果 `design/gdd/game-concept.md` 存在就讀它，或讀 `design/game-brief.md`（在 `rigor: minimal` 時取代它的一頁式 brief），兩者有一個存在就讀
   - 讀 `design/gdd/game-pillars.md` 的遊戲支柱
   - 讀 `design/levels/` 裡現有的關卡文件
   - 讀 `design/narrative/` 裡相關的敘事文件
   - 讀該區域所屬地區／陣營的世界觀文件

## How to Delegate

用 `Agent` 工具把每個團隊成員 spawn 成 subagent：
- `subagent_type: narrative-director` — 敘事目的、角色、情緒弧線
- `subagent_type: world-builder` — 背景設定脈絡、環境敘事、世界規則
- `subagent_type: level-designer` — 空間配置、節奏、遭遇戰、導航
- `subagent_type: systems-designer` — 敵人編組、掉落表、難度平衡
- `subagent_type: art-director` — 視覺主題、色盤、光照、資產需求
- `subagent_type: accessibility-specialist` — 導航清晰度、色盲友善、認知負荷
- `subagent_type: qa-tester` — 測試案例、邊界測試、試玩檢查表

**給每個 agent 的 brief 要精簡，不要整包 context 倒過去。** 共用的輸入只讀**一次**，再把整理過的 brief 直接寫在 prompt 裡：只放每個 agent 真正需要的那幾行，你已經讀過的文件絕對不要只丟檔案路徑（agent 拿到路徑會把整份檔案重讀一遍）。只有你還沒讀、而且只有那個 agent 需要的文件，才給路徑。

**每個 agent 的 prompt 結尾都要加上回傳約定：**「Write your full output to `[path]` — that named path is your write authorisation under the bounded exception below, so write it without a separate approval prompt. Return **only** (1) the path written, (2) a ≤5-bullet summary of decisions, (3) any BLOCKED/CONCERNS items, one line each. Do not restate the documents you read.」沒有這個約定的話，agent 會把它讀過的東西全部倒回這個 session。

**`[path]` 要換成真實路徑。** 工作中的產出放在
`production/levels/[level-name]/` 底下，slug 的規則跟下面「Save to」步驟一樣。每個 agent 一個檔案，這樣平行的步驟就不會共用同一個檔：

| Step / agent | Writes to |
|---|---|
| 1 narrative-director | `production/levels/[level-name]/narrative.md` |
| 1 world-builder | `production/levels/[level-name]/lore.md` |
| 1 art-director | `production/levels/[level-name]/visual-direction.md` |
| 2 level-designer | `production/levels/[level-name]/layout.md` |
| 3 systems-designer | `production/levels/[level-name]/systems.md` |
| 4 art-director | `production/levels/[level-name]/production-concepts.md` |
| 4 accessibility-specialist | `production/levels/[level-name]/accessibility.md` |
| 5 qa-tester | `production/qa/test-cases/[level-name]-cases.md` — test cases, edge cases, playtest checklist, acceptance criteria |

這些是工作草稿；真正留存的紀錄，是你用它們彙整出來的關卡設計文件（`design/levels/[level-name].md`）。

> **為什麼這不違反 Collaboration Protocol。** `CLAUDE.md` 要求 agent 在 Write/Edit 之前先問「May I write this to [filepath]?」。這裡 spawn 出來的 subagent **不問**就寫，這是刻意設計的有界例外，不是疏忽，跟 `consistency-check` 附加寫入 `active.md` 是同一個決定。這個例外只在三個條件**同時**成立時才有效：(1) 路徑是**你**在 prompt 裡指定的，所以使用者核准這個 phase 的時候，就等於核准了目的地；(2) 它是 `production/`、`docs/` 或 `tests/` 底下的新產物，絕對不是改既有的原始碼或設定；(3) 產生它的那個 phase，本身在 pipeline 往下走之前有 `AskUserQuestion` 把關。這三條以外，agent 一定要先問。**不要靠「每個 subagent 都問一次」來「修」這件事**：每個 agent 每個 phase 都跳一次提示，會讓 orchestrator 根本沒辦法用，這就是這個例外存在的原因。

3. **依序統籌關卡設計團隊**：

### Step 1: Narrative + Visual Direction (narrative-director + world-builder + art-director, parallel)

同時 spawn 三個 agent：三個 `Agent` 呼叫都發出去之後，才去等任何結果。

Spawn `narrative-director` agent 來：
- 定義這個區域的敘事目的（這裡會發生哪些劇情節拍？）
- 找出關鍵角色、對白觸發點和背景設定元素
- 指定情緒弧線（玩家進入時、過程中、離開時應該有什麼感受？）

Spawn `world-builder` agent 來：
- 提供該區域的背景設定脈絡（歷史、陣營存在感、生態）
- 定義環境敘事的機會
- 指定任何會影響這個區域遊戲玩法的世界規則

Spawn `art-director` agent 來：
- 為這個區域建立視覺主題目標，這些是配置的 INPUT，不是配置的產出
- 定義這個區域的色溫與光照氛圍（跟相鄰區域有什麼不同？）
- 指定造型語言的方向（稜角分明的要塞？有機的洞穴？衰敗的壯麗？）
- 點名會讓玩家定位方向的主要視覺地標
- 如果 `design/art/art-bible.md` 存在就讀它，所有方向都要以既有的 art bible 為準。要分段讀：先用 Grep 工具（pattern `^#`，content mode）找出需要的標題，再用 offset 和 limit 讀那些範圍。

**art-director 在 Step 1 給出的視覺目標，必須在 Step 2 當成明確的限制條件傳給 level-designer。** 配置決策要在視覺方向的範圍內做，不能先於它。

**Gate**：用 `AskUserQuestion` 呈現 Step 1 的三份產出（敘事 brief、背景設定基礎、視覺方向目標），確認後再進 Step 2。

### Step 2: Layout and Encounter Design (level-designer)
Spawn `level-designer` agent，並把 Step 1 的完整產出當 context 交給它：
- 敘事 brief（來自 narrative-director）
- 背景設定基礎（來自 world-builder）
- **視覺方向目標（來自 art-director）**：配置必須在這些目標的範圍內運作，不能跟它們矛盾

level-designer 要：
- 設計空間配置（主線路徑、選擇性路徑、隱藏要素），確保主要路線跟 Step 1 的視覺地標目標一致
- 定義節奏曲線（緊張高峰、休息區、探索區），跟 narrative-director 的情緒弧線互相協調
- 安排難度漸進的遭遇戰
- 設計環境謎題或導航挑戰
- 定義供尋路用的興趣點與地標，這些必須跟 art-director 指定的視覺地標吻合
- 指定出入口，以及跟相鄰區域的連接

**相鄰區域依賴檢查**：配置產出之後，針對 level-designer 提到的每個相鄰區域，去 `design/levels/` 檢查。如果任何被提到的區域沒有對應的 `.md` 檔，就把這個缺口揭露出來：
> "Level references [area-name] as an adjacent area but `design/levels/[area-name].md` does not exist."

用 `AskUserQuestion` 提供選項：
- (a) 用佔位的參照繼續：在關卡文件裡把這個連接標成 UNRESOLVED，並列在摘要報告的未解跨關卡依賴章節
- (b) 先暫停，執行 `/team-level [area-name]` 把那個區域建立起來

絕對不准替缺漏的相鄰區域編造內容。

**Gate**：用 `AskUserQuestion` 呈現 Step 2 的配置（包含任何未解決的相鄰區域依賴），確認後再進 Step 3。

### Step 3: Systems Integration (systems-designer)
Spawn `systems-designer` agent 來：
- 指定敵人編組與遭遇戰公式
- 定義掉落表與獎勵擺放
- 依預期的玩家等級／裝備來平衡難度
- 設計任何該區域專屬的機制或環境危害
- 指定資源分布（補血道具、存檔點、商店）

**Gate**：用 `AskUserQuestion` 呈現 Step 3 的產出，確認後再進 Step 4。

### Step 4: Production Concepts + Accessibility (art-director + accessibility-specialist, parallel)

**注意**：art-director 的方向性那一輪（視覺主題、色彩目標、氛圍）在 Step 1 已經做過了。這一輪是針對特定地點的製作概念：配置定案後，每個具體空間長什麼樣子？

Spawn `art-director` agent，並把 Step 2 定案的配置交給它：
- 為關鍵空間（入口、關鍵遭遇區、地標、出口）產出特定地點的概念規格
- 指定哪些美術資產是這個區域獨有的，哪些是從全域共用池拿來用的
- 為每個關鍵空間定義視線與光照設置（這些現在是依配置而定，不再是方向性的）
- 指定專屬於這個區域配置的 VFX 需求（天氣體積、粒子、大氣效果）
- 標出任何配置跟 Step 1 目標產生視覺方向衝突的地點，把它們當成製作風險揭露出來

同時平行 spawn `accessibility-specialist` agent 來：
- 檢視關卡配置的導航清晰度（玩家不只靠顏色也能辨認方位嗎？）
- 確認主線路徑的指標除了顏色，也有用形狀／圖示／聲音提示
- 檢視任何謎題機制的認知負荷，凡是需要同時記住超過 3 個狀態的都要標出來
- 確認關鍵遊戲區域對色盲玩家有足夠的對比
- 輸出：附嚴重程度（BLOCKING / RECOMMENDED / NICE TO HAVE）的無障礙問題清單

等兩個 agent 都回來再往下走。

**Gate**：用 `AskUserQuestion` 呈現 Step 4 的兩份結果。如果 accessibility-specialist 回傳了任何 BLOCKING 的問題，要醒目地標出來，並提供：
- (a) 回頭請 level-designer 和 art-director 重新設計被標出的元素，再進 Step 5
- (b) 記為已知的無障礙缺口，帶著這個問題明確記錄在最終報告裡，繼續進 Step 5

使用者沒有確認任何 BLOCKING 的無障礙問題之前，絕對不准進 Step 5。

### Step 5: QA Planning (qa-tester)
Spawn `qa-tester` agent 來：
- 為主線路徑撰寫測試案例
- 找出邊界與邊緣案例（順序跳過、軟鎖死）
- 為這個區域建立試玩檢查表
- 定義關卡完成的驗收標準

4. **彙整關卡設計文件**，把所有團隊成員的產出合併成關卡設計模板的格式。

orchestrator 已經握有每個 sub-agent 的產出：**自己彙整文件，不要再 spawn 一次 `level-designer`、把所有產出原封不動重送過去。** 第二次 spawn 要付一個全新 agent 的開銷，外加把 orchestrator 手上已有的 context 完整重傳一遍，只為了搬運它本來就握著的文字。彙整成關卡設計模板格式之後，直接用 `AskUserQuestion` 問使用者：「May I write the compiled level design to
`design/levels/[level-name].md`?」核准後再寫。

5. 該次核准之後，**儲存到** `design/levels/[level-name].md`。
   `[level-name]` 是參數轉成的 slug：全小寫、空格換成連字號
   （`forest dungeon` → `forest-dungeon.md`），相鄰區域檢查裡的 `[area-name]` 也用同樣的方式轉 slug。

6. **輸出摘要**，包含：區域概述、遭遇戰數量、預估資產清單、敘事節拍、任何跨團隊依賴或待解問題、未解的跨關卡依賴（被提到但還沒設計的相鄰區域，每個都標成 UNRESOLVED），以及無障礙問題與它們的處理狀態。

## File Write Protocol

每個 agent 的產出（敘事文件、測試檢查表）由產出它們的 sub-agent 自己寫，依據的是上面「為什麼這不違反 Collaboration Protocol」所記載的**有界例外**：路徑是你指定的、產物是 `production/`、`docs/` 或 `tests/` 底下的新檔案、而且這個 phase 有 `AskUserQuestion` 把關。在這些範圍內，sub-agent **不會**每次寫入都問；範圍之外就一定要問。**唯一的例外是最後彙整出來的關卡設計文件**：orchestrator 已經握有所有輸入，所以它自己彙整，並在自己的「May I write …?」提示之後（Step 4）親自寫那個檔案，光為了寫 orchestrator 手上已有的文字就重新 spawn 一個 agent，純粹是浪費。

Verdict: **COMPLETE** — level design document produced and all team outputs compiled.
Verdict: **BLOCKED** — one or more agents blocked, or an agent was skipped (`.claude/docs/error-recovery-protocol.md` step 5); partial report produced with unresolved items listed.

## Next Steps

- 跑 `/design-review design/levels/[level-name].md` 驗證完成的關卡設計文件。
- 設計核准後，跑 `/dev-story` 來實作關卡內容。
- 跑 `/qa-plan` 為這個關卡產生 QA 測試計畫。

## Error Recovery Protocol

**先驗證產物。** 如果回傳約定指定了路徑，在把這個 phase 當成做完之前，先確認該路徑真的存在：**指名的產物不在磁碟上，就是失敗的 phase，不管回覆讀起來多流暢。** agent 可能耗掉整個 phase，回你一段看似合理的開場白，卻什麼都沒寫；這既不是 BLOCKED、也不是錯誤、也不是「無法完成」，所以下面的觸發條件永遠不會被觸發。要叫它繼續，並指明沒達成的約定；context 通常還在。

如果任何 spawn 出去的 agent 回傳 BLOCKED、出錯或無法完成：**立刻揭露，不要越過它所阻擋的依賴項繼續往下走，而且一定要產出部分報告。** 被略過的 agent 那一節要留成一個有名字的缺口，絕對不准用你自己的內容填進去。完整流程：`.claude/docs/error-recovery-protocol.md`。

常見的阻擋原因：
- 輸入檔案缺失（找不到 story、GDD 不存在）→ 導向建立它的 skill
- ADR 狀態是 Proposed → 不要實作；決定之後，用 `/architecture-decision accept ADR-NNNN` 接受它
- 範圍太大 → 用 `/create-stories` 拆成兩個 story
- ADR 和 story 的指示互相衝突 → 把衝突揭露出來，不要猜

---
name: team-level
description: "Orchestrate the level team — level-designer, narrative-director, world-builder, art-director, systems-designer, qa-tester — for complete area creation."
argument-hint: "[level name or area to design] [--review full|lean|solo]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Edit, Agent, AskUserQuestion, TaskCreate, TaskGet, TaskList, TaskUpdate, Bash(bash "*/.claude/skills/team-level/../../hooks/yaml-helper.sh" resolve_config *)
model: sonnet
---

# Team Level

If no argument is provided, output usage guidance and exit without spawning any agents or reading any design files:
> Usage: `/team-level [level name or area to design] [--review full|lean|solo]` — specify the level or area to design (e.g., `forest temple`, `tutorial village`, `final boss arena`). Do not use `AskUserQuestion` here; output the guidance directly.

When this skill is invoked:

**Decision Points:** At each step transition, use `AskUserQuestion` to present
the user with the subagent's proposals as selectable options. Write the agent's
full analysis in conversation, then capture the decision with concise labels.
In `collaborative` mode, the user must approve before moving to the next step.
In `guided` mode the pipeline advances automatically unless a step is BLOCKED;
in `autonomous` mode it runs end to end, recording each step outcome via
`log_decision`. Decisions in `automation_always_ask` categories
(`is_always_ask_category` helper) always prompt regardless of mode. See
`.claude/docs/automation-modes.md`.

## Phase 0: Resolve Config

!`bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys review_mode,automation,team.size`

Resolved above — use as-is; `--review` overrides `review_mode`. No block →
defaults in `.claude/docs/config-resolution.md`.

`review_mode` sets director-gate depth, and this pipeline has no director gate:
no phase below spawns CD-, TD-, PR- or AD-PHASE-GATE, at any `review_mode`. Its
phase gates are the pipeline's own decision points (defined under `team.size`
below), and the agents that work at them are team members, not director gates.

`automation` drives the Decision Points note above. See the Decision Points note above and
`.claude/docs/automation-modes.md` for how each mode changes pipeline behavior.

**`team.size`**: which agents are active (orthogonal to review_mode gate-depth and workflow docs).
- **`individual`** (default): `level-designer` only. Other agents consulted via the level-designer, not spawned separately.
- **`small`**: + `systems-designer` + `art-director` + `qa-tester`.
- **`studio`**: + `narrative-director` + `world-builder` + `accessibility-specialist` (the full pipeline as documented).
A non-core agent needed at `individual` routes through the nearest active core agent with an informational note. **"Phase gate" means any phase that ends in an `AskUserQuestion` decision point this pipeline itself lists** — a transition under Decision Points above, or a **Gate** step written into the pipeline below — **whatever the `automation` mode.** `guided` and `autonomous` change how a gate is passed (it auto-advances, or is recorded with `log_decision`), not whether it is one, so bounded-exception condition (3) below holds at it in every mode. An agent restricted to "phase gates only" is spawned at those points and no others. This active-set scoping applies throughout the pipeline below: any phase that names an agent outside the active set routes through the nearest core agent rather than spawning it.

**Announce the active set before Step 1 — never let the collapse be silent.**
Before spawning anything, state in one line which agents this run will actually
spawn, and which the pipeline below names but will **not** spawn at the resolved
`team.size`. For example:

> `Active set (team.size: <resolved>): <the agents listed for that size above>.`
> `Not spawned this run: <every other agent this pipeline names> — consulted`
> `through <nearest active core agent>. Raise team.size (or modes.rigor) to widen.`

Fill it from the `team.size` list directly above and the agents this file's own
pipeline names — not from an example. Both sets differ per orchestrator.

The pipeline below reads as a multi-agent fan-out and at the shipped default it
is one or two agents — `team-release` names ten and runs one, `team-narrative`
names six across five phases and runs `writer` alone. **The collapse is correct**:
`team.size` is rigor-fronted and the narrow default is the token lever.
Without saying so, a reader cannot
distinguish a correctly-collapsed run from a broken pipeline, and the per-agent
"routes through the nearest core agent with an informational note" rule above
fires at routing time and never states the shape of the run as a whole.

This is the same rule as the skipped-check reporting elsewhere in this file: **a constraint that is enforced but never surfaced is
indistinguishable, to the person reading the output, from one that was never
enforced.**

1. **Read the argument** for the target level or area (e.g., `tutorial`,
   `forest dungeon`, `hub town`, `final boss arena`).

2. **Gather context** (read each design doc by section: find the headings you need
   with the Grep tool with pattern `^#` in content mode, and Read those ranges
   with offset and limit):
   - Read the game concept at `design/gdd/game-concept.md` — or `design/game-brief.md`,
     the one-page brief that replaces it at `rigor: minimal` — if either exists
   - Read game pillars at `design/gdd/game-pillars.md`
   - Read existing level docs in `design/levels/`
   - Read relevant narrative docs in `design/narrative/`
   - Read world-building docs for the area's region/faction

## How to Delegate

Use the `Agent` tool to spawn each team member as a subagent:
- `subagent_type: narrative-director` — Narrative purpose, characters, emotional arc
- `subagent_type: world-builder` — Lore context, environmental storytelling, world rules
- `subagent_type: level-designer` — Spatial layout, pacing, encounters, navigation
- `subagent_type: systems-designer` — Enemy compositions, loot tables, difficulty balance
- `subagent_type: art-director` — Visual theme, color palette, lighting, asset requirements
- `subagent_type: accessibility-specialist` — Navigation clarity, colorblind safety, cognitive load
- `subagent_type: qa-tester` — Test cases, boundary testing, playtest checklist

**Brief each agent — do not dump context.** Read the shared inputs **once** and pass a distilled brief inline: the lines each agent actually needs, never a file path for a document you have already read (an agent handed a path re-reads the whole file). Pass a path only for a document you have not read and only that agent needs.

**End every agent prompt with a return contract:** "Write your full output to `[path]` — that named path is your write authorisation under the bounded exception below, so write it without a separate approval prompt. Return **only** (1) the path written, (2) a ≤5-bullet summary of decisions, (3) any BLOCKED/CONCERNS items, one line each. Do not restate the documents you read." Without it, an agent returns everything it read back into this session.

**Substitute a real path for `[path]`.** Working artifacts go under
`production/levels/[level-name]/`, slugged as in the "Save to" step below. One
file per agent, so the parallel steps never share one:

| Step / agent | Writes to |
|---|---|
| 1 narrative-director | `production/levels/[level-name]/narrative.md` |
| 1 world-builder | `production/levels/[level-name]/lore.md` |
| 1 art-director | `production/levels/[level-name]/visual-direction.md` |
| 2 level-designer | `production/levels/[level-name]/layout.md` |
| 3 systems-designer | `production/levels/[level-name]/systems.md` |
| 4 art-director | `production/levels/[level-name]/production-concepts.md` |
| 4 accessibility-specialist | `production/levels/[level-name]/accessibility.md` |
| 5 qa-tester | `production/qa/test-cases/[level-name]-cases.md` — test cases, edge cases, playtest checklist, acceptance criteria |

These are working drafts; the durable record is the level design document you
compile from them (`design/levels/[level-name].md`).

> **Why this does not violate the Collaboration Protocol.** `CLAUDE.md` requires an agent to ask "May I write this to [filepath]?" before Write/Edit. A subagent spawned here writes **without** asking, and that is a deliberate, bounded exception rather than an oversight — the same call already made for `consistency-check` appending to `active.md`. The exception holds only when all three are true: (1) the path is one **you** named in the prompt, so the user approved the destination when they approved the phase; (2) it is a new artifact under `production/`, `docs/` or `tests/`, never an edit to existing source or config; (3) the phase that produced it is itself gated by an `AskUserQuestion` before the pipeline advances. Outside those three, the agent must ask. **Do not "fix" this by asking per subagent** — a prompt per agent per phase makes an orchestrator unusable, which is why the exception exists.

3. **Orchestrate the level design team** in sequence:

### Step 1: Narrative + Visual Direction (narrative-director + world-builder + art-director, parallel)

Spawn all three agents simultaneously — issue all three `Agent` calls before waiting for any result.

Spawn the `narrative-director` agent to:
- Define the narrative purpose of this area (what story beats happen here?)
- Identify key characters, dialogue triggers, and lore elements
- Specify emotional arc (how should the player feel entering, during, leaving?)

Spawn the `world-builder` agent to:
- Provide lore context for the area (history, faction presence, ecology)
- Define environmental storytelling opportunities
- Specify any world rules that affect gameplay in this area

Spawn the `art-director` agent to:
- Establish visual theme targets for this area — these are INPUTS to layout, not outputs of it
- Define the color temperature and lighting mood for this area (how does it differ from adjacent areas?)
- Specify shape language direction (angular fortress? organic cave? decayed grandeur?)
- Name the primary visual landmarks that will orient the player
- Read `design/art/art-bible.md` if it exists — anchor all direction in the established art bible. Read it by section: find the headings you need with the Grep tool (pattern `^#`, content mode) and Read those ranges with offset and limit.

**The art-director's visual targets from Step 1 must be passed to the level-designer in Step 2** as explicit constraints. Layout decisions happen within the visual direction, not before it.

**Gate**: Use `AskUserQuestion` to present all three Step 1 outputs (narrative brief, lore foundation, visual direction targets) and confirm before proceeding to Step 2.

### Step 2: Layout and Encounter Design (level-designer)
Spawn the `level-designer` agent with the full Step 1 output as context:
- Narrative brief (from narrative-director)
- Lore foundation (from world-builder)
- **Visual direction targets (from art-director)** — layout must work within these targets, not contradict them

The level-designer should:
- Design the spatial layout (critical path, optional paths, secrets) — ensuring primary routes align with the visual landmark targets from Step 1
- Define pacing curve (tension peaks, rest areas, exploration zones) — coordinated with the emotional arc from narrative-director
- Place encounters with difficulty progression
- Design environmental puzzles or navigation challenges
- Define points of interest and landmarks for wayfinding — these must match the visual landmarks the art-director specified
- Specify entry/exit points and connections to adjacent areas

**Adjacent area dependency check**: After the layout is produced, check `design/levels/` for each adjacent area referenced by the level-designer. If any referenced area's `.md` file does not exist, surface the gap:
> "Level references [area-name] as an adjacent area but `design/levels/[area-name].md` does not exist."

Use `AskUserQuestion` with options:
- (a) Proceed with a placeholder reference — mark the connection as UNRESOLVED in the level doc and list it in the open cross-level dependencies section of the summary report
- (b) Pause and run `/team-level [area-name]` first to establish that area

Do NOT invent content for the missing adjacent area.

**Gate**: Use `AskUserQuestion` to present Step 2 layout (including any unresolved adjacent area dependencies) and confirm before proceeding to Step 3.

### Step 3: Systems Integration (systems-designer)
Spawn the `systems-designer` agent to:
- Specify enemy compositions and encounter formulas
- Define loot tables and reward placement
- Balance difficulty relative to expected player level/gear
- Design any area-specific mechanics or environmental hazards
- Specify resource distribution (health pickups, save points, shops)

**Gate**: Use `AskUserQuestion` to present Step 3 outputs and confirm before proceeding to Step 4.

### Step 4: Production Concepts + Accessibility (art-director + accessibility-specialist, parallel)

**Note**: The art-director's directional pass (visual theme, color targets, mood) happened in Step 1. This pass is location-specific production concepts — given the finalized layout, what does each specific space look like?

Spawn the `art-director` agent with the finalized layout from Step 2:
- Produce location-specific concept specs for key spaces (entrance, key encounter zones, landmarks, exits)
- Specify which art assets are unique to this area vs. shared from the global pool
- Define sight-line and lighting setups per key space (these are now layout-informed, not directional)
- Specify VFX needs that are specific to this area's layout (weather volumes, particles, atmospheric effects)
- Flag any locations where the layout creates visual direction conflicts with the Step 1 targets — surface these as production risks

Spawn the `accessibility-specialist` agent in parallel to:
- Review the level layout for navigation clarity (can players orient themselves without relying on color alone?)
- Check that critical path signposting uses shape/icon/sound cues in addition to color
- Review any puzzle mechanics for cognitive load — flag anything that requires holding more than 3 simultaneous states
- Check that key gameplay areas have sufficient contrast for colorblind players
- Output: accessibility concerns list with severity (BLOCKING / RECOMMENDED / NICE TO HAVE)

Wait for both agents to return before proceeding.

**Gate**: Use `AskUserQuestion` to present both Step 4 results. If the accessibility-specialist returned any BLOCKING concerns, highlight them prominently and offer:
- (a) Return to level-designer and art-director to redesign the flagged elements before Step 5
- (b) Document as a known accessibility gap and proceed to Step 5 with the concern explicitly logged in the final report

Do NOT proceed to Step 5 without the user acknowledging any BLOCKING accessibility concerns.

### Step 5: QA Planning (qa-tester)
Spawn the `qa-tester` agent to:
- Write test cases for the critical path
- Identify boundary and edge cases (sequence breaks, softlocks)
- Create a playtest checklist for the area
- Define acceptance criteria for level completion

4. **Compile the level design document** combining all team outputs into the
   level design template format.

The orchestrator already holds every sub-agent's output — **compile the document
itself; do not re-spawn `level-designer` and re-send all outputs verbatim.** That
second spawn pays a fresh agent's overhead plus a full re-transmission of context
the orchestrator already has, to move text it is already holding. After compiling
into the level-design template format, ask the user directly via
`AskUserQuestion`: "May I write the compiled level design to
`design/levels/[level-name].md`?" On approval, write it.

5. **Save to** `design/levels/[level-name].md` after that approval.
   `[level-name]` is the argument as a slug — lowercase, spaces → hyphens
   (`forest dungeon` → `forest-dungeon.md`) — and `[area-name]` in the adjacent
   area check is slugged the same way.

6. **Output a summary** with: area overview, encounter count, estimated asset
   list, narrative beats, any cross-team dependencies or open questions, open
   cross-level dependencies (adjacent areas referenced but not yet designed, each
   marked UNRESOLVED), and accessibility concerns with their resolution status.

## File Write Protocol

Per-agent artifacts (narrative docs, test checklists) are written by the
sub-agent that produced them, under the **bounded exception** documented above
under "Why this does not violate the Collaboration Protocol" — the path is one
you named, the artifact is new under `production/`, `docs/` or `tests/`, and the
phase is gated by an `AskUserQuestion`. A sub-agent does **not** prompt per write
inside those bounds; outside them it must ask. The **one exception is the final
compiled level-design document**: the
orchestrator already holds every input, so it compiles and writes that file
itself after its own "May I write …?" prompt (Step 4) — re-spawning an agent
just to write text the orchestrator is already holding is pure overhead.

Verdict: **COMPLETE** — level design document produced and all team outputs compiled.
Verdict: **BLOCKED** — one or more agents blocked, or an agent was skipped (`.claude/docs/error-recovery-protocol.md` step 5); partial report produced with unresolved items listed.

## Next Steps

- Run `/design-review design/levels/[level-name].md` to validate the completed level design doc.
- Run `/dev-story` to implement level content once the design is approved.
- Run `/qa-plan` to generate a QA test plan for this level.

## Error Recovery Protocol

**First, verify the artifact.** If the return contract named a path, check the
path exists before treating the phase as done — **a named artifact that is not
on disk is a failed phase, however fluent the response reads.** An agent can
burn a full phase and return a plausible preamble having written nothing, which
is neither BLOCKED nor an error nor "cannot complete", so the trigger below
never fires. Resume it naming the unmet contract; the context is
usually still there.

If any spawned agent returns BLOCKED, errors, or cannot complete: **surface it
immediately, don't proceed past a dependency it blocks, and always produce a
partial report.** A skipped agent's section stays a named gap — never fill it with content of your own. Full procedure: `.claude/docs/error-recovery-protocol.md`.

Common blockers:
- Input file missing (story not found, GDD absent) → redirect to the skill that creates it
- ADR status is Proposed → do not implement; once it is decided, accept it with `/architecture-decision accept ADR-NNNN`
- Scope too large → split into two stories via `/create-stories`
- Conflicting instructions between ADR and story → surface the conflict, do not guess