@xulthekl/team-flow 0.22.4 → 0.24.0

package/gemini-extension.json

@@ -1,6 +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",
+  "version": "0.24.0",
   "contextFileName": "GEMINI.md"
 }

package/hooks/pre-tool-use-guard

@@ -1,12 +1,12 @@
 #!/usr/bin/env bash
 #
-# pre-tool-use-guard — spec-superflow implementation-edit state guard (PreToolUse)
+# pre-tool-use-guard — team-flow 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
+# team-flow 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).
@@ -15,8 +15,8 @@
 # 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).
+#      `.team-flow.yaml`.
+#        - Not found  -> ALLOW (no active team-flow 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
@@ -73,13 +73,13 @@ case "$TOOL_NAME" in
   *) allow ;;                  # anything else — allow
 esac
 
-# --- locate .spec-superflow.yaml (cwd + max 3 parent levels) ---------------
+# --- locate .team-flow.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"
+  if [ -f "$dir/.team-flow.yaml" ]; then
+    yaml="$dir/.team-flow.yaml"
     break
   fi
   [ "$dir" = "/" ] && break          # reached filesystem root
@@ -87,7 +87,7 @@ while [ "$i" -le 3 ]; do
   i=$((i + 1))
 done
 
-# No active spec-superflow change in scope -> allow.
+# No active team-flow change in scope -> allow.
 [ -n "$yaml" ] || allow
 [ -r "$yaml" ] || allow
 
@@ -107,7 +107,7 @@ case "$state" in
     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."
+    reason="team-flow 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 /team-flow:workflow-start). If no change is actually active, remove or fix the stray .team-flow.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"

package/hooks/session-start

@@ -1,6 +1,6 @@
 #!/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>"
+# v0.24.0: conditional injection — detects artifacts, injects workflow-start pointer
+msg="<EXTREMELY_IMPORTANT>\nYou have team-flow installed. Use /team-flow:workflow-start ONLY when you detect an active team-flow change in the workspace (look for \`.team-flow.yaml\`, \`proposal.md\`, \`execution-contract.md\`, or \`specs/\` directories), OR when the user explicitly invokes it by name. For ordinary coding tasks without team-flow 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

package/llms.txt

@@ -3,7 +3,7 @@
 ## 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.
+Current version: v0.24.0.
 
 ## Key Documents
 - README.md: Chinese homepage with full usage guide and FAQ

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xulthekl/team-flow",
-  "version": "0.22.4",
+  "version": "0.24.0",
   "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",

package/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "team-flow",
-  "version": "0.22.4",
+  "version": "0.24.0",
   "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"

package/scripts/guard/checks/arch-design.mjs

@@ -0,0 +1,79 @@
+// scripts/guard/checks/arch-design.mjs — architecture-design artifacts guard
+// v0.23.0 §30: 架构设计门控——exploring:specifying 增加 arch 维度
+//
+// 规则：
+// - arch_design_decision == "required" → architecture/*.md 必须存在且非空
+// - arch_design_decision == "skipped" → arch_design_reason 非空（advisory，不阻断）
+// - arch_design_decision == null → 未执行 architecture-design，不阻断（向后兼容）
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * 从 .team-flow.yaml 提取顶层字段值（简单正则，与 state-loader 兼容）
+ */
+function extractYamlField(content, field) {
+  for (const line of content.split('\n')) {
+    const match = line.match(new RegExp(`^${field}:\\s*(.*)`));
+    if (match) {
+      const val = match[1].trim();
+      return val === 'null' || val === '' ? null : val;
+    }
+  }
+  return null;
+}
+
+/**
+ * Check architecture-design artifacts for the exploring:specifying transition.
+ *
+ * @param {string} changeDir - change directory path
+ * @returns {{ pass: boolean, failures: string[] }}
+ */
+export function checkArchDesign(changeDir) {
+  const failures = [];
+  const stateFile = path.join(changeDir, '.team-flow.yaml');
+
+  // 无状态文件 → 不阻断（向后兼容存量 change）
+  if (!fs.existsSync(stateFile)) {
+    return { pass: true, failures: [] };
+  }
+
+  const raw = fs.readFileSync(stateFile, 'utf-8');
+  const decision = extractYamlField(raw, 'arch_design_decision');
+
+  // 未执行 architecture-design（null）→ 不阻断，向后兼容
+  if (!decision) {
+    return { pass: true, failures: [] };
+  }
+
+  // skipped → 检查 reason 非空（advisory，不阻断）
+  if (decision === 'skipped') {
+    const reason = extractYamlField(raw, 'arch_design_reason');
+    if (!reason) {
+      // advisory: 输出 warning 但不加入 failures
+      console.warn('  [WARN] arch-design: arch_design_decision=skipped but arch_design_reason is empty');
+    }
+    return { pass: true, failures: [] };
+  }
+
+  // required → 检查 architecture/*.md 存在且非空
+  if (decision === 'required') {
+    const archDir = path.join(changeDir, 'architecture');
+    if (!fs.existsSync(archDir)) {
+      failures.push('architecture/: directory missing (arch_design_decision=required)');
+      return { pass: false, failures };
+    }
+
+    const requiredFiles = ['architecture.md', 'database.md', 'api.md'];
+    for (const f of requiredFiles) {
+      const fp = path.join(archDir, f);
+      if (!fs.existsSync(fp)) {
+        failures.push(`architecture/${f}: missing (arch_design_decision=required)`);
+      } else if (fs.readFileSync(fp, 'utf-8').trim().length === 0) {
+        failures.push(`architecture/${f}: empty (arch_design_decision=required)`);
+      }
+    }
+  }
+
+  return { pass: failures.length === 0, failures };
+}

