@xulthekl/team-flow 0.22.4

package/scripts/infer-workflow.mjs

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+// scripts/infer-workflow.mjs — infer hotfix/tweak/full from change artifacts
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { readState } from './lib/state-loader.mjs';
+
+const CODE_EXTS = [
+  'mjs', 'js', 'ts', 'jsx', 'tsx', 'cjs',
+  'java', 'go', 'py', 'pyw', 'rb', 'php',
+  'rs', 'kt', 'kts', 'swift',
+  'c', 'h', 'cc', 'cpp', 'cxx', 'hpp',
+  'cs', 'fs', 'fsx', 'vb',
+  'scala', 'sc', 'clj', 'cljs', 'ex', 'exs',
+  'dart', 'lua', 'r', 'pl', 'pm', 'sh', 'bash', 'zsh', 'fish',
+];
+const CONFIG_DOC_EXTS = [
+  'md', 'json', 'yaml', 'yml', 'toml', 'ini',
+  'txt', 'html', 'css',
+];
+const CODE_EXT_SET = new Set(CODE_EXTS);
+const CONFIG_DOC_EXT_SET = new Set(CONFIG_DOC_EXTS);
+const FILE_EXT_PATTERN = [...CODE_EXTS, ...CONFIG_DOC_EXTS]
+  .sort((a, b) => b.length - a.length)
+  .join('|');
+
+const FILE_RE = new RegExp(`\\b/?(?:[\\w-]+/)*[\\w-]+\\.(${FILE_EXT_PATTERN})\\b`, 'gi');
+
+function readText(dir, name) {
+  const p = join(dir, name);
+  return existsSync(p) ? readFileSync(p, 'utf-8') : '';
+}
+
+function countTasks(tasks) {
+  return (tasks.match(/^- \[([ x])\]/gm) || []).length;
+}
+
+function collectFiles(text) {
+  const matches = text.match(FILE_RE) || [];
+  return [...new Set(matches.map(m => m.trim()))];
+}
+
+function hasKeyword(text, patterns) {
+  const lower = text.toLowerCase();
+  return patterns.some(p => lower.includes(p.toLowerCase()));
+}
+
+function inferMode(changeDir) {
+  const state = readState(changeDir);
+
+  // Explicit override: honor any non-auto, non-null workflow value
+  if (state.workflow && state.workflow !== 'auto') {
+    const valid = ['hotfix', 'tweak', 'full'];
+    if (valid.includes(state.workflow)) {
+      return {
+        mode: state.workflow,
+        explicit: true,
+        reason: `workflow explicitly set to '${state.workflow}' in .team-flow.yaml; skipping auto-detection`,
+      };
+    }
+  }
+
+  const proposal = readText(changeDir, 'proposal.md');
+  const tasks = readText(changeDir, 'tasks.md');
+  const combined = `${proposal}\n${tasks}`;
+
+  const taskCount = countTasks(tasks);
+  const files = collectFiles(combined);
+  const fileCount = files.length;
+
+  const hasSchemaChange = hasKeyword(combined, [
+    'schema', 'api', 'interface', '接口', 'validator', '类型',
+    'type definition', 'protobuf', 'openapi', 'json schema',
+  ]);
+  const hasNewModule = hasKeyword(combined, [
+    'new module', '新增模块', '新模块', '新增 skill', '新目录',
+    '新增 capability', 'new capability',
+  ]);
+
+  const allExts = files.map(f => {
+    const parts = f.split('.');
+    return parts[parts.length - 1].toLowerCase();
+  });
+  const codeFileCount = allExts.filter(e => CODE_EXT_SET.has(e)).length;
+  const configDocOnly = codeFileCount === 0 && allExts.every(e => CONFIG_DOC_EXT_SET.has(e));
+
+  // No artifacts → safe default to full
+  if (taskCount === 0 && fileCount === 0) {
+    return {
+      mode: 'full',
+      explicit: false,
+      reason: 'no planning artifacts detected → full (safe default)',
+    };
+  }
+
+  // Hotfix: very small, no schema/api, no new module
+  if (taskCount <= 2 && fileCount <= 2 && !hasSchemaChange && !hasNewModule) {
+    return {
+      mode: 'hotfix',
+      explicit: false,
+      reason: `≤2 tasks, ≤2 files, no schema/API/new-module keywords → hotfix`,
+    };
+  }
+
+  // Tweak: small config/doc change
+  if (taskCount <= 4 && configDocOnly && !hasSchemaChange && !hasNewModule) {
+    return {
+      mode: 'tweak',
+      explicit: false,
+      reason: `≤4 tasks, only config/doc files, no schema/API/new-module keywords → tweak`,
+    };
+  }
+
+  // Default
+  return {
+    mode: 'full',
+    explicit: false,
+    reason: `${taskCount} tasks, ${fileCount} files${codeFileCount > 0 ? ` (${codeFileCount} code files)` : ''}${hasSchemaChange ? ', schema/API change detected' : ''}${hasNewModule ? ', new module detected' : ''} → full`,
+  };
+}
+
+function main() {
+  const changeDir = process.argv[2];
+  if (!changeDir) {
+    console.error('Usage: node scripts/infer-workflow.mjs <change-dir>');
+    process.exit(2);
+  }
+
+  const result = inferMode(changeDir);
+  console.log(JSON.stringify(result, null, 2));
+}
+
+export { inferMode };
+
+if (import.meta.filename === process.argv[1] || import.meta.url === `file://${process.argv[1]}`) {
+  main();
+}

