@xulthekl/team-flow 0.22.4

package/docs/skill-rename-v0.8.0.md

@@ -0,0 +1,49 @@
+# Skill 重命名迁移指南（v0.8.0）
+
+v0.8.0 把 9 个 skill 的名字改为“动作 + 对象”风格，让入口和每个阶段的作用一目了然。旧名字不再保留 alias，因此升级后需要按下面的对照表使用新名字。
+
+## 名字对照表
+
+| 旧名称 | 新名称 | 阶段 | 作用 |
+|--------|--------|------|------|
+| `workflow-orchestrator` | `workflow-start` | 入口 | 工作流启动入口，检测状态并路由到下一个 skill |
+| `spec-explorer` | `need-explorer` | 探索 | 澄清需求、比较方案、确认范围 |
+| `spec-forger` | `spec-writer` | 规划 | 撰写 proposal、specs、design、tasks |
+| `bridge-contract` | `contract-builder` | 桥接 | 把规划工件压缩成 `execution-contract.md` |
+| `execution-governor` | `build-executor` | 执行 | 按契约实现代码，支持 Inline / Batch Inline / SDD |
+| `systematic-debugger` | `bug-investigator` | 调试 | 4 阶段根因调试 |
+| `code-reviewer` | `code-reviewer` | 审查 | 代码审查（未改名） |
+| `closure-archivist` | `release-archivist` | 收尾 | 验证、总结、归档 |
+| `spec-syncer` | `spec-merger` | 同步 | 把 delta spec 合并进主规格 |
+
+## 用户需要改什么
+
+### Claude Code
+
+- 触发入口从 `/workflow-orchestrator` 改为 `/workflow-start`。
+- 其他 skill 名称在路由时会自动被 `workflow-start` 引用，通常不需要手动输入。
+
+### Cursor
+
+- 重新运行 `node scripts/install-cursor.mjs`，把 skill 复制到 `.cursor/skills/`。
+- `.cursor/rules/phase-guard.mdc` 会同步更新。
+- `.cursor/` 是本地生成目录，不需要提交到仓库。
+
+### GitHub Copilot CLI
+
+- 通过 root `plugin.json` 重新加载插件。
+- `plugin.json` 中的 `skills` 字段指向 `skills/` 目录，目录重命名后无需手动修改 manifest，只需确保插件刷新。
+
+### Gemini CLI
+
+- 重新激活插件，读取更新后的 `GEMINI.md`。
+
+## 为什么重命名
+
+- **降低认知成本**：`workflow-start` 比 `workflow-orchestrator` 更直接地表达“这是入口”。
+- **动作 + 对象**：`spec-writer`、`contract-builder`、`bug-investigator` 等名字看到就知道职责。
+- **去掉生僻词**：`orchestrator`、`forger`、`archivist` 等词需要额外解释。
+
+## 兼容性
+
+v0.8.0 起旧 skill 名称不再可用。如果你在任何脚本、别名或个人笔记中引用了旧名字，请按上表替换。

package/docs/state-machine.md

