cowork-flow 0.0.16 → 0.0.17

package/README.md

@@ -2,7 +2,7 @@
 
 cowork-flow 是一个用于新项目初始化协作流程的模板仓库。它把项目说明、任务流转、规格治理、开发计划和会话记录放在一套可复制的目录结构里，帮助团队在项目早期就建立清晰的工作闭环。
 
-这个仓库本身不绑定具体技术栈，也不提供业务代码脚手架。它提供的是协作与治理基础设施：你可以把 `template/` 复制到目标项目中，再按目标项目的真实情况补充技术栈、验证命令、目录规范和提交策略。
+这个仓库本身不绑定具体技术栈，也不提供业务代码脚手架。它提供的是协作与治理基础设施：你可以把 `template/` 复制到目标项目中，再按目标项目的真实情况补充技术栈、质量门禁、目录规范和提交策略。
 
 ## 适用场景
 
@@ -23,12 +23,13 @@ cowork-flow 是一个用于新项目初始化协作流程的模板仓库。它
 ├── README.md
 └── template/
     ├── AGENTS.md
+    ├── .codex/
+    │   └── agents/
     ├── .agent/
     │   └── skills/
     └── .cowork-flow/
         ├── config.yaml
         ├── workflow.md
-        ├── agent-team/
         ├── scripts/
         ├── spec/
         ├── changes/
@@ -43,10 +44,16 @@ cowork-flow 是一个用于新项目初始化协作流程的模板仓库。它
 项目级协作入口，包含编码前思考、简单优先、外科手术式改动、验证优先等基础原则。接入项目后，应把项目名称、技术栈、运行命令、测试命令和提交策略补齐。
 
 `template/.agent/skills/`
-本地技能入口，覆盖开始工作、收尾验证、记录 session、更新规范、跨层检查等常见协作动作。这里的 skill 应保持通用，不承载某个业务项目的一次性细节。
+本地技能入口，覆盖 start、before-dev、brainstorming、writing-plans、check、finish-work、continue、meta、python-design、update-spec 和 break-loop 等协作动作。这里的 skill 应保持通用，不承载某个业务项目的一次性细节。
+
+`template/.codex/agents/`
+固定角色 agent 定义，包含 `cowork-research`、`cowork-implement` 和 `cowork-check`。主会话负责计划与收口，并用 Codex `spawn_agent` 派发固定 agent；派发必须使用 `fork_turns="none"`，提示词首行使用 `Active task: <task-dir>`。
+
+`template/.codex/config.toml`、`template/.codex/hooks.json`、`template/.codex/hooks/`
+Codex 项目级配置与每轮上下文注入入口。hook 会读取当前 session task、`.cowork-flow/workflow.md` 中的 `workflow-state` 片段和 `codex.dispatch_mode`，把流程状态注入到当前轮对话。
 
 `template/.cowork-flow/`
-工作流目录，包含流程说明、任务状态、开发者工作区、项目规范、行为变更规格、实现计划和辅助脚本。`.cowork-flow/config.yaml` 用于填写项目自己的 lint、build、test 等验证命令。
+工作流目录，包含流程说明、任务状态、开发者工作区、项目规范、行为变更规格、实现计划和辅助脚本。`.cowork-flow/config.yaml` 只承载真实接线的 session/journal, Codex hint, and task lifecycle hook settings。
 
 `template/.cowork-flow/spec/`
 项目规范目录，预置了 backend、frontend 和 guides 三类说明。接入时应按项目事实保留、改写或删除对应规范。
@@ -57,9 +64,6 @@ cowork-flow 是一个用于新项目初始化协作流程的模板仓库。它
 `template/.cowork-flow/plans/`
 保存可执行步骤、验证方式和执行状态。
 
