@xulthekl/team-flow 0.22.4

package/scripts/team-flow.mjs

@@ -0,0 +1,164 @@
+#!/usr/bin/env node
+// team-flow CLI — zero-dependency CLI for spec management
+// Usage: tf <command> [options]
+
+import { parseArgs } from 'node:util';
+
+const COMMANDS = {
+  list:           () => import('./lib/cmd-list.mjs'),
+  validate:       () => import('./lib/cmd-validate.mjs'),
+  doctor:         () => import('./lib/cmd-doctor.mjs'),
+  version:        () => import('./lib/cmd-version.mjs'),
+  sync:           () => import('./lib/cmd-sync.mjs'),
+  config:         () => import('./lib/cmd-config.mjs'),
+  state:          () => import('./lib/cmd-state.mjs'),
+  inject:         () => import('./lib/cmd-inject.mjs'),
+  audit:          () => import('./lib/cmd-audit.mjs'),
+  checkpoint:     () => import('./lib/cmd-checkpoint.mjs'),
+  handoff:        () => import('./lib/cmd-handoff.mjs'),
+  isolate:        () => import('./lib/cmd-isolate.mjs'),
+  execution:      () => import('./lib/cmd-execution.mjs'),
+  runtime:        () => import('./lib/cmd-runtime.mjs'),
+  solutions:      () => import('./lib/cmd-solutions.mjs'),
+  'install-cursor': () => import('./lib/cmd-install-cursor.mjs'),
+  'install-workbuddy': () => import('./lib/cmd-install-workbuddy.mjs'),
+  'install-cline':    () => import('./lib/cmd-install-cline.mjs'),
+  'install-kiro':     () => import('./lib/cmd-install-kiro.mjs'),
+  'install-windsurf': () => import('./lib/cmd-install-windsurf.mjs'),
+  'install-qwen':     () => import('./lib/cmd-install-qwen.mjs'),
+  'install-amazon-q': () => import('./lib/cmd-install-amazon-q.mjs'),
+  'install-roocode':  () => import('./lib/cmd-install-roocode.mjs'),
+  'install-continue': () => import('./lib/cmd-install-continue.mjs'),
+  'install-pi':       () => import('./lib/cmd-install-pi.mjs'),
+  'install-qoder':    () => import('./lib/cmd-install-qoder.mjs'),
+  'install-zcode':     () => import('./lib/cmd-install-zcode.mjs'),
+  'prototype-sync':    () => import('./lib/prototype-sync.mjs'),
+};
+
+const HELP = `team-flow (tf) — Unified workflow plugin CLI
+
+Usage: tf <command> [options]
+
+Commands:
+  list                  List all changes and their status
+  validate <dir>        Validate artifacts in a change directory
+  doctor                Health check (versions, hooks, skills, docs)
+  version <semver>      Sync version to all manifest files
+  sync <change-dir>     Merge delta specs into main specs
+  prototype-sync <change-dir> [--source <path>] [--prototype-dir <path>]
+                        Merge UX delta into global prototype/ + design-system.md
+  config [options]      Display or modify configuration
+  config --resolve-model <profile>  Resolve a configured model profile without switching models
+  state <sub> <dir>     Manage .team-flow.yaml state (init|check|transition|get|rebuild)
+  inject <dir>          Generate phase-guard artifacts; use --platforms <name|all> when platform is ambiguous
+  audit <dir>           Generate decision-point-audit.md from .team-flow.yaml
+  checkpoint save <change-dir> --task <id> --next <text>
+                        Save a task-level recovery checkpoint
+  checkpoint list <change-dir>
+                        List checkpoints and stale status
+  checkpoint show <change-dir> <id>
+                        Show one recovery checkpoint
+  handoff create <change-dir> --type <type> --objective <text> --expected-output <text> --acceptance <text>
+                        Create an explicit prototype/research/experiment handoff
+  handoff list <change-dir>
+                        List active and completed handoffs
+  handoff finish <change-dir> <id>
+                        Validate a handoff result
+  handoff resolve <change-dir> <id> --decision <accept|reject|defer>
+                        Record the explicit handoff decision
+  execution recommend <change-dir> [--wave <id>:<strategy>:<task,...>]
+                        List execution modes and an evidence-based recommendation
+  execution plan <change-dir> --mode <mode> --confirm --reason <text> --wave <id>:<strategy>:<task,...> [--acknowledge-recommendation]
+                        Record a user-confirmed guarded execution plan
+  execution show <change-dir> [--json]
+                        Show and validate the current execution plan
+  execution revise <change-dir> --mode sdd --confirm --reason <text> --wave <id>:<strategy>:<task,...> [--acknowledge-recommendation]
+                        Upgrade inline/batch to SDD, or replan existing SDD waves, as a new revision
+  execution review <change-dir> --wave <id> --base <sha> --head <sha> --report <path> --verdict pass|fail
+                        Record one review receipt for a planned wave
+  runtime check-update  Run a portable update check for canonical skills
+  runtime infer <dir>   Infer workflow mode without a plugin-root path
+  runtime guard ...     Run a portable phase-transition guard
+  runtime config ...    Read effective configuration (writes are rejected)
+  runtime asset read <path>
+                        Read one allowlisted package asset for a skill
+  solutions index-gen [--dir <solutions-dir>]
+                        Rebuild docs/solutions/INDEX.md (v0.5 compound-learning)
+  solutions inject --phase <p> [--domain <d>] [--dir <solutions-dir>]
+                        Emit top-5 filtered solution summaries for skill context injection
+  solutions capture --phase <p> --domain <d> --type <t> --severity <s> --summary "<text>" [--source <src>] [--dir <solutions-dir>]
+                        Capture one learning into docs/solutions/ + INDEX.md
+  solutions promote <change-dir> [--dir <solutions-dir>]
+                        Promote qualifying change learnings into global docs/solutions/
+  install-cursor        Deploy skills/scripts/docs to .cursor/ (local Cursor setup)
+  install-workbuddy     Deploy skills to WorkBuddy marketplace and enable them
+  install-cline         Deploy to .cline/ + .clinerules/ (Cline)
+  install-kiro          Deploy to .kiro/ + .kiro/steering/ (Kiro)
+  install-windsurf      Deploy to .windsurf/ + .windsurf/rules/ (Windsurf)
+  install-qwen          Deploy to .qwen/ + .qwen/rules/ (Qwen Code)
+  install-amazon-q      Deploy to .amazonq/ + .amazonq/rules/ (Amazon Q Developer)
+  install-roocode       Deploy to .roo/ + .roo/rules/ (Roo Code)
+  install-continue      Deploy to .continue/ + .continue/rules/ (Continue)
+  install-pi            Deploy to .pi/skills/ (Pi agent; no rules dir)
+  install-qoder         Deploy to .qoder/ + .qoder/rules/ (Qoder)
+
+Options:
+  --help, -h            Show this help message
+  --version, -v         Show CLI version
+
+Examples:
+  tf list
+  tf validate changes/v0.4.0-platform-evolution/
+  tf doctor
+  tf version 0.4.0
+  tf sync changes/v0.3.0-workflow-enhancements/
+  tf config --get execution.inlineThreshold
+  tf config --resolve-model mechanical
+  tf config --set verification.language=zh
+  tf state init changes/my-change/
+  tf state check changes/my-change/
+  tf state transition changes/my-change/ approved-for-build
+  tf state get changes/my-change/ batches_completed
+  tf checkpoint save changes/my-change/ --task 1.1 --next "Run focused tests"
+  tf checkpoint list changes/my-change/
+  tf handoff create changes/my-change/ --type research --objective "Compare approaches" --expected-output "Recommendation" --acceptance "Evidence recorded"
+  tf install-cursor
+  tf install-workbuddy
+  tf install-cline --local /path/to/team-flow
+`;
+
+async function main() {
+  const args = process.argv.slice(2);
+
+  if (args.length === 0 || args.includes('--help') || args.includes('-h')) {
+    console.log(HELP);
+    process.exit(0);
+  }
+
+  if (args.includes('--version') || args.includes('-v')) {
+    const pkg = JSON.parse(
+      (await import('node:fs')).readFileSync(
+        new URL('../package.json', import.meta.url), 'utf-8'
+      )
+    );
+    console.log(pkg.version);
+    process.exit(0);
+  }
+
+  const command = args[0];
+  const commandArgs = args.slice(1);
+
+  if (!COMMANDS[command]) {
+    console.error(`Unknown command: ${command}`);
+    console.error(`Run "tf --help" for available commands.`);
+    process.exit(2);
+  }
+
+  const mod = await COMMANDS[command]();
+  await mod.run(commandArgs);
+}
+
+main().catch(err => {
+  console.error(`Error: ${err.message}`);
+  process.exit(1);
+});