package/scripts/install-amazon-q.mjs

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+// scripts/install-amazon-q.mjs — deploy team-flow for Amazon Q Developer CLI
+// Skills → .amazonq/skills/, phase-guard rule → .amazonq/rules/phase-guard.md
+import { installPlatform } from './lib/install.mjs';
+
+installPlatform('amazon-q').catch(err => {
+  console.error(`❌ ${err.message}`);
+  process.exit(1);
+});

package/scripts/install-cline.mjs

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+// scripts/install-cline.mjs — deploy team-flow for Cline
+// Skills → .cline/skills/, phase-guard rule → .clinerules/phase-guard.md
+import { installPlatform } from './lib/install.mjs';
+
+installPlatform('cline').catch(err => {
+  console.error(`❌ ${err.message}`);
+  process.exit(1);
+});

package/scripts/install-continue.mjs

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+// scripts/install-continue.mjs — deploy team-flow for Continue
+// Skills → .continue/skills/, phase-guard rule → .continue/rules/phase-guard.md
+import { installPlatform } from './lib/install.mjs';
+
+installPlatform('continue').catch(err => {
+  console.error(`❌ ${err.message}`);
+  process.exit(1);
+});

package/scripts/install-cursor.mjs

@@ -0,0 +1,265 @@
+#!/usr/bin/env node
+// scripts/install-cursor.mjs — deploy team-flow for Cursor Agent
+//
+// Copies the full plugin tree (skills + scripts + docs + templates + dist + hooks)
+// to .cursor/team-flow/ so that skill instructions referencing
+// ${CLAUDE_PLUGIN_ROOT}/scripts/... and ${CLAUDE_PLUGIN_ROOT}/docs/... resolve
+// correctly. Also copies skills to .cursor/skills/ (where Cursor reads them).
+//
+// Defaults to the latest GitHub release; use --local <path> to deploy from a local repo.
+import { existsSync, mkdirSync, readdirSync, statSync, rmSync, readFileSync, writeFileSync } from 'node:fs';
+import { cp, writeFile, mkdtemp } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { execFileSync } from 'node:child_process';
+import { parseArgs } from 'node:util';
+import { shellQuote } from './lib/shell-quote.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const defaultPluginRoot = dirname(__dirname); // repository root when running from clone
+const targetRoot = process.cwd();
+
+const GITHUB_REPO = 'MageByte-Zero/team-flow';
+const GITHUB_API_URL = `https://api.github.com/repos/${GITHUB_REPO}/releases/latest`;
+
+// Directories needed by local installer-rewritten runtime commands.
+const RUNTIME_DIRS = ['scripts', 'docs', 'templates', 'dist', 'hooks'];
+
+function ensureDir(dir) {
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+}
+
+async function fetchLatestTag() {
+  const res = await fetch(GITHUB_API_URL);
+  if (!res.ok) {
+    throw new Error(`GitHub API failed: ${res.status} ${res.statusText}`);
+  }
+  const data = await res.json();
+  if (!data.tag_name) {
+    throw new Error('GitHub API response missing tag_name');
+  }
+  return data.tag_name;
+}
+
+async function cloneRelease(tag) {
+  const tmpDir = await mkdtemp(join('/tmp', 'team-flow-'));
+  const url = `https://github.com/${GITHUB_REPO}.git`;
+  console.log(`📥 Cloning ${tag} into ${tmpDir} ...`);
+  execFileSync('git', ['clone', '--depth', '1', '--branch', tag, url, tmpDir], {
+    stdio: 'inherit',
+  });
+  return tmpDir;
+}
+
+/**
+ * Recursively copy a directory.
+ */
+async function copyDir(src, dst) {
+  if (!existsSync(src)) return 0;
+  ensureDir(dst);
+  const entries = readdirSync(src);
+  for (const name of entries) {
+    const srcPath = join(src, name);
+    const dstPath = join(dst, name);
+    const st = statSync(srcPath);
+    if (st.isDirectory()) {
+      await copyDir(srcPath, dstPath);
+    } else {
+      await cp(srcPath, dstPath, { force: true });
+    }
+  }
+  return entries.length;
+}
+
+/**
+ * Copy skills to target, replacing ${CLAUDE_PLUGIN_ROOT} with the actual
+ * plugin root path so skill instructions work in Cursor's environment.
+ */
+async function copySkillsWithRoot(sourceSkills, targetSkills, pluginRootAbs) {
+  // Clean old skill directories before copying
+  if (existsSync(targetSkills)) {
+    const oldEntries = readdirSync(targetSkills).filter(name => {
+      const full = join(targetSkills, name);
+      try { return statSync(full).isDirectory(); } catch { return false; }
+    });
+    for (const name of oldEntries) {
+      rmSync(join(targetSkills, name), { recursive: true, force: true });
+    }
+  }
+  ensureDir(targetSkills);
+  const entries = readdirSync(sourceSkills).filter(name => {
+    const full = join(sourceSkills, name);
+    try { return statSync(full).isDirectory(); } catch { return false; }
+  });
+
+  for (const name of entries) {
+    const src = join(sourceSkills, name);
+    const dst = join(targetSkills, name);
+    await cp(src, dst, { recursive: true, force: true });
+
+    // Replace ${CLAUDE_PLUGIN_ROOT} with the absolute path so commands work
+    const skillMd = join(dst, 'SKILL.md');
+    if (existsSync(skillMd)) {
+      let content = readFileSync(skillMd, 'utf-8');
+      if (content.includes('${CLAUDE_PLUGIN_ROOT}')) {
+        content = content.replace(/\$\{CLAUDE_PLUGIN_ROOT\}/g, pluginRootAbs);
+      }
+      content = content.replace(
+        /npx --yes --package @xulthekl\/team-flow@\d+\.\d+\.\d+ tf/g,
+        `node ${shellQuote(join(pluginRootAbs, 'scripts', 'team-flow.mjs'))}`,
+      );
+      writeFileSync(skillMd, content, 'utf-8');
+    }
+    // Also fix sub-prompt files (implementer-prompt.md, etc.)
+    const subFiles = readdirSync(dst).filter(f => f.endsWith('.md') && f !== 'SKILL.md');
+    for (const sub of subFiles) {
+      const subPath = join(dst, sub);
+      let content = readFileSync(subPath, 'utf-8');
+      if (content.includes('${CLAUDE_PLUGIN_ROOT}')) {
+        content = content.replace(/\$\{CLAUDE_PLUGIN_ROOT\}/g, pluginRootAbs);
+      }
+      content = content.replace(
+        /npx --yes --package @xulthekl\/team-flow@\d+\.\d+\.\d+ tf/g,
+        `node ${shellQuote(join(pluginRootAbs, 'scripts', 'team-flow.mjs'))}`,
+      );
+      writeFileSync(subPath, content, 'utf-8');
+    }
+  }
+
+  return entries.length;
+}
+
+async function writePhaseGuard(targetRules) {
+  ensureDir(targetRules);
+  const content = `---
+description: team-flow phase guard — 防止阶段漂移和未授权实现
+alwaysApply: true
+---
+
+# Phase Guard
+
+## 入口规则
+
+- 所有工作必须从 "/workflow-start" 入口开始。
+- 在 .team-flow.yaml 中确认当前 state 和 workflow 模式之前，不要开始写代码。
+
+## 全局禁止
+
+- 没有 execution-contract.md 或未经用户明确批准，不得进入实现。
+- full/hotfix 必须先运行 tf execution plan <change-dir> ...；没有 current execution plan 不得开始实现。
+- 只有 all pass review receipts 后才可 closing；不得把未审查的 wave 当作完成。
+- 上述 plan/receipt gates 仅适用于 full/hotfix；tweak 免除这些 gates (tweak exempt)。
+- 执行过程中如果发现需求/范围变化，必须回退到 specifying 或 bridging，而不是直接改代码。
+- 不要直接调用执行类 skill（如 "/build-executor"），必须通过入口路由。
+
+## 决策点协议
+
+- DP-0：设计前确认
+- DP-1：需求确认
+- DP-2：工件审查
+- DP-3：是否批准 execution contract？
+- DP-4：先运行 tf execution recommend，展示可用模式与推荐；用户用 --confirm 确认，非推荐选择额外使用 --acknowledge-recommendation
+- DP-5：调试升级
+- DP-6：验证失败
+- DP-7：是否收口归档？
+
+> 本文件由 scripts/install-cursor.mjs 生成；对具体变更的 guard 内容请运行 tf inject <change-dir> 更新。
+`;
+  await writeFile(join(targetRules, 'phase-guard.mdc'), content, 'utf-8');
+}
+
+async function writeCursorHooks(hooksDir) {
+  ensureDir(join(targetRoot, '.cursor'));
+  const hooksJson = {
+    hooks: [
+      {
+        event: 'sessionStart',
+        command: `bash ${join(hooksDir, 'session-start')}`,
+      },
+    ],
+  };
+  await writeFile(
+    join(targetRoot, '.cursor', 'hooks.json'),
+    JSON.stringify(hooksJson, null, 2) + '\n',
+    'utf-8',
+  );
+}
+
+async function main() {
+  const { values } = parseArgs({
+    options: {
+      local: { type: 'string' },
+      tag: { type: 'string' },
+    },
+  });
+
+  let pluginRoot = defaultPluginRoot;
+  let isTemp = false;
+  let installedTag = null;
+
+  if (values.local) {
+    pluginRoot = resolve(values.local);
+    console.log(`📁 Using local repo: ${pluginRoot}`);
+  } else {
+    installedTag = values.tag || await fetchLatestTag();
+    console.log(`⬆️  Installing team-flow ${installedTag} ...`);
+    pluginRoot = await cloneRelease(installedTag);
+    isTemp = true;
+  }
+
+  const sourceSkills = join(pluginRoot, 'skills');
+  if (!existsSync(sourceSkills)) {
+    console.error(`❌ skills/ directory not found at ${pluginRoot}`);
+    if (isTemp) rmSync(pluginRoot, { recursive: true, force: true });
+    process.exit(1);
+  }
+
+  // Target paths
+  const targetPluginDir = join(targetRoot, '.cursor', 'team-flow');
+  const targetSkills = join(targetRoot, '.cursor', 'skills');
+  const targetRules = join(targetRoot, '.cursor', 'rules');
+  const pluginRootAbs = resolve(targetPluginDir);
+
+  try {
+    // 1. Copy runtime dependencies to .cursor/team-flow/
+    console.log('📋 Copying runtime dependencies...');
+    for (const dir of RUNTIME_DIRS) {
+      const src = join(pluginRoot, dir);
+      const dst = join(targetPluginDir, dir);
+      if (existsSync(src)) {
+        const count = await copyDir(src, dst);
+        console.log(`   ${dir}/ → ${dst} (${count} entries)`);
+      } else {
+        console.log(`   ${dir}/ — skipped (not found)`);
+      }
+    }
+
+    // 2. Copy skills to .cursor/skills/ with CLAUDE_PLUGIN_ROOT replaced
+    const count = await copySkillsWithRoot(sourceSkills, targetSkills, pluginRootAbs);
+    console.log(`   skills/ → ${targetSkills} (${count} skills, paths rewritten)`);
+
+    // 3. Write phase guard rule
+    await writePhaseGuard(targetRules);
+    console.log(`   phase guard → ${join(targetRules, 'phase-guard.mdc')}`);
+
+    // 4. Write .cursor/hooks.json for session-start
+    await writeCursorHooks(join(targetPluginDir, 'hooks'));
+    console.log(`   hooks.json → ${join(targetRoot, '.cursor', 'hooks.json')}`);
+
+    console.log(`\n✅ Cursor install complete:`);
+    console.log(`   Plugin root: ${pluginRootAbs}`);
+    if (installedTag) {
+      console.log(`   Version:     ${installedTag}`);
+    }
+    console.log(`\nNext: open Cursor Agent and try "/workflow-start".`);
+  } finally {
+    if (isTemp) {
+      rmSync(pluginRoot, { recursive: true, force: true });
+    }
+  }
+}
+
+main().catch(err => {
+  console.error(`❌ ${err.message}`);
+  process.exit(1);
+});

