acomo ワークフローシステム開発ループ（スキルセット入口）

このスキルは、acomo をバックエンドとした業務ワークフローシステムを AI エージェントと対話的に開発するための 開発ループとハーネスの正本である。ユーザーが開発者かどうかを問わず、「業務の説明 → 動くワークフロー」までを エージェント主導で反復できるようにする。

ユーザー向け回答の作法はリポジトリ共通ルール（AGENTS.md「ユーザー向け回答（全スキル共通）」）に従う。 スキル名・参照ファイルパス・取得過程をエンドユーザー向けの説明文に出さない。

このパッケージが提供するもの

スキルセット構成（ルーティング）

このスキルはオーケストレーターであり、各作業は既存スキルへ委譲する。該当スキルを必ず読み込んでから作業する。

acomo-ui は acomo 標準画面の案内スキル。カスタムアプリの画面はアプリ自身の言葉で案内する（A4）。

2 つの利用モード

最初にユーザーの環境と役割を把握し、モードを決める（途中で切り替えてよい）。

どちらのモードでも、業務の意思決定（承認段数・権限・分岐条件など）はユーザーに確認する。 技術的な検証・修正はエージェントが自律的に回す。

開発ループ（概要）

正本は references/loop-guide.md。各フェーズには入口条件・出口条件（DoD）がある。

Phase 0 環境準備      … 接続先（ローカル or 本番テナント）と認証を確立し、疎通を確認する
Phase 1 ヒアリング設計 … acomo-workflow-modeling に従い draft（definition/dataSchema/policy）を対話生成
Phase 2 静的検証      … validate-model.mjs でエラー 0 になるまで draft を修正（エージェント自律ループ）
Phase 3 登録          … createWorkflowModel でドラフト登録し、モデル ID を控える
Phase 4 ウォークスルー … walkthrough-plan.mjs の計画に沿って公開 → 全結末経路を実走 → 証跡を残す
Phase 5 改善          … ユーザーのフィードバックを差分で draft に反映し、Phase 2 へ戻る
Phase 6 引き渡し      … 運用手順（画面操作ベース）をユーザーに説明して完了

カスタムフロントエンドが要る場合は、Phase 4 green を入口条件に A1〜A4 トラック （画面設計 → 実装 → E2E → 引き渡し。正本: references/custom-app-guide.md）へ続ける。 操作面が acomo 標準 UI / CLI で足りるなら Phase 6 で完了。

ループ停止条件（このスキルの DoD）

1. validate-model.mjs がエラー 0（警告は個別に妥当性を説明済み）
2. ウォークスルー計画の全経路（承認・却下など全結末）を実走し、期待した終了ノードに到達した
3. ユーザーが画面上（または CLI 出力）で業務どおり動くことを確認し、受け入れた
4. （カスタムアプリを作る場合）A3 の DoD — 全結末経路がカスタム UI 経由でも到達し、権限外ケースを確認済み

エージェント実行レール（迷ったらこの順）

モデル 1 本を作って引き渡すまでの機械的な最短手順。各行のゲートを満たすまで次の行に進まない。 詳細・例外は references/loop-guide.md。JSON の形で迷ったら fixtures/sample-*.json を正とする（文中の断片より fixtures 優先）。

ハーネス早見

モノレポ内ではルート npm script を使う（実体は本スキル scripts/ 配下・依存ゼロの Node スクリプト）。

# draft の静的検証（fenced ブロック付きテキストも直接渡せる）
npm run workflow:validate -- path/to/draft.json
npm run workflow:validate -- path/to/draft.json --json   # 機械可読

# ウォークスルー計画の生成（Markdown。--json で機械可読）
npm run workflow:walkthrough -- path/to/draft.json

モノレポ外（スタンドアロン配布時）は node scripts/validate-model.mjs <file> で直接実行できる。 詳細・エラーコード対応表: references/harness-guide.md

モノレポ外での利用（配布）

本スキルは acomo モノレポを持たない利用者・カスタムアプリ開発者にも配布される （配布チャネル: acomo-skills リポジトリ。公開手順はモノレポの docs/skills-distribution.md）。 配布レイアウトでも次が成り立つように書かれている。

• 依存スキル（acomo / acomo-workflow-modeling / acomo-ui）は同じ親ディレクトリに併設される前提。 相対リンク（../acomo/SKILL.md 等）はそのまま解決する。
• ハーネスは依存ゼロの Node スクリプト（Node 20+）。node <このスキル>/scripts/validate-model.mjs <file> で動く。 スキーマ検証層は併設の acomo-workflow-modeling/schemas/ を自動解決する（無ければ --schemas-dir か 環境変数 ACOMO_MODEL_SCHEMAS_DIR で指定。未指定時はスキーマ層のみスキップし警告を出す）。
• npm run workflow:validate / workflow:walkthrough / npm run skills:install はモノレポ内専用の入口。 配布環境では上記のスタンドアロン実行を使う。
• ローカル開発スタック（dev:up / seed ユーザー等）に触れる記述はモノレポ内でのみ有効。配布先では 対象テナントの実値（URL・authTenantId・ユーザー）に読み替える。