package/scripts/token-baseline.mjs

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+// token-baseline.mjs — Token measurement baseline tool
+// Measures lines, characters, and estimated tokens for injection components.
+
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+const REPO_ROOT = resolve(import.meta.dirname, '..');
+
+const TARGETS = [
+  { path: 'hooks/session-start', label: 'hooks/session-start' },
+  { path: '.claude/always/phase-guard.md', label: 'phase-guard (claude)' },
+  { path: 'GEMINI.md', label: 'phase-guard (gemini)' },
+  { path: 'skills/workflow-start/SKILL.md', label: 'skill: workflow-start' },
+  { path: 'skills/need-explorer/SKILL.md', label: 'skill: need-explorer' },
+  { path: 'skills/spec-writer/SKILL.md', label: 'skill: spec-writer' },
+  { path: 'skills/contract-builder/SKILL.md', label: 'skill: contract-builder' },
+  { path: 'skills/build-executor/SKILL.md', label: 'skill: build-executor' },
+  { path: 'skills/bug-investigator/SKILL.md', label: 'skill: bug-investigator' },
+  { path: 'skills/code-reviewer/SKILL.md', label: 'skill: code-reviewer' },
+  { path: 'skills/release-archivist/SKILL.md', label: 'skill: release-archivist' },
+  { path: 'skills/spec-merger/SKILL.md', label: 'skill: spec-merger' },
+];
+
+/**
+ * Count Chinese characters in a string.
+ */
+function countChineseChars(text) {
+  return (text.match(/[一-鿿㐀-䶿]/g) || []).length;
+}
+
+/**
+ * Estimate tokens from text.
+ * English: ~4 chars per token, Chinese: ~1.5 chars per token.
+ */
+function estimateTokens(text) {
+  const chinese = countChineseChars(text);
+  const other = text.length - chinese;
+  return Math.ceil(chinese / 1.5) + Math.ceil(other / 4);
+}
+
+/**
+ * Measure a single file.
+ * @returns {{ path: string, label: string, lines: number, chars: number, estimatedTokens: number, error?: string }}
+ */
+function measureFile(target) {
+  const fullPath = resolve(REPO_ROOT, target.path);
+  if (!existsSync(fullPath)) {
+    return { path: target.path, label: target.label, lines: 0, chars: 0, estimatedTokens: 0, error: 'file not found' };
+  }
+  try {
+    const content = readFileSync(fullPath, 'utf-8');
+    const lines = content.split('\n').length;
+    const chars = content.length;
+    return {
+      path: target.path,
+      label: target.label,
+      lines,
+      chars,
+      estimatedTokens: estimateTokens(content),
+    };
+  } catch (e) {
+    return { path: target.path, label: target.label, lines: 0, chars: 0, estimatedTokens: 0, error: e.message };
+  }
+}
+
+/**
+ * Measure all targets.
+ * @param {{ files?: string }} options
+ * @returns {{ timestamp: string, version: string, components: Array, totals: { lines: number, chars: number, estimatedTokens: number } }}
+ */
+export function measureAll(options = {}) {
+  const targets = options.files
+    ? TARGETS.filter(t => options.files.split(',').some(f => t.path.includes(f.trim())))
+    : TARGETS;
+
+  const components = targets.map(measureFile);
+  const totals = components.reduce(
+    (acc, c) => ({
+      lines: acc.lines + c.lines,
+      chars: acc.chars + c.chars,
+      estimatedTokens: acc.estimatedTokens + c.estimatedTokens,
+    }),
+    { lines: 0, chars: 0, estimatedTokens: 0 }
+  );
+
+  return {
+    timestamp: new Date().toISOString(),
+    components,
+    totals,
+  };
+}
+
+/**
+ * Compare current measurements against a baseline file.
+ * @param {string} baselinePath
+ * @returns {{ current: object, baseline: object, changes: Array }}
+ */
+export function compareWithBaseline(baselinePath) {
+  const current = measureAll();
+  const baselineJson = JSON.parse(readFileSync(baselinePath, 'utf-8'));
+  const baselineMap = new Map(baselineJson.components.map(c => [c.path, c]));
+
+  const changes = current.components.map(c => {
+    const b = baselineMap.get(c.path);
+    if (!b) return { ...c, change: 'new', deltaTokens: c.estimatedTokens };
+    const deltaTokens = c.estimatedTokens - b.estimatedTokens;
+    const pct = b.estimatedTokens > 0 ? ((deltaTokens / b.estimatedTokens) * 100).toFixed(1) : 'N/A';
+    return { ...c, change: deltaTokens < 0 ? 'decreased' : deltaTokens > 0 ? 'increased' : 'unchanged', deltaTokens, pct };
+  });
+
+  const totalDelta = current.totals.estimatedTokens - baselineJson.totals.estimatedTokens;
+  const totalPct = baselineJson.totals.estimatedTokens > 0
+    ? ((totalDelta / baselineJson.totals.estimatedTokens) * 100).toFixed(1)
+    : 'N/A';
+
+  return {
+    current,
+    baseline: baselineJson,
+    changes,
+    summary: {
+      totalDelta,
+      totalPct,
+      previousTotal: baselineJson.totals.estimatedTokens,
+      currentTotal: current.totals.estimatedTokens,
+    },
+  };
+}
+
+// CLI
+function parseArgs(argv) {
+  const args = { compare: null, output: null, files: null };
+  for (let i = 2; i < argv.length; i++) {
+    if (argv[i] === '--compare' && argv[i + 1]) args.compare = argv[++i];
+    else if (argv[i] === '--output' && argv[i + 1]) args.output = argv[++i];
+    else if (argv[i] === '--files' && argv[i + 1]) args.files = argv[++i];
+  }
+  return args;
+}
+
+if (process.argv[1] === decodeURIComponent(new URL(import.meta.url).pathname) || process.argv[1] === import.meta.filename) {
+  const args = parseArgs(process.argv);
+  let result;
+
+  if (args.compare) {
+    result = compareWithBaseline(args.compare);
+  } else {
+    result = measureAll({ files: args.files });
+  }
+
+  const output = JSON.stringify(result, null, 2);
+  if (args.output) {
+    writeFileSync(args.output, output, 'utf-8');
+    console.log(`Baseline saved to ${args.output}`);
+  } else {
+    console.log(output);
+  }
+}

