cxas-agent-foundry

Agent Foundry

GECX 会話エージェントのエンドツーエンドのライフサイクル：構築、テスト、デバッグ、反復。

ステップ追跡 — 必須（フェーズ 0、ブロッキング）

セットアップの実行、質問、ファイルのスキャフォールディングなど、どのような作業を始める前にも、関連するサブスキルのチェックリストを（そのままの内容で）<project>/todo.md に初期化してください。 チェックリストは契約であり、提案ではありません。現在のタスク用の todo.md が存在しない場合は、作業を進めず、まず作成してください。

長時間のデバッグや構築では、プレッシャーのもとで検証手順が省略されがちです（例：lint を実行せずにプッシュする、TDD なしでスキャフォールディングする、実際にはプッシュしていないのに「デプロイ済み」と報告する）。チェックリストは、こうした事態を防ぐためにあります。手順を省きたいという衝動が生じたときこそ、チェックリストが役立つ瞬間です。そのときに参照すべきであり、回避すべきではありません。

クイックリファレンス

# Lint: dispatch agents/lint-fixer.md sub-agent — DO NOT run `cxas lint` on the main thread.
# Lint output is verbose; keep it inside the sub-agent context.

# Push local files to platform (only after lint-fixer returns status: clean)
cxas push --app-dir <project>/cxas_app/<AppName> \
  --to projects/<project_id>/locations/<location>/apps/<app_id> \
  --project-id <project_id> --location <location>

# Pull platform state to local (use --version-id to export an immutable version snapshot instead of live draft)
cxas pull projects/<project_id>/locations/<location>/apps/<app_id> \
  --project-id <project_id> --location <location> --target-dir <project>/cxas_app/ \
  [--version-id <version_id_or_name>]

# Run evals + triage + report (single command)
python .agents/skills/cxas-agent-foundry/scripts/run-and-report.py --message "what changed" --runs 5

# Generate dynamic interactive HTML dashboard with Gemini LLM failure clustering and parameter filters
python .agents/skills/cxas-agent-foundry/scripts/generate_interactive_report.py --input <path_to_sim_results.json> --output <path_to_report.html>

# Inspect app architecture
python .agents/skills/cxas-agent-foundry/scripts/inspect-app.py

# Triage failures
python .agents/skills/cxas-agent-foundry/scripts/triage-results.py --last 3

# Run all 6 build-verification gates against the deployed app
python .agents/skills/cxas-agent-foundry/scripts/gate-check.py

# Tune scoring thresholds (similarity, hallucination, extra-tools)
python .agents/skills/cxas-agent-foundry/scripts/app-thresholds.py show

# Sync callback Python code into evals/callback_tests/agents/ + create test.py symlinks.
# Required for tests to be discoverable by test_all_callbacks_in_app_dir.
python .agents/skills/cxas-agent-foundry/scripts/sync-callbacks.py                  # post-push: pull from platform
python .agents/skills/cxas-agent-foundry/scripts/sync-callbacks.py --from-local <app_dir>  # pre-push: copy from local app dir

# Snapshot app version (create immutable platform backup)
cxas versions create --app-name projects/<project_id>/locations/<location>/apps/<app_id> \
  --display-name "v1.0.0-snapshot" --description "Pre-refactor baseline"

# List and compare app versions
cxas versions list --app-name projects/<project_id>/locations/<location>/apps/<app_id>
cxas versions compare --app-name projects/<project_id>/locations/<location>/apps/<app_id> \
  --source <version_id_1> --target <version_id_2> --web

# Cold-start setup (first-time only — venv + project bootstrap)
.agents/skills/cxas-agent-foundry/scripts/setup.sh
python .agents/skills/cxas-agent-foundry/scripts/setup-project.py

使い分け： gate-check.py と inspect-app.py は、どちらも「アーキテクチャを見せて」という用途に使えますが、プッシュを控えているとき、構築を終えたとき、または検証を依頼されたときは、必ず gate-check.py を使います。inspect-app.py は、検証ゲートを通さずに「ここに何があるか」を手早く確認するためのものです。迷った場合は、gate-check.py を使ってください。

サブエージェント

メインスレッドのコンテキストを大きく消費するような、負荷の高い診断や分析作業では、Agent ツールを使って以下のサブエージェントを起動してください。該当する .md ファイルの内容をプロンプトとして渡し、そのファイルに記載されている入力を追加してください。