package/scripts/install-git-hooks.mjs

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+// install-git-hooks.mjs — install git hooks for team-flow repo
+// Run with: npm run setup-hooks  (or node scripts/install-git-hooks.mjs)
+//
+// Installs a pre-commit hook that checks version consistency.
+// Automatically run post-install so every contributor gets the guard.
+
+import { writeFileSync, existsSync, chmodSync, readFileSync } from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { execFileSync } from 'node:child_process';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = join(__dirname, '..');
+// Ask Git for the common hooks directory so linked worktrees install correctly.
+// `git rev-parse --git-path hooks` may be relative in a normal checkout.
+const HOOKS_DIR = resolve(ROOT, execFileSync('git', ['rev-parse', '--git-path', 'hooks'], {
+  cwd: ROOT,
+  encoding: 'utf8',
+}).trim());
+const HOOK_PATH = join(HOOKS_DIR, 'pre-commit');
+
+const HOOK_SCRIPT = `#!/bin/sh
+# team-flow pre-commit hook — auto-check and fix version consistency
+# Installed by: npm run setup-hooks
+# Features:
+#   1. Run check-version-consistency (blocking on version mismatch)
+#   2. Auto-fix skill count and npx references (--fix mode)
+#   3. Re-stage fixed files so they're included in the commit
+# To bypass: git commit --no-verify
+
+set -e
+
+echo "🔍 Running pre-commit version consistency check..."
+
+REPO_ROOT="$(git rev-parse --show-toplevel)"
+
+cd "$REPO_ROOT"
+
+# Run check-versions with auto-fix
+if node scripts/check-version-consistency.mjs --fix; then
+  # Check if any files were modified by auto-fix
+  MODIFIED=$(git diff --name-only)
+  if [ -n "$MODIFIED" ]; then
+    echo "📝 Auto-fixed files detected, re-staging..."
+    echo "$MODIFIED" | xargs git add
+    echo "✅ Fixed files staged for commit"
+  fi
+  exit 0
+else
+  echo ""
+  echo "❌ Pre-commit check failed: version consistency issues found"
+  echo "   Fix the issues above and try again"
+  exit 1
+fi
+`;
+
+if (!existsSync(HOOKS_DIR)) {
+  console.error('❌ Not inside a git repository (no .git/hooks/).');
+  process.exit(1);
+}
+
+// Preserve an unrelated hook, but upgrade an older team-flow hook.
+const MARKER = '# team-flow pre-commit hook';
+if (existsSync(HOOK_PATH)) {
+  const existing = readFileSync(HOOK_PATH, 'utf-8');
+  if (existing.includes(MARKER)) {
+    if (existing === HOOK_SCRIPT) {
+      console.log('✅ Pre-commit hook already installed (team-flow).');
+      process.exit(0);
+    }
+    console.log('♻️  Updating existing pre-commit hook (team-flow).');
+  } else {
+    console.log('⚠️  Existing pre-commit hook found. Backing up to pre-commit.backup ...');
+    writeFileSync(`${HOOK_PATH}.backup`, existing);
+  }
+}
+
+writeFileSync(HOOK_PATH, HOOK_SCRIPT);
+chmodSync(HOOK_PATH, 0o755);
+console.log('✅ Pre-commit hook installed — version consistency checked before every commit.');
+console.log('   To bypass: git commit --no-verify');