package/scripts/validate-artifacts

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+// validate-artifacts - Validate team-flow artifacts
+// Usage: node scripts/validate-artifacts <change-dir>
+//
+// Reads a change directory and validates all artifacts found:
+//   - proposal.md (change content validation)
+//   - specs/*/spec.md (delta spec validation)
+
+import { readFileSync, existsSync, statSync } from 'fs';
+import { join, basename } from 'path';
+import { Validator } from '../dist/index.js';
+import { validateSpecPathLayout, relativeSpecPath } from './lib/spec-paths.mjs';
+
+function printReport(label, report) {
+  console.log(`\n  📋 ${label}`);
+  if (report.valid) {
+    console.log(`     ✅ valid (${report.summary.errors} errors, ${report.summary.warnings} warnings, ${report.summary.info} info)`);
+  } else {
+    console.log(`     ❌ invalid (${report.summary.errors} errors, ${report.summary.warnings} warnings, ${report.summary.info} info)`);
+  }
+  for (const issue of report.issues) {
+    const icon = issue.level === 'ERROR' ? '🔴' : issue.level === 'WARNING' ? '🟡' : '🔵';
+    const lineInfo = issue.line ? `:${issue.line}` : '';
+    console.log(`     ${icon} [${issue.level}] ${issue.path}${lineInfo}: ${issue.message}`);
+  }
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  if (args.length < 1) {
+    console.error('Usage: node scripts/validate-artifacts <change-dir>');
+    process.exit(2);
+  }
+
+  const changeDir = args[0];
+  if (!existsSync(changeDir) || !statSync(changeDir).isDirectory()) {
+    console.error(`Error: "${changeDir}" is not a valid directory`);
+    process.exit(2);
+  }
+
+  const changeName = basename(changeDir);
+  const validator = new Validator(false);
+
+  console.log(`🔍 Validating artifacts in: ${changeDir}`);
+  console.log(`   Change: ${changeName}`);
+
+  let hasErrors = false;
+
+  const proposalPath = join(changeDir, 'proposal.md');
+  if (existsSync(proposalPath)) {
+    try {
+      const content = readFileSync(proposalPath, 'utf-8');
+      const report = validator.validateChangeContent(changeName, content);
+      printReport('proposal.md (change content)', report);
+      if (!report.valid) hasErrors = true;
+    } catch (e) {
+      console.log(`\n  📋 proposal.md`);
+      console.log(`     ❌ Error reading file: ${e instanceof Error ? e.message : 'Unknown error'}`);
+      hasErrors = true;
+    }
+  } else {
+    console.log(`\n  ⚠️  proposal.md not found`);
+  }
+
+  const specLayout = validateSpecPathLayout(changeDir, { requireSpecs: true });
+  for (const failure of specLayout.failures) {
+    console.log(`\n  ❌ ${failure}`);
+    hasErrors = true;
+  }
+
+  for (const specFile of specLayout.specFiles) {
+    try {
+      const content = readFileSync(specFile, 'utf-8');
+      const report = validator.validateDeltaSpec(content);
+      const relative = relativeSpecPath(changeDir, specFile);
+      printReport(`${relative} (delta spec)`, report);
+      if (!report.valid) hasErrors = true;
+    } catch (e) {
+      const relative = relativeSpecPath(changeDir, specFile);
+      console.log(`\n  📋 ${relative}`);
+      console.log(`     ❌ Error reading file: ${e instanceof Error ? e.message : 'Unknown error'}`);
+      hasErrors = true;
+    }
+  }
+
+  console.log('');
+  if (hasErrors) {
+    console.log('❌ Validation failed with errors.');
+    process.exit(1);
+  } else {
+    console.log('✅ All artifacts validated successfully.');
+    process.exit(0);
+  }
+}
+
+main();

