ModE · Modular Evolution

Build fast. Keep your project worth building on.

English · 繁體中文
Install · Try it · How it works · MIT license

Your coding agent can ship another feature, create another candidate, and install another environment. Over time, the harder question becomes: what should the next version reuse, and what can the previous one safely leave behind?

ModE is a Codex skill that brings modular reuse, rebuildability, and evidence-aware retirement into those decisions. It helps your agent preserve meaningful differences, make dependencies explicit, and keep valuable results without keeping every full working copy forever.

Force your agent to think modularly and keep the best of your software’s evolution.

Give fast iteration a longer memory

When iteration leaves you with…	ModE asks your agent to…
Several full candidates with a few meaningful differences	Keep one maintained source, preserve changes in Git, and use worktrees when concurrent work needs them.
Repeated dependency environments	Check compatibility and tool-managed reuse while preserving the isolation each environment needs.
A new version that still imports an old candidate	Make the shared dependency explicit, migrate its consumers, and verify the result before retirement.
Old folders mixing build output, private state, and useful failures	Separate what can be rebuilt from what must be retained, including counterexamples and recovery inputs.
A growing project with no clear retirement point	Give candidates a purpose, supported scope, consumers, and evidence-backed successor criteria.

Reuse deliberately. Preserve what matters. Retire with evidence.

These are decisions the skill guides your agent through. ModE is a text-based instruction package, with no runtime package dependencies, background service, or automatic cleanup job. Results depend on your agent, project, and verification.

Install

The documented target is Codex. The compact release bundle contains the skill and its operational references, without the hero artwork or Git history.

1. Open the v0.2.0 release and download modular-evolution-v0.2.0.zip and SHA256SUMS.txt.
2. Compare the ZIP’s SHA-256 with the checksum file. Use Get-FileHash on PowerShell, shasum -a 256 on macOS, or sha256sum on Linux.
3. Extract the included modular-evolution folder into your personal skills directory:
   • macOS / Linux: ~/.agents/skills/
   • Windows: %USERPROFILE%\.agents\skills\
4. Confirm the final layout is .agents/skills/modular-evolution/SKILL.md, without an extra nested folder. In Codex, select the skill or invoke $modular-evolution.

Updating an existing installation? Compare its provenance and local changes first. Keep one installed copy; do not overwrite custom work blindly. See host integration and the official Codex skills documentation for discovery and installation details.

Try it

Start with an inventory. Give the agent a concrete scope and keep the first action read-only:

Use $modular-evolution to inspect this repository and its candidate directories.
Identify duplicated environments, cross-candidate dependencies, rebuildable
output, and evidence that must be retained. Recommend one small next step.
Do not move, delete, refactor, or restart anything.

Use it before growth, too:

Use $modular-evolution to plan this feature before creating another full
project copy. Check what we can reuse, which boundaries need to change,
and whether an isolated worktree is actually necessary. Keep this to a plan.

For an authorized consolidation, name the selected unit, affected consumers, verification, and recovery boundary. A plan or inventory does not grant permission to modify or retire files.

A typical decision

Suppose candidate-b imports a helper from candidate-a, and the older folder also contains a unique crash reproducer.

The useful next step is to make that shared helper a maintained dependency, migrate its consumer, and verify the affected workflow without hidden reliance on the old path. Preserve the crash reproducer and its source mapping separately when that separation is justified. Only then consider the eligible parts of candidate-a for recoverable retirement.

This is an illustrative workflow, not a measured case study. A newer candidate may replace only part of an older one’s purpose.

How it works

ModE supplies five practical decisions. Apply the stages your task needs; a small change does not require the whole sequence.

1. Establish the outcome and current state. Inspect selected source, inputs, outputs, private state, consumers, evidence, and storage. Make scan gaps visible.
2. Choose the smallest reversible unit. Address one concrete source of growth. Extract a module when demonstrated coupling or repeated change justifies it.
3. Implement and verify within authority. Rebuild from pinned, obtainable inputs and check that the result no longer depends on paths proposed for retirement.
4. Establish supersession by scope. Verify which behaviors the successor actually covers. Preserve still-needed consumers, evidence, and recovery material.
5. Retire recoverably and report facts. Recheck paths, active use, preservation, and permission. Follow the host’s existing archive and retention rules.

The lifecycle can be as simple as an existing issue or small table:

active → superseded for a defined scope → eligible for retirement → archived

Evidence can remain pinned at any stage. No new registry or process framework is required.

Boundaries that matter

• Storage savings need measurement. Logical file size, allocated storage, and free capacity are different. Moving files to an archive on the same volume does not free that volume.
• Matching inputs are a clue, not a compatibility proof. Lockfiles and hashes alone do not establish compatible OS, CPU, ABI, toolchain, install effects, or private state. Worktrees and filesystem links have their own costs and risks.
• Preservation comes first. Necessary history, uncommitted work, unique evidence, credentials, private data, and recovery inputs do not become disposable because a folder looks old.
• Authority stays with the user and host. The skill does not authorize unrelated refactoring, restarting paused systems, permanent deletion, publication, or changes to retention policy.
• Verification stays proportional. Use the smallest check that can falsify the affected claim. Avoid speculative abstractions, mandatory full suites, and endless review loops.

Inside the skill

Read	For
SKILL.md	The compact operating instructions and quick decisions.
Inventory and retirement	What to inspect, preserve, verify, and report before consolidation or retirement.
Toolchains and Windows	Reuse considerations across Python, Node.js, Rust, Go, .NET, JVM, C/C++, containers, and Windows storage mechanisms.
Host integration	Installation, local policy, archives, and the distinction between source and installed copies.
Product decisions	Positioning, engineering foundations, related projects, and the limits of product claims.
Changelog	Release history.

ModE builds on familiar engineering practice: modular design, continuous refactoring, reproducible inputs, and deliberate artifact lifecycles. Related projects including Worktrunk, worktree-cleanup, and Agentdisk informed its approach. They are credited in the product decisions, and are not runtime dependencies.

Release scope

v0.2.0 is the first public release. Package structure, local references, installation bytes, and release-archive contents can be checked independently of agent behavior. Those checks do not establish automatic invocation, cross-host compatibility, or a particular amount of disk space saved. Other agent hosts have not been runtime-validated.

Have an improvement? Open an issue with the workflow, expected behavior, and a minimal example. Remove credentials, private paths, and personal data before sharing.

---

MIT licensed. The hero artwork is an original AI-generated conceptual illustration, not a product screenshot or evidence of measured savings.