-`template/.cowork-flow/agent-team/`
-保存 agent team 的项目级 registry、适配器和策略。默认适配器是 `codex`，由主 agent 调度 Codex 子 agent；没有子 agent 能力时可退回 `manual` 提示词模式。
-
 ## 快速开始
 
 使用 CLI 把模板内容安装到目标项目根目录：
@@ -68,17 +72,23 @@ cowork-flow 是一个用于新项目初始化协作流程的模板仓库。它
 npx cowork-flow init ./my-project
 ```
 
+`init` 会显式要求开发者身份。交互式终端会提示输入；脚本或 CI 请传入：
+
+```bash
+npx cowork-flow init ./my-project --developer <your-name>
+```
+
 也可以先全局安装：
 
 ```bash
 npm install -g cowork-flow
-cowork-flow init ./my-project
+cowork-flow init ./my-project --developer <your-name>
 ```
 
 初始化后优先完成这些配置：
 
 1. 更新 `AGENTS.md` 中的项目名称、技术栈、命令和提交策略。
-2. 更新 `.cowork-flow/config.yaml` 中的验证命令。
+2. 按需调整 `.cowork-flow/config.yaml` 中的 session/journal, Codex hint, and task lifecycle hook settings。
 3. 更新 `.cowork-flow/workflow.md` 中与项目流程不一致的门禁、分级和完成定义。
 4. 按项目实际情况调整 `.cowork-flow/spec/`，删除不存在的 frontend、backend 或行为变更场景。
 5. 按团队实践使用 `.cowork-flow/changes/` 管理规格变更，使用 `.cowork-flow/plans/` 管理实现计划和验证状态。
@@ -97,8 +107,7 @@ npx cowork-flow --help
 cowork-flow init ./my-project
 ```
 
-`init` 会询问你是否已经安装了 Superpowers skills。选择未安装时，会把内置的 `.superpowers/` 技能复制到目标项目的 `.agent/skills/` 下。
-在非交互环境里，这一步会自动跳过询问并默认视为已安装。
+`init` 会直接复制模板中的 `.agent/skills/`、`.codex/` 和 `.cowork-flow/`，并初始化 `.cowork-flow/.developer` 与 `.cowork-flow/workspace/<developer>/`。交互式终端会提示输入开发者名称；非交互式环境必须传入 `--developer <name>`。`init` 不会复制额外技能包。
 
 初始化到当前项目：
 
@@ -115,9 +124,11 @@ cowork-flow init ./my-project --dry-run
 需要明确覆盖已有文件时使用：
 
 ```bash
-cowork-flow init ./my-project --force
+cowork-flow init ./my-project --force --developer <your-name>
 ```
 
+`--force` 不会静默覆盖既有 `.cowork-flow/.developer`；如需重设身份，请先显式处理旧身份文件。
+
 升级 CLI 本身：
 
 ```bash
@@ -176,18 +187,21 @@ cowork-flow sync . --dry-run
 ./.cowork-flow/run task start <task-dir>
 ```
 
-执行 plan 时准备 agent team：
+执行 plan 时使用固定 cowork agents：
 
-默认 `agent_team.enabled: false`。运行 `agent-team prepare/status/next/record-result/record-review/retry/complete` 前，先在 `.cowork-flow/config.yaml` 中设置 `agent_team.enabled: true`。
+主会话负责创建/启动任务、维护计划与收口验证；可并行的实现或检查工作通过 Codex subagent 交给固定角色 agent。
 
