workflow-orchestrator

Builder + Observer の同時並行チーム、コスト追跡、git worktree による並列実行、セキュリティゲート、インテリジェントなエージェントオーケストレーションを提供するデュアルチームプロジェクトワークフローシステムです。すべてのセッションでは 2 つのチームが稼働します。Builder は機能を高速にリリースし、Observer はドリフト、負債、スコープクリープを監視します。各チームには悪魔の代弁者（devil's advocate）の役割があります。セッション開始から終業までの開発ライフサイクル全体を、必須の 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 のもとで 2 つのチームが同時に稼働します:

              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 は速度を最適化します — worktree またはサブエージェント経由で機能をリリースします
• 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 クックブックにある既存のソリューションを確認する
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

⛔ ゲート: フェーズ 1 の前にアーキテクチャ Observer がコントラクトを承認する必要があります

フェーズ 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 が渡されます:

• スコープ境界（触れてよいものと触れてはいけないもの）
• コントラクトの参照
• 悪魔の代弁者の責務（サイクルごとに 1 人の Builder に対して）

フェーズ 2: オブザーバー監視（並行実行）

オブザーバーはビルダーと並行して 5〜10 分のループで実行されます:

1. ビルダーブランチから最新を取得する
2. 7 つのドリフト検出パターンを実行する（reference/observer-patterns.md を参照）
3. 検出結果を .claude/OBSERVER_QUALITY.md と .claude/OBSERVER_ARCH.md に書き込む
4. BLOCKER を .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

⛔ ゲート: すべてが合格し、かつアクティブなオブザーバー BLOCKER が存在しないこと

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. 体系的なテスト — 一度に 1 つの変数
4. 確認 — 修正をコミットする前に根本原因を特定する

重要なルール

• ❌ 行きがけの修正は禁止 — コミットする前に WHY を説明する
• ❌ 推測は禁止 — すべてを検証する
• ✅ すべてのツールを使用する: MCP サーバー、Web 検索、拡張思考
• ✅ 一度に 1 つの変数

詳細解説: 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-capability-matrix-skill	—

ネイティブエージェントチーム（実験的）

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

機能: DAG タスクシステム、ピアツーピアメッセージング、TeammateIdle/TaskCompleted フック、共有タスクリスト、サブエージェント用の isolation: "worktree"。

詳細解説: 完全な 70 以上のエージェントカタログについては reference/agent-routing.md を参照

---

進捗の描画

ライブ UI スピナーには activeForm を指定した TaskCreate を使用します:

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	1日の開始 — コンテキストスキャン、Observer の起動、コスト状況
/build-feature <name>	機能開発 — コントラクト → ビルド → 観察 → 出荷
/end-day	1日の終了 — Observer レポート、セキュリティスイープ、コンテキスト保存
/quick-fix <issue>	デバッグ — 証拠 → 仮説 → 修正
/cost-check	日次/月次累計の支出と予算状況を表示

---

GTME の視点

このデュアルチームワークフローは、GTME の高度な能力を示しています。

1. プロセスエンジニアリング — 品質管理はライフサイクルに組み込まれており、後付けではありません
2. 並列オーケストレーション — 異なる目的を持つチームを同時に管理します
3. 敵対的思考 — 悪魔の代弁者が「ハッピーパスだけ」の罠を防ぎます
4. コスト意識 — Observer はより安価なモデルを使用します。ユニットエコノミクスの考え方
5. 測定可能な成果 — Observer レポートは負債、カバレッジ、コンプライアンスを定量化します

ポートフォリオ価値: エンジニアリングの規律 + プロセスの考え方 + コスト最適化を示す、監査可能な成果物を生成します。

結果サイドカーの出力

最終ステップとして、~/.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」を使用してください。