@xulthekl/team-flow 0.24.0 → 0.26.0

package/skills/ce-brainstorm/references/output-format.md

@@ -0,0 +1,25 @@
+# Output Format Resolution
+
+Phase 0.0 resolves `OUTPUT_FORMAT` — the PRD document is written as either markdown (`.md`) OR HTML (`.html`), never both.
+
+## Precedence (highest to lowest)
+
+1. **In-prompt request.** Reason over the user's prompt for a request about *this document's* output format, expressed either as the `output:` shorthand or in plain language ("make this a webpage", "I want this in HTML"). On an explicit format, match it case-insensitively to `md`/`html`, and ignore the `output:` shorthand token when reading the rest of the prompt as the feature description. Distinguish a request about the document's format from a format named as subject matter: "explore an HTML export feature" is the work, not a doc-format request — do not switch on it.
+   - `output:` alone (no value) → no-op, fall through to step 2.
+   - `output:<unknown>` (e.g., `output:pdf`) → drop the token, fall through to step 2, and remember to emit a one-line note above the post-generation menu after final resolution: `Ignored unknown output: value '<value>' — using <resolved_format> instead.` where `<resolved_format>` is the value `OUTPUT_FORMAT` actually resolved to. Do not hardcode `md` in the note.
+
+2. **User-stated preference.** If this prompt holds no format request, honor an output-format preference (markdown vs HTML) the user established earlier — earlier in this session, in your memory, or written into their active instructions — that is already in your context. A remembered preference overrides the config in step 3. Do not open or search instruction files to find it.
+
+3. **Config.** Read `<repo-root>/.compound-engineering/config.local.yaml`. If the config file has an **active (non-commented)** `brainstorm_output:` key whose value matches `md` or `html` (case-insensitive), use it. Missing, invalid, or commented values fall through silently. Critical: lines starting with `#` are YAML comments and must be ignored.
+
+4. **Default.** `OUTPUT_FORMAT=md`.
+
+5. **Pipeline override.** When invoked from LFG or any `disable-model-invocation` context, force `OUTPUT_FORMAT=md` regardless of steps 1-4.
+
+## Token-parsing convention
+
+Only literal-prefix flag tokens (`output:`, `mode:`, `delegate:` where applicable) are consumed and stripped. Other `<word>:<word>` tokens — including conventional commit prefixes like `feat:`, `fix:`, `chore:` — pass through verbatim.
+
+## Rendering reference loading
+
+**Resolve the format here; load the rendering reference at Phase 3, not now.** The format-rendering reference (`references/markdown-rendering.md` for `md`, `references/html-rendering.md` for `html`) is consumed only when the doc is composed — loading it during Phase 0 would carry 200+ lines through the entire dialogue.

package/skills/ce-brainstorm/references/phase0-routing.md

