Personality OS
§ The framework · v0.1

OS

Consistency doesn't emerge. It's built.

Five layers. One persona. Authored in markdown, validated by code, contracted by tests, shipped through environments. Personality OS is the engineering substrate that turns a character spec into an agent that doesn't drift.

Currently powering Sama, in production with an airline. Built by Uneeq.

§ Thesis

Personality is not what your agent says once. It's what it never stops being. That takes method.

— The Personality OS thesis
§ A · The Stack

Five layers, one personality.

From the cortex that classifies what a user means, up through corridors, senses, and reflexes, to the voice they actually hear. Each layer has a role. Each role has a file. Each file is reviewable.

  1. 01

    Router

    — the cortex

    LLM classifier with structured output: confidence scores per intent, plus a recommendation. Decides which Track gets the message.

    prompts/routers/Intent Classifier.md
  2. 02

    Track

    — the corridors

    A top-level conversation path per intent. A task-completion flow is one track. Free chat is another. They run in parallel; only one is active at a time.

    prompts/tracks/Task Flow.md
  3. 03

    Extractor

    — the senses

    Pulls structured data from messages — typed schemas with descriptions per field. The bridge from prose to objects.

    prompts/extractors/User Goal.md
  4. 04

    Rule

    — the spine

    Deterministic JS where reliability matters. LLMs do language; rules do math, validation, and state. Trustable.

    code/rules/confidence-threshold.js
  5. 05

    Composer

    — the voice

    Shapes the final user-facing reply. Owns the persona — warmth, tone, brand voice. One per stage.

    prompts/composers/Greeter.md
§ B · Substrate

Four substrates. One source of truth.

The stack is what runs at the user. The substrate is what makes it ship-able and review-able for the team that builds it.

Markdown source

Authored in Obsidian-flavored markdown with a 17-callout dialect. Source of truth lives in git — every change is a commit, reviewable, blamable, revertable.

See the 17 callouts

Code as truth

JavaScript validators carry the logic that must be reliable — thresholds, state mutations, validation. The LLM never does math; the code never tries to write copy.

Behavioral contracts

YAML scenarios assert intent in plain English, judged by an in-flow LLM. Paraphrase-tolerant. Catches drift before stage.

Read the testing walkthrough

Promotion pipeline

Bob runs the build: compile · push · test · promote. Flows move dev → stage → prod with explicit ID remapping, credential injection, and env state.

Bob's commands
§ C · Why teams choose it

Six concrete wins.

— 01

Source in git. Runtime in Flowise.

Every prompt change is a commit. Every behavioral fix is reviewable. Every release is a tag you can roll back to. Flowise keeps doing what Flowise does best — visual flow, runtime — while git handles what it does best: version-controlled source.

— 02

AI can edit your prompts.

Because prompts live in markdown, LLMs read them natively. Ask Claude or GPT for a refactor across seventeen prompts and get back a reviewable diff. Your iteration loop just got 10× shorter.

— 03

Cross-role visibility.

Obsidian renders the dialect beautifully. Prompt engineers, PMs, designers, and developers read the same source files — no tool lock-in, no exported PDFs, no stale screenshots.

— 04

Determinism where it matters.

LLMs do language; JavaScript does rules. Validation, thresholds, state — all in code. No more LLM-does-math disasters. No more flaky branching logic.

— 05

Drift-resistant by design.

Behavioral contracts catch regressions the moment a prompt edit changes how the agent behaves. The drift never makes it past dev. Releases stop being scary.

— 06

Repeatable across environments.

Promotion remaps resource IDs, swaps credentials, and injects env-specific state. Same source, three environments — without manual UI clicking, ever.

§ D · Before & After

How most teams ship LLM agents. How Personality OS teams do.

Flowise is the engine: visual flow, node connections, runtime. Personality OS is the source layer: every prompt and every custom node lifted into git, where you can version, test, review, and let AI refactor. We don't replace Flowise. We ground it.

Flowise alone Flowise + Personality OS
Source of truth Prompts live in Flowise textareas. No history. Prompts live in git. Every change diffable.
Testing Click through the UI. Hope for the best. Behavioral contracts in YAML, judged by LLM.
Shipping Manual UI export/import per environment. One command. ID remap + credential swap automatic.
AI assistance Copy-paste prompts into a chat to refactor. AI edits the source files directly — reviewable diff.
Team collaboration Engineers in Flowise, PMs in Notion, writers in Docs. Everyone reads the same markdown in Obsidian.
§ E · The toolchain

Bob is the official toolchain for Personality OS.

Personality OS is the spec — the layered architecture, the dialect, the contracts. Bob is the implementation that makes it faster: it compiles your markdown, pushes to Flowise, runs your behavioral contracts, and promotes a green flow up the chain. You can practice Personality OS without Bob; you'll just do it by hand.

What is Bob? Bob's commands
§ F · Adopt

Three steps to your first Personality OS agent.

  1. 01

    Author a Composer in markdown.

    Use the Obsidian dialect. [!persona] for identity, [!rule] for behavior, [!schema] for inputs. Save it under prompts/composers/.

    See all 17 callouts →
  2. 02

    Pin a behavior with a contract.

    Write a YAML scenario describing what the agent should and shouldn't do — in plain English. The judge evaluates intent, not exact wording.

    Read the testing walkthrough →
  3. 03

    Push and test.

    bob push my-agent to deploy. bob test --suite ... to run your contracts. Green? Promote to stage. Same source, every env.

    See Bob's commands →