workflow-orchestrator

双团队项目工作流系统，提供 Builder + Observer 并行团队、成本跟踪、通过 git worktrees 并行执行、安全关卡和智能 Agent 编排。每个会话都会运行两个团队：Builder 快速交付功能，Observer 监控偏差、技术债和范围蔓延。每个团队都设有唱反调角色。系统管理从会话开始到每日收尾的完整开发生命周期，并要求生成 Observer 报告、执行安全扫描和保留上下文。

<quick_start> 开始会话：

pwd && git status && git log --oneline -5
cat PROJECT_CONTEXT.md 2>/dev/null

→ 自动启动 Observer 团队（不可妥协）

功能开发： 契约 → Builder 团队 → Observer 监控 → 安全关卡 → 发布

结束会话：

1. Observer 最终报告
2. 安全扫描：gitleaks detect --source .
3. 更新 PROJECT_CONTEXT.md
4. 将成本记录到 costs/daily-YYYY-MM-DD.json </quick_start>

<success_criteria> 满足以下条件即表示工作流成功：

• 会话开始时完成上下文扫描
• Observer 团队已启动并进行监控（不可妥协）
• 实现任何功能前先定义契约
• 阶段转换前检查 Observer BLOCKER 关卡
• 提交前通过安全扫描
• 更新成本跟踪（daily.json、mtd.json）
• 当天结束时生成 Observer 最终报告
• 会话结束时更新 PROJECT_CONTEXT.md
• 发布前通过所有安全关卡 </success_criteria>

• 会话管理：“start day”、“begin session”、“what's the status”、“end day”、“wrap up”、“done for today”
• 功能开发：“new feature”、“build”、“implement”
• 双团队：“dual team”、“observer team”、“builder team”、“spawn observers”、“devil's advocate”
• 调试：“debug”、“investigate”、“why is this broken”
• 研究：“research”、“evaluate”、“should we use”

---

双团队架构

Orchestrator 下的每个会话都会运行两个并行团队：

              ORCHESTRATOR
              ┌────┴────┐
        BUILDER TEAM   OBSERVER TEAM
        (ships fast)   (watches quality)
        ├ Lead Builder  ├ Code Quality (haiku)
        ├ Builder(s)    └ Architecture (sonnet)
        └ Devil's Adv.    └─ (Devil's Advocate)

Observer 团队不可妥协。 它始终运行，即使只是“很小”的改动也不例外。

• Builder 优先考虑速度——通过 worktrees 或子 Agent 发布功能
• Observer 优先考虑正确性——发现偏差、技术债、缺漏和范围蔓延
• 每个团队都设有唱反调角色，以避免群体思维和盲点

Observer 将发现记录到 .claude/OBSERVER_*.md，并标注严重级别：

• 🔴 BLOCKER — 停止工作，立即修复
• 🟡 WARNING — 合并前修复或记录
• 🔵 INFO — 待办事项

**深入了解：**参见 reference/dual-team-architecture.md

---

开始一天

启动前检查

git status --short | head -5
[ -f package.json ] && [ ! -d node_modules ] && echo "Run npm install"
[ -f requirements.txt ] && [ ! -d .venv ] && echo "Run pip install"
[ -f .env.example ] && [ ! -f .env ] && echo "Copy .env.example to .env"

上下文扫描（必需）

pwd && git status && git log --oneline -5
cat PROJECT_CONTEXT.md 2>/dev/null || echo "No context file"
cat CLAUDE.md 2>/dev/null
cat PLANNING.md 2>/dev/null

启动 Observer 团队（自动）

在站会的同时启动 Observer 团队：

• 代码质量 Observer（haiku）— 技术债、测试缺口、导入项
• 架构 Observer（sonnet）— 契约偏差、范围蔓延、设计违规

# Detect Native Agent Teams support
if [ "${CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS}" = "1" ]; then
  echo "Native Agent Teams enabled — using DAG task system"
  # Use TeamCreate + SendMessage for Observer coordination
else
  echo "Native Agent Teams not enabled — falling back to manual worktree spawn"
  # Use subagent-teams-skill Task tool pattern
fi

冲刺计划

在冲刺计划中加入 Observer BLOCKER 关卡——只要 .claude/OBSERVER_ALERTS.md 中存在未解决的 BLOCKER，就不得进行阶段转换。

输出格式

## Session Start: [PROJECT_NAME]
### Completed (Last Session)
- [x] Task 1
### In Progress
| Task | Branch/Worktree | Status |
|------|-----------------|--------|
| API endpoint | feature/api | 70% |
### Observer Status
- Team: ACTIVE (Code Quality + Architecture)
- Active blockers: 0
### Today's Priority Queue
1. [BUILDER] Feature implementation
2. [OBSERVER] Continuous monitoring
### Cost Context
- Today: $0.00 | MTD: $12.34 | Budget: $100

