Tổ chức lại project file an toàn với ak:project-organization

Dùng ak:project-organization để quyết định nơi artifact mới nên nằm hoặc tổ chức lại file hiện có qua migration có thể review. Skill cung cấp general directory, naming và Markdown pattern, nhưng convention hiện tại cùng tool ownership của repository vẫn là authority.

Chọn advisory hoặc organize mode có chủ đích

Dùng ak:project-organization khi

• Bạn cần output path cùng name nhất quán cho plan, report, document, test, script hoặc asset mới.
• File hiện có đặt sai chỗ, đặt tên không nhất quán hoặc khó điều hướng.
• Bạn muốn proposed migration from → to trước khi move.

Chọn workflow khác khi

• Bạn thay đổi source architecture thay vì file organization. Dùng ak:plan trước.
• Formatter, framework generator hoặc repository-specific script sở hữu layout.
• Bạn chỉ cần tìm file. Dùng ak:scout.
• Target chứa generated, vendored, secret hoặc machine-owned content không nên move thủ công.

Chuẩn bị repository và runtime

Đọc repository instruction, current directory convention, ignore rule, build configuration, import, link và ownership marker. Giữ unrelated work và xác định request chỉ advisory hay cấp quyền move.

Chạy 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 fallback gồm docs/ cho durable documentation, plans/<timestamp>-<slug>/ cho multi-file plan, plans/reports/ cho standalone report, tests/ hoặc test/ cho test, scripts/ cho utility và assets/<type>/ cho media. Chỉ áp dụng khi project không có stronger convention.

Hiểu các giai đoạn có thể quan sát

1. Scan: liệt kê target file cùng surrounding structure liên quan mà không traverse excluded hoặc protected area.
2. Analyze: so sánh placement, name, link, import và body shape hiện tại với repository rule, rồi mới với fallback pattern của Skill.
3. Propose: trình bày mọi move hoặc rename thành cặp source và destination rõ ràng, gồm conflict cùng reference update cần thiết.
4. Confirm: chờ duyệt migration set chính xác. Yêu cầu audit không tự cấp quyền execution.
5. Execute: chỉ tạo directory cần thiết và áp dụng move hoặc rename đã duyệt mà không overwrite destination.
6. Verify: hiển thị final structure, changed reference, repository status và violation hoặc skipped target còn lại.

Bảo vệ repository state

• Không overwrite destination hiện có. Resolve từng conflict rõ ràng.
• Không chạm .git/, node_modules/ hoặc .env file; tôn trọng .gitignore cùng machine-owned directory marker.
• Ưu tiên Git-aware move trong tracked repository để rename evidence có thể review. Move không cấp quyền commit, push hoặc xóa history.
• Ecosystem naming hiện có thắng generic fallback. Không rename Java, Go, Rust, framework hoặc generated file chỉ để ép kebab-case.
• Chỉ thêm .gitkeep cho empty directory khi repository chủ động track directory đó.

Xác minh output và evidence

Advisory result hoàn chỉnh nêu proposed category, exact path, naming mode và repository evidence hỗ trợ. Organize run hoàn chỉnh còn cung cấp approved move table, conflict đã resolve, directory đã tạo, reference đã update, final tree, git status cùng focused validation result.

Với Markdown, xác nhận body structure đã chọn khớp consumer thực tế của document. Plan, report, journal, ADR, guide và spec có template khác nhau; generic template không được thay required frontmatter hoặc site navigation rule.

Xử lý sự cố an toàn

Biết các giới hạn hiện tại

• Fallback taxonomy không thể infer team intent chưa ghi hoặc thay thế framework, build cùng package-manager convention.
• Filesystem check không chứng minh moved path an toàn nếu thiếu import, link, test và build evidence liên quan.
• Bằng chứng cách gọi Cursor không thiết lập full filesystem parity.
• Stable và beta chứa source cùng reference template ak:project-organization giống nhau.

Dùng ak:plan trước khi organization làm đổi module boundary, hoặc ak:git sau review khi bạn rõ ràng muốn commit kết quả.