@xulthekl/team-flow 0.26.1 → 0.27.1

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

@@ -1,3 +1,3 @@
-# team-flow v0.26.1 | 阶段: {{state}} | 工作流: {{workflow}}
+# team-flow v0.27.1 | 阶段: {{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. 23 skills + 8 agents with embedded TDD, SDD, code review, debugging, delta spec sync, and design-system-driven prototyping.",
-      "version": "0.26.1",
+      "version": "0.27.1",
       "source": "./",
       "author": {
         "name": "LT",

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "team-flow",
-  "version": "0.26.1",
+  "version": "0.27.1",
   "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). 23 skills + 8 agents, one install.",
   "source": "./",
   "author": {

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "team-flow",
-  "version": "0.26.1",
+  "version": "0.27.1",
   "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.26.1"
+    "version": "0.27.1"
   },
   "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). 23 skills + 8 agents, one install.",
-  "version": "0.26.1",
+  "version": "0.27.1",
   "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.26.1"
+    "version": "0.27.1"
   },
   "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.26.1",
+      "version": "0.27.1",
       "source": ".",
       "author": {
         "name": "LT",

package/.zcode/hooks.json

@@ -0,0 +1,8 @@
+{
+  "hooks": [
+    {
+      "event": "sessionStart",
+      "command": "bash /Users/litong/Documents/work/code/practice/team-flow-workspace/team-flow/.zcode/team-flow/hooks/session-start"
+    }
+  ]
+}

package/.zcode/rules/phase-guard.mdc

@@ -0,0 +1,33 @@
+---
+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-zcode.mjs 生成；对具体变更的 guard 内容请运行 tf inject <change-dir> 更新。

package/.zcode/skills/workflow-start/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: workflow-start
+description: Primary entry point for the team-flow state-machine workflow. Invoke when the user is inside an active team-flow change directory (look for .team-flow.yaml, changes/<name>/, proposal.md, specs/, design.md, tasks.md, or execution-contract.md) and asks to start, continue, resume, implement, plan, or figure out the next workflow step. Also invoke when the user explicitly asks to start a new team-flow change or route through the team-flow workflow. Do not invoke for unrelated coding tasks that happen to use words like start, continue, implement, or plan.
+---
+
+# Workflow Start
+
+Primary entry point for `team-flow`. Jobs: inspect change context, check for updates, confirm DP-0, determine state, route to correct skill, block invalid transitions.
+
+## Use This Skill When
+
+Only invoke when team-flow context is present: `.team-flow.yaml` exists, artifacts like `proposal.md`/`specs/`/`design.md`/`tasks.md`/`execution-contract.md` are present, or user explicitly invokes team-flow by name. When in doubt, check for `.team-flow.yaml` first.
+
+Do NOT invoke for: general coding tasks outside team-flow changes, casual questions, unrelated work.
+
+## States
+
+`exploring` → `specifying` → `bridging` → `approved-for-build` → `executing` → `closing`, with `debugging` side-path from `executing`, and `abandoned` as terminal. If a transition is ambiguous, run `node '/Users/litong/Documents/work/code/practice/team-flow-workspace/team-flow/.zcode/team-flow/scripts/team-flow.mjs' runtime asset read docs/state-machine.md`.
+
+## Initialization
+
+1. **Update check**: Run `node '/Users/litong/Documents/work/code/practice/team-flow-workspace/team-flow/.zcode/team-flow/scripts/team-flow.mjs' runtime check-update`. Exit 0 → continue. Exit 1 → non-blocking upgrade reminder. Exit 2 → skip.
+2. **Inspect change folder**: Check for `proposal.md`, `specs/`, `design.md`, `tasks.md`, `execution-contract.md`. Answer: Is the change fuzzy? Artifacts missing/unstable? Contract exist? User approved contract? Execution in progress or blocked? In verification/wrap-up?
+3. **Overlay recovery scan**: Run `node '/Users/litong/Documents/work/code/practice/team-flow-workspace/team-flow/.zcode/team-flow/scripts/team-flow.mjs' handoff list <change-dir> --json` and `node '/Users/litong/Documents/work/code/practice/team-flow-workspace/team-flow/.zcode/team-flow/scripts/team-flow.mjs' checkpoint list <change-dir> --json`. A `result-ready` handoff requires explicit review and `node '/Users/litong/Documents/work/code/practice/team-flow-workspace/team-flow/.zcode/team-flow/scripts/team-flow.mjs' handoff resolve` before resuming the affected work. An `active` handoff is non-blocking side work. Show a non-stale checkpoint as recovery context; show a stale checkpoint only as historical evidence.
+4. **Execution-control recovery scan**: For `approved-for-build`, `executing`, `debugging`, or `closing`, run `node '/Users/litong/Documents/work/code/practice/team-flow-workspace/team-flow/.zcode/team-flow/scripts/team-flow.mjs' execution show <change-dir> --json`. Treat only `current: true` plus `waves[].eligible: true` as permission to start a wave; report plan revision, mode, next eligible wave, and every wave's receipt/blockers. A missing, invalid, or stale plan blocks implementation and routes to `build-executor`; do not infer progress from chat history.
+
+## DP-0: User Confirmation Gate
+
+Run DP-0 when: change folder doesn't exist, planning artifacts missing/empty, or `dp_0_confirmed` ≠ `true`. Skip if `dp_0_confirmed` is `true`.
+
+### Upstream Inheritance (v0.9)
+
+若 `change-brief.md` 存在且 `upstream_source == orchestrator`（本 change 由 orchestrator S4 分发），**继承** brief 的 scope/约束/AC 为默认值，DP-0 从"从零问"改为"一次确认继承或修正"，**不**重新问"你想做什么"。否则（手动新建 / hotfix / 单 change 快速通道 / 存量 change 无 brief）照常 DP-0。**主信号 = brief 文件存在**（非 yaml 字段——可天然排除无 brief 的快速通道，且对存量手动 change 零误伤）；双源冲突以 `prd/vN/plan.md` 为准并触发 Brief drift（见「Staleness Detection」）。完整判定伪代码与主信号理由见 `references/routing-rules.md`「DP-0」。
+
+Ask (manual path): change name + one-sentence intent, known constraints, related optimizations (include or stay focused?), communication preference (ask per decision or draft for review).
+
+After confirmation:
+```bash
+node '/Users/litong/Documents/work/code/practice/team-flow-workspace/team-flow/.zcode/team-flow/scripts/team-flow.mjs' state set <change-dir> dp_0_decisions "<summary>"
+node '/Users/litong/Documents/work/code/practice/team-flow-workspace/team-flow/.zcode/team-flow/scripts/team-flow.mjs' state set <change-dir> dp_0_result confirmed
+node '/Users/litong/Documents/work/code/practice/team-flow-workspace/team-flow/.zcode/team-flow/scripts/team-flow.mjs' state set <change-dir> dp_0_confirmed true
+node '/Users/litong/Documents/work/code/practice/team-flow-workspace/team-flow/.zcode/team-flow/scripts/team-flow.mjs' state set <change-dir> dp_0_timestamp $(date -u +%Y-%m-%dT%H:%M:%SZ)
+```
+
+Config-aware routing: check `artifacts.order` and `artifacts.skip` from project config.
+
+## Mode Detection
+
+If workflow is `auto`/`null`/unset: run `node '/Users/litong/Documents/work/code/practice/team-flow-workspace/team-flow/.zcode/team-flow/scripts/team-flow.mjs' runtime infer <change-dir>`. Inference: **hotfix** (≤2 tasks, ≤2 files, no schema/API/new modules), **tweak** (≤4 tasks, config/doc only), **full** (anything larger). Persist with `node '/Users/litong/Documents/work/code/practice/team-flow-workspace/team-flow/.zcode/team-flow/scripts/team-flow.mjs' state set <dir> workflow <mode>`.
+
+Validate mode against artifact content. If hotfix/tweak criteria not met → upgrade to `full` and output reason. Don't overwrite explicit mode unless user asks.
+
+## Routing Rules
+
+### Route to need-explorer
+Change is fuzzy, scope unclear, comparing options, no stable change name.
+
+### Route to architecture-design (v0.9 §26)
+Guard: `arch_design_decision` in `.team-flow.yaml` is `null` → must run before spec-writer. Dispatch `architecture-design` as sub-agent; after return, run reasonableness check and write yaml. Full protocol in `references/routing-rules.md`「Route to architecture-design」.
+
+### Route to spec-writer
+Guard: `node '/Users/litong/Documents/work/code/practice/team-flow-workspace/team-flow/.zcode/team-flow/scripts/team-flow.mjs' runtime guard check <dir> exploring specifying --json` → fail = BLOCK. **arch_design_decision must not be null** → fail = BLOCK (v0.9 §26). User knows what they want, artifacts missing/incomplete.
+
+### Route to contract-builder
+Guard: `... check <dir> specifying bridging --json` → fail = BLOCK. Artifacts exist, implementation requested, contract missing/stale. Include `DP-3: 契约批准`.
+
+### Route to build-executor
+Contract exists and approved, contract matches artifacts. Include `DP-4: 执行模式选择`: propose waves, run `node '/Users/litong/Documents/work/code/practice/team-flow-workspace/team-flow/.zcode/team-flow/scripts/team-flow.mjs' execution recommend <change-dir> [--wave ...]`, show the user every available mode plus evidence and the recommendation, then obtain a clear selection. The command saves a current receipt; before the first implementation edit, `build-executor` must run `node '/Users/litong/Documents/work/code/practice/team-flow-workspace/team-flow/.zcode/team-flow/scripts/team-flow.mjs' execution plan <change-dir> --mode <selected> --confirm ...` (and `--acknowledge-recommendation` when the selected mode differs from the recommendation) using matching artifacts, contract, and waves, then `node '/Users/litong/Documents/work/code/practice/team-flow-workspace/team-flow/.zcode/team-flow/scripts/team-flow.mjs' execution show <change-dir> --json`; report the saved revision, selected mode, recommendation alignment, ordered waves, and actual concurrent-dispatch capability. A revision must repeat recommend and confirmation. Do not transition to `executing` until `show` reports `current: true`; then run `... check <dir> approved-for-build executing --json` → fail = BLOCK.
+
+### Route to bug-investigator
+Execution hit blockage: test failure, unexpected behavior, build error, task cannot proceed. After debugging, route back to build-executor.
+
+### Route to code-reviewer
+The current planned wave is implemented and ready for spec-compliance + code-quality verification. A reviewer must write an `node '/Users/litong/Documents/work/code/practice/team-flow-workspace/team-flow/.zcode/team-flow/scripts/team-flow.mjs' execution review <change-dir> --wave <id> --base <sha> --head <sha> --report <path> --verdict <pass|fail>` receipt before any dependent wave or closing transition.
+
+### Route to release-archivist
+Guard: `... check <dir> executing closing --json` → fail = BLOCK. Implementation complete, verification complete/nearly complete. Include `DP-7: 归档确认`.
+
+### Route to spec-merger
+Delta specs exist that need merging, change closing with ADDED/MODIFIED/REMOVED/RENAMED specs.
+
+### Route to abandoned
+User explicitly requests, bug-investigator escalates after 3+ failures AND user chooses, scope change makes change no longer worthwhile AND user confirms. Block from `closing` or `abandoned`.
+
+### Optional Prototype Handoff
+
+When the user's brief explicitly contains UI, screen, interaction, layout, UX,
+or product-experience uncertainty, ask once whether a prototype would reduce
+uncertainty. Do not create a prototype handoff or enter a prototype worktree
+until the user confirms. After confirmation:
+
+```bash
+node '/Users/litong/Documents/work/code/practice/team-flow-workspace/team-flow/.zcode/team-flow/scripts/team-flow.mjs' handoff create <change-dir> \
+  --type prototype --objective "<confirmed objective>" \
+  --expected-output "<expected evidence>" --acceptance "<completion criterion>"
+tf isolate <change-dir> prototype-<handoff-id>
+```
+
+Never suggest or enter this route automatically for backend, CLI, configuration,
+or internal-refactor work. Never pass `--force` to `tf isolate` for prototype
+work.
+
+### Fast-Path Routing
+
+**DP-0 处理**（v0.22.5 F03 修复）：hotfix/tweak 路径隐式跳过 DP-0（`dp_0_confirmed` 保持 `null`），因为意图已明确（修复/微调），无需从零探索。contract-builder 的 DP-3 审批成为唯一门禁。
+
+- **Hotfix**: Route to contract-builder (minimal), skip need-explorer + spec-writer, guard check `exploring bridging --workflow hotfix`, then `bridging -> approved-for-build`, after DP-3 → build-executor (recommend, show, and confirm an execution mode), after → release-archivist (lightweight). Hotfix may skip `proposal.md`, `design.md`, `tasks.md`, and `specs/`, but it still requires a fresh minimal `execution-contract.md`, DP-3 approval, and a current execution plan before build. **architecture-design 不豁免**（v0.9 §26）：同样过 architecture-design 子代理判断门，快速判定是否涉及架构变更（hotfix 可能正是架构缺陷导致）
+- **Tweak**: Route to build-executor (direct edit), skip need-explorer + spec-writer + contract-builder, guard check `exploring approved-for-build --workflow tweak`, after → release-archivist (lightweight). **architecture-design 不豁免**（v0.9 §26）：同样过 architecture-design 子代理判断门
+
+Post-transition: 💡 `node '/Users/litong/Documents/work/code/practice/team-flow-workspace/team-flow/.zcode/team-flow/scripts/team-flow.mjs' inject <change-dir>` to update phase-guard artifacts.
+
+## Staleness Detection
+
+Use content inspection, not timestamps.
+
+**Stale contract**: proposal scope expanded beyond contract scope fence, or contract references capabilities no longer in proposal → route back to `contract-builder`.
+
+**Stale planning artifacts**: capability in proposal has no spec file, or spec exists for capability not in proposal → drift detected.
+
+**Stale tasks**: requirement in specs has no corresponding task → stale tasks.
+
+**Brief drift (advisory, v0.9, 不阻断)**: change-brief.md 是上游输入（非 team-flow 产物），**不**混入上述三条产物互查、**不**进入 `artifacts_hash`。当 brief 的 `plan_hash` 与当前 `prd/vN/plan.md` 不一致，或 brief AC 列表与 PRD 功能清单明显出入 → 提示"产品层已变更，brief 可能过期，建议回 orchestrator 重新分发（S4→S3 环路）"，**不**触发产物重审。
+
+## Guardrails
+
+- No implementation before planning artifacts or contract exist
+- No implementation for full/hotfix without a current `node '/Users/litong/Documents/work/code/practice/team-flow-workspace/team-flow/.zcode/team-flow/scripts/team-flow.mjs' execution plan`; no state transition based on an unverified DP-4 string
+- No "continue" without state inspection
+- No implementation past stale contract
+- No implementation past bug without investigation
+- No closure without all planned wave review receipts recorded as `pass`
+- No closure with unsynced delta specs
+- No transitions from `abandoned` (terminal)
+- No transition to `abandoned` from `closing` or `abandoned`
+- No auto-abandon without user confirmation
+- No merging delta specs from abandoned change
+- **No routing to spec-writer without architecture-design gate pass** (v0.9 §26): `arch_design_decision` must be `required` or `skipped` (not `null`). hotfix/tweak 不豁免
+
+## State Writes (v0.22.5 F06 修复)
+
+workflow-start 负责写入以下字段到 `.team-flow.yaml`：
+
+**核心状态字段**：
+- `state`：当前状态（exploring/specifying/bridging/approved-for-build/executing/debugging/closing/abandoned）
+- `workflow`：工作流类型（auto/full/hotfix/tweak）
+
+**决策点字段**（各阶段确认后写入）：
+- `dp_0_*`：need-explorer 完成后的需求澄清决策
+- `dp_1_*`：spec-writer 完成后的规格决策
+- `dp_2_*`：contract-builder 完成后的契约决策
+- `dp_3_*`：build-executor 完成后的执行决策
+- `dp_5_*`：code-reviewer 完成后的审查决策
+- `dp_6_*`：release-archivist 完成后的发布决策
+- `dp_7_*`：其他决策点
+
+**架构设计门控字段**（v0.9 §26，v0.22.5 F02 修复）：
+- `arch_design_decision`：`required` | `skipped`（architecture-design 子代理返回，workflow-start 经 reasonableness check 后写入）
+- `arch_design_reason`：判断理由
+- `arch_design_timestamp`：ISO 8601 时间戳（UTC）
+- `arch_design_artifacts`：产出路径列表（required 时必填，skipped 时为空）
+
+**职责边界**：architecture-design 负责判断+产出，workflow-start 负责 reasonableness check + 状态写入。详细写入命令见 `references/routing-rules.md`「Route to architecture-design」。
+
+## Output Standard
+
+Always state: (1) current detected state, (2) why (cite file/content/condition), (3) which skill should run next. If blocking, explain missing artifact/approval.
+
+Decision point references when routing:
+- architecture-design → DP-A（架构设计判断门，v0.9 §26）, contract-builder → DP-3, build-executor → DP-4, bug-investigator (escalation) → DP-5, release-archivist (verification failure) → DP-6, release-archivist → DP-7
+
+## Exception Handling
+
+- **Parse failures**: Fall back to content-level detection if `.team-flow.yaml` is malformed
+- **Missing files**: Route to the skill that generates the missing files
+- **User interruption**: Re-inspect change directory content (not cached state) on resume

package/AGENTS.md

@@ -14,7 +14,7 @@
 
 - **team-flow**（本插件）：Claude Code / Cursor 等宿主的插件实体（`plugin.json` name = `team-flow`），包含 23 个 skills + 8 个 agents + hooks + templates
 - **@xulthekl/team-flow**（npm 底座包）：team-flow 的 CLI 工具层（`package.json` name = `@xulthekl/team-flow`，bin = `tf` / `team-flow`），提供状态机、校验、复利 CLI 等运行时能力
-- 关系：team-flow 插件 **包含** @xulthekl/team-flow npm 包作为底座（同一仓库、同一版本）。skills 中的 `npx --yes --package @xulthekl/team-flow@x.y.z tf ...` 调用的是已发布的 npm 底座包，版本号必须与当前 `package.json` version 一致
+- 关系：team-flow 插件 **包含** @xulthekl/team-flow npm 包作为底座（同一仓库、同一版本）。skills 中的 `tf ...` 调用的是已全局安装的 @xulthekl/team-flow CLI，版本由 session-start hook 自动同步
 - 历史身份（已废弃）：`spec-superflow`（npm 包名，0.11.0 后停止发布）/ `ssf`（CLI 前缀）/ `.spec-superflow.yaml`（状态文件）—— 详见设计增强方案 v0.9 §27
 
 ## Commands

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.26.1 | 阶段: {{state}} | 工作流: {{workflow}}
+# team-flow v0.27.1 | 阶段: {{state}} | 工作流: {{workflow}}
 当前阶段允许的操作由 workflow-start 路由规则定义。
 禁止跨越 DP gate 进入下一阶段。变更范围以 execution-contract.md 的 Intent Lock 为准。
 <!-- team-flow-phase-guard-end -->

package/HANDOFF.md

@@ -111,7 +111,7 @@ team-flow/
 2. **npm 包名 = `@xulthekl/team-flow`**（scoped，解决 publish 权限冲突；author = `xulthekl`）。
 3. **compound 范围 = 核心子集（C 方案，6 个）**，非全量 33。理由：避免 27 个嵌套 agent 全部并入导致膨胀；6 个核心已覆盖「头脑风暴→PRD→全局复利→策略→创意→验证」主链路。
 4. **compound 的 agent 随所属 skill 自动并入**：嵌套在各 skill 内部的 `references/agents/*.md`，作为运行时子代理，非独立顶层 agents。
-5. **CLI = `tf`**（bin 同时暴露 `team-flow` 别名）。npx 调用统一用 `npx --yes --package @xulthekl/team-flow@X.Y.Z tf <subcmd>`。
+5. **CLI = `tf`**（bin 同时暴露 `team-flow` 别名）。CLI 调用统一用 `tf <subcmd>`（全局安装后直接可用，版本由 session-start hook 自动同步）。
 6. **状态文件 = `.team-flow.yaml`**（扁平，每 change 一份）。
 7. **配置文件 = `team-flow.config.json`**（插件层扩展字段：`prd.template` / `prototype.designSystem` / `prototype.entry`）。
 8. **版本同步机制**：`npm run version <x.y.z>` 自动更新 package.json + 所有 manifest + 所有 skill npx 引用 + phase-guard.md / llms.txt / GEMINI.md 版本戳。

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.26.1**。
+当前发布版本：**v0.27.1**。
 
 ---
 

package/README.md

@@ -1,6 +1,6 @@
 # team-flow
 
-> 当前版本：`v0.26.1`
+> 当前版本：`v0.27.1`
 
 > 统一插件：**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.26.1`
+- Current: `v0.27.1`
 - 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,5 +2,6 @@
 <!-- 每条一行，按 severity 降序，≤150 行硬上限 -->
 | date | phase | domain | type | severity | summary | file |
 |------|-------|--------|------|----------|---------|------|
+| 2026-07-30 | cross-phase | general | insight | medium | (no summary) | cross-phase/2026-07-30-no-summary.md |
 | 2026-07-29 | cross-phase | general | insight | medium | (no summary) | cross-phase/2026-07-29-no-summary.md |
 | 2026-07-28 | cross-phase | general | insight | medium | (no summary) | cross-phase/2026-07-28-no-summary.md |

package/docs/solutions/cross-phase/2026-07-30-no-summary.md

@@ -0,0 +1,17 @@
+---
+phase: cross-phase
+domain: general
+type: insight
+severity: medium
+date: 2026-07-30
+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). 17 skills, one install.",
-  "version": "0.26.1",
+  "version": "0.27.1",
   "contextFileName": "GEMINI.md"
 }

package/hooks/session-start

@@ -1,5 +1,41 @@
 #!/usr/bin/env bash
-# v0.26.1: conditional injection — detects artifacts, injects workflow-start pointer
+# v0.27.1: auto-sync CLI version with plugin version
+set -e
+
+# ═══════════════════════════════════════════════════════════════
+# Plugin version (update this when releasing new versions)
+# ═══════════════════════════════════════════════════════════════
+PLUGIN_VERSION="0.27.1"
+
+# ═══════════════════════════════════════════════════════════════
+# Step 1: Auto-sync CLI version with plugin version
+# ═══════════════════════════════════════════════════════════════
+
+sync_tf_version() {
+  # Get installed tf version
+  local installed_version=""
+  if command -v tf &>/dev/null; then
+    installed_version=$(tf --version 2>/dev/null | grep -o '[0-9]\+\.[0-9]\+\.[0-9]\+' | head -1)
+  fi
+
+  # Compare versions and sync if needed
+  if [ "$installed_version" != "$PLUGIN_VERSION" ]; then
+    echo "🔄 team-flow CLI version mismatch: ${installed_version:-not installed} → $PLUGIN_VERSION"
+    echo "   Auto-installing @xulthekl/team-flow@$PLUGIN_VERSION..."
+    npm install -g "@xulthekl/team-flow@$PLUGIN_VERSION" 2>&1 || {
+      echo "⚠️  Auto-install failed. Please run manually:"
+      echo "   npm install -g @xulthekl/team-flow@$PLUGIN_VERSION"
+    }
+  fi
+}
+
+# Run version sync (show output for visibility)
+sync_tf_version
+
+# ═══════════════════════════════════════════════════════════════
+# Step 2: Inject workflow context
+# ═══════════════════════════════════════════════════════════════
+
 msg="<EXTREMELY_IMPORTANT>\nYou have team-flow installed. Invoke /team-flow:workflow-start or /team-flow:workflow-orchestrator ONLY when active team-flow artifacts exist (\`.team-flow.yaml\`, \`proposal.md\`, \`execution-contract.md\`, \`specs/\`) or the user explicitly requests it. For ordinary coding tasks, do NOT invoke them.\n</EXTREMELY_IMPORTANT>\n<EXTREMELY_IMPORTANT>\n## Workspace Directory Rule\n\"Base directory for this skill\" = skill source location (read SKILL.md/references/ ONLY). User project = \`pwd\`. ALL project artifacts (changes/, prd/, docs/, .team-flow/, etc.) MUST operate under \`pwd\`, NEVER the skill base directory. Run \`pwd\` first in every skill execution.\n</EXTREMELY_IMPORTANT>"
 
 # Three platforms share the same message, only output format differs.

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.26.1.
+Current version: v0.27.1.
 
 ## 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.26.1",
+  "version": "0.27.1",
   "description": "Unified plugin (23 skills + 8 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.26.1",
+  "version": "0.27.1",
   "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). 23 skills + 8 agents, one install.",
   "author": {
     "name": "LT"

package/scripts/check-version-consistency.mjs

@@ -67,7 +67,7 @@ const TEXT_CHECKS = [
   { file: 'README.md',              extract: /当前版本：`v(\d+\.\d+\.\d+)`/ },
   { file: 'INSTALL.md',             extract: /当前发布版本：\*\*v(\d+\.\d+\.\d+)\*\*/ },
   { file: 'docs/README_en.md',      extract: /Current: `v(\d+\.\d+\.\d+)`/ },
-  { file: 'hooks/session-start',    extract: /# v(\d+\.\d+\.\d+): conditional injection/ },
+  { file: 'hooks/session-start',    extract: /# v(\d+\.\d+\.\d+):/ },
   { file: 'llms.txt',               extract: /Current version: v(\d+\.\d+\.\d+)\./ },
   { file: '.claude/always/phase-guard.md', extract: /# team-flow v(\d+\.\d+\.\d+) \|/ },
   { file: 'GEMINI.md',              extract: /# team-flow v(\d+\.\d+\.\d+) \|/ },
@@ -88,28 +88,11 @@ for (const check of TEXT_CHECKS) {
   }
 }
 
-const RUNTIME_FILES = [
-  'workflow-start', 'need-explorer', 'spec-writer', 'contract-builder',
-  'build-executor', 'code-reviewer', 'bug-investigator', 'release-archivist', 'spec-merger',
-].map(skill => `skills/${skill}/SKILL.md`).concat([
-  'skills/build-executor/implementer-prompt.md',
-  'skills/build-executor/task-reviewer-prompt.md',
-  'skills/code-reviewer/code-reviewer-prompt.md',
-]);
-for (const file of RUNTIME_FILES) {
-  const fp = join(ROOT, file);
-  if (!existsSync(fp)) {
-    errors.push({ file, found: 'FILE_NOT_FOUND', expected: CANONICAL });
-    continue;
-  }
-  const versions = [...readFileSync(fp, 'utf8').matchAll(/npx --yes --package @xulthekl\/team-flow@(\d+\.\d+\.\d+) tf/g)]
-    .map(match => match[1]);
-  if (versions.length === 0) {
-    errors.push({ file, found: 'RUNTIME_PREFIX_NOT_FOUND', expected: CANONICAL });
-  } else if (versions.some(version => version !== CANONICAL)) {
-    errors.push({ file, found: [...new Set(versions)].join(', '), expected: CANONICAL });
-  }
-}
+// ── Runtime npx version consistency (DISABLED) ──
+// v0.27.0: Skills no longer embed npx version references.
+// CLI version is now synced via session-start hook (reads plugin.json version).
+// This check is disabled to avoid false positives.
+const RUNTIME_FILES = [];
 
 // ── Skill count consistency ──
 // Count actual skill directories under skills/ and compare against the count
@@ -182,35 +165,12 @@ for (const check of SKILL_COUNT_TEXT_CHECKS) {
   }
 }
 
-// ── npx version reference consistency ──
-// Scan every skills/*/SKILL.md for `team-flow@X.Y.Z` references and ensure
-// each one matches the canonical version. Catches stale npx pins in any skill —
-// broader than RUNTIME_FILES above, which only covers the known runtime set.
-const SKILL_MD_FILES = skillDirs
-  .map(entry => `skills/${entry.name}/SKILL.md`)
-  .filter(file => existsSync(join(ROOT, file)));
-
-// Also scan references/ subdirectories for stale npx refs
+// ── npx version reference consistency (DISABLED) ──
+// v0.27.0: Skills no longer embed npx version references.
+// CLI version is now synced via session-start hook (reads plugin.json version).
+// This check is disabled to avoid false positives.
+const SKILL_MD_FILES = [];
 const REFERENCES_FILES = [];
-function scanDir(dir, prefix = '') {
-  const entries = readdirSync(dir, { withFileTypes: true });
-  for (const entry of entries) {
-    const fullPath = join(dir, entry.name);
-    const relPath = prefix ? `${prefix}/${entry.name}` : entry.name;
-    if (entry.isDirectory()) {
-      scanDir(fullPath, relPath);
-    } else if (entry.name.endsWith('.md')) {
-      REFERENCES_FILES.push(relPath);
-    }
-  }
-}
-const refsDir = join(ROOT, 'skills');
-for (const skillEntry of skillDirs) {
-  const refsPath = join(refsDir, skillEntry.name, 'references');
-  if (existsSync(refsPath)) {
-    scanDir(refsPath, `skills/${skillEntry.name}/references`);
-  }
-}
 
 const ALL_SCANNABLE_FILES = [...SKILL_MD_FILES, ...REFERENCES_FILES];
 

package/scripts/install-zcode.mjs

@@ -104,9 +104,10 @@ async function copySkillsWithRoot(sourceSkills, targetSkills, pluginRootAbs) {
       if (content.includes('${CLAUDE_PLUGIN_ROOT}')) {
         content = content.replace(/\$\{CLAUDE_PLUGIN_ROOT\}/g, pluginRootAbs);
       }
+      // v0.27.0: Replace bare `tf` commands with local node path for ZCODE platform
       content = content.replace(
-        /npx --yes --package @xulthekl\/team-flow@\d+\.\d+\.\d+ tf/g,
-        `node ${shellQuote(join(pluginRootAbs, 'scripts', 'team-flow.mjs'))}`,
+        /\btf\s+(?=state|execution|checkpoint|handoff|runtime|validate|doctor|config|version|list|inject|audit|sync|prototype-sync|arch-merge|solutions)/g,
+        `node ${shellQuote(join(pluginRootAbs, 'scripts', 'team-flow.mjs'))} `,
       );
       writeFileSync(skillMd, content, 'utf-8');
     }
@@ -118,9 +119,10 @@ async function copySkillsWithRoot(sourceSkills, targetSkills, pluginRootAbs) {
       if (content.includes('${CLAUDE_PLUGIN_ROOT}')) {
         content = content.replace(/\$\{CLAUDE_PLUGIN_ROOT\}/g, pluginRootAbs);
       }
+      // v0.27.0: Replace bare `tf` commands with local node path for ZCODE platform
       content = content.replace(
-        /npx --yes --package @xulthekl\/team-flow@\d+\.\d+\.\d+ tf/g,
-        `node ${shellQuote(join(pluginRootAbs, 'scripts', 'team-flow.mjs'))}`,
+        /\btf\s+(?=state|execution|checkpoint|handoff|runtime|validate|doctor|config|version|list|inject|audit|sync|prototype-sync|arch-merge|solutions)/g,
+        `node ${shellQuote(join(pluginRootAbs, 'scripts', 'team-flow.mjs'))} `,
       );
       writeFileSync(subPath, content, 'utf-8');
     }

package/scripts/lib/cmd-doctor.mjs

@@ -116,7 +116,7 @@ function checkRuntimeDistribution(root) {
     return { pass: false, message: 'runtime distribution cannot be checked: package.json or skills/ is missing; reinstall team-flow' };
   }
 
-  const canonicalPrefix = `npx --yes --package @xulthekl/team-flow@${pkg.version} tf`;
+  const canonicalPrefix = "tf";
   const issues = [];
   for (const name of readdirSync(skillsDir)) {
     if (!RUNTIME_SKILLS.has(name)) continue;

package/skills/bug-investigator/SKILL.md

@@ -49,7 +49,7 @@ Scientific method: form a single hypothesis ("I think X is the root cause becaus
 
 ### DP-5: Debug Escalation (3+ Failures)
 
-3+ failed fixes = architectural problem. Each fix revealing new problems elsewhere = wrong architecture. Record: `npx --yes --package @xulthekl/team-flow@0.26.1 tf state set <change-dir> dp_5_result <decision>`. Discuss with user before attempting more fixes.
+3+ failed fixes = architectural problem. Each fix revealing new problems elsewhere = wrong architecture. Record: `tf state set <change-dir> dp_5_result <decision>`. Discuss with user before attempting more fixes.
 
 ## Red Flags — Return to Phase 1