@xulthekl/team-flow 0.26.0 → 0.27.0

package/skills/build-executor/SKILL.md

@@ -15,18 +15,18 @@ When `architecture/sql/` exists, also read:
 - `architecture/sql/ddl/*.sql` — executable DDL scripts; reference directly for DB schema change tasks instead of hand-writing DDL
 - `architecture/sql/migration/*.sql` — data migration scripts; execute as-is for data transformation tasks
 
-Check workflow mode first: `npx --yes --package @xulthekl/team-flow@0.26.0 tf state get <change-dir> workflow`. If `tweak` → direct edit mode. If `hotfix` or `full` → standard contract-first discipline.
+Check workflow mode first: `tf state get <change-dir> workflow`. If `tweak` → direct edit mode. If `hotfix` or `full` → standard contract-first discipline.
 
 Branch/worktree preflight before ANY implementation edit (mandatory — do not skip):
 1. Run the isolation check:
    ```bash
-   npx --yes --package @xulthekl/team-flow@0.26.0 tf isolate <change-dir>
+   tf isolate <change-dir>
    ```
    This script enforces git isolation: if you are on `main`/`master` it creates a
    git worktree (preferred) or a new branch, and exits non-zero if it cannot and you
    have not approved `--force`.
-2. If `npx --yes --package @xulthekl/team-flow@0.26.0 tf isolate` exits non-zero: STOP. Do not edit `main`/`master` in place.
-   Ask the user for explicit approval (and re-run with `npx --yes --package @xulthekl/team-flow@0.26.0 tf isolate <change-dir> --force`
+2. If `tf isolate` exits non-zero: STOP. Do not edit `main`/`master` in place.
+   Ask the user for explicit approval (and re-run with `tf isolate <change-dir> --force`
    only after they approve).
 3. If it succeeds, report the chosen branch/worktree and make all implementation
    edits there.
@@ -52,15 +52,15 @@ Return to `specifying` or `bridging` if: new behavior appears, interfaces change
 For `full`/`hotfix`, generate proposed waves from the approved contract, then use the recommendation as a decision aid rather than silently defaulting a mode:
 
 ```bash
-npx --yes --package @xulthekl/team-flow@0.26.0 tf execution recommend <change-dir> \
+tf execution recommend <change-dir> \
   --wave <wave-id>:<parallel|serial>:<task,...>[:<depends-on,...>] --json
 # Show every available mode, the observed facts, and the recommendation to the user.
 # The command writes a receipt tied to the artifacts, contract, and waves. After the user chooses, record that explicit confirmation:
-npx --yes --package @xulthekl/team-flow@0.26.0 tf execution plan <change-dir> \
+tf execution plan <change-dir> \
   --mode <selected-mode> --confirm --reason "user-selected execution mode" \
   --wave <wave-id>:<parallel|serial>:<task,...>[:<depends-on,...>]
 # Add --acknowledge-recommendation when the selection differs from the recommendation.
-npx --yes --package @xulthekl/team-flow@0.26.0 tf execution show <change-dir> --json
+tf execution show <change-dir> --json
 ```
 
 The optional fourth `--wave` segment names prerequisite wave IDs. `execution show --json` reports `current`, plus each wave's `depends_on`, `receipt`, `blockers`, `retryable`, and `eligible` status. A wave with `retryable: true` has a current `fail` receipt and is eligible only for its focused repair and re-review; its dependents remain blocked until its replacement `pass` receipt. Report the saved plan revision, selected mode, ordered waves, dependencies, and whether every `parallel` wave can actually be dispatched concurrently on the current platform. If concurrency is unavailable, state the capability and reason plainly; retain the planned `parallel` strategy and do not silently execute it as a serial or Batch Inline plan.
@@ -73,7 +73,7 @@ The recommendation uses task count, configured `execution.inlineThreshold`, and
 | **Inline** | Recommended for a single sequential task; always available for a user-confirmed choice |
 | **Batch Inline** | Recommended for a bounded sequential batch; it remains serial and is never presented as parallel |
 
-Do not transition to `executing` until `execution show` reports `current: true` and the phase guard passes. A revised plan must repeat `npx --yes --package @xulthekl/team-flow@0.26.0 tf execution recommend` and use `npx --yes --package @xulthekl/team-flow@0.26.0 tf execution revise --confirm`; it creates a new revision and invalidates receipts from the prior revision.
+Do not transition to `executing` until `execution show` reports `current: true` and the phase guard passes. A revised plan must repeat `tf execution recommend` and use `tf execution revise --confirm`; it creates a new revision and invalidates receipts from the prior revision.
 
 ## Batch Inline Execution
 
@@ -88,21 +88,21 @@ Boundaries: if any task touches >1 module, involves schema/API/config changes, o
 For full/hotfix by default. Dispatch according to the persisted plan, review each planned wave, and run a final broad review after all waves.
 
 ### Planned-Wave Loop
-1. Read the current plan with `npx --yes --package @xulthekl/team-flow@0.26.0 tf execution show <change-dir> --json`; only waves shown with `current: true` and `eligible: true` may start. A `retryable: true` wave may only be repaired and re-reviewed; do not dispatch its dependents until its replacement receipt is `pass`. The CLI encodes dependencies in `--wave <id>:<strategy>:<tasks>[:<depends-on,...>]` and rejects a review receipt for a wave whose prerequisites lack current `pass` receipts.
+1. Read the current plan with `tf execution show <change-dir> --json`; only waves shown with `current: true` and `eligible: true` may start. A `retryable: true` wave may only be repaired and re-reviewed; do not dispatch its dependents until its replacement receipt is `pass`. The CLI encodes dependencies in `--wave <id>:<strategy>:<tasks>[:<depends-on,...>]` and rejects a review receipt for a wave whose prerequisites lack current `pass` receipts.
 2. A `parallel` wave may dispatch independent tasks simultaneously only when the platform supports concurrent dispatch. If it does not, disclose the unavailable capability and execute the same wave one task at a time without changing its stored strategy.
 3. A `serial` wave dispatches one task at a time in listed order.
 4. After every wave, write a non-empty persisted regular-file review report (separate from the implementer's report), then record exactly one receipt that names that review report:
    ```bash
-   npx --yes --package @xulthekl/team-flow@0.26.0 tf execution review <change-dir> \
+   tf execution review <change-dir> \
      --wave <wave-id> --base <sha> --head <sha> --report <review-report-path> --verdict <pass|fail>
    ```
    Do not begin a dependent wave until its predecessor receipt is `pass`.
 5. Critical/Important findings require a `fail` receipt, a focused repair, re-review, then a replacement `pass` receipt. Never advance or close with a missing or failed receipt.
 
 ### Per-Task Loop
-1. **Dispatch implementer**: Load the template with `npx --yes --package @xulthekl/team-flow@0.26.0 tf runtime asset read skills/build-executor/implementer-prompt.md`. Extract task brief with `scripts/task-brief PLAN_FILE N`. Include: where task fits, brief path, interfaces from prior tasks, report file path.
+1. **Dispatch implementer**: Load the template with `tf runtime asset read skills/build-executor/implementer-prompt.md`. Extract task brief with `scripts/task-brief PLAN_FILE N`. Include: where task fits, brief path, interfaces from prior tasks, report file path.
 2. **Handle response**: DONE → generate review package + dispatch reviewer. DONE_WITH_CONCERNS → assess. NEEDS_CONTEXT → provide context. BLOCKED → re-dispatch with better model or escalate.
-3. **Review**: Load `npx --yes --package @xulthekl/team-flow@0.26.0 tf runtime asset read skills/build-executor/task-reviewer-prompt.md`. Reviewer returns spec compliance + code quality verdicts with the wave ID, git range, report path, and `pass`/`fail` receipt command.
+3. **Review**: Load `tf runtime asset read skills/build-executor/task-reviewer-prompt.md`. Reviewer returns spec compliance + code quality verdicts with the wave ID, git range, report path, and `pass`/`fail` receipt command.
 4. **Fix**: If Critical or Important issues, write the `fail` receipt, dispatch fix subagent, re-review, and write the replacement `pass` receipt.
 5. **Mark complete**: Append to `.superpowers/sdd/progress.md`: `Task N: complete (commits <base7>..<head7>, review clean)`
 
@@ -110,7 +110,7 @@ For full/hotfix by default. Dispatch according to the persisted plan, review eac
 Use the configured profile that matches the task role. Resolve it before dispatch:
 
 ```bash
-npx --yes --package @xulthekl/team-flow@0.26.0 tf runtime config --resolve-model <profile>
+tf runtime config --resolve-model <profile>
 ```
 
 | Profile | Role |
@@ -123,11 +123,11 @@ npx --yes --package @xulthekl/team-flow@0.26.0 tf runtime config --resolve-model
 For platforms whose dispatch supports a `model` field, explicitly pass the resolved `model` value. If the result is `configured: false`, automatic selection is unavailable: do not invent a provider model and do not bypass the existing requirement to specify `model` explicitly. Resolution only reads configuration; it does not switch models.
 
 ### Progress Ledger
-Track in `.superpowers/sdd/progress.md`. Check for existing ledger — completed tasks are done. After each batch: `npx --yes --package @xulthekl/team-flow@0.26.0 tf state set <change-dir> batches_completed <N>`.
+Track in `.superpowers/sdd/progress.md`. Check for existing ledger — completed tasks are done. After each batch: `tf state set <change-dir> batches_completed <N>`.
 
 ## Inline Execution Mode
 
-Only after a user-confirmed `inline` selection is recorded by `npx --yes --package @xulthekl/team-flow@0.26.0 tf execution plan --confirm`; a non-recommended selection also records `--acknowledge-recommendation`. Executes in the current session and still writes one review receipt per planned wave.
+Only after a user-confirmed `inline` selection is recorded by `tf execution plan --confirm`; a non-recommended selection also records `--acknowledge-recommendation`. Executes in the current session and still writes one review receipt per planned wave.
 
 Per-task: extract brief → write failing test → confirm failure → implement → confirm green → checkpoint review (done-when criteria, SHALL/MUST verification) → commit → save a task-level recovery checkpoint when another task remains → append to progress ledger.
 
@@ -135,7 +135,7 @@ After a task is committed and reviewed, when another task remains, save the
 recovery context with real evidence:
 
 ```bash
-npx --yes --package @xulthekl/team-flow@0.26.0 tf checkpoint save <change-dir> \
+tf checkpoint save <change-dir> \
   --task <completed-task-id> --next "<next task>" --completed "<completed work>" \
   --verification "<verification report path>" --review "<review report path>" \
   --risk "<open risk or None>" --commit-start <base-sha> --commit-end <head-sha>
@@ -143,7 +143,7 @@ npx --yes --package @xulthekl/team-flow@0.26.0 tf checkpoint save <change-dir> \
 
 This augments `.superpowers/sdd/progress.md`; it does not replace the progress
 ledger or add a new core workflow state. Do not claim a checkpoint is current
-when `npx --yes --package @xulthekl/team-flow@0.26.0 tf checkpoint list` reports it as stale.
+when `tf checkpoint list` reports it as stale.
 
 If task hits BLOCKED (3+ fix failures or changes outside declared scope), escalate to SDD.
 
@@ -153,8 +153,8 @@ Skip TDD. Apply changes directly. Verify file integrity (exists, non-empty, vali
 
 ## DP Records
 
-DP-4 is written by `npx --yes --package @xulthekl/team-flow@0.26.0 tf execution plan`; do not write it with raw `state set`.
-DP-5 (debug escalation): `npx --yes --package @xulthekl/team-flow@0.26.0 tf state set <change-dir> dp_5_result "<resolution>"` + timestamp.
+DP-4 is written by `tf execution plan`; do not write it with raw `state set`.
+DP-5 (debug escalation): `tf state set <change-dir> dp_5_result "<resolution>"` + timestamp.
 
 ## Completion Standard
 

package/skills/build-executor/implementer-prompt.md

@@ -22,7 +22,7 @@ Subagent (general-purpose):
     ## Planned Wave
 
     You are assigned to planned wave [WAVE_ID] with strategy [WAVE_STRATEGY].
-    Read `npx --yes --package @xulthekl/team-flow@0.26.0 tf execution show <change-dir> --json` before editing. Do not start
+    Read `tf execution show <change-dir> --json` before editing. Do not start
     unless all declared dependencies have `pass` review receipts. A `parallel`
     label permits concurrent dispatch only when the controller confirms the
     platform supports it; never change the saved wave strategy yourself.

package/skills/build-executor/references/execution-modes.md

@@ -7,14 +7,14 @@
 For `full`/`hotfix`, generate proposed waves from the approved contract, then use the recommendation as a decision aid:
 
 ```bash
-npx --yes --package @xulthekl/team-flow@0.26.0 tf execution recommend <change-dir> \
+tf execution recommend <change-dir> \
   --wave <wave-id>:<parallel|serial>:<task,...>[:<depends-on,...>] --json
 # Show every available mode, the observed facts, and the recommendation to the user.
-npx --yes --package @xulthekl/team-flow@0.26.0 tf execution plan <change-dir> \
+tf execution plan <change-dir> \
   --mode <selected-mode> --confirm --reason "user-selected execution mode" \
   --wave <wave-id>:<parallel|serial>:<task,...>[:<depends-on,...>]
 # Add --acknowledge-recommendation when the selection differs from the recommendation.
-npx --yes --package @xulthekl/team-flow@0.26.0 tf execution show <change-dir> --json
+tf execution show <change-dir> --json
 ```
 
 The optional fourth `--wave` segment names prerequisite wave IDs. `execution show --json` reports `current`, plus each wave's `depends_on`, `receipt`, `blockers`, `retryable`, and `eligible` status.
@@ -37,7 +37,7 @@ Dispatch according to the persisted plan, review each planned wave, and run a fi
 3. A `serial` wave dispatches one task at a time in listed order.
 4. After every wave, write a review report, then record one receipt:
    ```bash
-   npx --yes --package @xulthekl/team-flow@0.26.0 tf execution review <change-dir> \
+   tf execution review <change-dir> \
      --wave <wave-id> --base <sha> --head <sha> --report <review-report-path> --verdict <pass|fail>
    ```
 5. Critical/Important findings require a `fail` receipt, focused repair, re-review, then replacement `pass` receipt.
@@ -66,7 +66,7 @@ Per-task: extract brief → write failing test → confirm failure → implement
 ## Model Selection
 
 ```bash
-npx --yes --package @xulthekl/team-flow@0.26.0 tf runtime config --resolve-model <profile>
+tf runtime config --resolve-model <profile>
 ```
 
 | Profile | Role |
@@ -79,7 +79,7 @@ npx --yes --package @xulthekl/team-flow@0.26.0 tf runtime config --resolve-model
 ## Recovery Checkpoint
 
 ```bash
-npx --yes --package @xulthekl/team-flow@0.26.0 tf checkpoint save <change-dir> \
+tf checkpoint save <change-dir> \
   --task <completed-task-id> --next "<next task>" --completed "<completed work>" \
   --verification "<verification report path>" --review "<review report path>" \
   --risk "<open risk or None>" --commit-start <base-sha> --commit-end <head-sha>

package/skills/build-executor/task-reviewer-prompt.md

@@ -146,7 +146,7 @@ Subagent (general-purpose):
     command for the controller:
 
     ```bash
-    npx --yes --package @xulthekl/team-flow@0.26.0 tf execution review <change-dir> --wave [WAVE_ID] --base [BASE_SHA] --head [HEAD_SHA] --report [REVIEW_REPORT_FILE] --verdict <pass|fail>
+    tf execution review <change-dir> --wave [WAVE_ID] --base [BASE_SHA] --head [HEAD_SHA] --report [REVIEW_REPORT_FILE] --verdict <pass|fail>
     ```
 
     Use `fail` for any Critical/Important finding. A repair must be re-reviewed

package/skills/ce-brainstorm/SKILL.md

@@ -81,13 +81,22 @@ Determine `OUTPUT_FORMAT` (md or html). For the full 5-level precedence, read `r
 2. **降级逻辑（tf 不可用时）**：
    - 通知用户：`tf` 命令不可用，将使用默认配置
    - **询问用户**：默认模板 or 自定义路径？
-     - 默认模板：使用 skill 内置 `templates/prd.md`
+     - 默认模板：**直接 cp skill 内置模板到项目目录**（见下方步骤）
      - 自定义路径：验证文件存在，在项目工作区记录配置
-   - 在 `.team-flow/templates/` 目录创建/使用模板（绝不在 skill 目录写入）
    - **维护配置文件**：在 `.team-flow/team-flow.config.json` 中记录配置（如文件不存在则创建）
 
+3. **默认模板处理步骤（重要）**：
+   - **源文件**：skill 内置 `templates/prd.md`（相对于 skill 基础目录）
+   - **目标目录**：`.team-flow/templates/`（项目工作区）
+   - **操作**：直接 `cp` 源文件到目标目录，**不要自行创建简化版本**
+   - **验证**：检查目标文件是否存在且包含完整的11个章节
+
 Built-in `templates/prd.md` is relative to the skill's base directory. Custom paths are relative to project root.
 
+**⛔ 关键约束**：
+- **错误行为**：自行创建简化版本的PRD模板
+- **正确行为**：直接 cp 原始 PRD 模板到项目目录，保持模板完整性
+
 **Resolve brainstorm profile.** After template resolution, look for `<template-name>-brainstorm-profile.md` in the same directory. Store as `BRAINSTORM_PROFILE_PATH`. Fall back to built-in `templates/prd-brainstorm-profile.md`.
 
 #### 0.1–0.5 Routing Sub-phases
@@ -126,6 +135,22 @@ Propose **2-3 approaches** (or recommend directly if one is clearly best). Use n
 
 ### Phase 3: Generate PRD Document
 
+**⛔ MANDATORY：生成PRD文档前，必须先读取 `references/brainstorm-sections.md`**
+
+**§8.4 功能模块提取规则（关键规则，必须遵守）**：
+- **详细程度**：保留原始需求文档中的关键细节，不要过度概括
+- **必须保留的内容**：
+  - 页面布局（上下分栏、标准列表等）
+  - 搜索模块（具体字段）
+  - 表格列定义（完整字段列表）
+  - 交互规则（默认选中、点击切换、筛选联动等）
+  - 按领域动态字段（如有）
+  - 动态列名说明
+  - 操作说明（已发布/草稿状态等）
+  - 级联选择逻辑（如有）
+- **⛔ 错误行为**：只提取输入/输出/业务规则，丢失原始需求文档中的大量关键细节
+- **⛔ 正确行为**：充分利用原始需求文档的详细内容，保持信息完整性
+
 Read `references/brainstorm-sections.md` for doc-warranted criteria. If warranted: read template from `PRD_TEMPLATE_PATH`, fill via `references/prd-mapping.md`, write to `prd/{ITERATION_VERSION}/prd.md`. Vocabulary capture: update `CONCEPTS.md` with resolved domain terms (only if it exists).
 
 ### Phase 3.5: Prototype Inner Loop

package/skills/ce-brainstorm/references/brainstorm-sections.md

@@ -223,6 +223,20 @@ as template placeholder.
   Skip §8.3 (hardware/network) and §8.5 (non-functional) unless the brainstorm
   explicitly covered these.
 
+  **§8.4 功能模块提取规则**：
+  - **详细程度**：保留原始需求文档中的关键细节，不要过度概括
+  - **必须保留的内容**：
+    - 页面布局（上下分栏、标准列表等）
+    - 搜索模块（具体字段）
+    - 表格列定义（完整字段列表）
+    - 交互规则（默认选中、点击切换、筛选联动等）
+    - 按领域动态字段（如有）
+    - 动态列名说明
+    - 操作说明（已发布/草稿状态等）
+    - 级联选择逻辑（如有）
+  - **错误行为**：只提取输入/输出/业务规则，丢失原始需求文档中的大量关键细节
+  - **正确行为**：充分利用原始需求文档的详细内容，保持信息完整性
+
 ## Agent agency
 
 The chapter catalog is a floor, not a ceiling. When the brainstorm's content

package/skills/code-reviewer/SKILL.md

@@ -16,7 +16,7 @@ Two responsibilities: requesting review (dispatching a reviewer subagent) and re
 1. Get SHAs: `BASE_SHA=$(git rev-parse HEAD~1)` and `HEAD_SHA=$(git rev-parse HEAD)`
 2. Dispatch `general-purpose` subagent using template at `skills/code-reviewer/code-reviewer-prompt.md`
 3. Fill placeholders: `[DESCRIPTION]` (what was built), `[PLAN_OR_REQUIREMENTS]` (contract/spec reference), `[BASE_SHA]`, `[HEAD_SHA]`, `[WAVE_ID]`, and a distinct `[REVIEW_REPORT_FILE]`.
-4. Require the reviewer to write a non-empty persisted review report at `[REVIEW_REPORT_FILE]`, then record that exact path in the wave receipt: `npx --yes --package @xulthekl/team-flow@0.26.0 tf execution review <change-dir> --wave <id> --base <sha> --head <sha> --report <review-report-path> --verdict <pass|fail>`.
+4. Require the reviewer to write a non-empty persisted review report at `[REVIEW_REPORT_FILE]`, then record that exact path in the wave receipt: `tf execution review <change-dir> --wave <id> --base <sha> --head <sha> --report <review-report-path> --verdict <pass|fail>`.
 5. Act on feedback: Critical/Important findings require a `fail` receipt, focused repair, re-review, and replacement `pass` receipt before a dependent wave or closing can proceed. Note Minor for later, push back with reasoning if reviewer is wrong.
 
 ### Minimality And Scope
@@ -76,7 +76,7 @@ Suggestion breaks existing functionality, reviewer lacks context, violates YAGNI
 | Performative agreement | State requirement or just act |
 | Blind implementation | Verify against codebase first |
 | Batch without testing | One at a time, test each |
-| Proceeding without a wave receipt | Record `pass`/`fail` via `npx --yes --package @xulthekl/team-flow@0.26.0 tf execution review` before the next dependent wave |
+| Proceeding without a wave receipt | Record `pass`/`fail` via `tf execution review` before the next dependent wave |
 | Assuming reviewer is right | Check if breaks things |
 | Avoiding pushback | Technical correctness > comfort |
 | Partial implementation | Clarify all items first |

package/skills/code-reviewer/code-reviewer-prompt.md

@@ -93,7 +93,7 @@ Subagent (general-purpose):
     report path. End with the exact receipt command:
 
     ```bash
-    npx --yes --package @xulthekl/team-flow@0.26.0 tf execution review <change-dir> --wave [WAVE_ID] --base [BASE_SHA] --head [HEAD_SHA] --report [REVIEW_REPORT_FILE] --verdict <pass|fail>
+    tf execution review <change-dir> --wave [WAVE_ID] --base [BASE_SHA] --head [HEAD_SHA] --report [REVIEW_REPORT_FILE] --verdict <pass|fail>
     ```
 
     Use `fail` when any Critical or Important finding remains. A repair needs

package/skills/contract-builder/SKILL.md

@@ -5,9 +5,9 @@ description: Convert approved planning artifacts into an execution contract. Inv
 
 # Contract Builder
 
-Converts planning artifacts into a single execution handshake: `execution-contract.md`. Load the baseline with `npx --yes --package @xulthekl/team-flow@0.26.0 tf runtime asset read templates/execution-contract.md`.
+Converts planning artifacts into a single execution handshake: `execution-contract.md`. Load the baseline with `tf runtime asset read templates/execution-contract.md`.
 
-Read before generating: `proposal.md`, `specs/`, `design.md`, `tasks.md`, then load `docs/artifact-contract.md` with `npx --yes --package @xulthekl/team-flow@0.26.0 tf runtime asset read docs/artifact-contract.md`.
+Read before generating: `proposal.md`, `specs/`, `design.md`, `tasks.md`, then load `docs/artifact-contract.md` with `tf runtime asset read docs/artifact-contract.md`.
 
 **Architecture Design Outputs (v0.9 §26)**: 若 `architecture/` 目录存在，同时读取 `architecture/architecture.md` / `database.md` / `api.md`，作为执行契约的架构约束补充输入——确保 execution-contract.md 的 Implementation Constraints 段包含架构设计的关键约束（聚合边界/CQRS 分流/API 契约/schema 变更）。`architecture/` 不存在时跳过。
 
@@ -38,8 +38,8 @@ Must make obvious: approved behavior, out-of-scope, constraints, batches, test o
 
 After drafting: summarize handoff rules, identify ambiguity, flag unmapped requirements, ask user to approve explicitly. After approval:
 ```bash
-npx --yes --package @xulthekl/team-flow@0.26.0 tf state set <change-dir> dp_3_result "approved: <summary>"
-npx --yes --package @xulthekl/team-flow@0.26.0 tf state set <change-dir> dp_3_timestamp $(date -u +%Y-%m-%dT%H:%M:%SZ)
+tf state set <change-dir> dp_3_result "approved: <summary>"
+tf state set <change-dir> dp_3_timestamp $(date -u +%Y-%m-%dT%H:%M:%SZ)
 ```
 DP-3 is a hard gate — no implementation without this record.
 
@@ -60,9 +60,9 @@ Generate minimal contract: Intent Lock (one sentence), Task List (numbered), App
 
 ## Post-Generation
 
-Run `npx --yes --package @xulthekl/team-flow@0.26.0 tf state init <change-dir>` to create `.team-flow.yaml` with hashes.
+Run `tf state init <change-dir>` to create `.team-flow.yaml` with hashes.
 
-For hotfix, after writing the minimal contract, run `npx --yes --package @xulthekl/team-flow@0.26.0 tf state init <change-dir>` or `npx --yes --package @xulthekl/team-flow@0.26.0 tf state rebuild <change-dir>` so `contract_hash` is recorded. DP-3 remains mandatory before build.
+For hotfix, after writing the minimal contract, run `tf state init <change-dir>` or `tf state rebuild <change-dir>` so `contract_hash` is recorded. DP-3 remains mandatory before build.
 
 ## Exception Handling
 

package/skills/need-explorer/SKILL.md

@@ -41,8 +41,8 @@ Restate what you heard: "Here's what I'm hearing: [problem, scope, non-goals, su
 
 After user confirms the summary:
 ```bash
-npx --yes --package @xulthekl/team-flow@0.26.0 tf state set <change-dir> dp_1_result "confirmed: <one-line summary>"
-npx --yes --package @xulthekl/team-flow@0.26.0 tf state set <change-dir> dp_1_timestamp $(date -u +%Y-%m-%dT%H:%M:%SZ)
+tf state set <change-dir> dp_1_result "confirmed: <one-line summary>"
+tf state set <change-dir> dp_1_timestamp $(date -u +%Y-%m-%dT%H:%M:%SZ)
 ```
 DP-1 confirms scope, non-goals, and success criteria before artifact creation.
 

package/skills/release-archivist/SKILL.md

@@ -72,12 +72,12 @@ If an `e2e/` suite exists for the change, fold its report into verification (see
 - Scope added without artifact updates?
 - Unresolved blockers or known risks?
 - Delta specs exist that need merging?
-- Run `npx --yes --package @xulthekl/team-flow@0.26.0 tf audit <change-dir>` — include `decision-point-audit.md` in archive
+- Run `tf audit <change-dir>` — include `decision-point-audit.md` in archive
 
 ### DP-6 (Verification Outcome)
 ```bash
-npx --yes --package @xulthekl/team-flow@0.26.0 tf state set <change-dir> dp_6_result "<pass|conditional|fail>: <summary>"
-npx --yes --package @xulthekl/team-flow@0.26.0 tf state set <change-dir> dp_6_timestamp $(date -u +%Y-%m-%dT%H:%M:%SZ)
+tf state set <change-dir> dp_6_result "<pass|conditional|fail>: <summary>"
+tf state set <change-dir> dp_6_timestamp $(date -u +%Y-%m-%dT%H:%M:%SZ)
 ```
 If FAIL, do NOT proceed to DP-7. Route back or ask about abandonment.
 
@@ -85,13 +85,13 @@ After recording a PASS outcome, also record it as the verification gate so the
 `executing → closing` transition is allowed (the guard accepts either
 `test_result: pass` or a `dp_6_result` starting with `pass`):
 ```bash
-npx --yes --package @xulthekl/team-flow@0.26.0 tf state set <change-dir> test_result pass
+tf state set <change-dir> test_result pass
 ```
 
 ### DP-7 (Archive Confirmation)
 ```bash
-npx --yes --package @xulthekl/team-flow@0.26.0 tf state set <change-dir> dp_7_result "confirmed: <archive summary>"
-npx --yes --package @xulthekl/team-flow@0.26.0 tf state set <change-dir> dp_7_timestamp $(date -u +%Y-%m-%dT%H:%M:%SZ)
+tf state set <change-dir> dp_7_result "confirmed: <archive summary>"
+tf state set <change-dir> dp_7_timestamp $(date -u +%Y-%m-%dT%H:%M:%SZ)
 ```
 Verify DP-0 through DP-6 are recorded before DP-7.
 
@@ -101,14 +101,14 @@ If implementation diverged from the contract, return to `bridging` before closur
 
 ## Post-Verification
 
-Run `npx --yes --package @xulthekl/team-flow@0.26.0 tf state transition <change-dir> closing`. If delta specs exist, route to `spec-merger`.
+Run `tf state transition <change-dir> closing`. If delta specs exist, route to `spec-merger`.
 
 ### Architecture Merge (v0.10 §28-§31) — MUST run first
 
 Merge change-level architecture artifacts to the global `docs/architecture/` baseline **before** any other post-verification step:
 
 ```bash
-npx --yes --package @xulthekl/team-flow@0.26.0 tf arch-merge <change-dir>
+tf arch-merge <change-dir>
 ```
 
 This merges `architecture/{architecture,database,api}.md` and `architecture/sql/` into the global architecture docs. Skip silently when `architecture/` does not exist (architecture-design was `skipped`).
@@ -120,7 +120,7 @@ This merges `architecture/{architecture,database,api}.md` and `architecture/sql/
 After `arch-merge` completes, run prototype-sync to merge UX deltas back to the global prototype:
 
 ```bash
-npx --yes --package @xulthekl/team-flow@0.26.0 tf prototype-sync <change-dir>
+tf prototype-sync <change-dir>
 ```
 
 **Write-back order (mandatory)**: `arch-merge` → `prototype-sync` → `compound promotion` must be executed **sequentially** within the same change closing. Do not run them in parallel — the global `docs/architecture/` and `prototype/` must not be in a half-updated state when the next change grounds on them.
@@ -134,7 +134,7 @@ If `prototype-sync` reports conflicts, list them in the closing summary and flag
 During closing, promote change-level learnings to the global solutions library:
 
 ```bash
-npx --yes --package @xulthekl/team-flow@0.26.0 tf solutions promote <change-dir>
+tf solutions promote <change-dir>
 ```
 
 This checks `specs/<cap>/learnings.md` for entries meeting promotion criteria:
@@ -154,7 +154,7 @@ Before finalizing the closing, check if this change produced any learnable momen
 
 If any of the above occurred, capture the learning:
 ```bash
-npx --yes --package @xulthekl/team-flow@0.26.0 tf solutions capture \
+tf solutions capture \
   --phase cross-phase --domain <domain> --type pitfall \
   --severity medium --summary "<what happened and how to prevent it>"
 ```
@@ -176,6 +176,6 @@ Verify files exist and are non-empty, run `node --check` on code files, skip 5-s
 ## Exception Handling
 
 - **Parse failures**: Report exact file and section
-- **Missing files**: If audit can't generate, run `npx --yes --package @xulthekl/team-flow@0.26.0 tf audit` manually
+- **Missing files**: If audit can't generate, run `tf audit` manually
 - **User interruption**: Re-run verification from the beginning on resume
 - **DP gaps**: Flag missing DPs during DP-6; ask user whether to proceed or return

package/skills/release-archivist/references/closing-procedures.md

@@ -7,7 +7,7 @@
 After `arch-merge` completes, run prototype-sync to merge UX deltas back to the global prototype:
 
 ```bash
-npx --yes --package @xulthekl/team-flow@0.26.0 tf prototype-sync <change-dir>
+tf prototype-sync <change-dir>
 ```
 
 **Write-back order (mandatory)**: `arch-merge` → `prototype-sync` → `compound promotion` must be executed **sequentially** within the same change closing. Do not run them in parallel — the global `docs/architecture/` and `prototype/` must not be in a half-updated state when the next change grounds on them.
@@ -21,7 +21,7 @@ If `prototype-sync` reports conflicts, list them in the closing summary and flag
 During closing, promote change-level learnings to the global solutions library:
 
 ```bash
-npx --yes --package @xulthekl/team-flow@0.26.0 tf solutions promote <change-dir>
+tf solutions promote <change-dir>
 ```
 
 Promotion criteria:
@@ -41,7 +41,7 @@ Before finalizing the closing, check if this change produced any learnable momen
 
 If any occurred, capture the learning:
 ```bash
-npx --yes --package @xulthekl/team-flow@0.26.0 tf solutions capture \
+tf solutions capture \
   --phase cross-phase --domain <domain> --type pitfall \
   --severity medium --summary "<what happened and how to prevent it>"
 ```
@@ -51,22 +51,22 @@ Advisory — skip silently if no learnable moments detected.
 ## DP-6 (Verification Outcome)
 
 ```bash
-npx --yes --package @xulthekl/team-flow@0.26.0 tf state set <change-dir> dp_6_result "<pass|conditional|fail>: <summary>"
-npx --yes --package @xulthekl/team-flow@0.26.0 tf state set <change-dir> dp_6_timestamp $(date -u +%Y-%m-%dT%H:%M:%SZ)
+tf state set <change-dir> dp_6_result "<pass|conditional|fail>: <summary>"
+tf state set <change-dir> dp_6_timestamp $(date -u +%Y-%m-%dT%H:%M:%SZ)
 ```
 
 If FAIL, do NOT proceed to DP-7. Route back or ask about abandonment.
 
 After PASS, also record the verification gate:
 ```bash
-npx --yes --package @xulthekl/team-flow@0.26.0 tf state set <change-dir> test_result pass
+tf state set <change-dir> test_result pass
 ```
 
 ## DP-7 (Archive Confirmation)
 
 ```bash
-npx --yes --package @xulthekl/team-flow@0.26.0 tf state set <change-dir> dp_7_result "confirmed: <archive summary>"
-npx --yes --package @xulthekl/team-flow@0.26.0 tf state set <change-dir> dp_7_timestamp $(date -u +%Y-%m-%dT%H:%M:%SZ)
+tf state set <change-dir> dp_7_result "confirmed: <archive summary>"
+tf state set <change-dir> dp_7_timestamp $(date -u +%Y-%m-%dT%H:%M:%SZ)
 ```
 
 Verify DP-0 through DP-6 are recorded before DP-7.

package/skills/spec-merger/SKILL.md

@@ -10,7 +10,7 @@ After a change completes, delta specs (ADDED/MODIFIED/REMOVED/RENAMED) must be m
 ## Pre-Flight Checks
 
 ### Conflict Detection
-Run `npx --yes --package @xulthekl/team-flow@0.26.0 tf sync <change-dir>`. If conflicts are detected (same requirement modified by multiple changes), present the conflict list to the user for resolution order.
+Run `tf sync <change-dir>`. If conflicts are detected (same requirement modified by multiple changes), present the conflict list to the user for resolution order.
 
 ### Abandoned Change Guard
 Check if the change is `abandoned`. If so → STOP: "Abandoned changes cannot be synced. Delta specs are preserved for reference but must not be merged."
@@ -55,7 +55,7 @@ Output sync report table: Capability, ADDED/MODIFIED/REMOVED/RENAMED counts, Sta
 2. Change folder (including deltas) remains for traceability.
 3. Record that merging is complete so the `executing → closing` guard allows closure:
    ```bash
-   npx --yes --package @xulthekl/team-flow@0.26.0 tf state set <change-dir> spec_merged true
+   tf state set <change-dir> spec_merged true
    ```
    (If the change had no delta sections, still set `spec_merged true` — there was nothing to merge.)
 

package/skills/spec-writer/SKILL.md

@@ -55,7 +55,7 @@ Read `docs/solutions/INDEX.md` if it exists. Filter entries where `phase = spec
 
 ## Config Check
 
-Run: `npx --yes --package @xulthekl/team-flow@0.26.0 tf runtime config --get artifacts.order` — generate in configured order (default: proposal → specs → design → tasks). Run with `artifacts.skip` — skip any listed artifacts.
+Run: `tf runtime config --get artifacts.order` — generate in configured order (default: proposal → specs → design → tasks). Run with `artifacts.skip` — skip any listed artifacts.
 
 ## Artifact Roles
 
@@ -135,8 +135,8 @@ Generate one at a time. Confirm each before next. This prevents scope drift —
 
 Present summary of all 4 artifacts (2-3 sentences each). Ask user for adjustments. After approval:
 ```bash
-npx --yes --package @xulthekl/team-flow@0.26.0 tf state set <change-dir> dp_2_result "approved: <summary>"
-npx --yes --package @xulthekl/team-flow@0.26.0 tf state set <change-dir> dp_2_timestamp $(date -u +%Y-%m-%dT%H:%M:%SZ)
+tf state set <change-dir> dp_2_result "approved: <summary>"
+tf state set <change-dir> dp_2_timestamp $(date -u +%Y-%m-%dT%H:%M:%SZ)
 ```
 
 ## Handoff Rule

package/skills/workflow-orchestrator/SKILL.md

@@ -40,13 +40,101 @@ Do NOT invoke for:
 **先做需求选择**（v0.15.0 多需求）：读 `.team-flow/registry.yaml`，确定 `active_requirement`（多需求则询问操作哪个/新建）。再判断 7 种入口路径之一；检查 baseline.md / CONCEPTS.md 并注入；复利注入（INDEX.md top-5）。**路由结果必须向用户显式确认**（路由是建议非决定）。详见 `references/s1-path-router.md`。
 
 ### S2: PRD + 原型阶段
+
+**⛔ MANDATORY：执行S2阶段前，必须先读取 `references/s2-prd-prototype-loop.md`**
+
+**S2阶段状态管理（关键规则，必须遵守）**：
+```
+prd_draft → user_review → prototype_loop → prd_frozen → completed
+```
+
+| 子阶段 | 说明 | 是否阻塞 |
+|--------|------|---------|
+| `prd_draft` | PRD草稿生成完成 | ⛔ 是（等待用户确认） |
+| `user_review` | 用户查看PRD文档 | ⛔ 是（等待用户确认） |
+| `prototype_loop` | 原型循环（如需要） | 否（自动执行） |
+| `prd_frozen` | PRD冻结 | 否（自动执行） |
+| `completed` | S2阶段完成 | 否（自动执行） |
+
+**⛔ 关键约束**：
+- `prd_draft` 完成后**必须等待用户确认**，不能自动进入 `prototype_loop`
+- 只有用户确认后，才能进入原型循环
+- PRD冻结后，才能进入S3阶段
+- **错误行为**：PRD草稿完成后直接标记S3阶段完成
+- **正确行为**：PRD草稿完成后等待用户查看，确认后继续S2阶段的后续步骤
+
 调用 `/ce-brainstorm`（mode: orchestrated）产出 PRD 草稿；**冻结前派 `prd-completeness-reviewer` 子代理做 PRD 完整性评审**（v0.15.0，管"说得全不全"）；原型循环由编排层直接编排（prototype skill 内部编排产出 → prototype-reviewer 自动评审 → 人工评审 → 冻结）；冻结语义为 `frozen_downstream`（迭代内变更不升版）。反馈环路检查点：scope 是否合理。详见 `references/s2-prd-prototype-loop.md`。
 
 ### S3: 计划阶段
 **入口一次性问定计划模式**（业务/一人公司），调用 `/ce-plan`（`pipeline_mode: orchestrator` + `plan_mode: business|solo`，跳过仪式开销、保留 repo research + change splitting + 依赖 DAG + 技术方向）产出 `prd/vN/plan.md`。plan 只到产品级策略 + 高阶技术设计，**不含接口清单**（属各 change 的 spec-writer）。反馈环路检查点：plan 是否暴露 PRD scope 问题（是→回退 S2）。详见 `references/s3-plan-pipeline.md`。
 
 ### S4: 拆分验证与分发
-change-split-auditor 审计拆分质量（**必选门禁**，粒度/DAG 无环/并行策略/AC 预分配，PASS 后方可创建 change；FAIL → 回退 S3 调整后重新审计）；创建 change 目录（项目根 `changes/<name>/`）+ `.team-flow.yaml`；写入 change_dag；按依赖顺序分发。反馈环路检查点：依赖图是否可执行（否→回退 S3）。详见 `references/s4-split-validate.md`。
+
+**⛔ MANDATORY：执行S4阶段前，必须先读取 `references/s4-split-validate.md`**
+
+**S4 步骤清单（必须按顺序执行，不可跳过）**：
+
+- [ ] **Step 1: 拆分质量审计**（必选门禁，不可跳过）
+  - 调用 `change-split-auditor` agent 对 plan.md 做拆分质量审计
+  - 质量维度：覆盖矩阵 / DAG 无环 / 粒度均衡 / 字段完整 / 拆分维度合规（D5 硬门禁）
+  - **verdict = PASS 是后续步骤的硬前置条件**
+  - verdict = FAIL → 必须回退 S3 调整拆分后重新审计，**不可绕过直接创建 change**
+
+- [ ] **Step 2: 反馈环路检查点**
+  - 依赖图是否可执行？粒度是否合理？
+  - **否** → 回退 S3 调整拆分策略（详见 `references/feedback-loops.md`）
+  - **是** → 继续
+
+- [ ] **Step 3: 创建 change 脚手架**
+  - 为每个 change 执行 `tf state init changes/<change-name>`
+  - 验证 `.team-flow.yaml` 已创建在 `changes/<change-name>/` 下
+  - ⚠️ 路径约束：项目根 `changes/`，非 `.team-flow/` 或 `specs/`
+
+- [ ] **Step 3.5: 落盘 change-brief.md**（产品级→变更级交接物）
+  - 为每个 change 写 `changes/<change-name>/change-brief.md`（已存在则覆盖更新）
+  - 必须包含 YAML frontmatter（见下方规范）
+  - 验证文件存在且格式正确
+
+- [ ] **Step 4: 写入 change_dag**
+  - 更新 `.team-flow/requirements/<req-id>/orchestrator.yaml` 的 `change_dag` 字段
+  - 格式规范：`[{id, change_dir, state_file, depends_on, priority, parallel_group, status}]`
+  - **同步更新** orchestrator.yaml 顶层 `workflow_phase` 为 `s4_split`（单一真相源）
+
+- [ ] **Step 5: 分发**
+  - 告知用户各 change 已就绪及执行顺序建议
+  - 示例：`Change C1 已就绪，运行 /workflow-start 进入变更级流程。执行顺序：C1 → (C2 ∥ C3) → C4`
+
+**S4 完成校验（必须全部通过才能标记 completed）**：
+
+1. ✅ change-split-auditor verdict = PASS（审计报告已生成）
+2. ✅ 所有 change 目录存在于 `changes/` 下（非 `.team-flow/`）
+3. ✅ 每个 change 目录包含 `.team-flow.yaml`（`tf state init` 已执行）
+4. ✅ 每个 change 目录包含 `change-brief.md`（含 YAML frontmatter）
+5. ✅ orchestrator.yaml 的 `change_dag` 已填充（格式正确）
+6. ✅ orchestrator.yaml 顶层 `workflow_phase` 已更新为 `s4_split`
+
+**change-brief.md 规范（v0.27.0 强化）**：
+
+必要字段（YAML frontmatter）：
+```yaml
+upstream_source: orchestrator          # orchestrator | manual | null
+upstream_req_id: <req-id>              # 对应 requirement ID
+upstream_plan_ref: prd/vN/plan.md      # hotfix/快速通道为 null
+upstream_change_id: C2                 # 对应 change_dag.id
+plan_hash: sha256:<plan.md 内容摘要>    # 检测产品层改动后变更层未同步
+```
+
+内容段：Scope / 约束 / AC 列表（取自 auditor 报告 Dim1 覆盖矩阵）/ 全局技术方向（指针，非完整设计）/ PRD & plan 引用
+
+**⛔ 反模式（禁止）**：
+- 使用 CLAUDE.md 替代 change-brief.md（team-flow 从不读取 CLAUDE.md）
+- 在 change-brief 中写完整文件清单（这是 spec-writer 的职责，不属于编排层）
+- 省略 YAML frontmatter
+
+**workflow_phase 同步规则**：
+- **单一真相源**：`orchestrator.yaml` 顶层 `workflow_phase` 字段
+- **阶段转换时**：必须同步更新顶层 `workflow_phase` + 对应 phase 子节点的 `status`
+- **registry.yaml**：引用 `orchestrator.yaml` 的 `workflow_phase`，不独立维护
 
 ### S5: 全局监控（change ≥ 2 必选）
 跟踪各 change 进度；cross-change-consistency-checker 检测跨 change 冲突；change closing 时复利晋升；必要时触发动态重规划。详见 `references/s5-monitoring.md`。