package/scripts/install-kiro.mjs

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+// scripts/install-kiro.mjs — deploy team-flow for Kiro
+// Skills → .kiro/skills/, phase-guard rule → .kiro/steering/phase-guard.md
+import { installPlatform } from './lib/install.mjs';
+
+installPlatform('kiro').catch(err => {
+  console.error(`❌ ${err.message}`);
+  process.exit(1);
+});

package/scripts/install-pi.mjs

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+// scripts/install-pi.mjs — deploy team-flow for Pi agent
+// Skills → .pi/skills/ (global: .pi/agent/skills/). No rules dir — invoke "/workflow-start" manually.
+import { installPlatform } from './lib/install.mjs';
+
+installPlatform('pi').catch(err => {
+  console.error(`❌ ${err.message}`);
+  process.exit(1);
+});

package/scripts/install-qoder.mjs

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+// scripts/install-qoder.mjs — deploy team-flow for Qoder
+// Skills → .qoder/skills/, phase-guard rule → .qoder/rules/phase-guard.md
+import { installPlatform } from './lib/install.mjs';
+
+installPlatform('qoder').catch(err => {
+  console.error(`❌ ${err.message}`);
+  process.exit(1);
+});

package/scripts/install-qwen.mjs

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+// scripts/install-qwen.mjs — deploy team-flow for Qwen Code
+// Skills → .qwen/skills/, phase-guard rule → .qwen/rules/phase-guard.md
+import { installPlatform } from './lib/install.mjs';
+
+installPlatform('qwen').catch(err => {
+  console.error(`❌ ${err.message}`);
+  process.exit(1);
+});

package/scripts/install-roocode.mjs

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+// scripts/install-roocode.mjs — deploy team-flow for Roo Code
+// Skills → .roo/skills/, phase-guard rule → .roo/rules/phase-guard.md
+import { installPlatform } from './lib/install.mjs';
+
+installPlatform('roocode').catch(err => {
+  console.error(`❌ ${err.message}`);
+  process.exit(1);
+});

package/scripts/install-windsurf.mjs

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+// scripts/install-windsurf.mjs — deploy team-flow for Windsurf
+// Skills → .windsurf/skills/, phase-guard rule → .windsurf/rules/phase-guard.md
+import { installPlatform } from './lib/install.mjs';
+
+installPlatform('windsurf').catch(err => {
+  console.error(`❌ ${err.message}`);
+  process.exit(1);
+});