playbooks

home / skills / zenobi-us / dotfiles / storage-function-structure

storage-function-structure skill

/ai/files/skills/projectmanagement/storage-function-structure

This skill defines and enforces a clear storage function structure to organize artifacts and accelerate project planning.

npx playbooks add skill zenobi-us/dotfiles --skill storage-function-structure

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
1.7 KB
---
name: storage-function-structure
description: Define the structure and organization of storage functions within a project.
---

# File Structure for Project Planning Artifacts

- [Planning Artifact] are stored in dedicated directories based on their type, with each file named using a short hash and a descriptive title.
- These directories are typically stored in a parent folder. defer to the storage backend conventions for exact paths.

## Directory and File Naming Conventions

- Each planning artifact type has its own directory:
  - `Prd/` for Product Requirements Documents
  - `Epic/` for Epics
  - `Spec/` for Specifications
  - `Story/` for User Stories
  - `Task/` for Tasks
  - `Decision/` for Decisions
  - `Research/` for Research Documents
  - `Retro/` for Retrospectives
  
- Files within these directories are named using the format:
  - `<short-hash>-<descriptive-title>.md`

```
Prd/
  feca343-the-prd-title.md
Epic/
  123e4567-an-epic-title.md
Spec/
  89ab0123-a-spec-title.md
Story/
  456def78-a-story-title.md
  321cba98-another-story-title.md
  334fed56-yet-another-story-title.md
Task/
  789abc12-a-task-title.md
  654ghi34-another-task-title.md
  987jkl56-yet-another-task-title.md
Decision/
  112mno78-a-decision-title.md
  223pqr90-another-decision-title.md
  334stu12-yet-another-decision-title.md
  fff44455-a-fourth-decision-title.md
Ressearch/
  445vwx34-a-research-title.md
  556yzb56-another-research-title.md
  667abc78-yet-another-research-title.md
  778def90-a-fourth-research-title.md
Retro/
  889ghi12-a-retro-title.md
  990jkl34-another-retro-title.md
  aabmno56-yet-another-retro-title.md
  bbcpqr78-a-fourth-retro-title.md
  ccdstu90-a-fifth-retro-title.md
```

Overview

This skill defines a clear structure and naming convention for storage functions that manage planning artifacts in a project. It prescribes dedicated directories per artifact type and a short-hash + descriptive-title filename pattern to ensure consistency and easy lookup. The guidance adapts to the target storage backend while keeping logical organization stable across environments.

How this skill works

The skill inspects the set of planning artifact types and enforces one directory per type (e.g., Prd, Epic, Spec, Story, Task, Decision, Research, Retro). It validates file names follow the <short-hash>-<descriptive-title>.md pattern and maps those directories into the configured storage backend using backend conventions for paths. It can be used to generate folder templates, validate existing layouts, and produce migration plans when reorganizing storage.

When to use it

  • When standardizing how planning artifacts are stored across a team or org
  • When integrating a project into a new storage backend or provisioning system
  • When validating repositories for consistent naming and discoverability
  • When automating backups, syncs, or migrations of planning documents
  • When onboarding contributors who need predictable locations for artifacts

Best practices

  • Keep one directory per artifact type to simplify access control and discovery
  • Use a short hash prefix for filenames to avoid collisions and allow safe renames
  • Use hyphenated, lowercase descriptive titles for readability and URL-friendliness
  • Defer to the storage backend for absolute paths; keep the logical layout consistent across environments
  • Automate validation checks in CI to catch naming and placement errors early

Example use cases

  • Provision a fresh project workspace with Prd/, Epic/, Spec/, Story/, Task/, Decision/, Research/, and Retro/ directories
  • Run a validator to find files that do not follow the <short-hash>-<descriptive-title>.md convention
  • Migrate existing planning artifacts into the standardized layout while preserving history and hashes
  • Create sync scripts that mirror just the artifact directories to a remote storage backend
  • Generate an index or catalog by scanning directories and extracting metadata from filenames

FAQ

What length should the short hash be?

Use a short, collision-resistant hash (6–8 hex characters) that balances uniqueness and readability.

How do I handle artifacts that belong to multiple types?

Duplicate the artifact into each logical directory with cross-reference links, or keep a single canonical file and use lightweight pointers or metadata in the other directories.