[BUG] Plan file naming is non-deterministic despite full semantic availability

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (please file separate reports for different bugs)
• [x] I am using the latest version of Claude Code

What's Wrong?

Summary

Claude Code generates plan filenames using non-semantic, non-deterministic adjective-based strings (e.g. ~/.claude/plans/playful-exploring-wind.md). This occurs at plan creation time, despite the system having full access to the plan content and originating context. The resulting filenames lack semantic signal and referential stability, reducing the usefulness of plans as durable artifacts.

---

Context

At the moment a plan file is created, Claude Code has:

• The complete plan text
• The conversational context that produced it
• Any explicit titles or structural headings in the document

Despite this, filename generation is decoupled from content and instead introduces randomness. This injects avoidable entropy at the filesystem boundary.

---

Expected Behavior

Plan filenames should function as stable, meaningful identifiers that allow users to:

• Identify artifacts without opening them
• Sort, group, and search plans by intent or domain
• Iterate and version plans predictably
• Reference plans from scripts, documentation, or other tools

These expectations are consistent with standard engineering workflows involving persistent artifacts.

---

Actual Behavior

• Filenames are randomly generated and non-deterministic
• Filenames encode no information about plan intent, scope, or domain
• Equivalent or repeated plan generations do not produce stable identifiers
• Versioning and grouping must be inferred manually from file contents

---

Technical Impact

Loss of Referential Stability

Randomized filenames prevent reliable references across time and tooling. Identical or similar plans cannot be correlated without inspecting contents.

Reduced Discoverability

The absence of semantic signal in filenames prevents meaningful filesystem-level operations such as filtering, sorting, or pattern matching.

Poor Composition with Iteration

Plans are naturally iterative artifacts. Random names do not compose with common versioning patterns and obscure logical relationships between revisions.

Identifier–Presentation Coupling

The current approach conflates decorative labeling with artifact identity. Filenames should prioritize stability and semantic meaning; aesthetic labels can be represented within document metadata if desired.

---

Recommendation

At plan creation time:

• Derive a filename slug from a plan title, heading, or content summary
• Normalize to lowercase kebab-case
• Enforce a reasonable length and token limit
• Prefer deterministic generation for equivalent inputs, with collision handling as needed

Example filenames:

• chakra-metadata-refactor.md
• rust-toolchain-cleanup.md
• agentic-review-pipeline-v1.md

---

Rationale

Given that the system already performs content synthesis, semantic filename derivation has negligible additional cost and materially improves:

• Artifact usability
• Workflow integration
• Automation compatibility
• Long-term maintainability

This change corrects a design defect in how plan artifacts are identified and exposed to users.

What Should Happen?

At plan creation time:

• Derive a filename slug from a plan title, heading, or content summary
• Normalize to lowercase kebab-case
• Enforce a reasonable length and token limit
• Prefer deterministic generation for equivalent inputs, with collision handling as needed

Example filenames:

• chakra-metadata-refactor.md
• rust-toolchain-cleanup.md
• agentic-review-pipeline-v1.md

Error Messages/Logs

Steps to Reproduce

Create a plan in plan mode

Claude Model

Opus

Is this a regression?

Yes, this worked in a previous version

Last Working Version

_No response_

Claude Code Version

2.1.50 (Claude Code)

Platform

Anthropic API

Operating System

Ubuntu/Debian Linux

Terminal/Shell

Windows Terminal

Additional Information

_No response_