The key words MUST, MUST NOT and SHOULD are to be interpreted as described in RFC 2119.
Definition
Microwise Development (MWD) builds software as small packages, each in its own repository, that depend on each other only through published, versioned releases. It was designed for working with AI coding agents, including several agents working in parallel. Each part can be developed, measured, replaced or retired on its own, and changes move between parts one release at a time.
Origin
First drafted by Sisung Kim (crimson206) in 2024 to make codebases easier for AI coding tools to work on, by keeping modules small (micro-level modules). First published on 2024-07-03 (github.com/crimson206/micro-wise-development). This page (v0.1) is the canonical definition.
Core rules
- R1. One repo = one package. Each package MUST live in its own repository. One package name MUST map to exactly one repository and one publisher.
- R2. Depend only on published releases. A package MUST depend on another package only through a published, versioned release. Workspace links (
workspace:*), path dependencies (file:) and symlinks between packages MUST NOT be used.
Principles
- Changes reach consumers only as new releases. A change MUST NOT reach a consumer except as a new release; each consumer moves only when it changes its own declared version or lockfile.
- Each repository records its own reasons. A repository SHOULD state in its own commits why it changed, including why it took a given version; the version pin is the link between histories.
- A package is small and single-purpose. A package SHOULD be small enough for one owner to hold its whole scope and SHOULD do one thing; when it outgrows that, it SHOULD be split.
- Deploy only what was released. A deployment MUST use a published release pinned to an exact version, never a working tree.
- One active owner per repository. At any time, a repository MUST have exactly one owner making changes in it.
Version stairs
Releases form a staircase: each version is a step, and every consumer stands on the step that its own declaration and lockfile resolve to. This is the mechanism that connects packages in MWD.
- Each consumer moves at its own pace. A new release does not move anyone by itself. Consumers step up when they are ready, one at a time, so adoption is gradual and there is no big-bang switch.
- A consumer's dependencies change only when the consumer changes them. The declared version or range (for example
^1.4.0) and the lockfile together decide which release the consumer gets, so what it builds against stays put while it iterates. - Several versions can run side by side. With a shared core held at one pinned version, different consumers or experiments can take different versions of another package in parallel, and each result can be compared, kept or dropped on its own.
Terms
- Package — a unit of code with one name and one purpose, published as releases.
- Repository — the version-controlled home of exactly one package, with its own history.
- Owner — the person or agent responsible for a package's whole scope at a given time.
- Release — an immutable, published build of a package, identified by a version.
- Version — the identifier of a release (for example
1.4.2). - Dependency — a package that another package declares it needs.
- Consumer — a package or deployment that depends on another package.
- Version pin — the version or range a consumer declares for a dependency; together with the lockfile it decides which release, that is which step of the staircase, the consumer gets.