specstory-organize

The specstory-organize skill provides a streamlined, automated workflow for developers who utilize SpecStory for AI-assisted coding sessions. As your project matures, the .specstory/history/ directory often accumulates hundreds of markdown files, making it difficult to locate specific sessions, manage project archives, or maintain a clean workspace. This skill systematically scans your history directory, extracts date information embedded directly in the session filenames, and migrates these files into organized subdirectories categorized by year and month (e.g., 2026/01/). It is designed to be highly reliable, ensuring that only valid files are moved while leaving your project structure clean and manageable.

• Automatically organizes markdown files by parsing timestamps from session filenames.

• Prevents clutter in the root history directory by creating a scalable YYYY/MM folder tree.

• Supports a dry-run execution mode, allowing you to preview file movements before any actual disk changes occur.

• Compatible with diverse environments where Claude Code, Cursor, or similar CLI-based AI coding agents are deployed.

• Safe for use on large history datasets; only moves files once and skips already-organized content.

• Ideal for developers who frequently use AI coding assistants and require a simplified archive strategy for their interaction logs.

• To run the organization process, invoke the slash command /specstory-organize or use the Python script directly from the project root.

• Use the --dry-run argument during execution to safely audit which files will be affected before committing to the file system changes.

• Note that the skill relies on the timestamp format within the filename itself rather than the operating system's file modification time, ensuring consistency across different file systems.

• Files that lack a recognizable date pattern or are already organized into subdirectories will be safely ignored by the script to prevent accidental errors.

• The tool is designed to work in standard POSIX environments and is compatible with Python 2.7+ and 3.x installations.