Hs:project Organization

Project Organization

Standardize file locations, naming conventions, directory structures, and markdown content templates for any project type.

When to Use

• Creating any file that needs a consistent output path
• Organizing existing project files and directories
• Determining where to save plans, reports, docs, assets, tests
• Enforcing naming conventions across the project
• Structuring markdown content (plans, journals, reports, docs)

Modes

Core Rules

Rule 1 — Directory Categories

Every project file belongs to one of these top-level categories:

Subcategories within each:

docs/
├── journals/                  # Technical diary, session reflections
├── decisions/                 # ADRs (Architecture Decision Records)
└── *.md                       # Evergreen docs (architecture, standards, roadmap)

plans/
├── {date-slug}/               # Timestamped plan folders
│   ├── plan.md                # Overview
│   ├── phase-{NN}-{name}.md   # Phase details
│   ├── research/              # Research materials for this plan
│   └── reports/               # Agent reports scoped to this plan
├── reports/                   # Standalone agent reports (not plan-scoped)
├── templates/                 # Reusable plan templates
└── visuals/                   # Generated diagrams, previews

assets/
├── images/                    # Static images, screenshots
├── videos/                    # Video files
├── designs/                   # UI/UX designs, mockups
├── branding/                  # Logos, brand assets
├── generated/                 # AI-generated content
└── {custom-type}/             # Project-specific asset categories

Rule 2 — Naming Patterns

All filenames use kebab-case, self-documenting names.

Three naming modes based on content temporality:

Slug rules:

• Lowercase, hyphens only (no underscores, spaces, special chars)
• Max 50 chars (truncate at word boundary)
• Self-documenting: readable without opening the file
• No leading/trailing hyphens

Date format: Use $HS_PLAN_DATE_FORMAT env var or default YYMMDD-HHmm.

date +%y%m%d-%H%M   # run_shell capability

Code file naming: kebab-case for JS/TS/Python/Shell, PascalCase for C#/Java/Swift, snake_case for Go/Rust.

Rule 3 — Nesting Logic

Decide between flat file vs folder based on output count:

Empty directories: Add .gitkeep to preserve in git.

Rule 4 — Markdown Body Standards

Every markdown file MUST have consistent structure based on its type.

Universal rules for all markdown:

• Start with a # Title (H1)
• Use frontmatter (---) for metadata when the file is consumed by tools
• Keep sections ordered: context → content → next steps
• Use tables for structured data, lists for sequences
• Sacrifice grammar for concision

Quick reference — required sections by type:

Load: references/markdown-body-templates.md for full templates.

Rule 5 — Path Resolution Decision Tree

When creating a new file, follow this decision tree:

1. Is it source code?
   → YES: src/ or project root (follow language conventions)
   → NO: continue

2. Is it a test?
   → YES: tests/ (mirror source structure)
   → NO: continue

3. Is it an implementation plan or agent output?
   → Plan: plans/{date-slug}/
   → Agent report (plan-scoped): plans/{date-slug}/reports/
   → Agent report (standalone): plans/reports/
   → Research: plans/{date-slug}/research/ or plans/research/
   → NO: continue

4. Is it documentation for humans/AI?
   → Technical journal: docs/journals/{date-slug}.md
   → Architecture decision: docs/decisions/{date-slug}.md
   → Evergreen doc: docs/{slug}.md
   → NO: continue

5. Is it a media/design/brand asset?
   → assets/{type}/{naming-per-rule-2}
   → NO: continue

6. Is it a utility script?
   → scripts/{slug}.{ext}
   → NO: continue

7. Is it configuration?
   → Root or .config/ (follow ecosystem conventions)

Organize Mode Actions

When invoked directly with /hs:project-organization [targets]:

1. Scan — List all files in target dirs, categorize by type
2. Analyze — Check naming violations, misplaced files, inconsistencies
3. Propose — Present a migration plan (from → to) as a table
4. Confirm — Ask user approval before any moves
5. Execute — Move/rename files, create missing directories
6. Verify — List final structure, flag any remaining issues

Safety:

• Never overwrite existing files (prompt on conflict)
• Never touch .git/, node_modules/, .env files
• Create backups when renaming (git handles this)
• Respect .gitignore patterns

File Type Reference

Load: references/directory-patterns.md for detailed patterns per category. Load: references/naming-conventions.md for slug generation, date formats, variant naming.

Integration

This skill is the single source of truth for file organization. Other skills reference it when determining output paths:

• plan / brainstorm → plans/ structure
• journal → docs/journals/
• cook / fix → source code paths (defer to language conventions)
• test → tests/ structure
• docs / docs-manager → docs/ structure
• scout / research → plans/reports/ or plans/{plan}/research/
• code-review → plans/reports/
• project-management → docs/ + plans/
• ui-ux-designer / frontend-design → assets/designs/
• ai-artist / codex → assets/generated/
• media-processing → assets/videos/, assets/images/
• git → respects all naming conventions
• Code file naming → per-language conventions (JS/TS/Python/Shell = kebab-case)

Pre-Output Checklist

Before writing any file:

1. Determine category → get base path (Rule 1)
2. Choose naming mode → timestamped/evergreen/variant (Rule 2)
3. Decide nesting → flat or subdirectory (Rule 3)
4. Apply body template if markdown (Rule 4)
5. Check if file/folder exists (avoid overwrite)
6. Create directory structure if needed