spec-metadata

規格元數據生成器 (Spec Metadata Generator) 是一款專業的工程工具，旨在確保各類技術文檔的一致性與可追溯性。它透過自動提取系統環境資訊並將其轉化為結構化格式，簡化了獲取關鍵環境狀態與版本控制上下文的流程。本技能主要針對軟體工程師、技術主管與文檔管理員，協助他們在研究文件、專案交接與詳細實施計劃中維護清晰的稽核紀錄。透過將此元數據直接整合到檔案的 YAML 前端 (Frontmatter) 中，您可以確保每份文檔都鎖定在特定的時間點與驗證過的程式碼庫狀態，這對於追蹤歷史架構決策與協調團隊工作至關重要。

• 自動偵測並提取 Git 與 Jujutsu (jj) 版本控制系統的存儲庫根目錄、分支名稱與提交雜湊值。

• 生成精確且可排序的時間戳，同時提供人類可讀與適用於檔案名稱的格式，並包含時區資訊。

• 提供標準化的 YAML 輸出結構，協助自動化工具與腳本可靠地解析文件歷史記錄。

• 支援直接整合至 thoughts/shared/research/ 與 thoughts/shared/handoffs/ 工作流程目錄中。

• 通過基於 Bash 的可靠命令執行取代容易出錯的手動輸入，從而降低人為誤差。

• 在起草新的研究或實施規範時啟用此技能，以確保文檔能反映當前的開發上下文。

• 針對 Git 使用者，該技能利用標準的 rev-parse 與 date 命令；針對 Jujutsu (jj) 使用者，則利用 workspace 與 log 命令來保持兼容性。

• 請務必使用提供的下劃線分隔格式（例如 YYYY-MM-DD_HH-MM-SS）將時間戳納入檔案名稱中，以提升專案組織效率。

• 將元數據插入 YAML 前端時，請確保日期欄位符合 ISO 格式，以維持與靜態網站產生器與文檔檢視器的兼容性。

• 若在 Jujutsu 環境中偵測到多個書籤，請優先選擇最相關的書籤，以便清晰傳達當前的實施分支狀態。