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".

Best use case

specstory-organize is best used when you need a repeatable AI agent workflow instead of a one-off prompt.

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".

Teams using specstory-organize should expect a more consistent output, faster repeated execution, less prompt rewriting.

When to use this skill

  • You want a reusable workflow that can be run more than once with consistent structure.

When not to use this skill

  • You only need a quick one-off answer and do not need a reusable workflow.
  • You cannot install or maintain the underlying files, dependencies, or repository context.

Installation

Claude Code / Cursor / Codex

$curl -o ~/.claude/skills/specstory-organize/SKILL.md --create-dirs "https://raw.githubusercontent.com/organvm-iv-taxis/a-i--skills/main/distributions/claude/skills/specstory-organize/SKILL.md"

Manual Installation

  1. Download SKILL.md from GitHub
  2. Place it in .claude/skills/specstory-organize/SKILL.md inside your project
  3. Restart your AI agent — it will auto-discover the skill

How specstory-organize Compares

Feature / Agentspecstory-organizeStandard Approach
Platform SupportNot specifiedLimited / Varies
Context Awareness High Baseline
Installation ComplexityUnknownN/A

Frequently Asked Questions

What does this skill do?

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".

Where can I find the source code?

You can find the source code on GitHub using the link provided at the top of the page.

SKILL.md Source

# 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

Related Skills

specstory-yak

5
from organvm-iv-taxis/a-i--skills

Analyze your SpecStory AI coding sessions in .specstory/history for yak shaving - when your initial goal got derailed into rabbit holes. Run when user says "analyze my yak shaving", "check for rabbit holes", "how distracted was I", or "yak shave score".

specstory-session-summary

5
from organvm-iv-taxis/a-i--skills

Summarize recent SpecStory AI coding sessions in standup format. Use when the user wants to review sessions from .specstory/history, prepare for standups, track work progress, or understand what was accomplished.

specstory-project-stats

5
from organvm-iv-taxis/a-i--skills

Fetch project statistics from SpecStory Cloud. Run when user says "get project stats", "show SpecStory stats", "project statistics", "how many sessions", or "SpecStory metrics".

specstory-link-trail

5
from organvm-iv-taxis/a-i--skills

Track all URLs fetched during SpecStory AI coding sessions. Run when user says "show my link trail", "what URLs did I visit", "list fetched links", or "show web fetches".

specstory-guard

5
from organvm-iv-taxis/a-i--skills

Install a pre-commit hook that scans .specstory/history for secrets before commits. Run when user says "set up secret scanning", "install specstory guard", "protect my history", or "check for secrets".

taxonomy-modeling-design

5
from organvm-iv-taxis/a-i--skills

Phase 2 of the pentaphase structural-overhaul protocol. Classifies entities, standardizes attributes, establishes relationships, and designs the access framework. Use when the user invokes phase 2 of an overhaul, asks to "design the taxonomy" or "model the structure", or has completed a landscape audit and is ready to redesign. Consumes phase-1-landscape-report.md; produces phase-2-taxonomy-model.md.

systemic-ingestion-normalization

5
from organvm-iv-taxis/a-i--skills

Phase 4 of the pentaphase structural-overhaul protocol. Purges redundancies, enriches and aligns legacy entities to the new schema, executes phased ingestion into the new environment, and audits integrity. Use when the user invokes phase 4 of an overhaul, asks to "migrate the data" or "ingest into the new system", or has a configured environment ready to accept legacy entities. Consumes phase-3-environment-spec.md; produces phase-4-ingestion-report.md.

system-environment-configuration

5
from organvm-iv-taxis/a-i--skills

Phase 3 of the pentaphase structural-overhaul protocol. Translates the taxonomy model into objective technical criteria, evaluates candidate mechanisms or frameworks, instantiates the chosen architecture, and programs validation rules. Use when the user invokes phase 3 of an overhaul, asks to "select a system" or "configure the environment", or has a taxonomy model and is ready to choose technology. Consumes phase-2-taxonomy-model.md; produces phase-3-environment-spec.md.

pentaphase-orchestrator

5
from organvm-iv-taxis/a-i--skills

Threads the full five-phase structural-overhaul protocol — landscape discovery, taxonomy design, environment configuration, systemic ingestion, governance evolution — for any substrate the user names. Use when the user requests a structural overhaul, system redesign, or end-to-end restructuring of a documentation system, asset registry, code monorepo, knowledge base, or operational workflow; or when they explicitly invoke the pentaphase methodology. Coordinates handoffs between phase-skills and seats validation gates between phases.

landscape-discovery-audit

5
from organvm-iv-taxis/a-i--skills

Phase 1 of the pentaphase structural-overhaul protocol. Inventories assets, maps current flow, identifies friction, and defines value metrics for any substrate. Use when the user invokes phase 1 of an overhaul, requests a baseline audit, asks to "discover the landscape" of a system, or wants to understand current state before redesigning. Produces phase-1-landscape-report.md.

governance-evolution-protocol

5
from organvm-iv-taxis/a-i--skills

Phase 5 of the pentaphase structural-overhaul protocol. Codifies operational protocols, onboards the ecosystem of participants, programs behavior monitoring, and establishes an iteration cadence so the substrate evolves rather than calcifies. Use when the user invokes phase 5 of an overhaul, asks to "establish governance" or "lock in the protocols", or has completed ingestion and is ready to declare the substrate operational. Consumes phase-4-ingestion-report.md; produces phase-5-governance-charter.md, which closes the protocol.

dimension-surfacing

5
from organvm-iv-taxis/a-i--skills

Surfaces the parallel domain dimensions implicit in a dense or minimal prompt. Use when a user prompt is small on the surface but plainly implies multiple independent domains needing different expertise; when explicitly invoked by the coliseum-orchestrator skill as Phase 1; or when the user asks "what dimensions does this prompt encode" or "what axes does this break into." Produces a named dimension set where each dimension is independently executable and not a paraphrase of another.