The Living Signal
Before sunrise, birds begin singing. Cryptochrome proteins in their retinas — quantum sensors that detect Earth's magnetic field — are part of a system tuned to the approaching dawn. Their circadian clocks drop melatonin levels and the chorus begins, 30 to 60 minutes before the sun appears.
Flowers open. Not because birdsong wakes them, but because their own circadian clocks anticipate the same event. Turgor pressure shifts in motor cells at the base of their petals, preparing for the pollinators that are about to arrive.
Then the bees come. And when a bee buzzes near an evening primrose, the flower's petals vibrate at the bee's wing frequency — below 1 kHz — and within three minutes, the flower increases its nectar sugar concentration by 20%. The petals are acoustic sensors. The nectar is a signal. The bee gets fed. The flower gets pollinated.
The Bird
Signal: Song (circadian + magnetic)
Sensor: Cryptochrome quantum receptor
Outcome: Territory, mating, dawn coordination
The Flower
Signal: Nectar concentration (acoustic response)
Sensor: Petal mechanoreception
Outcome: Pollination
The Bee
Signal: Wing frequency (200–300 Hz)
Sensor: Magnetite navigation + vibration
Outcome: Food, hive sustenance
Three completely different entities. Three completely different sensory systems — quantum magnetoreception, circadian turgor pressure, acoustic mechanoreception. No shared vocabulary. No shared modality. But the signals are structurally aligned: the right frequency, the right timing, the right chemistry. The outcome benefits the whole living system.
When the signals degrade — when a pesticide disrupts bee navigation, when light pollution shifts the dawn chorus, when habitat loss removes a pollinator — the graph breaks. Not because anyone did something wrong. Because clarity was lost at an edge.
This is the Universal Communication Graph. Communication between any two entities succeeds or fails based on the structural clarity of the signals between them. The domain does not matter. The properties are the same.
Tel Aviv University, 2019 — the research behind flower acoustics
Veits et al. published in Ecology Letters (2019) demonstrated that evening primrose (Oenothera drummondii) flowers respond to airborne sound at pollinator-relevant frequencies. Within three minutes of exposure to bee-frequency vibrations (0.2–1 kHz), nectar sugar concentration increased by approximately 20%. The petals themselves act as acoustic sensors, vibrating sympathetically at the relevant frequencies. Flowers with petals removed showed no response.
The Shape of Communication
Communication has been formally studied for over a century. Four properties keep appearing, regardless of domain. Each one maps directly to a component in the system that follows.
Identity
How entities express themselves. The bird's song is identity. In the system: persona artifacts and agent definitions.
Communication Theory of Identity
Hecht's Communication Theory of Identity (CTI) describes identity as enacted through communication across four frames: personal, enacted, relational, and communal. Identity is not a static property but something performed and negotiated in every interaction. In the system, persona schemas and agent definition files are the machine-readable encoding of this.
Progressive Disclosure
Trust develops through layered revelation. In the system: the 6-phase ideation state machine and the ClarityPacket annotation ledger.
Social Penetration Theory
Altman and Taylor's Social Penetration Theory (1973) models relationships as moving from superficial to intimate through progressive self-disclosure. The breadth and depth of shared information increases as trust builds. The ideation pipeline mirrors this: signal (surface) → shape → concept → structure (deep). Each phase discloses more, and the ClarityPacket's append-only annotation ledger is the structural record of that progressive disclosure.
Interconnected Systems
Components seek equilibrium. Disruption propagates. In the system: the living project lifecycle and protocol-governed conversation flow.
Systems Theory
Von Bertalanffy's General Systems Theory and its application to communication (Watzlawick et al.) describes communication as occurring within interconnected systems where each component affects all others. The system seeks homeostasis. When one part changes, the whole system adjusts. Kepric Protocol's stage graph with transition conditions on ClarityPacket state is a direct implementation: each stage is a system node, transitions are governed by the state of the whole, and the living project lifecycle is the long-term homeostatic loop.
Real-Time Feedback
Communication is transactional — simultaneous sending and receiving shaped by environment. In the system: the LSP (live gap detection as you write) and Langfuse observation.
Transactional Model
Barnlund's Transactional Model (1970) rejects the sender-receiver dichotomy. Both parties are simultaneously encoding and decoding, influenced by their environment and noise. The Language Server Protocol is exactly this: the human writes, the LSP simultaneously analyzes, gap diagnostics appear in real time, the human adjusts. It is not send-then-receive. It is continuous, bidirectional, environmentally aware feedback.
Gezellig — the feeling of belonging through shared experience
The Dutch concept of gezellig (roughly: warmth, coziness, belonging through shared experience) describes what good communication produces. It is not a property of the words exchanged but of the interaction itself — the feeling that both parties are participating in something that works. The bird, the flower, and the bee do not experience gezellig. But the system they participate in has the same structural property: when the signals are clear, the interaction produces warmth for the whole graph. The system described in this document exists to make that structural property measurable and reproducible.
The Graph Evolution
Graphs model relationships. Each generation of graph technology optimized for a different metric.
Web Graph
Google PageRank
Edges are links. Value is authority.
Social Graph
Edges are friendships. Value is connection count.
Interest Graph
TikTok
Edges are attention. Value is engagement time.
Communication Graph
Kepric
Edges are intent & sentiment. Value is signal clarity.
Each previous graph optimized for capture — authority, connections, attention. The metric was how much you took. The Communication Graph measures something different: how clear was the signal? Did the interaction produce a quality outcome for the system, not just for one party?
The bee does not extract from the flower. The flower does not extract from the bee. They participate in a system where signal quality determines whether the whole thing thrives or collapses. The Communication Graph is built on the same principle: participation, not extraction.
How the protocol layer implements the graph
In Kepric, the graph is not a metaphor. It is a literal implementation. Every conversation is governed by a ProtocolSpec — a directed graph of stages with transition conditions evaluated against ClarityPacket state. Each stage has participants, expected outcomes, and consensus rules. Each transition has conditions on packet fields (clarity score, annotation count, gap presence). The protocol runtime walks the graph, and the ClarityPacket is the structured container that flows through it — immutable request text, append-only annotation ledger, push-only delegation stack.
This is the composable structured communication graph. Any two entities that implement the
ConversationParticipant protocol can participate. The cognition behind their
responses is unconstrained — clarity pipeline, LLM, rules engine, a human typing.
The protocol only cares about the ClarityPacket state after each turn.
The Root Binary
Every interaction begins with one of two orientations: seeking to understand, or seeking to be understood.
The bee seeks nectar — to understand where food is. The flower seeks pollination — to be understood as ready. Neither invented this protocol. The structure emerged because it works.
In any communication — human, machine, or cross-entity — three properties determine whether the signal is clear. These are not failures. They are properties, the way frequency is a property of sound:
Different Vocabularies
The same concept, different words. The bee hears vibration; the flower produces chemistry. Overlapping meanings with no shared definitions.
Implicit Context
Assumed shared understanding that does not exist. The bird doesn't know the flower is listening.
Structural Mismatch
Information organized differently by sender and receiver. Quantum sensing vs. turgor pressure vs. acoustic reception.
These properties are universal, detectable, and measurable. That observation is where the system begins.
Axiom 1
This is not asserted. It follows from the observation. The bird, the flower, and the bee succeed because their signals have structural clarity. When the structure degrades, the outcome degrades. Clarity is the measurable property that connects signal quality to outcome quality.
Clarity is a layered property. Five levels, each progressively harder to detect:
The five layers of clarity
| Layer | What it means | Machine-detectable? |
|---|---|---|
| Well-formedness | Required structure is present | Yes — deterministic gap detection |
| Specificity | No vague or ambiguous language | Partially — catches pronouns, vague terms |
| Referential integrity | All references resolve, terms are defined | Yes — cross-reference validation |
| Transparency of intent | The reader can see the writer's goal | Requires understanding meaning |
| Freedom from confusion | Nothing creates misinterpretation | Requires the reader's perspective |
The ClarityScorer computes a 0.0–1.0 score: what percentage of required structure is present and validated? The score maps to a tier that determines how the system handles the input. This is not optimization — it is measurement. The system observes how clear the signal is and responds accordingly.
How clarity measurement stratifies execution
When clarity is measured, execution naturally stratifies. Some inputs are clear enough to be handled deterministically. Some need interpretation. This is an observation about the input, not a cost strategy.
Decision Tree
Gherkin-compilable · Score ~1.0 · Deterministic O(1) lookup
Small Model
Structured, specific, complete · Lightweight LLM
Large Model
Ambiguous, partially clarified · Full LLM reasoning
Axiom 2
The pipeline that follows is ordered by what is true, not what is convenient. Each phase depends on the output of the previous phase. "Done" means "proven to work," not "code was merged."
The ClarityPacket — the structured container that flows through the entire system — enforces this. Its request text is immutable. Its annotation ledger is append-only. Its delegation stack is push-only. You cannot skip ahead. You can only build on what has been established.
What is a ClarityPacket?
The ClarityPacket is the atomic unit of communication in the system. It contains:
- Immutable request text — the original signal, never modified
- Append-only annotation ledger — clarifications, assumptions, decisions, constraints, gaps, each typed and authored
- Push-only delegation stack — when work is delegated, the full context travels with it
- Iteration control — step counting and halt policies (halt to human, halt to parent, halt to orchestrator)
- Turn tracking — who said what, when, in what order
Every annotation is one of seven types: clarification, assumption,
decision, constraint, routing, gap,
error. The packet is the structured record of how an idea was progressively
understood. It flows through protocol stages, accumulating clarity.
Axiom 3
That's a signal. It has meaning but no structure. Here's what happens to it.
Signal → Shape → Concept
kepric-conversations · Ideation state machineThe idea enters through the conversational interface — backed by a 6-phase ideation state machine. Transitions are driven by analysis results, not timelines.
Each phase transition is governed by a protocol — a ProtocolSpec with stages,
transition conditions evaluated against ClarityPacket state, and consensus rules. The conversation
is not freeform. It is structured communication, walking a graph.
How each sub-phase works
Signal. The raw idea is captured. An Idea is created in the idea bag with status signal. A conversation session begins.
Shape. The human elaborates: "They should use LIDAR and cameras for hazard detection." The ClarityEngine's intake pipeline fires: PatternClassifier identifies intent, PatternExtractor pulls entities, HeuristicNormalizer resolves synonyms. Entities detected → mode advances. The Crystallizer generates a component decomposition.
Concept. More detail: "Two components: a hazard-detector module and an alert-system." Synonyms found and normalized. A glossary artifact is crystallized — shared definitions for every term. Without shared definitions, there is no communication.
Creating the initial signal, the list view with status badges
The clarity cockpit — thread, packet, questions, artifacts panels updating live
Axiom 4
The human never writes the artifact. The human talks. The machine — constrained by grammar, validated by the LSP, guided by gap detection — listens, interprets, structures, and produces. Parse failure is a bug in the tooling, never a human authoring error, because the human does not author the artifact.
What each side contributes
The Human
- Provides meaning, intent, domain knowledge
- Answers binary choices (Prioritree)
- Reviews and approves artifacts
- Says yes or no
The Machine
- Interprets messy intent into structure
- Normalizes vocabulary — one word, one meaning
- Produces artifacts constrained by grammar
- Validates via LSP gap detection
From this division, the rest of the pipeline follows. The conversation discovered the idea (Axiom 3). Now the machine structures it, validates it, plans it, staffs it, and executes it — each phase governed by protocol, each transition gated by ClarityPacket state.
Structure
kepric-clarity-core + LSP plugins · .kcl crystallizationThe conversation reaches the structure phase. The system produces formal artifacts: ADR candidates and RFC drafts as .kcl files — crystallized conversations validated by a textX grammar.
Inside the structure phase
5 Domain Plugins
Every plugin produces Gap objects through a shared anti-corruption layer. The ClarityScorer computes 0.0–1.0. The Gherkin-to-decision-tree compiler produces O(1) lookup structures for deterministic execution.
What is a textX grammar?
textX is a Python meta-language for building domain-specific languages. A textX grammar defines the exact structure that a .kcl file must follow — required fields, allowed values, nesting rules. The machine produces .kcl files; the grammar constrains what the machine can produce. If the output doesn't parse, the tooling has a bug. The human never sees a parse error because the human doesn't write the artifact.
What is DDD (bounded contexts)?
Domain-Driven Design organizes software around bounded contexts — each context has its own vocabulary, its own models, and communicates with other contexts through explicit contracts. Each LSP plugin is a bounded context: the persona plugin knows about persona schemas, the planning plugin knows about ADRs and RFCs, the agent-definitions plugin knows about agent files. They share the Gap protocol as their anti-corruption layer — the contract that lets them communicate without leaking internal concepts.
A rendered RFC or ADR produced by the system
Research
kepric-conversations + kepric-clarity-prioritreeThe research phase assesses technology viability. Which LIDAR sensor for outdoor robotics? Velodyne VLP-16 vs. Ouster OS1 vs. Livox Mid-360.
How research and prioritization work
Prioritree — pairwise comparison prioritization — uses the one thing humans are reliably good at: binary choice. "Is A better than B?" Repeat. No Likert scales, no weighted matrices, no cognitive overload.
The pairwise comparison interface and viability results
Plan Generation
kepric-conversations · PlanGeneratorAll viability complete → mode advances to project. The PlanGenerator produces a ProjectPlan.
What the plan contains
What is Gherkin?
Gherkin is a structured language for writing executable specifications in Given/When/Then format. Given establishes preconditions, When describes the action, Then states the expected outcome. Each scenario is both a human-readable requirement and a machine-executable test. In Kepric, the Gherkin-to-decision-tree compiler transforms these scenarios into O(1) lookup structures — if the input matches a compiled scenario exactly, no model is needed at all.
Tasks with clarity scores, requirements coverage, dependency graph
Team Generation
kepric-conversations · TeamGeneratorThe TeamGenerator creates a TeamSpec from the plan — agent specifications with relationships, workflows, and a handoff packet (a ClarityPacket with the full delegation stack).
How teams are specified
Each agent in the team implements the ConversationParticipant protocol. The cognition behind their responses is unconstrained — the protocol only cares about the ClarityPacket state after each turn. The team includes:
- Agent definitions — role, capabilities, model assignment based on clarity score
- Relationships — who delegates to whom
- Workflows — step sequences with branching
- Handoff packet — the full ClarityPacket with delegation stack, so the receiving team has complete context
Agent specs, relationships, workflows, model assignments
Execution
kepric-agentos · FastAPI runtimeThe ExecutionBridge serializes the team into an AgentOS-compatible format and hands off.
The execution handoff
- Agent definitions loaded into the runtime
- Workflows instantiated with step sequencing and branching
- Each agent run passes through
ClarityScorer clarity_score,clarity_tier,clarity_packet_jsonpersisted on everyAgentRun- Execution results flow back through the system via protocol
The handoff — agent run with clarity score persisted
Axiom 5
This is what makes the system a living system. Measurement without blame creates a feedback loop that improves over time instead of creating defensiveness. The agent team persists because the system measures without judging.
The Living System
Execution is not the end. It's the beginning of the project's permanent lifecycle.
A generated agent team doesn't disband after the first delivery. The team — its agent definitions, workflows, relationships, clarity packets, and the entire artifact graph that produced them — persists as the living infrastructure of that project.
The continuous evolution loop
Continuous Validation
New requirements enter the same pipeline. The PlanGenerator produces incremental amendments, not rebuilds. The team already knows the domain.
Reliability Through Measurement
Longitudinal clarity scores detect drift. The project gets more reliable over time as more interactions are measured and more patterns are compiled.
Institutional Memory
The agent team doesn't leave. Conversation history is ingested into the knowledge graph. New humans enter a conversation with full context.
Observability
Nothing runs unobserved. The system measures itself at four layers:
Four layers of measurement
Layer 1
Deterministic gap detection via LSP plugins
Layer 2
Runtime observation via Langfuse traces
Layer 3
LLM-as-Judge meta-evaluation
Layer 4
Semantic enhancement — intent, entities, normalization
What is Langfuse?
Langfuse is an open-source LLM observability platform. It captures traces — structured records of every LLM call, including inputs, outputs, latency, token counts, and custom scores. In Kepric, every conversation turn, every clarity analysis, every agent run produces a Langfuse trace. This creates a longitudinal record of how clarity evolves across the life of a project.
What is an LSP?
The Language Server Protocol (LSP) was created by Microsoft for VS Code and is now a standard across editors. An LSP server analyzes documents in real time and reports diagnostics (errors, warnings, information) back to the editor. Kepric's LSP server analyzes Markdown, .kcl, and .protocol files for structural gaps — missing fields, undefined terms, unresolved references — and surfaces them as live diagnostics. It is the Transactional Model implemented: continuous, bidirectional, real-time feedback.
A real trace showing the observation chain — spans, scores, mode transitions
What Emerges
These are not features. They are the components that follow from the observations above. Remove any one and the chain of reasoning breaks.
What breaks without each component
| Component | What breaks without it |
|---|---|
| Conversational interface | No way to capture messy human intent progressively |
| Ideation state machine | No structured progression — ideas stay formless |
| ClarityEngine intake | No entity extraction, no synonym resolution, no intent classification |
| LSP + plugins | No gap detection — unclear artifacts pass through unchecked |
| ClarityScorer | No measurement — can't observe how clear the signal is |
| Gherkin compiler | No deterministic execution — everything requires a model |
| .kcl grammar | No structural constraint on machine output |
| Protocol layer | No structural guarantee on conversation flow — interactions are freeform |
| ClarityPacket | No structured container — context is lost between stages |
| Prioritree | No reliable human input mechanism for ranking |
| PlanGenerator | No bridge from artifacts to executable tasks |
| TeamGenerator | No bridge from tasks to agent specifications |
| ExecutionBridge | No handoff — plans stay plans |
| AgentOS runtime | No execution — agents have no runtime |
| Langfuse observability | No measurement of the measurement — system is opaque |
The Proof
Spec breakdown by domain
engine, scoring, Gherkin, plugins, KCL
sessions, modes, crystallization, chat
parsing, runtime, negotiation
CRUD, execution, workflows, bridge
What is BDD?
Behavior-Driven Development writes specifications as executable scenarios in Gherkin format. Each scenario is both a requirement and a test. In Kepric, failing tests are unimplemented features, not bugs. The specs are the roadmap. When all scenarios pass, the feature is complete by definition.
Every spec is a Gherkin scenario. Every scenario is an executable test. The specs are the roadmap.
The Vision
The current system proves the concept in software planning. The architecture is domain-agnostic. The protocol layer and ClarityPacket are composable — any domain that has structured communication can use them.
Where clarity applies beyond software
Healthcare
Surgery protocols, Medicare billing, clinical trials
Construction
Building permits, safety inspections, contractor specs
Legal
Contract review, compliance, regulatory filings
Education
Curriculum design, assessment criteria, learning objectives
The Universal Communication Graph — a graph of translations between entities, where every edge is a clarity transformation governed by protocol and measured by ClarityPacket state. The current system is the first edge. The architecture is designed for all of them.