What M21 is trying to prove
A software project can be easier to understand and safer to change when its structure is captured in a small set of living artifacts:
Specs describe intent
A spec explains what a module owns, what it depends on, and what it deliberately does not own.
Features define contracts
Gherkin scenarios describe the observable behavior a module offers to the rest of the system.
Dependencies are explicit
A module should not just depend on another module; it should say which capabilities it relies on.
Tests close the loop
Passing scenarios make the spec executable instead of aspirational.
Why this matters
Modern codebases often fail quietly. The code may still run, but the architecture becomes implicit, onboarding becomes oral tradition, tests drift from intent, and changes become risky because nobody can see the contracts between parts.
M21 aims to make those contracts durable. A maintainer should be able to open a project and quickly answer what the major modules are, what each one promises, what each one depends on, which behavior is tested, where the risky relationships are, and what is safe to change.
Principles
Understandable by default
The primary audience is a human maintainer. Specs should be readable without knowing the implementation language or file layout.
Contracts over vibes
A graph edge is more valuable when it says why the relationship exists.
Living documentation
Specs, features, test results, and the graph should reinforce each other instead of drifting apart.
Professional software hygiene
Clean boundaries, explicit responsibilities, reproducible tests, and visible risk help teams keep leverage over time.
The long-term direction
- Describe the system as modules and contracts.
- Visualize the relationships and risks.
- Bind behavior to executable scenarios.
- Use tooling and agents to safely evolve the system from the specs.
- Keep documentation, tests, and implementation from drifting apart.
The experiment succeeds if M21 helps builders move faster without making the system harder to understand later.
Read the source version in VISION.md.