@@ -0,0 +1,96 @@
+# Phase 0 Routing — Sub-phases 0.1 through 0.5
+
+Detailed routing logic for Phase 0 sub-phases. Phase 0.0 (output format + template resolution) lives in `output-format.md` and the main SKILL.md.
+
+## 0.1 Resume Existing Work When Appropriate
+
+If the user references an existing brainstorm topic or document, or there is an obvious recent matching PRD in the `prd/` directory:
+- Scan `prd/` for existing iteration versions (v1, v2, ...)
+- Read the latest PRD document
+- Confirm with the user before resuming: "Found an existing PRD for [topic]. Should I continue from this, or start fresh?"
+- If resuming, summarize the current state briefly, continue from its existing decisions and outstanding questions, and update the existing document instead of creating a duplicate
+- **Resume preserves the existing artifact's format, except pipeline mode.** Write back in whatever format the existing artifact uses — markdown if `.md`, HTML if `.html`. Explicit `output:` arguments override. Pipeline mode always forces `OUTPUT_FORMAT=md`.
+
+Historical `docs/brainstorms/*-requirements.{md,html}` files remain legacy inputs for `ce-plan`, but new outputs write to `prd/{ITERATION_VERSION}/prd.md`.
+
+## 0.1b Classify Task Domain
+
+Before proceeding to Phase 0.2, classify whether this is a software task. The key question is: **does the task involve building, modifying, or architecting software?** — not whether the task *mentions* software topics.
+
+**Software** (continue to Phase 0.2) — the task references code, repositories, APIs, databases, or asks to build/modify/debug/deploy software.
+
+**Non-software brainstorming** (route to universal brainstorming) — BOTH conditions must be true:
+- None of the software signals above are present
+- The task describes something the user wants to explore, decide, or think through in a non-software domain
+
+**Neither** (respond directly, skip all brainstorming phases) — the input is a quick-help request, error message, factual question, or single-step task.
+
+**Verdict-shape carve-out — do not exit before the 0.1c gate.** A request weighing whether to **adopt / switch to / replace** a *named external technology, library, pattern, platform, or architecture* for this project is a **software** decision. Classify it as **Software** and continue so the 0.1c gate can catch it.
+
+**If non-software brainstorming is detected:** Read `references/universal-brainstorming.md` now and follow it — it replaces Phases 0.2–4 entirely. The non-software route does **not** write a PRD document. The **Core Principles and Interaction Rules still apply unchanged**.
+
+## 0.1c Route a Verdict Question to ce-pov
+
+A brainstorm scopes **what to build** once a direction is chosen. Deciding **whether to adopt, switch to, or replace** a *specific named external candidate* judged against this project is `ce-pov`'s purpose.
+
+**The verdict shape — all three hold:** a **named external candidate**; a **whether-to-commit intent** (adopt / switch to / migrate / replace / is-it-time-for / revisit); judged **against this project** (fit, migration cost, worth it here).
+
+When the shape matches — at intake, or whenever later dialogue clarifies a request into it — read `references/verdict-routing.md` and follow it: offer the `/ce-pov` handoff interactively (never silently switch), invoke `ce-pov` on accept, drop the offer and continue unchanged on decline.
+
+## 0.2 Assess Whether Brainstorming Is Needed
+
+**Clear requirements indicators:**
+- Specific acceptance criteria provided
+- Referenced existing patterns to follow
+- Described exact expected behavior
+- Constrained, well-defined scope
+
+**If requirements are already clear:**
+Keep the interaction brief. Skip Phase 1.1 and 1.2 entirely — still classify tier in Phase 0.3, then go straight to Phase 1.3 or Phase 2.5 and follow `references/synthesis-summary.md`'s Path A / Path B gate exactly. Do not assume the synthesis is announce-only: a richly pre-loaded prompt classifies as Standard or Deep, which routes to Path B.
+
+## 0.3 Assess Scope
+
+Use the feature description plus a light repo scan to classify the work:
+- **Lightweight** — small, well-bounded, low ambiguity
+- **Standard** — normal feature or bounded refactor with some decisions to make
+- **Deep** — cross-cutting, strategic, or highly ambiguous
+
+If the scope is unclear, ask one targeted question to disambiguate.
+
+**Deep sub-mode: feature vs product.** For Deep scope, also classify whether the brainstorm must establish product shape or inherit it:
+
+- **Deep — feature** (default): existing product shape anchors decisions. The brainstorm extends or refines within that shape.
+- **Deep — product**: the brainstorm must establish product shape. Primary actors, core outcome, positioning, or primary end-to-end flows are materially unresolved.
+
+Product-tier triggers additional Phase 1.2 questions and additional Product Contract sections.
+
+**Visual probe tripwire.** If the feature is inherently visual or spatial — drawing/canvas tools, annotation behavior, visual editors, UI layout or navigation, interaction states, charts, diagrams, animation, maps, timelines, or spatial flows — read `references/visual-probes.md` now. Loading the reference here is readiness only; it owns when the gate fires.
+
+**Unfamiliarity tripwire.** If the user signals they lack working knowledge of the domain — "I know nothing about X", "never touched the auth modules" — read `references/blindspot-pass.md` now. Loading here is readiness only; the reference owns when the offer fires.
+
+## 0.4 Surface the Workflow Spine
+
+For **Standard and Deep** scope, use the platform's task-tracking capability when available. Skip for Lightweight and on the non-software route.
+
+The spine is five tasks, in order:
+1. Check what already exists
+2. Ask scoping questions
+3. Weigh approaches and recommend
+4. Confirm scope before writing
+5. Write the PRD document
+
+**Conditional work earns a task only when its gate fires** — never at creation. A branch earns one when the user is waiting on it or would be surprised. Insert at the position where it runs.
+
+**Name every task** verb first, five words or fewer, naming the outcome — not the phase or tool. `Verify claims against the code`, not `Phase 2.6 claim verification`.
+
+**When a gate resolves such that a listed task will not run, record the skip** — never mark it plainly complete. Use `cancelled`/`skipped` status, or rename to name the skip, or delete. Say why in the conversation.
+
+## 0.5 Resolve Iteration Version
+
+Scan the `prd/` directory to detect existing iteration versions (v1, v2, v3, ...).
+- If no iterations exist: suggest creating v1, ask user to confirm
+- If iterations exist: suggest the latest iteration, offer to continue or create new
+- User confirms the target iteration version
+- Store as `ITERATION_VERSION` (e.g., "v1", "v2")
+- Target PRD path: `prd/{ITERATION_VERSION}/prd.md`
+- Scan `prototype/` directory to confirm prototype branch aligns with PRD iteration version (if prototype exists).

