spec-metadata

The Spec Metadata Generator is a specialized engineering utility designed to ensure consistency and traceability across technical documentation. It streamlines the process of capturing essential environmental state and version control context by automating the extraction of system data into a structured format. This skill is primarily intended for software engineers, technical leads, and documentation managers who need to maintain clear audit trails in research documents, project handoffs, and detailed implementation plans. By integrating this metadata directly into the YAML frontmatter of your files, you ensure that every document is anchored to a specific point in time and a verified codebase state, which is critical for debugging historical architectural decisions and coordinating team efforts.

• Automatically detects and extracts repository root, branch name, and commit hashes for Git and Jujutsu (jj) version control systems.

• Generates precise, sortable timestamps in both human-readable and filename-friendly formats, including timezone information.

• Provides a standardized YAML-ready output schema that helps tools and automated scripts parse document history reliably.

• Facilitates immediate integration into the thoughts/shared/research/ and thoughts/shared/handoffs/ workflow directories.

• Reduces manual error by replacing error-prone manual data entry with reliable bash-based command execution for metadata collection.

• The skill is activated when drafting new research or implementation specifications to ensure the documentation reflects the current development context.

• For Git users, it leverages standard rev-parse and date commands; for Jujutsu (jj) users, it utilizes workspace and log commands to maintain compatibility.

• Always include the generated timestamp in your filenames using the underscore-delimited format provided (e.g., YYYY-MM-DD_HH-MM-SS) to improve project organization.

• When inserting metadata into YAML frontmatter, ensure that the date fields follow the ISO format to maintain compatibility with static site generators and documentation viewers.

• If multiple bookmarks are detected in a Jujutsu environment, prioritize the most relevant bookmark to clearly communicate the implementation branch status.