@xulthekl/team-flow 0.22.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MageByte
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,185 @@
+# team-flow
+
+> 当前版本：`v0.22.4`
+
+> 统一插件：**team-flow**（spec 驱动开发）+ **compound-engineering 核心子集**（全局复利）+ **architecture-design**（4A+DDD 增量设计）+ **prototype**（本地 HTML 原型）+ **e2e**（AC 驱动 E2E）+ **workflow-orchestrator**（产品级编排）+ **workflow-bootstrap**（既有项目接入）。一次安装，七套能力协同。
+
+## 30 秒上手
+
+告诉它你的想法，它会帮你理清楚要做什么、怎么做、先做哪个。
+
+```bash
+# 在 Claude Code 中输入：
+/workflow-orchestrator
+# 然后说你的想法，例如："我想做一个任务管理功能"
+# 跟着走就行——它会自动安排需求澄清、原型验证、计划拆分
+```
+
+**你只需要知道 3 个概念**：
+1. **PRD**：你的需求文档（它帮你写）
+2. **change**：拆分后的实施单元（它帮你拆）
+3. **workflow-start**：开始实施一个 change（它帮你启动）
+
+更多能力（原型验证、复利经验库、动态重规划等）在使用中自然接触，无需提前学习。
+
+## 安装（plugin.json 一次安装）
+
+支持 9 安装面：Claude Code、Cursor、OpenAI Codex CLI/App、GitHub Copilot CLI、Gemini CLI、OpenCode、WorkBuddy、Trae、ima-copilot。
+
+```bash
+# 本地路径安装（子命令依宿主 CLI 而定）
+<cli> plugin install /path/to/team-flow
+
+# 或从仓库
+git clone <your-repo> && <cli> plugin install ./team-flow
+```
+
+> 不同宿主 CLI 的安装子命令略有差异（如 Claude Code 为 `/plugin add`，Cursor 为 `plugin install`）。以宿主文档为准；本插件提供单一 `plugin.json`，一次安装即加载全部 22 个 skills。
+
+## 配置（插件层扩展字段）
+
+项目根 `team-flow.config.json` 可注入（**插件层扩展字段，非 team-flow 原生 schema；原生仅 `artifacts.order` / `artifacts.skip`**）：
+
+```json
+{
+  "prd.template": ".team-flow/prd.template.md",
+  "prototype.designSystem": "prototype/design-system.md",
+  "prototype.entry": "prototype/index.html"
+}
+```
+
+读取方式：`tf runtime config --get <key>`（插件层自读，字段命名避开原生 key 冲突）。
+
+## 初始化原型（首次）
+
+```bash
+cp -r <plugin>/skills/prototype/references/prototype-scaffold/ <project>/prototype/
+```
+
+随后按 `prototype/design-system.md` 填 token；`prototype/` 与 `prd/` 同级、git 分支隔离版本。
+
+## 全局产物结构
+
+```
+prd/               PRD + 实施方案 + 原型审查记录（v1→v2，分支隔离）
+prototype/         全局原型（UI 契约真相源）
+docs/
+  ├── architecture/  全局架构锚点（ARCHITECTURE.md / DATABASE.md / <bc>/ / baseline.md）
+  └── solutions/     复利经验库（三层索引：INDEX.md → 分阶段目录 → 经验文件）
+specs/<cap>/        每变更设计/任务/契约 + learnings.md
+STRATEGY.md CONCEPTS.md 策略 / 领域词汇
+```
+
+## 九套能力（23 skills）
+
+- **team-flow**（9）：workflow-start / need-explorer / spec-writer / contract-builder / build-executor / code-reviewer / spec-merger / release-archivist / bug-investigator
+- **compound 核心子集**（6）：ce-brainstorm / ce-plan / ce-compound / ce-strategy / ce-ideate / ce-proof
+- **architecture-design**（1）：architecture-design
+- **prototype**（1）：prototype
+- **e2e**（1）：e2e（AC 驱动 Playwright E2E 测试）
+- **产品级编排**（1）：workflow-orchestrator（brainstorm→原型内循环→plan→拆change→分发）
+- **既有项目接入**（1）：workflow-bootstrap（代码库侦察→架构基线→领域词汇→目录初始化）
+- **会话交接**（1）：session-handoff（上下文腐化时压缩会话为交接文档，v0.16.0）
+- **工作流反馈**（1）：workflow-feedback（工作流问题结构化记录，与 ce-compound 互补，v0.16.0）
+- **设计系统**（1）：design-system（独立创建/迭代项目级设计系统，用户主导交互，v0.19.0）
+
+### 配套 agents（8 个，v0.15.0 增至 8）
+
+执行下沉的非交互子代理（主代理只编排）：code-reviewer / bug-investigator / prototype-reviewer / change-split-auditor / cross-change-consistency-checker / **prd-completeness-reviewer**（PRD 完整性评审）/ **prototype-builder**（原型绘制）/ **prototype-env-scout**（原型环境探查）。
+
+### 命名约定
+
+Skills 命名保留其来源前缀，作为功能分组的自然标识：
+
+| 前缀 | 来源 | 含义 | Skills |
+|------|------|------|--------|
+| `ce-` | compound-engineering | 产品级思维工具（头脑风暴、计划、策略、复利、创意、验证） | ce-brainstorm, ce-plan, ce-strategy, ce-compound, ce-ideate, ce-proof |
+| 无前缀 | team-flow | 变更级开发流程工具（状态机、规格、构建、审查、归档） | workflow-start, need-explorer, spec-writer, contract-builder, build-executor, code-reviewer, spec-merger, release-archivist, bug-investigator |
+| 无前缀 | team-flow 新增 | 编排/接入/设计/原型/测试/交接/反馈 | workflow-orchestrator, workflow-bootstrap, architecture-design, prototype, e2e, session-handoff, workflow-feedback |
+
+> `ce-` 前缀来自 compound-engineering 项目，team-flow 整合时保留了这一命名以维持功能分组的可辨识性。这不是命名不一致，而是有意的来源标注。
+
+## 工作流（SOP，v0.7 修订）
+
+```
+模糊需求
+  → [既有项目接入层 workflow-bootstrap]（一次性，baseline.md 已存在则跳过）
+  → [产品级编排层 workflow-orchestrator]（v0.7 重设计）
+  → S1 路径路由器 → 判断入口路径（全新/续版/重新计划/继续执行/快速通道/Hotfix）
+  → S2 PRD + 原型阶段 → ce-brainstorm + 原型循环上提（prototype → 自动评审 → 人工评审 → 冻结）
+  → S3 计划阶段 → ce-plan（pipeline 快速路径）→ plan.md（change 拆分+依赖+技术方向）
+  → S4 拆分验证与分发 → change-split-auditor 审计（必选门禁）→ 创建 change → 进入 team-flow
+  → S5 全局监控（change≥2 必选）→ 跨 change 一致性 + 复利晋升 + 动态重规划
+  → [复利贯穿层] 每个阶段转换点：检测→捕获→索引→注入
+  → change 完成：arch-merge → prototype-sync（顺序提交）+ 复利晋升
+```
+
+详见 `AGENTS.md`。
+
+## 受 guard 保护的执行计划（execution plan）
+
+full/hotfix 在 DP-4 必须保存 current execution plan 到
+`<change>/.superpowers/sdd/execution-plan.json`；它不属于 `execution-contract.md`。
+先运行 `tf execution recommend`（执行模式推荐）：它按任务量和 wave 策略列出 `inline`、
+`batch-inline`、`sdd` 并给出推荐，并保存当前 wave 的推荐凭据到
+`<change>/.superpowers/sdd/execution-recommendation.json`。Agent 展示候选项和理由后，
+`plan` 与 `revise` 必须消费匹配当前 artifact、contract 和 wave 的凭据；用户用 `--confirm`
+确认；若选择非推荐方式，必须用 `--acknowledge-recommendation` 记录确认风险。Batch
+Inline 始终串行，不会表示并行。`tweak` 免除 execution plan 与 review receipt gate。
+
+```bash
+tf execution recommend changes/my-change \
+  --wave foundation:parallel:1.1,1.2 \
+  --wave integration:serial:2.1:foundation --json
+tf execution plan changes/my-change --mode sdd --confirm --reason "independent work" \
+  --wave foundation:parallel:1.1,1.2 \
+  --wave integration:serial:2.1:foundation
+tf execution show changes/my-change --json
+# inline/batch-inline 可升级为 sdd，或重规划已有 sdd 的 wave/依赖；不能降级。
+tf execution recommend changes/my-change \
+  --wave foundation:parallel:1.1,1.2 \
+  --wave integration:serial:2.1:foundation --json
+tf execution revise changes/my-change --mode sdd --confirm --reason "need parallel work" \
+  --wave foundation:parallel:1.1,1.2 \
+  --wave integration:serial:2.1:foundation
+tf execution review changes/my-change --wave foundation --base <sha> --head <sha> \
+  --report .superpowers/sdd/reviews/foundation.md --verdict pass
+```
+
+`--report` 相对于 `<change>` 解析，且必须位于
+`<change>/.superpowers/sdd/reviews/` 之下。`--base` 和 `--head` 必须是该
+`<change>` Git 工作树中的真实 commit，且 `base` 必须是 `head` 的祖先。
+`<change>/.superpowers/sdd/reviews/` 的目录层级必须是物理、非符号链接目录；
+report 本身必须为普通、非空、非符号链接文件。
+
+每一个 wave 均须有当前 `pass` review receipt，才可启动依赖 wave 或进入 closing；
+修订计划会废止旧 receipt。#47 所提出的恢复、切换与手动保存 slash command 尚未实现，
+不能假定有 `/tf:*` 命令。
+
+## OpenAI Codex CLI 安装与升级
+
+```bash
+codex plugin marketplace add hashgraph-online/awesome-codex-plugins
+codex plugin add team-flow@awesome-codex-plugins
+```
+
+直接安装指定 release tag（绕过社区镜像延迟）：
+
+```bash
+codex plugin marketplace add MageByte-Zero/team-flow --ref v0.9.0
+codex plugin add team-flow@team-flow
+```
+
+升级：
+
+```bash
+codex plugin marketplace upgrade awesome-codex-plugins
+codex plugin add team-flow@awesome-codex-plugins
+codex plugin list | rg team-flow
+```
+
+## v0.9.0 亮点
+
+- **Node 20** 最低运行时要求
+- **model profiles**（`tf config --resolve-model`）：mechanical / standard / strong / review 四档模型配置，只读解析，不切换当前会话模型
+- **最小性**原则：零运行时依赖、自包含插件、按需加载

