cowork-flow 0.0.1

package/README.md

@@ -0,0 +1,193 @@
+# cowork-flow
+
+cowork-flow 是一个用于新项目初始化协作流程的模板仓库。它把项目说明、任务流转、规格治理、开发计划和会话记录放在一套可复制的目录结构里，帮助团队在项目早期就建立清晰的工作闭环。
+
+这个仓库本身不绑定具体技术栈，也不提供业务代码脚手架。它提供的是协作与治理基础设施：你可以把 `template/` 复制到目标项目中，再按目标项目的真实情况补充技术栈、验证命令、目录规范和提交策略。
+
+## 适用场景
+
+- 新项目需要建立 `AGENTS.md`、任务流、规格文档和开发记录。
+- 已有项目希望补上一套轻量的协作流程，但不想引入完整工程脚手架。
+- 团队希望把需求澄清、规格变更、实现计划、验证和会话记录串成闭环。
+
+## 不适用场景
+
+- 只需要一个语言或框架脚手架，例如 React、Spring Boot、Rust crate 模板。
+- 项目已经有成熟且完整的任务、规格和协作系统，并且不希望引入新的目录约定。
+- 只想复制某一段提示词，而不需要维护项目级流程文件。
+
+## 仓库结构
+
+```text
+.
+├── README.md
+└── template/
+    ├── AGENTS.md
+    ├── .agent/
+    │   └── skills/
+    └── .cowork-flow/
+        ├── config.yaml
+        ├── workflow.md
+        ├── scripts/
+        ├── spec/
+        ├── changes/
+        ├── plans/
+        ├── tasks/
+        └── workspace/
+```
+
+## 模板内容
+
+`template/AGENTS.md`
+项目级协作入口，包含编码前思考、简单优先、外科手术式改动、验证优先等基础原则。接入项目后，应把项目名称、技术栈、运行命令、测试命令和提交策略补齐。
+
+`template/.agent/skills/`
+本地技能入口，覆盖开始工作、收尾验证、记录 session、更新规范、跨层检查等常见协作动作。这里的 skill 应保持通用，不承载某个业务项目的一次性细节。
+
+`template/.cowork-flow/`
+工作流目录，包含流程说明、任务状态、开发者工作区、项目规范、行为变更规格、实现计划和辅助脚本。`.cowork-flow/config.yaml` 用于填写项目自己的 lint、build、test 等验证命令。
+
+`template/.cowork-flow/spec/`
+项目规范目录，预置了 backend、frontend 和 guides 三类说明。接入时应按项目事实保留、改写或删除对应规范。
+
+`template/.cowork-flow/changes/`
+由 `change.py` 管理 proposal、design、behavior specs 和归档，不维护实现 checklist。
+
+`template/.cowork-flow/plans/`
+保存可执行步骤、验证方式和执行状态。
+
+## 快速开始
+
+使用 CLI 把模板内容安装到目标项目根目录：
+
+```bash
+npx cowork-flow init ./my-project
+```
+
+也可以先全局安装：
+
+```bash
+npm install -g cowork-flow
+cowork-flow init ./my-project
+```
+
+初始化后优先完成这些配置：
+
+1. 更新 `AGENTS.md` 中的项目名称、技术栈、命令和提交策略。
+2. 更新 `.cowork-flow/config.yaml` 中的验证命令。
+3. 更新 `.cowork-flow/workflow.md` 中与项目流程不一致的门禁、分级和完成定义。
+4. 按项目实际情况调整 `.cowork-flow/spec/`，删除不存在的 frontend、backend 或行为变更场景。
+5. 按团队实践使用 `.cowork-flow/changes/` 管理规格变更，使用 `.cowork-flow/plans/` 管理实现计划和验证状态。
+
+## CLI 使用
+
+查看命令：
+
+```bash
+npx cowork-flow --help
+```
+
+初始化到新项目：
+
+```bash
+cowork-flow init ./my-project
+```
+
+`init` 会询问你是否已经安装了 Superpowers skills。选择未安装时，会把内置的 `.superpowers/` 技能复制到目标项目的 `.agent/skills/` 下。
+在非交互环境里，这一步会自动跳过询问并默认视为已安装。
+
+初始化到当前项目：
+
+```bash
+cowork-flow init .
+```
+
+默认不会覆盖已有文件。需要预览时使用：
+
+```bash
+cowork-flow init ./my-project --dry-run
+```
+
+需要明确覆盖已有文件时使用：
+
+```bash
+cowork-flow init ./my-project --force
+```
+
+升级 CLI 本身：
+
+```bash
+cowork-flow update
+npm install -g cowork-flow@latest
+```
+
+同步已初始化项目中的模板脚本和本地技能：
+
+```bash
+cowork-flow sync .
+cowork-flow sync . --dry-run
+```
+
+`sync` 默认保护 `AGENTS.md`、`.cowork-flow/config.yaml`、`.cowork-flow/workflow.md`、`.cowork-flow/spec/`、任务、计划、变更和 workspace 记录。只有明确传入 `--force` 时才覆盖保护文件。
+
+## 常用入口
+
+初始化或查看开发者身份：
+
+```bash
+python3 ./.cowork-flow/scripts/get_developer.py
+python3 ./.cowork-flow/scripts/init_developer.py <developer-name>
+```
+
+查看当前上下文：
+
+```bash
+python3 ./.cowork-flow/scripts/get_context.py
+python3 ./.cowork-flow/scripts/task.py list
+```
+
+创建并验证行为变更：
+
+```bash
+python3 ./.cowork-flow/scripts/change.py create <slug>
+python3 ./.cowork-flow/scripts/change.py validate <slug>
+```
+
+创建并启动任务：
+
+```bash
+python3 ./.cowork-flow/scripts/task.py create "<title>" --slug <task-name>
+python3 ./.cowork-flow/scripts/task.py start <task-dir>
+```
+
+记录 session：
+
+```bash
+python3 ./.cowork-flow/scripts/get_context.py --mode record
+python3 ./.cowork-flow/scripts/add_session.py \
+  --title "<session-title>" \
+  --commit "<commit-or-handoff-ref>" \
+  --summary "<summary>"
+```
+
+## 接入原则
+
+- 以目标项目事实为准，不把模板内容当成项目事实。
+- 保留有价值的流程骨架，删除目标项目不存在的场景。
+- 项目差异写入 `AGENTS.md`、`.cowork-flow/workflow.md`、`.cowork-flow/config.yaml` 和 `.cowork-flow/spec/`。
+- 不为了替换项目命令或一次性任务而改写通用 skill。
+- README 只说明项目定位和使用方式；具体协作规则应沉淀在模板内对应文件中。
+
+## 维护建议
+
+更新模板时，优先确认这几件事：
+
+- `template/` 中的目录结构和 README 描述一致。
+- 新增流程规则有明确承载位置，不散落在多个文件里互相冲突。
+- 脚本入口和文档中的命令保持一致。
+- 通用 skill 保持可复用，项目专用规则不混入 starter 模板。
+- 示例命令尽量保持最小可用，避免把模板写成某个具体项目的实现方案。
+
+## 发布流程
+
+CI 会运行 Node CLI 测试、npm pack 内容检查和现有 Python 模板测试。发布到 npm 通过 GitHub Actions 的 `Publish npm Package` workflow 完成，需要在仓库 secrets 中配置 `NPM_TOKEN`。