package/scripts/guard/checks/compound-captured.mjs

@@ -0,0 +1,70 @@
+// scripts/guard/checks/compound-captured.mjs — compound engineering capture guard
+// v0.24.0: 复利贯穿强制化——executing:closing 增加 compound-captured 维度
+//
+// 规则：
+// - learnings.md 存在且非空 → pass（已记录经验）
+// - compound_skipped === true → pass（显式豁免，用户主动跳过）
+// - workflow === 'tweak' → 不进入本检查器（由 WORKFLOW_TRANSITION_CHECKS 豁免）
+// - 其他情况 → fail（提示用户执行 tf solutions capture 或显式 skip）
+//
+// 设计原则：
+// - 与 arch-design 检查器同属"产物存在性"维度，不涉及内容质量评审
+// - 只检查 learnings.md 存在，不验证 frontmatter 格式（advisory 由 ce-compound 保证）
+// - 显式 skip 必须通过 state 字段（`tf state set compound_skipped true`），防止遗忘
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * 从 .team-flow.yaml 提取顶层字段值（与 arch-design.mjs 同源模式）
+ */
+function extractYamlField(content, field) {
+  for (const line of content.split('\n')) {
+    const match = line.match(new RegExp(`^${field}:\\s*(.*)`));
+    if (match) {
+      const val = match[1].trim();
+      return val === 'null' || val === '' ? null : val;
+    }
+  }
+  return null;
+}
+
+/**
+ * Check compound engineering capture for the executing:closing transition.
+ *
+ * @param {string} changeDir - change directory path
+ * @returns {{ pass: boolean, failures: string[] }}
+ */
+export function checkCompoundCaptured(changeDir) {
+  const failures = [];
+
+  // 1. 检查 learnings.md 存在且非空
+  const learningsPath = path.join(changeDir, 'learnings.md');
+  if (fs.existsSync(learningsPath)) {
+    const content = fs.readFileSync(learningsPath, 'utf-8').trim();
+    if (content.length > 0) {
+      return { pass: true, failures: [] };
+    }
+    // 文件存在但为空，视为未捕获
+    failures.push('learnings.md exists but is empty — run `tf solutions capture` or populate with session learnings');
+    return { pass: false, failures };
+  }
+
+  // 2. 检查显式豁免（compound_skipped === true）
+  const stateFile = path.join(changeDir, '.team-flow.yaml');
+  if (fs.existsSync(stateFile)) {
+    const raw = fs.readFileSync(stateFile, 'utf-8');
+    const skipped = extractYamlField(raw, 'compound_skipped');
+    if (skipped === 'true') {
+      return { pass: true, failures: [] };
+    }
+  }
+
+  // 3. 未捕获且未豁免 → fail
+  failures.push(
+    'Compound capture missing: no learnings.md found in change directory. ' +
+    'Run `tf solutions capture --phase review --domain <d> --type insight --severity medium --summary "..."` ' +
+    'to document session learnings, or `tf state set compound_skipped true` to explicitly skip.'
+  );
+  return { pass: false, failures };
+}

package/scripts/guard/guard.mjs

@@ -8,19 +8,21 @@ import { checkTestsPassing } from './checks/tests-passing.mjs';
 import { checkContractFresh } from './checks/contract-fresh.mjs';
 import { check as checkDpGate } from './checks/dp-gate-passed.mjs';
 import { checkSpecsMerged } from './checks/specs-merged.mjs';
+import { checkArchDesign } from './checks/arch-design.mjs';
 import { checkContractCurrent } from './checks/contract-current.mjs';
 import { checkDp3Approved } from './checks/dp3-approved.mjs';
 import { checkExecutionPlanReady } from './checks/execution-plan-ready.mjs';
 import { checkExecutionReviewsPassed } from './checks/execution-reviews-passed.mjs';
+import { checkCompoundCaptured } from './checks/compound-captured.mjs';
 
 // Transition matrix: <from>:<to> → required check dimensions
 const TRANSITION_CHECKS = {
   // Forward transitions
-  'exploring:specifying':           ['artifacts-exist'],
+  'exploring:specifying':           ['artifacts-exist', 'arch-design'],
   'specifying:bridging':            ['artifacts-exist', 'schema-valid'],
   'bridging:approved-for-build':    ['artifacts-exist', 'schema-valid', 'contract-fresh', 'dp-gate-passed'],
   'approved-for-build:executing':   ['artifacts-exist', 'contract-fresh', 'dp-gate-passed', 'execution-plan-ready'],
-  'executing:closing':              ['tasks-complete', 'tests-passing', 'specs-merged', 'execution-plan-ready', 'execution-reviews-passed'],
+  'executing:closing':              ['tasks-complete', 'tests-passing', 'specs-merged', 'execution-plan-ready', 'execution-reviews-passed', 'compound-captured'],
 
   // Debugging side-path
   'executing:debugging':            [],
@@ -163,6 +165,8 @@ async function main() {
     'dp3-approved': (dir) => checkDp3Approved(dir),
     'execution-plan-ready': (dir) => checkExecutionPlanReady(dir),
     'execution-reviews-passed': (dir) => checkExecutionReviewsPassed(dir),
+    'arch-design': (dir) => checkArchDesign(dir),
+    'compound-captured': (dir) => checkCompoundCaptured(dir),
   };
 
   const checks = [];