@michaelxwb/code-flow 0.8.1 → 1.0.0

package/package.json

@@ -1,33 +1,30 @@
 {
   "name": "@michaelxwb/code-flow",
-  "version": "0.8.1",
-  "description": "Initialize and manage AI coding workflow specs (Claude Code / Codex / Costrict / OpenCode)",
+  "version": "1.0.0",
+  "description": "Global Node-only spec injection and task-to-spec workflow for AI coding agents",
   "license": "UNLICENSED",
   "bin": {
-    "code-flow": "src/cli.js"
+    "code-flow": "bin/code-flow.js"
   },
   "engines": {
     "node": ">=18"
   },
+  "codeFlow": {
+    "hookProtocol": 1
+  },
   "files": [
-    "src/cli.js",
-    "src/runtime.js",
-    "src/migrate/**",
-    "src/core/**",
-    "src/core/code-flow/scripts/runtime-resources.json",
-    "src/adapters/**",
-    "docs/migrations/spec-workflow-0.6.0.md",
-    "docs/migrations/runtime-0.7.0.md",
-    "docs/migrations/runtime-0.8.0.md",
-    "docs/migrations/runtime-0.9.0.md",
-    "docs/acceptance-contract.md",
-    "docs/spec-injection-hardening.md",
-    "docs/spec-optimization.md",
-    "docs/spec-injection-performance.json",
+    "bin/",
+    "lib/",
+    "templates/",
+    "README.md",
     "docs/USAGE.md",
-    "docs/ci/acceptance-evidence.md"
+    "docs/v1-design.md",
+    "docs/v1-implementation.md",
+    "docs/README.md"
   ],
-  "dependencies": {
-    "@ccusage/codex": "^18.0.10"
+  "dependencies": {},
+  "scripts": {
+    "test": "node test/run.cjs",
+    "test:performance": "node --test test/performance.test.js"
   }
-}
+}

package/templates/adapters/opencode.mjs