package/SECURITY.md

@@ -0,0 +1,37 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability in team-flow, please report it via GitHub's [private vulnerability reporting](https://github.com/MageByte-Zero/team-flow/security/advisories/new) or email **magebyte@163.com**.
+
+**Do not open a public issue** for security vulnerabilities.
+
+## What to Include
+
+- A clear description of the vulnerability
+- Steps to reproduce
+- Affected versions
+- Any potential mitigations you've identified
+
+## Response Timeline
+
+- **Acknowledgment**: Within 48 hours
+- **Status Update**: Within 5 business days
+- **Resolution**: We aim to patch confirmed vulnerabilities within 30 days
+
+## Scope
+
+team-flow is a plugin that runs locally. Security considerations include:
+
+- **Session-start hooks**: Hook scripts execute with the user's shell privileges. Review hook changes carefully.
+- **Skill instructions**: Skills contain AI agent instructions. Maliciously crafted skills could instruct the agent to execute harmful commands.
+- **CLI tools**: The `tf` command runs with Node.js privileges and reads/writes local files.
+
+## Supported Versions
+
+| Version | Supported |
+|---------|-----------|
+| Latest release (`main` branch) | ✅ |
+| Older releases | ❌ |
+
+**This project does not offer long-term support (LTS) for older versions.**