-```bash
-./.cowork-flow/run agent-team init
-./.cowork-flow/run agent-team prepare <task-dir> --plan <plan-file>
-./.cowork-flow/run agent-team next <task-dir>
-./.cowork-flow/run agent-team complete <task-dir>
+```python
+spawn_agent(
+    agent_type="cowork-implement",
+    fork_turns="none",
+    message="Active task: <task-dir>\n\n<assignment>",
+)
 ```
 
-`agent-team` 命令会生成任务目录内的 dispatch plan、assignments、状态、审阅和 metrics 工件。默认 `codex` 适配器采用主 agent 调度型：脚本生成 Codex-ready 分派文件，主 agent 负责调用子 agent、协调并回写结果。
+默认角色为 `cowork-research`、`cowork-implement`、`cowork-check`，任务上下文由 agent 根据 active task 自行加载。主会话必须用 `wait_agent` 等待结果，验收输出，再用 `list_agents` / `close_agent` 收口。
+
+Codex hook 启用后，每轮会自动注入 `<workflow-state>`，其中包含当前任务、状态来源和下一步流程提示。hook 不替代主会话验收；它只负责把 task 状态和 workflow gate 放进上下文。
 
 记录 session：
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cowork-flow",
-  "version": "0.0.16",
+  "version": "0.0.17",
   "description": "CLI for installing and maintaining cowork-flow collaboration templates.",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -1,3 +1,6 @@
+import { stdin as input, stdout as output } from 'node:process';
+import { createInterface } from 'node:readline/promises';
+
 import { runInit } from './commands/init.js';
 import { runSync } from './commands/sync.js';
 import { runUpdate } from './commands/update.js';
@@ -6,7 +9,7 @@ import { readPackageInfo } from './lib/package-info.js';
 const HELP = `cowork-flow
 
 Usage:
-  cowork-flow init [target] [--dry-run] [--force]
+  cowork-flow init [target] [--developer <name>] [--dry-run] [--force]
   cowork-flow update [--global] [--yes]
   cowork-flow sync [target] [--dry-run] [--force]
   cowork-flow --version
@@ -24,8 +27,21 @@ function defaultIo() {
   };
 }
 