@@ -0,0 +1,65 @@
+// code-flow:v1
+import { execFile } from "node:child_process";
+import { existsSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+const NODE = __CODE_FLOW_NODE__;
+const ENTRY = __CODE_FLOW_ENTRY__;
+function invoke(directory, event, signal) {
+  return new Promise((resolve, reject) => {
+    const bridge = join(directory, ".code-flow/launcher/bridge.cjs");
+    const useBridge = existsSync(bridge);
+    const command = existsSync(NODE) ? NODE : process.execPath;
+    const args = useBridge
+      ? [bridge, "--format", "opencode", "--node", NODE, "--entry", ENTRY]
+      : [ENTRY, "hook", "prompt", "--format=opencode"];
+    const child = execFile(command, args,
+      { cwd: directory, timeout: 3000, maxBuffer: 131072, windowsHide: true, signal },
+      (error, stdout, stderr) => {
+        if (stderr.trim()) console.error(stderr.trim());
+        if (error) return reject(error);
+        try {
+          const result = stdout.trim() ? JSON.parse(stdout) : { context: "" };
+          if (typeof result.context !== "string") throw new Error("Invalid code-flow context");
+          resolve(result.context);
+        } catch (failure) { reject(failure); }
+      });
+    child.stdin.on("error", reject);
+    child.stdin.end(JSON.stringify({ directory, event }));
+  });
+}
+export default {
+  id: "code-flow",
+  async setup(ctx) {
+    const pending = new Map(), jobs = new Map(), controller = new AbortController();
+    const diagnose = error => { if (!controller.signal.aborted) console.error("code-flow: " + error.message); };
+    try {
+      await ctx.session.hook("prompt", event => {
+        if (controller.signal.aborted) return;
+        if (typeof event?.prompt?.text !== "string" || !event.prompt.text.trim()) return;
+        const sid = event.sessionID;
+        const previous = jobs.get(sid) || Promise.resolve();
+        const job = previous.then(async () => {
+          if (typeof sid !== "string" || !sid) throw new Error("Missing native sessionID");
+          const info = await ctx.session.get({ sessionID: sid });
+          if (!isAbsolute(info?.location?.directory || "")) throw new Error("Missing session directory");
+          const text = await invoke(info.location.directory, event, controller.signal);
+          if (!controller.signal.aborted) pending.set(sid, text);
+        }).catch(error => {
+          pending.delete(sid);
+          diagnose(error);
+        });
+        jobs.set(sid, job);
+        void job.finally(() => { if (jobs.get(sid) === job) jobs.delete(sid); });
+        return job;
+      });
+      await ctx.session.hook("context", async event => {
+        try {
+          await jobs.get(event.sessionID);
+          const text = pending.get(event.sessionID);
+          if (text && !controller.signal.aborted) event.system.push({ type: "text", text });
+        } catch (error) { diagnose(error); }
+      });
+    } catch (error) { diagnose(error); }
+    return () => { controller.abort(); pending.clear(); jobs.clear(); };
+  }
+};

package/templates/config.json

@@ -0,0 +1,39 @@
+{
+  "_comment": {
+    "note": "本字段仅用于说明，code-flow 会忽略。JSON 不支持注释，因此用 _comment 记录参数含义。",
+    "version": "配置格式版本，当前固定为 1。",
+    "workflow": "工作流级别：hook（默认，Spec 注入 + 一份带声明测试的任务文档）或 full（额外 PRD/design/scenarios）。",
+    "always": "每次 prompt 都注入的 Spec 路径数组；路径相对 .code-flow/specs，不带 .md，可带 #RULE-...。",
+    "budget": {
+      "maxTokens": "一次注入的最大估算 token 数（正整数）；超出时按优先级省略并输出 omitted。",
+      "maxBytes": "一次注入的最大 UTF-8 字节数（正整数）；与 maxTokens 同时生效。"
+    },
+    "tests": {
+      "timeoutSeconds": "任务声明测试的默认超时秒数（正整数）；单个测试可用 timeout 覆盖。",
+      "jobs": "task finish 并行执行声明测试的默认并发数（正整数）。",
+      "regression": "合并后追加的回归命令：null 表示关闭；否则为对象，提供 argv 或 run 之一，可带 cwd/timeout/parallel/group/env。"
+    },
+    "capture": {
+      "enabled": "是否自动记录过程事件；只有 literal true 开启。",
+      "path": "过程事件目录，必须是 .code-flow 下的相对路径。"
+    },
+    "paths": "文件 glob 到 Spec 引用数组的映射；prompt 中出现匹配路径时注入对应 Spec。glob 支持 *、**、?，不支持 {}、[]、() 或 !。"
+  },
+  "version": 1,
+  "workflow": "hook",
+  "always": [],
+  "budget": {
+    "maxTokens": 2500,
+    "maxBytes": 16384
+  },
+  "tests": {
+    "timeoutSeconds": 120,
+    "jobs": 2,
+    "regression": null
+  },
+  "capture": {
+    "enabled": false,
+    "path": ".code-flow/process"
+  },
+  "paths": {}
+}

package/templates/instructions.md

@@ -0,0 +1,13 @@
+使用全局 code-flow CLI，以及 `.code-flow/config.json`、`.code-flow/specs/`、`.code-flow/tasks/`、`.code-flow/templates/` 中的当前项目数据。
+
+一个需求一份任务文档 `<requirement>.md`，包含多个 `## TASK-NNN` 段。通过任务文档路径 + TASK ID，或 prompt Hook 提供的 session token 选择 Task；不要根据状态推断。
+
+实现前读取当前 Task 的 Spec 引用。Spec 引用是相对于 `.code-flow/specs` 的路径，不带 `.md`。
+
+工作流级别来自 `.code-flow/config.json` 的 `workflow`：`hook`（默认）使用 Spec 注入加一份带声明测试的任务文档，不要求 PRD/design/scenarios；`full` 增加 PRD/design/scenarios 流程。设计文档是项目资产，不作为 prompt 输入；只有 Spec 会被注入。
+
+标记完成前，用 `task finish <task-document>.md --task TASK-NNN` 执行声明的测试。测试应限定在有意义的 unit/integration 回归；优先一次框架调用，使用框架自己的 workers。
+
+archive 应用声明的 Spec Delta 并移动需求；CI 独立执行完整回归和 E2E。使用 `cf-task:prd`、`cf-task:align` 和 `cf-task:plan` 处理文档流程；不要为每个 Task 建一个文件。
+
+Hook 诊断永不阻止工作。缺少绑定时要显式提供任务文档 + TASK ID，或重新执行 task start。

package/templates/launcher/bridge.cjs

@@ -0,0 +1,295 @@
+'use strict';
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+const { spawn, spawnSync } = require('child_process');
+
+const MAX_INPUT = 1024 * 1024;
+const MAX_OUTPUT = 1024 * 1024;
+const MAX_DIAGNOSTIC = 4096;
+const PROBE_MS = 800;
+const RUN_RESERVE_MS = 1200;
+const CACHE_TTL_MS = 600000;
+const TOTAL_MS = 2000;
+
+function emptyPayload(format) {
+  return format === 'opencode'
+    ? { context: '' }
+    : { hookSpecificOutput: { hookEventName: 'UserPromptSubmit', additionalContext: '' } };
+}
+
+function validPayload(format, payload) {
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) return false;
+  if (format === 'opencode') return typeof payload.context === 'string';
+  const hook = payload.hookSpecificOutput;
+  return hook !== null && typeof hook === 'object' &&
+    hook.hookEventName === 'UserPromptSubmit' && typeof hook.additionalContext === 'string';
+}
+
+function normalizePayload(format, payload) {
+  if (!validPayload(format, payload)) return null;
+  return format === 'opencode' ? { context: payload.context } : {
+    hookSpecificOutput: { hookEventName: 'UserPromptSubmit',
+      additionalContext: payload.hookSpecificOutput.additionalContext }
+  };
+}
+
+function emit(format, payload) {
+  process.stdout.write(JSON.stringify(payload) + '\n');
+}
+
+function readStdin(deadline) {
+  return new Promise(resolve => {
+    const chunks = [];
+    let size = 0, timer;
+    const finish = value => {
+      clearTimeout(timer);
+      process.stdin.removeAllListeners();
+      process.stdin.destroy();
+      resolve(value);
+    };
+    timer = setTimeout(() => finish(''), Math.max(0, Math.min(TOTAL_MS, deadline - Date.now())));
+    process.stdin.on('data', chunk => {
+      size += chunk.length;
+      if (size > MAX_INPUT) finish('');
+      else chunks.push(chunk);
+    });
+    process.stdin.on('end', () => finish(Buffer.concat(chunks).toString('utf8')));
+    process.stdin.on('error', () => finish(''));
+  });
+}
+
+function inside(root, candidate) {
+  const relative = path.relative(root, candidate);
+  return relative === '' || (!relative.startsWith('..' + path.sep) && relative !== '..');
+}
+
+function safeCandidate(root, candidate) {
+  try {
+    const real = fs.realpathSync(candidate);
+    return fs.statSync(real).isFile() && !inside(root, real);
+  } catch (_) { return false; }
+}
+
+function realFile(candidate) {
+  try { return fs.realpathSync(candidate); } catch (_) { return null; }
+}
+
+function findOnPath(root) {
+  const names = process.platform === 'win32'
+    ? ['code-flow.cmd', 'code-flow.exe', 'code-flow']
+    : ['code-flow'];
+  const found = [];
+  for (const directory of (process.env.PATH || '').split(path.delimiter)) {
+    if (!directory) continue;
+    for (const name of names) {
+      const candidate = path.join(directory, name);
+      if (safeCandidate(root, candidate)) found.push(candidate);
+    }
+  }
+  return [...new Set(found)];
+}
+
+function packageIdentity(entry) {
+  let directory = path.dirname(entry);
+  while (directory !== path.dirname(directory)) {
+    const file = path.join(directory, 'package.json');
+    if (fs.existsSync(file)) {
+      try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch (_) { return null; }
+    }
+    directory = path.dirname(directory);
+  }
+  return null;
+}
+
+function validCapability(data, candidate) {
+  if (!data || data.package !== '@michaelxwb/code-flow' || data.hook_protocol !== 1) return false;
+  if (typeof data.node !== 'string' || !path.isAbsolute(data.node)) return false;
+  if (typeof data.entry !== 'string' || !path.isAbsolute(data.entry)) return false;
+  const dataEntry = realFile(data.entry), candidateEntry = realFile(candidate);
+  if (!dataEntry || !candidateEntry) return false;
+  const shim = process.platform === 'win32' || !/\.js$/i.test(candidateEntry);
+  if (candidateEntry !== dataEntry && !shim) return false;
+  const pkg = packageIdentity(dataEntry);
+  if (!pkg || pkg.name !== data.package || pkg.version !== data.version) return false;
+  const bin = pkg.bin && typeof pkg.bin === 'object' ? pkg.bin['code-flow'] : pkg.bin;
+  if (typeof bin !== 'string' ||
+    path.resolve(path.dirname(dataEntry), '..', bin) !== path.resolve(dataEntry)) return false;
+  return pkg.codeFlow && pkg.codeFlow.hookProtocol === 1;
+}
+
+function probeCommand(candidate, args) {
+  if (process.platform === 'win32' && /\.(?:cmd|bat)$/i.test(candidate)) {
+    const quote = value => '"' + value.replace(/"/g, '""') + '"';
+    return [process.env.ComSpec || 'cmd.exe',
+      ['/d', '/s', '/c', [candidate, ...args].map(quote).join(' ')]];
+  }
+  return [candidate, args];
+}
+
+function probe(root, candidate, budget) {
+  const [file, args] = probeCommand(candidate, ['hook', 'capabilities', '--json']);
+  return new Promise(resolve => {
+    const chunks = [];
+    let size = 0, settled = false, timer;
+    const child = spawn(file, args, {
+      cwd: root, stdio: ['ignore', 'pipe', 'pipe'], detached: process.platform !== 'win32',
+      windowsHide: true
+    });
+    const finish = ok => {
+      if (settled) return;
+      settled = true; clearTimeout(timer);
+      try { child.stdout.destroy(); child.stderr.destroy(); } catch (_) { /* best effort */ }
+      if (!ok) { resolve(null); return; }
+      try {
+        const data = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+        resolve(validCapability(data, candidate) ? data : null);
+      } catch (_) { resolve(null); }
+    };
+    timer = setTimeout(() => { killTree(child); finish(false); }, Math.max(1, Math.min(PROBE_MS, budget)));
+    child.on('error', () => finish(false));
+    child.stdout.on('data', chunk => {
+      size += chunk.length;
+      if (size > MAX_OUTPUT) { killTree(child); finish(false); }
+      else chunks.push(chunk);
+    });
+    child.stderr.on('data', () => {});
+    child.on('close', code => finish(code === 0));
+  });
+}
+
+function cacheFile(root) {
+  const digest = crypto.createHash('sha256').update(fs.realpathSync(root)).digest('hex');
+  return path.join(os.tmpdir(), 'code-flow', digest, 'bridge.json');
+}
+
+function selectionKey(fixed) {
+  return crypto.createHash('sha256').update(JSON.stringify({
+    path: process.env.PATH || '', node: fixed.node || '', entry: fixed.entry || ''
+  })).digest('hex');
+}
+
+function readCache(root, key) {
+  let data;
+  try { data = JSON.parse(fs.readFileSync(cacheFile(root), 'utf8')); } catch (_) { return null; }
+  if (!data || data.key !== key || typeof data.checked_at !== 'number' ||
+      Date.now() - data.checked_at > CACHE_TTL_MS ||
+      typeof data.entry_mtime !== 'number' || typeof data.candidate !== 'string' ||
+      !data.capability || typeof data.capability !== 'object') return null;
+  try { if (fs.statSync(data.capability.entry).mtimeMs !== data.entry_mtime) return null; }
+  catch (_) { return null; }
+  return validCapability(data.capability, data.candidate) ? data.capability : null;
+}
+
+function writeCache(root, key, selected) {
+  try {
+    const { candidate, ...capability } = selected;
+    const entry_mtime = fs.statSync(capability.entry).mtimeMs;
+    const file = cacheFile(root), temporary = file + '.' + process.pid + '.' + Date.now() + '.tmp';
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(temporary, JSON.stringify({ key, checked_at: Date.now(), entry_mtime,
+      candidate, capability }), { mode: 0o600 });
+    fs.renameSync(temporary, file);
+  } catch (_) { /* best effort */ }
+}
+
+async function probePath(root, fixed, deadline) {
+  for (const candidate of findOnPath(root)) {
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) break;
+    const capability = await probe(root, candidate, remaining);
+    if (capability) return { ...capability, candidate };
+  }
+  if (fixed.node && fixed.entry && fs.existsSync(fixed.node) && fs.existsSync(fixed.entry)) {
+    const capability = { node: fixed.node, entry: fixed.entry, package: '@michaelxwb/code-flow',
+      version: packageIdentity(fixed.entry)?.version, hook_protocol: 1 };
+    if (validCapability(capability, fixed.entry)) return { ...capability, candidate: fixed.entry };
+  }
+  return null;
+}
+
+async function select(root, fixed, deadline) {
+  const key = selectionKey(fixed), cached = readCache(root, key);
+  if (cached) return cached;
+  const selected = await probePath(root, fixed, deadline);
+  if (selected) writeCache(root, key, selected);
+  return selected;
+}
+
+function killTree(child) {
+  if (!child.pid) return;
+  if (process.platform === 'win32') {
+    spawnSync('taskkill', ['/PID', String(child.pid), '/T', '/F'], { windowsHide: true });
+    return;
+  }
+  try { process.kill(-child.pid, 'SIGKILL'); } catch (_) { try { child.kill('SIGKILL'); } catch (_) {} }
+}
+
+function run(root, selected, format, input, deadline) {
+  return new Promise(resolve => {
+    const chunks = [];
+    let stderr = '', size = 0, settled = false, timer;
+    const child = spawn(selected.node, [selected.entry, 'hook', 'prompt', '--format=' + format], {
+      cwd: root, stdio: ['pipe', 'pipe', 'pipe'], detached: process.platform !== 'win32', windowsHide: true
+    });
+    const finish = ok => {
+      if (settled) return;
+      settled = true; clearTimeout(timer);
+      if (!ok) {
+        if (stderr.trim()) process.stderr.write(stderr.trim() + '\n');
+        resolve(null);
+        return;
+      }
+      try {
+        const parsed = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+        resolve(normalizePayload(format, parsed));
+      } catch (_) { resolve(null); }
+    };
+    timer = setTimeout(() => { killTree(child); finish(false); },
+      Math.max(0, Math.min(TOTAL_MS, deadline - Date.now())));
+    child.on('error', error => {
+      stderr = (stderr + error.message).slice(-MAX_DIAGNOSTIC); finish(false);
+    });
+    child.stdout.on('data', chunk => {
+      size += chunk.length;
+      if (size > MAX_OUTPUT) { killTree(child); finish(false); }
+      else chunks.push(chunk);
+    });
+    child.stderr.setEncoding('utf8');
+    child.stderr.on('data', chunk => { stderr = (stderr + chunk).slice(-MAX_DIAGNOSTIC); });
+    child.on('close', code => finish(code === 0));
+    child.stdin.on('error', () => {});
+    child.stdin.end(input);
+  });
+}
+
+function parseArgs(argv) {
+  const fixed = { node: '', entry: '' }, options = {};
+  for (let index = 0; index < argv.length; index++) {
+    if (argv[index] === '--format') options.format = argv[++index];
+    else if (argv[index] === '--node') fixed.node = argv[++index];
+    else if (argv[index] === '--entry') fixed.entry = argv[++index];
+  }
+  return { fixed, format: options.format || 'claude' };
+}
+
+async function main() {
+  const { fixed, format } = parseArgs(process.argv.slice(2));
+  const root = process.cwd(), deadline = Date.now() + TOTAL_MS;
+  const input = await readStdin(deadline);
+  if (!input.trim()) return;
+  const selected = await select(root, fixed, deadline - RUN_RESERVE_MS);
+  if (!selected) {
+    process.stderr.write('code-flow bridge: no valid global entry; run doctor\n');
+    emit(format, emptyPayload(format));
+    return;
+  }
+  const output = await run(root, selected, format, input, deadline);
+  emit(format, output ?? emptyPayload(format));
+}
+
+main().catch(error => {
+  process.stderr.write('code-flow bridge: ' + error.message + '\n');
+  emit('claude', emptyPayload('claude'));
+});

