Mushin Docs / Design Streams & Version Control

Design Streams & Version Control

A Mushin project’s design is version-controlled the way source code is — with branches, commits, and a full history. This page covers the rhythm you work in, called the Mushin Cycle, and how branches and commits work.

The blackboard

At the center of a Mushin project is the blackboard — the evolving design document that is your application’s source of truth. Each feature has its own blackboard. As you work in design streams, the blackboard grows to capture the whole design.

You view the blackboard from the project explorer. It is presented read-only — you shape it through design streams and commits rather than editing it as free text, so that every change to your application’s design flows through the reviewable cycle below.

The Mushin Cycle

Building a Mushin project follows a repeating cycle:

  1. Check out — start from the current state of the design on your branch.
  2. Generate — run a design stream to produce the next contribution.
  3. Review the difference — see exactly what the contribution changes, as a difference against what was there before.
  4. Commit — snapshot the blackboard, making the contribution part of the design’s history.
  5. Sync — the structured metadata for your application is brought up to date with the new commit.

Each turn of the cycle advances your application by one reviewable step. You are never handed a wholesale rewrite; you approve changes as differences, one commit at a time.

Branches and commits

  • A branch is a line of development. You can develop a change on a branch without disturbing the main design.
  • A commit is an immutable snapshot of the blackboard. Commits form a history you can read from newest to oldest.
  • Because commits are immutable, your design’s past is always intact — you can see how any part of the application came to be.

Reviewing changes as differences

Mushin expresses each contribution as a difference — what was added, changed, or removed relative to the previous state. This is more than a text diff: it is a semantic difference, describing the change to your application’s design in its own terms. Reviewing differences is how you keep control of what the AI is doing, approving each step deliberately.

Committing and reverting

From the branch manager you perform a commit to make the current contribution permanent, or revert the last commit if it went the wrong way. Reverting steps the design back, cleanly, to the previous commit. This safety net is what makes it comfortable to let the AI propose changes: nothing is final until you commit, and a commit can be undone.

← PreviousThe Neuro-Symbolic Approach