# OpenCode SaaS Starter: Stop the Every-Session Redesign

> OpenCode agents invent architecture per session unless the repo decides first. The conventions file that ends the debate. How it works inside.

Source: https://boringpush.com/blog/opencode-saas-starter

## Every session redesigns your app

Ask an OpenCode agent to "add email receipts" on Monday. OpenCode is SST's open-source terminal agent. Verify the current version before you adopt it.

It creates a mailer folder, wires a new pattern and ships.

Ask a different session on Friday to "add welcome emails." It creates a different email folder. A second pattern. Ships.

Both work. Neither matches.

By month three the repo holds four mailers, three auth helpers and two database clients. Each correct alone. Incoherent together.

The agent was never wrong. It was never told.

Decide once, in the repo. The agent obeys every session.

## Configured repos or convention repos

| Decision | A repo with no conventions | A convention repo |
|---|---|---|
| "Where does X go?" | The agent's choice, per session | The file says so, every session |
| A new database table | Three different patterns tried | The same actions on every engine |
| A new API route | Logic dumped in the handler | Thin: validate, check access, call, return |
| A new dependency | Installed casually | Forbidden without an argument |
| Month-three shape | Four mailers, archaeology | One mailer, boredom |

Invention per session is worse than it looks. Three reasons.

**Agents optimize locally.** Each session sees its task, not your history. "Best" means best for these 20 minutes, which is how four mailers happen.

**Reviews cannot catch philosophy.** You can review code. You cannot review "why is this in that folder instead of the usual one?" at scale. Structure drifts silently while tests stay green.

**Onboarding resets to zero.** Every new agent, new model, new editor or new teammate relearns your architecture from scratch. A conventions file is onboarding that never degrades.

A written conventions file is the strongest instruction file. Not suggestions. Law, with locations.

## What to do

Map every kind of creation to exactly one location.

A new database entity.

A new API endpoint.

A new UI piece.

A new setting.

Each has one legal home and one required shape.

When the only legal answer to "where does this go?" is written down, sessions stop inventing and start complying.

Close the last loophole: no new top-level folders without updating the file. Point your agent's rules at this file first, before prompts and before skills.

Make shapes consistent across engines, or they do not merge.

"Same on every database, or it does not merge" is the one-line review standard. An agent adding a field must touch every engine with the same behavior, or the change is incomplete.

Same names. Same plain-data results. No driver details leaking upward.

End every session at the gate.

Every change finishes with a syntax check and a lint run that must come back with zero warnings. "Done" means proven, not claimed.

Invented architecture usually breaks lint, through wrong imports and dead code, or breaks the short-route rule when logic lands in a handler.

Agents learn quickly that compliance passes and creativity fails. That is the incentive you want from a tireless, literal-minded junior.

## Convention or invention

| Question | No conventions file | Conventions enforced |
|---|---|---|
| New patterns introduced | A new one per session | None |
| Route length | Drifts upward | Held to the target |
| New dependencies | Added casually | Need an argument first |
| Session startup | Context-building each time | One file to read |
| A new tool | A full re-brief | Point it at the file |

Any agent. Any device. One rulebook.

## The cost

Writing conventions costs a senior afternoon. Enforcing them costs each session a minute or two of gate time.

Against that, you skip archaeology expeditions, "which mailer is real" mysteries and migrations caused by drift rather than need.

Conventions ossify. Review the file every quarter and delete rules that stopped earning their keep. A dead rule teaches agents that rules are decorative.

## Know this first

Writing conventions costs a senior afternoon. Review the file every quarter.

A dead rule teaches agents that rules are decoration.

## Why BoringPush is the way to do this

Decide once. Every agent obeys.

BoringPush ships a conventions file and a rules file.

Where things go.

What shape they take.

Every session ends with a clean check.

Any agent. Any device. One rulebook.

## FAQ

### How is this different from any repo with a README?

READMEs explain; conventions constrain. "We use Stripe for payments" is an explanation.

"A new payment provider goes in exactly one place, with exactly these three behaviors" is a constraint an agent can execute without judgment. READMEs inform humans, and a conventions file programs agents.

### Does OpenCode read AGENTS.md or its own config?

OpenCode reads its own configuration and commonly respects `AGENTS.md`-style instruction files. Verify the current behavior, because tool authors rename these paths. BoringPush keeps the law in one file and points each tool at it, so there is one source of truth and no duplicated rules to drift apart.

### What belongs in conventions versus regular docs?

Constraints go in conventions: never, always, exactly one place. Explanations go in docs: why SQLite first, how the paywall reads.

Agents obey constraints and skim prose. If a rule cannot fail a diff, it belongs in docs.

### How do I stop agents debating my conventions mid-task?

Scope the debate window. Sessions may propose a change to the file only as a separate diff, never as a drive-by violation inside feature work.

"This rule slowed me, here is the amendment" is welcome input. "I ignored the rule for speed" fails review.

### Can conventions cover UI taste too?

Yes. BoringPush pins its visual style in the written rules: a neutral palette, hairline borders, rounded corners and restrained decoration. Agents with taste constraints produce coherent interfaces, and without them every session imports a new design era.

### When should a solo founder write the conventions file?

Before the third agent session, or tonight, whichever comes first. Session one explores, session two sets patterns, and session three fossilizes them without a file. An afternoon of writing pays back every session after it.

## Keep reading

- [Will Claude Code Respect Your Boilerplate? 6 Tests](/blog/claude-code-saas-boilerplate) — the 6-trait scorecard conventions satisfy
- [Antigravity + Next.js: Tame Its 40-File Weekends](/blog/antigravity-nextjs-boilerplate) — fences for longer autonomous missions
- [Mobile AI Guardrails: Couch Fixes That Can't Break Prod](/blog/mobile-session-guard-zero-breakage) — the same law at phone scale