進め方の原則（ループエンジニアリング）

• draft を早く見せ、検証を挟んでから登録する。 ヒアリングだけを続けない（acomo-workflow-modeling の段階生成プロトコルに従う）。
• 静的検証はエージェントの自律ループ。 validate のエラーはユーザーに逐一報告せず、直してから結果だけ伝える。警告は「業務判断が要るもの」だけユーザーに確認する。
• ウォークスルーは必ず全結末を通す。 承認で終わる経路だけでなく、却下・差し戻し・分岐の各経路を通し、期待した終了ノード名に到達したことを確認する。
• 改善は差分で回す。 フィードバックのたびに全作り直しせず、definition / dataSchema / policy のどこに効くかを説明してから draft を更新し、Phase 2（静的検証）から再走する。
• 証跡を残す。 各ウォークスルーの実行コマンド・プロセス ID・到達ノードを記録し、受入時にユーザーへ提示する。

Known failure modes

• エッジ type に revert を書く — モデル JSON の FlowType に revert は存在しない（差し戻しはノードの canRevert とランタイム API の担当）。validate が E_EDGE_TYPE で検出する。
• 条件式を文字列 1 本で書く — conditions[].expression / actionPolicies[].allow は必ず {operator, expression1, expression2} のオブジェクト形式（"$token.approveCount >= $token.childTokenLength" のような文字列はスキーマ違反で E_SCHEMA_DEFINITION になる）。正しい形の正本は fixtures/sample-*.json — 文中の JSON 断片と食い違ったら fixtures を正とする。
• policy のノード ID をノード名や別 ID で書く — definition の id と完全一致が必要。E_POLICY_NODE で検出する。
• dataSchema プロパティの _order 欠落 — バックエンドの AJV は _order / _acomoType を必須とする。スキーマ検証（E_SCHEMA）で検出する。
• 却下経路の実走漏れ — 承認経路だけ試して完成と報告してしまう。walkthrough-plan が列挙する全経路を通すこと。
• ローカル検証で acomo login の恒久トークンを前提にする — ローカル開発スタックでは SuperTokens のセッションアクセストークンを ACOMO_ACCESS_TOKEN に使う（短命）。手順は references/walkthrough-testing.md。
• プロセスデータを {"data":{...}} で包んで送る — engine 系 API（submit / approve / reject / save）の body は dataSchema のキーをトップレベルに持つフラットな JSON（ローカル実走で確認済み）。包んで送ると dataSchema 外のキーとして無視される。
• 完了後にプロセスデータが見えないのをバグと報告する — 終了イベントに read の policy がないと完了後の取得で data が {} になる仕様。完了後閲覧が要る業務は終了イベントに read を並べる。
• @acomo/client の高レベル生成メソッドでプロセスを受け取る — engine 系・プロセス取得系は *Raw + raw.json() を使う（高レベル版は token.childProcessTokens の FromJSON マッパーで落ちる。ローカル実走で確認済み。正本: references/client-integration.md）。
• Engine:execute ロールなしのユーザーで engine API を叩いて 403 を actionPolicies のせいにする — engine 系はロールの SystemActionPolicies Engine:execute が前提（実測。エラーメッセージに Engine:execute が必要 と出る）。カスタムアプリ利用者・E2E テストユーザーに該当ロールを割り当てる。
• カスタムアプリでボタン活性をロール名・status 文字列で自作判定する — getProcessWithNodeActions の nodeActions（サーバー側の actionPolicies 評価結果）を使う。
• @acomo/client のクラス名を operationId から推測する / 一般ユーザーのアプリで getWorkflowModel を呼ぶ — 生成クラスは OpenAPI tag ごと（getMyModel は MyModelApi）。/models・/processes 系は Model:read 等が要る管理者向けで一般業務ユーザーは 403 — アプリは /my/...（MyModelApi / MyProcessApi）で組む。対応表: references/client-integration.md。
• カスタム SPA から業務 API をブラウザ直呼びして CORS で落ちる — CORS の許可ヘッダに x-tenant-id が含まれない（実測）。認証 API は直呼びできるが、業務 API は同一オリジン化（プロキシ / BFF）する。正本: references/auth-integration.md。