@@ -0,0 +1,162 @@
+# State Machine
+
+`team-flow` treats workflow progression as explicit state transitions.
+
+## States
+
+### `exploring`
+
+- intent is still fuzzy
+- options are still being compared
+- no implementation is allowed
+- `need-explorer` is active
+
+### `specifying`
+
+- planning artifacts are being written or revised
+- proposal, specs, design, and tasks are refined
+- `spec-writer` is active
+- schema validation runs on every artifact generation
+
+### `bridging`
+
+- planning artifacts are translated into `execution-contract.md`
+- ambiguity is compressed into explicit approved decisions
+- `contract-builder` is active
+- parsing engine auto-extracts intent/scope/test-obligations/constraints/batches
+- hotfix also passes through this state with a fresh minimal contract and DP-3 approval before build
+
+### `approved-for-build`
+
+- the execution contract exists
+- the user has approved it
+- full/hotfix still require a current execution plan before implementation can begin
+
+### `executing`
+
+- implementation follows the execution contract
+- TDD, SDD (subagent-driven), review gates, and escalation rules apply
+- `build-executor` is active
+- `code-reviewer` invoked after each execution batch
+
+## Execution Plan Control Plane
+
+For full/hotfix, DP-4 is the persisted execution plan created by `tf execution
+plan` at `<change>/.superpowers/sdd/execution-plan.json`, not an arbitrary
+state value or content stored in `execution-contract.md`. Before planning, run
+`tf execution recommend`; it lists applicable `inline`, `batch-inline`, and
+`sdd` modes with evidence and one recommendation, and persists a receipt at
+`<change>/.superpowers/sdd/execution-recommendation.json`. `plan` and `revise`
+accept only a receipt whose artifacts, contract, and waves still match. The user must record the
+selected mode with `--confirm`; a non-recommended selection also requires
+`--acknowledge-recommendation`. Batch Inline remains serial and is never a
+substitute for parallel execution.
+`tweak` is exempt from execution-plan and review-receipt requirements.
+
+The plan names ordered execution waves, dependencies, and parallel/serial
+strategy. `tf execution show <change-dir> --json` reports which current waves
+are eligible. Each completed wave must have a current
+`pass` review receipt, recorded with `tf execution review`, before a dependent
+wave or `closing` can proceed. `tf execution revise` retains or upgrades an
+existing plan as `sdd`; that new revision requires a fresh confirmation (and
+acknowledgement when it differs from the new recommendation), invalidates old
+review receipts, and does not permit a downgrade. #47 recovery/switch/save
+slash commands are not implemented; do not assume `/tf:*` commands exist.
+
+### `debugging`
+
+- execution has hit a bug, test failure, or unexpected behavior
+- `bug-investigator` is active
+- 4-phase debugging (Root Cause → Pattern Analysis → Hypothesis → Implementation)
+- After debugging completes, returns to `executing`
+
+### `closing`
+
+- verification is complete with evidence
+- `release-archivist` is active
+- `verification-before-completion` gate enforced
+- `spec-merger` invoked if delta specs need merging into main specs
+- the change can be summarized, archived, or handed off
+
+### `abandoned`
+
+- the change has been abandoned by the user or after bug-investigator escalation
+- no delta spec merge is allowed
+- no further state transitions are allowed
+- delta specs are preserved for reference only
+
+## Terminal States
+
+- `closing` — successful completion with verification
+- `abandoned` — change abandoned (no delta spec merge, no further transitions allowed)
+
+## Recovery Overlays
+
+Checkpoints, handoffs, and prototypes are durable overlays, not workflow states.
+They do not add transitions to the state machine or change the meaning of the
+eight core states.
+
+- `tf checkpoint save <change-dir> --task <id> --next <text>` records task-level
+  recovery context under `.superpowers/sdd/checkpoints/`.
+- `tf handoff create <change-dir> --type <type> ...` creates explicit side-work
+  contracts under `.superpowers/sdd/handoffs/`.
+- `workflow-start` lists overlays before normal routing. `result-ready` handoffs
+  require explicit review and resolution before affected work resumes; stale
+  checkpoints remain historical evidence only.
+- Prototype work is optional and requires explicit user confirmation. Results
+  are reviewed manually and never mutate `design.md` or `tasks.md`.
+
+## Transitions
+
+```text
+  exploring ──── hotfix ─────────> bridging          (fast-path)
+  bridging  ──── hotfix ─────────> approved-for-build
+  exploring ──── tweak ──────────> approved-for-build (fast-path)
+
+  exploring -> specifying -> bridging -> approved-for-build -> executing -> closing
+                ^              ^             |                 ^    |
+                |              |             v                 |    |
+                |              |         debugging ────────────┘    |
+                |              |                                    |
+                |              +------------------------------------+
+                |              (contract drift → re-bridge)
+                +---------------------------------------------------+
+                     (scope change → re-specify)
+
+  (any non-terminal state) ──> abandoned
+                                (terminal, no further transitions)
+```
+
+## Mandatory Rewind
+
+The workflow must move back to `specifying` or `bridging` when:
+
+- new scope appears
+- a critical interface changes
+- a key design assumption is wrong
+- current artifacts no longer define the intended behavior
+- `execution-contract.md` intent lock no longer matches `proposal.md` scope
+- the execution plan is stale, its mode no longer matches state, or its waves
+  need different dependencies
+
+## Debugging State
+
+During `executing`, if a bug, test failure, or unexpected behavior blocks progress:
+
+1. Pause `executing` and enter `debugging`
+2. `bug-investigator` performs 4-phase root cause analysis
+3. If root cause found → fix (with TDD) → return to `executing`
+4. If 3+ fix attempts fail → question architecture → escalate to user
+
+## Anti-Pattern
+
+Do not stay in `executing` and "just adjust things in chat" when scope or behavior changes.
+
+If the contract changed, the artifacts changed.
+
+## Fast-Path Notes
+
+- `hotfix` follows `exploring -> bridging -> approved-for-build -> executing`.
+- `hotfix` may skip full planning artifacts such as `proposal.md`, `design.md`, `tasks.md`, and `specs/`.
+- `hotfix` still requires a fresh minimal `execution-contract.md` and explicit DP-3 approval before implementation.
+- `tweak` remains the only path that can jump directly from `exploring` to `approved-for-build`.

