@monzingo89/engineer-maxxing

Package-first repo intelligence tool for AI-heavy codebases.

Latest release: v1.0.6

Use this as a package (not a cloned template)

This repository is primarily maintained as the source for the npm package.

• ✅ Typical usage: run it via npx inside your target repository.
• ⚠️ Not the intended path: cloning this repo as your project base.

If you are developing the tool itself, clone this repo. If you are using the tool on your own codebase, use the package.

What this tool is for

This tool is built to help clean up messy repositories (especially ones heavily generated by AI models), and to keep durable development memory/context so work can resume smoothly after long gaps.

It is designed to:

• detect structure, smells, noise, and over-complication in dirty repos,
• maintain persistent context in anatomy + .cortex state files across sessions,
• allow a developer to leave and come back days later and continue from where work left off,
• stay efficient with token usage while scanning, learning, and handing off context.

Recommended workflow

1) Learn the repo and populate anatomy

Run the tool in the target repo to generate/refresh anatomy and context.

• First pass (clean start): use --fresh
• Subsequent passes: run without --fresh to preserve continuity

Outputs are written to:

• anatomy/BRAIN.md
• anatomy/EYES.md
• anatomy/EARS.md
• anatomy/NOSE.md
• anatomy/HANDS.md
• anatomy/SOUL.md
• anatomy/HEART.md
• .cortex/context.json
• .cortex/token-usage.json

2) Clean up what anatomy detects

Use anatomy as your cleanup queue:

• EYES: what exists (inventory, stack signals, integrations)
• NOSE: smells/risks/dead-code and safety issues
• EARS: over-complexity/noise and simplification direction
• SOUL: dependency health, docs map, integration docs, secret hygiene summary
• HANDS: progress/handoff continuity + token usage

Then apply fixes in your repo iteratively (small changes, re-run scanner, verify improvements).

Generate an actionable cleanup plan from current anatomy:

npx @monzingo89/engineer-maxxing clean-repo

This writes:

• anatomy/CLEANUP_PLAN.md (prioritized cleanup phases)
• anatomy/CLEANUP_DEAD_CODE_QUEUE.txt (full dead-code candidate queue when present)

You can also target another path:

npx @monzingo89/engineer-maxxing clean-repo --path /absolute/path/to/repo

3) Develop features without drift

Use:

• BRAIN for durable architecture/context and guardrails
• HEART for feature planning across visual/frontend/backend/database/infrastructure

This helps keep AI-assisted development aligned to standards and avoids repo drift over time.

4) Reorganize to industry-standard structure

Generate a reorganization plan that uses anatomy findings (including SRP/noise signals) and SOUL technology docs:

npx @monzingo89/engineer-maxxing reorganize-repo

This writes:

• anatomy/REORGANIZE_PLAN.md (phased reorganization strategy)
• anatomy/REORGANIZE_MOVE_MAP.md (source -> suggested target map)
• updated anatomy/HEART.md (reorganization execution plan across all HEART sections)

You can also target another path:

npx @monzingo89/engineer-maxxing reorganize-repo --path /absolute/path/to/repo

5) One-command pipeline (recommended for external npm users)

Run learn + clean + reorganize in a single command:

npx @monzingo89/engineer-maxxing setup-repo --fresh

Equivalent commands across CLIs:

npx @monzingo89/engineer-maxxing setup-repo --fresh
pnpm dlx @monzingo89/engineer-maxxing setup-repo --fresh
yarn dlx @monzingo89/engineer-maxxing setup-repo --fresh
bunx @monzingo89/engineer-maxxing setup-repo --fresh

If you want the pipeline to execute generated plans immediately:

npx @monzingo89/engineer-maxxing setup-repo --execute

Simulate execution first:

npx @monzingo89/engineer-maxxing setup-repo --execute --dry-run

Include dead-code quarantine during execution:

npx @monzingo89/engineer-maxxing setup-repo --execute --execute-dead-code

6) Execute generated plans (after clean-repo + reorganize-repo)

If you already ran clean-repo and reorganize-repo, execute their artifacts with:

npx @monzingo89/engineer-maxxing execute-repo

By default, execution now attempts to:

• apply move-map file moves,
• quarantine dead-code queue entries,
• clean unused dependencies from package.json (based on dependency audit),
• safely split large ("god") files above 500 lines when export-level extraction is safe.

Recommended first pass:

npx @monzingo89/engineer-maxxing execute-repo --dry-run

Optional dead-code quarantine execution:

npx @monzingo89/engineer-maxxing execute-repo --dead-code

Optional hard delete of dead-code queue entries:

npx @monzingo89/engineer-maxxing execute-repo --delete-dead-code

Quick start

Run in a repo root:

npx @monzingo89/engineer-maxxing

Start fresh (reset anatomy + local state first):

npx @monzingo89/engineer-maxxing --fresh

Anatomy behavior