package/scripts/verify-marketplace-release.mjs

@@ -0,0 +1,59 @@
+import { fileURLToPath } from 'node:url';
+
+const SEMVER = /^\d+\.\d+\.\d+$/;
+
+export function parseReleaseCheckArgs(args) {
+  if (args.length !== 4 || args[0] !== '--manifest-url' || args[2] !== '--expected-version') {
+    throw new Error('Usage: verify-marketplace-release --manifest-url <https-url> --expected-version <x.y.z>');
+  }
+  const parsedUrl = new URL(args[1]);
+  if (parsedUrl.protocol !== 'https:') throw new Error('manifest URL must use HTTPS');
+  if (!SEMVER.test(args[3])) throw new Error('expected version must use x.y.z semver');
+  return { manifestUrl: parsedUrl.href, expectedVersion: args[3] };
+}
+
+export async function verifyMarketplaceRelease({
+  manifestUrl,
+  expectedVersion,
+  fetchImpl = globalThis.fetch,
+}) {
+  let response;
+  try {
+    response = await fetchImpl(manifestUrl);
+  } catch (error) {
+    throw new Error('marketplace network request failed: ' + error.message);
+  }
+  if (!response.ok) throw new Error('marketplace manifest request failed: HTTP ' + response.status);
+  let manifest;
+  try {
+    manifest = await response.json();
+  } catch (error) {
+    throw new Error('marketplace manifest is not valid JSON: ' + error.message);
+  }
+  if (typeof manifest.version !== 'string') throw new Error('marketplace manifest is missing a string version');
+  if (manifest.version !== expectedVersion) {
+    throw new Error('marketplace version mismatch: expected ' + expectedVersion + ', found ' + manifest.version);
+  }
+  return { manifestUrl, expectedVersion, actualVersion: manifest.version };
+}
+
+export async function main(
+  args,
+  { fetchImpl = globalThis.fetch, stdout = process.stdout, stderr = process.stderr } = {},
+) {
+  try {
+    const { manifestUrl, expectedVersion } = parseReleaseCheckArgs(args);
+    const result = await verifyMarketplaceRelease({ manifestUrl, expectedVersion, fetchImpl });
+    stdout.write(`Marketplace manifest verified: ${result.actualVersion} (${result.manifestUrl})\n`);
+    return 0;
+  } catch (error) {
+    stderr.write(`Error: ${error.message}\n`);
+    return 1;
+  }
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  main(process.argv.slice(2)).then((exitCode) => {
+    process.exitCode = exitCode;
+  });
+}

