Feat/optimize naming (#2)

* Refactor project name from "Open Claude Design" to "Open Design" - Updated project name in package.json, package-lock.json, and README files. - Changed CLI commands and references from "ocd" to "od". - Adjusted file structure references in documentation and code to reflect new naming conventions. - Enhanced .gitignore to include new runtime data files. - Updated metadata in LICENSE file to match new project name. * Add contributing guidelines in English and Chinese - Introduced CONTRIBUTING.md and CONTRIBUTING.zh-CN.md to provide clear instructions for contributors. - Outlined contribution types, local setup instructions, and merging criteria for skills and design systems. - Enhanced README files to reference the new contributing guidelines. * Update README and documentation for deck framework directives - Clarified DECK_FRAMEWORK_DIRECTIVE description in both English and Chinese README files to specify conditions for deck kind without a skill seed. - Added detailed workflow instructions in deck-framework.ts to emphasize the importance of copying the framework before adding content. - Enhanced discovery.ts to reinforce the framework-first approach for deck projects. - Updated system.ts to ensure proper handling of deck projects with and without bound skills, preventing re-authorship of scaling and navigation logic. * Update README and documentation for deck framework directives - Clarified DECK_FRAMEWORK_DIRECTIVE description in both English and Chinese README files to specify conditions for deck kind without a skill seed. - Added detailed workflow instructions in deck-framework.ts to emphasize the importance of copying the framework before adding content. - Enhanced discovery.ts to reinforce the framework-first approach for deck projects. - Updated system.ts to ensure proper handling of deck projects with and without bound skills, preventing re-authorship of scaling and navigation logic.
2026-06-01 03:14:35 +07:00 · 2026-04-28 16:28:19 +08:00 · 2026-04-28 16:28:19 +08:00 · bc2198103a
commit bc2198103a
parent 6f6bf31dd2
9 changed files with 135 additions and 80 deletions
--- a/README.md
+++ b/README.md
@ -211,7 +211,7 @@ DISCOVERY directives  (turn-1 form, turn-2 brand branch, TodoWrite, 5-dim critiq
  + active SKILL.md    (19 skills available)
  + project metadata   (kind, fidelity, speakerNotes, animations, inspiration ids)
  + skill side files   (auto-injected pre-flight: read assets/template.html + references/*.md)
-  + (deck mode only)   DECK_FRAMEWORK_DIRECTIVE   (nav / counter / scroll / print)
+  + (deck kind, no skill seed) DECK_FRAMEWORK_DIRECTIVE   (nav / counter / scroll / print)
 ```

 Every layer is composable. Every layer is a file you can edit. Read [`src/prompts/system.ts`](src/prompts/system.ts) and [`src/prompts/discovery.ts`](src/prompts/discovery.ts) to see the actual contract.
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@ -211,7 +211,7 @@ DISCOVERY 指令         （turn-1 表单、turn-2 品牌分支、TodoWrite、
  + 激活的 SKILL.md    （19 套备选）
  + 项目元数据          （kind、fidelity、speakerNotes、animations、灵感 system id）
  + Skill 副文件       （自动注入 pre-flight：先读 assets/template.html + references/*.md）
-  + （仅 deck 模式）    DECK_FRAMEWORK_DIRECTIVE   （nav / counter / scroll / print）
+  + （deck kind 且无 skill 种子时） DECK_FRAMEWORK_DIRECTIVE   （nav / counter / scroll / print）
 ```

 每一层都可组合。每一层都是一个你能改的文件。看 [`src/prompts/system.ts`](src/prompts/system.ts) 和 [`src/prompts/discovery.ts`](src/prompts/discovery.ts) 就知道真实契约长什么样。
--- a/daemon/skills.js
+++ b/daemon/skills.js
@ -2,9 +2,9 @@
 // front-matter, returns listing. No watching in this MVP — re-scans on every
 // GET /api/skills, which is fine for dozens of skills.

-import { readdir, readFile, stat } from 'node:fs/promises';
-import path from 'node:path';
-import { parseFrontmatter } from './frontmatter.js';
+import { readdir, readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { parseFrontmatter } from "./frontmatter.js";

 export async function listSkills(skillsRoot) {
  const out = [];
@ -17,26 +17,32 @@ export async function listSkills(skillsRoot) {
  for (const entry of entries) {
    if (!entry.isDirectory()) continue;
    const dir = path.join(skillsRoot, entry.name);
-    const skillPath = path.join(dir, 'SKILL.md');
+    const skillPath = path.join(dir, "SKILL.md");
    try {
      const stats = await stat(skillPath);
      if (!stats.isFile()) continue;
-      const raw = await readFile(skillPath, 'utf8');
+      const raw = await readFile(skillPath, "utf8");
      const { data, body } = parseFrontmatter(raw);
      const hasAttachments = await dirHasAttachments(dir);
      const mode = data.od?.mode || inferMode(body, data.description);
      out.push({
        id: data.name || entry.name,
        name: data.name || entry.name,
-        description: data.description || '',
+        description: data.description || "",
        triggers: Array.isArray(data.triggers) ? data.triggers : [],
        mode,
-        platform: normalizePlatform(data.od?.platform, mode, body, data.description),
+        platform: normalizePlatform(
+          data.od?.platform,
+          mode,
+          body,
+          data.description
+        ),
        scenario: normalizeScenario(data.od?.scenario, body, data.description),
-        previewType: data.od?.preview?.type || 'html',
+        previewType: data.od?.preview?.type || "html",
        designSystemRequired: data.od?.design_system?.requires ?? true,
        defaultFor: normalizeDefaultFor(data.od?.default_for),
-        upstream: typeof data.od?.upstream === 'string' ? data.od.upstream : null,
+        upstream:
+          typeof data.od?.upstream === "string" ? data.od.upstream : null,
        featured: normalizeFeatured(data.od?.featured),
        // Optional metadata hints used by 'Use this prompt' fast-create so
        // the resulting project mirrors the shipped example.html. Each hint
@ -63,15 +69,15 @@ export async function listSkills(skillsRoot) {
 // open those files via absolute paths.
 function withSkillRootPreamble(body, dir) {
  const preamble = [
-    '> **Skill root (absolute):** `' + dir + '`',
-    '>',
-    '> This skill ships side files alongside `SKILL.md`. When the workflow',
-    '> below references relative paths such as `assets/template.html` or',
-    '> `references/layouts.md`, resolve them against the skill root above and',
-    '> open them via their full absolute path.',
-    '',
-    '',
-  ].join('\n');
+    "> **Skill root (absolute):** `" + dir + "`",
+    ">",
+    "> This skill ships side files alongside `SKILL.md`. When the workflow",
+    "> below references relative paths such as `assets/template.html` or",
+    "> `references/layouts.md`, resolve them against the skill root above and",
+    "> open them via their full absolute path.",
+    "",
+    "",
+  ].join("\n");
  return preamble + body;
 }

@ -79,7 +85,9 @@ async function dirHasAttachments(dir) {
  try {
    const entries = await readdir(dir, { withFileTypes: true });
    return entries.some(
-      (e) => e.name !== 'SKILL.md' && (e.isDirectory() || /\.(md|html|css|js|json|txt)$/i.test(e.name)),
+      (e) =>
+        e.name !== "SKILL.md" &&
+        (e.isDirectory() || /\.(md|html|css|js|json|txt)$/i.test(e.name))
    );
  } catch {
    return false;
@ -96,7 +104,7 @@ function normalizeDefaultFor(value) {
 // 'high-fidelity' are meaningful — anything else collapses to null so the
 // caller falls back to the form default ('high-fidelity').
 function normalizeFidelity(value) {
-  if (value === 'wireframe' || value === 'high-fidelity') return value;
+  if (value === "wireframe" || value === "high-fidelity") return value;
  return null;
 }

@ -104,11 +112,11 @@ function normalizeFidelity(value) {
 // to a real boolean. Returns null for anything we can't interpret so the
 // caller knows to fall back to the form default.
 function normalizeBoolHint(value) {
-  if (typeof value === 'boolean') return value;
-  if (typeof value === 'string') {
+  if (typeof value === "boolean") return value;
+  if (typeof value === "string") {
    const v = value.trim().toLowerCase();
-    if (v === 'true' || v === 'yes' || v === '1') return true;
-    if (v === 'false' || v === 'no' || v === '0') return false;
+    if (v === "true" || v === "yes" || v === "1") return true;
+    if (v === "false" || v === "no" || v === "0") return false;
  }
  return null;
 }
@ -119,8 +127,8 @@ function normalizeBoolHint(value) {
 // natural alphabetical order.
 function normalizeFeatured(value) {
  if (value === true) return 1;
-  if (typeof value === 'number' && Number.isFinite(value)) return value;
-  if (typeof value === 'string' && value.trim()) {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value === "string" && value.trim()) {
    const n = Number(value);
    if (Number.isFinite(n)) return n;
  }
@ -133,66 +141,70 @@ function normalizeFeatured(value) {
 // serves as a passable starter prompt.
 function derivePrompt(data) {
  const explicit = data.od?.example_prompt;
-  if (typeof explicit === 'string' && explicit.trim()) return explicit.trim();
-  const desc = typeof data.description === 'string' ? data.description.trim() : '';
-  if (!desc) return '';
-  const collapsed = desc.replace(/\s+/g, ' ').trim();
+  if (typeof explicit === "string" && explicit.trim()) return explicit.trim();
+  const desc =
+    typeof data.description === "string" ? data.description.trim() : "";
+  if (!desc) return "";
+  const collapsed = desc.replace(/\s+/g, " ").trim();
  const firstSentence = collapsed.match(/^.+?[.!?。！？](?:\s|$)/)?.[0]?.trim();
  return (firstSentence || collapsed).slice(0, 320);
 }

 function inferMode(body, description) {
-  const hay = `${description ?? ''}\n${body ?? ''}`.toLowerCase();
-  if (/\bppt|deck|slide|presentation|幻灯|投影/.test(hay)) return 'deck';
-  if (/\bdesign[- ]system|\bdesign\.md|\bdesign tokens/.test(hay)) return 'design-system';
-  if (/\btemplate\b/.test(hay)) return 'template';
-  return 'prototype';
+  const hay = `${description ?? ""}\n${body ?? ""}`.toLowerCase();
+  if (/\bppt|deck|slide|presentation|幻灯|投影/.test(hay)) return "deck";
+  if (/\bdesign[- ]system|\bdesign\.md|\bdesign tokens/.test(hay))
+    return "design-system";
+  if (/\btemplate\b/.test(hay)) return "template";
+  return "prototype";
 }

 // Validate platform tag — only desktop / mobile are meaningful for the
 // Examples gallery. Falls back to autodetecting "mobile" from descriptions
 // so legacy skills sort under the right pill without authoring changes.
 function normalizePlatform(value, mode, body, description) {
-  if (value === 'desktop' || value === 'mobile') return value;
-  if (mode !== 'prototype') return null;
-  const hay = `${description ?? ''}\n${body ?? ''}`.toLowerCase();
-  if (/mobile|phone|ios|android|手机|移动端/.test(hay)) return 'mobile';
-  return 'desktop';
+  if (value === "desktop" || value === "mobile") return value;
+  if (mode !== "prototype") return null;
+  const hay = `${description ?? ""}\n${body ?? ""}`.toLowerCase();
+  if (/mobile|phone|ios|android|手机|移动端/.test(hay)) return "mobile";
+  return "desktop";
 }

 // Normalise a scenario tag to a small fixed vocabulary so the filter pills
 // stay tidy. Unknown values pass through verbatim so authors can experiment;
 // missing values default to "general".
 const KNOWN_SCENARIOS = new Set([
-  'general',
-  'engineering',
-  'product',
-  'design',
-  'marketing',
-  'sales',
-  'finance',
-  'hr',
-  'operations',
-  'support',
-  'legal',
-  'education',
-  'personal',
+  "general",
+  "engineering",
+  "product",
+  "design",
+  "marketing",
+  "sales",
+  "finance",
+  "hr",
+  "operations",
+  "support",
+  "legal",
+  "education",
+  "personal",
 ]);
 function normalizeScenario(value, body, description) {
-  if (typeof value === 'string') {
+  if (typeof value === "string") {
    const v = value.trim().toLowerCase();
    if (v) return v;
  }
-  const hay = `${description ?? ''}\n${body ?? ''}`.toLowerCase();
-  if (/finance|invoice|expense|budget|p&l|revenue/.test(hay)) return 'finance';
-  if (/\bhr\b|onboarding|payroll|employee|人事/.test(hay)) return 'hr';
-  if (/marketing|campaign|brand|landing/.test(hay)) return 'marketing';
-  if (/runbook|incident|deploy|engineering|sre|api/.test(hay)) return 'engineering';
-  if (/spec|prd|roadmap|product manager|product team/.test(hay)) return 'product';
-  if (/design system|moodboard|mockup|ui kit/.test(hay)) return 'design';
-  if (/sales|quote|proposal|lead/.test(hay)) return 'sales';
-  if (/operations|ops|logistics|inventory/.test(hay)) return 'operations';
-  return 'general';
+  const hay = `${description ?? ""}\n${body ?? ""}`.toLowerCase();
+  if (/finance|invoice|expense|budget|p&l|revenue/.test(hay)) return "finance";
+  if (/\bhr\b|onboarding|payroll|employee|人事/.test(hay)) return "hr";
+  if (/marketing|campaign|brand|landing/.test(hay)) return "marketing";
+  if (/runbook|incident|deploy|engineering|sre|api/.test(hay))
+    return "engineering";
+  if (/spec|prd|roadmap|product manager|product team/.test(hay))
+    return "product";
+  if (/design system|moodboard|mockup|ui kit/.test(hay)) return "design";
+  if (/sales|quote|proposal|lead/.test(hay)) return "sales";
+  if (/operations|ops|logistics|inventory/.test(hay)) return "operations";
+  return "general";
 }
 // Surface the vocabulary so callers (frontend filter UI) could mirror it
 // later if they want to. Not exported today, kept here for documentation.
--- a/docs/assets/banner.png
+++ b/docs/assets/banner.png
--- a/docs/assets/design-systems-library.png
+++ b/docs/assets/design-systems-library.png
--- a/src/prompts/deck-framework.ts
+++ b/src/prompts/deck-framework.ts
@ -313,6 +313,22 @@ Decks regress when each turn re-authors the scale-to-fit logic, the keyboard han

 **You do not write any of that. You do not modify any of that.** Your job is to fill content slots only.

+## Workflow — copy framework first, then fill content
+
+When the user asks for slides, your TodoWrite plan **must** start with "copy the deck framework verbatim" before any content step. The intended order is:
+
+\`\`\`
+1.  Bind the active direction's palette + fonts to :root in the framework
+2.  Copy the canonical skeleton below as index.html (nothing else first)
+3.  Plan the slide arc and theme rhythm (state aloud before writing)
+4.  Add per-deck classes inside the second <style> block
+5.  Replace each <section class="slide"> SLOT with real content
+6.  Self-check (no rewriting framework chrome / @media print / nav script)
+7.  Emit single <artifact>
+\`\`\`
+
+If you find yourself writing \`<style>\` rules for \`.deck-shell\`, \`.deck-stage\`, \`.slide\`, \`.canvas\`, \`fit()\`, \`@media print\`, or a keyboard handler — STOP. The framework already has them. Re-read this directive, then keep going from "fill SLOT content".
+
 ## The contract

 When you start a new deck, your output is a single HTML file built from the canonical skeleton below. **Copy the skeleton verbatim**, including its first \`<style>\` block, the \`.deck-shell\` / \`.deck-stage\` / \`.deck-counter\` / \`.deck-hint\` chrome, and the entire trailing \`<script>\`.
--- a/src/prompts/discovery.ts
+++ b/src/prompts/discovery.ts
@ -142,6 +142,8 @@ The standard plan template (adapt the middle steps to the brief):
 - 9.  Emit single <artifact>
 \`\`\`

+**Decks especially — framework first, content second.** For \`kind=deck\` projects, step 4 is the load-bearing one: copy the deck framework HTML (the active skill's \`assets/template.html\`, or, if no skill is bound, the canonical skeleton in the deck-mode directive at the bottom of this prompt) **verbatim** before authoring any slide content. Do NOT write your own scale-to-fit logic, keyboard handler, slide visibility toggle, counter, or print stylesheet — every freeform attempt at this re-introduces the same iframe positioning / scaling bugs we have already fixed in the framework. Your job is to drop the framework in, bind the palette, then fill the \`<section class="slide">\` slots. That's it.
+
 After TodoWrite, immediately update — **mark step 1 \`in_progress\` before starting it, \`completed\` the moment it's done, mark step 2 \`in_progress\`**, etc. Do not batch updates at the end of the turn; the live progress is the point. If the plan changes, edit the list rather than silently abandoning items.

 Step 7 (checklist) and step 8 (critique) are non-negotiable.
--- a/src/prompts/system.ts
+++ b/src/prompts/system.ts
@ -14,11 +14,17 @@
 *      (`assets/template.html`) and references (`references/layouts.md`,
 *      `references/checklist.md`), we inject a hard pre-flight rule above
 *      the skill body so the agent reads them BEFORE writing any code.
- *   4. For decks (skillMode === 'deck'), the deck framework directive
- *      (./deck-framework.ts) is pinned LAST so it overrides any softer
- *      slide-handling wording earlier in the stack — this is the
- *      load-bearing nav / counter / scroll JS / print stylesheet contract
- *      that PDF stitching depends on.
+ *   4. For decks (skillMode === 'deck' OR metadata.kind === 'deck'), the
+ *      deck framework directive (./deck-framework.ts) is pinned LAST so it
+ *      overrides any softer slide-handling wording earlier in the stack —
+ *      this is the load-bearing nav / counter / scroll JS / print
+ *      stylesheet contract that PDF stitching depends on. We also fire on
+ *      the metadata path so deck-kind projects without a bound skill
+ *      (skill_id null) still get a framework, instead of having the agent
+ *      re-author scaling / nav / print logic from scratch each turn. When
+ *      the active skill ships its own seed (skill body references
+ *      `assets/template.html`), we defer to that seed and skip the generic
+ *      skeleton — the skill's framework wins to avoid double-injection.
 *
 * The composed string is what the daemon sees as `systemPrompt` and what
 * the Anthropic path sends as `system`.
@ -85,7 +91,23 @@ export function composeSystemPrompt({
  // Decks have a load-bearing framework (nav, counter, scroll JS, print
  // stylesheet for PDF stitching). Pin it last so it overrides any softer
  // wording earlier in the stack ("write a script that handles arrows…").
-  if (skillMode === 'deck') {
+  //
+  // We fire on either (a) the active skill is a deck skill OR (b) the
+  // project metadata declares kind=deck. Case (b) catches projects created
+  // without a skill (skill_id null) — without this, a deck-kind project
+  // with no bound skill gets neither a skill seed nor the framework
+  // skeleton, and the agent writes scaling / nav / print logic from scratch
+  // with the same buggy `place-items: center` + transform pattern we keep
+  // having to fix at runtime. Skill seeds (when present) win — they
+  // already define their own opinionated framework (simple-deck's
+  // scroll-snap, guizang-ppt's magazine layout) and re-pinning the generic
+  // skeleton would conflict. The skill-seed path takes over via
+  // `derivePreflight` above, so we only fire the generic skeleton when no
+  // skill seed is on offer.
+  const isDeckProject = skillMode === 'deck' || metadata?.kind === 'deck';
+  const hasSkillSeed =
+    !!skillBody && /assets\/template\.html/.test(skillBody);
+  if (isDeckProject && !hasSkillSeed) {
    parts.push(`\n\n---\n\n${DECK_FRAMEWORK_DIRECTIVE}`);
  }

--- a/src/runtime/srcdoc.ts
+++ b/src/runtime/srcdoc.ts
@ -16,10 +16,10 @@
 */
 export function buildSrcdoc(
  html: string,
-  options: { deck?: boolean } = {},
+  options: { deck?: boolean } = {}
 ): string {
  const head = html.trimStart().slice(0, 64).toLowerCase();
-  const isFullDoc = head.startsWith('<!doctype') || head.startsWith('<html');
+  const isFullDoc = head.startsWith("<!doctype") || head.startsWith("<html");
  const wrapped = isFullDoc
    ? html
    : `<!doctype html>
@ -68,8 +68,10 @@ function injectSandboxShim(doc: string): string {
  tryShim('localStorage');
  tryShim('sessionStorage');
 })();</script>`;
-  if (/<head[^>]*>/i.test(doc)) return doc.replace(/<head[^>]*>/i, (m) => `${m}${shim}`);
-  if (/<body[^>]*>/i.test(doc)) return doc.replace(/<body[^>]*>/i, (m) => `${m}${shim}`);
+  if (/<head[^>]*>/i.test(doc))
+    return doc.replace(/<head[^>]*>/i, (m) => `${m}${shim}`);
+  if (/<body[^>]*>/i.test(doc))
+    return doc.replace(/<body[^>]*>/i, (m) => `${m}${shim}`);
  return shim + doc;
 }

@ -101,10 +103,10 @@ function injectDeckBridge(doc: string): string {
 .stage, .deck-stage, .deck-shell { place-content: center !important; }
 </style>`;
  const docWithStyle = /<\/head>/i.test(doc)
-    ? doc.replace(/<\/head>/i, styleFix + '</head>')
+    ? doc.replace(/<\/head>/i, styleFix + "</head>")
    : /<head[^>]*>/i.test(doc)
-      ? doc.replace(/<head[^>]*>/i, (m) => m + styleFix)
-      : styleFix + doc;
+    ? doc.replace(/<head[^>]*>/i, (m) => m + styleFix)
+    : styleFix + doc;
  doc = docWithStyle;
  const script = `<script>(function(){
  function slides(){ return document.querySelectorAll('.slide'); }
@ -265,6 +267,7 @@ function injectDeckBridge(doc: string): string {
  }
  observeSlides();
 })();</script>`;
-  if (/<\/body>/i.test(doc)) return doc.replace(/<\/body>/i, `${script}</body>`);
+  if (/<\/body>/i.test(doc))
+    return doc.replace(/<\/body>/i, `${script}</body>`);
  return doc + script;
 }