isotc-cli

Intent-to-Spec Optimal Transport Compiler CLI — Spec Compiler + Agent Runtime Policy + Human-Centered Guardrail

isotc-cli は、requirements / constraints / architecture decisions を実行可能な repo policy に変換する spec compiler である。単なる architecture linter ではなく、仕様をコンパイルし、AI/人間/CI に同じ境界を配布し、違反を継続検査する CLI として設計されている。憲法（Constitution）に基づいた検証と自己修復により、AIエージェントによる ad-hoc prompt-based development（Vibe-coding）が引き起こすアーキテクチャ破壊を防ぐ。

インストール

# 一行で実行（推奨）
npx isotc-cli@latest verify

# または
npm exec --yes isotc-cli@latest -- verify

以下、isotc は npx isotc-cli@latest の省略形として記載します。

開発者向け（ソースビルド）

git clone https://github.com/SoundLabbitTechnology/isotc-cli.git
cd isotc-cli
npm install && npm run build
npm link  # 任意

使い方

1. プロジェクトの初期化

isotc init
# → .spec/constitution.toml が生成される

2. 仕様→計画→実装→検証のフロー

# モード設定（LLM 直呼び or Agent モード）
# LLM モード（デフォルト）
#   - intent / plan が LLM API（OpenAI / Gemini / Claude）を直接呼び出す
# Agent モード
#   - LLM を呼ばず、.spec/requirements.json や .spec/tasks.json のスケルトンと
#     IDE エージェント向けプロンプト（.spec/agent/*.md）を生成

# 例: Agent モードでのフロー（LLM キー不要）
isotc init
isotc config set mode agent

# 自然言語要件を構造化するためのスケルトンとプロンプトを生成
isotc intent "ユーザーはメールでログインできる。応答は200ms以内とする。"
# → .spec/requirements.json, open_questions.md, assumptions.toml, agent/intent-prompt.md を生成

# 設計とタスク分解用のスケルトンとプロンプトを生成
isotc plan --force
# → .spec/tasks.json, design.md, adr/, model.puml, testplan.json, trace-seed.json, agent/plan-prompt.md を生成

# トレーサビリティグラフの構築
isotc trace build
# → .spec/trace.json を生成

# タスク単位の隔離プロンプトで実装委譲
isotc impl --task-id 1.1 --isolated-prompt > prompt.txt

# アーキテクチャ検証
isotc verify

3. アーキテクチャ検証

# 人間向けテキスト出力
isotc verify

# CI / AI連携用 JSON 出力
isotc verify --format json

# pre-commit hook 用（ステージ済みファイルのみ検証）
isotc verify --staged --format json

# 対象ファイルを指定して検証
isotc verify --changed-files "src/a.ts,src/b.ts" --format json

終了コード（2_REQUIREMENTS.md 3.4 準拠）:

| コード | 意味 | |-------|------| | 0 | 成功（検証パス、タスク完了） | | 1 | 一般的なエラー（引数間違い、設定欠損） | | 2 | 検証エラー（アーキテクチャ違反）— AI の自己修復ループに利用 | | 3 | 致命的なエラー（設定ファイル破損、解析不能） |

4. CI での利用（GitHub Actions）

- uses: actions/checkout@v4
- uses: actions/setup-node@v4
  with:
    node-version: "20"
    cache: "npm"
- run: npx isotc-cli@latest init --force
- run: npx isotc-cli@latest verify --format json

CI / AI 連携時は verify --format json を指定し、stdout に純粋な JSON のみ出力させることを推奨します。

composite action を使う場合:

- uses: actions/checkout@v4
- uses: SoundLabbitTechnology/isotc-cli/.github/actions/setup-isotc@main
- run: npx isotc-cli@latest init --force
- run: npx isotc-cli@latest verify --format json

コマンド一覧

| コマンド | 説明 | |----------|------| | init | 憲法ファイル（.spec/constitution.toml）の生成 | | intent | 自然言語要件から構造化要件の生成（requirements.json, open_questions.md, assumptions.toml） | | plan | 技術設計とタスク分解（design.md, adr/, model.puml, testplan.json, trace-seed.json） | | impl | AIエージェントへの実装委譲（--isolated-prompt で隔離プロンプト生成） | | handoff | 役割別ハンドオフ出力（implementer / reviewer / tester / architect） | | verify | アーキテクチャ検証（import/re-export/パッケージ/循環依存）と反例の出力 | | trace build | トレーサビリティグラフ（trace.json）の構築 | | trace diff | 変更ファイルから影響する requirement / test を列挙 | | trace explain | ファイル・違反がどの要件にぶつかるかを返す | | emit copilot | constitution から .github/copilot-instructions.md を生成 | | emit claude | constitution から CLAUDE.md を生成（Claude Code 用） | | emit agents | constitution から .github/agents/architecture.agent.md を生成 | | doctor | 環境と .spec の健全性チェック | | config | LLM アダプター設定の表示・変更（.spec/config.toml） |

