ak-project-organization

name	ak:project-organization
description	Organize files, directories, and content structure in any project. Use when creating files, determining output paths, organizing existing assets, or standardizing project layout.
user-invocable	true
when_to_use	Invoke when deciding file paths or project layout.
category	utilities
keywords	["files","directories","structure","layout"]
argument-hint	[directories or files to organize]
metadata	{"author":"agentkit","version":"2.0.0"}

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

Mode	Trigger	Behavior
Advisory	Other skills/agents reference this skill	Return correct path + naming for requested file type
Organize	User invokes directly with dirs/files	Scan → propose changes → execute after confirm

Core Rules

Rule 1 — Directory Categories

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

Category	Path	Purpose
Source code	src/ or project root	Application code (language-specific, not managed here)
Documentation	docs/	Human & AI readable docs, guides, specs
Plans	plans/	Implementation plans, research, agent reports
Tests	tests/ or test/	Test suites (unit, integration, e2e)
Scripts	scripts/	Build, deploy, utility scripts
Assets	assets/{type}/	Media, branding, designs, generated content
Config	Root or .config/	dotfiles, config files, env files
Guides	guide/ or guides/	User-facing reference docs, tutorials

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:

Mode	Pattern	When to use	Examples
Timestamped	{YYMMDD-HHmm}-{slug}	Time-sensitive: plans, reports, journals, sessions	260304-1530-auth-plan
Evergreen	{slug}	Stable docs, configs, guides	system-architecture.md
Variant	{slug}-{variant}.{ext}	Multiple versions of same asset	logo-dark.svg, hero-1920x1080.png

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 $CK_PLAN_DATE_FORMAT env var or default YYMMDD-HHmm.

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

Code file naming: Defer to descriptive-name hook — 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:

Scenario	Pattern	Example
Single file output	Flat file in category dir	docs/journals/260304-session-review.md
Multi-file output	Self-contained subdirectory	plans/260304-auth-impl/plan.md + phase-01-*.md
Scoped to parent	Nested under parent context	plans/260304-auth-impl/reports/scout-report.md
Platform-specific	Platform subdirectory	assets/posts/twitter/, assets/posts/linkedin/
Variant-based	Flat with variant suffix	logo-light.svg, logo-dark.svg

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:

Type	Key sections
Plan	frontmatter → overview → phases with status → dependencies → success criteria
Phase	context links → overview → requirements → architecture → impl steps → todo checklist → risks
Report	frontmatter → summary → findings → recommendations → unresolved questions
Journal	frontmatter → context → what happened → reflection → decisions → next
Doc	title → overview → content sections → references
ADR	status → context → decision → consequences → alternatives considered
Changelog	version blocks → categories (added/changed/fixed/removed/deprecated)
README	name → badges → description → quick start → usage → contributing → license
Guide	title → prerequisites → step-by-step → troubleshooting → FAQ
Spec	overview → requirements → constraints → API/interface → acceptance criteria

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 /ak: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 / ai-multimodal → assets/generated/
• media-processing → assets/videos/, assets/images/
• git → respects all naming conventions
• descriptive-name hook → code file naming (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