+async function defaultPrompt(message) {
+  if (!input.isTTY || !output.isTTY) {
+    return null;
+  }
+  const readline = createInterface({ input, output });
+  try {
+    return await readline.question(message);
+  } finally {
+    readline.close();
+  }
+}
+
 export async function main(argv = process.argv.slice(2), options = {}) {
   const io = options.io ?? defaultIo();
+  const prompt = Object.hasOwn(options, 'prompt') ? options.prompt : defaultPrompt;
   const [command, ...args] = argv;
 
   try {
@@ -41,7 +57,7 @@ export async function main(argv = process.argv.slice(2), options = {}) {
     }
 
     if (command === 'init') {
-      return await runInit(args, { io, prompt: options.prompt });
+      return await runInit(args, { io, prompt });
     }
 
     if (command === 'sync') {

package/src/commands/init.js

@@ -1,21 +1,30 @@
-import { resolve } from 'node:path';
-import { createInterface } from 'node:readline/promises';
+import { access, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
 
 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) {
+  const options = { developer: null, dryRun: false, force: false, target: process.cwd() };
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
     if (arg === '--dry-run') {
       options.dryRun = true;
     } else if (arg === '--force') {
       options.force = true;
+    } else if (arg === '--developer') {
+      const value = args[index + 1];
+      if (!value || value.startsWith('--')) {
+        throw new Error('Missing value for --developer');
+      }
+      options.developer = value;
+      index += 1;
+    } else if (arg.startsWith('--developer=')) {
+      options.developer = arg.slice('--developer='.length);
     } else if (arg.startsWith('--')) {
       throw new Error(`Unknown init option: ${arg}`);
     } else {
@@ -25,27 +34,139 @@ function parseInitArgs(args) {
   return options;
 }
 
-function isAffirmative(answer) {
-  const normalized = answer.trim().toLowerCase();
-  return normalized === 'y' || normalized === 'yes' || normalized === 'true' || normalized === '1';
+async function pathExists(path) {
+  try {
+    await access(path);
+    return true;
+  } catch (error) {
+    if (error && error.code === 'ENOENT') {
+      return false;
+    }
+    throw error;
+  }
 }
 
-async function defaultSuperpowersPrompt(io) {
-  if (!process.stdin.isTTY || !process.stdout.isTTY) {
-    io.writeOut('Superpowers prompt skipped because stdin is not interactive.\n');
-    return true;
+function normalizeDeveloperName(value) {
+  const name = String(value ?? '').trim();
+  if (!name) {
+    throw new Error('Developer name required. Run: cowork-flow init <target> --developer <name>');
+  }
+  if (/[\\/]/.test(name)) {
+    throw new Error('Developer name must not contain path separators');
   }
+  return name;
+}
 
-  const rl = createInterface({
-    input: process.stdin,
-    output: process.stdout
-  });
+async function readExistingDeveloper(target) {
+  const developerFile = join(target, '.cowork-flow', '.developer');
+  if (!await pathExists(developerFile)) {
+    return null;
+  }
+  const content = await readFile(developerFile, 'utf8');
+  const match = content.match(/^name=(.+)$/m);
+  return match ? match[1].trim() : null;
+}
 
-  try {
-    const answer = await rl.question('Have you already installed Superpowers skills? [y/N] ');
-    return isAffirmative(answer);
-  } finally {
-    rl.close();
+async function resolveDeveloperName(options, prompt) {
+  const existing = await readExistingDeveloper(options.target);
+  if (existing) {
+    return { existing: true, name: existing };
+  }
+
+  if (options.dryRun && !options.developer) {
+    return { existing: false, name: null };
+  }
+
+  let name = options.developer;
+  if (!name && typeof prompt === 'function') {
+    name = await prompt('Developer name: ');
+  }
+
+  return { existing: false, name: normalizeDeveloperName(name) };
+}
+
+function todayIsoDate() {
+  return new Date().toISOString().slice(0, 10);
+}
+
+function initialJournalContent(name) {
+  return `# Development Journal - ${name} (Part 1)
+
+> AI development session journal
+> Start date: ${todayIsoDate()}
+
+---
+
+`;
+}
+
+function initialIndexContent(name) {
+  return `# Workspace Index - ${name}
+
+> Tracks AI development session records.
+
+---
+
+## Current Status
+
+<!-- @@@auto:current-status -->
+- **Current file**: \`journal-1.md\`
+- **Total Sessions**: 0
+- **Last Active**: -
+<!-- @@@/auto:current-status -->
+
+---
+
+## Active Documents
+
+<!-- @@@auto:active-documents -->
+| File | Lines | Status |
+|------|------|------|
+| \`journal-1.md\` | ~0 | Current |
+<!-- @@@/auto:active-documents -->
+
+---
+
+## Session History
+
+<!-- @@@auto:session-history -->
+| # | Date | Title | Commit |
+|---|------|------|------|
+<!-- @@@/auto:session-history -->
+
+---
+
+## Notes
+
+- Sessions are appended to the journal file
+- A new journal file is created automatically after the current file exceeds 2000 lines
+- Use \`add_session.py\` to record sessions
+- New records use English text; legacy records can remain as they are
+`;
+}
+
+async function initializeDeveloper(target, developer) {
+  const workflowDir = join(target, '.cowork-flow');
+  const developerFile = join(workflowDir, '.developer');
+  const workspaceDir = join(workflowDir, 'workspace', developer.name);
+  const journalFile = join(workspaceDir, 'journal-1.md');
+  const indexFile = join(workspaceDir, 'index.md');
+
+  await mkdir(workflowDir, { recursive: true });
+  if (!developer.existing) {
+    await writeFile(
+      developerFile,
+      `name=${developer.name}\ninitialized_at=${new Date().toISOString()}\n`,
+      'utf8'
+    );
+  }
+
+  await mkdir(workspaceDir, { recursive: true });
+  if (!await pathExists(journalFile)) {
+    await writeFile(journalFile, initialJournalContent(developer.name), 'utf8');
+  }
+  if (!await pathExists(indexFile)) {
+    await writeFile(indexFile, initialIndexContent(developer.name), 'utf8');
   }
 }
 
@@ -53,8 +174,9 @@ export async function runInit(args, { io, prompt }) {
   return runInitWithOptions(args, { io, prompt });
 }
 
-export async function runInitWithOptions(args, { io, prompt = defaultSuperpowersPrompt }) {
+export async function runInitWithOptions(args, { io, prompt }) {
   const options = parseInitArgs(args);
+  const developer = await resolveDeveloperName(options, prompt);
   const packageInfo = await readPackageInfo();
   const plan = await buildInitPlan(options.target, {
     force: options.force,
@@ -65,24 +187,22 @@ export async function runInitWithOptions(args, { io, prompt = defaultSuperpowers
   io.writeOut(summarizePlan(plan, options.dryRun));
 
   if (options.dryRun) {
-    io.writeOut('Superpowers prompt skipped in dry-run.\n');
+    if (developer.existing) {
+      io.writeOut(`dry-run preserve-existing=.cowork-flow/.developer for developer ${developer.name}\n`);
+    } else if (developer.name) {
+      io.writeOut(`dry-run would-create=.cowork-flow/.developer for developer ${developer.name}\n`);
+      io.writeOut(`dry-run would-create=.cowork-flow/workspace/${developer.name}/\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;
+  await initializeDeveloper(options.target, developer);
+  if (developer.existing) {
+    io.writeOut(`Developer already initialized: ${developer.name}\n`);
+  } else {
+    io.writeOut(`Developer initialized: ${developer.name}\n`);
   }
-
-  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/lib/copy-template.js

@@ -36,16 +36,12 @@ function toTemplatePath(relativePath) {
   return relativePath.replaceAll('\\', '/');
 }
 
-export function isInternalTemplateFile(relativePath) {
-  return toTemplatePath(relativePath).startsWith('.superpowers/');
-}
-
 export async function buildInitPlan(targetDir, options = {}) {
   const files = await listFiles(templateRoot);
   const actions = [];
 
   for (const file of files) {
-    if (toTemplatePath(file) === '.cowork-flow/.version' || isInternalTemplateFile(file)) {
+    if (toTemplatePath(file) === '.cowork-flow/.version') {
       continue;
     }
 
@@ -69,26 +65,6 @@ export async function buildInitPlan(targetDir, options = {}) {
   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([
   '.cowork-flow/config.yaml'
 ]);
@@ -102,6 +78,7 @@ const PROTECTED_SYNC_PREFIXES = [
 ];
 
 const SAFE_SYNC_PREFIXES = [
+  '.codex/',
   '.agent/skills/',
   '.cowork-flow/'
 ];
@@ -180,7 +157,7 @@ export async function buildSyncPlan(targetDir, options = {}) {
   const actions = [];
 
   for (const file of files) {
-    if (toTemplatePath(file) === '.cowork-flow/.version' || isInternalTemplateFile(file)) {
+    if (toTemplatePath(file) === '.cowork-flow/.version') {
       continue;
     }
 

package/template/.agent/skills/before-dev/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: before-dev
+description: Use before writing code in a cowork-flow project to load project-specific guidelines, active task context, and verification expectations.
+---
+
+# Before Dev
+
+Use this immediately before code edits.
+
+## Read
+
+1. `AGENTS.md`
+2. `.cowork-flow/workflow.md`
+3. Active task `prd.md`
+4. Active task `implement.jsonl`
+5. Relevant `.cowork-flow/spec/*/index.md`
+6. Any exact files named by the task, plan, or user
+
+Do not bulk-load unrelated tasks, archived sessions, or every spec file.
+
+## Confirm
+
+State briefly:
+
+- Assumptions.
+- Success criteria.
+- Files or modules likely to change.
+- Verification command you expect to run.
+- Whether fixed agents or inline work are appropriate.
+
+If the task is a bounded subagent prompt, do not convert it into main-session planning.