package/bin/cowork-flow.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { main } from '../src/cli.js';
+
+try {
+  process.exitCode = await main(process.argv.slice(2));
+} catch (error) {
+  process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+  process.exitCode = 1;
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "cowork-flow",
+  "version": "0.0.1",
+  "description": "CLI for installing and maintaining cowork-flow collaboration templates.",
+  "type": "module",
+  "bin": {
+    "cowork-flow": "./bin/cowork-flow.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "template",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "test:template": "python3 -m unittest discover tests -v",
+    "pack:check": "npm_config_cache=/tmp/cowork-flow-npm-cache npm pack --dry-run --json",
+    "test:all": "npm test && npm run test:template && npm run pack:check"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/cli.js

@@ -0,0 +1,61 @@
+import { runInit } from './commands/init.js';
+import { runSync } from './commands/sync.js';
+import { runUpdate } from './commands/update.js';
+import { readPackageInfo } from './lib/package-info.js';
+
+const HELP = `cowork-flow
+
+Usage:
+  cowork-flow init [target] [--dry-run] [--force]
+  cowork-flow update [--global] [--yes]
+  cowork-flow sync [target] [--dry-run] [--force]
+  cowork-flow --version
+  cowork-flow --help
+`;
+
+function defaultIo() {
+  return {
+    writeOut(message) {
+      process.stdout.write(message);
+    },
+    writeErr(message) {
+      process.stderr.write(message);
+    }
+  };
+}
+
+export async function main(argv = process.argv.slice(2), options = {}) {
+  const io = options.io ?? defaultIo();
+  const [command, ...args] = argv;
+
+  try {
+    if (!command || command === '--help' || command === '-h') {
+      io.writeOut(HELP);
+      return 0;
+    }
+
+    if (command === '--version' || command === '-v') {
+      const packageInfo = await readPackageInfo();
+      io.writeOut(`${packageInfo.version}\n`);
+      return 0;
+    }
+
+    if (command === 'init') {
+      return await runInit(args, { io, prompt: options.prompt });
+    }
+
+    if (command === 'sync') {
+      return await runSync(args, { io });
+    }
+
+    if (command === 'update') {
+      return await runUpdate(args, { io });
+    }
+
+    io.writeErr(`Unknown command: ${command}\n`);
+    return 1;
+  } catch (error) {
+    io.writeErr(`${error instanceof Error ? error.message : String(error)}\n`);
+    return 1;
+  }
+}

package/src/commands/init.js

@@ -0,0 +1,88 @@
+import { resolve } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+
+import {
+  applyPlan,
+  buildInitPlan,
+  buildSuperpowersPlan,
+  summarizePlan
+} from '../lib/copy-template.js';
+import { readPackageInfo } from '../lib/package-info.js';
+
+function parseInitArgs(args) {
+  const options = { dryRun: false, force: false, target: process.cwd() };
+  for (const arg of args) {
+    if (arg === '--dry-run') {
+      options.dryRun = true;
+    } else if (arg === '--force') {
+      options.force = true;
+    } else if (arg.startsWith('--')) {
+      throw new Error(`Unknown init option: ${arg}`);
+    } else {
+      options.target = resolve(arg);
+    }
+  }
+  return options;
+}
+
+function isAffirmative(answer) {
+  const normalized = answer.trim().toLowerCase();
+  return normalized === 'y' || normalized === 'yes' || normalized === 'true' || normalized === '1';
+}
+
+async function defaultSuperpowersPrompt(io) {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    io.writeOut('Superpowers prompt skipped because stdin is not interactive.\n');
+    return true;
+  }
+
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+
+  try {
+    const answer = await rl.question('Have you already installed Superpowers skills? [y/N] ');
+    return isAffirmative(answer);
+  } finally {
+    rl.close();
+  }
+}
+
+export async function runInit(args, { io, prompt }) {
+  return runInitWithOptions(args, { io, prompt });
+}
+
+export async function runInitWithOptions(args, { io, prompt = defaultSuperpowersPrompt }) {
+  const options = parseInitArgs(args);
+  const packageInfo = await readPackageInfo();
+  const plan = await buildInitPlan(options.target, {
+    force: options.force,
+    version: packageInfo.version
+  });
+
+  await applyPlan(plan, { dryRun: options.dryRun });
+  io.writeOut(summarizePlan(plan, options.dryRun));
+
+  if (options.dryRun) {
+    io.writeOut('Superpowers prompt skipped in dry-run.\n');
+    io.writeOut('Next: update AGENTS.md and .cowork-flow/config.yaml for this project.\n');
+    return 0;
+  }
+
+  const alreadyInstalled = await prompt(io);
+  if (alreadyInstalled) {
+    io.writeOut('Superpowers skills already installed; skipping bundled skills.\n');
+    io.writeOut('Next: update AGENTS.md and .cowork-flow/config.yaml for this project.\n');
+    return 0;
+  }
+
+  const superpowersPlan = await buildSuperpowersPlan(options.target, {
+    force: options.force
+  });
+  await applyPlan(superpowersPlan, { dryRun: false });
+  io.writeOut(summarizePlan(superpowersPlan, false));
+  io.writeOut('Superpowers skills were bundled into .agent/skills.\n');
+  io.writeOut('Next: update AGENTS.md and .cowork-flow/config.yaml for this project.\n');
+  return 0;
+}

package/src/commands/sync.js

@@ -0,0 +1,33 @@
+import { resolve } from 'node:path';
+
+import { applyPlan, buildSyncPlan, summarizePlan } from '../lib/copy-template.js';
+import { readPackageInfo } from '../lib/package-info.js';
+
+function parseSyncArgs(args) {
+  const options = { dryRun: false, force: false, target: process.cwd() };
+  for (const arg of args) {
+    if (arg === '--dry-run') {
+      options.dryRun = true;
+    } else if (arg === '--force') {
+      options.force = true;
+    } else if (arg.startsWith('--')) {
+      throw new Error(`Unknown sync option: ${arg}`);
+    } else {
+      options.target = resolve(arg);
+    }
+  }
+  return options;
+}
+
+export async function runSync(args, { io }) {
+  const options = parseSyncArgs(args);
+  const packageInfo = await readPackageInfo();
+  const plan = await buildSyncPlan(options.target, {
+    force: options.force,
+    version: packageInfo.version
+  });
+
+  await applyPlan(plan, { dryRun: options.dryRun });
+  io.writeOut(summarizePlan(plan, options.dryRun));
+  return 0;
+}

package/src/commands/update.js

@@ -0,0 +1,60 @@
+import {
+  compareVersions,
+  fetchLatestVersion,
+  readPackageInfo,
+  runGlobalInstall
+} from '../lib/package-info.js';
+
+function parseUpdateArgs(args) {
+  const options = { global: false, yes: false };
+  for (const arg of args) {
+    if (arg === '--global') {
+      options.global = true;
+    } else if (arg === '--yes') {
+      options.yes = true;
+    } else {
+      throw new Error(`Unknown update option: ${arg}`);
+    }
+  }
+  return options;
+}
+
+export async function runUpdate(args, deps = {}) {
+  const io = deps.io;
+  const readInfo = deps.readPackageInfo ?? readPackageInfo;
+  const fetchLatest = deps.fetchLatestVersion ?? fetchLatestVersion;
+  const installGlobal = deps.runGlobalInstall ?? runGlobalInstall;
+  const options = parseUpdateArgs(args);
+  const packageInfo = await readInfo();
+  const current = packageInfo.version;
+  const installCommand = 'npm install -g cowork-flow@latest';
+
+  let latest = null;
+  try {
+    latest = await fetchLatest('cowork-flow');
+  } catch (error) {
+    io.writeErr(`${error instanceof Error ? error.message : String(error)}\n`);
+    io.writeOut(`current=${current}\n`);
+    io.writeOut(`Unable to query npm latest. Run: ${installCommand}\n`);
+    return 0;
+  }
+
+  io.writeOut(`current=${current}\n`);
+  io.writeOut(`latest=${latest}\n`);
+
+  if (compareVersions(current, latest) >= 0) {
+    io.writeOut('cowork-flow is already up to date.\n');
+    return 0;
+  }
+
+  if (options.global && options.yes) {
+    const code = await installGlobal('cowork-flow@latest');
+    if (code === 0) {
+      io.writeOut('installed cowork-flow@latest\n');
+    }
+    return code;
+  }
+
+  io.writeOut(`Run: ${installCommand}\n`);
+  return 0;
+}

package/src/lib/copy-template.js

@@ -0,0 +1,189 @@
+import { constants } from 'node:fs';
+import { access, copyFile, mkdir, readdir, writeFile } from 'node:fs/promises';
+import { dirname, join, relative } from 'node:path';
+
+import { templateRoot } from './paths.js';
+
+async function pathExists(path) {
+  try {
+    await access(path, constants.F_OK);
+    return true;
+  } catch (error) {
+    if (error && error.code === 'ENOENT') {
+      return false;
+    }
+    throw error;
+  }
+}
+
+async function listFiles(root, current = root) {
+  const entries = await readdir(current, { withFileTypes: true });
+  const files = [];
+
+  for (const entry of entries) {
+    const absolute = join(current, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...await listFiles(root, absolute));
+    } else if (entry.isFile()) {
+      files.push(relative(root, absolute));
+    }
+  }
+
+  return files.sort();
+}
+
+export async function buildInitPlan(targetDir, options = {}) {
+  const files = await listFiles(templateRoot);
+  const actions = [];
+
+  for (const file of files) {
+    if (file === '.cowork-flow/.version' || file.startsWith('.superpowers/')) {
+      continue;
+    }
+
+    const source = join(templateRoot, file);
+    const destination = join(targetDir, file);
+    const exists = await pathExists(destination);
+    const action = exists ? (options.force ? 'update' : 'skip') : 'create';
+    actions.push({ action, source, destination, relativePath: file });
+  }
+
+  const versionDestination = join(targetDir, '.cowork-flow', '.version');
+  const versionExists = await pathExists(versionDestination);
+  actions.push({
+    action: versionExists ? (options.force ? 'update' : 'skip') : 'create',
+    source: null,
+    destination: versionDestination,
+    relativePath: '.cowork-flow/.version',
+    content: `${options.version}\n`
+  });
+
+  return actions;
+}
+
+export async function buildSuperpowersPlan(targetDir, options = {}) {
+  const sourceRoot = join(templateRoot, '.superpowers');
+  if (!await pathExists(sourceRoot)) {
+    return [];
+  }
+
+  const files = await listFiles(sourceRoot);
+  const actions = [];
+
+  for (const file of files) {
+    const source = join(sourceRoot, file);
+    const destination = join(targetDir, '.agent', 'skills', file);
+    const exists = await pathExists(destination);
+    const action = exists ? (options.force ? 'update' : 'skip') : 'create';
+    actions.push({ action, source, destination, relativePath: `.agent/skills/${file}` });
+  }
+
+  return actions;
+}
+
+const PROTECTED_SYNC_FILES = new Set([
+  'AGENTS.md',
+  '.cowork-flow/config.yaml',
+  '.cowork-flow/workflow.md'
+]);
+
+const PROTECTED_SYNC_PREFIXES = [
+  '.cowork-flow/spec/',
+  '.cowork-flow/workspace/',
+  '.cowork-flow/tasks/',
+  '.cowork-flow/changes/',
+  '.cowork-flow/plans/'
+];
+
+const SAFE_SYNC_PREFIXES = [
+  '.agent/skills/',
+  '.cowork-flow/scripts/'
+];
+
+const SAFE_SYNC_FILES = new Set([
+  '.cowork-flow/.gitignore',
+  '.cowork-flow/.version'
+]);
+
+function isProtectedSyncFile(relativePath) {
+  return PROTECTED_SYNC_FILES.has(relativePath)
+    || PROTECTED_SYNC_PREFIXES.some((prefix) => relativePath.startsWith(prefix));
+}
+
+function isSafeSyncFile(relativePath) {
+  return SAFE_SYNC_FILES.has(relativePath)
+    || SAFE_SYNC_PREFIXES.some((prefix) => relativePath.startsWith(prefix))
+    || relativePath.endsWith('/.gitkeep');
+}
+
+export async function buildSyncPlan(targetDir, options = {}) {
+  if (!await pathExists(join(targetDir, '.cowork-flow'))) {
+    throw new Error(`Target is not initialized: ${targetDir}`);
+  }
+
+  const files = await listFiles(templateRoot);
+  const actions = [];
+
+  for (const file of files) {
+    if (file === '.cowork-flow/.version' || file.startsWith('.superpowers/')) {
+      continue;
+    }
+
+    const source = join(templateRoot, file);
+    const destination = join(targetDir, file);
+    const exists = await pathExists(destination);
+    const protectedFile = isProtectedSyncFile(file) && !options.force && exists;
+    const safeFile = isSafeSyncFile(file);
+
+    if (protectedFile) {
+      actions.push({ action: 'protected', source, destination, relativePath: file });
+    } else if (exists && (safeFile || options.force)) {
+      actions.push({ action: 'update', source, destination, relativePath: file });
+    } else if (!exists) {
+      actions.push({ action: 'create', source, destination, relativePath: file });
+    } else {
+      actions.push({ action: 'protected', source, destination, relativePath: file });
+    }
+  }
+
+  actions.push({
+    action: 'update',
+    source: null,
+    destination: join(targetDir, '.cowork-flow', '.version'),
+    relativePath: '.cowork-flow/.version',
+    content: `${options.version}\n`
+  });
+
+  return actions;
+}
+
+export function summarizePlan(actions, dryRun = false) {
+  const counts = { create: 0, update: 0, skip: 0, protected: 0 };
+  for (const action of actions) {
+    counts[action.action] += 1;
+  }
+
+  const prefix = dryRun ? 'dry-run ' : '';
+  const createLabel = dryRun ? 'would-create' : 'created';
+  const updateLabel = dryRun ? 'would-update' : 'updated';
+  return `${prefix}${createLabel}=${counts.create} ${updateLabel}=${counts.update} skipped=${counts.skip} protected=${counts.protected}\n`;
+}
+
+export async function applyPlan(actions, options = {}) {
+  if (options.dryRun) {
+    return;
+  }
+
+  for (const item of actions) {
+    if (item.action === 'skip' || item.action === 'protected') {
+      continue;
+    }
+
+    await mkdir(dirname(item.destination), { recursive: true });
+    if (item.content !== undefined) {
+      await writeFile(item.destination, item.content, 'utf8');
+    } else {
+      await copyFile(item.source, item.destination);
+    }
+  }
+}