@playcraft/cli 0.0.41 → 0.0.42
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/commands/tools-generation.js +2 -4
- package/dist/commands/tools-utils.js +19 -0
- package/dist/utils/version-checker.js +8 -11
- package/package.json +3 -3
- package/project-template/.claude/agents/designer.md +12 -8
- package/project-template/.claude/agents/developer.md +53 -62
- package/project-template/.claude/agents/refs/README.md +21 -15
- package/project-template/.claude/agents/refs/designer-deliverable-spec.md +24 -0
- package/project-template/.claude/agents/refs/designer-master-composite-recipes.md +20 -28
- package/project-template/.claude/agents/refs/developer-phase1-flow.md +81 -156
- package/project-template/.claude/agents/refs/pm-workflow-detail.md +6 -0
- package/project-template/.claude/agents/refs/reviewer-convergence-eval.md +130 -0
- package/project-template/.claude/agents/refs/reviewer-six-dimension-eval.md +4 -284
- package/project-template/.claude/agents/refs/ta-atlas-deliverable-standard.md +27 -6
- package/project-template/.claude/agents/refs/ta-pipeline-cookbook.md +433 -24
- package/project-template/.claude/agents/reviewer.md +62 -38
- package/project-template/.claude/agents/technical-artist.md +36 -25
- package/project-template/.claude/hooks/README.md +9 -1
- package/project-template/.claude/hooks/validate-workflow-stop.mjs +86 -1
- package/project-template/.claude/settings.json +4 -0
- package/project-template/.claude/skills/playcraft-image-generation/SKILL.md +65 -15
- package/project-template/.claude/skills/playcraft-storyboard/SKILL.md +26 -7
- package/project-template/.claude/skills/playcraft-workflow/SKILL.md +104 -15
- package/project-template/.claude/skills/playwright-cli/SKILL.md +390 -0
- package/project-template/.claude/skills/playwright-cli/references/element-attributes.md +23 -0
- package/project-template/.claude/skills/playwright-cli/references/playwright-tests.md +39 -0
- package/project-template/.claude/skills/playwright-cli/references/request-mocking.md +87 -0
- package/project-template/.claude/skills/playwright-cli/references/running-code.md +240 -0
- package/project-template/.claude/skills/playwright-cli/references/session-management.md +226 -0
- package/project-template/.claude/skills/playwright-cli/references/spec-driven-testing.md +312 -0
- package/project-template/.claude/skills/playwright-cli/references/storage-state.md +275 -0
- package/project-template/.claude/skills/playwright-cli/references/test-generation.md +138 -0
- package/project-template/.claude/skills/playwright-cli/references/tracing.md +142 -0
- package/project-template/.claude/skills/playwright-cli/references/video-recording.md +157 -0
- package/project-template/.cursor/rules/playcraft-orchestrator.mdc +74 -24
- package/project-template/.cursor/rules/playcraft-subagent-boundary.mdc +1 -1
- package/project-template/CLAUDE.md +99 -59
- package/project-template/docs/team/agent-conduct.md +42 -26
- package/project-template/docs/team/atom-plan-format.md +33 -2
- package/project-template/docs/team/collaboration.md +57 -48
- package/project-template/docs/team/workflow-changelog.md +28 -14
- package/project-template/docs/team/workflow-consistency-checklist.md +12 -0
- package/project-template/templates/atom-plan.template.md +35 -3
- package/project-template/templates/designer-log.template.md +16 -0
- package/project-template/templates/developer-log.template.md +95 -101
- package/project-template/templates/layout-spec.template.md +14 -0
- package/project-template/templates/project-state.template.md +51 -33
- package/project-template/templates/review-report.template.md +76 -151
- package/project-template/templates/ta-log.template.md +138 -0
|
@@ -19,27 +19,28 @@ It hooks the player in 3 seconds, delivers a compressed gameplay experience, the
|
|
|
19
19
|
**Always read `docs/project-state.md` first.** Parse **`## Agent handoff`** (YAML) before any orchestration or sub-agent work. It tracks:
|
|
20
20
|
|
|
21
21
|
- Current stage and active agent(s)
|
|
22
|
-
- Gates (#1, #2a, #2b, #3), `selectedMcOption`, `
|
|
22
|
+
- Gates (#1, #2a, #2b, #3), `selectedMcOption`, `uiReworkRound`
|
|
23
23
|
- Handoff: `subagent_stop`, `gate_pending`, `next_orchestrator_action`
|
|
24
24
|
- Completed checkpoints (resume from here, not from scratch)
|
|
25
25
|
- File index pointing to all design docs and assets
|
|
26
|
-
- Production Pipeline serial waves (Designer Ph.2 → TA → Developer in `
|
|
26
|
+
- Production Pipeline serial waves (Designer Ph.2 → TA → Developer in `ui_pass` / `gameplay_pass`)
|
|
27
27
|
|
|
28
28
|
## Stage Model
|
|
29
29
|
|
|
30
30
|
```
|
|
31
|
-
pm → style_exploration → production →
|
|
31
|
+
pm → style_exploration → production → ui_pass → ui_review ⇄ ui_rework → gameplay_pass → done
|
|
32
32
|
```
|
|
33
33
|
|
|
34
|
-
| Stage | Active Agent(s) | Completion
|
|
35
|
-
| ------------------- | ------------------------------------- |
|
|
36
|
-
| `pm` | PM | Gate #1 passed
|
|
37
|
-
| `style_exploration` | Designer Phase 1 | Gate #2b passed (MC + ASR
|
|
38
|
-
| `production` | Designer Ph.2 → **TA** (serial waves) | Production Pipeline Wave 1 + Wave 2 both `done`
|
|
39
|
-
| `
|
|
40
|
-
| `
|
|
41
|
-
| `
|
|
42
|
-
| `
|
|
34
|
+
| Stage | Active Agent(s) | Completion |
|
|
35
|
+
| ------------------- | ------------------------------------- | ------------------------------------------------------------------------- |
|
|
36
|
+
| `pm` | PM | Gate #1 passed (after Reviewer `design_check`) |
|
|
37
|
+
| `style_exploration` | Designer Phase 1 | Gate #2b passed (MC + ASR; after Reviewer `design_check`) |
|
|
38
|
+
| `production` | Designer Ph.2 → **TA** (serial waves) | Production Pipeline Wave 1 + Wave 2 both `done` |
|
|
39
|
+
| `ui_pass` | **Developer** (UI shell only) | `devStatus: ui_ready` + devUrl; light logic only (no core gameplay rules) |
|
|
40
|
+
| `ui_review` | Reviewer (`ui_diff`) | Browser screenshots vs MC panels pass (or max 5 `ui_rework` rounds) |
|
|
41
|
+
| `ui_rework` | Developer (+ TA/Designer on demand) | Fixes per UI Diff Report → re-enter `ui_review` |
|
|
42
|
+
| `gameplay_pass` | **Developer** (core gameplay) | `devStatus: ready` + devUrl; Reviewer `load_check` → Gate #3 |
|
|
43
|
+
| `done` | — | Gate #3 passed (user accepts at devUrl) |
|
|
43
44
|
|
|
44
45
|
## Agent Team
|
|
45
46
|
|
|
@@ -51,7 +52,7 @@ pm → style_exploration → production → integration → review ⇄ rework
|
|
|
51
52
|
| **Designer** | 1) Gate #2 visual+narrative (MC = Developer UI spec) 2) TA-ready handoff 3) Audio + digit strip | `@designer` — style exploration, audio |
|
|
52
53
|
| **Technical Artist** | 1) Style-faithful mass production 2) 100% assetMapping 3) Production-grade assets for Developer | `@technical-artist` — asset pipeline |
|
|
53
54
|
| **Developer** | 1) Dev UI matches MC 2) Dev gameplay matches PM 3) Dev preview owner — **final owner of devUrl** | `@developer` — integrate, `npm run dev` self-check |
|
|
54
|
-
| **Reviewer** | 1)
|
|
55
|
+
| **Reviewer** | 1) `design_check` before Gates 2) `ui_diff` (screenshots vs MC) 3) `load_check` before Gate #3 | `@reviewer` — design / UI / load convergence |
|
|
55
56
|
|
|
56
57
|
### PM is the project owner
|
|
57
58
|
|
|
@@ -61,10 +62,10 @@ PM is accountable for **intent and contracts** (Layout Spec + Atom Plan, degrada
|
|
|
61
62
|
|
|
62
63
|
Full protocol: [docs/team/collaboration.md § Gate Protocol](docs/team/collaboration.md#gate-protocol-orchestrator-only).
|
|
63
64
|
|
|
64
|
-
1. **Gate #1 (Direction)** — PM prepares four docs → **you** `AskUserQuestion` → user confirms gameplay + style direction
|
|
65
|
-
2. **Gate #2a (MC selection)** — Designer produces MC options → **you** `AskUserQuestion` → set `selectedMcOption`
|
|
66
|
-
3. **Gate #2b (MC + ASR final)** — Designer produces ASR sheets (UI + element) + docs → **you** `AskUserQuestion` → then `stage: production`
|
|
67
|
-
4. **Gate #3 (Dev delivery)** — Reviewer
|
|
65
|
+
1. **Gate #1 (Direction)** — PM prepares four docs → **Reviewer `design_check`** → **you** `AskUserQuestion` → user confirms gameplay + style direction
|
|
66
|
+
2. **Gate #2a (MC selection)** — Designer produces MC options → **you** `AskUserQuestion` → set `selectedMcOption` (no Reviewer pre-check)
|
|
67
|
+
3. **Gate #2b (MC + ASR final)** — Designer produces ASR sheets (UI + element) + docs → **Reviewer `design_check`** → **you** `AskUserQuestion` → then `stage: production`
|
|
68
|
+
4. **Gate #3 (Dev delivery)** — Reviewer `load_check` pass → **you** share **devUrl** → user accepts in browser (user never runs `npm run dev`; gameplay judged by user)
|
|
68
69
|
|
|
69
70
|
**Master Composite** — five 9:16 panels in one image: **Panel 1 = concept panel** (Main Gameplay, all element types); **Panels 2–5 = storyboard** (Hook, Onboarding, End Card, CTA). See collaboration.md § MC five panels.
|
|
70
71
|
|
|
@@ -73,19 +74,22 @@ Full protocol: [docs/team/collaboration.md § Gate Protocol](docs/team/collabora
|
|
|
73
74
|
**Asset Contract** — Layout Spec `assetMapping` paths are locked after Gate #1:
|
|
74
75
|
|
|
75
76
|
- **TA** produces files at these exact paths (production Wave 2)
|
|
76
|
-
- **Developer** (`
|
|
77
|
+
- **Developer** (`ui_pass`): bind real assets, scene switching, simple states → **`npm run dev`** → `devStatus: ui_ready` + devUrl
|
|
78
|
+
- **Developer** (`gameplay_pass`): add core gameplay on verified UI → `devStatus: ready` + devUrl (see Dev Preview Protocol)
|
|
77
79
|
|
|
78
80
|
**Spec Quick-Check** — 30s validation per wave:
|
|
79
81
|
|
|
80
82
|
- **TA** (production Wave 2 start): every assetMapping entry has clear size/format specs
|
|
81
|
-
- **Developer** (`
|
|
83
|
+
- **Developer** (`ui_pass` start): every GameplayAtom reference exists in assetMapping
|
|
82
84
|
- Gaps → `spec-gap` in project-state.md → PM auto-supplements within 5 min
|
|
83
85
|
|
|
84
|
-
**Rework Loop** — Max
|
|
86
|
+
**UI Rework Loop** — Max 5 iterations (`uiReworkRound` in project-state):
|
|
85
87
|
|
|
86
|
-
- Reviewer routes issues by target agent (
|
|
87
|
-
- Severity: `critical`
|
|
88
|
-
- After
|
|
88
|
+
- Reviewer `ui_diff` routes issues by target agent (`developer` / `ta` / `designer`)
|
|
89
|
+
- Severity: `critical` / `major` (must fix) / `minor` (log only, does not block pass)
|
|
90
|
+
- After 5 rounds → orchestrator decision (proceed to `gameplay_pass` or escalate to user)
|
|
91
|
+
|
|
92
|
+
**Gameplay delivery** — No AI rework loop. Reviewer `load_check` only (page loads, no console errors). Gameplay quality = **user at Gate #3**.
|
|
89
93
|
|
|
90
94
|
**Intent Clarification Protocol (ICP)** — Agent-to-agent async Q&A during production:
|
|
91
95
|
|
|
@@ -116,13 +120,13 @@ Three phases — **do not ask the user to run terminal commands** for preview.
|
|
|
116
120
|
|
|
117
121
|
**Dev** = local preview via **`npm run dev`** at project root (implementation is whatever `package.json` → `scripts.dev` defines). **Not** `playcraft start` unless the project script explicitly uses it.
|
|
118
122
|
|
|
119
|
-
| Role | Runs `npm run dev`?
|
|
120
|
-
| ---------------------- |
|
|
121
|
-
| **Developer** | **Yes** (throughout
|
|
122
|
-
| **Reviewer** | **Yes**
|
|
123
|
-
| **You (orchestrator)** | Only if dev server stopped
|
|
124
|
-
| **PM / Designer / TA** | No
|
|
125
|
-
| **User** | **Never**
|
|
123
|
+
| Role | Runs `npm run dev`? | Responsibility |
|
|
124
|
+
| ---------------------- | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------- |
|
|
125
|
+
| **Developer** | **Yes** (throughout `ui_pass` + `gameplay_pass`) | **Final owner of Dev outcome** — UI shell then gameplay at devUrl |
|
|
126
|
+
| **Reviewer** | **Yes** if needed | **`playwright-cli`**: `design_check` (docs), `ui_diff` (screenshots vs MC), `load_check` (no errors) |
|
|
127
|
+
| **You (orchestrator)** | Only if dev server stopped | Keep devUrl valid for Gate #3; **user only clicks the link** |
|
|
128
|
+
| **PM / Designer / TA** | No | Fix assets when Developer blocks upstream (see below) |
|
|
129
|
+
| **User** | **Never** | Gate #3: click devUrl only |
|
|
126
130
|
|
|
127
131
|
### Developer upstream rework
|
|
128
132
|
|
|
@@ -132,13 +136,13 @@ When Developer finds **missing or substandard** Designer/TA output in Dev:
|
|
|
132
136
|
2. Write `docs/intent-clarifications.md` with paths, gap vs MC/spec, and acceptance criteria.
|
|
133
137
|
3. Mark affected atoms `blocked` in `atom-plan.md`.
|
|
134
138
|
4. **You** re-invoke `@technical-artist` and/or `@designer` for targeted rework → then `@developer` again.
|
|
135
|
-
5. Developer re-runs `npm run dev` until no open blockers → `devStatus: ready` + **devUrl**.
|
|
139
|
+
5. Developer re-runs `npm run dev` until no open blockers → `devStatus: ui_ready` (after `ui_pass`) or `devStatus: ready` (after `gameplay_pass`) + **devUrl**.
|
|
136
140
|
|
|
137
|
-
**Never** set `devStatus: ready` with placeholders, open `devBlockers`, or silent skips.
|
|
141
|
+
**Never** set `devStatus: ui_ready` or `ready` with placeholders, open `devBlockers`, or silent skips.
|
|
138
142
|
|
|
139
143
|
### Gate #3 (orchestrator only)
|
|
140
144
|
|
|
141
|
-
1. `
|
|
145
|
+
1. Reviewer `load_check: passed` (page loads within 10s, console has no Error-level logs).
|
|
142
146
|
2. Read **devUrl** from `project-state.md`; if dev server down, run `npm run dev` and refresh devUrl (user still only opens the link).
|
|
143
147
|
3. `AskUserQuestion`: show devUrl + accept / request changes (route to PM/Designer/TA/Developer).
|
|
144
148
|
4. User accepts → `stage: done`, `gates.#3 = passed`.
|
|
@@ -167,32 +171,38 @@ See `docs/team/collaboration.md` § Agent Handoff, § Stage field ownership, §
|
|
|
167
171
|
|
|
168
172
|
When executing `next_orchestrator_action`, **also** update mainline `stage` / gates:
|
|
169
173
|
|
|
170
|
-
| `next_orchestrator_action` contains
|
|
171
|
-
|
|
|
172
|
-
| `Run Gate #1`
|
|
173
|
-
| `
|
|
174
|
-
| `Run Gate #
|
|
175
|
-
| `Invoke @
|
|
176
|
-
| `
|
|
177
|
-
| `Invoke @
|
|
178
|
-
| `Set stage=
|
|
179
|
-
| `
|
|
174
|
+
| `next_orchestrator_action` contains | Orchestrator **must** write |
|
|
175
|
+
| ----------------------------------------- | -------------------------------------------------------------------------------------------------- |
|
|
176
|
+
| `Run Gate #1` | After user pass: `gates.#1 = passed`, `stage: style_exploration` |
|
|
177
|
+
| `Invoke @reviewer design_check Gate #1` | Before Gate #1 — Reviewer soft checklist on four docs |
|
|
178
|
+
| `Run Gate #2a` | `gates.#2a = passed`, set `selectedMcOption`, resume `@designer` (stage stays `style_exploration`) |
|
|
179
|
+
| `Invoke @reviewer design_check Gate #2b` | Before Gate #2b — Reviewer soft checklist on MC + ASR |
|
|
180
|
+
| `Run Gate #2b` | `gates.#2b = passed`, `stage: production`, invoke `@designer` Ph.2 only |
|
|
181
|
+
| `Invoke @technical-artist` | Production Pipeline Wave 1 `done` → invoke TA (Wave 2) |
|
|
182
|
+
| `Set stage=ui_pass` / invoke `@developer` | Production Pipeline Wave 2 `done` → `stage: ui_pass` |
|
|
183
|
+
| `Invoke @reviewer ui_diff` | `stage: ui_review`; Developer `devStatus: ui_ready` |
|
|
184
|
+
| `Set stage=ui_rework` | `stage: ui_rework` + invoke routed agents per UI Diff Report |
|
|
185
|
+
| `Set stage=gameplay_pass` | UI convergence pass → `stage: gameplay_pass` → invoke `@developer` |
|
|
186
|
+
| `Invoke @reviewer load_check` | `devStatus: ready` → Reviewer load_check before Gate #3 |
|
|
187
|
+
| `Run Gate #3` | `gates.#3 = pending` → user accept → `stage: done`, `gates.#3 = passed` |
|
|
180
188
|
|
|
181
189
|
**Stage transition table:**
|
|
182
190
|
|
|
183
|
-
| Current Stage | Trigger | Your Action
|
|
184
|
-
| ------------------- | ------------------------------------- |
|
|
185
|
-
| (start) | User prompt received | Invoke `@pm`
|
|
186
|
-
| `pm` | PM STOP + `gates.#1 = pending` | Gate #1
|
|
187
|
-
| `style_exploration` | Designer STOP + `gates.#2a = pending` | Gate #2a `AskUserQuestion` → set `selectedMcOption` → resume `@designer`
|
|
188
|
-
| `style_exploration` | Designer STOP + `gates.#2b = pending` | Gate #2b
|
|
189
|
-
| `production` | Designer Wave 1 `done` | Invoke `@technical-artist` (Wave 2)
|
|
190
|
-
| `production` | TA Wave 2 `done` (Compliance green) | `stage:
|
|
191
|
-
| `
|
|
192
|
-
| `
|
|
193
|
-
| `
|
|
194
|
-
| `
|
|
195
|
-
| `
|
|
191
|
+
| Current Stage | Trigger | Your Action |
|
|
192
|
+
| ------------------- | ------------------------------------- | ----------------------------------------------------------------------------------------------------- |
|
|
193
|
+
| (start) | User prompt received | Invoke `@pm` |
|
|
194
|
+
| `pm` | PM STOP + `gates.#1 = pending` | Invoke `@reviewer` `design_check` Gate #1 → pass → Gate #1 → on pass invoke `@designer` |
|
|
195
|
+
| `style_exploration` | Designer STOP + `gates.#2a = pending` | Gate #2a `AskUserQuestion` → set `selectedMcOption` → resume `@designer` |
|
|
196
|
+
| `style_exploration` | Designer STOP + `gates.#2b = pending` | Invoke `@reviewer` `design_check` Gate #2b → pass → Gate #2b → `stage: production` → `@designer` Ph.2 |
|
|
197
|
+
| `production` | Designer Wave 1 `done` | Invoke `@technical-artist` (Wave 2) |
|
|
198
|
+
| `production` | TA Wave 2 `done` (Compliance green) | `stage: ui_pass` → invoke `@developer` (UI shell only) |
|
|
199
|
+
| `ui_pass` | `devStatus: ui_ready` | `stage: ui_review` → invoke `@reviewer` `ui_diff` |
|
|
200
|
+
| `ui_pass` | `devStatus: blocked_upstream` | Re-invoke `@technical-artist` / `@designer` per `devBlockers` → then `@developer` |
|
|
201
|
+
| `ui_review` | Fail + `uiReworkRound` < 5 | `stage: ui_rework` → invoke routed agents → `@developer` → `@reviewer` `ui_diff` |
|
|
202
|
+
| `ui_review` | Pass or 5 rounds reached | `stage: gameplay_pass` → invoke `@developer` (gameplay) |
|
|
203
|
+
| `gameplay_pass` | `devStatus: ready` | Invoke `@reviewer` `load_check` → Gate #3 devUrl |
|
|
204
|
+
| `gameplay_pass` | `load_check` fail | Re-invoke `@developer` → `@reviewer` `load_check` |
|
|
205
|
+
| `done` | Gate #3 passed | Project complete |
|
|
196
206
|
|
|
197
207
|
**How to invoke sub-agents:**
|
|
198
208
|
|
|
@@ -204,6 +214,36 @@ When executing `next_orchestrator_action`, **also** update mainline `stage` / ga
|
|
|
204
214
|
|
|
205
215
|
**Requires sub-agent invoke** (`@pm`, `@designer`, `@technical-artist`, `@developer`, `@reviewer`). Do not role-play all five roles in one session — use Claude Code or Cursor agent spawn.
|
|
206
216
|
|
|
217
|
+
### Dispatching Principle (WHAT not HOW)
|
|
218
|
+
|
|
219
|
+
**你不是全知全能的指挥官。** Sub-agent 有完整的 `.claude/agents/<role>.md` + `refs/` + Skills。
|
|
220
|
+
|
|
221
|
+
**调度时只传递：**
|
|
222
|
+
|
|
223
|
+
1. **目标**（atoms to complete, stage entry condition）
|
|
224
|
+
2. **关键约束/提醒**（如 `mediaGroups` 有可用预制资产、`skillRef` 列表）
|
|
225
|
+
3. **上游状态**（which Waves done, which files exist）
|
|
226
|
+
|
|
227
|
+
**禁止在调度消息中：**
|
|
228
|
+
|
|
229
|
+
- 编写详细生产步骤（agent 自己读 refs/ + Skills 决定 HOW）
|
|
230
|
+
- 越俎代庖选择 prompt / model / 工具参数
|
|
231
|
+
- 替 agent 做 Skill Preflight 或 Transparency Classification
|
|
232
|
+
|
|
233
|
+
### Post-STOP Verification (阶段转换前必须)
|
|
234
|
+
|
|
235
|
+
Sub-agent STOP 后，**先验证再转阶段**：
|
|
236
|
+
|
|
237
|
+
| 验证项 | 失败处理 |
|
|
238
|
+
| ----------------------------- | ----------------- |
|
|
239
|
+
| 所有 atoms `status ≠ pending` | 要求补全 |
|
|
240
|
+
| `actualOutput` 文件存在 | 要求补全 |
|
|
241
|
+
| `atom-plan.md` Context 非空 | 要求回填 |
|
|
242
|
+
| Skill Preflight 已完成 | 拒绝 STOP，重新入 |
|
|
243
|
+
| mediaGroups 处置已记录 | 要求补充 |
|
|
244
|
+
|
|
245
|
+
验证失败 → **不转阶段**，re-invoke 该 agent 补全。详见 `.cursor/rules/playcraft-orchestrator.mdc`。
|
|
246
|
+
|
|
207
247
|
## Directory Layout
|
|
208
248
|
|
|
209
249
|
```
|
|
@@ -225,9 +265,9 @@ Project-level principles (full MUST/NEVER: [docs/team/agent-conduct.md](docs/tea
|
|
|
225
265
|
4. Style Gate (#2a + #2b) cannot be skipped — no production without confirmed MC + ASR
|
|
226
266
|
5. Layout Spec is the sole three-way alignment mechanism — do not violate
|
|
227
267
|
6. Asset Contract paths are immutable after Gate #1
|
|
228
|
-
7. Production serial: Designer Ph.2 → TA → Developer (`
|
|
229
|
-
8.
|
|
230
|
-
9. Dev delivery: Developer owns Dev quality;
|
|
268
|
+
7. Production serial: Designer Ph.2 → TA → Developer (`ui_pass` → `gameplay_pass`) — never invoke `@developer` during `production`
|
|
269
|
+
8. UI rework max 5 rounds (`uiReworkRound`) — then orchestrator decision or proceed to `gameplay_pass`
|
|
270
|
+
9. Dev delivery: Developer owns Dev quality; Reviewer `load_check` + user gameplay judgment at Gate #3
|
|
231
271
|
10. No `playcraft build` for `done` — endpoint is `devStatus: ready` + user devUrl acceptance
|
|
232
272
|
|
|
233
273
|
## Detailed References
|
|
@@ -30,27 +30,36 @@ On every invoke, in order:
|
|
|
30
30
|
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
31
31
|
| **MUST** | Be the **only** role that uses `AskUserQuestion` toward the user (Gate #1, #2a, #2b, #3) |
|
|
32
32
|
| **MUST** | After any sub-agent STOP, read `## Agent handoff` in `project-state.md` before spawn / resume / Gate |
|
|
33
|
+
| **MUST** | After any sub-agent STOP, verify: all atoms `status ≠ pending`, `actualOutput` files exist, Context sections filled, Skill Preflight done |
|
|
33
34
|
| **MUST** | If `gate_pending` is non-null and `waiting_for: user_gate`, run **only** the matching Gate (`AskUserQuestion`) — **do not** invoke sub-agents |
|
|
34
35
|
| **MUST** | If `subagent_stop: true` and `waiting_for: orchestrator`, execute **only** `next_orchestrator_action` |
|
|
35
36
|
| **MUST** | Before invoke: reset handoff (`subagent_stop: false`, `waiting_for: none`, set `subagent` to target role) |
|
|
37
|
+
| **MUST** | Dispatch = WHAT + skill refs + constraints only; do NOT write detailed production steps for sub-agents |
|
|
38
|
+
| **MUST** | Run Reviewer `design_check` before Gate #1 and Gate #2b — do **not** ask user until Reviewer passes soft checklist |
|
|
36
39
|
| **MUST NOT** | Role-play all five agents in one session when sub-agent invoke is available |
|
|
37
40
|
| **MUST NOT** | Skip Gate #2a / #2b while gates are `pending` |
|
|
38
41
|
| **MUST NOT** | Invoke `@technical-artist` before Production Pipeline Wave 1 (Designer Ph.2) is `done` |
|
|
39
|
-
| **MUST NOT** | Invoke `@developer` or set `stage:
|
|
40
|
-
| **MUST NOT** | Spawn `@developer` during `stage: production` (serial workflow: Designer → TA → Developer)
|
|
42
|
+
| **MUST NOT** | Invoke `@developer` or set `stage: ui_pass` before Production Pipeline Wave 2 (TA) is `done` |
|
|
43
|
+
| **MUST NOT** | Spawn `@developer` during `stage: production` (serial workflow: Designer → TA → Developer ui_pass) |
|
|
41
44
|
| **MUST NOT** | Advance mainline `stage` when a sub-agent could do it — **orchestrator owns** `stage` transitions (see collaboration.md § Stage field ownership) |
|
|
45
|
+
| **MUST NOT** | Advance to next stage if post-STOP verification fails (atom status, actualOutput, Context, Skill Preflight) |
|
|
42
46
|
|
|
43
47
|
## Sub-agents only (PM, Designer, TA, Developer, Reviewer)
|
|
44
48
|
|
|
45
|
-
| | Rule
|
|
46
|
-
| ------------ |
|
|
47
|
-
| **MUST NOT** | Use `AskUserQuestion` or present Gate choices to the user
|
|
48
|
-
| **MUST** | On Gate-ready materials: sync `gates.#N = pending` + handoff (`gate_pending`, `waiting_for: user_gate`) → **STOP**
|
|
49
|
-
| **MUST** | Run Spec Quick-Check within 30s: TA when starting production Wave 2; Developer when starting `
|
|
50
|
-
| **MUST
|
|
51
|
-
| **MUST
|
|
52
|
-
| **MUST
|
|
53
|
-
| **MUST** | Complete
|
|
49
|
+
| | Rule |
|
|
50
|
+
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
51
|
+
| **MUST NOT** | Use `AskUserQuestion` or present Gate choices to the user |
|
|
52
|
+
| **MUST** | On Gate-ready materials: sync `gates.#N = pending` + handoff (`gate_pending`, `waiting_for: user_gate`) → **STOP** |
|
|
53
|
+
| **MUST** | Run Spec Quick-Check within 30s: TA when starting production Wave 2; Developer when starting `ui_pass` |
|
|
54
|
+
| **MUST** | Update `atom-plan.json` → `atoms[].status` + `atoms[].actualOutput` upon completing each assigned atom — never leave `pending` after delivery |
|
|
55
|
+
| **MUST** | Fill corresponding `atom-plan.md` § Context section (Asset / TA / Impl Skill Context) — never leave `(Pending)` after delivery |
|
|
56
|
+
| **MUST** | Check `atom-plan.json` → `skillsMatch.mediaGroups` for reusable assets before generating from scratch (Designer/TA) |
|
|
57
|
+
| **MUST** | Complete Skill Preflight (read relevant platform Skills) before production — TA: `ta-log § Skill Preflight`; Developer: `developer-log § Skill Preflight`; Designer: `designer-log § Skill Preflight` |
|
|
58
|
+
| **MUST NOT** | Continue producing while `subagent_stop: true` and `waiting_for: orchestrator` (resume only when orchestrator clears handoff) |
|
|
59
|
+
| **MUST NOT** | Change mainline `stage` (orchestrator only — see collaboration.md § Stage field ownership) |
|
|
60
|
+
| **MUST NOT** | Skip required logs (`designer-log`, `ta-log`, `developer-log`, `review-report`) |
|
|
61
|
+
| **MUST NOT** | Ignore `mediaGroups` matches and generate from scratch when a pre-matched asset exists — link first, skip only with documented reason |
|
|
62
|
+
| **MUST** | Complete [STOP sync checklist](collaboration.md#stop-sync-checklist) on every STOP |
|
|
54
63
|
|
|
55
64
|
### PM (four-doc discipline)
|
|
56
65
|
|
|
@@ -78,28 +87,35 @@ On every invoke, in order:
|
|
|
78
87
|
| **MUST** | Execute `refs/ta-pipeline-cookbook.md` **Step 0a → Step 0** in order after intake |
|
|
79
88
|
| **MUST NOT** | Start bulk generation or write `ta-log` Style Interpretation until Upstream Intake is complete |
|
|
80
89
|
| **MUST NOT** | Mark TA wave `done` without Upstream Intake + Style Interpretation sections filled |
|
|
90
|
+
| **MUST** | Before any asset generation: complete **`logs/ta-log.md` § Production Plan** — Coverage Plan covering 100% `assetMapping`, Atlas Assembly Plan matching layout-spec groups, Risk Checklist all `[x]` |
|
|
91
|
+
| **MUST NOT** | Start bulk generation or write deliverables under `assets/` until Production Plan Risk Checklist is fully checked |
|
|
81
92
|
| **MUST** | Pass **`.claude/hooks/validate-workflow-stop.mjs`** on STOP (Claude `SubagentStop` + Cursor `subagentStop` — see `.claude/hooks/README.md`) |
|
|
82
93
|
|
|
83
94
|
### Developer
|
|
84
95
|
|
|
85
|
-
| | Rule
|
|
86
|
-
| ------------ |
|
|
87
|
-
| **MUST** | Before Spec Quick-Check or any `game/` work in `
|
|
88
|
-
| **MUST** | Execute `refs/developer-phase1-flow.md` **Step 0 → Step 1** in order after intake
|
|
89
|
-
| **MUST NOT** | Start Skill Preflight or edit `game/**` until Upstream Intake is complete
|
|
90
|
-
| **MUST** |
|
|
91
|
-
| **MUST** |
|
|
92
|
-
| **MUST** |
|
|
93
|
-
| **MUST
|
|
94
|
-
| **MUST
|
|
95
|
-
| **MUST NOT** |
|
|
96
|
-
| **MUST NOT** |
|
|
97
|
-
| **MUST**
|
|
96
|
+
| | Rule |
|
|
97
|
+
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
98
|
+
| **MUST** | Before Spec Quick-Check or any `game/` work in `ui_pass`: complete **Upstream Intake** in `logs/developer-log.md` — Read **四件套** + `docs/style-exploration.md` + `logs/designer-log.md` + `logs/ta-log.md`; tick every row; one-line takeaway per doc |
|
|
99
|
+
| **MUST** | Execute `refs/developer-phase1-flow.md` **Step 0 → Step 1** in order after intake |
|
|
100
|
+
| **MUST NOT** | Start Skill Preflight or edit `game/**` until Upstream Intake is complete |
|
|
101
|
+
| **MUST** | **`ui_pass` scope only**: scene switching, element placement, simple state display — bind real assets at contract paths; **MUST NOT** implement core gameplay rules (scoring, elimination, level logic, win/lose) |
|
|
102
|
+
| **MUST** | Before `ui_pass` STOP: complete **`logs/developer-log.md` § UI Pass Plan** — Scene-Asset Binding + scene navigation + Risk Checklist all `[x]` |
|
|
103
|
+
| **MUST** | Set `devStatus: ui_ready` (not `ready`) after `ui_pass`; handoff `Invoke @reviewer ui_diff` |
|
|
104
|
+
| **MUST** | **`gameplay_pass` scope**: add core gameplay on verified UI shell — PGS, first level success, CTA; complete **`logs/developer-log.md` § Gameplay Pass Plan** before gameplay logic |
|
|
105
|
+
| **MUST** | Before any `game/` implementation: for each non-empty `skillRef`, read Recipe + `ref/` from `.claude/skills/<skillRef>/` when link exists; else `playcraft skills read` — log in `developer-log.md` § Skill Preflight |
|
|
106
|
+
| **MUST NOT** | Rewrite UI layout during `gameplay_pass` unless open UI Diff items remain |
|
|
107
|
+
| **MUST NOT** | Set `devStatus: ready` while `devBlockers` has open items |
|
|
108
|
+
| **MUST NOT** | Use placeholder assets or silently skip `blocked` atoms |
|
|
109
|
+
| **MUST** | Pass **`.claude/hooks/validate-workflow-stop.mjs`** on STOP (plan section validated per stage: UI Pass Plan vs Gameplay Pass Plan) |
|
|
98
110
|
|
|
99
111
|
### Reviewer
|
|
100
112
|
|
|
101
113
|
| | Rule |
|
|
102
114
|
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
103
|
-
| **MUST** |
|
|
115
|
+
| **MUST** | Operate in one of three modes per orchestrator invoke: **`design_check`** \| **`ui_diff`** \| **`load_check`** |
|
|
116
|
+
| **MUST** | Read **`playwright-cli`** skill before `ui_diff` or `load_check` browser steps |
|
|
117
|
+
| **MUST** | **`design_check`**: soft checklist only — block obvious defects (missing docs, wrong MC ratio, empty assetMapping); do **not** judge subjective design quality |
|
|
118
|
+
| **MUST** | **`ui_diff`**: screenshot each MC panel scene via `playwright-cli`; compare layout/color/elements; route issues with `routeTo: developer \| ta \| designer`; increment `uiReworkRound` on fail (max 5) |
|
|
119
|
+
| **MUST** | **`load_check`**: confirm page loads within 10s, no Error-level console logs; do **not** perform gameplay walkthrough |
|
|
104
120
|
| **MUST NOT** | Modify production files (only `logs/review-report.md` + `project-state` checkpoint) |
|
|
105
|
-
| **MUST**
|
|
121
|
+
| **MUST NOT** | Write mainline `stage` — set handoff `next_orchestrator_action` for orchestrator (`Set stage=ui_rework`, `Run Gate #3`, etc.) |
|
|
@@ -67,8 +67,39 @@ jq -n \
|
|
|
67
67
|
| 角色 | 读 JSON | 读 MD | Skills 路径 |
|
|
68
68
|
| ------------------------ | ------------------------ | ------------------------ | ------------------------------------------------ |
|
|
69
69
|
| Orchestrator / Developer | `atoms[]`、`skillsMatch` | `## Impl Skill Context` | `playcraft.config.json` + `.claude/skills/` 软链 |
|
|
70
|
-
| TA | `atoms[]`
|
|
71
|
-
| Designer | `atoms[]`
|
|
70
|
+
| TA | `atoms[]`、`mediaGroups` | `## TA Skill Context` | 同上 |
|
|
71
|
+
| Designer | `atoms[]`、`mediaGroups` | `## Asset Skill Context` | 同上 |
|
|
72
72
|
| Reviewer | 两者只读 | 两者只读 | — |
|
|
73
73
|
|
|
74
74
|
Developer 软链：`.claude/skills/<skillRef>/`（`playcraft skills link --from-atom-plan`）。断链时用 `playcraft skills read <skillRef>`（自动读 config，勿手抄 node_modules 路径）。
|
|
75
|
+
|
|
76
|
+
## Status Update Protocol（所有产出 Agent 必须遵守）
|
|
77
|
+
|
|
78
|
+
**atom-plan.json 是活的追踪系统，不是一次性规划文档。** 每个 Agent 完成 atom 后立即更新：
|
|
79
|
+
|
|
80
|
+
```json
|
|
81
|
+
{
|
|
82
|
+
"atomId": "<id>",
|
|
83
|
+
"status": "done", // or "skipped" with reason in dagRevisions
|
|
84
|
+
"actualOutput": "<path>" // the actual deliverable path on disk
|
|
85
|
+
}
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
| Agent | 何时更新 | `actualOutput` 格式 |
|
|
89
|
+
| --------- | ------------------------------- | ----------------------------------------------------- |
|
|
90
|
+
| Designer | Phase 2 每完成一个 atom | `"assets/audio/bgm.mp3"` 或 `"ASR:ui_sheet:region_3"` |
|
|
91
|
+
| TA | 每完成一个 atlas/asset | `"assets/images/ui/ui_atlas.webp"` |
|
|
92
|
+
| Developer | 每完成一个 gameplay/config atom | `"game/gameplay/reducer.ts"` |
|
|
93
|
+
|
|
94
|
+
**Context 回填同样强制**：对应 agent 的 `atom-plan.md` § Context 区不得为空（`Pending`）。Orchestrator 在阶段转换前验证。
|
|
95
|
+
|
|
96
|
+
## mediaGroups 使用规则
|
|
97
|
+
|
|
98
|
+
`skillsMatch.mediaGroups` 包含 `playcraft skills match` 自动发现的可复用预制资产（图片/音频/3D）。
|
|
99
|
+
|
|
100
|
+
**协议**：
|
|
101
|
+
|
|
102
|
+
1. **Designer / TA 必须读** `mediaGroups` 并对每个 entry 判断是否匹配当前 atom
|
|
103
|
+
2. **匹配 → 直接 link**：`playcraft skills link --atom <atomId>` → 后处理（resize/convert/mix）→ `status: done`
|
|
104
|
+
3. **不匹配 → 跳过并记录**：在 `dagRevisions` 记录 skip 原因
|
|
105
|
+
4. **禁止**：mediaGroups 中有匹配项却无视、从零生成
|