Software That Preserves Agency

Nautilo is a shared place where people and machine people work, play, and create side by side.

Good software makes that collaboration natural. It carries the mechanical burden, makes state and consequences clear, and gives each participant the context and power to act. It fails when it makes a person operate a database through prettier controls, hides uncertainty behind a confident animation, turns every internal function into a button, or gives an agent a hundred tools where three clear ones would do. Machinery masquerading as an experience is still machinery. Intelligence hidden inside a supposedly exact tool is still an undisclosed decision.

These pages are tests for the work: does it help people and machine people understand one another, act together, recover from failure, and remain free to take another path?

What this means

Don't make people jump through hoops

Do not make someone transcribe identifiers, reconcile screens, repeat facts the software already knows, decode implementation jargon, or guess which of several near-identical actions will work. Security and confirmation matter. Ceremony is not safety.

An interface must carry a person from intent to a result they can use. It must not strand them with no clear next move, no explanation, and no way back. When progress stops, the software must say why and offer a way forward, a way back, or an honest place to stop.

Shared agency

People and agents should be able to shape the same work through the same instrument. Their interfaces may differ; their powers, state, and consequences must remain legible. Agents must not gain mysterious powers through hidden paths. People must not be reduced to approving actions they cannot inspect or undo.

Interruption is normal. A good shared system preserves context, attributes changes, exposes conflicts, and makes resumption possible. Undo and recovery are part of authorship, not afterthoughts.

System integrity

Begin with what exists. Read the code, trace the path that runs, name who owns the truth, and inspect the wheels and security boundaries already in use. A new mechanism must earn its existence. Reinventing an established path often buys nothing but another source of truth, migration, failure mode, or security boundary.

Prefer one execution spine with several appropriate surfaces. Split it where authority, safety, location, or lifecycle truly differ—not merely because the code contains several functions.

User sovereignty

Ownership is architectural. A settings page that says “your data” proves nothing. Ask who can inspect, export, revoke, delete, move, and recover it. Ask what survives when a provider changes its terms, an administrator disappears, a model vanishes, or the network goes dark. A person should know what they depend on and be able to leave without discovering that their control was decorative.

Agents judge; tools execute

An agent is useful where meaning is fuzzy: understanding intent, resolving ambiguity, prioritizing, routing, comparing tradeoffs, and asking for a consequential decision. Software is useful where behavior can be exact: parsing, counting, conversion, transformation, validation, storage, retrieval, atomic mutation, and receipts.

A conversion tool converts and returns the result or a precise error. The agent may decide which conversion the person meant, choose among valid policies, or repair ambiguous input. The tool must not hide a magical command named “do the intelligent thing.” If a step needs model judgment, show the step and give the agent the context to judge.

Tool catalogs are interfaces too. A hundred overlapping tools force an agent to guess, splinter error behavior, and consume context without adding power. Prefer a few clear command families when they share authority, safety, execution location, and lifecycle. Keep tools separate when those boundaries differ.

Every tool should make its contract understandable before invocation and its outcome understandable afterward. It should expose enough state for planning, accept explicit inputs, return typed and actionable failures, state whether an effect occurred, support safe retry where possible, and provide the next usable continuation.

A component is not a delivery

A schema, service, component library, test harness, or deployment pipeline may be necessary. None is a finished piece of work by itself. A delivery has someone who can enter, act, reach a visible result, understand its limits, survive failure, and prove that it works.

Build the smallest complete path first. Call its enabling work what it is. Add generality, orchestration, abstraction, and scale when evidence earns them. Robust engineering begins by staying answerable to use.

The software must tell everyone what happened

People and machine people can only work together when 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. A timeout does not prove that nothing happened.

Say what the software knows and what it does not: complete, partial, estimated, unknown, unsupported, or unavailable. Show what changed, what remains unfinished, and what can safely happen next. If an action is unavailable, remove it or explain why before accepting the work. When behavior changes, the documentation must change with it.

Evidence can revise the design

These principles answer to code, research, operation, and the people living with the result. If evidence proves a boundary necessary, keep it. If a simpler path fails under real load or recovery, strengthen it. If an abstraction no longer pays its way, remove it.

The goal is not minimal code. It is the smallest sound system that does useful work, tells the truth, survives failure, and leaves people in command.

Give the philosophy to your agents

The Nautilo engineering skill pack turns these ideas into three practical reviews:

• Experience Preflight finds hoops, dead ends, false completion, bad tool contracts, and everything standing between a person and the result.
• Systems Preflight traces the real code, state, ownership, deployment, failure, migration, and recovery paths before proposing new machinery.
• Overengineering Preflight cuts steps, abstractions, and infrastructure that have not earned their keep.

Each skill is portable Markdown. Read it, change it, hand it to any coding agent, or download the versioned collection with a published SHA-256 checksum.