Project Organization

Place files consistently without overriding established project conventions.

Modes

• Advisory: Return the recommended path and name when another skill or task needs an output location.
• Organize: When asked to reorganize targets, scan, propose a migration, obtain approval, execute, and verify.

Priority

1. Preserve explicit user requirements.
2. Follow existing repository and ecosystem conventions.
3. Apply this skill's defaults only where the project has no convention.

Path Rules

Content	Default location
Source	src/ or the ecosystem-standard project root
Tests	Existing test/ or tests/, mirroring source where practical
Documentation	docs/
Technical logs	docs/logs/
Architecture decisions	docs/decisions/
Plans	plans/{timestamp}-{slug}/
Plan-scoped research/reports	plans/{plan}/research/, plans/{plan}/reports/
Standalone research/reports	plans/research/, plans/reports/
Scripts	scripts/
Assets	assets/{type}/
User guides	Existing guide/ or guides/; otherwise docs/guides/
Configuration	Ecosystem-standard root path; .config/ only when supported

Read references/directory-patterns.md only when detailed layout guidance is needed.

Naming Rules

• Use a lowercase kebab-case, self-documenting slug, at most 50 characters.
• Timestamp time-sensitive plans, reports, logs, sessions, and generated content as {YYMMDD-HHmm}-{slug}.
• Leave evergreen docs, configs, guides, scripts, and source files untimestamped.
• Name variants {slug}-{variant}.{ext}.
• Follow the repository or language convention for code files instead of forcing kebab-case.
• Use $HI_PLAN_DATE_FORMAT when set; otherwise use YYMMDD-HHmm.

Read references/naming-conventions.md only for slug normalization and variant examples.

Nesting Rules

• Keep a single output flat in its category directory.
• Give a multi-file output a self-contained directory.
• Nest artifacts under their owning plan or feature context.
• Keep variants flat with suffixes; use platform subdirectories only for collections.
• Add .gitkeep only when an intentionally empty directory must be tracked.

Markdown Rules

• Use one H1 title.
• Add frontmatter only when a tool or workflow consumes it.
• Order content as context, main content, then next steps or unresolved questions.
• Use tables for structured comparisons and lists for sequences.
• Prefer concise, scannable prose.

Read references/markdown-body-templates.md only when creating a plan, phase, report, log, ADR, changelog, README, guide, or specification.

Resolve a New Output

1. Detect the file type and the project's existing convention.
2. Select the base path from the table above.
3. Choose timestamped, evergreen, or variant naming.
4. Choose flat or nested placement from the output count and ownership.
5. Apply a Markdown template when relevant.
6. Check for path conflicts before writing.

Organize Existing Files

1. Scan only the requested targets and categorize their files.
2. Identify misplaced files, naming violations, and inconsistent structure.
3. Present a from -> to migration table, including conflicts and tradeoffs.
4. Obtain user approval before moving or renaming anything.
5. Apply only approved changes.
6. Verify the final tree and report unresolved issues.

Safety

• Never overwrite an existing file; surface conflicts.
• Never modify .git/, dependency directories, secrets, or .env files.
• Respect .gitignore and preserve repository history with normal moves.
• Do not create categories or directories that the requested output does not need.