package/templates/launcher/hook.cmd

@@ -0,0 +1,15 @@
+@echo off
+rem code-flow:v1
+setlocal
+set "ROOT=%~dp0..\.."
+set "FORMAT=%~1"
+if "%FORMAT%"=="" set "FORMAT=claude"
+set "NODE="
+where node >nul 2>nul && set "NODE=node"
+if not defined NODE set "NODE=__FIXED_NODE__"
+if not exist "%ROOT%\.code-flow\launcher\bridge.cjs" (
+  echo code-flow launcher missing; run init again 1>&2
+  exit /b 0
+)
+"%NODE%" "%ROOT%\.code-flow\launcher\bridge.cjs" --format "%FORMAT%" --node "__FIXED_NODE__" --entry "__FIXED_ENTRY__"
+exit /b 0

package/templates/launcher/hook.ps1

@@ -0,0 +1,10 @@
+# code-flow:v1
+param([string]$Format = 'claude')
+$cmd = Join-Path $PSScriptRoot 'hook.cmd'
+if (-not (Test-Path -LiteralPath $cmd)) {
+  [Console]::Error.WriteLine('code-flow launcher missing; run init again')
+  exit 0
+}
+$shell = if ($env:ComSpec) { $env:ComSpec } else { 'cmd.exe' }
+& $shell /d /c call $cmd $Format
+exit 0