package/gemini-extension.json

@@ -0,0 +1,6 @@
+{
+  "name": "team-flow",
+  "description": "Unified workflow plugin: team-flow (spec-driven dev) + compound-engineering core subset + architecture-design (4A/DDD) + prototype (local HTML). 17 skills, one install.",
+  "version": "0.22.4",
+  "contextFileName": "GEMINI.md"
+}

package/hooks/hooks-cursor.json

@@ -0,0 +1,8 @@
+{
+  "hooks": [
+    {
+      "event": "sessionStart",
+      "command": "bash hooks/session-start"
+    }
+  ]
+}

package/hooks/hooks.json

@@ -0,0 +1,26 @@
+{
+  "description": "team-flow workflow hooks - session-start context injection + pre-tool-use implementation-edit state guard",
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/session-start\""
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/pre-tool-use-guard\""
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/pre-tool-use-guard

@@ -0,0 +1,116 @@
+#!/usr/bin/env bash
+#
+# pre-tool-use-guard — spec-superflow implementation-edit state guard (PreToolUse)
+#
+# ----------------------------------------------------------------------------
+# Purpose
+# ----------------------------------------------------------------------------
+# Blocks Write/Edit/MultiEdit implementation edits unless the active
+# spec-superflow change is in a state that permits building. This enforces the
+# state-machine rule that "no implementation is allowed" outside the
+# build-permitted states (exploring / specifying / bridging must finish and be
+# approved before any code is written).
+#
+# ----------------------------------------------------------------------------
+# Guard logic
+# ----------------------------------------------------------------------------
+#   1. Walk up from $PWD (current dir + max 3 parent levels) looking for
+#      `.spec-superflow.yaml`.
+#        - Not found  -> ALLOW (no active spec-superflow change in scope).
+#   2. Read the current workflow state from the `state:` line of the yaml.
+#   3. For Write/Edit/MultiEdit only:
+#        - state in {approved-for-build, executing, debugging} -> ALLOW
+#        - any other state (exploring/specifying/bridging/closing/abandoned/
+#          unknown) -> BLOCK with an explanatory reason.
+#   4. Any other tool -> ALLOW.
+#
+# ----------------------------------------------------------------------------
+# Defensive contract (IMPORTANT — read before editing)
+# ----------------------------------------------------------------------------
+# This hook must NEVER block the user because of a hook bug. On ANY error
+# (unreadable/unparseable yaml, unexpected stdin, missing binaries, a failed
+# command) it defaults to ALLOW: exit 0 with no output. Only an explicit,
+# successfully detected disallowed state may emit a block decision. The single
+# `printf` that prints a block is reachable ONLY after every parse step has
+# succeeded, so a failure anywhere upstream can never produce a false block.
+#
+# ----------------------------------------------------------------------------
+# I/O contract (Claude Code PreToolUse)
+# ----------------------------------------------------------------------------
+#   stdin : JSON with `tool_name` and `tool_input` (Write/Edit/MultiEdit carry
+#           `tool_input.file_path`).
+#   block : print {"decision":"block","reason":"..."} then exit 0.
+#   allow : print nothing, exit 0.
+#
+# ----------------------------------------------------------------------------
+# Design reference
+# ----------------------------------------------------------------------------
+#   docs/state-machine.md — state definitions + "no implementation is allowed"
+#   rule. Build-permitted states: approved-for-build, executing, debugging.
+#
+# Perf: pure bash + grep/sed (no node/python). Target < 50ms.
+
+# Master safety net: any unexpected failing command falls through to ALLOW.
+# We intentionally do NOT use `set -e`/`set -u`; an aborted script must never
+# be misread as a block. The trap only ever exits 0 (allow).
+trap 'exit 0' ERR
+
+allow() { exit 0; }
+
+# --- read tool invocation from stdin ---------------------------------------
+INPUT="$(cat 2>/dev/null)" || allow
+[ -n "$INPUT" ] || allow
+
+# --- only guard implementation-edit tools ----------------------------------
+# hooks.json already restricts the matcher to Write|Edit|MultiEdit; we re-check
+# defensively so a future broader matcher can never over-block other tools.
+TOOL_NAME="$(printf '%s' "$INPUT" \
+  | grep -o '"tool_name"[[:space:]]*:[[:space:]]*"[^"]*"' \
+  | head -1 \
+  | sed 's/.*:"//; s/"$//')"
+case "$TOOL_NAME" in
+  Write|Edit|MultiEdit) : ;;   # guarded tools — continue
+  *) allow ;;                  # anything else — allow
+esac
+
+# --- locate .spec-superflow.yaml (cwd + max 3 parent levels) ---------------
+dir="$PWD"
+yaml=""
+i=0
+while [ "$i" -le 3 ]; do
+  if [ -f "$dir/.spec-superflow.yaml" ]; then
+    yaml="$dir/.spec-superflow.yaml"
+    break
+  fi
+  [ "$dir" = "/" ] && break          # reached filesystem root
+  dir="$(dirname "$dir")"
+  i=$((i + 1))
+done
+
+# No active spec-superflow change in scope -> allow.
+[ -n "$yaml" ] || allow
+[ -r "$yaml" ] || allow
+
+# --- read current state ----------------------------------------------------
+# First `state:` line, e.g. `state: executing`. Strip leading/trailing
+# whitespace and any surrounding quotes.
+state="$(grep -E '^[[:space:]]*state:[[:space:]]*' "$yaml" 2>/dev/null \
+  | head -1 \
+  | sed -E 's/^[[:space:]]*state:[[:space:]]*//; s/[[:space:]]*$//; s/^["'\'']//; s/["'\'']$//')"
+
+# Could not determine state -> defensive allow (never block on parse failure).
+[ -n "$state" ] || allow
+
+# --- decision --------------------------------------------------------------
+case "$state" in
+  approved-for-build|executing|debugging)
+    allow
+    ;;
+  *)
+    reason="spec-superflow guard: implementation edits (Write/Edit/MultiEdit) are blocked while the change is in state '$state'. Edits are only allowed in states: approved-for-build, executing, debugging. Advance the workflow to an approved build state first (see docs/state-machine.md or /spec-superflow:workflow-start). If no change is actually active, remove or fix the stray .spec-superflow.yaml."
+    # Escape backslashes and double quotes for safe JSON string embedding.
+    reason_esc="$(printf '%s' "$reason" | sed 's/\\/\\\\/g; s/"/\\"/g')"
+    printf '{"decision":"block","reason":"%s"}\n' "$reason_esc"
+    exit 0
+    ;;
+esac

