Core concepts

The eight system primitives

Everything Nika OS does reduces to eight primitives. They structure the kernel, the hooks, the pods, and the routing of user intents.

#	Primitive	Role
1	Instruction	What guides behavior: the kernel instruction file, system prompts, skills, policy files
2	Lifecycle	What handles transitions: SessionStart, PostToolUse, Stop, SubagentStop, PreCompact, UserPromptSubmit hooks
3	Context	What is injected at time T: user prompt + RAG retrieval + hierarchy state + handoff packet
4	Memory	What persists beyond the context window: Qdrant (semantic), YAML hierarchy (workflow), JSONL bus (audit)
5	Execution	What acts: CLI-agent tools, MCP servers, pods
6	IPC	What connects agents: Redis Streams signaling + working memory + entity feed + consumer groups
7	Schedule	What fires over time: Remote Triggers (persistent), CronCreate (session-scoped), OS crontab
8	Autonomy	What decides without asking: Plan mode (questions, clarification) vs. Execution mode (full autonomy)

The two autonomy modes

Nika operates by explicit toggle between two mutually exclusive modes.

Plan mode

Activated when scope is ambiguous, under-specified, or when a user request admits multiple defensible interpretations. In Plan mode the kernel:

• asks targeted questions (never more than 4);
• structures the request into a PROJ / JOB / TASK / SUB hierarchy;
• waits for explicit human validation before any Edit, Write, or pod spawn.

Execution mode

Activated as soon as a brief is validated or the request is unambiguous. In Execution mode the kernel:

• never asks for permission;
• explores multiple paths in parallel when useful;
• mutates its mutable primitives (hyperparameters, formulations, heuristics) on failure rather than waiting for instruction.

Pods are always in Execution mode. A pod that asks “shall I continue?” is a bug to fix, not a behavior to accept.

Minimum vocabulary

Term	Definition
Kernel agent	The orchestrator pod (master CLI-agent instance). Receives the user prompt, decides strategy, spawns worker pods when needed.
Pod	A specialized CLI-agent instance, running in a dedicated tmux, charged with one isolable mission. Lifecycle: spawn → invoke → observe → kill.
Skill	A reusable capability described by a markdown file with name, description, trigger frontmatter. Composable, versioned, mutable through GEPA.
Hook	A Python script attached to a lifecycle event. Reads stdin, writes stdout/stderr, returns an exit code that can block or modify the action.
MCP server	An external server (stdio or HTTP) that exposes tools to the CLI agent through the Model Context Protocol.
Bus	The append-only JSONL file _bus/kernel_bus.jsonl that acts as a permanent audit trail for all inter-agent communication.
RAG	Retrieval-Augmented Generation. Semantic search in Qdrant nika_vault, the first stage of the WATERFALL RETRIEVAL cascade run before any factual claim.
Kernel	The immutable layer of instructions and invariants. Off-limits to automatic mutation — we protect what works.
Harness	The mutable layer: prompt phrasings, hyperparameters, heuristics. Under GEPA tournament: variants compete, the best one survives.

Three golden rules

1. WATERFALL RETRIEVAL (formerly PALACE PROTOCOL) — Never answer a factual question about a client, project, or past decision without first running the wide→narrow retrieval cascade: semantic RAG → naming-key/metadata filter → graph → grep + structured state. If the cascade returns zero relevant hit, say so explicitly instead of fabricating.
2. SQP matrix — Security (P0) > Quality (P1) > Performance (P2). No top-down arbitration can invert this order.
3. Requested scope = delivered scope — No opportunistic refactor during a bug fix. No added feature during a config update.

Going further

• Kernel and pods — the orchestrator, the workers, the spawn contract.
• Memory system — three tiers, five stores, strict separation.
• IPC and bus — Redis Streams, consumer groups, JSONL audit.