@xulthekl/team-flow 0.22.4

package/scripts/lib/platforms.mjs

@@ -0,0 +1,165 @@
+// scripts/lib/platforms.mjs
+// Platform registry for team-flow cross-platform installers.
+//
+// All paths verified against comet (https://github.com/rpamis/comet)
+// src/core/platforms.ts and each platform's documented conventions.
+// team-flow's guard mechanism is the phase-guard RULE file (auto-included
+// by the platform), not a PreToolUse hook; therefore `supportsHooks`/
+// `hookFormat` are recorded for documentation accuracy only — the shared
+// installer does not write hook configs for these platforms (SessionStart
+// wiring is deferred until each platform's session-start support is
+// individually verified).
+
+import { join } from 'node:path';
+
+/**
+ * @typedef {Object} PlatformConfig
+ * @property {string} id              - platform identifier (cli arg / install-<id>)
+ * @property {string} name            - human-readable name
+ * @property {string} skillsDir       - project-local skills base dir (e.g. '.cline')
+ * @property {string} [globalSkillsDir] - global (user-level) skills base dir
+ * @property {string} [rulesBaseDir]  - base dir for rules; '' = project root;
+ *                                      defaults to skillsDir when omitted
+ * @property {string} [rulesDir]      - rules subdirectory (omit => no rules)
+ * @property {'md'|'mdc'|'copilot'} [rulesFormat] - rule file format
+ * @property {boolean} [supportsHooks]   - platform supports hooks (info only)
+ * @property {string} [hookFormat]       - native hook config format (info only)
+ * @property {string} [notes]            - install / usage notes
+ */
+
+/** Platforms added by the v0.8.13 platform-expansion PR. */
+export const NEW_PLATFORMS = [
+  {
+    id: 'cline',
+    name: 'Cline',
+    skillsDir: '.cline',
+    globalSkillsDir: '.cline',
+    // Cline reads .clinerules/*.md at project root (not inside .cline/).
+    rulesBaseDir: '',
+    rulesDir: '.clinerules',
+    rulesFormat: 'md',
+    supportsHooks: false,
+    notes: 'Cline auto-includes .clinerules/*.md as always-on context.',
+  },
+  {
+    id: 'kiro',
+    name: 'Kiro',
+    skillsDir: '.kiro',
+    globalSkillsDir: '.kiro',
+    rulesDir: 'steering',
+    rulesFormat: 'md',
+    supportsHooks: true,
+    hookFormat: 'kiro',
+    notes: 'AWS Kiro IDE reads .kiro/steering/*.md as steering rules.',
+  },
+  {
+    id: 'windsurf',
+    name: 'Windsurf',
+    skillsDir: '.windsurf',
+    globalSkillsDir: '.windsurf',
+    rulesDir: 'rules',
+    rulesFormat: 'md',
+    supportsHooks: true,
+    hookFormat: 'windsurf',
+    notes: 'Codeium Windsurf reads .windsurf/rules/*.md as rules.',
+  },
+  {
+    id: 'qwen',
+    name: 'Qwen Code',
+    skillsDir: '.qwen',
+    globalSkillsDir: '.qwen',
+    rulesDir: 'rules',
+    rulesFormat: 'md',
+    supportsHooks: true,
+    hookFormat: 'qwen',
+    notes: 'Qwen Code CLI (Gemini CLI fork) reads .qwen/rules/*.md.',
+  },
+  {
+    id: 'amazon-q',
+    name: 'Amazon Q Developer',
+    skillsDir: '.amazonq',
+    globalSkillsDir: '.amazonq',
+    rulesDir: 'rules',
+    rulesFormat: 'md',
+    supportsHooks: true,
+    hookFormat: 'claude-code',
+    notes: 'Amazon Q Developer CLI reads .amazonq/rules/*.md as rules.',
+  },
+  {
+    id: 'roocode',
+    name: 'Roo Code',
+    skillsDir: '.roo',
+    globalSkillsDir: '.roo',
+    rulesDir: 'rules',
+    rulesFormat: 'md',
+    supportsHooks: false,
+    notes: 'Roo Code (Roo Cline) reads .roo/rules/*.md as rules.',
+  },
+  {
+    id: 'continue',
+    name: 'Continue',
+    skillsDir: '.continue',
+    globalSkillsDir: '.continue',
+    rulesDir: 'rules',
+    rulesFormat: 'md',
+    supportsHooks: false,
+    notes: 'Continue (VS Code) reads .continue/rules/*.md as rules.',
+  },
+  {
+    id: 'pi',
+    name: 'Pi',
+    skillsDir: '.pi',
+    globalSkillsDir: '.pi/agent',
+    // Pi has no rules directory — skills-only deployment.
+    rulesDir: undefined,
+    rulesFormat: undefined,
+    supportsHooks: false,
+    notes: 'Pi agent reads skills from .pi/ (global: .pi/agent/). No rules dir; invoke "/workflow-start" manually.',
+  },
+  {
+    id: 'qoder',
+    name: 'Qoder',
+    skillsDir: '.qoder',
+    globalSkillsDir: '.qoder',
+    rulesDir: 'rules',
+    rulesFormat: 'md',
+    supportsHooks: false,
+    notes: 'Qoder reads .qoder/rules/*.md as rules.',
+  },
+];
+
+/** Lookup a new platform config by id. */
+export function getPlatform(id) {
+  const p = NEW_PLATFORMS.find(x => x.id === id);
+  if (!p) {
+    throw new Error(
+      `Unknown platform: "${id}". Available: ${NEW_PLATFORMS.map(x => x.id).join(', ')}`,
+    );
+  }
+  return p;
+}
+
+/** All platform ids added by this PR. */
+export const NEW_PLATFORM_IDS = NEW_PLATFORMS.map(p => p.id);
+
+/**
+ * Compute the project-local rules target directory for a platform.
+ * Mirrors comet: rules go to (rulesBaseDir || skillsDir)/rulesDir.
+ * For Cline, rulesBaseDir='' places .clinerules/ at project root.
+ */
+export function rulesTargetDir(platform, targetRoot) {
+  if (!platform.rulesDir) return null;
+  const base = platform.rulesBaseDir !== undefined ? platform.rulesBaseDir : platform.skillsDir;
+  // join(targetRoot, '', '.clinerules') === targetRoot/.clinerules
+  return join(targetRoot, base, platform.rulesDir);
+}
+
+/** Phase-guard rule file name for a rules format. */
+export function phaseGuardFileName(rulesFormat) {
+  switch (rulesFormat) {
+    case 'mdc': return 'phase-guard.mdc';
+    case 'copilot': return 'team-flow.instructions.md';
+    case 'md':
+    default: return 'phase-guard.md';
+  }
+}