package/agents/bug-investigator.md

@@ -0,0 +1,180 @@
+---
+name: bug-investigator
+description: Use this agent when the user encounters a bug, test failure, unexpected behavior, build failure, or performance issue and wants autonomous root-cause investigation. The agent explores the codebase, forms hypotheses, tests them, and produces a structured root-cause analysis report. Examples:
+
+<example>
+Context: A test is failing and the user wants to understand why before attempting a fix.
+user: "This test has been failing since yesterday, can you investigate why?"
+assistant: "I'll launch the bug-investigator agent to systematically trace the root cause of the test failure."
+<commentary>
+The user wants root-cause analysis, not a quick patch. The bug-investigator agent follows a scientific method: read errors → reproduce → trace data flow → form hypothesis → test → report. It writes investigation notes but does not fix the code.
+</commentary>
+</example>
+
+<example>
+Context: Unexpected behavior in production that doesn't reproduce easily.
+user: "用户在生产环境报了一个诡异的 bug，偶发性的，帮我排查一下"
+assistant: "我来启动 bug-investigator agent，系统性地排查这个偶发问题的根因。"
+<commentary>
+Intermittent bugs require structured investigation — gathering evidence, checking component boundaries, tracing data flow. The agent excels at methodical root-cause analysis for hard-to-reproduce issues.
+</commentary>
+</example>
+
+<example>
+Context: Multiple fix attempts have failed and the user suspects a deeper issue.
+user: "I've tried fixing this three times and it keeps breaking in different ways — something is fundamentally wrong"
+assistant: "This sounds like an architectural issue. Let me dispatch the bug-investigator agent to do a deep root-cause investigation."
+<commentary>
+Multiple failed fixes indicate the symptom is being addressed, not the cause. The agent's DP-5 escalation logic specifically handles this: 3+ failures = question the architecture.
+</commentary>
+</example>
+
+<example>
+Context: A build failure with unclear error messages.
+user: "The build broke and the error message doesn't make sense, can you figure out what's going on?"
+assistant: "I'll use the bug-investigator agent to trace the build failure to its root cause."
+<commentary>
+Unclear errors require careful reading of stack traces, checking recent changes, and tracing dependency chains. The agent systematically narrows down the cause.
+</commentary>
+</example>
+
+model: inherit
+color: yellow
+tools: ["Read", "Bash", "Grep", "Glob", "Write"]
+---
+
+You are an expert Bug Investigator. You systematically investigate bugs, test failures, and unexpected behavior to find their root cause. You follow the scientific method: observe, hypothesize, test, conclude. You produce a root-cause analysis report — you do NOT implement fixes.
+
+## The Iron Law
+
+No conclusions without evidence. If you haven't completed root-cause investigation, you cannot declare a cause. Symptom-level guesses are failure.
+
+## Investigation Process
+
+Complete each phase before proceeding to the next. Do not skip phases.
+
+### Phase 1: Root Cause Investigation
+
+1. **Read error messages carefully**: Parse stack traces, line numbers, file paths, error codes. They often contain the exact solution — don't skim.
+2. **Reproduce consistently**: Run the failing command/test. Record exact steps. If not reproducible → gather more data, add diagnostics, do NOT guess.
+3. **Check recent changes**: Use `git log`, `git diff`, and `git blame` to identify what changed recently. Check new dependencies, config changes, environment differences.
+4. **Multi-component systems**: Add diagnostic instrumentation at each component boundary. Log what enters and exits each layer. Run once to gather evidence, then analyze which component fails.
+5. **Trace data flow**: Backward tracing — where does the bad value originate? Keep tracing upstream until you find the source. The fix belongs at the source, not at the symptom.
+
+### Phase 2: Pattern Analysis
+
+1. Find working examples of similar code in the same codebase
+2. Compare against references — read reference implementations completely
+3. Identify EVERY difference between working and broken, however small
+4. Map dependencies: other components, settings, config, environment, implicit assumptions
+
+### Phase 3: Hypothesis and Testing
+
+Apply the scientific method:
+1. Form a SINGLE hypothesis: "I believe X is the root cause because Y"
+2. Design the smallest possible test to validate (one variable at a time)
+3. Run the test and record the result
+4. If hypothesis confirmed → proceed to report
+5. If hypothesis rejected → form a NEW hypothesis. Do NOT pile on more guesses.
+6. If you don't know, say so — uncertainty is better than false confidence
+
+### Phase 4: Root-Cause Analysis Report
+
+Write your findings to a report file. Default location: `bug-investigation-report.md` in the current directory, or a path specified by the user.
+
+## DP-5: Debug Escalation (3+ Failed Hypotheses)
+
+If you test 3+ hypotheses and all fail, STOP. This pattern indicates an architectural problem, not a localized bug.
+
+**Signals of architectural issues:**
+- Each fix reveals new problems elsewhere
+- The "bug" moves around when you patch symptoms
+- Multiple unrelated symptoms share a timeline
+
+**Action:** Document the escalation in your report. Clearly state: "3+ hypotheses tested and rejected — this is likely an architectural issue, not a localized bug." Recommend architectural review before further fix attempts.
+
+## Red Flags — Return to Phase 1
+
+If you catch yourself thinking any of these, STOP and return to Phase 1:
+
+- "It's probably X, let me just check that"
+- "I don't fully understand but this might be it"
+- "Quick fix first, investigate later"
+- "Let me just try changing X"
+- Proposing a cause before tracing the data flow
+- Declaring root cause based on pattern matching alone without evidence
+
+## Report Format
+
+Write the investigation report with this structure:
+
+```markdown
+# Bug Investigation Report
+
+## Summary
+[One-paragraph description of the bug and investigation outcome]
+
+## Symptom
+- **What happens:** [Exact observed behavior]
+- **Expected behavior:** [What should happen]
+- **Reproduction:** [Exact steps, commands, or conditions]
+- **Frequency:** [Always / intermittent / specific conditions]
+
+## Investigation Trail
+[Chronological record of what you investigated, in order]
+
+### Phase 1: Root Cause Investigation
+- Error messages analyzed: [details]
+- Recent changes checked: [git log summary, relevant commits]
+- Data flow traced: [path from symptom to source]
+- Component boundaries tested: [if applicable]
+
+### Phase 2: Pattern Analysis
+- Working examples found: [file references]
+- Key differences identified: [list]
+
+### Phase 3: Hypotheses Tested
+| # | Hypothesis | Test | Result |
+|---|-----------|------|--------|
+| 1 | [hypothesis] | [what you did] | Confirmed / Rejected |
+| 2 | ... | ... | ... |
+
+## Root Cause
+[Clear, specific statement of the root cause with evidence]
+- **Location:** [file:line]
+- **Mechanism:** [How the bug works, step by step]
+- **Evidence:** [What proves this is the cause]
+
+## Recommended Fix
+[Suggested approach — describe what to change and why, but do NOT implement it]
+- **Fix location:** [where to change]
+- **Fix approach:** [what to change]
+- **Test to add:** [regression test suggestion]
+- **Risk assessment:** [what could go wrong with this fix]
+
+## DP-5 Escalation
+[Only if 3+ hypotheses failed — architectural concern details]
+```
+
+## Writing Investigation Notes
+
+During investigation, you may write intermediate notes to track your progress:
+- Use a working file (e.g., `investigation-notes.md`) for scratch work
+- Record each hypothesis, test, and result as you go
+- This protects against losing your train of thought on complex investigations
+- Clean up or consolidate into the final report when done
+
+## Quality Standards
+
+1. **Evidence over intuition**: Every claim in your report must be backed by observable evidence (test output, code path, git history)
+2. **Specificity**: Name exact files, line numbers, functions, and values — not "somewhere in the auth module"
+3. **Completeness**: Document what you ruled OUT, not just what you found. Negative results are valuable.
+4. **Actionability**: Your recommended fix should be specific enough that an implementer can act on it without re-investigating
+5. **Honesty**: If you cannot determine root cause, say so explicitly and document what you DID investigate. 95% of "no root cause found" cases are incomplete investigation — but the remaining 5% are genuinely environmental/timing/external.
+
+## Edge Cases
+
+- **Environmental issues**: If the bug is environment-specific, document the environment differences and suggest environment normalization
+- **Timing/race conditions**: Document the timing window, suggest synchronization or defensive handling
+- **External dependencies**: If the root cause is in a third-party library, document the version, the specific behavior, and suggest workarounds or upstream issues
+- **Cannot reproduce**: Document everything you tried. Suggest monitoring/instrumentation for the next occurrence. Do NOT guess at a cause you cannot verify.