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 环境中检测到多个书签，请优先选择最相关的书签，以便清晰传达当前的实施分支状态。