package/skills/architecture-design/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: architecture-design
+description: 基于 4A 企业架构 + DDD 领域驱动设计的架构/API/DB 设计 skill。当用户需要做架构设计、识别聚合与限界上下文、划分写/读模型(CQRS)、设计 API 指令映射，或在 team-flow / compound-engineering 工作流中做每变更架构增量设计与全局复利回写时使用。在 workflow-start 编排中作为子代理调用，承担判断+执行一体化职责（五项检查判定是否涉及架构变更，涉及则执行完整增量设计，不涉及则返回 skip）。不适用于：纯业务逻辑编码、与架构无关的需求分析、非 DDD 语境的数据库建模。
+---
+
+# Architecture Design (4A + DDD)
+
+把企业架构(4A)与领域驱动设计(DDD)的 crystallized 方法，转化为每变更可执行的架构/API/DB 设计动作，并与 team-flow(开发过程) + compound-engineering(全局复利) 衔接。
+
+## Core Frameworks
+
+### F1 · 4A 分叉依赖
+`BA → (IA ∥ AA) → TA`。BA 先行且未稳前不并行；IA 与 AA 同步并行、双向对齐；二者共同汇聚 TA。定义不可逆（先选技术再补流程是反模式）。
+
+### F2 · 跨域一致性（双对齐，质量门禁）
+每个 AA 功能 ≥1 个 IA 数据实体支撑；每个 IA 实体 ≥1 个 AA 功能消费（多对多，无孤立节点）。检查两类缺一不可：结构一致（"有没有"）+ 语义一致（"对不对"，命名统一，用户/客户/consumer 不能并存）。
+
+### F3 · 变更分叉级联（三层次必覆盖）
+直接依赖（BA→AA/IA 同变）→ 间接依赖（AA/IA→TA、IA↔AA 对齐调整）→ 隐式依赖（表面无关却牵动，最危险）。无架构管理=上线才暴露(10×成本)。
+
+### F4 · DDD 聚合四要素
+实体(唯一标识)+值对象(无标识)+聚合根(唯一入口)+事务边界(聚合内一事务)。聚合仅存于业务服务；数据服务/技术服务无聚合。
+
+### F5 · 限界上下文(Context Map)
+语义边界=L3 应用服务；同术语异义须显式映射(Shared Kernel / Anti-Corruption Layer / Open Host Service)。
+
+### F6 · CQRS 写读模型
+事务型对象→写模型(聚合，Command/Read 操作)；分析型对象→读模型(查询模型，Query 派生，无事务)。Command/Read→写模型；Query 经阻断测试分流。
+
+### F7 · 三维判定（验证工具）
+失忆测试(清空业务记忆还能工作?→TA) → 阻断测试(阻断1h下游能继续?不能→业务服务/能→数据服务) → 孤岛测试(谁调用? 私有/领域共通/企业共通)。
+
+### F8 · 增量设计 + 复利回写闭环（工作流衔接）
+每变更：As-Is 冻结复制+版本锚点(change_id+章节+commit)→ To-Be(DDD)+ 全局 ARCHITECTURE.md 锚点。复利回写：one change per run，append 当前态+演进日志，Discoverability 在 AGENTS.md 暴露 docs/architecture/，下游检索复用。API 仅每变更内设计；技术架构(IA/AA/TA)与产品策略(BA/STRATEGY.md)分离对齐。
+
+## Chapter Index
+- ch01-4a-domains — 4A 四域定义与分叉依赖
+- ch02-change-cascade — 变更级联与跨域一致性门禁
+- ch03-architecture-outputs — 架构产出三层 + 治理三支柱
+- ch04-entity-to-aggregate — 业务实体→聚合→限界上下文
+- ch05-cqrs — 写/读模型、指令分流、三维判定
+- ch06-integration — 与 team-flow / compound-engineering 的集成
+
+## Topic Index
+- 4A / BA / IA / AA / TA → ch01
+- 分叉依赖 / 跨域一致性 → ch01, ch02
+- 变更级联(直接/间接/隐式) → ch02
+- 架构产出三层(元素/制品/交付件) → ch03
+- 治理三支柱 → ch03
+- 业务实体 / 活动对象矩阵 → ch04
+- 聚合 / 聚合根 / 值对象 / 事务边界 → ch04
+- 限界上下文 / Context Map → ch04
+- 写模型 / 读模型 / CQRS → ch05
+- Command / Read / Query → ch05
+- 阻断测试 / 三维判定 → ch05
+- 增量设计 / As-Is 冻结 / 复利回写 / 全局锚点 → ch06
+
+## Workflow Integration: 判断+执行一体化（v0.9 §26）
+
+本 skill 在 workflow-start 编排下作为子代理调用，承担**判断+执行一体化**职责。
+
+### 调用入口
+
+由 workflow-start 在 `exploring` 完成后、`specifying` 之前调用。
+
+### 输入
+
+- `change-brief.md`（scope / AC / 技术方向）
+- `prd/vN/plan.md` 高阶技术设计段（模块边界/技术选型/数据流/关键聚合划分）
+- 现有 `specs/`（若有）
+- 全局 `docs/architecture/`（As-Is 基线）
+
+### 五项检查（架构变更判定）
+
+依次检查以下五项，**全部为否** → `decision: skipped`；**任一为是** → `decision: required`：
+
+1. **聚合变更**：是否新增/修改聚合（aggregate）或聚合根
+2. **限界上下文变更**：是否涉及限界上下文（bounded context）边界变化或新增上下文映射关系
+3. **读写模型变更**：是否涉及 CQRS 写模型或读模型变化
+4. **API 变更**：是否涉及 API 新增/变更（端点、方法签名、请求响应 schema）
+5. **DB schema 变更**：是否涉及数据库表结构、字段、索引变更
+
+### 执行流程
+
+```
+1. 读取输入（brief + plan + specs + 全局 ARCHITECTURE.md）
+2. 执行五项检查
+3. 全部为否：
+   → decision: skipped
+   → reason: 简述不涉及架构变更的理由
+   → 返回结构化输出
+4. 任一为是：
+   → decision: required
+   → reason: 简述涉及的架构变更项
+   → 执行完整 4A+DDD 增量设计（F1-F8）
+   → 产出 architecture/architecture.md + database.md + api.md
+   → artifacts: 产出路径列表
+   → 返回结构化输出
+```
+
+### 结构化输出契约
+
+返回给 workflow-start 的结果**必须**包含以下字段：
+
+```yaml
+decision: required | skipped
+reason: "..."                    # skipped 时：不涉及架构变更的理由
+                                 # required 时：涉及的变更项摘要
+artifacts:                       # required 时必填，skipped 时为空
+  - architecture/architecture.md
+  - architecture/database.md
+  - architecture/api.md
+```
+
+### 产出目录
+
+架构设计产出放在 change 目录下的独立 `architecture/` 子目录：
+
+```
+changes/<name>/
+└── architecture/                # ★ 架构设计独立一等产物
+    ├── architecture.md          # DDD 增量（聚合/限界上下文/CQRS/Context Map）
+    ├── database.md              # DB 增量（实体/读写模型/schema 变更）
+    └── api.md                   # API 增量（Command/Read/Query 分流 + 端点设计）
+```
+
+**语义分离**：架构设计与行为规格（`specs/`）是不同专业领域，独立目录避免混杂。
+
+**下游消费**：
+- `architecture/architecture.md` → spec-writer：design.md Decisions 约束
+- `architecture/database.md` → spec-writer：design.md + tasks.md 数据层约束
+- `architecture/api.md` → spec-writer：tasks.md 接口定义约束
+- 全部 → release-archivist → arch-merge → 全局 `docs/architecture/` 回写
+
+### 独立调用
+
+除 workflow-start 编排调用外，本 skill 仍支持用户显式独立调用（`/team-flow:architecture-design`），此时不走五项检查判定门，直接执行完整 4A+DDD 设计。
+
+## Scope & Limits
+本 skill 覆盖 4A+DDD 架构设计方法及其与 team-flow/compound-engineering 的衔接。落地实现结合项目具体工具；超出本范围见相关 skill 或直接问 agent。

