ub-mode: A Discipline Layer for Coding Agents

What ub-mode actually is

ub-mode is not a framework with a runtime, and it does not take over the coding task. It is a single instruction file that constrains an agent while code is being written or changed. The rule set imposes one explicit sequence: make the change work, then make it right, and then follow a practice loop that preserves the reasoning, protects the context window, and keeps commits reviewable. The upstream file states that order as a requirement rather than a recommendation.

The important boundary is that the skill does not pretend to replace engineering judgment. It tells the agent to write a failing test first, get the shape of the data right, and reduce shared mutable state, but the deterministic checks for complexity, duplication, and mutation survival live in separate companion repositories. The most useful mental model is a loadable behavioral contract. The contract is concrete; its outcome still depends on whether the agent follows it and whether the team connects the companion tools.

First make it work

The first phase is not about speed. It is about avoiding invented work. One decision must live in one place, and the agent ships the smallest edit that actually solves the problem. The “laziness protocol” is not permission to skip understanding; it is a guard against premature abstraction and scope growth. Before the logic spreads, the agent has to establish the data shape and do whatever helps every later phase. That places modeling, boundaries, and ownership of state ahead of implementation details.

Test-driven development is stated concretely: write the failing test first, see it fail for the expected reason, and make the smallest change that makes it pass. If an honest test is impractical, the rules forbid writing a bad one to preserve the ritual. That distinction matters because the test is treated as evidence of behavior, not as a formality attached to the end of a change.

When a requirement cannot fit the existing design, the skill asks for first-principles redesign instead of bolting another condition onto the old shape. The agent asks what it would have built if the requirement had existed from the start, works that design through, and delivers it in pieces. There is also an explicit rule for failed hypotheses: when two fixes sharing one premise fail the same gate, the agent must write that premise in one sentence, count which actors hold the imbalance, remove the bad assignment, and do that before starting another fix. Before adding anything, the agent removes complexity, aims at a checkable end state, and only allows a planned intermediate break when it can be undone.

Architecture as constraints

The architecture section reads like five review questions. Model the domain so illegal states are impossible to represent and maintain a glossary of domain terms; if the existing code is already clear and local, do not rewrite it for ceremony. Check data where it enters, trust it inside the boundary, and keep business logic in pure functions.

Use the type system as a design tool so illegal values cannot be written. Parse outside data once at the entry point, and do not silence the compiler. Make operations idempotent so running twice, or retrying after a halfway crash, converges to the same state. Finally, if workers do not need the same mutable thing, give each its own state; if they truly do, allow one writer and enforce that constraint in the structure. None of this is tied to a language or framework, but the direction is consistent: make invalid programs harder to write and concurrent outcomes easier to reason about.

Then make it right

Once the change works, a rough implementation is not considered done. The agent must reproduce the problem and fix its cause; a guard that merely hides the crash is not a fix. Work is sequenced into small verifiable units: finish one, check it, then start the next. Tests must call the code the way its user does and assert the result that user would see. If a test would still pass when every function returned nothing, it is testing implementation details and should be discarded.

The quality gates give this phase its distinctive force. Crapper computes cyclomatic complexity, test coverage, and CRAP score per function, with the target below 10; splitting the function, testing it, or both can get it there. Dryer detects structural duplication and targets blocks with similarity of 0.8 or higher. Mutator runs mutation testing, covers the uncovered code, kills surviving mutants, and removes dead code. The companion uml-viewer visualizes components, coverage, CRAP, mutation scores, and dependency directions, so the quality data is not just a set of disconnected numbers.

Refactoring has a strict safety order: pin what the code does, change the structure, then prove that the behavior did not change. Together, these gates push toward small functions, tested behavior, low duplication, and structural changes that can be traced rather than merely described.

Practice makes the run auditable

The final section addresses what agent workflows most often lose. The agent keeps a log of every action and the reason for it, then reports that log on completion. The final patch therefore arrives with a traceable path instead of appearing as an unexplained result.

Context management is treated as real work: keep the main thread small, send bulk work elsewhere, and retain a summary. Worktree cleanup requires identifying what is safe to remove, confirming that nothing still in use needs it, and only then reclaiming disk; uncommitted work waits for a decision. Commits are small, ordered, and frequent. Each one explains why the change was made, what changed, and how the behavior was proven, and the work is pushed to the main line at the end.

Fit and limitations

ub-mode is most valuable in an agent workflow that already values tests and review. It gives the model a disciplined order of operations: do not immediately polish an exploratory change into a “done” state, do not let tests become mirrors of implementation details, and do not reduce quality to a subjective impression.

The limitations are equally clear. Installation copies the instruction file into the agent’s skills directory and invokes the slash command; the upstream README gives Claude and Cursor directories as examples and also mentions Grok. The skill contains no executable code, and the repository metadata does not provide license information, so no license can be assumed. Crapper, Dryer, Mutator, and uml-viewer are separate repositories that must be evaluated and installed on their own. Teams expecting one command to guarantee code quality will not get that; ub-mode is better understood as a discipline layer that works alongside external gates and human review.