Why sprig and prose exist
Modern systems are hard to understand — not because they are poorly built, but because they are alive.
They grow. They accumulate history. They reflect decisions made by different people, under different constraints, at different moments in time.
Most tooling assumes the opposite.
Most tooling assumes:
- there is a single source of truth
- that truth is owned
- and the primary goal is to enforce it
sprig and prose start from a different premise.
This philosophy is reflected directly in how sprig is introduced — slowly, concretely, and without pressure to act.
Understanding comes before control
sprig exists to help people understand systems as they are.
It is not an ORM. It is not a schema language. It is not a framework that asks to be “in charge.”
Instead, sprig is an ecosystem for describing, observing, and understanding real systems over time.
It is designed to be useful:
- before execution
- before adoption is complete
- before certainty exists
Sometimes even before intent exists.
Understanding is not a precursor to action. Understanding is valuable on its own.
Description has intrinsic value
A core belief of sprig is that description matters, even when nothing else follows.
Even without observation. Even without execution. Even without enforcement.
Prose exists to support this:
- human-first modeling
- narrative structure
- orientation and exploration
- shared language across experience levels
New engineers learn faster. Experienced engineers continue learning safely.
sprig helps systems be read.
Nouns before verbs
sprig favors nouns over verbs.
You begin by describing:
- what exists
- how things relate
- what shape reality seems to have
- what identifiers appear to matter
You do not begin by declaring:
- how things must change
- who owns enforcement
- or what actions are allowed
sprig stays among the nouns. It describes what exists and observes what is real. It does not act on your behalf, migrate, or enforce.
This keeps sprig readable, calm, and safe to approach.
Fuzzy first, precise later
Real systems are rarely known all at once.
sprig is designed for:
- partial knowledge
- evolving understanding
- incremental refinement
You can begin with:
- rough shapes
- optional fields
- multiple perspectives
- incomplete knowledge
And move toward:
- clearer identities
- richer description
- more evidence
Without losing information along the way.
sprig is lossless by design.
Observing, not owning
When sprig touches reality, it does so gently.
Code points back at the universe with small @sprig markers in ordinary comments. From each one, sprig records a receipt — evidence that a named thing exists here, at this place, at this moment.
It reads files. It does not change them.
Reality may even name something the universe hasn’t yet. That is recorded, not refused.
It does not punish. It does not assume ownership. It does not demand compliance.
sprig doesn’t say “this is wrong.” It says “this is what I see.”
Observing before acting
sprig’s natural progression is:
describe → make visible → observe
You describe a world in prose. Sprig makes it visible as a manifest. Then real code observes it, and receipts record what is true:
- where a named thing appears
- when it was last seen
- whether reality names something the universe does not yet
Observation is not a bolt-on feature. It is a continuation of description.
Only after observing does it make sense to talk about what comes next. These directions are still in development — not built yet:
- reconciliation — what is present, missing, or drifting
- runtime emission — letting systems speak while they run
- collection — gathering receipts upstream, over time
Even then, everything remains optional.
Names and structure are separate
In prose:
- concepts name ideas
- nesting, dimensions, and scope add structure — only when it helps
A name does not imply a structure. Where an idea sits does not change what it is.
Names resolve in the enclosing container first, and can always be made explicit with a path.
This separation allows systems to stay flexible:
- ideas can move
- structures can evolve
- meaning remains intact
Structure is made explicit only when it helps.
Local-first, non-invasive
sprig runs where your systems live.
It reads files. It connects locally. It links to repositories without owning them.
You can adopt sprig:
- per directory
- per entity
- per moment in time
There is no cliff. There is no rewrite. There is no lock-in.
sprig should touch systems — not dominate them.
The goal
sprig exists to make systems:
- more legible
- more humane
- easier to learn
- safer to evolve
It is a companion, not a commander. A field guide, not a rulebook.
Calm by design. 🌱