サブエージェント	推論強度	使用する場面
agents/triage-failure.md	HIGH	失敗した評価を1件診断します。カテゴリの優先順位に基づき、失敗上位5件を並行して処理します。最初のバッチの結果が返った後、さらに反復します。
agents/tdd-writer.md	HIGH	既存のエージェントからTDDをリバースエンジニアリングするか、PRDから草案を作成します。TDDと未解決の質問の引き継ぎ事項を返します。メインスレッドでユーザーとの提示・質問・反復のループを実行してください（サブエージェントは質問できません）。
agents/scaffolder.md	MEDIUM	承認済みのTDDから、すべてのエージェントコード（エージェントのJSON、instruction.txt、ツールのpython_code、コールバック、app.json）を一括生成します。1回の起動で、メインスレッドでのファイル書き込み30～60回分を置き換えられます。
agents/coverage-analyst.md	MEDIUM	エージェントのアーキテクチャに対する評価カバレッジレポート全体を生成します。
agents/eval-writer.md	MEDIUM	評価タイプ1つ分（すべてのゴールデン、すべてのシミュレーションなど）の評価を生成します。TDDのカバレッジマップは自ら参照します。1回の構築につき最大4回まで起動できます。
agents/lint-fixer.md	LOW（機械的）	cxas lint を実行し、クリーンになるまで、すべてのエラーと決定的な警告を機械的に修正します。メインスレッドでは lint を実行しないでください。

評価を実行するサブエージェントはありません。scripts/run-and-report.py --json-summary <path> > /dev/null 2>&1 を使い、サマリーファイルを読み取ってください。references/debug.md → 「クイックスタート」を参照してください。作業は決定的であるため、スクリプトにまとめられています。

推論強度はランタイム向けの目安です。HIGH のサブエージェントは、より多くの思考予算や強力なモデルの恩恵を受けます。一方、LOW のサブエージェントは手順に沿って実行するため、そうした設定は必要ありません。各サブエージェントのファイル冒頭にも、1行の根拠とともにこの目安が記載されています。

環境準備状況の確認（ルーティング前に実行）

サブスキルにルーティングする前に、次の項目を順に確認してください。

1. 仮想環境が存在するか？ -- .venv/ ディレクトリが存在するか確認します
2. 設定が存在するか？ -- .active-project ファイルが存在し、そこに記載された <project>/gecx-config.json が存在するか確認します
3. 以前にビルドしたことがあるか？ -- 内容がある <project>/cxas_app/ ディレクトリが存在するか確認します

シグナル	アクション
.venv/ または設定がない	初回セットアップが必要です。 ほかの作業を始める前に references/setup.md を読み込みます。
gecx-config.json は存在するが、cxas_app/ に内容がない	リピーターユーザーの新規プロジェクトです。通常どおりルーティングします。
すべて存在する	リピーターユーザーです。通常どおりルーティングします。

意図を判断してルーティングする

ユーザーの要望を読み取り、適切なサブスキルを読み込みます。

ユーザーの発言	フェーズ	読み込むもの
「この PRD からエージェントを作って」	Build	references/build.md
「新しい cxas アプリを作って」「新しいエージェントを作って」「エージェントをセットアップして」「エージェントを作りたい」	Build	references/build.md
「エージェント用の eval を作って」	Build	references/build.md
「ツールのテストを生成して」「コールバックのテストを作って」	Build	references/build.md
「要件が変わったので eval を更新して」	Build	references/build.md
「TDD を更新して」	Build	references/build.md
「eval を実行して」「eval をプッシュして」「結果を確認して」	Run	references/run.md
「ツールのテストを実行して」「コールバックをテストして」	Run	references/run.md
「レポートを生成して」	Run	references/run.md
「インタラクティブレポートを生成して」「失敗をクラスタリングするダッシュボード」	Run	references/generating-reports.md → 「インタラクティブ診断ダッシュボード」
「この eval が失敗する理由は？」「90% にして」	Debug	references/debug.md
「失敗している eval を修正して」「エージェントをデバッグして」	Debug	references/debug.md
「ツールのテストが失敗している」「コールバックのテストが壊れた」	Debug	references/debug.md
「アプリのバージョンをスナップショットして」「バージョンを作成して」「バージョンを比較して」「バージョンを一覧表示して」	Manage	references/api-reference.md → 「バージョン管理」
「エージェントの指示を編集して」「認証ツールを調整して」「あいさつを修正して」「このコールバックを更新して」	Build（編集サイクル）	references/build.md → 「既存エージェントの編集」

エージェント／アプリの作成、構築、セットアップを意味する表現は、たとえ「アプリのシェルだけを作って」というように聞こえても、references/build.md にルーティングします。 「新しい cxas アプリを作って」は、スキャフォールディングへの近道ではありません。完全なビルドフロー（todo.md → インタビュー／PRD → TDD + 承認 → スキャフォールド → lint → eval → プッシュ）が開始されます。ユーザーが「build」ではなく「create」と言ったことを理由にインタビュー／TDD を省略するのは、ルーティングの失敗です。

既存エージェントの編集（指示の調整、ツールの変更、コールバックの修正）は、build.md の「既存エージェントの編集」セクションにルーティングします。標準の pull → edit → lint → push → run-evals サイクルに従います。その後の lint や eval の実行を省略しないでください。回帰に気づかないまま、スコアが 90% から 70% に低下することがあります。

意図が不明確な場合は、次のように尋ねます。「eval を構築／作成したいですか、実行したいですか、それとも失敗をデバッグしたいですか？」

開始前

プロジェクト固有のコンテキスト（アプリ ID、変数の処理ルール、音声スコアリングの回避策）がないか、メモリを確認します。情報がない場合は、ユーザーに尋ねてください。