# Specstory Organize

> Organize SpecStory AI coding sessions in .specstory/history into year/month folders. Run when user says "organize my history", "clean up specstory", "sort my sessions", or "organize specstory files".

- **Type:** Skill
- **Install:** `agentstack add skill-specstoryai-agent-skills-specstory-organize`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [specstoryai](https://agentstack.voostack.com/s/specstoryai)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [specstoryai](https://github.com/specstoryai)
- **Source:** https://github.com/specstoryai/agent-skills/tree/main/skills/specstory-organize
- **Website:** https://specstory.com/agent-skills

## Install

```sh
agentstack add skill-specstoryai-agent-skills-specstory-organize
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# SpecStory Organize

Organizes your `.specstory/history` directory by moving session files into `YYYY/MM/` subdirectories based on the timestamp in each filename.

## How It Works

1. **Scans** `.specstory/history/` for markdown files
2. **Extracts** the date from filenames (e.g., `2026-01-22_19-20-56Z-fix-bug.md`)
3. **Creates** year/month folders (e.g., `2026/01/`)
4. **Moves** files into the appropriate subdirectory
5. **Reports** what was moved

## Why Organize?

Over time, your history directory can accumulate hundreds of session files. Organizing by date makes it easier to:
- Find sessions from a specific time period
- Archive old sessions
- Keep your project directory clean

## Usage

### Slash Command

| User says | Action |
|-----------|--------|
| `/specstory-organize` | Organize all files (default) |
| `/specstory-organize dry run` | Preview changes without moving |
| `/specstory-organize --dry-run` | Preview changes without moving |

### Direct Script Usage

```bash
# From project root
python skills/specstory-organize/scripts/organize.py

# Preview what would be moved (no changes made)
python skills/specstory-organize/scripts/organize.py --dry-run
```

## Output

```
SpecStory History Organizer
===========================

Found 47 files to organize in .specstory/history/

Moving files:
  2026-01-15_10-30-22Z-refactor-auth.md -> 2026/01/
  2026-01-15_14-22-01Z-fix-tests.md -> 2026/01/
  2026-01-22_19-20-56Z-add-feature.md -> 2026/01/
  2025-12-28_09-15-33Z-cleanup.md -> 2025/12/
  ...

Summary:
--------
Files moved: 47
  2026/01/: 23 files
  2025/12/: 18 files
  2025/11/: 6 files

Your history is now organized!
```

## Dry Run Output

When using `--dry-run`:

```
SpecStory History Organizer (DRY RUN)
=====================================

Would organize 47 files in .specstory/history/

Preview:
  2026-01-15_10-30-22Z-refactor-auth.md -> 2026/01/
  2026-01-15_14-22-01Z-fix-tests.md -> 2026/01/
  ...

No files were moved. Run without --dry-run to apply changes.
```

## Present Results to User

After running the organize script:

1. **Confirm success** - Tell the user how many files were organized
2. **Show the breakdown** - List how many files went to each month
3. **Note any skips** - If files couldn't be parsed (no date in filename), mention them

### Example Response

```
Done! I organized 47 session files in your `.specstory/history/` directory:

- **2026/01/**: 23 files
- **2025/12/**: 18 files
- **2025/11/**: 6 files

Your history files are now sorted by year and month, making it much easier
to find sessions from specific time periods.
```

## Notes

- Files without a recognizable date pattern in the filename are skipped
- The script uses the filename timestamp, not the file's modification time
- Already-organized files (in subdirectories) are not moved again
- Compatible with Python 2.7+ and Python 3.x

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [specstoryai](https://github.com/specstoryai)
- **Source:** [specstoryai/agent-skills](https://github.com/specstoryai/agent-skills)
- **License:** Apache-2.0
- **Homepage:** https://specstory.com/agent-skills

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-specstoryai-agent-skills-specstory-organize
- Seller: https://agentstack.voostack.com/s/specstoryai
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.