Reorganize project files safely with ak:project-organization

Use ak:project-organization to decide where new artifacts belong or to reorganize existing files through a reviewable migration. The Skill offers general directory, naming, and Markdown patterns, but the repository's current conventions and tool ownership remain authoritative.

Choose advisory or organize mode deliberately

Use ak:project-organization when

• You need a consistent output path and name for a new plan, report, document, test, script, or asset.
• Existing files are misplaced, inconsistently named, or difficult to navigate.
• You want a proposed from → to migration before any move occurs.

Choose another workflow when

• You are changing source architecture rather than file organization. Use ak:plan first.
• A formatter, framework generator, or repository-specific script owns the layout.
• You only need to find files. Use ak:scout.
• The target includes generated, vendored, secret, or machine-owned content that should not be moved manually.

Prepare the repository and runtime

Read repository instructions, current directory conventions, ignore rules, build configuration, imports, links, and ownership markers. Preserve unrelated work and identify whether the request is advisory-only or authorizes moves.

Run the Skill

/ak:project-organization docs scripts "Audit naming and placement, preserve repository conventions and links, show a from-to table, and wait for approval before moving anything."

/ak:project-organization docs scripts "Audit naming and placement, preserve repository conventions and links, show a from-to table, and wait for approval before moving anything."

$ak:project-organization docs scripts "Audit naming and placement, preserve repository conventions and links, show a from-to table, and wait for approval before moving anything."

General fallbacks include docs/ for durable documentation, plans/<timestamp>-<slug>/ for multi-file plans, plans/reports/ for standalone reports, tests/ or test/ for tests, scripts/ for utilities, and assets/<type>/ for media. Apply them only when the project has no stronger convention.

Understand the observable stages

1. Scan: list target files and relevant surrounding structure without traversing excluded or protected areas.
2. Analyze: compare current placement, names, links, imports, and body shape with repository rules and only then with the Skill's fallback patterns.
3. Propose: present every move or rename as an explicit source and destination pair, including conflicts and required reference updates.
4. Confirm: wait for approval of the exact migration set. A request for an audit alone does not authorize execution.
5. Execute: create only necessary directories and apply approved moves or renames without overwriting a destination.
6. Verify: show final structure, changed references, repository status, and remaining violations or skipped targets.

Protect repository state

• Never overwrite an existing destination. Resolve each conflict explicitly.
• Do not touch .git/, node_modules/, or .env files, and respect .gitignore plus machine-owned directory markers.
• Prefer Git-aware moves in tracked repositories so rename evidence remains reviewable. A move does not authorize commit, push, or deletion of history.
• Existing ecosystem naming wins over the generic fallback. Do not rename Java, Go, Rust, framework, or generated files merely to force kebab-case.
• Empty-directory .gitkeep files should be added only when the repository intentionally tracks that directory.

Verify outputs and evidence

A complete advisory result names the proposed category, exact path, naming mode, and repository evidence that supports it. A complete organize run also provides the approved move table, conflicts resolved, directories created, references updated, final tree, git status, and focused validation results.

For Markdown, confirm the selected body structure matches the document's actual consumer. Plans, reports, journals, ADRs, guides, and specs have different templates; a generic template must not replace required frontmatter or site navigation rules.

Troubleshoot safely

Know the current limits

• The fallback taxonomy cannot infer undocumented team intent or replace framework, build, and package-manager conventions.
• Filesystem checks cannot prove a moved path is safe without relevant imports, links, tests, and build evidence.
• Cursor invocation evidence does not establish full filesystem parity.
• Stable and beta contain identical ak:project-organization source and reference templates.

Use ak:plan first when reorganization changes module boundaries, or ak:git after review when you explicitly want to commit the result.