package/scripts/lib/prototype-sync.mjs

@@ -0,0 +1,192 @@
+#!/usr/bin/env node
+/**
+ * prototype-sync — change 完成后将 UX 增量合并回全局 prototype/ + design-system.md
+ *
+ * v0.3 定义，v0.5 实现为 CLI 子命令
+ * 用法：tf prototype-sync <change-dir> --source <ux-delta-path>
+ *
+ * 功能：
+ * 1. 读取 change 的 UX 增量（从 execution-contract.md 或指定 --source 路径）
+ * 2. 合并进全局 prototype/（pages/components/assets/flow.md）
+ * 3. 若涉及设计系统迭代（新组件/token/anti-pattern），合并进 prototype/design-system.md
+ * 4. 输出合并报告
+ *
+ * 回写顺序：arch-merge → prototype-sync（同一 change closing 内，顺序提交）
+ */
+
+import { readFileSync, writeFileSync, existsSync, cpSync, mkdirSync } from 'node:fs';
+import { join, basename, relative } from 'node:path';
+
+/**
+ * 解析 CLI 参数数组为结构化对象
+ * @param {string[]} argv - 原始参数数组，如 ['changes/my-change/', '--source', 'delta.md']
+ * @returns {{ _: string[], source?: string, prototypeDir?: string }}
+ */
+function parseArgv(argv) {
+  const parsed = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--source' && argv[i + 1] && !argv[i + 1].startsWith('--')) {
+      parsed.source = argv[++i];
+    } else if (argv[i] === '--prototype-dir' && argv[i + 1] && !argv[i + 1].startsWith('--')) {
+      parsed.prototypeDir = argv[++i];
+    } else if (!argv[i].startsWith('--')) {
+      parsed._.push(argv[i]);
+    }
+  }
+  return parsed;
+}
+
+/**
+ * 执行 prototype-sync 合并
+ * @param {string[]|object} args - CLI 参数数组（从 tf 框架传入）或已解析的对象
+ * @returns {{ synced: boolean, pages?: number, components?: number, designSystem?: boolean, conflicts?: string[], reason?: string }}
+ */
+export function run(args = {}) {
+  // 支持两种调用方式：数组（CLI 框架 mod.run(commandArgs)）或对象（直接调用）
+  if (Array.isArray(args)) {
+    args = parseArgv(args);
+  }
+
+  const changeDir = args._?.[0] || args.changeDir;
+  const sourcePath = args.source;
+  const prototypeDir = args.prototypeDir || 'prototype';
+
+  if (!changeDir) {
+    console.error('Usage: tf prototype-sync <change-dir> [--source <ux-delta-path>] [--prototype-dir <path>]');
+    process.exit(1);
+  }
+
+  // 1. 确定 UX 增量来源
+  let uxDeltaContent = '';
+  let uxDeltaSource = '';
+
+  if (sourcePath && existsSync(sourcePath)) {
+    uxDeltaContent = readFileSync(sourcePath, 'utf-8');
+    uxDeltaSource = sourcePath;
+  } else {
+    // 默认从 execution-contract.md 提取 UX 增量
+    const contractPath = join(changeDir, 'execution-contract.md');
+    if (existsSync(contractPath)) {
+      const contract = readFileSync(contractPath, 'utf-8');
+      // 提取 UX 相关章节（## UX 增量 或 ## Prototype Changes）
+      const uxMatch = contract.match(/## (?:UX 增量|Prototype Changes|UX Delta)\n([\s\S]*?)(?=\n## |\n---|\n$)/);
+      if (uxMatch) {
+        uxDeltaContent = uxMatch[1].trim();
+        uxDeltaSource = contractPath;
+      }
+    }
+  }
+
+  if (!uxDeltaContent) {
+    console.log('No UX delta found in change, nothing to sync');
+    return { synced: false, reason: 'no-ux-delta' };
+  }
+
+  console.log(`UX delta source: ${uxDeltaSource}`);
+
+  // 2. 确保全局 prototype/ 目录存在
+  if (!existsSync(prototypeDir)) {
+    console.log(`Creating prototype directory: ${prototypeDir}`);
+    mkdirSync(prototypeDir, { recursive: true });
+    mkdirSync(join(prototypeDir, 'pages'), { recursive: true });
+    mkdirSync(join(prototypeDir, 'components'), { recursive: true });
+    mkdirSync(join(prototypeDir, 'assets'), { recursive: true });
+  }
+
+  // 3. 解析 UX 增量中的文件操作
+  // UX 增量格式约定：
+  // - 新增页面：`[ADD] pages/xxx.html`
+  // - 修改页面：`[MODIFY] pages/xxx.html`
+  // - 新增组件：`[ADD] components/xxx.html`
+  // - 设计系统更新：`[DS] design-system.md` + 具体内容
+  const operations = [];
+  const lines = uxDeltaContent.split('\n');
+  let currentOp = null;
+  let currentContent = [];
+
+  for (const line of lines) {
+    const opMatch = line.match(/^\[(ADD|MODIFY|DS)\]\s+(.+)$/);
+    if (opMatch) {
+      if (currentOp) {
+        operations.push({ ...currentOp, content: currentContent.join('\n') });
+      }
+      currentOp = { action: opMatch[1], target: opMatch[2].trim() };
+      currentContent = [];
+    } else if (currentOp) {
+      currentContent.push(line);
+    }
+  }
+  if (currentOp) {
+    operations.push({ ...currentOp, content: currentContent.join('\n') });
+  }
+
+  // 4. 执行合并
+  const report = { synced: true, pages: 0, components: 0, designSystem: false, conflicts: [] };
+
+  for (const op of operations) {
+    const targetPath = join(prototypeDir, op.target);
+
+    if (op.action === 'DS') {
+      // 设计系统更新
+      const dsPath = join(prototypeDir, 'design-system.md');
+      if (existsSync(dsPath)) {
+        const existing = readFileSync(dsPath, 'utf-8');
+        // 追加到 design-system.md 末尾（不覆盖，避免冲突）
+        writeFileSync(dsPath, existing + '\n\n<!-- prototype-sync: ' + new Date().toISOString().slice(0, 10) + ' -->\n' + op.content + '\n', 'utf-8');
+      } else {
+        writeFileSync(dsPath, op.content, 'utf-8');
+      }
+      report.designSystem = true;
+      console.log(`  [DS] Updated design-system.md`);
+      continue;
+    }
+
+    // 页面/组件文件操作
+    if (op.action === 'ADD' && existsSync(targetPath)) {
+      report.conflicts.push(`ADD conflict: ${op.target} already exists`);
+      console.log(`  [CONFLICT] ${op.target} already exists, skipping ADD`);
+      continue;
+    }
+
+    // 确保目录存在
+    const targetDir = join(prototypeDir, op.target.includes('/') ? op.target.split('/').slice(0, -1).join('/') : '');
+    if (targetDir && !existsSync(targetDir)) {
+      mkdirSync(targetDir, { recursive: true });
+    }
+
+    writeFileSync(targetPath, op.content, 'utf-8');
+
+    if (op.target.startsWith('pages/')) report.pages++;
+    if (op.target.startsWith('components/')) report.components++;
+    console.log(`  [${op.action}] ${op.target}`);
+  }
+
+  // 5. 输出合并报告
+  console.log(`\nPrototype sync complete:`);
+  console.log(`  Pages: ${report.pages} synced`);
+  console.log(`  Components: ${report.components} synced`);
+  console.log(`  Design system: ${report.designSystem ? 'updated' : 'unchanged'}`);
+  if (report.conflicts.length > 0) {
+    console.log(`  Conflicts: ${report.conflicts.length}`);
+    for (const c of report.conflicts) {
+      console.log(`    - ${c}`);
+    }
+  }
+
+  return report;
+}
+
+// 支持直接执行：node prototype-sync.mjs <change-dir> --source <path>
+if (process.argv[1]?.includes('prototype-sync')) {
+  const args = { _: [] };
+  for (let i = 2; i < process.argv.length; i++) {
+    if (process.argv[i].startsWith('--')) {
+      const key = process.argv[i].replace('--', '');
+      const val = process.argv[i + 1] && !process.argv[i + 1].startsWith('--') ? process.argv[++i] : true;
+      args[key] = val;
+    } else {
+      args._.push(process.argv[i]);
+    }
+  }
+  run(args);
+}

package/scripts/lib/sdd-overlay.mjs

@@ -0,0 +1,262 @@
+import { createHash, randomUUID } from 'node:crypto';
+import {
+  existsSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync,
+} from 'node:fs';
+import { dirname, join } from 'node:path';
+import { computeArtifactsHash } from './hash.mjs';
+import { readState } from './state-loader.mjs';
+
+export const HANDOFF_TYPES = new Set(['prototype', 'research', 'experiment']);
+export const HANDOFF_DECISIONS = new Set(['accept', 'reject', 'defer']);
+export const RESULT_HEADINGS = [
+  'Conclusion', 'Evidence', 'Produced Artifacts', 'Risks', 'Suggested Changes',
+];
+const HANDOFF_RESULT_FILE = 'HANDOFF_RESULT.md';
+
+export function getOverlayPaths(changeDir) {
+  const root = join(changeDir, '.superpowers', 'sdd');
+  return {
+    root,
+    checkpoints: join(root, 'checkpoints'),
+    handoffs: join(root, 'handoffs'),
+    executionPlan: join(root, 'execution-plan.json'),
+    executionRecommendation: join(root, 'execution-recommendation.json'),
+    reviews: join(root, 'reviews'),
+  };
+}
+
+export function computeTaskHash(changeDir, taskId) {
+  const tasks = readFileSync(join(changeDir, 'tasks.md'), 'utf8');
+  const escaped = taskId.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const match = tasks.match(new RegExp(`^- \\[([ xX])\\] ${escaped}\\s+.+$`, 'm'));
+  if (!match) throw new Error(`Task '${taskId}' was not found in tasks.md`);
+  return `sha256:${createHash('sha256').update(match[0]).digest('hex')}`;
+}
+
+export function saveCheckpoint(changeDir, input) {
+  requireText(input?.taskId, 'taskId');
+  requireText(input?.next, 'next');
+  const paths = getOverlayPaths(changeDir);
+  mkdirSync(paths.checkpoints, { recursive: true });
+  const record = {
+    task_id: input.taskId,
+    task_hash: computeTaskHash(changeDir, input.taskId),
+    next: input.next,
+    completed: input.completed ?? 'Not recorded',
+    evidence: input.evidence ?? 'Not recorded',
+    review: input.review ?? 'Not recorded',
+    risk: input.risk ?? 'Not recorded',
+    commit_start: input.commitStart ?? 'Not recorded',
+    commit_end: input.commitEnd ?? 'Not recorded',
+    created_at: new Date().toISOString(),
+  };
+  const targetPath = join(paths.checkpoints, `${safeName(input.taskId)}.md`);
+  atomicWrite(targetPath, renderRecord(record, `# Checkpoint: ${input.taskId}`, checkpointBody(record)));
+  return readCheckpoint(targetPath);
+}
+
+export function listCheckpoints(changeDir) {
+  const directory = getOverlayPaths(changeDir).checkpoints;
+  if (!existsSync(directory)) return [];
+  return readdirSync(directory).filter(name => name.endsWith('.md')).sort()
+    .map(name => readCheckpoint(join(directory, name)));
+}
+
+export function getCheckpoint(changeDir, taskId) {
+  const filePath = join(getOverlayPaths(changeDir).checkpoints, `${safeName(taskId)}.md`);
+  if (!existsSync(filePath)) return null;
+  return readCheckpoint(filePath);
+}
+
+export function createHandoff(changeDir, input) {
+  requireText(input?.type, 'type');
+  if (!HANDOFF_TYPES.has(input.type)) throw new Error(`Unsupported handoff type '${input.type}'`);
+  requireText(input?.title, 'title');
+  requireText(input?.question, 'question');
+  const paths = getOverlayPaths(changeDir);
+  const id = input.id || `${Date.now()}-${randomUUID().slice(0, 8)}`;
+  const directory = join(paths.handoffs, safeName(id));
+  mkdirSync(directory, { recursive: true });
+  const state = readState(changeDir);
+  const metadata = {
+    id,
+    type: input.type,
+    title: input.title,
+    question: input.question,
+    context: input.context ?? 'Not recorded',
+    source: input.source ?? 'Not recorded',
+    core_state: state.state,
+    state: state.state,
+    source_artifacts_hash: computeArtifactsHash(changeDir),
+    status: 'active',
+    created_at: new Date().toISOString(),
+  };
+  atomicWrite(join(directory, 'HANDOFF.md'), renderRecord(
+    metadata,
+    `# Handoff: ${input.title}`,
+    handoffBody(metadata),
+  ));
+  atomicWrite(join(directory, HANDOFF_RESULT_FILE), renderResultTemplate());
+  return readHandoff(directory);
+}
+
+export function listHandoffs(changeDir) {
+  const directory = getOverlayPaths(changeDir).handoffs;
+  if (!existsSync(directory)) return [];
+  return readdirSync(directory, { withFileTypes: true }).filter(entry => entry.isDirectory())
+    .sort((a, b) => a.name.localeCompare(b.name))
+    .map(entry => readHandoff(join(directory, entry.name)));
+}
+
+export function finishHandoff(changeDir, id) {
+  const handoff = getHandoff(changeDir, id);
+  if (!handoff) throw new Error(`Handoff '${id}' was not found`);
+  const resultPath = join(handoff.directory, HANDOFF_RESULT_FILE);
+  const result = parseResult(readFileSync(resultPath, 'utf8'));
+  for (const heading of RESULT_HEADINGS) {
+    if (!result[heading]) throw new Error(`${heading} must contain non-empty content`);
+  }
+  if (handoff.status !== 'active') throw new Error(`Handoff '${id}' is not active`);
+  const metadata = { ...handoff.metadata, status: 'result-ready', result_ready_at: new Date().toISOString() };
+  atomicWrite(join(handoff.directory, 'HANDOFF.md'), renderRecord(
+    metadata,
+    `# Handoff: ${metadata.title}`,
+    handoffBody(metadata),
+  ));
+  return readHandoff(handoff.directory);
+}
+
+export function resolveHandoff(changeDir, id, decision, acknowledgeSourceDrift) {
+  if (!HANDOFF_DECISIONS.has(decision)) throw new Error(`Unsupported handoff decision '${decision}'`);
+  const handoff = getHandoff(changeDir, id);
+  if (!handoff) throw new Error(`Handoff '${id}' was not found`);
+  if (handoff.status !== 'result-ready') throw new Error(`Handoff '${id}' is not result-ready`);
+  const sourceDrift = handoff.source_artifacts_hash !== computeArtifactsHash(changeDir);
+  if (sourceDrift && acknowledgeSourceDrift !== true) {
+    throw new Error('resolve requires acknowledge-source-drift');
+  }
+  const metadata = {
+    ...handoff.metadata,
+    status: 'resolved',
+    decision,
+    resolved_at: new Date().toISOString(),
+    source_drift: sourceDrift,
+    source_drift_acknowledged: sourceDrift && acknowledgeSourceDrift === true,
+  };
+  atomicWrite(join(handoff.directory, 'HANDOFF.md'), renderRecord(
+    metadata,
+    `# Handoff: ${metadata.title}`,
+    handoffBody(metadata),
+  ));
+  return readHandoff(handoff.directory);
+}
+
+function checkpointBody(record) {
+  return [
+    `## Next\n${record.next}`,
+    `## Completed\n${record.completed}`,
+    `## Evidence\n${record.evidence}`,
+    `## Review\n${record.review}`,
+    `## Risk\n${record.risk}`,
+    `## Commit Start\n${record.commit_start}`,
+    `## Commit End\n${record.commit_end}`,
+  ].join('\n\n');
+}
+
+function handoffBody(metadata) {
+  return [
+    `## Question\n${metadata.question}`,
+    `## Context\n${metadata.context}`,
+    `## Source\n${metadata.source}`,
+  ].join('\n\n');
+}
+
+function renderResultTemplate() {
+  return `${RESULT_HEADINGS.map(heading => `## ${heading}\n`).join('\n')}\n`;
+}
+
+function readCheckpoint(filePath) {
+  const { metadata } = parseRecord(readFileSync(filePath, 'utf8'));
+  metadata.commit_start ??= 'Not recorded';
+  metadata.commit_end ??= 'Not recorded';
+  let currentHash;
+  try {
+    currentHash = computeTaskHash(dirname(dirname(dirname(dirname(filePath)))), metadata.task_id);
+  } catch (error) {
+    if (error instanceof Error && error.message === `Task '${metadata.task_id}' was not found in tasks.md`) {
+      return { ...metadata, stale: true };
+    }
+    throw error;
+  }
+  return { ...metadata, stale: metadata.task_hash !== currentHash };
+}
+
+function readHandoff(directory) {
+  const { metadata } = parseRecord(readFileSync(join(directory, 'HANDOFF.md'), 'utf8'));
+  return { ...metadata, directory };
+}
+
+function getHandoff(changeDir, id) {
+  const directory = join(getOverlayPaths(changeDir).handoffs, safeName(id));
+  if (!existsSync(join(directory, 'HANDOFF.md'))) return null;
+  const { metadata } = parseRecord(readFileSync(join(directory, 'HANDOFF.md'), 'utf8'));
+  return { ...metadata, directory, metadata };
+}
+
+function renderRecord(metadata, title, body) {
+  const frontmatter = Object.entries(metadata)
+    .map(([key, value]) => `${key}: ${JSON.stringify(value)}`)
+    .join('\n');
+  return `---\n${frontmatter}\n---\n\n${title}\n\n${body}\n`;
+}
+
+function parseRecord(content) {
+  const lines = content.split('\n');
+  if (lines[0] !== '---') throw new Error('Record is missing frontmatter');
+  const end = lines.indexOf('---', 1);
+  if (end < 0) throw new Error('Record frontmatter is not closed');
+  const metadata = {};
+  for (const line of lines.slice(1, end)) {
+    const match = line.match(/^([A-Za-z_][\w-]*):\s*(.*)$/);
+    if (!match) continue;
+    metadata[match[1]] = parseScalar(match[2]);
+  }
+  return { metadata, body: lines.slice(end + 1).join('\n') };
+}
+
+function parseScalar(value) {
+  if (value.startsWith('"')) {
+    try { return JSON.parse(value); } catch { return value; }
+  }
+  return value;
+}
+
+function parseResult(content) {
+  const result = {};
+  let currentHeading = null;
+  for (const line of content.split('\n')) {
+    const heading = line.match(/^## (.+?)\s*$/)?.[1];
+    if (heading && RESULT_HEADINGS.includes(heading)) {
+      currentHeading = heading;
+      result[currentHeading] = '';
+    } else if (currentHeading) {
+      result[currentHeading] += `${line}\n`;
+    }
+  }
+  for (const heading of RESULT_HEADINGS) result[heading] = result[heading]?.trim() || '';
+  return result;
+}
+
+function atomicWrite(targetPath, content) {
+  const tempPath = `${targetPath}.tmp-${process.pid}-${randomUUID()}`;
+  writeFileSync(tempPath, content, 'utf8');
+  renameSync(tempPath, targetPath);
+}
+
+function requireText(value, field) {
+  if (typeof value !== 'string' || !value.trim()) throw new Error(`${field} is required`);
+}
+
+function safeName(value) {
+  return String(value).replace(/[^A-Za-z0-9._-]/g, '_');
+}

package/scripts/lib/shell-quote.mjs

@@ -0,0 +1,4 @@
+// Quote one value for a POSIX shell command embedded in a skill instruction.
+export function shellQuote(value) {
+  return `'${value.replace(/'/g, "'\\''")}'`;
+}