**深入了解：**参见 reference/start-day-protocol.md

---

研究阶段

**触发条件：**在开发涉及新框架、API 或架构决策的任何功能之前。

扫描 → 评估 → 决策

1. 检查你的代码仓库和 MCP cookbook 中的现有解决方案
2. 使用 research-skill 检查清单选择框架
3. 构建前进行成本预测
4. 创建 RESEARCH.md → FINDINGS.md，并提出 GO/NO-GO 建议

⛔ 关卡：继续前必须经过人工检查点

**深入了解：**参见 reference/research-workflow.md

---

功能开发

阶段 0：定义契约（编写代码前）

## Feature Contract: [NAME]
### Endpoints / Interfaces
- POST /api/widgets → { id, name, created_at }
### Scope Boundaries
- IN SCOPE: [list]
- OUT OF SCOPE: [list]
### Observer Checkpoints
- [ ] Architecture Observer approves contract
- [ ] Code Quality Observer runs after each merge

⛔ 关卡：架构 Observer 必须在阶段 1 开始前批准契约

阶段 1：启动 Builder 团队

# Option A: Worktree sessions (long tasks, 30+ min)
git worktree add -b feature/api ~/tmp/worktrees/$(basename $(pwd))/api
# Option B: Native Agent Teams (short tasks, <20 min)
# Use TeamCreate + Task tool subagents
# Option C: Hybrid — worktrees for Builders, Task tool for Observers

每位 Builder 都会收到一份 WORKTREE_TASK.md，其中包含：

• 范围边界（可以和不可以改动的内容）
• 契约参考
• 唱反调职责（每轮指定一位 Builder 承担）

阶段 2：观察者监控（并发）

观察者与构建者并行运行，每 5-10 分钟循环一次：

1. 从构建者分支拉取最新内容
2. 运行 7 种偏移检测模式（参见 reference/observer-patterns.md）
3. 将发现写入 .claude/OBSERVER_QUALITY.md 和 .claude/OBSERVER_ARCH.md
4. 将阻塞项上报至 .claude/OBSERVER_ALERTS.md

阶段 3：安全 + 质量门禁

# Security scans
semgrep --config auto .
gitleaks detect --source .
npm audit --audit-level=critical || pip-audit
pytest --cov=src || npm test -- --coverage

⛔ 门禁：必须全部通过，且没有活动的观察者阻塞项

gate = (
    sast_clean AND
    secrets_found == 0 AND
    critical_vulns == 0 AND
    test_coverage >= 80 AND
    observer_blockers == 0  # NEW: Observer gate
)

阶段 4：发布

git diff main...HEAD
git add . && git commit -m "feat: [description]"
git push
echo '{"feature": "X", "cost": 1.23}' >> costs/by-feature.jsonl

**深入了解：**参见 reference/feature-development.md

---

调试模式

**触发条件：**标准故障排查无效或问题复杂时。

收集证据 → 提出假设 → 测试 → 验证

1. 收集证据——准确的错误信息、复现步骤、预期结果与实际结果
2. 形成假设——提出 3 个以上假设，并为每个假设提供证据
3. 系统化测试——每次只更改一个变量
4. 验证——提交修复前确认根本原因

关键规则

• ❌ 禁止临时修补——提交前说明原因
• ❌ 禁止猜测——核实所有事项
• ✅ 使用所有工具：MCP 服务、网络搜索、扩展思考
• ✅ 每次只更改一个变量

**深入了解：**参见 reference/debug-methodology.md

---

结束一天

阶段 1：观察者最终报告（安全扫描前）

观察者生成最终报告：

• 所有发现的摘要（已解决 + 未解决）
• 指标：债务项、测试覆盖率变化、契约合规性
• 写入 .claude/OBSERVER_QUALITY.md 和 .claude/OBSERVER_ARCH.md

⛔ 门禁：继续之前先审阅观察者报告

阶段 2：安全扫描（必需）

gitleaks detect --source . --verbose
git log -p | grep -E "(password|secret|api.?key|token)" || echo "Clean"
npm audit --audit-level=critical 2>/dev/null || pip-audit 2>/dev/null

⛔ 门禁：提交任何更改前必须全部通过

阶段 3：上下文 + 指标 + 清理

## PROJECT_CONTEXT.md Update
### Completed This Session
- [x] Feature X
### Observer Summary
- Blockers resolved: N | Warnings logged: N | Debt delta: +/-N
### Tomorrow's Priorities
1. Next task

