[FEATURE] Add YAML frontmatter with metadata to auto-generated plan files

[PaulRBerg]

Problem Statement

When Claude Code creates plan files in ~/.claude/plans/*.md, they contain only the plan content without any metadata. As far as I can see it, the Markdown file names are random, e.g. indexed-brewing-teapot.md.

This makes it difficult to:

• Track when plans were created
• Correlate plans with specific Claude sessions
• Understand the context in which a plan was generated

Proposed Solution

Include a YAML frontmatter block at the top of auto-generated plan files with metadata such as:

---
created: 2025-01-15T14:30:00Z
session_id: abc123xyz
model: claude-sonnet-4-5-20250929
working_directory: /path/to/project
---

Potential fields to include:

• created - ISO 8601 timestamp of when the plan was generated
• session_id - The Claude Code session identifier
• model - The model used during planning
• working_directory - The directory context when the plan was created
• git_branch - Current git branch (if in a repo)
• plan_name - The auto-generated plan name (e.g., "iterative-booping-parnas")

Alternative Solutions

• Adding a separate metadata JSON file alongside each plan
• Storing metadata in a central index file
• Embedding metadata as HTML comments instead of YAML frontmatter

YAML frontmatter is preferred because it's a well-established convention (used by Jekyll, Hugo, Obsidian, etc.) and is easily parseable.

Priority

Medium - Would be very helpful

Feature Category

Configuration and settings

Use Case Example

1. User generates multiple plans over several days
2. Later, user wants to find a plan from a specific session or time period
3. With frontmatter metadata, they can easily grep or search for plans by date/session
4. This enables better organization and retrieval of planning history

Additional Context

This would be especially useful for users who:

• Work on multiple projects and generate many plans
• Want to audit their planning history
• Build tooling around Claude Code's plan files
• Use tools like Obsidian that can leverage YAML frontmatter for organization

[github-actions[bot]]

This issue has been inactive for 30 days. If the issue is still occurring, please comment to let us know. Otherwise, this issue will be automatically closed in 30 days for housekeeping purposes.

[PaulRBerg]

Please keep active. I maintain my own custom hook at the moment for inserting this YAML frontmatter.