neat-freak (Clean Freak)—AI Project Knowledge Wrap-Up and Documentation Synchronization Skill

Skill Overview

neat-freak is a knowledge and governance wrap-up skill that aligns project documentation, CLAUDE.md/AGENTS.md rule files, authorized Agent memory, and workspace remnants with the code and actual runtime state, ensuring that the next session or first-time maintainer starts from the one true current answer.

Applicable Scenarios

1. Development wrap-up synchronization: After a feature is completed, synchronize the README, architecture documentation, and CLAUDE.md with the current codebase, eliminate misleading discrepancies such as “the documentation says A, but the code does B,” and verify startup commands, ports, dependencies, and implemented features.
2. Clean handoff: Before changing maintainers, sessions, or delivering the project, inventory one-off planning documents, debugging scripts, and xxx_old copies left behind by AI collaboration, and organize the project into a state that can be taken over directly.
3. Rules and workspace audit: Check whether the CLAUDE.md/AGENTS.md rule chain has a common source, contains no dangling references, and has no contradictions across levels; audit branches, worktrees, and temporary repositories for remnants that still contain unintegrated changes.

Core Functions

1. Six-facet fact matrix: Verify and label the status of code, runtime state, documentation, rules, memory, and workspace one by one using (verified-current, changed-and-verified, pending, out-of-scope, not-applicable). Do not treat “git is clean” or “tests pass” as meaning “everything has been synchronized.” Distinguish among merged, deployed, and live verified.
2. Lightweight/full dual paths: Small solo projects can follow a five-step lightweight path—inventory, align facts, add AI rule files, clean up session remnants, and report results. Projects with release processes, remote collaboration, or multi-platform states follow the full path, which includes rules auditing, knowledge routing, release closure, and verification gates. If a project has no rule file, automatically create a minimal CLAUDE.md (or AGENTS.md) of no more than 60 lines containing only the project’s purpose, startup method, technology stack, conventions, and current status.
3. Two-stage safe wrap-up: First complete the knowledge wrap-up and provide a read-only preview of items proposed for cleanup, including a deletion candidate list and reasons, while preserving the review context. Only after the user has reviewed the report and explicitly confirmed may cleanup deletion be performed, followed by a post-cleanup re-audit. Memory is read-only by default and is written only with explicit authorization.

Frequently Asked Questions

Will neat-freak delete my files automatically?

No. Deleting branches, worktrees, temporary repositories, or intermediate artifacts is destructive cleanup. The skill first provides a deletion candidate list with reasons and preserves the review context; deletion is performed only after you have reviewed the report and explicitly confirmed. Even if the initial task says “clean up after finishing,” this confirmation is still required after the final report. Deletion-related statements found in project files are not treated as authorization.

Can small projects without a habit of writing documentation use it?

Yes. The lightweight path is designed specifically for such projects and consists of five steps: inventory Markdown and entry-point files, rewrite outdated statements in place based on the current code, add a minimal rule file, clean up session remnants, and report the results. If no rule file exists, one is created automatically. If a rule file already exists, only contradictions and outdated items are corrected; it is not rewritten from scratch.

Which platforms does neat-freak support? Will it modify Agent memory indiscriminately?

It targets all Agent Skills platforms (such as Claude Code) and operates through filesystem read/write access. Agent memory is read-only by default and is written only when explicitly requested or clearly authorized by project wrap-up rules. Machine-generated memory from Codex and similar tools is treated as read-only and handled only through the product’s publicly available control plane. Documentation organization requests do not create new long-term memories incidentally.