@playcraft/cli 0.0.55 → 0.0.56

package/dist/remix/clone.js

@@ -0,0 +1,255 @@
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, writeFileSync, readFileSync, existsSync } from 'node:fs';
+import path from 'node:path';
+import { loadGlobalConfig } from '../config.js';
+import { PlayCraftHttpClient } from '../utils/playcraft-http-client.js';
+import { isRemoteCloneSource, resolveRemixCloneTarget, } from './clone-source.js';
+/** Build the branch-scoped Git Smart HTTP URL (no credentials in URL). */
+export function buildRemixGitProxyUrl(apiBaseUrl, projectId, branch) {
+    const base = apiBaseUrl.replace(/\/+$/, '');
+    const encodedBranch = encodeURIComponent(branch);
+    return `${base}/api/git/projects/${encodeURIComponent(projectId)}/branches/${encodedBranch}.git`;
+}
+export function resolveCloneTargetDir(projectId, branch, dir) {
+    if (dir?.trim())
+        return path.resolve(dir.trim());
+    const safeBranch = branch.replace(/[/\\]+/g, '-').replace(/[^a-zA-Z0-9._-]+/g, '-');
+    return path.resolve(process.cwd(), `${projectId}-${safeBranch}`);
+}
+function localServiceUrl(baseUrl, fromPort, toPort) {
+    try {
+        const url = new URL(baseUrl);
+        const isLocal = ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname);
+        if (isLocal && url.port === fromPort)
+            url.port = toPort;
+        return url.toString().replace(/\/+$/, '');
+    }
+    catch {
+        return baseUrl.replace(/\/+$/, '');
+    }
+}
+function createApiClient(options) {
+    const configured = new PlayCraftHttpClient(options);
+    const apiBaseUrl = localServiceUrl(configured.baseUrl, '3000', '3001');
+    if (apiBaseUrl === configured.baseUrl)
+        return configured;
+    return new PlayCraftHttpClient({
+        url: apiBaseUrl,
+        token: configured.token,
+        requestId: configured.requestId,
+    });
+}
+/**
+ * Prefer explicit --url; else env/login config (via PlayCraftHttpClient).
+ * Only use pasted portal origin when no API base is configured yet.
+ */
+function resolveApiBaseHint(options, portalOrigin) {
+    if (options.url?.trim())
+        return options.url.trim();
+    const globalConfig = loadGlobalConfig();
+    const configured = process.env.PLAYCRAFT_API_URL ||
+        process.env.PLAYCRAFT_URL ||
+        (typeof globalConfig.backendUrl === 'string' && globalConfig.backendUrl) ||
+        (typeof globalConfig.url === 'string' && globalConfig.url);
+    if (configured)
+        return undefined;
+    if (portalOrigin?.trim()) {
+        return localServiceUrl(portalOrigin.trim(), '3000', '3001');
+    }
+    return undefined;
+}
+function writePlaycraftMeta(targetDir, meta) {
+    writeFileSync(path.join(targetDir, '.playcraft.json'), `${JSON.stringify(meta, null, 2)}\n`, 'utf8');
+}
+function configureRepoCredentialHelper(targetDir) {
+    // Prefer invoking the same CLI binary the user used.
+    const helper = `!playcraft git-credential`;
+    spawnSync('git', ['config', 'credential.helper', helper], {
+        cwd: targetDir,
+        encoding: 'utf8',
+    });
+    spawnSync('git', ['config', 'credential.useHttpPath', 'true'], {
+        cwd: targetDir,
+        encoding: 'utf8',
+    });
+}
+async function resolveProjectIdFromGitHost(client, repositoryUrl) {
+    try {
+        const data = await client.get(`/git/resolve-repo?repositoryUrl=${encodeURIComponent(repositoryUrl)}`);
+        const projectId = String(data?.projectId || data?.projectUuid || '').trim();
+        if (!projectId) {
+            throw new Error('empty_project_id');
+        }
+        return projectId;
+    }
+    catch {
+        throw new Error('无法根据工蜂/Git 地址定位 PlayCraft 项目（无权限或不存在）。请改用 Remix 详情页 URL，或 --project-id / --branch。');
+    }
+}
+export async function remixClone(options) {
+    const target = resolveRemixCloneTarget({
+        source: options.source,
+        projectId: options.projectId,
+        branch: options.branch,
+    });
+    let projectId = target.projectId?.trim() || '';
+    const branch = String(target.branch || '').trim();
+    if (!branch) {
+        throw new Error('缺少 Remix 分支名。');
+    }
+    if (branch === 'main' || branch === 'master') {
+        throw new Error('不允许 clone 主干分支；请指定 Remix 分支（例如 remix/...）。');
+    }
+    const client = createApiClient({
+        url: resolveApiBaseHint(options, target.origin),
+        token: options.token,
+    });
+    if (target.kind === 'git-host') {
+        if (!target.repositoryUrl) {
+            throw new Error('工蜂/Git 地址无效。');
+        }
+        projectId = await resolveProjectIdFromGitHost(client, target.repositoryUrl);
+    }
+    if (!projectId) {
+        throw new Error('缺少项目 ID。');
+    }
+    const cloneUrl = buildRemixGitProxyUrl(client.baseUrl, projectId, branch);
+    const targetDir = resolveCloneTargetDir(projectId, branch, options.dir);
+    if (existsSync(targetDir) && existsSync(path.join(targetDir, '.git'))) {
+        throw new Error(`目标目录已存在 Git 仓库：${targetDir}`);
+    }
+    mkdirSync(path.dirname(targetDir), { recursive: true });
+    if (!options.json) {
+        process.stderr.write(`[clone] ${cloneUrl}\n`);
+        process.stderr.write(`[clone] → ${targetDir}\n`);
+    }
+    const result = spawnSync('git', [
+        '-c',
+        `http.extraHeader=Authorization: Bearer ${client.token}`,
+        'clone',
+        '--branch',
+        branch,
+        '--single-branch',
+        '--depth',
+        '1',
+        cloneUrl,
+        targetDir,
+    ], {
+        encoding: 'utf8',
+        stdio: options.json ? 'pipe' : 'inherit',
+    });
+    if (result.status !== 0) {
+        const detail = [result.stderr, result.stdout].filter(Boolean).join('\n').trim();
+        throw new Error(detail || `git clone 失败（exit ${result.status}）`);
+    }
+    const meta = {
+        schemaVersion: '1.0',
+        projectId,
+        branch,
+        cloneUrl,
+        clonedAt: new Date().toISOString(),
+    };
+    writePlaycraftMeta(targetDir, meta);
+    configureRepoCredentialHelper(targetDir);
+    let projectType;
+    try {
+        const project = await client.get(`/projects/${encodeURIComponent(projectId)}`);
+        projectType = project?.projectType;
+    }
+    catch {
+        // optional — next-step hints only
+    }
+    if (options.install || options.dev) {
+        const install = spawnSync('npm', ['install'], {
+            cwd: targetDir,
+            encoding: 'utf8',
+            stdio: options.json ? 'pipe' : 'inherit',
+            shell: process.platform === 'win32',
+        });
+        if (install.status !== 0) {
+            throw new Error('npm install 失败');
+        }
+    }
+    if (options.dev) {
+        spawnSync('npm', ['run', 'dev'], {
+            cwd: targetDir,
+            encoding: 'utf8',
+            stdio: 'inherit',
+            shell: process.platform === 'win32',
+        });
+    }
+    if (options.json) {
+        console.log(JSON.stringify({
+            schemaVersion: '1.0',
+            ok: true,
+            command: 'remix.clone',
+            requestId: client.requestId,
+            data: { ...meta, targetDir, projectType, sourceKind: target.kind },
+        }));
+        return;
+    }
+    console.log(`✓ Remix 已克隆到 ${targetDir}`);
+    console.log(`  分支: ${branch}`);
+    console.log(`  remote: ${cloneUrl}`);
+    console.log('');
+    console.log('下一步：');
+    console.log(`  cd ${targetDir}`);
+    if (projectType === 'external') {
+        console.log('  npm install && npm run dev');
+    }
+    else {
+        console.log('  playcraft start --project <project-id>   # PlayCanvas / 本地 Agent 预览');
+    }
+    console.log('  git pull / git push   # 经 PlayCraft Git 代理（需已 login）');
+}
+export { isRemoteCloneSource, resolveRemixCloneTarget };
+/**
+ * Git credential helper (get/store/erase). Only `get` is implemented:
+ * returns PAT from ~/.playcraft/config.json for PlayCraft git proxy hosts.
+ */
+export function gitCredentialCommand(action) {
+    const op = (action || process.argv[3] || 'get').trim();
+    if (op !== 'get') {
+        // store/erase: no-op (PAT lives in global config)
+        return;
+    }
+    const input = readFileSync(0, 'utf8');
+    const attrs = {};
+    for (const line of input.split(/\r?\n/)) {
+        const eq = line.indexOf('=');
+        if (eq <= 0)
+            continue;
+        attrs[line.slice(0, eq)] = line.slice(eq + 1);
+    }
+    const host = attrs.host || '';
+    const protocol = attrs.protocol || 'https';
+    const reqPath = attrs.path || '';
+    if (!reqPath.includes('/api/git/projects/')) {
+        return;
+    }
+    const globalConfig = loadGlobalConfig();
+    const token = process.env.PLAYCRAFT_TOKEN ||
+        (typeof globalConfig.token === 'string' ? globalConfig.token : undefined);
+    if (!token || !token.startsWith('playcraft_pat_')) {
+        return;
+    }
+    // Optional host check against saved backend URL
+    const configured = (typeof globalConfig.backendUrl === 'string' && globalConfig.backendUrl) ||
+        (typeof globalConfig.url === 'string' && globalConfig.url) ||
+        process.env.PLAYCRAFT_API_URL ||
+        process.env.PLAYCRAFT_URL ||
+        '';
+    if (configured && host) {
+        try {
+            const configuredHost = new URL(configured).host;
+            if (configuredHost && configuredHost !== host) {
+                // Still allow if path is clearly our git proxy (e.g. custom CDN host)
+            }
+        }
+        catch {
+            // ignore
+        }
+    }
+    process.stdout.write(`username=playcraft\npassword=${token}\n\n`);
+    void protocol;
+}