package/hooks/session-start

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+# v0.22.4: conditional injection — detects artifacts, injects workflow-start pointer
+msg="<EXTREMELY_IMPORTANT>\nYou have spec-superflow installed. Use /spec-superflow:workflow-start ONLY when you detect an active spec-superflow change in the workspace (look for \`.spec-superflow.yaml\`, \`proposal.md\`, \`execution-contract.md\`, or \`specs/\` directories), OR when the user explicitly invokes it by name. For ordinary coding tasks without spec-superflow artifacts, do NOT invoke workflow-start — just handle the request directly.\n</EXTREMELY_IMPORTANT>"
+
+# Three platforms share the same message, only output format differs.
+if [ -n "${CURSOR_PLUGIN_ROOT:-}" ]; then
+  printf '{\n  "additional_context": "%s"\n}\n' "$msg"
+elif [ -n "${CLAUDE_PLUGIN_ROOT:-}" ] && [ -z "${COPILOT_CLI:-}" ]; then
+  printf '{\n  "hookSpecificOutput": {\n    "hookEventName": "SessionStart",\n    "additionalContext": "%s"\n  }\n}\n' "$msg"
+else
+  printf '{\n  "additionalContext": "%s"\n}\n' "$msg"
+fi
+
+exit 0

package/llms.txt

