Core Principles

Seven principles. Every design decision in Aura answers to them. When features conflict, the principles are the tiebreakers.

The philosophy says what Aura believes. The principles translate belief into operational rules the project can be held to. Each one is short enough to remember, specific enough to act on, and testable enough that you can tell when it's violated.

They are, in order:

1. Semantic-first
2. Intent-aware
3. Sovereign-by-default
4. Agent-native
5. Git-compatible
6. Open-source
7. Cryptographically verifiable

Principle 1: Semantic-first

The unit of version control is the logic node, not the line of text.

This is the foundational principle and the one every other principle ultimately serves. Logic is what the program does. Text is how humans and machines happen to encode it. When the two diverge — equivalent logic with different text, or identical text with different logic — Aura follows the logic.

Operational rules

• Every primitive operation (diff, merge, rename-detection, impact analysis) is defined against the AST-normalized logic graph.
• Cosmetic changes (whitespace, comments, ordering where irrelevant) must not produce spurious diffs.
• A function's identity is content-addressed on its AST, not its filename or its position.
• When text and logic disagree about what changed, logic wins.

How you know it's violated

If a rename produces a conflict. If reformatting noise shows up in a semantic diff. If moving a function across files loses its history. Any of these mean the text layer leaked through; the principle was compromised.

Principle 2: Intent-aware

Every commit carries a validated intent. The system compares what you said to what you did.

Intent is not metadata. It is part of the change itself. A commit without intent is not a complete commit; a commit whose intent does not match its code is not a safe commit.

Operational rules

• Every commit has a logged intent (via aura_log_intent or equivalent).
• The pre-commit hook compares the stated intent against the AST-level changes.
• Intent mismatches block commits by default (teams can configure the threshold).
• Intent is durable, searchable, and tied cryptographically to the changes it describes.

How you know it's violated

If a commit lands whose title is "fix typo" but whose diff deletes a function. If the intent log is lost or overwritten. If intent becomes optional by default. Any of these mean the sanctity principle slipped.

Principle 3: Sovereign-by-default

The default configuration keeps your code and your coordination data on infrastructure you control.

Sovereignty is not a paid feature or an opt-in. It is the shipping default. Anything that requires external dependencies — SaaS endpoints, phone-home telemetry, vendor accounts — must be explicitly opted into.

Operational rules

• No telemetry. Ever. Not for crashes, not for usage, not for "improving the product."
• No mandatory cloud account to run any core workflow.
• Mothership runs fully self-hosted on hardware you control.
• All data — commits, intent logs, agent messages, zone claims — stays on your infrastructure by default.
• Network egress is visible, minimal, and controllable.

How you know it's violated

If installing Aura opens a network connection you didn't approve. If a core workflow requires a hosted service. If a feature phones home silently. If opting out of the cloud costs you functionality users expect.

Principle 4: Agent-native

AI agents are first-class users, and no agent vendor is privileged.

Aura was designed for a world where agents co-author code. That world is not hypothetical; it is the current state of affairs. Tooling built only for humans, with agents bolted on, fails the workload. Tooling built for one agent vendor fragments the ecosystem.

Operational rules

• Every core workflow is exposed through the MCP server so agents can drive it.
• The agent coordination substrate (Sentinel) is tool-agnostic: Claude, Cursor, Gemini, Copilot, and future agents participate through the same interface.
• No agent-specific branches in the codebase. If a workflow works for Claude, it works for all MCP-speaking agents.
• Context compression (aura_handover) is generic, not Claude-shaped.

How you know it's violated

If Aura ships a Claude-only feature. If Sentinel messages don't round-trip between agents of different vendors. If the MCP surface lags behind the CLI by more than a minor version.

Principle 5: Git-compatible

Aura coexists with Git. Adoption is incremental. Reversal is clean.

Era transitions are long. Aura does not ask teams to abandon twenty years of Git muscle memory and tooling as the price of entry. It sits alongside Git, never modifies Git's state, and can be removed without a trace.

Operational rules

• Aura never writes to .git/.
• Aura never rewrites Git history.
• Aura's on-disk state lives under .aura/ and is self-contained.
• Deleting .aura/ fully removes Aura from a repository.
• Any Git operation that worked before Aura was installed continues to work after.
• Aura can be adopted incrementally: observation first, then intent validation, then Sentinel, then Mothership.

How you know it's violated

