npx claudepluginhub pjt222/agent-almanacThis skill uses the workspace's default tool permissions.
---
Audits project health with three passes: architectural compliance (files in right layers), filesystem hygiene (loose/misplaced files), bloat detection (oversized/binaries). Reports score, manages directory manifests.
Safely scans, previews, and reorganizes project structure with read-only analysis, dry-runs, user confirmations, and protections for git, node_modules, secrets, and builds.
Optimizes project structure, config files, and tools to make productive actions obvious and errors invisible. Use for project setup, codebase audits, or reducing dev workflow friction.
Share bugs, ideas, or general feedback.
Use this skill when project organization has drifted from conventions:
Do NOT use for code refactoring or dependency restructuring. This skill focuses on file organization and documentation hygiene.
| Parameter | Type | Required | Description |
|---|---|---|---|
project_path | string | Yes | Absolute path to project root |
conventions | string | No | Path to style guide (e.g., docs/conventions.md) |
archive_mode | enum | No | move (default) or delete for deprecated files |
readme_update | boolean | No | Update stale READMEs (default: true) |
Compare current structure against project conventions or language best practices.
Common conventions by language:
JavaScript/TypeScript:
src/ # Source code
tests/ # Test files
dist/ # Build output (gitignored)
docs/ # Documentation
.github/ # CI/CD workflows
Python:
package_name/ # Package code
tests/ # Test suite
docs/ # Sphinx docs
scripts/ # Utility scripts
R:
R/ # R source
tests/testthat/ # Test suite
man/ # Documentation (generated)
vignettes/ # Long-form guides
inst/ # Installed files
data/ # Package data
Rust:
src/ # Source code
tests/ # Integration tests
benches/ # Benchmarks
examples/ # Usage examples
Expected: List of files/directories violating conventions saved to structure_audit.txt
On failure: If no conventions documented, use language-standard defaults
Relocate files to their conventional directories.
Common moves:
tests/ → move to tests/docs/ → move to docs/src/ → delete (should be gitignored)config/ or .config/For each move:
# Check if file is referenced anywhere
grep -r "filename" .
# If no references or only relative path references:
mkdir -p target_directory/
git mv source/file target_directory/file
# Update any imports/requires
# (language-specific — see repair-broken-references skill)
Expected: All files in conventional locations; git history preserved via git mv
On failure: If moving breaks imports, update import paths or escalate
Identify stale information in all README files.
Staleness indicators:
# Find all READMEs
find . -name "README.md" -o -name "readme.md"
# For each README:
# - Check last modified date
git log -1 --format="%ci" README.md
# - Check for broken links
markdown-link-check README.md
# - Verify example code still runs (sample first example)
Expected: List of stale READMEs in readme_freshness.txt with specific issues
On failure: If markdown-link-check unavailable, manually review external links
Fix broken links, update examples, add missing sections.
Standard fixes:
README template structure:
# Project Name
Brief description (1-2 sentences).
## Installation
```bash
# Language-specific install command
# Basic example
Link to full docs.
Link to CONTRIBUTING.md or inline guidelines.
LICENSE badge and link.
**Expected:** All READMEs updated; examples verified to run
**On failure:** If example code cannot be verified, mark with warning comment
### Step 5: Review Config Files
Identify configuration drift and consolidate duplicate settings.
**Common config issues**:
1. Multiple `.env` files (`.env`, `.env.local`, `.env.dev`, `.env.prod`)
2. Duplicate settings across config files
3. Hardcoded secrets (should use environment variables)
4. Outdated API endpoints or feature flags
```bash
# Find all config files
find . -name "*.config.*" -o -name ".env*" -o -name "*.yml" -o -name "*.yaml"
# For each config:
# - Check for duplicate keys
# - Grep for hardcoded secrets (API keys, tokens, passwords)
grep -E "(api[_-]?key|token|password|secret)" config_file
# - Compare dev vs prod settings
diff .env.dev .env.prod
Expected: Config drift documented in config_review.txt; secrets flagged for escalation
On failure: If diff shows major divergence, escalate to devops-engineer
Move or delete files no longer needed.
Candidates for archiving:
nginx.conf.old)file.bak, file~)Archive process:
# Create archive directory (if archive_mode=move)
mkdir -p archive/YYYY-MM-DD/
# For each deprecated file:
# 1. Verify not referenced anywhere
grep -r "filename" .
# 2. Check git history for last modification
git log -1 --format="%ci" filename
# 3. If not modified in >1 year and no references:
if [ "$archive_mode" = "move" ]; then
git mv filename archive/YYYY-MM-DD/
else
git rm filename
fi
# 4. Document in ARCHIVE_LOG.md
echo "- filename (reason, last modified: DATE)" >> ARCHIVE_LOG.md
Expected: Deprecated files archived; ARCHIVE_LOG.md updated
On failure: If uncertain whether file is deprecated, leave in place and document in report
Check for inconsistent file naming across project.
Common conventions:
my-file.js (common in JS/web projects)my_file.py (Python standard)MyComponent.tsx (React components)myUtility.js (JavaScript functions)# Find files violating conventions
# Example: Python project expecting snake_case
find . -name "*.py" | grep -v "__pycache__" | grep -E "[A-Z-]"
# For each violation, either:
# 1. Rename to match conventions
# 2. Document exception (e.g., Django settings.py convention)
Expected: All files follow naming conventions or exceptions documented
On failure: If renaming breaks imports, update references or escalate
Document all structural changes.
# Project Structure Tidying Report
**Date**: YYYY-MM-DD
**Project**: <project_name>
## Directory Changes
- Moved X files to conventional directories
- Created Y new directories
- Archived Z deprecated files
## README Updates
- Updated W stale READMEs
- Fixed X broken links
- Verified Y code examples
## Config Cleanup
- Consolidated X duplicate settings
- Flagged Y hardcoded secrets for removal
- Documented Z config drift issues
## Files Archived
See ARCHIVE_LOG.md for full list (Z files).
## Naming Convention Fixes
- Renamed X files to match conventions
- Documented Y exceptions
## Escalations
- [Config drift requiring devops review]
- [Hardcoded secrets requiring security audit]
Expected: Report saved to TIDYING_REPORT.md
On failure: (N/A — generate report regardless)
After tidying:
git mv, not mv)Breaking Relative Imports: Moving files breaks relative import paths. Update all references or use absolute imports.
Losing Git History: Using mv instead of git mv loses file history. Always use git commands for moves.
Over-Organizing: Creating too many nested directories makes navigation harder. Keep it flat until complexity requires structure.
Deleting Instead of Archiving: Direct deletion loses ability to recover. Always archive first unless certain.
Ignoring Language Conventions: Imposing personal preferences over language standards. Follow established conventions.
Not Updating Documentation: Moving files without updating README paths leaves docs broken.