建立 CLI 指令規範檔（cli-spec.yaml）作為所有指令的 single source of truth

[kiki830621]

Problem

目前 macdoc 所有 CLI 指令的規範散在多處：

• 各子命令的 --help 輸出
• CLAUDE.md 的 Development Commands 區塊
• CONVERSIONS.md 的轉換矩陣
• openspec/specs/ 各 spec 文件

沒有一個統一的檔案定義「macdoc 有哪些指令、每個指令的參數、輸入輸出格式」。

特別是 PDF 相關指令有多條重疊路徑（convert --to md、pdf ocr、ocr），使用者不清楚該用哪個。

Type

feature

Priority

P2

Expected

一個 cli-spec.yaml（或 .md）定義所有 CLI 指令的：

• 子命令結構（command / subcommand）
• 參數（args、options、required/optional、default values）
• 輸入格式與輸出格式
• 同一 source→target 有多條路徑時的差異說明
• 依賴條件（如需要 ollama / mlx）

此檔案作為 single source of truth，未來可用於：

• 自動生成 --help 文字
• 自動生成 CONVERSIONS.md
• CLI routing 邏輯參考
• 新增 converter 時只需加一筆 entry

Impact

降低維護成本，減少文件與實作不同步的風險，讓使用者和 AI 都能快速查到完整指令清單。

Current Status

Phase: diagnosed
Last updated: 2026-04-22 by idd-diagnose (batch)

[kiki830621]

Diagnosis

Type

feature (docs infrastructure)

Root Cause / Analysis

macdoc's command surface is already large (convert with 16 routes, pdf subcommands, bib, config ai, config ocr, top-level ocr), and currently spread across:

• Per-file ArgumentParser definitions (Sources/MacDocCLI/MacDoc+*.swift)
• CLAUDE.md Development Commands section
• .claude/rules/cli-design/* spec fragments
• plugin SKILL.md (psychquant-claude-plugins/plugins/macdoc/skills/macdoc/SKILL.md)

There is no machine-readable manifest. The design rules (.claude/rules/cli-design/textutil-compat.md, convert-entry-point.md, unix-conventions.md) describe conventions but don't enumerate the current surface. PDF-adjacent paths (convert --to md file.pdf vs pdf ocr vs top-level ocr) overlap and the distinction isn't captured anywhere discoverable.

Impact

• SKILL.md drift (e.g. docs: skill 文件漏列 HTML→PDF via playwright（#69 已實作但 skill.md 仍標 textutil） #85 — skill doc lagged behind feat: 支援 HTML → PDF 轉換 (macdoc convert --to pdf) #69's HTML→PDF via playwright for >1 release)
• New converter onboarding burden — author has to touch CLI code + CLAUDE.md + SKILL.md + CONVERSIONS.md + rules files
• AI/agent consumption — LLMs calling macdoc have to grep multiple files

Strategy

• /spectra:discuss to scope: single YAML vs split per-subcommand? derive --help strings from spec, or keep them authored inline and cross-check in CI?
• Define schema covering: command path, args, options (name/short/type/default/required), accepted input formats, produced output format, stdout-capable flag, external dependencies (e.g. playwright), and documentation pointer
• Decide authoritative side: spec-first (generate ArgumentParser stubs) vs code-first (generate spec from ArgumentParser introspection + tests that verify spec matches)
• Produce CONVERSIONS.md from spec as a smoke test of round-trip fidelity
• Add to openspec/specs/ so future changes touch both code and spec

Complexity

SDD-warranted — affects CLI contract, CLAUDE.md, SKILL.md, and multiple downstream consumers. Needs /spectra:discuss first to pin authoritative side (spec-first vs code-first introspection) before proposing.

Risks

• Spec-first risks duplicating swift-argument-parser work and going stale (same problem in YAML instead of markdown)
• Code-first introspection requires reflection over ArgumentParser types — possible via dumpHelp JSON output (swift-argument-parser supports --experimental-dump-help), reduces drift risk substantially
• Scope creep into "CLI framework replacement" — keep this constrained to documentation/discovery, not routing