package/skills/ce-brainstorm/references/prd-mapping.md

@@ -69,3 +69,40 @@ PRD 冻结时（`frozen_downstream`），在正文标题下方插入冻结声明
 > 仅当**启动新迭代 vN+1** 或**用户显式绝对冻结**（`frozen_absolute`）时，才需升版。
 ```
 
+## Brainstorm Profile 机制（v0.25 新增）
+
+每个 PRD 模板应配套一个 **brainstorm profile** 文件，定义 Phase 2 方案探索的产品维度锚点，确保需求阶段聚焦产品方案而非技术决策。
+
+### 文件命名规则
+
+`<模板名>-brainstorm-profile.md`，与模板同目录：
+
+| PRD 模板 | Brainstorm Profile |
+|----------|-------------------|
+| `templates/prd.md` | `templates/prd-brainstorm-profile.md` |
+| `my-project/prd-template.md` | `my-project/prd-template-brainstorm-profile.md` |
+| `.team-flow/custom-prd.md` | `.team-flow/custom-prd-brainstorm-profile.md` |
+
+### 查找优先级
+
+1. 自定义模板同目录的 profile 文件（按命名规则推导）
+2. 内置默认 `templates/prd-brainstorm-profile.md`（相对 skill 基目录）
+
+### Profile 三段结构
+
+| 段落 | 作用 | Phase 2 中的行为 |
+|------|------|-----------------|
+| **核心思考维度** | 每个方案必须覆盖的产品维度 | 每个方案按维度展开，未覆盖需说明原因 |
+| **扩展思考维度** | 按需触发的补充维度 | 根据需求特征决定是否覆盖 |
+| **反例边界** | 禁止越界的技术决策类型 | 方案探索中不得包含这些内容 |
+
+### 自定义 Profile
+
+创建新 PRD 模板时，**必须同步创建**对应的 brainstorm profile。未配套 profile 的模板将使用内置默认的 GTMC D7 profile——维度可能与模板结构不匹配。
+
+自定义 profile 应包含：
+1. 核心维度表：维度名、对应 PRD 章节、引导问题
+2. 扩展维度表：维度名、触发条件、对应 PRD 章节、引导问题
+3. 反例边界列表：Phase 2 不应包含的技术决策类型
+4. 正向示例：正确的产品方案输出 + 错误的技术方案输出
+

package/skills/ce-brainstorm/references/prototype-loop.md

@@ -0,0 +1,55 @@
+# Phase 3.5 — Prototype Inner Loop（原型内循环）
+
+> **v0.7 条件化**：当 `mode: orchestrated` 时，跳过整个 Phase 3.5（原型循环由 orchestrator 编排）。以下为 standalone 模式的流程。
+
+PRD 文档写入后、Handoff 之前，执行原型内循环。原型是 PRD 的**验证工具**，不是 PRD 的下游。
+
+## 3.5.1 原型触发判断
+
+检查 PRD 草稿中是否包含 UI/画面/交互相关功能点（§4 画面原型、§7 系统功能清单中的 UI 功能）。
+
+- **包含 UI 功能点** → 使用平台阻塞问题工具询问用户："PRD 包含 UI 功能点，是否需要产出原型进行验证？"
+- **不包含 UI 功能点** → 跳过原型内循环，直接进入 Phase 4
+- **用户选择跳过** → 跳过，PRD 直接冻结
+
+## 3.5.2 原型产出
+
+如果需要原型：
+1. 读取 PRD 草稿中的功能点清单（§7 系统功能清单）
+2. 读取项目 `design-system.md`（通过 `tf runtime config --get prototype.designSystem` 获取路径）
+3. 调用 `/prototype` skill 产出原型页面
+4. 产出 `prototype/` 目录（index.html + pages/ + components/ + flow.md）
+
+## 3.5.3 原型审查（对照 PRD）
+
+逐功能点检查：
+- PRD 中每个 UI 功能点是否在原型中有对应页面/组件？
+- PRD 中的状态流转是否在原型 flow.md 中完整体现？
+- PRD 中的边界条件是否在原型中有体现（空状态/错误状态/加载状态）？
+
+产出审查报告：覆盖/遗漏/矛盾清单。
+
+## 3.5.4 修正循环
+
+如果审查发现问题：
+- **遗漏** → 回到 Phase 1.3 对话，补充 PRD 功能点 → 更新原型 → 回 3.5.3
+- **矛盾** → 回到 Phase 1.3 对话，解决矛盾 → 更新原型 → 回 3.5.3
+- **最多循环 3 次**，超过则标记为"需人工介入"，在 PRD 中记录未解决项
+- 每次修正触发复利捕获：`tf solutions capture --phase prd --domain <domain> --type pitfall --severity medium --summary "<修正原因>"`
+
+## 3.5.5 PRD 完整性评审（冻结前门禁）
+
+原型审查通过后、冻结前，派发 `prd-completeness-reviewer` 子代理（只读，独立上下文），评审 PRD「是否完整到能支撑后续 plan/spec 实施」（区别于 Phase 2.6 claim verifier——后者管"说得对不对"，本评审管"说得全不全"）。
+
+- 派发：按名派发插件 agent `prd-completeness-reviewer`（定义见插件 `agents/prd-completeness-reviewer.md`），传入 PRD 路径 + CONCEPTS.md 路径。
+- 子代理按 §18.1 交接协议返回。报告落盘到 `prd/{ITERATION_VERSION}/prd-completeness-review.md`。
+- 判定（柔性）：PASS / PASS_WITH_WARNINGS → 进入冻结；**FAIL（Critical>0）→ 回 Phase 1.3 补充**后重审。
+- 5 维度：用户故事完整性(Critical)/验收标准(Critical)/边界与非功能(Important)/术语一致性(Minor)/范围闭环(Important)。
+
+## 3.5.6 冻结
+
+完整性评审通过后：
+1. 写入 `prd/{ITERATION_VERSION}/prototype-review.md`（审查结论 + 版本 + 日期 + 循环次数）
+2. PRD 标记为 frozen（在 PRD frontmatter 中增加 `frozen: true` + `frozen_date: YYYY-MM-DD`），并在正文标题下插入冻结声明（措辞见 `references/prd-mapping.md`「冻结声明」节）
+3. **冻结语义为 `frozen_downstream`（非升版）**：后续阶段（ce-plan、spec-writer）**不可直接回改** PRD；如 plan 或实施暴露 scope 问题，经 **S3→S2 回退在 vN 内修订**并记录「决策与变更履历」（不升版）。**仅当启动新迭代 vN+1 或用户显式绝对冻结（`frozen: absolute`）时才需升版。**
+4. 同步更新正文 §1.1 文档状态为「已冻结-下游」（与 frontmatter `frozen: true` 一致）