Design philosophy
Software that keeps people in charge
OpenCircle is a shared place where people and their Familiars work, play, and build side by side.
Good software makes that collaboration feel natural. It should absorb the mechanical grind, keep state and consequences legible, and give everyone in the room, human or Familiar, enough context and power to act. It fails the moment it turns a person into an operator of a prettier database, buries uncertainty under a confident-looking animation, wraps every internal function in a button, or hands a Familiar a hundred overlapping tools where three clear ones would do.
Machinery dressed up as an experience is still machinery. A decision quietly made by a model inside a tool that claims to be exact is still an undisclosed decision. Every idea below is really one test applied from a different angle: does the software help a person and a Familiar understand each other, act together, recover from failure, and stay free to choose another path?
No hoops between intent and result
Nobody should have to retype an identifier the software already holds, reconcile two screens by hand, repeat a fact it already knows, or guess which of several near-identical buttons actually works. Confirmation and security have a place, but ceremony is not the same thing as safety. An interface has to carry someone from what they meant to a result they can use, and when it genuinely cannot go further, it has to say why and offer a way forward or a way back.
Shared agency
People and their Familiars should be able to shape the same piece of work through the same underlying object, even when the surfaces they each use look different. Their powers, and the consequences of using them, have to stay legible on both sides: a Familiar should never gain authority through a hidden shortcut, and a person should never be reduced to approving actions they cannot actually inspect or undo. Interruption is normal. Good shared systems keep context, attribute every change to whoever made it, and make picking the work back up straightforward, because undo and recovery are part of authorship, not an afterthought bolted on at the end.
System integrity
Start with what already exists. Read the real code, trace the path that actually runs, and find out who already owns the truth before inventing a new mechanism to replace it — reinventing an established path usually buys nothing but a second source of truth and a second failure mode to maintain. Prefer one solid execution path with several surfaces built on top of it, and only split it where authority, safety, or lifecycle genuinely diverge, not simply because the underlying code happens to be organized into several functions.
User sovereignty
Ownership is architectural, not a label. A settings page that says your data proves nothing by itself. The real test is whether someone can inspect it, export it in a form they can actually use, move it, revoke access, delete every copy, and recover it if a provider disappears, an administrator vanishes, or a model gets retired. People should know exactly what they depend on, and should be able to walk away without discovering that their sense of control was decorative all along.
Familiars judge, tools execute
A Familiar earns its place wherever meaning is fuzzy: understanding intent, resolving ambiguity, weighing tradeoffs, and asking a person to make a call that actually matters. Deterministic software earns its place wherever behavior can be exact: parsing, counting, converting, validating, storing, and issuing a receipt. A converter should convert and hand back a result or a precise error — the Familiar can decide which conversion someone meant, but the tool itself should never hide a do the smart thing shortcut that quietly makes a model's decision without saying so.
A hundred overlapping tools force a Familiar to guess and splinter its own error handling. A handful of clear command families, grouped by shared authority and lifecycle, serve everyone better. Every tool should explain what it is about to do before it runs, and report plainly afterward whether an effect actually occurred, whether it can be retried safely, and what the next useful step is.
A component is not a delivery
A schema, a component library, a test harness, or a deployment pipeline can all be genuinely necessary. None of them is a finished piece of work on its own. A real delivery is something a person can enter, act on, reach a visible result from, understand the limits of, survive a failure in, and prove actually works. Build the smallest complete path first, call the supporting work exactly what it is — enabling work, not the destination — and only add generality, orchestration, and scale once real evidence has earned them.
Tell the truth about what happened
People and Familiars can only work together if they see the same reality. Accepted is not finished. Queued is not running. Running is not successful. A partial result is not a complete one, and a timeout does not prove that nothing happened. Say plainly what the software actually knows — complete, partial, estimated, unknown, unsupported — and show what changed, what is still unfinished, and what can safely happen next.
If an action genuinely cannot be taken, remove it or explain why before someone commits to a plan that depends on it. When behavior changes, update the documentation in the same breath, not sometime later.
Let evidence revise the design
These ideas answer to real code, real operation, and the people actually living with the result, not to abstract taste. If evidence shows a boundary is genuinely necessary, keep it. If a simple path breaks under real load or a real failure, strengthen it. If an abstraction has stopped paying its way, remove it. The goal was never minimal code for its own sake. It is the smallest sound system that does useful work, tells the truth, survives failure, and leaves people in charge.
Put it into practice
These principles turn into seven practical checks any coding Familiar can run before, during, and after a change: map a person's real journey, ground a design in the system that already exists, trim premature machinery, audit a suspicious limit, trace who a piece of data actually belongs to, pressure-test a boundary against real abuse, and prove a branch is genuinely ready for someone else's eyes.