package/templates/launcher/hook.sh

@@ -0,0 +1,20 @@
+#!/bin/sh
+# code-flow:v1
+root=$(CDPATH= cd -- "$(dirname -- "$0")/../.." && pwd) || exit 0
+cd "$root" || exit 0
+format=${1:-claude}
+node=$(command -v node 2>/dev/null || true)
+[ -n "$node" ] || node='__FIXED_NODE__'
+bridge="$root/.code-flow/launcher/bridge.cjs"
+if [ ! -f "$bridge" ]; then
+  printf 'code-flow launcher missing; run init again\n' >&2
+  exit 0
+fi
+if code_flow_output=$("$node" "$bridge" --format "$format" --node '__FIXED_NODE__' --entry '__FIXED_ENTRY__'); then
+  if [ -n "$code_flow_output" ]; then
+    printf '%s\n' "$code_flow_output"
+  fi
+else
+  printf 'code-flow launcher failed; run doctor\n' >&2
+fi
+exit 0

package/templates/skills/cf-check.md

@@ -0,0 +1,19 @@
+---
+name: cf-check
+description: Run read-only code-flow health checks.
+---
+<!-- code-flow:v1 -->
+Run:
+
+```bash
+code-flow doctor --json
+```
+
+Report:
+- hook/launcher entry and template status;
+- config and Spec parse errors;
+- Task document errors and dependency problems;
+- worktree run ledger state;
+- the next safe action.
+
+`doctor` is read-only. Do not repair or mutate project files from this skill unless the user explicitly asks.