LLM / モード設定（config）

プロジェクトごとに LLM プロバイダーとモデル、モード（llm | agent）を .spec/config.toml に保存できます。isotc init 実行後に利用可能です。

# プロバイダーを Gemini に設定
isotc config set provider gemini

# モデルを指定
isotc config set model gemini-2.5-flash

# モードを Agent に設定（LLM API キー不要）
isotc config set mode agent

# 現在の設定を確認
isotc config show

# 利用可能なプロバイダー一覧
isotc config list-providers

優先順位: 環境変数 > .spec/config.toml > デフォルト。API キーはセキュリティのため環境変数のみで指定します。

環境変数

| 変数 | 説明 | |------|------| | ISOTC_LLM_PROVIDER | LLM プロバイダー: openai | gemini | claude（デフォルト: openai） | | ISOTC_LLM_MODEL | 使用するモデル（プロバイダーごとのデフォルト: gpt-4o-mini / gemini-2.0-flash / claude-3-5-sonnet-20241022） | | ISOTC_MODE | isotc のモード: llm（LLM直呼び） | agent（LLM キー不要。intent / plan はスケルトンと .spec/agent/*.md を生成） | | OPENAI_API_KEY | OpenAI 利用時に必須 | | GEMINI_API_KEY または GOOGLE_API_KEY | Gemini 利用時に必須 | | ANTHROPIC_API_KEY | Claude 利用時に必須 |

コンテキストクリアの推奨ワークフロー

タスク切り替え時は、前タスクの会話履歴に引っ張られず仕様に集中するため、コンテキストを切ることを推奨します。

# タスク 1.1 の隔離プロンプトを生成
isotc impl --task-id 1.1 --isolated-prompt > prompt_1.1.txt

# 新規チャットを開き、prompt_1.1.txt の内容を貼り付けて実装
# タスク 1.2 に進む際は /clear または新規チャットで再度
isotc impl --task-id 1.2 --isolated-prompt > prompt_1.2.txt

憲法（Constitution）

.spec/constitution.toml でレイヤー、依存ルール、Agent Steering を定義します。AI が扱えるコンテキスト境界を保つ設計が有利だという仮説に基づき、モジュール境界を明示的に検証可能にします。

[[layers]]
name = "domain"
basePath = "src/domain/**"

[rules]
domain = []
application = ["domain"]
infrastructure = ["domain", "application"]

# オプション: レイヤーごとのパッケージ import ルール
[rules.packages.domain]
allow = []
deny = ["fs", "path", "process"]

[steering]
codingStandards = "ESLint + Prettier を推奨"
technologyStack = "TypeScript, Node.js 18+"
designPrinciples = "ヘキサゴナルアーキテクチャを厳守"

verify は import 違反に加え、re-export、パッケージ import、循環依存を検出します。

Agent 配布（emit）

constitution を定義した後、isotc emit で各 Agent 環境向けの設定ファイルを生成できる。

# GitHub Copilot 用
isotc emit copilot --force

# Claude Code 用
isotc emit claude --force

# GitHub Agents 用
isotc emit agents --force

生成されたファイルは、各 Agent が constitution に基づいたアーキテクチャ規約を参照するための指示として機能する。詳細は AGENTS.md を参照。

ドキュメント

| ドキュメント | 内容 | |--------------|------| | docs/0_INDEX.md | ドキュメント一覧・ナビゲーション | | docs/1_PRD.md | プロダクト要求仕様書 | | docs/2_REQUIREMENTS.md | コマンド契約・I/O仕様・JSON Schema | | docs/3_ARCHITECTURE.md | 内部アーキテクチャ設計 | | docs/4_RESEARCH_BACKGROUND.md | 学術的裏付けと参考文献 | | docs/5_LLM_CONFIGURATION.md | LLM プロバイダー選択・設定ガイド | | docs/TEST_SIMULATION_REPORT.md | テストシミュレーション・棚卸し表 | | AGENTS.md | AI エージェント向けガイド（機械可読コマンド一覧） |

開発

npm install
npm run build
npm test

License

本プロジェクトは MIT License の下で公開されています。

Copyright (c) 2025 Sound Labbit Technology Inc.

• CONTRIBUTING.md - 貢献ガイドライン（互換性ポリシー・破壊的変更ポリシー含む）
• SECURITY.md - 脆弱性報告について
• CODE_OF_CONDUCT.md - 行動規範