• BRAIN.md is pre-seeded with code-agnostic engineering principles.
• EYES, EARS, NOSE, HANDS, SOUL, HEART start empty (header only).
• Initial scan populates observations and dependency audit (SOUL).
• HEART is reserved for feature planning and is not populated by the initial scan.

Core capabilities

• Real-time token usage and model handoff at threshold.
• Resume-aware learning using persistent .cortex/context.json.
• Container signal detection (Docker, Compose, AKS, ACA, Kubernetes).
• Technology detection with docs links.
• Architecture summary + pattern inference (DDD/multi-tenant/identity/database).
• Symbol inventory and dead-code candidate detection.
• Dependency health audit and unused dependency identification.

CLI options

• --path <repoPath>: explicit repository path.
• --fresh: reset anatomy and local cortex state before scanning.
• --max-file-bytes <bytes>: file bytes sent to prompts (default: 20000).
• --include-ext ".toml,.env": add extensions to scan.
• --exclude-dir "tmp,artifacts": add directories to skip.
• --repo-models "Codex,ChatGPT,Gemini": declare repo authorship models.
• --quiet: minimal output.
• --verbose: detailed per-file output.
• --json-summary: machine-readable summary.

clean-repo subcommand

• clean-repo [repoPath]: generate an actionable cleanup plan using anatomy + .cortex/context.json.
• clean-repo --path <repoPath>: explicit repository path.
• clean-repo --quiet: suppress output.
• clean-repo --json-summary: machine-readable summary.

reorganize-repo subcommand

• reorganize-repo [repoPath]: generate a SIMPLIFY_REPO reorganization plan using anatomy + SOUL docs.
• reorganize-repo --path <repoPath>: explicit repository path.
• reorganize-repo --quiet: suppress output.
• reorganize-repo --json-summary: machine-readable summary.

setup-repo subcommand

• setup-repo [repoPath]: run LEARN_REPO + CLEAN_REPO + REORGANIZE_REPO in one command.
• setup-repo --path <repoPath>: explicit repository path.
• setup-repo --fresh: reset anatomy/context before running full pipeline.
• setup-repo --max-file-bytes <bytes>: learn-pass file bytes cap.
• setup-repo --include-ext ".toml,.env": add file extensions for learn pass.
• setup-repo --exclude-dir "tmp,artifacts": add excluded directories for learn pass.
• setup-repo --repo-models "Codex,ChatGPT,Gemini": declare repo authorship models.
• setup-repo --quiet: suppress output.
• setup-repo --verbose: verbose learn output.
• setup-repo --execute: apply generated plans after planning phases.
• setup-repo --dry-run: simulate execution when combined with --execute.
• setup-repo --execute-dead-code: quarantine dead-code queue entries when combined with --execute.
• setup-repo --execute-delete-dead-code: delete dead-code queue entries when combined with --execute.
• setup-repo --execute-max-file-lines <count>: line threshold for safe god-file splitting.
• setup-repo --execute-max-operations <count>: cap execution operations per run.
• setup-repo --no-execute-split-god-files: disable god-file splitting during execution.
• setup-repo --no-execute-cleanup-deps: disable dependency cleanup during execution.
• setup-repo --json-summary: machine-readable summary.

execute-repo subcommand

• execute-repo [repoPath]: apply generated clean/reorganize artifacts.
• execute-repo --path <repoPath>: explicit repository path.
• execute-repo --dry-run: simulate without applying changes.
• execute-repo --dead-code: quarantine entries from anatomy/CLEANUP_DEAD_CODE_QUEUE.txt.
• execute-repo --delete-dead-code: delete entries from anatomy/CLEANUP_DEAD_CODE_QUEUE.txt.
• execute-repo --max-file-lines <count>: line threshold for safe god-file splitting (default 500).
• execute-repo --no-split-god-files: disable god-file splitting.
• execute-repo --no-cleanup-deps: disable dependency cleanup from dependency audit.
• execute-repo --max-operations <count>: cap changes per run.
• execute-repo --quiet: suppress output.
• execute-repo --json-summary: machine-readable summary.

For maintainers (this repo)

If you are contributing to the package itself:

npm run build
npm run test

Workflow aliases for local development:

• npm run workflow:learn
• npm run workflow:clean
• npm run workflow:reorganize
• npm run workflow:execute
• npm run workflow:setup

Funding ❤️

If this project helps you clean up AI-generated repositories and keep long-running context stable, please consider sponsoring ongoing development.

• GitHub Sponsors: https://github.com/sponsors/Monzingo89

Publishing (dual registry)

This package can be published to both registries:

• npmjs: https://registry.npmjs.org
• GitHub Packages: https://npm.pkg.github.com

Scripts:

• npm run publish:npmjs
• npm run publish:github
• npm run publish:dual
• npm run release:patch:dual
• npm run release:minor:dual

Required auth:

• npmjs publish requires NODE_AUTH_TOKEN (or npm login) for npmjs.
• GitHub Packages publish requires NODE_AUTH_TOKEN with write:packages scope (or GitHub Actions GITHUB_TOKEN with packages write permission).

License

MIT — see LICENSE.