@xulthekl/team-flow 0.33.0 → 0.34.0

package/.claude/always/phase-guard.md

@@ -1,3 +1,3 @@
-# team-flow v0.33.0 | 阶段: {{state}} | 工作流: {{workflow}}
+# team-flow v0.34.0 | 阶段: {{state}} | 工作流: {{workflow}}
 当前阶段允许的操作由 workflow-start 路由规则定义。
 禁止跨越 DP gate 进入下一阶段。变更范围以 execution-contract.md 的 Intent Lock 为准。

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "team-flow",
       "description": "8-state spec workflow + compound global compounding + architecture-design (4A/DDD) + local HTML prototype + product-level orchestration + bootstrap + e2e + session handoff + workflow feedback. 24 skills + 15 agents with embedded TDD, SDD, code review, debugging, delta spec sync, and design-system-driven prototyping.",
-      "version": "0.33.0",
+      "version": "0.34.0",
       "source": "./",
       "author": {
         "name": "LT",

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "team-flow",
-  "version": "0.33.0",
+  "version": "0.34.0",
   "description": "Unified workflow plugin: team-flow (spec-driven dev: TDD/SDD/code-review/debugging) + compound-engineering core subset (brainstorm/plan/compound/strategy/ideate/proof, global compounding) + architecture-design (4A+DDD incremental design & global compounding) + prototype (local HTML prototype, zero external deps) + e2e (Playwright E2E, AC-driven) + workflow-orchestrator (product-level workflow orchestration) + workflow-bootstrap (existing project onboarding) + session-handoff (context transfer) + workflow-feedback (issue tracking). 24 skills + 15 agents, one install.",
   "source": "./",
   "author": {

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "team-flow",
-  "version": "0.33.0",
+  "version": "0.34.0",
   "description": "Spec-first workflow that bridges OpenSpec-style planning and Superpowers-style execution discipline.",
   "author": {
     "name": "MageByte",

package/.cursor-plugin/marketplace.json

@@ -5,7 +5,7 @@
   },
   "metadata": {
     "description": "Unified workflow plugin marketplace for Cursor (team-flow: team-flow + compound + architecture-design + prototype).",
-    "version": "0.33.0"
+    "version": "0.34.0"
   },
   "plugins": [
     {

package/.cursor-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "team-flow",
   "displayName": "team-flow",
   "description": "Unified workflow plugin: team-flow (spec-driven dev: TDD/SDD/code-review/debugging) + compound-engineering core subset (brainstorm/plan/compound/strategy/ideate/proof, global compounding) + architecture-design (4A+DDD incremental design & global compounding) + prototype (local HTML prototype, zero external deps) + e2e (Playwright E2E, AC-driven) + workflow-orchestrator (product-level workflow orchestration) + workflow-bootstrap (existing project onboarding) + session-handoff (context transfer) + workflow-feedback (issue tracking). 24 skills + 15 agents, one install.",
-  "version": "0.33.0",
+  "version": "0.34.0",
   "author": {
     "name": "LT",
     "url": "https://github.com/LT"

package/.github/plugin/marketplace.json

@@ -6,13 +6,13 @@
   },
   "metadata": {
     "description": "Unified workflow plugins and skills for AI coding agents (team-flow: team-flow + compound + architecture-design + prototype).",
-    "version": "0.33.0"
+    "version": "0.34.0"
   },
   "plugins": [
     {
       "name": "team-flow",
       "description": "Unified workflow with planning artifacts, execution contracts, TDD, review gates, systematic debugging, delta spec sync, architecture-design, and local HTML prototyping.",
-      "version": "0.33.0",
+      "version": "0.34.0",
       "source": ".",
       "author": {
         "name": "LT",

package/AGENTS.md

@@ -210,6 +210,8 @@ STRATEGY.md CONCEPTS.md 产品策略(BA) / 领域词汇
 
 ### Agents 索引（v0.7 新增，v0.30.0 增至 15 个）
 
+> **agent 文件设计规范见 CONTRIBUTING.md §6 + `templates/agent-template.md`**（v0.33.0）：frontmatter 必须合法 YAML（非法时 Claude Code 静默降级，skills: 预加载与 tools: 限制全部失效）；description 单句、禁 `<example>` 块；新增/修改 agent 必过 frontmatter-lint + 实证探针。
+
 | Agent | 职责 | Tools | 触发场景 |
 |-------|------|-------|---------|
 | architecture-design | 架构设计门控 agent——五项检查 + 三件套产出 + SQL 制品（workflow-start 子代理调用，判断+执行一体化） | Read/Bash/Grep/Glob/Write | workflow-start exploring→specifying 状态转换时（架构设计门控，v0.27.2） |

package/CHANGELOG.md

@@ -6,6 +6,41 @@ The format loosely follows Keep a Changelog.
 
 ## [Unreleased]
 
+## [0.34.0] - 2026-08-04
+
+### Added（测试能力增强——吸收 glaf4-test 通用能力 + conventions 机制，设计见工作区级文档 team-flow-workspace/docs/plan/test-capability-enhancement-design.md）
+
+#### P0：组合覆盖声明（test-strategy SKILL.md）
+- **§8 组合覆盖声明**：多参数方法（param_count > 1）必须声明 `pairwise`，有分支逻辑必须声明 `branch`；contract-builder 生成矩阵后强制对账
+
+#### P1：测试质量规则 + failure 分类法
+- **skills/test-strategy/references/test-quality-rules.md**：从 glaf4-test scan-generated-tests.py 抽取 16 条通用规则（断言质量、调试代码残留、测试状态、测试数据、测试结构、矩阵对账、语言特定）
+- **scripts/lib/test-record.mjs**：新增 `classifyFailure` 函数，测试失败时自动分类为 6 类（assertion_failure / runtime_error / framework_error / compile_error / dependency_blocker / unknown），记录到 test_result
+
+#### P2：社交测试契约 + 测试隔离分级
+- **skills/test-strategy/references/integration-test-contracts.md**：5 种契约类型（入口/协作者/数据/中间件/清理），集成测试的组织方法论
+- **skills/test-strategy/references/integration-test-isolation.md**：4 级隔离策略（L1 进程内 / L2 事务 / L3 手动清理 / L4 无隔离），基础设施隔离策略
+
+#### P2：conventions 机制建设（v0.34.0 核心特性）
+- **templates/conventions/**：plugin 内置 conventions 模板
+  - `glaf4-compliant/java-testing.md`：Java 测试规范（JUnit 5 + Mockito），符合 glaf4-test 要求
+  - `glaf4-compliant/spring-patterns.md`：Spring Boot 测试规范，符合 glaf4-test 要求
+  - `js-testing.md`：JavaScript 测试规范（Jest/Vitest）
+  - `python-testing.md`：Python 测试规范（Pytest）
+  - `_manifest.json`：模板清单（版本、描述、适用技术栈）
+- **scripts/lib/conventions-generator.mjs**：conventions 生成器脚本
+  - 技术栈自动检测（Java/JavaScript/Python）
+  - conventions 模板选择和生成
+  - 版本管理机制（.versions.json）
+  - team-flow.config.json 自动更新
+  - 支持存量项目（自动识别）和全新项目（交互式引导）
+- **skills/workflow-bootstrap/SKILL.md**：增加 B1.5 阶段（Conventions Generator）
+
+### Tests
+- **tests/lib/conventions-generator.test.mjs**：15 个测试（detectTechStack/selectTemplates/generateConventions/updateConfig）
+- 全量回归：571/571 通过（含 15 个新增测试）
+- check-versions ✅
+
 ## [0.33.0] - 2026-08-03
 
 ### Fixed（skills 注入恢复——frontmatter YAML 非法导致预加载静默失效，设计见工作区级文档 team-flow-workspace/docs/architecture-api-db-design-enhancement-v0.13.md §54）

package/CONTRIBUTING.md

@@ -86,6 +86,50 @@ Skill text should help an agent decide:
 
 Avoid vague motivational language when an operational rule would be clearer.
 
+### 6. Agent file design spec (v0.33.0+)
+
+Background: before v0.33.0, every agent's YAML frontmatter was invalid (an
+`<example>` block at column 0 inside the `description` field). Claude Code
+degrades SILENTLY on invalid frontmatter — `skills:` preload and `tools:`
+restrictions are dropped with no warning, and the agent body alone is kept.
+The defect survived the entire plugin lifetime. `tests/lib/frontmatter-lint.test.mjs`
+(npm test) is the machine gate; this spec is the human gate.
+
+Copy `templates/agent-template.md` when creating a new agent. Hard rules:
+
+1. **`description` is a single-line string.** No `>-` block scalars, no
+   `<example>` blocks — the official Anthropic plugin-dev agents use that
+   pattern and it is a trap (it breaks YAML indentation and silently disables
+   the whole frontmatter). If the text must contain an ASCII `: `, wrap the
+   entire value in double quotes. team-flow agents are dispatched explicitly
+   by `workflow-start`, so example-driven auto-triggering buys nothing.
+2. **`name` must equal the file name** (minus `.md`). On degraded parsing the
+   registry falls back to the file name — a mismatch means silent mislabeling.
+3. **Declare `tools` explicitly.** Since v0.33.0 the restriction is enforced;
+   the subagent holds ONLY the declared tools (no MCP tools unless listed).
+4. **`skills` entries must resolve.** Each entry must match an existing
+   `skills/<name>/SKILL.md` (bare name, same as glaf4-test's proven pattern).
+   A dangling entry means a silent no-preload.
+5. **Body ≤ 100 lines, WHO/WHAT only.** No SOP/methodology in the body — that
+   belongs to the preloaded Skill. If the body says "Your preloaded Skill
+   contains the detailed methodology", the `skills:` field MUST declare it.
+
+Anti-patterns (forbidden):
+
+- `<example>` blocks anywhere in frontmatter
+- Unquoted ASCII `: ` inside `description` values
+- Copying frontmatter style from other plugins without running the lint
+
+Verification (mandatory for new/changed agents):
+
+1. `npm test` — the frontmatter-lint gate must pass.
+2. **Empirical probe** — dispatch the agent once and verify with a BEHAVIORAL
+   probe (ask it to recite a rule that exists only in the preloaded Skill or
+   the agent body). Do NOT rely on exact-string introspection questions — they
+   produce false negatives. Do not write "mechanism works" claims into any doc
+   without this probe. See design doc §54.6 (workspace-level
+   `docs/architecture-api-db-design-enhancement-v0.13.md`).
+
 ## Pull Request Guidance
 
 When opening a change, explain:

package/GEMINI.md

@@ -8,7 +8,7 @@ The workflow is self-contained and does not require OpenSpec or Superpowers at r
 
 
 <!-- team-flow-phase-guard-start -->
-# team-flow v0.33.0 | 阶段: {{state}} | 工作流: {{workflow}}
+# team-flow v0.34.0 | 阶段: {{state}} | 工作流: {{workflow}}
 当前阶段允许的操作由 workflow-start 路由规则定义。
 禁止跨越 DP gate 进入下一阶段。变更范围以 execution-contract.md 的 Intent Lock 为准。
 <!-- team-flow-phase-guard-end -->

package/INSTALL.md

@@ -7,7 +7,7 @@
 - [Fission-AI/OpenSpec](https://github.com/Fission-AI/OpenSpec) — 规划引擎（Schema 验证、Delta Spec、工件解析）
 - [obra/superpowers](https://github.com/obra/superpowers) — 执行纪律（TDD 铁律、SDD、系统化调试、代码审查）
 
-当前发布版本：**v0.33.0**。
+当前发布版本：**v0.34.0**。
 
 ---
 

package/README.md

@@ -1,6 +1,6 @@
 # team-flow
 
-> 当前版本：`v0.33.0`
+> 当前版本：`v0.34.0`
 
 > 统一插件：**team-flow**（spec 驱动开发）+ **compound-engineering 核心子集**（全局复利）+ **architecture-design**（4A+DDD 增量设计）+ **prototype**（本地 HTML 原型）+ **e2e**（AC 驱动 E2E）+ **workflow-orchestrator**（产品级编排）+ **workflow-bootstrap**（既有项目接入）。一次安装，七套能力协同。
 

package/docs/README_en.md

@@ -126,7 +126,7 @@ npm install -g team-flow
 
 ### Version
 
-- Current: `v0.33.0`
+- Current: `v0.34.0`
 - v0.9.1 highlights: DP-4 execution-mode recommendations, a portable runtime across 17 platforms, and a raw-package smoke with no plugin-root variable.
 - Self-contained — no OpenSpec or Superpowers runtime required
 - Upstream: [Fission-AI/OpenSpec](https://github.com/Fission-AI/OpenSpec), [obra/superpowers](https://github.com/obra/superpowers)

package/docs/solutions/INDEX.md

@@ -2,6 +2,7 @@
 <!-- 每条一行，按 severity 降序，≤150 行硬上限 -->
 | date | phase | domain | type | severity | summary | file |
 |------|-------|--------|------|----------|---------|------|
+| 2026-08-04 | cross-phase | general | insight | medium | (no summary) | cross-phase/2026-08-04-no-summary.md |
 | 2026-08-03 | cross-phase | general | insight | medium | (no summary) | cross-phase/2026-08-03-no-summary.md |
 | 2026-08-01 | cross-phase | general | insight | medium | (no summary) | cross-phase/2026-08-01-no-summary.md |
 | 2026-07-31 | cross-phase | general | insight | medium | (no summary) | cross-phase/2026-07-31-no-summary.md |

package/docs/solutions/cross-phase/2026-08-04-no-summary.md

@@ -0,0 +1,17 @@
+---
+phase: cross-phase
+domain: general
+type: insight
+severity: medium
+date: 2026-08-04
+source: 
+---
+
+## 问题描述
+(no summary)
+
+## 根因/模式
+（待补充）
+
+## 预防措施/应用方式
+（待补充）

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "team-flow",
   "description": "Unified workflow plugin: team-flow (spec-driven dev) + compound-engineering core subset + architecture-design (4A/DDD) + prototype (local HTML). 24 skills, one install.",
-  "version": "0.33.0",
+  "version": "0.34.0",
   "contextFileName": "GEMINI.md"
 }

package/hooks/session-start

@@ -1,11 +1,11 @@
 #!/usr/bin/env bash
-# v0.33.0: auto-sync CLI version with plugin version
+# v0.34.0: auto-sync CLI version with plugin version
 set -e
 
 # ═══════════════════════════════════════════════════════════════
 # Plugin version (update this when releasing new versions)
 # ═══════════════════════════════════════════════════════════════
-PLUGIN_VERSION="0.33.0"
+PLUGIN_VERSION="0.34.0"
 
 # ═══════════════════════════════════════════════════════════════
 # Step 1: Auto-sync CLI version with plugin version

package/llms.txt

@@ -3,7 +3,7 @@
 ## Overview
 spec-superflow is a self-contained workflow integration plugin for Claude Code, Cursor, OpenAI Codex CLI/App, GitHub Copilot CLI, Gemini CLI, OpenCode, WorkBuddy, and Trae. It merges spec-driven planning artifacts (proposal, specs, design, tasks) with disciplined execution guardrails (TDD, review gates, controlled handoff) into one unified workflow.
 
-Current version: v0.33.0.
+Current version: v0.34.0.
 
 ## Key Documents
 - README.md: Chinese homepage with full usage guide and FAQ

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xulthekl/team-flow",
-  "version": "0.33.0",
+  "version": "0.34.0",
   "description": "Unified plugin (24 skills + 15 agents) integrating team-flow, compound-engineering, architecture-design, prototype, design-system, workflow-orchestrator, workflow-bootstrap, e2e, session-handoff, workflow-feedback for multi-agent coding tools.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "team-flow",
-  "version": "0.33.0",
+  "version": "0.34.0",
   "description": "Unified workflow plugin: team-flow (spec-driven dev: TDD/SDD/code-review/debugging) + compound-engineering core subset (brainstorm/plan/compound/strategy/ideate/proof, global compounding) + architecture-design (4A+DDD incremental design & global compounding) + prototype (local HTML prototype, zero external deps) + e2e (Playwright E2E, AC-driven) + workflow-orchestrator (product-level workflow orchestration) + workflow-bootstrap (existing project onboarding) + session-handoff (context transfer) + workflow-feedback (issue tracking). 24 skills + 15 agents, one install.",
   "author": {
     "name": "LT"

package/scripts/lib/conventions-generator.mjs

@@ -0,0 +1,350 @@
+#!/usr/bin/env node
+// scripts/lib/conventions-generator.mjs — conventions 生成器（v0.34.0 新增）
+//
+// 根据项目技术栈自动生成测试规范 conventions，符合 glaf4-test 要求。
+// 支持存量项目（自动识别）和全新项目（交互式引导）。
+//
+// 使用方式：
+//   node scripts/lib/conventions-generator.mjs --root <项目根目录> [--interactive]
+//
+// 设计来源：test-capability-enhancement-design v1.0 §四
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync } from 'node:fs';
+import path, { join } from 'node:path';
+import { parseArgs } from 'node:util';
+
+// ── 常量 ─────────────────────────────────────────────────────────────────────
+
+const TEMPLATE_DIR = join(import.meta.dirname, '../../templates/conventions');
+const GLAF4_TEMPLATE_DIR = join(TEMPLATE_DIR, 'glaf4-compliant');
+
+// 技术栈检测特征
+const TECH_STACK_SIGNATURES = {
+  java: ['pom.xml', 'build.gradle', 'build.gradle.kts'],
+  javascript: ['package.json', 'yarn.lock', 'pnpm-lock.yaml'],
+  python: ['requirements.txt', 'pyproject.toml', 'setup.py', 'Pipfile'],
+};
+
+// 测试框架检测特征
+const TEST_FRAMEWORK_SIGNATURES = {
+  'junit5-mockito': { file: 'pom.xml', content: /junit-jupiter|org\.junit\.jupiter/ },
+  jest: { file: 'package.json', content: /"jest"|"@jest\/|vitest/ },
+  pytest: { file: 'requirements.txt', content: /pytest/ },
+};
+
+// 应用框架检测特征
+const APP_FRAMEWORK_SIGNATURES = {
+  'spring-boot': { file: 'pom.xml', content: /spring-boot|org\.springframework\.boot/ },
+  express: { file: 'package.json', content: /"express"/ },
+  django: { file: 'requirements.txt', content: /django/ },
+};
+
+// ── 技术栈检测 ─────────────────────────────────────────────────────────────
+
+/**
+ * 检测项目技术栈
+ * @param {string} root 项目根目录
+ * @returns {{ language: string|null, buildTool: string|null, testFramework: string|null, appFramework: string|null }}
+ */
+export function detectTechStack(root) {
+  const result = {
+    language: null,
+    buildTool: null,
+    testFramework: null,
+    appFramework: null,
+  };
+
+  // 检测语言
+  for (const [lang, files] of Object.entries(TECH_STACK_SIGNATURES)) {
+    if (files.some(f => existsSync(join(root, f)))) {
+      result.language = lang;
+      break;
+    }
+  }
+
+  // 检测构建工具
+  if (existsSync(join(root, 'pom.xml'))) result.buildTool = 'maven';
+  else if (existsSync(join(root, 'build.gradle')) || existsSync(join(root, 'build.gradle.kts'))) result.buildTool = 'gradle';
+  else if (existsSync(join(root, 'package.json'))) result.buildTool = 'npm';
+  else if (existsSync(join(root, 'yarn.lock'))) result.buildTool = 'yarn';
+  else if (existsSync(join(root, 'pnpm-lock.yaml'))) result.buildTool = 'pnpm';
+  else if (existsSync(join(root, 'requirements.txt')) || existsSync(join(root, 'pyproject.toml'))) result.buildTool = 'pip';
+  else if (existsSync(join(root, 'Pipfile'))) result.buildTool = 'pipenv';
+
+  // 检测测试框架
+  for (const [fw, sig] of Object.entries(TEST_FRAMEWORK_SIGNATURES)) {
+    const filePath = join(root, sig.file);
+    if (existsSync(filePath)) {
+      const content = readFileSync(filePath, 'utf-8');
+      if (sig.content.test(content)) {
+        result.testFramework = fw;
+        break;
+      }
+    }
+  }
+
+  // 检测应用框架
+  for (const [fw, sig] of Object.entries(APP_FRAMEWORK_SIGNATURES)) {
+    const filePath = join(root, sig.file);
+    if (existsSync(filePath)) {
+      const content = readFileSync(filePath, 'utf-8');
+      if (sig.content.test(content)) {
+        result.appFramework = fw;
+        break;
+      }
+    }
+  }
+
+  return result;
+}
+
+// ── 模板选择 ─────────────────────────────────────────────────────────────
+
+/**
+ * 根据技术栈选择 conventions 模板
+ * @param {{ language: string|null, buildTool: string|null, testFramework: string|null, appFramework: string|null }} techStack
+ * @returns {string[]} 模板文件名列表
+ */
+export function selectTemplates(techStack) {
+  const templates = [];
+
+  if (techStack.language === 'java') {
+    // Java 项目：使用 glaf4-compliant 模板
+    if (existsSync(join(GLAF4_TEMPLATE_DIR, 'java-testing.md'))) {
+      templates.push('glaf4-compliant/java-testing.md');
+    }
+    if (techStack.appFramework === 'spring-boot') {
+      if (existsSync(join(GLAF4_TEMPLATE_DIR, 'spring-patterns.md'))) {
+        templates.push('glaf4-compliant/spring-patterns.md');
+      }
+    }
+  } else if (techStack.language === 'javascript') {
+    templates.push('js-testing.md');
+  } else if (techStack.language === 'python') {
+    templates.push('python-testing.md');
+  }
+
+  return templates;
+}
+
+// ── conventions 生成 ─────────────────────────────────────────────────────
+
+/**
+ * 生成 conventions 文件
+ * @param {string} root 项目根目录
+ * @param {{ language: string|null, buildTool: string|null, testFramework: string|null, appFramework: string|null }} techStack
+ * @param {string[]} templates 模板文件名列表
+ * @returns {{ created: string[], skipped: string[] }}
+ */
+export function generateConventions(root, techStack, templates) {
+  const conventionsDir = join(root, '.team-flow', 'conventions');
+  const versionsFile = join(conventionsDir, '.versions.json');
+
+  // 创建目录
+  mkdirSync(conventionsDir, { recursive: true });
+
+  // 读取现有版本信息
+  let versions = {};
+  if (existsSync(versionsFile)) {
+    try {
+      versions = JSON.parse(readFileSync(versionsFile, 'utf-8'));
+    } catch {
+      versions = {};
+    }
+  }
+  if (!versions.conventions) versions.conventions = {};
+
+  const created = [];
+  const skipped = [];
+
+  for (const template of templates) {
+    const templatePath = join(TEMPLATE_DIR, template);
+    const fileName = path.basename(template);
+    const targetPath = join(conventionsDir, fileName);
+
+    // 检查是否已存在且未自定义
+    if (existsSync(targetPath)) {
+      const existingVersion = versions.conventions[fileName];
+      if (existingVersion && !existingVersion.customized) {
+        // 读取模板版本
+        const templateContent = readFileSync(templatePath, 'utf-8');
+        const versionMatch = templateContent.match(/version:\s*(\d+\.\d+\.\d+)/);
+        const templateVersion = versionMatch ? versionMatch[1] : '1.0.0';
+
+        if (existingVersion.source_version === templateVersion) {
+          skipped.push(fileName);
+          continue;
+        }
+      }
+    }
+
+    // 复制模板
+    const templateContent = readFileSync(templatePath, 'utf-8');
+    writeFileSync(targetPath, templateContent, 'utf-8');
+
+    // 更新版本信息
+    const versionMatch = templateContent.match(/version:\s*(\d+\.\d+\.\d+)/);
+    const templateVersion = versionMatch ? versionMatch[1] : '1.0.0';
+
+    versions.conventions[fileName] = {
+      source_version: templateVersion,
+      installed_at: new Date().toISOString().split('T')[0],
+      customized: false,
+      last_checked: new Date().toISOString().split('T')[0],
+      source: template,
+    };
+
+    created.push(fileName);
+  }
+
+  // 写入版本信息
+  writeFileSync(versionsFile, JSON.stringify(versions, null, 2), 'utf-8');
+
+  return { created, skipped };
+}
+
+// ── 更新 team-flow.config.json ─────────────────────────────────────────
+
+/**
+ * 更新 team-flow.config.json 的 conventions 字段
+ * @param {string} root 项目根目录
+ * @param {string[]} conventionsFiles conventions 文件名列表
+ */
+export function updateConfig(root, conventionsFiles) {
+  const teamFlowDir = join(root, '.team-flow');
+  const configPath = join(teamFlowDir, 'team-flow.config.json');
+
+  // 确保目录存在
+  mkdirSync(teamFlowDir, { recursive: true });
+
+  let config = {};
+  if (existsSync(configPath)) {
+    try {
+      config = JSON.parse(readFileSync(configPath, 'utf-8'));
+    } catch {
+      config = {};
+    }
+  }
+
+  if (!config.conventions) config.conventions = {};
+
+  for (const file of conventionsFiles) {
+    const key = file.replace(/\.md$/, '').replace(/\//g, '-');
+    config.conventions[key] = `.team-flow/conventions/${file}`;
+  }
+
+  writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
+}
+
+// ── 交互式引导 ─────────────────────────────────────────────────────────────
+
+/**
+ * 交互式引导用户选择技术栈（全新项目）
+ * @returns {Promise<{ language: string, buildTool: string, testFramework: string, appFramework: string }>}
+ */
+export async function interactiveSetup() {
+  // 注意：在实际使用中，这里需要使用 readline 或 inquirer 等库
+  // 这里提供默认值，实际实现需要集成到 workflow-bootstrap 的交互流程中
+  console.log('\n=== 全新项目技术栈配置 ===\n');
+  console.log('由于当前为脚本模式，使用默认配置：');
+  console.log('  - 编程语言：Java');
+  console.log('  - 构建工具：Maven');
+  console.log('  - 测试框架：JUnit 5 + Mockito');
+  console.log('  - 应用框架：Spring Boot');
+  console.log('\n如需自定义配置，请在 workflow-bootstrap 中使用交互式模式。\n');
+
+  return {
+    language: 'java',
+    buildTool: 'maven',
+    testFramework: 'junit5-mockito',
+    appFramework: 'spring-boot',
+  };
+}
+
+// ── CLI ─────────────────────────────────────────────────────────────────────
+
+export async function run(args) {
+  const { positionals, values } = parseArgs({
+    args,
+    options: {
+      root: { type: 'string', default: '.' },
+      interactive: { type: 'boolean', default: false },
+      json: { type: 'boolean', default: false },
+    },
+    allowPositionals: true,
+  });
+
+  const root = path.resolve(values.root);
+
+  // 检查项目根目录
+  if (!existsSync(root)) {
+    console.error(`项目根目录不存在: ${root}`);
+    process.exit(1);
+  }
+
+  // 检查 conventions 是否已存在
+  const conventionsDir = join(root, '.team-flow', 'conventions');
+  if (existsSync(conventionsDir) && readdirSync(conventionsDir).length > 0) {
+    console.log('⚠️  conventions 已存在，跳过生成');
+    console.log(`   路径: ${conventionsDir}`);
+    process.exit(0);
+  }
+
+  // 检测技术栈
+  let techStack = detectTechStack(root);
+
+  // 如果未检测到技术栈且启用交互式模式
+  if (!techStack.language && values.interactive) {
+    techStack = await interactiveSetup();
+  }
+
+  // 如果仍未检测到技术栈
+  if (!techStack.language) {
+    console.error('❌ 未检测到技术栈特征');
+    console.error('   请指定项目根目录，或使用 --interactive 模式手动配置');
+    process.exit(1);
+  }
+
+  // 选择模板
+  const templates = selectTemplates(techStack);
+
+  if (templates.length === 0) {
+    console.error('❌ 未找到匹配的 conventions 模板');
+    console.error(`   技术栈: ${JSON.stringify(techStack)}`);
+    process.exit(1);
+  }
+
+  // 生成 conventions
+  const result = generateConventions(root, techStack, templates);
+
+  // 更新配置
+  updateConfig(root, result.created);
+
+  // 输出结果
+  if (values.json) {
+    console.log(JSON.stringify({
+      ok: true,
+      techStack,
+      templates,
+      created: result.created,
+      skipped: result.skipped,
+      conventionsDir,
+    }));
+  } else {
+    console.log('✅ conventions 生成完成');
+    console.log(`   技术栈: ${techStack.language} + ${techStack.testFramework}`);
+    console.log(`   创建: ${result.created.join(', ')}`);
+    if (result.skipped.length > 0) {
+      console.log(`   跳过: ${result.skipped.join(', ')}`);
+    }
+    console.log(`   路径: ${conventionsDir}`);
+  }
+}
+
+// 直接运行
+if (import.meta.url === `file://${process.argv[1]}`) {
+  run(process.argv.slice(2)).catch(err => {
+    console.error(err);
+    process.exit(1);
+  });
+}