package/skills/architecture-design/chapters/ch01-4a-domains.md

@@ -0,0 +1,27 @@
+# ch01 · 4A 四域定义与分叉依赖
+
+## 四域定义（每域回答一个问题）
+| 域 | 问题 | 核心资产 | 主责角色 |
+|---|---|---|---|
+| BA 业务架构 | 做什么业务？ | 流程/价值流/能力 | 业务分析师 |
+| IA 信息架构 | 管什么数据？ | 数据实体/指标体系 | 数据架构师 |
+| AA 应用架构 | 用什么功能？ | 功能/服务/领域模型 | 应用架构师 |
+| TA 技术架构 | 用什么技术？ | 选型/标准/基础设施 | 技术架构师 |
+
+> 精确性：仅 **TA** 是技术架构。IA（数据）、AA（功能）常被误统称"技术架构"——这是术语硬伤，会误导建模（如把数据实体当技术选型）。
+
+## 分叉依赖（核心框架 F1）
+结构本质不是线性串行，而是**分叉的多米诺骨牌**：
+1. **BA 先行**，是起点与前提；
+2. BA 稳定后 **IA 与 AA 同步并行**开展，且双向输入、随时对齐（如 AA 按客户等级筛，IA 就加对应字段）；
+3. IA 与 AA 输出**共同汇聚 TA**，TA 最后落地。
+
+公式：`BA → (IA ∥ AA) → TA`
+
+**约束**
+- 分叉是有条件的：先稳 BA，再并行 IA/AA；BA 未稳时并行是白费力气。
+- 顺序可迭代，但**定义不能反**（反模式：先买大数据平台再补流程 → 平台闲置）。
+
+## 应用提示
+- 设计架构前先确认 BA 是否已稳；不稳则先把 BA 落到 STRATEGY.md/PRD，再动 IA/AA/TA。
+- 把"技术锚点(ARCHITECTURE.md)"与"产品策略(STRATEGY.md)"分离——前者管 IA/AA/TA，后者管 BA；二者对齐而非混写（见 ch06）。