@@ -0,0 +1,51 @@
+# spec-superflow
+
+## Overview
+spec-superflow is a self-contained workflow integration plugin for Claude Code, Cursor, OpenAI Codex CLI/App, GitHub Copilot CLI, Gemini CLI, OpenCode, WorkBuddy, and Trae. It merges spec-driven planning artifacts (proposal, specs, design, tasks) with disciplined execution guardrails (TDD, review gates, controlled handoff) into one unified workflow.
+
+Current version: v0.22.4.
+
+## Key Documents
+- README.md: Chinese homepage with full usage guide and FAQ
+- docs/README_en.md: English documentation
+- INSTALL.md: Multi-platform installation guide
+- docs/state-machine.md: Workflow state machine (exploring -> specifying -> bridging -> approved-for-build -> executing -> closing)
+- docs/artifact-contract.md: Artifact mapping from planning to execution contract
+- docs/decision-points.md: Standard decision-point protocol
+- CHANGELOG.md: Version history
+- CONTRIBUTING.md: Contribution guidelines
+
+## Core Skills (in skills/)
+- workflow-start: Entry point, content-level state detection, 8-state routing, blocks illegal transitions
+- need-explorer: Clarifies intent, scope, constraints, and success criteria
+- spec-writer: Generates proposal, specs, design, and tasks with Schema validation
+- contract-builder: Parses 4 artifacts and compresses into execution-contract.md
+- build-executor: Enforces TDD, SDD subagent execution, and Review Gates
+- bug-investigator: 4-phase root cause analysis, escalates after repeated failures
+- code-reviewer: Structured review with Critical / Important / Minor severity
+- release-archivist: Verification-before-completion, archiving, risk summary
+- spec-merger: Merges delta specs into main specs with conflict detection
+
+## Templates (in templates/)
+- proposal.md: Change proposal template
+- spec.md: Capability specification template
+- design.md: Technical design template
+- tasks.md: Implementation tasks template
+- execution-contract.md: Bridge artifact template
+
+## Examples (in docs/examples/)
+- add-dark-mode: New UI feature example (dark mode)
+- refactor-auth-boundary: Brownfield backend refactor example (auth layer)
+
+## Installation
+See INSTALL.md for platform-specific instructions. Quick install for Claude Code:
+```
+/plugin marketplace add MageByte-Zero/spec-superflow
+/plugin install spec-superflow@spec-superflow
+```
+
+Cursor: `npx spec-superflow@latest install-cursor`
+WorkBuddy: `npx spec-superflow@latest install-workbuddy`
+
+## Usage
+Start from workflow-start. The workflow inspects current artifacts and routes to the correct stage automatically.

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@xulthekl/team-flow",
+  "version": "0.22.4",
+  "description": "Unified plugin (23 skills + 8 agents) integrating team-flow, compound-engineering, architecture-design, prototype, design-system, workflow-orchestrator, workflow-bootstrap, e2e, session-handoff, workflow-feedback for multi-agent coding tools.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "tf": "./scripts/team-flow.mjs",
+    "team-flow": "./scripts/team-flow.mjs"
+  },
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "test": "node --test tests/e2e.test.mjs tests/lib/*.test.mjs",
+    "test:raw-mode": "node --test tests/lib/raw-mode-smoke.test.mjs",
+    "validate": "node scripts/validate-artifacts",
+    "version": "node scripts/team-flow.mjs version $npm_new_version && node scripts/check-version-consistency.mjs && git add -A",
+    "check-versions": "node scripts/check-version-consistency.mjs",
+    "setup-hooks": "node scripts/install-git-hooks.mjs"
+  },
+  "keywords": [
+    "spec-driven-development",
+    "tdd",
+    "workflow",
+    "skills",
+    "contract-driven",
+    "claude-code",
+    "cursor",
+    "trae",
+    "codex",
+    "gemini-cli",
+    "copilot-cli",
+    "opencode",
+    "workbuddy"
+  ],
+  "author": "xulthekl",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MageByte-Zero/team-flow"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "typescript": "^6.0.3"
+  }
+}

package/plugin.json

@@ -0,0 +1,27 @@
+{
+  "name": "team-flow",
+  "version": "0.22.4",
+  "description": "Unified workflow plugin: team-flow (spec-driven dev: TDD/SDD/code-review/debugging) + compound-engineering core subset (brainstorm/plan/compound/strategy/ideate/proof, global compounding) + architecture-design (4A+DDD incremental design & global compounding) + prototype (local HTML prototype, zero external deps) + e2e (Playwright E2E, AC-driven) + workflow-orchestrator (product-level workflow orchestration) + workflow-bootstrap (existing project onboarding) + session-handoff (context transfer) + workflow-feedback (issue tracking). 23 skills + 8 agents, one install.",
+  "author": {
+    "name": "LT"
+  },
+  "homepage": "https://github.com/LT/team-flow",
+  "repository": "https://github.com/LT/team-flow",
+  "license": "MIT",
+  "keywords": [
+    "workflow",
+    "skills",
+    "spec-driven-development",
+    "tdd",
+    "sdd",
+    "architecture",
+    "ddd",
+    "compound-engineering",
+    "prototype",
+    "claude-code",
+    "cursor",
+    "trae"
+  ],
+  "category": "Productivity",
+  "skills": "skills/"
+}