package/templates/skills/cf-init.md

@@ -0,0 +1,16 @@
+---
+name: cf-init
+description: Initialize code-flow v1 and organize current project standards.
+---
+<!-- code-flow:v1 -->
+Run the globally installed `code-flow init --platform=<claude|codex|costrict|opencode|all>`.
+
+`init` overwrites tool-owned templates under `.code-flow/templates/` and platform skills/hooks. It preserves `.code-flow/specs/`, `.code-flow/tasks/` and an existing `config.json`. If it reports `conflicts`, resolve those paths and re-run; other files are already updated.
+
+For an existing nonempty `.code-flow` without a valid v1 config, preserve it outside the project and manually clear earlier managed platform entries first. Do not write conversion or cleanup scripts.
+
+Keep `workflow` at `hook` unless the requirement is complex enough to justify the full PRD/design/scenarios flow. `capture.enabled` can record process data under `.code-flow/process/`; it is off by default.
+
+After init, read `.code-flow/templates/project-guidelines.md` and write the project-specific guidelines into `CLAUDE.md` / `AGENTS.md` outside the code-flow managed block. Keep the project's identity, architecture, commands and Spec conventions there; do not modify the managed block or overwrite user content. Specs under `.code-flow/specs` are the project standards: read them before writing rules, and update `config.json` `always` / `paths` when adding a Spec.
+
+Inspect current code and project instructions. Create a small number of applicable Specs with JSON frontmatter `{"description":"...","next_rule":1}`. Use path identity, a `## Rules` section, stable RULE IDs and indented examples. Set `next_rule` above all allocated numeric IDs. Configure a few shared rules in `always` and concrete file globs in `paths`. Finish with `code-flow doctor --json`.