将观察者报告归档至 .claude/OBSERVER_HISTORY/，并为下一次会话重置。

# Cost tracking
echo '{"total": 0.47}' >> costs/daily-$(date +%Y-%m-%d).json
# Portfolio metrics
git diff --stat $(git log --since="today 00:00" --format="%H" | tail -1)..HEAD 2>/dev/null

**深入了解：**参见 reference/end-day-protocol.md

---

成本门禁

飞行前预算检查

COST_FILE=~/.claude/daily-cost.json
SPENT=$(jq '.spent' "$COST_FILE" 2>/dev/null || echo 0)
BUDGET=$(jq '.budget_monthly' "$COST_FILE" 2>/dev/null || echo 100)
echo "MTD: \$$SPENT / \$$BUDGET"

预算占比	操作
< 50%	正常继续
50-80%	发出成本警告，建议降级模型
80-95%	警告——继续前询问用户
> 95%	阻止——要求明确授权

**深入了解：**参见 reference/cost-tracking.md

---

回滚 / 恢复

• 暂存当前工作 → 找到最近一次已知正常状态 → 选择性回滚或完全还原 → 验证测试 → 调查根本原因
• 使用 debug-like-expert-skill 分析根本原因

**深入了解：**参见 reference/rollback-recovery.md

---

技能调用速查

需求	调用	模型
启动构建团队	agent-teams-skill 或使用 team_name 的 Task 工具	sonnet
启动观察者团队	在 START DAY 时自动启动，或使用 workflow-orchestrator	haiku/sonnet
调试失败的测试	debug-like-expert-skill	sonnet
审查代码质量	superpowers:requesting-code-review	sonnet
运行安全扫描	security-skill	sonnet
跟踪成本	cost-metering-skill	haiku
编写测试	testing-skill	sonnet
设计 API 契约	api-design-skill	sonnet
规划架构	planning-prompts-skill	opus
采集指标	portfolio-artifact-skill	haiku
并行构建（工作树）	agent-teams-skill	sonnet
并行构建（会话内）	subagent-teams-skill	sonnet
将任务映射至最佳 Agent	agent-capability-matrix-skill	—

原生 Agent 团队（实验性）

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
claude --worktree  # auto-creates worktree branch

功能：DAG 任务系统、点对点消息传递、TeammateIdle/TaskCompleted 钩子、共享任务列表，以及适用于子 Agent 的 isolation: "worktree"。

**深入了解：**完整的 70 多个 Agent 目录参见 reference/agent-routing.md

---

进度呈现

使用带有 activeForm 的 TaskCreate 显示实时 UI 加载动画：

TaskCreate({ subject: "Plan architecture", activeForm: "Planning architecture" })
TaskUpdate({ taskId: "1", status: "in_progress" })  // → live spinner
TaskUpdate({ taskId: "1", status: "completed" })     // → checkmark

使用 addBlockedBy 进行阶段排序。使用 Markdown 表格呈现摘要。

---

CLAUDE CODE 命令

命令	工作流
/start-day	开始一天 — 扫描上下文、启动 Observer、查看成本状态
/build-feature <name>	功能开发 — 契约 → 构建 → 观察 → 发布
/end-day	结束一天 — Observer 报告、安全检查、保存上下文
/quick-fix <issue>	调试 — 证据 → 假设 → 修复
/cost-check	显示每日和本月至今的支出及预算状态

---

GTME 视角

这种双团队工作流展示了先进的 GTME 能力：

1. 流程工程 — 将质量控制融入生命周期，而非事后补上
2. 并行编排 — 管理目标各异的并行团队
3. 对抗性思维 — 魔鬼代言人可避免“只有顺利路径”的陷阱
4. 成本意识 — Observer 使用成本更低的模型；注重单位经济效益
5. 可衡量的产出 — Observer 报告量化技术债务、覆盖率和合规性

作品集价值： 产出可审计的成果，展示工程纪律、流程思维和成本优化能力。

输出结果 Sidecar

最后一步，写入 ~/.claude/skill-analytics/last-outcome-workflow-orchestrator.json：

{"ts":"[UTC ISO8601]","skill":"workflow-orchestrator","version":"2.0.0","variant":"default",
 "status":"[success|partial|error]","runtime_ms":[estimated ms from start],
 "metrics":{"workflows_run":[n],"stages_completed":[n],"observers_spawned":[n]},
 "error":null,"session_id":"[YYYY-MM-DD]"}

如果某些阶段失败但仍产出了结果，请使用状态 "partial"。只有在没有生成任何输出时，才使用 "error"。