@xulthekl/team-flow 0.22.4

package/docs/README_en.md

@@ -0,0 +1,358 @@
+<h1 align="center">team-flow</h1>
+
+<p align="center">
+  <strong>A self-contained AI coding workflow plugin fusing OpenSpec planning + Superpowers execution discipline</strong>
+</p>
+
+<p align="center">
+  <a href="../LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="MIT License"></a>
+  <a href="https://github.com/MageByte-Zero/team-flow/stargazers"><img src="https://img.shields.io/github/stars/MageByte-Zero/team-flow" alt="GitHub Stars"></a>
+  <a href="https://www.npmjs.com/package/team-flow"><img src="https://img.shields.io/npm/v/team-flow" alt="npm version"></a>
+</p>
+
+<p align="center">
+  <a href="#quick-start">Quick Start</a> |
+  <a href="#installation">Install</a> |
+  <a href="#why">Why</a> |
+  <a href="#core-skills">Skills</a> |
+  <a href="#workflow">Workflow</a> |
+  <a href="../README.md">中文</a> |
+  <a href="showcase.html">Showcase</a> |
+  <a href="#faq">FAQ</a>
+</p>
+
+---
+
+## Quick Start
+
+Once installed, just tell your agent:
+
+```
+use workflow-start to begin
+```
+
+The agent inspects your current artifacts, performs **content-level detection** (comparing proposal scope vs. contract intent lock, not just file timestamps), determines your workflow stage, and routes to the correct next skill.
+
+- New change → `use workflow-start to begin`
+- Resume work → `continue the workflow`
+- Unsure → `check what state we're in`
+
+## Installation
+
+### Claude Code (Marketplace)
+
+Claude Code's primary installation path is the plugin marketplace:
+
+```bash
+/plugin marketplace add MageByte-Zero/team-flow
+/plugin install team-flow@team-flow
+/plugin update team-flow@team-flow   # upgrade
+```
+
+### Cursor (Skills directories / GitHub import)
+
+```bash
+npx team-flow@latest install-cursor
+
+# Or run the installer directly:
+curl -fsSL https://raw.githubusercontent.com/MageByte-Zero/team-flow/main/scripts/install-cursor.mjs | node -
+```
+
+Cursor discovers `.cursor/skills/`, `.agents/skills/`, `~/.cursor/skills/`, and compatible Claude/Codex skill directories. You can also import a GitHub repo from Customize → Rules → Remote Rule (Github).
+
+### OpenAI Codex CLI / App
+
+Codex uses the Plugin Directory / marketplace model. This repo ships `.codex-plugin/plugin.json` and `.agents/plugins/marketplace.json`.
+
+```bash
+codex
+/plugins
+
+# Or add the community marketplace and install:
+codex plugin marketplace add hashgraph-online/awesome-codex-plugins
+codex plugin add team-flow@team-flow
+```
+
+In the Codex app, open **Plugins** and install or enable `team-flow`. If installed from the CLI, restart the app and enable it in the Plugins panel.
+
+### GitHub Copilot CLI
+
+```bash
+copilot plugin marketplace add MageByte-Zero/team-flow
+copilot plugin install team-flow@team-flow
+```
+
+### Gemini CLI
+
+```bash
+gemini extensions install https://github.com/MageByte-Zero/team-flow
+gemini extensions update team-flow   # upgrade
+```
+
+### OpenCode / WorkBuddy / Trae
+
+| Platform | Method | Status |
+|----------|--------|--------|
+| **OpenCode** | `.opencode/plugins/team-flow.js` or `.agents/skills -> skills/` | Entry provided |
+| **WorkBuddy** | `npx team-flow@latest install-workbuddy` | Installer provided |
+| **Trae IDE / TRAE Work** | `.trae/skills/`, `~/.trae/skills/`, or zip/.skill upload | Manual/import |
+
+> Full installation guide: [INSTALL.md](../INSTALL.md)
+
+### CLI Toolchain
+
+```bash
+npm install -g team-flow
+```
+
+| Command | Purpose |
+|---------|---------|
+| `tf list` | List all changes and status |
+| `tf validate <dir>` | Validate artifact completeness |
+| `tf doctor` | Health check (versions, hooks, skills, docs) |
+| `tf version <semver>` | Sync version across all manifests |
+| `tf state <sub> <dir>` | Manage `.team-flow.yaml` state file |
+| `tf inject <dir>` | Generate phase-guard artifacts; omit `--platforms` only when exactly one platform marker is detected |
+| `tf audit <dir>` | Generate decision-point audit report |
+| `tf checkpoint save <dir> --task <id> --next <text>` | Save a task-level recovery checkpoint |
+| `tf checkpoint list <dir>` | List checkpoints and stale status |
+| `tf checkpoint show <dir> <id>` | Show one recovery checkpoint |
+| `tf handoff create <dir> --type <type> ...` | Create a prototype/research/experiment handoff |
+| `tf handoff list <dir>` | List handoff lifecycle status |
+| `tf handoff finish <dir> <id>` | Validate a handoff result |
+| `tf handoff resolve <dir> <id> --decision <decision>` | Record an explicit handoff decision |
+| `tf install-cursor` | Deploy to `.cursor/` directory |
+| `tf install-workbuddy` | Deploy to WorkBuddy marketplace and enable skills |
+
+### Version
+
+- Current: `v0.22.4`
+- 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)
+- Changelog: [CHANGELOG.md](../CHANGELOG.md)
+
+`tf inject` examples:
+
+```bash
+tf inject changes/my-change --platforms cursor
+tf inject changes/my-change --platforms all
+```
+
+If `--platforms` is omitted, injection only proceeds when exactly one project marker is detected. Ambiguous projects must use `--platforms <platform>` or `--platforms all`.
+
+Session recovery and optional prototypes:
+
+```bash
+tf checkpoint save changes/my-change --task 1.1 --next "Run focused tests"
+tf checkpoint list changes/my-change
+tf handoff create changes/my-change --type research --objective "Compare approaches" --expected-output "Recommendation" --acceptance "Evidence recorded"
+```
+
+Prototype work starts only after explicit user confirmation. Backend, CLI,
+configuration, and internal-refactor work does not enter the prototype route
+automatically. Handoff results never edit `design.md` or `tasks.md` automatically.
+
+Canonical delta specs live at `specs/<capability>/spec.md`; flat `specs/<capability>.md` and root-level `specs/spec.md` are not valid canonical paths.
+
+---
+
+## Why
+
+AI coding sessions fail in one of two ways:
+
+- **The AI starts coding before you've decided what to build.** You say "add authorization" and it touches 40 files before you realize — RBAC or ABAC?
+
+- **The plan is solid, but execution drifts.** The proposal, specs, and design are written, but nobody enforces testing, nobody gates reviews, and by merge time the behavior doesn't match.
+
+**team-flow builds a hard wall between these two failure points:** intent exploration → formal artifacts (Schema-validated) → execution contract bridge → TDD + SDD + Review Gate enforcement → verified closure → delta spec sync to prevent spec rot.
+
+| Principle | Meaning |
+|---|---|
+| Spec First | No stable planning artifacts → implementation blocked |
+| Guarded Handoff | `execution-contract.md` is the only bridge to implementation |
+| Strong Guardrails | Contract violations intercepted and rolled back |
+| Schema Validated | Planning artifacts validated by embedded engine |
+| Execute Disciplined | TDD Iron Law + SDD subagents + Review Gates |
+| Self-Contained | No external runtime dependencies |
+
+### When to Use
+
+**✅ Recommended:** Large features, multi-person collaboration, long-term maintenance, brownfield projects needing TDD + review gates.
+
+**❌ Skip:** One-off scripts, pure Q&A conversations.
+
+> **v0.6.0+ auto mode detection:** hotfix (≤2 files, minimal contract + DP-3 before execution) and tweak (≤4 files, config/docs only, skips planning + bridging) make lightweight changes efficient too.
+
+---
+
+## Core Skills
+
+| # | Skill | Stage | Purpose |
+|---|-------|-------|---------|
+| 1 | `workflow-start` | Entry | Content-level state detection, 8-state routing, blocks illegal transitions |
+| 2 | `need-explorer` | Exploring | One question at a time, approach comparison, recommendation |
+| 3 | `spec-writer` | Specifying | Generate proposal/specs/design/tasks with Schema engine validation |
+| 4 | `contract-builder` | Bridging | Parse 4 artifacts → compress into execution-contract.md |
+| 5 | `build-executor` | Executing | TDD Iron Law + SDD subagent-driven + Review Gates |
+| 6 | `bug-investigator` | Debugging | 4-phase root cause analysis; 3+ failures → escalate |
+| 7 | `code-reviewer` | Review | Structured review with 3-level severity classification |
+| 8 | `release-archivist` | Closing | Verification-before-completion + archive + risk summary |
+| 9 | `spec-merger` | Syncing | Delta spec → main spec merge with conflict detection |
+
+---
+
+## Workflow
+
+```text
+You: "add authorization to the API"
+       │
+       ▼
+   workflow-start     ← Single entry. Content-level detection, routes to correct skill
+       │
+       ▼
+   exploring          need-explorer: "RBAC or ABAC? What granularity?"
+       ▼
+   specifying         spec-writer generates 4 artifacts + Schema validation
+       ▼
+   bridging           contract-builder auto-extracts → execution-contract.md
+       │
+  ◇ User Approval ◇   ← The only human gate
+       │
+       ▼
+   executing          build-executor: TDD → SDD → Review Gate
+       │
+       ├──[bug]──→ debugging  → bug-investigator
+       ▼
+   closing            release-archivist: verify + archive
+       ▼
+   syncing            spec-merger (delta specs → main specs)
+```
+
+**Hard constraints:** No `execution-contract.md` or no approval → implementation blocked. Requirements change mid-execution → forced rollback. Bug encountered → must enter debugging state, no ad-hoc fixes.
+
+### Guarded execution plans
+
+For full/hotfix, DP-4 is a persisted, current execution plan at
+`<change>/.superpowers/sdd/execution-plan.json`, rather than an arbitrary text
+field or content stored in `execution-contract.md`. Run `tf execution recommend`
+first: it lists `inline`, `batch-inline`, and `sdd` from task count and wave
+strategy, with auditable reasons, and saves a recommendation receipt at
+`<change>/.superpowers/sdd/execution-recommendation.json`. The agent presents that recommendation and the
+user records a choice with `--confirm`; `plan` and `revise` require a receipt matching the current
+artifacts, contract, and waves. A non-recommended choice also requires
+`--acknowledge-recommendation`. Batch Inline remains serial and never claims
+parallel work.
+`tweak` is exempt from this execution-plan and 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
+# Retains/upgrades an existing plan as sdd; it can replan waves and dependencies,
+# creates a new revision, and clears old review receipts. Downgrades are rejected.
+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
+```
+
+The `--report` path is resolved relative to `<change>` and must remain under
+`<change>/.superpowers/sdd/reviews/`. `--base` and `--head` must be real commits
+in the `<change>` Git worktree, and `base` must be an ancestor of `head`.
+The `<change>/.superpowers/sdd/reviews/` directory hierarchy must be physical,
+non-symlink directories. The report itself must be a regular, non-empty,
+non-symlink file.
+
+Every planned wave needs a current `pass` review receipt before dependent
+waves or closing may proceed; revising a plan invalidates earlier receipts.
+The recovery, switching, and manual-save slash commands proposed in #47 are
+not implemented, so this documentation does not claim `/tf:*` commands.
+
+### Fast Paths (hotfix / tweak)
+
+- **hotfix** — ≤2 files, no new modules → `exploring -> bridging -> approved-for-build -> executing`. It may skip full planning artifacts such as `proposal.md`, `design.md`, `tasks.md`, and `specs/`, but it still requires a fresh minimal `execution-contract.md` plus DP-3 approval before implementation
+- **tweak** — ≤4 files, config/docs only → skip planning + bridging, direct edit
+
+---
+
+## Model Profiles (Optional Configuration)
+
+Configure platform model IDs for execution roles in the project-root `team-flow.config.json`:
+
+```json
+{
+  "models": {
+    "mechanical": "vendor-small",
+    "standard": "vendor-standard",
+    "strong": "vendor-strong",
+    "review": "vendor-review"
+  }
+}
+```
+
+| Profile | Role |
+|---|---|
+| `mechanical` | Low-cost, routine edits |
+| `standard` | Integration and judgment work |
+| `strong` | Architecture, design, and final review |
+| `review` | Code review that matches the diff |
+
+Resolve a profile in read-only mode:
+
+```bash
+tf config --resolve-model mechanical
+```
+
+This command only resolves local configuration, does not call platform APIs, and does not switch models in the current session. The controller explicitly passes the returned model ID only to platforms whose dispatch supports a `model` field. A `configured: false` result means automatic selection is unavailable: never invent a provider model and continue to meet the existing explicit `model` requirement.
+
+---
+
+## FAQ
+
+<details>
+<summary><strong>How is this different from OpenSpec or Superpowers?</strong></summary>
+
+team-flow is a source-level fusion, not side-by-side installation. It absorbs OpenSpec's Schema/validation/parsing engine and Superpowers' TDD/SDD/debugging/review discipline, while adding a unique contract-builder bridge layer and 8-state routing. Self-contained — no upstream runtimes needed.
+
+</details>
+
+<details>
+<summary><strong>Can I use this alongside existing OpenSpec or Superpowers?</strong></summary>
+
+Not recommended in the same session. Projects with existing OpenSpec artifacts can be adopted directly — `contract-builder` reads your existing proposal/specs/design/tasks to generate the execution contract.
+
+</details>
+
+<details>
+<summary><strong>How does the execution contract detect staleness?</strong></summary>
+
+Content-level detection, not timestamps: proposal scope changed, approved spec behavior changed, design constraints changed, or task batches changed → contract marked stale → route back to `contract-builder`.
+
+</details>
+
+<details>
+<summary><strong>How does SDD (Subagent-Driven Development) work?</strong></summary>
+
+For full/hotfix, `tf execution recommend` first presents Inline, Batch Inline,
+and SDD with evidence from the change, then recommends one. The user confirms a
+selection with `--confirm`; a different selection requires
+`--acknowledge-recommendation`. The saved execution plan at
+`<change>/.superpowers/sdd/execution-plan.json` names waves, dependencies, and
+strategies before dispatching implementers. Each wave gets a review report and a
+`pass`/`fail` receipt. Batch Inline remains serial, and the progress ledger
+prevents session-compression loss.
+
+</details>
+
+---
+
+**Star the repo — find it when you need it.**

package/docs/artifact-contract.md

@@ -0,0 +1,96 @@
+# Artifact Contract
+
+`team-flow` uses five primary artifacts in each change:
+
+1. `proposal.md`
+2. `specs/`
+3. `design.md`
+4. `tasks.md`
+5. `execution-contract.md`
+
+The first four are planning artifacts. The fifth is the execution handshake.
+
+## Artifact Roles
+
+### `proposal.md`
+
+Defines:
+
+- why the change exists
+- what is in scope
+- what is explicitly out of scope
+- which capabilities are affected
+
+### `specs/`
+
+Defines:
+
+- required behavior
+- scenarios and acceptance conditions
+- behavioral edges the implementation must respect
+
+### `design.md`
+
+Defines:
+
+- architecture and component boundaries
+- interface and dependency decisions
+- trade-offs and risk areas
+
+### `tasks.md`
+
+Defines:
+
+- implementation ordering
+- dependency-aware work breakdown
+- completion units that become named execution waves in the execution plan
+
+### `execution-contract.md`
+
+Defines:
+
+- the approved intent lock
+- the approved behavior summary
+- implementation constraints
+- the instructions for the execution plan and named execution waves
+- test obligations
+- review gates and their review receipts
+- escalation rules
+
+For full/hotfix, `tf execution recommend` lists applicable execution modes and
+recommends one from task count and wave strategy, and persists a recommendation
+receipt at `<change>/.superpowers/sdd/execution-recommendation.json`. `plan`
+and `revise` require the receipt to match the current artifacts, contract, and
+waves. The user confirms the selected mode with `--confirm`; a non-recommended mode additionally requires
+`--acknowledge-recommendation`. Batch Inline remains serial. After approval,
+`tf execution plan` writes
+the persisted execution plan to `<change>/.superpowers/sdd/execution-plan.json`.
+That JSON records each wave's dependencies and parallel/serial strategy; it is
+not stored in `execution-contract.md`. A current `pass` review receipt is
+required for every wave before dependent work or closing proceeds. `tweak` is
+exempt from execution-plan and review-receipt gates. `tf execution revise`
+retains or upgrades an existing plan as `sdd`, requires fresh confirmation,
+creates a new revision, and
+clears prior review receipts; it never permits a downgrade. #47 slash commands for recovery,
+switching, and manual save are not implemented, so `/tf:*` commands must not
+be claimed.
+
+## Mapping
+
+`team-flow` converts planning artifacts into execution inputs:
+
+- `proposal.md` -> intent lock and scope fence
+- `specs/` -> test obligations and acceptance checks
+- `design.md` -> implementation constraints
+- `tasks.md` -> execution-plan waves in `<change>/.superpowers/sdd/execution-plan.json`
+
+## Guardrail
+
+Implementation starts only after:
+
+- planning artifacts exist
+- `execution-contract.md` exists
+- the user approves the execution contract
+- full/hotfix have a current `tf execution plan` with a user-confirmed mode and
+  persisted recommendation evidence
+- every completed wave records a current `pass` review receipt before closing

package/docs/decision-points.md

@@ -0,0 +1,88 @@
+# Decision Points Protocol
+
+本文档集中定义了 team-flow 工作流中所有需要用户明确确认的决策点。每个决策点（Decision Point）都是工作流中的关键门禁，确保用户在自动化流程中始终保持最终决策权。工作流中的 skill 在到达决策点时必须暂停执行、向用户呈现所需信息，并等待明确指令后方可继续。
+
+## DP-0: 设计前确认（User Confirmation Gate）
+
+- **编号**：DP-0
+- **名称**：设计前确认
+- **触发条件**：`workflow-start` 检测到规划工件不存在或不完整，准备路由到 `spec-writer` 之前
+- **所需输入**：变更名称与意图、已知约束（命名风格、兼容性、受影响平台）、是否包含相关优化、用户沟通偏好
+- **预期输出**：用户确认关键决策，或提出修改意见；`workflow-start` 将确认结果写入 `.team-flow.yaml` 的 `dp_0_*` 字段
+- **关联 skill**：`team-flow:workflow-start`
+
+## DP-1: 需求确认
+
+- **编号**：DP-1
+- **名称**：需求确认
+- **触发条件**：need-explorer 完成需求澄清与范围界定之前，用户需要确认最终的 scope 和 capabilities
+- **所需输入**：need-explorer 整理的需求摘要、变更范围（scope）、能力清单（capabilities）、约束条件与成功标准
+- **预期输出**：用户明确确认需求范围和关键能力，或提出修改意见供 need-explorer 迭代
+- **关联 skill**：`team-flow:need-explorer`
+
+## DP-2: 工件审查
+
+- **编号**：DP-2
+- **名称**：工件审查
+- **触发条件**：spec-writer 完成全部规划工件的创建或更新后，用户需要审查产出的完整性和质量
+- **所需输入**：spec-writer 产出的 `proposal.md`、`specs/` 目录下的规格文档、`design.md` 设计文档、`tasks.md` 任务清单
+- **预期输出**：用户审查通过并批准全部工件，或指出需要修改的具体内容和方向
+- **关联 skill**：`team-flow:spec-writer`
+
+## DP-3: 契约批准
+
+- **编号**：DP-3
+- **名称**：契约批准
+- **触发条件**：contract-builder 完成 `execution-contract.md` 的生成后，用户必须明确批准该契约方可进入执行阶段（硬门禁，不可跳过）
+- **所需输入**：`execution-contract.md` 全文，包含执行批次、任务依赖、验收标准、回滚策略
+- **预期输出**：用户明确批准（approve）执行契约，或提出修改要求；未获批准前 build-executor 不得启动
+- **关联 skill**：`team-flow:contract-builder`
+
+## DP-4: 执行模式选择
+
+- **编号**：DP-4
+- **名称**：执行模式选择
+- **触发条件**：build-executor 启动执行前，用户需要选择本次执行的开发模式
+- **所需输入**：已批准的 `execution-contract.md`、项目测试基础设施现状、用户对 TDD（测试驱动开发）和 SDD（规格驱动开发）两种模式的说明
+- **预期输出**：用户明确选择 TDD 模式或 SDD 模式，build-executor 据此调整执行策略
+- **关联 skill**：`team-flow:build-executor`
+
+## DP-5: 调试升级
+
+- **编号**：DP-5
+- **名称**：调试升级
+- **触发条件**：bug-investigator 连续 3 次或更多修复尝试失败后，无法自动解决当前问题
+- **所需输入**：失败日志、每次修复尝试的具体方案与结果、错误根因分析、剩余可行方案（如有）
+- **预期输出**：用户决定继续调试（可附带方向指引）或放弃当前任务并标记为阻塞
+- **关联 skill**：`team-flow:bug-investigator`
+
+## DP-6: 验证失败
+
+- **编号**：DP-6
+- **名称**：验证失败
+- **触发条件**：release-archivist 在执行收尾验证时发现验证项未通过
+- **所需输入**：验证报告（包含通过项与失败项）、失败项的具体差异说明、原始规格要求与实际实现的对比
+- **预期输出**：用户决定返回修复失败项（重新进入执行阶段）或放弃验证直接关闭变更
+- **关联 skill**：`team-flow:release-archivist`
+
+## DP-7: 归档确认
+
+- **编号**：DP-7
+- **名称**：归档确认
+- **触发条件**：release-archivist 完成归档准备和 delta spec 合并方案后，用户确认最终归档操作
+- **所需输入**：变更总结报告、delta spec 合并方案（哪些增量规格将合并到主规格基线）、归档文件清单
+- **预期输出**：用户确认归档并批准 delta spec 合并，或要求调整合并范围后再执行
+- **关联 skill**：`team-flow:release-archivist`
+
+## 决策点与 Skill 映射总览
+
+| 编号 | 名称 | 关联 Skill | 阶段 |
+|------|------|------------|------|
+| DP-0 | 设计前确认 | `team-flow:workflow-start` | 入口 |
+| DP-1 | 需求确认 | `team-flow:need-explorer` | 探索 |
+| DP-2 | 工件审查 | `team-flow:spec-writer` | 规划 |
+| DP-3 | 契约批准 | `team-flow:contract-builder` | 桥接 |
+| DP-4 | 执行模式选择 | `team-flow:build-executor` | 执行 |
+| DP-5 | 调试升级 | `team-flow:bug-investigator` | 执行 |
+| DP-6 | 验证失败 | `team-flow:release-archivist` | 收尾 |
+| DP-7 | 归档确认 | `team-flow:release-archivist` | 收尾 |