package/templates/skills/cf-spec.md

@@ -0,0 +1,20 @@
+---
+name: cf-spec
+description: Inspect current code-flow v1 Specs and apply reviewed Task Spec Deltas.
+---
+<!-- code-flow:v1 -->
+Use `code-flow spec list --json`, `code-flow spec inject --task-file <task-document>.md --task TASK-001 --json`, or `code-flow spec inject --path <file> --full`.
+
+Spec identity is its path relative to `.code-flow/specs` without `.md`. Frontmatter is JSON with `description` and a positive `next_rule`. Rules use stable RULE IDs and complete indented explanations/examples.
+
+Review applicability and semantic conflicts against current code before writing a Spec Delta. Prefer stable shared constraints over task-specific narration.
+
+Delta operations are add/update/remove. Every item needs a stable ID, target Spec path and evidence; update/remove require the existing Rule ref and exact before text. New numeric IDs come from `next_rule`, never from the largest remaining Rule.
+
+Use:
+
+```bash
+code-flow spec learn --from-task <task-document>.md --task TASK-001 --dry-run --json
+```
+
+Review the exact diff, then run without `--dry-run`. Repeating an already applied payload is safe; changed content requires a new Delta ID. A missing target or before mismatch is an error. Preserve Applied Deltas records so interrupted multi-file learning can resume.

