Feature: LLM機能統合 — suggest / audit / propose コマンドの追加

[foo-ogawa]

概要

agent-contracts DSL / agent-contracts-runtime / cli-contracts スタックを使い、embedoc に LLM パワードコマンドを追加する。migraguard の実装パターン（DSL定義 → codegen → orchestrator → context-builder → formatter → CLI handler）を踏襲する。

追加コマンド

コマンド	Type	Agent	目的
suggest-markers <file>	propose	document-structure-advisor	embedoc化すべきmarker候補の提案
audit-markers	audit	document-structure-advisor	既存markerの健全性チェック
propose-renderer <description>	propose	document-structure-advisor	renderer雛形コードの提案

Agent定義: document-structure-advisor

• mode: read-only
• responsibilities:
  • ドキュメント内の手動管理されている生成可能セクションの特定
  • marker名・datasource・属性の設計提案
  • 既存markerと外部datasourceの乖離検出
  • renderer TypeScriptコードの雛形生成
• constraints: ファイル書き込みなし。marker挿入は人間が行う
• rules:
  • 提案するmarker名は既存の命名規則に従う
  • renderer提案は defineEmbed API に準拠したコードを出力
  • stale検出は datasource の最終更新時刻やハッシュが取得可能な場合のみ高confidenceとする

DSL構成

dsl/
├── embedoc-dsl.yaml
├── agent-runtime.config.yaml
├── agents/document-structure-advisor.yaml
├── tasks.yaml
└── handoff-types.yaml

Tasks

task_id	workflow	result_handoff	固有フィールド
suggest-marker-candidates	marker-suggestion	marker-suggestion-result	markerCandidates[]
audit-marker-health	marker-audit	marker-audit-result	staleMarkers[], orphanedMarkers[]
propose-renderer-code	renderer-proposal	renderer-proposal-result	rendererCode, requiredDatasources[]

context-builder の入力素材

• buildSuggestMarkersContext: 対象ファイル内容, embedoc.config.yaml, 既存renderer一覧, datasource定義
• buildAuditMarkersContext: 全marker一覧（パース結果）, datasource定義, config
• buildProposeRendererContext: ユーザ記述（--description）, 既存renderer例, datasource一覧, embedoc API型定義

cli-contract.yaml 追加スキーマ

MarkerSuggestionResult:
  # AgentAuditResult base +
  markerCandidates:
    - name: string
      location: { file, startLine, endLine }
      currentContent: string    # 現在の手書き内容（抜粋）
      suggestedDatasource: string
      suggestedAttributes: object
      rationale: string

MarkerAuditResult:
  # AgentAuditResult base +
  staleMarkers:
    - name: string
      file: string
      reason: string
      confidence: number
  orphanedMarkers:
    - name: string
      file: string
      reason: string

RendererProposalResult:
  # AgentAuditResult base +
  rendererCode: string          # TypeScript defineEmbed code
  requiredDatasources:
    - name: string
      type: string
      config: object
  usage: string                 # marker挿入例

特記事項

• embedoc は「手書きと生成の共存」がコア思想。LLMには生成処理自体ではなく、どこを生成領域にすべきかの設計補助を担当させる
• propose-renderer は explain よりも propose 寄り。出力コードはそのまま .embedoc/renderers/ に配置可能なレベルを目指すが、あくまで草案

実装方針

• dsl/ ディレクトリ（DSL定義一式）
• src/agents/ モジュール（orchestrator, context-builder, formatter, types）
• src/commands/ にLLMコマンドハンドラ（既存CLIに統合）
• cli-contract.yaml にLLMコマンド定義 + x-agent メタデータ
• components/schemas にドメイン固有の結果型

共通オプション（全LLMコマンド）

--adapter <name>       # cursor, claude, openai, gemini, mock
--model <name>         # モデル名（adapterのデフォルトを上書き）
--dry-run              # プロンプト構築のみ、LLM呼び出しなし
--fail-on <level>      # warning | error | critical
--output <file>        # ファイル出力
--report-format <fmt>  # json | text | yaml

Exit codes

Code	意味
0	成功（threshold超えのfindingsなし）
1	一般エラー
3	入力バリデーション失敗
10	threshold超えのfindings検出
11	agent-contracts-runtime 未インストール
12	Adapter初期化エラー

依存関係

devDependencies:
  agent-contracts: latest
  agent-contracts-runtime: latest
  @openai/agents: latest
  @cursor/sdk: latest
  zod: latest

備考

• Phase 3（補完的）の実装対象
• 「どこを生成領域にすべきか」という設計補助が中心で、ユースケースが他のツールに比べてニッチ