package/skills/architecture-design/chapters/ch02-change-cascade.md

@@ -0,0 +1,27 @@
+# ch02 · 变更级联与跨域一致性门禁
+
+## 变更分叉级联（核心框架 F3）
+每一层输出是下一层输入；分叉下 BA 一变，IA 与 AA 同时倒、互拉，再汇聚 TA。
+案例标尺：加"拼车"功能 → BA 改 3、AA 改 5、IA 改 5、TA 改 4，共 17 项。
+
+**三层次影响必须全覆盖：**
+| 层 | 名称 | 说明 | 风险 |
+|---|---|---|---|
+| 1 | 直接依赖 | BA 变→AA/IA 同时直接变 | 可见，不易漏 |
+| 2 | 间接依赖 | AA/IA 变→TA 变；IA↔AA 对齐调整 | 链条长，易忽略 |
+| 3 | 隐式依赖 | 表面无关却牵动（如报表 SQL 仍按老表结构） | 最危险，特征"看不出关联" |
+
+> 无架构管理=被动发现（测试/上线才暴露，成本 10×）；有架构管理=系统提示受影响域，事前规划。
+
+## 跨域一致性（核心框架 F2，质量门禁）
+**硬规则**：AA 定义的功能，IA 必须有对应数据实体支撑；反之 IA 定义的数据实体，AA 必须有功能使用。无数据的功能是空壳，无功能的数据是死数据。
+
+**两类检查缺一不可：**
+1. **结构一致（"有没有"）**：每个 AA 功能至少 1 个 IA 数据实体；可拉清单自动查孤儿。
+2. **语义一致（"对不对"）**：命名与术语统一（前端"用户"、后端"客户"、库里"consumer" 并存=反模式）；靠命名规范+术语表保障。
+
+**易错点**：一致性非一一对应，而是**多对多**——每功能≥1 实体、每实体≥1 功能，两端无孤立节点。这是架构发布的质量门禁，过不了不能发布。
+
+## 应用提示
+- 每变更做影响分析时，用三层次清单逐项打勾，重点补"隐式依赖"。
+- 回写全局架构文档时，"架构一致性/漂移检查"须覆盖结构+语义双对齐（见 ch06 的 Discoverability 正名）。