package/templates/skills/cf-task-align.md

@@ -0,0 +1,19 @@
+---
+name: cf-task-align
+description: Produce frontend/backend design and manual acceptance scenarios.
+---
+<!-- code-flow:v1 -->
+Read the requirement PRD or user brief. Read `.code-flow/templates/design-lite.md`, `design-full.md`, or `design-frontend.md` as appropriate. Write:
+
+- `.code-flow/tasks/<date>/<requirement>/<requirement>.frontend.design.md`
+- `.code-flow/tasks/<date>/<requirement>/<requirement>.backend.design.md`
+- or one `<requirement>.design.md` for a single domain
+- `.code-flow/tasks/<date>/<requirement>/<requirement>.scenarios.md`
+
+Design rules:
+- full-stack requirements keep frontend and backend design separate;
+- scenarios use S-/E-/B- IDs, level, boundary and expected result;
+- scenarios are a manual tester reference, not a manifest or blocking gate;
+- do not run or copy old manifest/design-lint/Stage Gate/E2E commands from templates.
+
+When design and scenarios are ready, continue with `cf-task:plan`.

package/templates/skills/cf-task-archive.md

@@ -0,0 +1,20 @@
+---
+name: cf-task-archive
+description: Archive a completed requirement after applying Spec Deltas.
+---
+<!-- code-flow:v1 -->
+Read `code-flow task status <requirement-dir> --json`. Every TASK in the one requirement task document must be `done`.
+
+Preview and apply:
+
+```bash
+code-flow task archive <requirement-dir> --dry-run --json
+code-flow task archive <requirement-dir> --json
+```
+
+Archive:
+- applies each TASK's Spec Delta in the coordinator worktree;
+- moves the whole requirement directory;
+- does not run tests, E2E, or scenarios.
+
+Do not run archive inside a worktree. Use the returned `archived_to` path. If Delta application fails, fix the Delta or explicitly use `--no-learn`; do not hand-edit the archive destination.

package/templates/skills/cf-task-plan.md

@@ -0,0 +1,31 @@
+---
+name: cf-task-plan
+description: Split a requirement into one multi-TASK document.
+---
+<!-- code-flow:v1 -->
+Read `.code-flow/config.json` `workflow` first:
+
+- `hook` (default): write one task document with TASK sections and declared tests; do not require or read PRD/design/scenarios; leave Source/Scenarios empty.
+- `full`: read the requirement's design files and scenarios first; fill Source/Scenarios.
+
+Read `.code-flow/templates/task.md`. Write exactly one task document:
+
+```text
+.code-flow/tasks/<date>/<requirement>/<requirement>.md
+```
+
+Start with JSON frontmatter naming the requirement:
+
+```markdown
+---
+{"version":1,"requirement":"<requirement>"}
+---
+```
+
+Inside it create `## TASK-NNN` sections. Keep each Task small enough to demonstrate a capability. For every Task declare:
+
+- Status, Depends, Source, Scenarios, Spec-Refs, Paths;
+- a `### Tests` JSON array of fast unit/integration commands;
+- a `### Spec Delta` JSON array (empty is valid).
+
+Do not create one file per Task. Do not create an acceptance manifest. Do not run old scenario/quality/Stage Gate commands. Verify the result with `code-flow task status --json`, then use `cf-task:start`.

package/templates/skills/cf-task-prd.md

@@ -0,0 +1,14 @@
+---
+name: cf-task-prd
+description: Produce a concise PRD for one requirement.
+---
+<!-- code-flow:v1 -->
+Read `.code-flow/templates/prd.md`. Ask only questions that block scope, users, or acceptance. Write one requirement PRD to `.code-flow/tasks/<date>/<requirement>/<requirement>.prd.md`.
+
+Keep it short:
+- problem, goal, users, user stories;
+- functional requirements and boundaries;
+- non-functional constraints only when real;
+- risks and open questions.
+
+Do not create Task files here. Do not run old manifest, scenario, design-lint, Stage Gate, or E2E gates. When the PRD is accepted, continue with `cf-task:align`.