If running aura breaks git. If Aura corrupts the Git index. If an Aura hook refuses to run unless Aura is permanently adopted. If uninstalling Aura leaves orphaned artifacts.

Principle 6: Open source

Every part of the engine is Apache 2.0. There is no proprietary core.

Aura is built by a company (Naridon) that has commercial offerings, but the engine is open end-to-end. This is both a philosophical commitment and a strategic one: a sovereign, trustable substrate must be readable, forkable, and permanent.

Operational rules

• The CLI, merge engine, Mothership, Sentinel, Live Sync, and MCP server are all in the public repository under Apache 2.0.
• Commercial products are on top of the engine (hosted Mothership, enterprise support, web dashboard), not inside it.
• No "open core with paid features" inside the engine itself.
• Every shipped release is built from the public source. Binary releases are reproducible from the tagged source.

How you know it's violated

If a core feature lands in a proprietary branch. If a critical primitive is locked behind a paid tier. If the public source lags the shipped binary.

Principle 7: Cryptographically verifiable

Trust is a property you can prove, not a policy you have to believe.

Every meaningful state in Aura — logic nodes, commits, intent, signed agent actions — is cryptographically addressable. Tampering is detectable. Provenance is provable. Audit is mechanical, not manual.

Operational rules

• Every logic node has a content hash derived from its normalized AST.
• Every commit covers the full state of the logic graph.
• Intent is bound to the AST diff it claims to describe, signed by its author.
• Agent-authored actions carry agent identity (keys, signatures) that travel with the change.
• The audit trail is designed to be consumable by both human auditors and automated compliance tools.

How you know it's violated

If a node's history can be silently rewritten. If intent can be forged. If an agent can send a message as another agent. If an audit produces ambiguous evidence about who did what.

How the principles interact

The seven principles are not independent. Several reinforce each other; a few create productive tension.

Reinforcements

• Semantic-first + Intent-aware: intent only validates against what the code did, and the only rigorous answer is the AST diff. Semantic-first is the prerequisite for meaningful intent validation.
• Sovereign-by-default + Open source: you cannot be sovereign using a tool whose source you cannot read. Open source is the precondition for real sovereignty.
• Agent-native + Semantic-first: agents need structured data, not text. Semantic-first gives them what they need.
• Cryptographically verifiable + Intent-aware: intent integrity depends on cryptographic binding of intent to changes.

Tensions

• Git-compatible vs Semantic-first: full semantic fidelity sometimes wants a richer on-disk format than Git understands. The resolution: Aura maintains its own store in .aura/, and the Git-side representation is best-effort.
• Sovereign-by-default vs Agent-native: many popular agents run through cloud APIs. The resolution: the coordination substrate is sovereign; which agents you run on top is your choice.
• Open source vs commercial viability: the engine is free, but the project needs a business model. The resolution: commercial products are on the infrastructure around the engine (hosted Mothership, enterprise support, dashboard), not inside it.

When principles conflict, the tiebreakers are, in this order: Semantic-first > Intent-aware > Sovereign-by-default > Cryptographically verifiable > Agent-native > Open source > Git-compatible. Semantic-first comes first because without it, nothing else Aura does is meaningful. Git-compatible comes last because it is an adoption convenience, not an architectural commitment.

Testing the principles

You can hold the project to these principles concretely.

• Semantic-first: run aura diff on a pure rename. It should show zero semantic changes.
• Intent-aware: try to commit without logging intent. It should fail (with strict mode on).
• Sovereign-by-default: capture network traffic during normal operation. Aura should emit no unsolicited egress.
• Agent-native: every CLI command you use should be available via MCP.
• Git-compatible: run git status, git log, git diff in an Aura-using repo. All should behave normally.
• Open source: clone the public repo. You should be able to build the shipped binary from it.
• Cryptographically verifiable: tamper with a logic node by hand. Aura should detect it.

If any of these tests fail, the project is failing the principle. We take that seriously.

A shorter version

If you want the seven principles on a sticky note:

1. Logic over text.
2. Intent over metadata.
3. Your infra over someone else's.
4. Any agent, not one agent.
5. Coexist with Git.
6. Stay open.
7. Prove it, don't claim it.

Next

• The Aura Philosophy — the beliefs these principles translate.
• Design Decisions — concrete choices that fall out of the principles.
• How Aura Works — the architecture that implements them.
• Mission and Roadmap — where this is heading.