package/dist/scaffold/templates.js

@@ -3,7 +3,7 @@ import { resolveCliPackageRoot } from './compose.js';
 export const CREATE_TEMPLATES = {
     agent: {
         id: 'agent',
-        dir: 'project-template',
+        dir: 'project-template-v2',
         label: 'Agent Team 工作流（默认）',
         kind: 'agent',
     },

package/dist/utils/agent-api-client.js

@@ -26,6 +26,7 @@ export class AgentApiClient {
     apiUrl;
     token;
     isPat;
+    playcraftEnv;
     constructor() {
         const localConfig = AgentApiClient.loadLocalConfig();
         const globalConfig = loadGlobalConfig();
@@ -47,13 +48,19 @@ export class AgentApiClient {
         this.apiUrl = apiUrl;
         this.token = token;
         this.isPat = isPatToken(token);
+        this.playcraftEnv = (process.env.PLAYCRAFT_ENV ||
+            localConfig.env ||
+            '').trim();
     }
     /** 根据 token 类型构造鉴权 headers */
     authHeaders() {
-        if (this.isPat) {
-            return { 'Authorization': `Bearer ${this.token}` };
+        const headers = this.isPat
+            ? { Authorization: `Bearer ${this.token}` }
+            : { 'X-Sandbox-Token': this.token };
+        if (this.playcraftEnv) {
+            headers['playcraft-env'] = this.playcraftEnv;
         }
-        return { 'X-Sandbox-Token': this.token };
+        return headers;
     }
     /** Absolute pathname under /api/agent/tools (path may omit leading slash). */
     toolsRequestUrl(path) {

package/dist/utils/remix-image-attachments.js

@@ -1,15 +1,9 @@
 import { readFileSync, statSync } from 'node:fs';
 import { basename, extname } from 'node:path';
 import { PlayCraftApiError } from './playcraft-http-client.js';
+import { appendRemixReferenceImagesPrompt, referenceImageExtensions, referenceImageMimeFromExtension, } from '@playcraft/common/agent/reference-images';
 const MAX_IMAGES = 4;
 const MAX_IMAGE_BYTES = 5 * 1024 * 1024;
-const IMAGE_MIME_BY_EXTENSION = {
-    '.gif': 'image/gif',
-    '.jpeg': 'image/jpeg',
-    '.jpg': 'image/jpeg',
-    '.png': 'image/png',
-    '.webp': 'image/webp',
-};
 function attachmentError(code, message, details, retryable = false) {
     return new PlayCraftApiError({ code, message, details, retryable });
 }
@@ -22,9 +16,9 @@ export function readImageAttachments(paths) {
     }
     return candidates.map((sourcePath) => {
         const extension = extname(sourcePath).toLowerCase();
-        const mimeType = IMAGE_MIME_BY_EXTENSION[extension];
+        const mimeType = referenceImageMimeFromExtension(extension);
         if (!mimeType) {
-            throw attachmentError('ATTACHMENT_TYPE_UNSUPPORTED', `不支持的图片格式：${sourcePath}。仅支持 JPEG (Joint Photographic Experts Group, 联合图像专家组)、PNG (Portable Network Graphics, 便携式网络图形)、WebP 和 GIF (Graphics Interchange Format, 图形交换格式)。`, { path: sourcePath, supportedExtensions: Object.keys(IMAGE_MIME_BY_EXTENSION) });
+            throw attachmentError('ATTACHMENT_TYPE_UNSUPPORTED', `不支持的图片格式：${sourcePath}。仅支持 JPEG (Joint Photographic Experts Group, 联合图像专家组)、PNG (Portable Network Graphics, 便携式网络图形)、WebP 和 GIF (Graphics Interchange Format, 图形交换格式)。`, { path: sourcePath, supportedExtensions: [...referenceImageExtensions()] });
         }
         let size;
         try {
@@ -98,28 +92,6 @@ export async function uploadImageAttachments(client, projectId, branch, attachme
     return uploaded;
 }
 export function buildReferenceImagesPrompt(prompt, attachments) {
-    if (attachments.length === 0)
-        return prompt;
-    const pathList = attachments.map((attachment) => `- ${attachment.sandboxPath}`).join('\n');
-    return [
-        prompt,
-        '',
-        '[Reference Images]',
-        `The user attached ${attachments.length} image(s) at these sandbox filesystem paths:`,
-        pathList,
-        '',
-        'These files have already been written to the sandbox filesystem.',
-        '',
-        '**IMPORTANT:** Do NOT read, open, or inspect any of these image files. Do NOT use tools like read_file, cat, or any other file reader on them. The paths themselves are all you need.',
-        '',
-        "Infer each image's purpose from the user's message (e.g. reference for style/composition, UI mockup, screenshot illustrating an issue, asset to import, etc.). For any image you judge to be a visual reference, pass its path directly to `playcraft-generate-image` — do NOT ask the user to confirm, and do NOT attempt to examine the image content first.",
-        '',
-        'When passing references to `playcraft-generate-image`:',
-        '- Put the first reference in `referenceImagePath`, remaining ones in `additionalReferenceImagePaths` as a comma-separated string.',
-        '- Preserve the original order.',
-        '- Up to 8 references total; paths must not contain commas.',
-        '- Save generated images under `src/theme/draft/assets/` unless the user explicitly asks for another project asset location.',
-        '- When reporting saved image paths back to the user, prefer `/project/<repo-relative-path>` such as `/project/src/theme/draft/assets/level-ref.png`, not the full `/projects/<projectId>/<branch>/...` path.',
-    ].join('\n');
+    return appendRemixReferenceImagesPrompt(prompt, attachments.map((attachment) => attachment.sandboxPath));
 }
 export const IMAGE_OPTION_HELP = '一个或多个图片路径（最多 4 张；JPEG (Joint Photographic Experts Group, 联合图像专家组)、PNG (Portable Network Graphics, 便携式网络图形)、WebP、GIF (Graphics Interchange Format, 图形交换格式)，每张不超过 5 MB (Megabyte, 兆字节)）';

package/dist/utils/sandbox-path.js

@@ -0,0 +1,20 @@
+/**
+ * Map legacy sandbox project root aliases onto the real cwd.
+ *
+ * Multi-slot sandboxes use workdir `/projects/{projectId}/{branch}` while many
+ * agent prompts / tools still advertise `/project/...`. CLI commands must treat
+ * `/project` as cwd so post-processing (e.g. remove-background) finds files.
+ */
+import { resolve } from 'path';
+export function resolveSandboxPath(userPath, cwd = process.cwd()) {
+    if (!userPath)
+        return userPath;
+    const forward = userPath.replace(/\\/g, '/');
+    if (forward === '/project') {
+        return cwd;
+    }
+    if (forward.startsWith('/project/')) {
+        return resolve(cwd, forward.slice('/project/'.length));
+    }
+    return userPath;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playcraft/cli",
-  "version": "0.0.55",
+  "version": "0.0.56",
   "private": false,
   "type": "module",
   "engines": {
@@ -45,8 +45,8 @@
     "@gltf-transform/core": "^4.3.0",
     "@gltf-transform/extensions": "^4.3.0",
     "@gltf-transform/functions": "^4.3.0",
-    "@playcraft/build": "^0.0.55",
-    "@playcraft/common": "^0.0.55",
+    "@playcraft/build": "^0.0.56",
+    "@playcraft/common": "^0.0.56",
     "chokidar": "^4.0.3",
     "commander": "^13.1.0",
     "cors": "^2.8.6",

package/project-template/.claude/agents/creative-director.md

@@ -0,0 +1,114 @@
+---
+name: creative-director
+description: 'Creative Director: Ring 1 creative discovery — Micro-Story Spine + north star + creative-process before spec work.'
+tools:
+  - 'Read'
+  - 'Write'
+  - 'Grep'
+  - 'Glob'
+  - 'WebSearch'
+  - 'WebFetch'
+  - 'Bash(npm run state:set:*)'
+  - 'Bash(npm run state:get:*)'
+  - 'Bash(playcraft skills read:*)'
+---
+
+# Creative Director — Role Contract
+
+> **Workflow spec**: growth-rings-v1 · Ring 1 creative discovery subagent (fresh context).
+
+## Role Essence
+
+You are the **15-second playable-ad Creative Director**. You own **creative discovery only**: diverge gameplay core-moment candidates, adversarial review, commitment, and a readable **Creative North Star** with a **Micro-Story Spine**.
+
+You do **not** match skills, write `DESIGN.md`, build level-sketch, seed slices, or run design verifiers. That is `@game-designer` spec mode after you STOP.
+
+**Mechanism-first wrap:** `@game-designer` already locked `handoffContext.primaryGameplaySkill`. **Step 0:** `playcraft skills read <primaryGameplaySkill>` — PGS (PlayCraft Gameplay Schema, 玩法模式) is the authority. Your story must **wrap** slide-out / tray / blocking moments; **do not invent** a new core verb (e.g. rotate-to-aim replacing path slide).
+
+**Persona:** Default **L1–L2** narrative (light story that fits the mechanic). L0 (pure mechanic) **only** when the user explicitly opts out of story — record their exact words in Phase 3. You decide Narrative Level; orchestrator hints are not binding.
+
+**MDA reverse (within PGS):** Start from Fantasy / Challenge / Urgency, then land on **PGS step names** (pathClick / slideOut / flyToTray / matchDetection) — not a different core loop.
+
+**Micro-Story Spine is non-negotiable:** L1/L2 require Who + Situation + Stakes + Payoff image. L0 requires Situation + Payoff + Phase 3 opt-out quote.
+
+**One-liner bar:** Answer _who is in what situation, betting on what_ — not _which buttons they press_.
+
+## Dispatch Contract
+
+Start every run with:
+
+```bash
+npm run state:get -- --json dispatchPacket contextPacket referenceReads
+```
+
+Read **`referenceReads`** from `state:get` for methodology files (five-axis, design-methodology, examples). Do not hard-code paths — the disclosure layer is the single source of truth.
+
+If `dispatchPacket.role` is `creative-director`, execute only that packet:
+
+- Obey `doWhat`, `flow`, `allowedFiles`, `forbiddenTasks`, and `acceptance`.
+- Do not infer spec-phase work from file names or validator docs.
+- Write state through `npm run state:set`; do not edit generated state markdown.
+
+Execution guide: `.claude/agents/refs/creative-discovery-guide.md` (read on start).
+
+## Four-Phase Creative Process
+
+Before STOP, produce:
+
+1. **`docs/creative-process.md`** — Phases 1–3 complete + Phase 4 **Design Intent** line only (from `templates/game-designer-creative-process.template.md`).
+2. **`docs/north-star.md`** — from `templates/north-star.template.md` (includes **Micro-Story Spine** before One-liner).
+
+| Phase | Name                                  | Forbidden                   |
+| ----- | ------------------------------------- | --------------------------- |
+| 0     | Skills read primary PGS               | No DESIGN.md                |
+| 1     | Radical diverge (≥3 candidates)       | No DESIGN.md                |
+| 2     | Adversarial review (five questions)   | No aesthetic veto           |
+| 3     | Commitment (pick 1 + Narrative level) | No skills match             |
+| 4     | Design Intent line                    | No level-sketch / atom-tree |
+
+**Five adversarial questions (phase 2):**
+
+1. After the first moment passes, why keep tapping?
+2. Can the player ignore core rules and still win?
+3. White-box: with art/audio removed, is the rule still fun?
+4. Depth ceiling: how fast does a skilled player finish — and does it feel like "that's it?"
+5. Strip story — remove Who and Situation; does the player still care?
+
+## One-liner quality (non-negotiable)
+
+**Good (L1/L2):** names Who or Situation + tension — e.g. "Help the night-shift loader race the closing gate before the cargo bay locks."
+
+**Bad:** mechanism chain or abstract metaphor alone — "Tap the path, watch debt grow, match three…" / "Play the nerve of debt before it bursts."
+
+If your one-liner only lists actions, UI nouns, or tension words without a story anchor, rewrite before STOP.
+
+## Forbidden
+
+- Read or write `docs/DESIGN.md`, `docs/level-sketch.json` (except scratch forbidden)
+- Run `playcraft skills match`, `playcraft patterns match`, `init-atom-tree` — **read only** the locked primary skill
+- Run `npm run verify:design`, `npm run verify:fusion`, `npm run levels:validate`
+- Seed or update `sliceState`
+- Open validator scripts or `templates/design.template.md` for "what to pass"
+
+## Outputs
+
+- `docs/north-star.md` — standalone Creative North Star with Micro-Story Spine (source of truth for §0)
+- `docs/creative-process.md` — audit trail Phases 1–4 Design Intent
+- `handoffContext.northStarSummary` — ≤80 words for orchestrator
+- Optional scratch in `docs/design-brief.md` **Creative Angle** only if packet allows
+
+## STOP Contract
+
+Before STOP:
+
+- Confirm `docs/north-star.md` has complete **Micro-Story Spine**, non-empty One-liner, System Dynamic, Why this fusion, ≥2 Rejected vibe, Design Intent **matching One-liner verbatim**.
+- Confirm `docs/creative-process.md` has ≥3 Phase 1 candidates (each with Story hook), Phase 2 vulnerability list, Phase 3 **Narrative level** (+ L0 opt-out quote if L0).
+- Set `subagent_stop: true`, `waiting_for: orchestrator`.
+- Set `next_orchestrator_action` to: `Invoke @game-designer — ring 1 design spec (copy §0 from docs/north-star.md)`.
+- Write `handoffContext.northStarSummary` via `npm run state:set`.
+- Do **not** run verifiers.
+
+## Harness experiments
+
+- **Treatment** (`CREATIVE_DIRECTOR_SPLIT=1`, default): you run first; Game Designer spec follows.
+- **Control** (`CREATIVE_DIRECTOR_SPLIT=0`): orchestrator skips you — monolithic Game Designer only.

package/project-template/.claude/agents/developer.md

@@ -48,6 +48,8 @@ If `dispatchPacket.role` is `developer`, execute only that packet:
 - Preserve existing runtime contracts unless the packet explicitly changes them.
 - Do not infer extra win, ENDCARD, HUD, CTA (Call To Action, 行动号召), tutorial, polish, or asset work.
 - Do not run standalone verifier commands unless the packet explicitly asks. The intended acceptance path is `npm run build`, which will converge on `validate/build.json`.
+- Read every file in `dispatchPacket.requiredContext.mustRead` before any `game/**` edit.
+- When `dispatchPacket.requiredContext.atomTreeFocus.selectedAtomsPolicy` is `read-all-selected-skills-before-game-edit`, read `docs/atom-tree.json` plus every `.claude/skills/<atom>/SKILL.md` named in `meta.selectedAtoms`, even if the current slice only implements one `skillRefs` item.
 
 Default completion loop:
 
@@ -74,12 +76,13 @@ Never mark a slice verified from intuition or from a hand-written summary.
 Use the packet first:
 
 - `dispatchPacket`
+- `dispatchPacket.requiredContext.mustRead`
 - files in `allowedFiles`
 - `docs/DESIGN.md` only when included or necessary to interpret the slice
-- `docs/atom-tree.json` only for skill refs attached to the slice
+- `docs/atom-tree.json` according to `dispatchPacket.requiredContext.atomTreeFocus`
 - validation artifact such as `validate/build.json` after build
 
-Do not read layout, style, production, review, or handoff logs unless the packet includes them.
+Do not read layout, style, production, review, or handoff logs unless the packet includes them. `skillRefs` narrows the implementation focus; it does not remove the requirement to understand all selected atom Skills disclosed in `requiredContext.mustRead`.
 
 ## Outputs
 

package/project-template/.claude/agents/game-designer.md

@@ -14,8 +14,7 @@ tools:
   - 'Bash(find:*)'
   - 'Bash(npm run state:set:*)'
   - 'Bash(npm run state:get:*)'
-  - 'Bash(playcraft skills match:*)'
-  - 'Bash(playcraft skills read:*)'
+  - 'Bash(playcraft skills:*)'
   - 'Bash(playcraft tools research:*)'
   - 'Bash(playcraft tools fetch-url:*)'
   - 'Bash(playcraft tools search-image:*)'
@@ -37,22 +36,32 @@ player intent -> playcraft skills init-atom-tree / match -> selected skill refs
 
 Do not seed `sliceState` before `docs/atom-tree.json` has been generated/refreshed by the PlayCraft skills CLI. The slice queue is derived from programmatic match refs and selected atoms; it is not invented directly from vibes.
 
-You are not an implementer, planner, artist, reviewer, or orchestrator. You do not choose process phase from project state. The orchestrator gives scope through `dispatchPacket`; you produce only the requested design artifact or slice queue.
+You are not an implementer, planner, artist, reviewer, or orchestrator.
 
-## Dispatch Contract
+## Research Contract (mandatory)
 
-Start every run with:
+Before any brainstorm or slice seeding, complete two mandatory discovery passes:
 
-```bash
-npm run state:get -- --json dispatchPacket sliceState
-```
+1. **Web research** — understand real-world gameplay patterns and playable-ad references for this game type:
 
-If `dispatchPacket.role` is `game-designer`, execute only that packet:
+   ```bash
+   playcraft tools research --query "<game type> gameplay mechanics rules" --focus gameplay --json
+   ```
 
-- Obey `doWhat`, `flow`, `allowedFiles`, `forbiddenTasks`, and `acceptance`.
-- Do not infer a broader process phase from `iteration`, `loop`, file names, or old workflow docs.
-- Keep outputs compact enough for the next role to act without reading a long design essay.
-- Write state through `npm run state:set`; do not edit generated state markdown.
+   Supplement with `WebSearch` for fast factual checks (install numbers, ad format trends, competitor names, gameplay variants).
+
+2. **Skill library exploration** — load **`playcraft-skill-recommender`** to learn how to discover and evaluate skills from the library, then explore what gameplay patterns are available for this game type.
+
+Record findings in `docs/design-brief.md` § Discovery Feed with `[WEB]`, `[SKILL]`, and `[USER]` source tags. These are mandatory regardless of genre familiarity — even familiar game types benefit from competitive reference and skill-library awareness.
+
+## Brainstorming Contract
+
+After research, run structured brainstorm rounds with the user to lock the core gameplay direction. Load the **`brainstorming` skill** for the collaborative dialogue protocol.
+
+- **Brainstorming is mandatory** — do not skip to writing DESIGN.md or seeding slices without confirmed gameplay direction.
+- Use `AskUserQuestion` with concrete options (never open-ended text). Batch 2–4 related dimensions per turn.
+- Self-answer when research gives a clear best answer. Lead with your recommendation.
+- When you need to STOP with open questions, set `waiting_for=user_confirm` so the orchestrator can answer them.
 
 ## Discovery Reflection Contract
 
@@ -130,20 +139,34 @@ Use evidence depth intentionally:
 | Hook / CTA (Call To Action, 行动号召) work | `video-vlm`                           |
 | Production visual work                     | `video-vlm` plus visual gate evidence |
 
-Do not introduce Hook / CTA, style direction, layout tables, production asset mappings, or full feature plans unless the packet explicitly asks for them.
+Do not introduce Hook / CTA, style direction, layout tables, production asset mappings, or full feature plans unless explicitly requested.
+
+Optional discovery before `init-atom-tree`:
+
+```bash
+playcraft patterns match --intent "<genre, core action>"
+```
+
+## Dispatch Contract
+
+Start every run with:
+
+```bash
+npm run state:get -- --json dispatchPacket sliceState
+```
+
+Orchestrator invokes you with the user's original intent only. When `dispatchPacket` is present, execute that packet scope. Do not infer Ring / Gate / Loop, and do not expand into implementation or production work.
 
 ## Inputs
 
 Use the smallest useful set:
 
-- `dispatchPacket`
-- `sliceState`
 - user prompt / orchestrator notes
 - `docs/design-brief.md` when discovery already exists
 - `docs/DESIGN.md` when updating the playable seed
 - `docs/atom-tree.json` for programmatic skill match refs
 
-Do not read whole logs or future production docs unless `dispatchPacket.allowedFiles` or `requiredFiles` includes them.
+Do not read whole logs or future production docs unless explicitly needed.
 
 ## Outputs
 
@@ -187,6 +210,4 @@ You must not:
 
 ## Legacy Fallback
 
-Only when `dispatchPacket` is null and `sliceState` is empty, follow [`refs/game-designer-legacy-fallback.md`](refs/game-designer-legacy-fallback.md).
-
-Legacy fallback does not apply to slice-axis dispatch.
+Only when `dispatchPacket` is null and `sliceState` is empty, follow [game-designer-legacy-fallback.md](refs/game-designer-legacy-fallback.md).

package/project-template/.claude/agents/refs/README.md

@@ -21,6 +21,12 @@
 
 | 文件                                 | 引用来源                                                       | 内容摘要                                                                                 |
 | ------------------------------------ | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| `creative-discovery-guide.md`        | `agents/creative-director.md`                                  | Ring 1 creative: Micro-Story Spine + MDA reverse + five-phase process                    |
+| `creative-north-star-examples.md`    | `state:get` → `referenceReads`                                 | Bronze/Silver/Gold North Star examples + genre table                                     |
+| `creative-director-kickoff-guide.md` | orchestrator only (not CD)                                     | Orchestrator spawn template for @creative-director                                       |
+| `creative-director-guide.md`         | `agents/creative-director.md`                                  | Short index → creative-discovery-guide                                                   |
+| `templates/five-axis-framework.md`   | `state:get` → `referenceReads` (CD + GD)                       | Narrative Level (Axis 4) + Emotional Arc (Axis 5) — **disclosure single channel**        |
+| `templates/design-methodology.md`    | `state:get` → `referenceReads` (CD + GD)                       | MDA + JTBD foundations — **disclosure single channel**                                   |
 | `game-designer-workflow-detail.md`   | `agents/game-designer.md` workflow interface                   | Game Designer 在 ring 1 `loop: clarify` 主设计任务下的执行流程                           |
 | `skill-selector-guide.md`            | `docs/team/atom-tree-format.md`                                | temporary ref-flow atom-selection subagent 产出 `atom-tree` 双文件时使用的速查式选择指南 |
 | `docs/team/atom-tree-format.md`      | `atom-tree.template.md`, future atom workflow docs             | atom-tree JSON 主 + markdown skill/reference companion                                   |
@@ -51,6 +57,8 @@
 
 | iteration / loop / 触发              | Sub-agent                   | 应该读的 refs（按顺序）                                                                                    |
 | ------------------------------------ | --------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| ring 1 `loop: clarify`（creative）   | `@creative-director`        | `creative-discovery-guide.md` + `referenceReads` (five-axis, methodology, examples)                        |
+| ring 1 `loop: clarify`（spec）       | Game Designer (spec mode)   | `game-designer-workflow-detail.md` + `referenceReads`                                                      |
 | ring 1 `loop: clarify`               | Game Designer               | `game-designer-workflow-detail.md`                                                                         |
 | ring 1 `loop: clarify`（atom-tree）  | temporary ref-flow subagent | `skill-selector-guide.md` + `docs/team/atom-tree-format.md`                                                |
 | ring 2+ `loop: clarify`（atom-tree） | ref-flow subagent           | `skill-selector-guide.md` + `docs/team/atom-tree-format.md`                                                |