Requirements of unifold#

What the standard must achieve, for whom, and which qualities win when they conflict.

Goals#

Explainable in one minute. A reader who knows what a folder and a dependency are understands the idea from the first page: a manifest per folder, needs that do not name their provider, wiring by the parent, a check, generated diagrams.
Adoptable in five. A repository gets a root manifest and a green check in minutes, and every further unit is one small file. Nothing is restructured and nothing is copied in.
One set of documents for people and agents. Whoever opens a folder, a newcomer, a maintainer, an end user or a coding agent, finds the same files in the same places and reads the same text. Nothing is written twice for a second audience, and nothing is kept outside the tree.
Checked, not promised. Everything the standard asks for is either checked by a tool or stated as a question for a reviewer. A clean check means that the files agree with each other. Whether the code follows them is for tests and review.
The standard is tried. Every rule is tried on the examples in this repository before a project has to follow it.

Rank	Quality	Observed as
1	Small normative surface	Everything normative about manifests, wiring and generated files fits one page of at most 200 lines.
2	Checkable	Every finding of the tool has an id, a test case and a fix text.
3	Incremental	One folder can be a unit while the rest of the repository is untouched and the check stays green.
4	Independent	No rule depends on a programming language, a build system or a code host. Nothing reads code.
5	Useful to agents	An agent finds the unit of a file, its interfaces and its documents with one command, and reads only what its task needs.

Shape of the repository	Fit
Workspace of packages (Cargo, npm, pnpm, yarn, Go, uv)	Good. The packages are candidates for units; the map adds what the build files do not say.
Services in one repository	Good. Each service is a unit, and its calls to other services are needs (wiring).
Firmware or a product of several components	Good: drivers, emulators and applications have real interfaces and stand-ins.
Application with feature folders, modular mobile app	Fits with one unit per feature or module.
Framework application organised by layer (`models/`, `views/`)	Not on the layer folders. Units belong on the level of features: Django apps, Rails engines.
Infrastructure modules (Terraform)	Partly. Modules map to units; environments have no place.
Single package or library	Good. A unit is a folder, not a package, so the package is one unit or one per module folder. With one unit the map is one box; the value is the root's `README.md` and `docs/`, which hold everything a reader needs in fixed places.
Data pipelines, notebooks	No. The parts are files, and the pipeline tool already has the graph.
System spread over several repositories	Each repository is a project of its own. The map across repositories is not produced.
A design before any code	Good. Planned units, wired, give a diagram to review, and a need that no part can meet shows a missing part (plantwatch).

If the folder layout does not match the architecture, unifold describes the layout. It does not ask you to restructure code.