modiqo/cliare

What it solves

CLIARE（CLI Agent Readiness Evaluation）解決了「CLI 漂移」的問題，也就是命令列介面的實際執行行為與文件或說明文字不一致的情況。這種漂移會讓 AI 代理因不斷透過試錯猜測指令與旗標而浪費 token 與延遲。它同時協助安全審查者找出未文件化的副作用（例如在看似安全的探索指令中意外寫入檔案）。

How it works

CLIARE 把 CLI 二進位檔視為黑箱，在受控的範圍內對其進行探測。它不依賴靜態文件，而是在各種情境（乾淨、已驗證或有測試資料）下執行二進位檔，記錄實際存在的指令、哪些旗標是安全的，以及輸出是否可機器解析（JSON/YAML）。接著產生指令索引與一系列報告（分數卡、問題清單與角色專屬封包），映射出 CLI 的真實表面。

Who it’s for

• CLI Maintainers：找出說明文件、診斷資訊與輸出合約的缺口，讓工具更適合代理使用。
• Security Reviewers：在二進位檔暴露給自主代理前，偵測未文件化的執行時行為與持續性副作用。
• Agent Harness Builders：取得有證據支撐的指令索引，讓代理能直接導向正確指令，免於再次透過試錯發現語法。

Highlights

• Evidence-Based Mapping：根據執行時證據產生 command-index.json，而非手寫文件。
• Black-Box Probing：在隔離或特定主機環境中測量二進位檔，以偵測副作用。
• Agent-Ready Artifacts：產出 AGENT_SKILL.md 與角色報告，指導代理行為。
• Surface Querying：提供工具讓 harness 查詢意圖到指令的對應答案。
• CI Integration：內建 GitHub Action，自動化就緒度稽核並建立發行門檻。