LLM (Large Language Model)

A neural network model with billions of parameters trained on vast text corpora to understand and generate human language by predicting the next token in a sequence. LLMs exhibit emergent abilities such as reasoning, translation, summarization, and in-context learning that arise from scale rather than explicit programming. They are the core reasoning engine behind modern AI agents, chatbots, and coding assistants.
See: 01-LLM-and-AI-Models.md (§2)

Foundation Model

A large-scale AI model (typically an LLM or multimodal model) trained on broad data at massive scale, designed to be adapted to a wide range of downstream tasks. Foundation models serve as the base layer upon which specialized models (instruct models, fine-tuned variants) are built. The term was popularized by the Stanford CRFM and encompasses models like GPT-4, LLaMA 3, and Claude.
See: 01-LLM-and-AI-Models.md (§1, §2)

Base Model

A model that has undergone only pre-training (or pre-training plus minimal curation) and is capable of text completion but not instruction following. Base models require careful prompt engineering to elicit useful behavior and are primarily used by developers and researchers who wish to fine-tune further. Example: meta-llama/Llama-3.1-8B (base).
See: 01-LLM-and-AI-Models.md (§5 — Base vs Instruct Models)

Instruct Model (Chat Model)

A model built by fine-tuning a base model on instruction-response pairs via Supervised Fine-Tuning (SFT), optionally followed by alignment techniques such as RLHF or DPO. Instruct models understand conversation formats, follow user instructions, and are designed for direct use in applications. Example: meta-llama/Llama-3.1-8B-Instruct.
See: 01-LLM-and-AI-Models.md (§4.2, §5)

Transformer

The neural network architecture introduced in the paper "Attention Is All You Need" (Vaswani et al., 2017) that serves as the foundation of virtually all modern LLMs. Transformers replace recurrent layers with a multi-head self-attention mechanism, processing all tokens in parallel rather than sequentially, which enables efficient training on massive datasets. Modern LLMs use a decoder-only variant that stacks transformer layers, each containing self-attention, feed-forward networks, layer normalization, and residual connections.
See: 01-LLM-and-AI-Models.md (§3)

Attention

The core mechanism in Transformer models that allows each token to "attend to" every other token in the sequence, computing weighted representations based on relevance. Attention is implemented via Query, Key, and Value (QKV) projections: each token produces a query vector, and the model computes attention scores by taking the dot product of that query with all key vectors, then using the resulting weights to aggregate the corresponding value vectors. Multi-head attention runs this process in parallel across multiple representation subspaces.
See: 01-LLM-and-AI-Models.md (§3.1, §3.5)

Token

The fundamental unit of text that a language model processes — typically a sub-word unit rather than a whole word. Tokenization converts raw text into token IDs using algorithms such as Byte-Pair Encoding (BPE), WordPiece, or SentencePiece. One token corresponds to approximately 0.75 English words on average, and pricing for LLM APIs is typically per token (input and output billed separately).
See: 01-LLM-and-AI-Models.md (§3.2, §9.1)

Embedding

A dense vector representation that encodes semantic meaning, typically with 1024–8192 dimensions. Each token ID is mapped to a high-dimensional embedding vector via a lookup table (token embeddings), and positional information is injected separately (e.g., via RoPE). Embedding spaces capture semantic relationships — similar words have similar vectors — and the final hidden state at the last token position is commonly used as a contextual representation for downstream tasks.
See: 01-LLM-and-AI-Models.md (§3.3, §9.2)

Context Window

The maximum number of tokens a model can process in a single forward pass, including both the prompt and the generated response. Modern models have context windows ranging from 8K (LLaMA 3) to 128K-200K (GPT-4 Turbo, Claude 3, LLaMA 3.1), with Gemini 1.5 Pro supporting up to 2M tokens. Managing context window limits is a central challenge in agent systems and RAG pipelines.
See: 01-LLM-and-AI-Models.md (§8.2)

KV Cache (Key-Value Cache)

A memory optimization technique that stores the Key and Value matrices from previously generated tokens during autoregressive decoding, avoiding redundant recomputation. The KV cache grows linearly with sequence length and batch size (approximately 1 MB per token for a 8B-parameter model). Optimizations such as PagedAttention, grouped-query attention (GQA), and cache quantization are used to manage its memory footprint.
See: 01-LLM-and-AI-Models.md (§8.3)

MoE (Mixture of Experts)

An architecture that achieves better performance per FLOP by having many specialized sub-networks ("experts") while activating only a subset for each input token. A router network selects the top-k experts (typically k=2) per token, enabling the model to have a large total parameter count (e.g., 671B in DeepSeek-V3) while keeping active parameters per token much smaller (e.g., 37B). MoE models have a large memory footprint but compute cost similar to a smaller dense model.
See: 01-LLM-and-AI-Models.md (§6.3)

Fine-tuning

The process of updating a pre-trained model's weights on a dataset of domain-specific examples to adapt it for a particular task or behavior. Fine-tuning can range from full parameter updates to parameter-efficient methods like LoRA (Low-Rank Adaptation) that train small adapter modules. It is distinct from RAG in that it modifies the model's internal weights rather than augmenting its input context.
See: 01-LLM-and-AI-Models.md (§4.2, §9.5)

SFT (Supervised Fine-Tuning)

A training stage after pre-training in which the model is fine-tuned on instruction-response pairs to teach it to follow user instructions and produce helpful, formatted responses. SFT typically uses 10,000–100,000 high-quality examples and optimizes the standard next-token prediction loss only on the response tokens. This transforms a base model (text completion) into an instruct model (conversational).
See: 01-LLM-and-AI-Models.md (§4.2)

RLHF (Reinforcement Learning from Human Feedback)

An alignment technique that trains a model to produce outputs preferred by humans through a three-step pipeline: (1) SFT warmup, (2) training a separate reward model on human preference rankings, and (3) using Proximal Policy Optimization (PPO) to fine-tune the model to maximize the reward model's score while staying close to the original SFT model via a KL penalty. RLHF was popularized by InstructGPT/ChatGPT and is used by most frontier models.
See: 01-LLM-and-AI-Models.md (§4.3)

DPO (Direct Preference Optimization)

A simpler alternative to RLHF that directly optimizes the model on preference pairs without training a separate reward model or using reinforcement learning. DPO uses a loss function that increases the relative log-probability of preferred responses over dispreferred responses. It has largely replaced PPO in open-source fine-tuning pipelines due to its simplicity and competitive performance.
See: 01-LLM-and-AI-Models.md (§4.3)

Distillation (Knowledge Distillation)

A technique that trains a smaller "student" model to mimic the output probability distribution of a larger "teacher" model, using the KL divergence between their logits as an additional loss term. This transfers the teacher's "soft knowledge" — including which alternative tokens are plausible — resulting in a model that is 1/10th the size while retaining 95%+ of the teacher's performance. Distillation differs from pruning (removing weights) and quantization (lowering precision).
See: 01-LLM-and-AI-Models.md (§9.6)

Hallucination

The phenomenon where an LLM generates information that is false, fabricated, or nonsensical but presented as factual. Hallucinations can be intrinsic (contradicting provided context), extrinsic (inventing unverifiable information), or factual (stating incorrect facts). Mitigation strategies include RAG (grounding generation in retrieved documents), chain-of-thought prompting, self-consistency, and constrained decoding.
See: 01-LLM-and-AI-Models.md (§9.3)

Quantization

The process of reducing the numerical precision of model weights (and optionally activations) to decrease memory usage and increase inference speed, at the cost of some accuracy. Common precision levels include FP16, INT8, INT4, and NF4. Quantization can be applied post-training (PTQ) or simulated during training (QAT), and the optimal format depends on the target hardware (CPU, consumer GPU, or data-center GPU).
See: 01-LLM-and-AI-Models.md (§7)

GGUF (GPT-Generated Unified Format)

A single-file quantization format created by the llama.cpp community (successor to GGML) that bundles model weights, tokenizer, and metadata into one file. GGUF offers quantization levels from q2_k to q8_0 and is optimized for CPU inference via llama.cpp, making it the standard choice for running models on consumer hardware, laptops, and edge devices.
See: 01-LLM-and-AI-Models.md (§7.3)

GPTQ (GPT-Post-Training Quantization)

A GPU-optimized quantization format based on the paper "GPTQ: Accurate Post-Training Quantization for Generative Pre-Trained Transformers." GPTQ stores weights as safetensors with a quantization config and is best used with CUDA-based inference engines such as AutoGPTQ and ExLlama. It offers good GPU performance and efficient batching but requires a calibration dataset.
See: 01-LLM-and-AI-Models.md (§7.3)

AWQ (Activation-aware Weight Quantization)

A quantization format that achieves better quality than GPTQ at the same bit-width by accounting for activation magnitudes during weight quantization. AWQ is optimized for GPU inference via engines such as vLLM, AutoAWQ, and TensorRT-LLM, and has become a preferred choice for production serving due to its quality retention and speed.
See: 01-LLM-and-AI-Models.md (§7.3)

Speculative Decoding

A technique that accelerates text generation without quality loss by using a small "draft" model to quickly generate several candidate tokens, which are then verified in parallel by the large "target" model in a single forward pass. This typically yields a 2–3x speedup and is supported by inference frameworks such as vLLM and TensorRT-LLM.
See: 01-LLM-and-AI-Models.md (§8.5)

Prompt Engineering

The practice of designing input prompts to elicit desired behavior from an LLM, including techniques such as zero-shot prompting, few-shot prompting, chain-of-thought reasoning, role prompting, negative prompting, and structured output formatting. Effective prompt engineering is critical for getting reliable, accurate results from base and instruct models alike.
See: 01-LLM-and-AI-Models.md (§9.4)

System Prompt

A special prompt that sets the model's behavioral guidelines, persona, and constraints, typically hidden from the end user and injected at the start of every conversation. System prompts define the model's role (e.g., "You are a helpful coding assistant"), establish safety guardrails, and configure output formatting preferences. They are distinct from user prompts, which contain the actual request.
See: 01-LLM-and-AI-Models.md (§9.4, §9.8)

Function Calling (Tool Use)

A capability of modern LLMs to generate structured output (typically JSON) specifying which external function or API to call and with what arguments, enabling the model to interact with tools, databases, search engines, and other external systems. Function calling is the model-level mechanism that expresses intent to use a tool, while MCP is the application-level protocol that discovers, describes, and invokes those tools.
See: 01-LLM-and-AI-Models.md (§9.8); 03-MCP-and-ACP-Protocols.md (Comparison to Function Calling)

RAG (Retrieval-Augmented Generation)

An AI paradigm that combines a retrieval system with a generative LLM: relevant document chunks are first retrieved from an external knowledge base (vector database or search index) and then fed as context to the LLM to produce a grounded, factually accurate response. RAG addresses LLM limitations including stale knowledge, hallucination, lack of attributability, and domain-specificity, without requiring model retraining.
See: 02-RAG-Retrieval-Augmented-Generation.md (§1, §2); 01-LLM-and-AI-Models.md (§9.5)

Chunking

The process of dividing documents into manageable segments (chunks) before embedding and indexing for RAG retrieval. Chunking strategies include fixed-size overlap splitting, semantic chunking (splitting at natural boundaries), recursive splitting, and agentic chunking. The chunk size, overlap, and strategy directly impact retrieval quality and the amount of context passed to the LLM.
See: 02-RAG-Retrieval-Augmented-Generation.md (§3.1, §6)

Embedding Model

A specialized neural network that converts text into fixed-dimensional dense vectors (embeddings) that capture semantic meaning, enabling similarity search. The same embedding model must be used to embed both documents (during indexing) and queries (during retrieval) to ensure they map to the same vector space. Popular embedding models include OpenAI's text-embedding-3, Cohere's Embed, and open-source models like BGE and E5.
See: 02-RAG-Retrieval-Augmented-Generation.md (§3.1, §7)

Vector Database (Vector Store)

A database optimized for storing embedding vectors and performing efficient Approximate Nearest Neighbor (ANN) search, enabling semantic similarity retrieval at scale. Vector databases support indexing (building search structures over embeddings) and querying (finding the top-k most similar vectors to a query embedding). Examples include Pinecone, Weaviate, ChromaDB, Qdrant, and Milvus.
See: 02-RAG-Retrieval-Augmented-Generation.md (§3.1, §8)

Semantic Search

A search paradigm that retrieves results based on meaning rather than exact keyword matching, powered by embedding models and vector databases. Unlike lexical search (BM25) which matches literal terms, semantic search captures conceptual relationships — e.g., a query about "canine health" can retrieve documents about "dog nutrition." Production RAG systems often combine both approaches in hybrid retrieval with reciprocal rank fusion.
See: 02-RAG-Retrieval-Augmented-Generation.md (§3.2)

MCP (Model Context Protocol)

An open-standard, client-server protocol developed by Anthropic that provides a standardized interface for LLMs to interact with external systems — databases, file systems, APIs, search engines, code repositories, and any other tool or data source. MCP solves the fragmentation problem where every LLM-to-tool integration was previously a bespoke implementation, analogous to how USB standardized peripheral connections for computers. The protocol uses JSON-RPC 2.0 over transport channels (stdio or SSE) and defines three core primitives: Tools, Resources, and Prompts.
See: 03-MCP-and-ACP-Protocols.md (§Part I)

MCP Host

The top-level application or environment where the LLM operates and the user interacts. The host manages MCP client connections, handles authentication and authorization, controls which servers are available, processes the LLM's tool invocation decisions, and presents results to the user. Examples include Claude Desktop, VS Code extensions, CLI tools, and custom applications that embed an LLM.
See: 03-MCP-and-ACP-Protocols.md (Architecture: Host, Client, Server)

MCP Client

A protocol-level component embedded within the host application that establishes and manages a 1:1 connection with an MCP server. The client handles transport initialization, protocol version negotiation, sending requests (tool calls, resource reads, prompt retrievals), receiving responses, and managing connection state. A single host may run multiple clients simultaneously, each connected to a different server, but the client is distinct from the LLM itself — it is a protocol adapter.
See: 03-MCP-and-ACP-Protocols.md (Architecture: Host, Client, Server)

MCP Server

A lightweight, single-purpose adapter that exposes a specific tool, data source, or service through the MCP protocol. Each server implements the MCP specification, registers its capabilities during initialization (tools, resources, prompts), handles incoming requests, and communicates with the underlying external system. Servers are independently deployable and can run locally (as subprocesses via stdio transport) or remotely (over HTTP via SSE transport).
See: 03-MCP-and-ACP-Protocols.md (Architecture: Host, Client, Server)

Tool (in MCP)

An executable operation that the LLM can invoke through the host application — the "do something" primitive of MCP. Tools are model-initiated, stateless operations with defined input schemas (JSON Schema), and their execution typically requires user approval. Common tool categories include file operations, database queries, API integrations, code operations, web operations, and system commands.
See: 03-MCP-and-ACP-Protocols.md (Protocol Primitives — Tools)

Resource (in MCP)

A data source that can be read by the LLM — the "know something" primitive of MCP. Resources are read-only, URI-addressed data items (text, binary, or structured) that provide context. Clients can list available resources, read their contents, and optionally subscribe to change notifications. Resource templates allow servers to expose dynamic resources with URI patterns (e.g., file:///{path}).
See: 03-MCP-and-ACP-Protocols.md (Protocol Primitives — Resources)

Prompt (in MCP)

A pre-defined, reusable prompt template that an MCP server can provide — the "structured interaction" primitive of MCP. Prompts can include dynamic arguments that get substituted at retrieval time and can consist of multiple messages with different roles (system, user, assistant). They serve as domain-specific interaction templates, pre-configured workflows, or contextual assistance patterns.
See: 03-MCP-and-ACP-Protocols.md (Protocol Primitives — Prompts)

ACP (Agent Communication Protocol)

An emerging open specification that defines how autonomous AI agents discover each other, exchange messages, coordinate actions, and share information in a multi-agent environment. While MCP standardizes LLM-to-tool communication (vertical integration), ACP standardizes agent-to-agent communication (horizontal integration). ACP is still in early-stage development with no canonical reference implementation, unlike the more mature MCP.
See: 03-MCP-and-ACP-Protocols.md (§Part II)

ACP Transport

The communication channel underlying ACP agent interactions, which may include HTTP, WebSocket, and message queues (to be formally defined as the protocol matures). Unlike MCP's well-defined stdio and SSE transports, ACP's transport layer is still being designed and will need to support discovery mechanisms (static configuration, capability registries, peer-to-peer) and communication patterns (request-response, task delegation, broadcast, pub-sub, negotiation).
See: 03-MCP-and-ACP-Protocols.md (§Part II — How Agents Discover and Communicate)

SSH-SCP Transport (SSP)

Not an ACP transport per se, but a related remote-execution protocol. SSP (Secure Session Protocol) is a proprietary protocol used by Claude Code for remote machine control, allowing the coding agent to execute commands and manage files on a remote host. This is distinct from MCP's stdio/SSE transports and ACP's emerging transport specifications. The term "SSH-SCP" is sometimes used conversationally to refer to SSH-based remote agent execution (supported by Hermes Agent via its terminal backends).
See: 05-OpenCode-ClaudeCode-and-Hermes-Agent.md (§2.3, §2.4)

AI Agent

An autonomous software entity that perceives its environment, processes information, makes decisions, and takes actions to achieve specific goals by leveraging LLMs or other AI models for reasoning. Agents operate in a perception-action cycle: they observe, reason about what to do next, execute actions (typically via tool calls), observe results, and repeat. Core characteristics include autonomy, tool-use, reasoning (ReAct, CoT, reflection), memory (short-term, long-term, episodic), and planning.
See: 04-AI-Agents-and-Orchestrators.md (§1)

AI Orchestrator

An intelligent coordination layer that manages multiple AI agents, tools, sub-systems, and data sources to accomplish complex, multi-step objectives. Unlike a simple agent that executes tasks directly, an orchestrator delegates to specialized sub-agents, monitors progress, aggregates results, and makes high-level decisions about task prioritization, reallocation, and synthesis. An orchestrator is essentially an agent that manages other agents.
See: 04-AI-Agents-and-Orchestrators.md (§2)

Agent Loop

The core execution cycle of an AI agent, typically following a ReAct pattern: the agent receives input, reasons about what to do (Thought), executes a tool call or action (Action), processes the result (Observation), and repeats until the goal is achieved. The agent loop is the fundamental operational pattern that distinguishes autonomous agents from stateless LLM calls.
See: 04-AI-Agents-and-Orchestrators.md (§1.4); 05-OpenCode-ClaudeCode-and-Hermes-Agent.md (§1.3, §2.3, §3.3)

ReAct (Reasoning + Acting)

A widely used agent architecture proposed by Yao et al. (2022) that interleaves reasoning traces with action execution. Instead of generating a full plan upfront, the agent alternates between Thought (reasoning about current state), Action (calling a tool), and Observation (processing the result). ReAct forms the basis of LangChain agents, OpenAI Assistants, and most modern agent implementations.
See: 04-AI-Agents-and-Orchestrators.md (§1.4)

Chain-of-Thought (CoT)

A prompting and reasoning technique where the model generates intermediate reasoning steps before arriving at a final answer, significantly improving performance on math, logic, and multi-step reasoning tasks. CoT can be triggered zero-shot (by adding "Let's think step by step") or via few-shot examples. It is distinct from ReAct in that CoT focuses on reasoning alone, while ReAct interleaves reasoning with external actions.
See: 04-AI-Agents-and-Orchestrators.md (§1.2 — Reasoning); 01-LLM-and-AI-Models.md (§9.4, §9.8)

Task Decomposition

The process by which an orchestrator or agent breaks down a high-level goal into smaller, well-defined sub-tasks that can be assigned to specialized agents or tools. Decomposition can be top-down (recursive breakdown until tasks are atomic), template-based (using predefined workflow patterns), or dynamic (LLM-generated on the fly). Effective decomposition considers dependencies, granularity, and resource requirements.
See: 04-AI-Agents-and-Orchestrators.md (§2.3 — Task Decomposition, §4.1)

Subagent

A specialized AI agent spawned by an orchestrator or parent agent to execute a specific sub-task independently. Subagents operate in their own context with their own tools and instructions, and they report results back to the parent. They enable parallel execution of independent workstreams and are a core building block of scalable multi-agent systems.
See: 04-AI-Agents-and-Orchestrators.md (§2.3 — Subagent Management, §4.1)

Tool-use

The capability of an AI agent to call external tools, APIs, and services to perform actions beyond text generation — such as reading files, executing code, searching the web, sending messages, or querying databases. Tool-use transforms an LLM from a static text generator into an active agent and is typically exposed through a function-calling interface where the agent outputs structured JSON specifying which tool to call and with what parameters.
See: 04-AI-Agents-and-Orchestrators.md (§1.2 — Tool-Use); 01-LLM-and-AI-Models.md (§9.8)

Autonomous Agent

An AI agent that operates without human intervention for extended periods, making independent decisions about tool selection, error recovery, and goal satisfaction. The degree of autonomy varies: some agents require human-in-the-loop approval for critical actions (e.g., file deletion, API calls with side effects), while others operate fully autonomously with only high-level goal supervision.
See: 04-AI-Agents-and-Orchestrators.md (§1.2 — Autonomy)

Human-in-the-Loop (HITL)

A design pattern where human oversight is integrated into the agent's decision-making process at specific checkpoints, typically for high-risk actions, ambiguous situations, or quality gates. HITL can be implemented at the per-action level (user must approve each tool call), the per-task level (user reviews intermediate results), or the workflow level (user approves the overall plan before execution).
See: 04-AI-Agents-and-Orchestrators.md (§1.2, §2.3, §3.3); 03-MCP-and-ACP-Protocols.md (Security Considerations)

Orchestration Pattern

A structured approach to coordinating multiple sub-tasks or agents within an orchestrator workflow. The five primary patterns are:
- Sequential: Sub-tasks execute one after another in dependency order; simple but slow.
- Parallel: Independent sub-tasks execute concurrently; faster but requires dependency analysis.
- Hierarchical: A tree structure with manager agents overseeing worker agents; scalable but adds latency.
- Recursive: Complex sub-tasks are further decomposed on demand; handles unknown complexity gracefully.
- Hybrid: Combines multiple patterns within a single workflow; used in virtually all production systems.
See: 04-AI-Agents-and-Orchestrators.md (§5)

Multi-Agent System

A system in which multiple AI agents collaborate, coordinate, and communicate to accomplish goals that exceed the capability of any single agent. Multi-agent systems can use various coordination mechanisms (ACP for communication, orchestrators for task delegation, shared memory for state) and patterns (role-based teams, debate/consensus, market-based allocation). Frameworks like CrewAI, AutoGen, and LangGraph specialize in building multi-agent systems.
See: 04-AI-Agents-and-Orchestrators.md (§1.5); 03-MCP-and-ACP-Protocols.md (§Part II)

Agent Framework

A software library or platform that provides the infrastructure for building, deploying, and managing AI agents. Key frameworks include LangChain/LangGraph (most widely adopted, extensive integration ecosystem), CrewAI (role-based multi-agent teams), AutoGen (Microsoft Research, flexible conversation patterns), Semantic Kernel (enterprise, Azure-integrated), and OpenAI Assistants API (managed platform). These frameworks abstract away common agent patterns such as tool-use, memory, and orchestration.
See: 04-AI-Agents-and-Orchestrators.md (§1.5)

SOUL.md

A Markdown file that defines the core identity, personality, values, and behavioral guidelines for an AI agent or software project. SOUL.md serves as the agent's "constitution" — a persistent reference the agent reads at session start to understand what it is, what it stands for, and how it should behave. It is injected into the agent's context window as a system prompt, ensuring consistent behavior across sessions. The name is intentionally philosophical: it captures the idea that a project has a spirit or character beyond technical specifications.
See: 06-SOUL-and-SKILL.md (§2)

SKILL.md

A structured Markdown file that defines a specific, repeatable procedure or workflow that an AI agent can execute — a unit of procedural knowledge. Unlike SOUL.md (which defines who the agent is), SKILL.md defines what the agent can do. It includes YAML frontmatter (name, description, triggers), numbered execution steps, pitfalls to avoid, and verification criteria. Skills form the agent's "procedural memory" and can be shared, versioned, and composed.
See: 06-SOUL-and-SKILL.md (§3)

AGENTS.md

A project-level instruction file that tells AI agents how to interact with a specific codebase, covering navigation conventions, testing standards, build procedures, and documentation expectations. AGENTS.md blends aspects of both SOUL.md (behavioral rules) and SKILL.md (procedures) into a single, shorter file. It originated in the open-source AI coding ecosystem and is commonly used as a lightweight alternative to separate SOUL.md and SKILL.md files.
See: 06-SOUL-and-SKILL.md (§4.1)

CLAUDE.md

A project-level configuration file specific to Anthropic's Claude Code that tells the assistant how to behave in a given repository. It typically includes build/test/lint commands, project conventions, and communication preferences. CLAUDE.md is more limited in scope than SOUL.md (focusing on practical coding instructions rather than deep identity) and less structured than SKILL.md (no YAML frontmatter or numbered steps).
See: 06-SOUL-and-SKILL.md (§4.2)

.cursorrules

A project-specific configuration file for Cursor IDE (an AI-powered code editor) that defines rules for how the AI assistant should behave within a project. It includes code style preferences, framework-specific instructions, and response formatting preferences. .cursorrules is editor-specific and uses a JSON configuration format, making it less flexible than SOUL.md/SKILL.md but well-integrated into the Cursor ecosystem.
See: 06-SOUL-and-SKILL.md (§4.3)

Agent Identity

The concept, formalized in SOUL.md, that an AI agent should have a defined character encompassing its name, role, core values, communication style, behavioral constraints, and domain knowledge. Agent identity is injected as context at session start and persists across interactions, providing a stable foundation for decision-making and human-AI alignment. It is the "who" that precedes the "how" (skills).
See: 06-SOUL-and-SKILL.md (§2.1, §2.4)

Procedural Memory

An agent's library of encoded procedures for performing specific tasks, analogous to the part of human memory that stores knowledge of how to do things. In AI agent systems, procedural memory is implemented as a collection of SKILL.md files (or equivalent skill definitions) that the agent loads and executes when triggered. Procedural memory is granular, composable, learnable (new skills can be added without retraining), shareable, versionable, and debuggable.
See: 06-SOUL-and-SKILL.md (§3.7)

OpenCode

An open-source, terminal-based AI coding agent built by the opencode-ai community, written in Go with a rich TUI (Bubble Tea framework), multi-provider AI support, LSP integration, and MCP connectivity. The original opencode-ai/opencode repository has been archived; the project has evolved into Crush by the Charm team, which inherits and extends OpenCode's architecture with industrial-grade cross-platform support and enhanced MCP (HTTP, stdio, SSE).
See: 05-OpenCode-ClaudeCode-and-Hermes-Agent.md (§1)

Crush

The active successor to OpenCode, developed by the Charm team (charmbracelet/crush). Crush adds industrial-grade terminal support across macOS, Linux, Windows, Android, FreeBSD, OpenBSD, and NetBSD, plus multi-model mid-session switching and enhanced MCP support. It is written in Go under the MIT license.
See: 05-OpenCode-ClaudeCode-and-Hermes-Agent.md (§1.5)

Claude Code

A proprietary, agentic coding tool built by Anthropic that lives in the terminal, understands codebases, and assists with coding tasks through natural language. Written in TypeScript/Node.js, Claude Code features an advanced agentic loop, enterprise-grade prompt caching, MCP integration, SSP remote control, a plugin system, and CLAUDE.md project-level memory. It is tied exclusively to Anthropic's Claude models and is available as a free (rate-limited) or paid per-token service.
See: 05-OpenCode-ClaudeCode-and-Hermes-Agent.md (§2)

Hermes Agent

A self-improving, multi-platform AI agent built by Nous Research, written in Python under the MIT license. Hermes Agent features a closed learning loop (autonomous skill creation from experience), persistent memory (MEMORY.md, USER.md, FTS5 search, Honcho dialectic modeling), a skills system (procedural memory with auto-generated skills), subagent delegation, scheduled automations (cron), multi-platform support (Telegram, Discord, Slack, WhatsApp, Signal, CLI), 20+ model providers, full MCP integration, and multiple terminal backends (Local, Docker, SSH, Modal, Daytona).
See: 05-OpenCode-ClaudeCode-and-Hermes-Agent.md (§3)

LangChain / LangGraph

The most widely adopted framework (Python/JS) for building LLM-powered agents. LangChain provides chains, agents, tools, memory, and callbacks; its LangGraph extension enables cyclic graphs (loops, branching) for multi-step agent workflows with streaming, human-in-the-loop, checkpointing, and persistent state.
See: 04-AI-Agents-and-Orchestrators.md (§1.5)

CrewAI

A multi-agent orchestration framework that models agent teams as "crews" with role-based agent design (researcher, writer, etc.) and built-in collaboration patterns. CrewAI supports sequential and hierarchical orchestration modes and is designed for easy setup of multi-agent systems, making it popular for content generation, research, and automation workflows.
See: 04-AI-Agents-and-Orchestrators.md (§1.5)

AutoGen (Microsoft)

A multi-agent conversation framework from Microsoft Research featuring AssistantAgent, UserProxyAgent, GroupChat, and tool registration with type-safe schemas. AutoGen provides built-in code execution sandboxes, flexible conversation patterns, nested chats, and human-in-the-loop capabilities, making it well-suited for complex multi-agent scenarios.
See: 04-AI-Agents-and-Orchestrators.md (§1.5)

The AI landscape is undergoing a structural transformation that rivals the shift from mainframes to personal computing or from desktop to mobile. Over the next three years, the following megatrends will define the trajectory:

• From Chat to Orchestration: The conversational chatbot interface is giving way to AI orchestrators — systems that decompose complex goals, delegate sub-tasks to specialized agents, and manage end-to-end workflows. This is not an incremental improvement; it is a new interaction paradigm.

• Protocol Standardisation as Infrastructure: The Model Context Protocol (MCP) is on track to become the universal "USB-C" for AI-tool integration, while the Agent Communication Protocol (ACP) is defining how agents discover and talk to each other. These protocols are becoming foundational infrastructure in the same way HTTP and TCP/IP became foundational to the internet.

• Model Commoditisation: The gap between open-source and closed-source models is narrowing rapidly. By late 2026, frontier open-weight models will be competitive with proprietary alternatives across most benchmarks, driving down costs and enabling offline, private, and custom deployments.

• Multi-Agent Systems as the Default Architecture: Monolithic AI assistants are being replaced by ecosystems of specialised agents — coding agents, testing agents, research agents, review agents — coordinated by an orchestrator. This mirrors the evolution from monoliths to microservices in software architecture.

• Developers as Orchestrators, Not Programmers: The developer's role is shifting from writing every line of code to designing system architecture, defining agent workflows, and orchestrating AI-assisted development pipelines. Natural language becomes a primary interface for instructing AI agents.

This document examines these trends across three time horizons — near-term (2026–2027), mid-term (2027–2028), and long-term (2028+) — and provides actionable recommendations for developers, teams, and organisations navigating this transition.

2.1 Multi-Agent Systems Go Mainstream

2026 is the year multi-agent architectures moved from research papers and experimental projects into production systems. The pattern is now well-understood: an orchestrator agent decomposes a goal, assigns tasks to specialist agents (coder, tester, researcher, reviewer), and synthesises their outputs. This architecture mirrors the way human engineering teams work and is proving dramatically more effective than monolithic approaches for complex tasks.

Key developments:
- OpenCode, Claude Code, and Hermes Agent (see 05-OpenCode-ClaudeCode-and-Hermes-Agent.md) all support multi-agent workflows, though with different architectures and trade-offs.
- Agent frameworks like LangGraph, CrewAI, AutoGen, and Semantic Kernel have matured, providing production-grade primitives for building multi-agent systems.
- Companies are deploying "agent squads" — teams of 3–10 specialised agents working on a single project — with a human or AI orchestrator managing them.

2.2 Agentic Workflows Replace Simple Automation

Agentic workflows — where an AI doesn't just answer questions but executes multi-step plans involving tool use, decision-making, and error recovery — are now the standard expectation. The shift is visible across the industry:

• Code generation has evolved from single-shot prompt-to-code to iterative workflows where an agent writes code, runs tests, reads error output, fixes bugs, and repeats until passing.
• Research tasks now involve agents that search multiple sources, cross-reference findings, generate reports, and fact-check themselves.
• DevOps sees agents managing CI/CD pipelines, diagnosing failures, and rolling back deployments autonomously.

See 04-AI-Agents-and-Orchestrators.md (§4) for detailed workflow examples.

2.3 MCP/ACP Standardisation in Progress

The Model Context Protocol (MCP), introduced by Anthropic in late 2024, has gained widespread adoption. As of mid-2026:

• MCP is supported by virtually every major AI application — IDE plugins, CLI tools, desktop apps, and server-side platforms. The ecosystem has thousands of MCP servers covering databases, APIs, filesystems, search engines, code repositories, and SaaS platforms.
• ACP (Agent Communication Protocol) is emerging as the complement to MCP. While MCP standardises how AI models connect to tools and data, ACP standardises how agents discover each other, negotiate tasks, share context, and pass results. Multiple draft specifications have been published.
• The relationship between MCP and ACP is analogous to HTTP (client-server resource access) and SMTP (peer-to-peer messaging). They operate at different layers of the stack and are designed to complement, not compete.

See 03-MCP-and-ACP-Protocols.md for a comprehensive treatment of both protocols.

2.4 Model Commoditisation

The economics of AI models have shifted dramatically:

• Open-source catch-up: Models in the LLaMA 3, Qwen 2.5, DeepSeek-V3, and Mistral families are within striking distance of GPT-4o and Claude 3.5 on most benchmarks. For many practical tasks, developers can no longer justify the cost premium of closed-source APIs.
• Price compression: The cost per million tokens has dropped by 10–20x since early 2024. Inference on open-weight models via providers like Together AI, Fireworks, Groq, and Replicate costs pennies per million tokens.
• Small model viability: Quantized 7B–14B parameter models (running locally on consumer hardware) now handle many agentic tasks that required GPT-4 in 2024. See 01-LLM-and-AI-Models.md (§7) for quantization details.
• Specialisation wins: Fine-tuned smaller models often outperform generalist giants on specific domains — code generation, medical diagnosis, legal document analysis, etc.

2.5 The Orchestrator Pattern Emerges

The most important architectural shift of 2026 is the rise of the AI Orchestrator — a meta-agent that doesn't execute tasks itself but manages the lifecycle of a multi-agent workflow. Key characteristics:

• Goal decomposition: Breaks a user's high-level request into a structured plan with dependencies.
• Agent selection: Chooses the right specialist agent(s) for each sub-task.
• Context management: Passes relevant context between agents without leaking irrelevant information.
• Quality control: Reviews outputs, runs validations, and triggers re-execution on failure.
• Human handoff: Knows when to ask for clarification or escalate.

See 04-AI-Agents-and-Orchestrators.md (§2, §3) for a detailed comparison of agents vs orchestrators.

3.1 Agent-to-Agent Communication Becomes Standard

By mid-2027, standalone AI assistants that work in isolation will feel as primitive as single-user desktop applications in the age of networked software. The emerging norm is agent ecosystems where agents communicate, negotiate, and collaborate directly.

What this looks like in practice:
- A research agent discovers a relevant paper and directly messages a summarisation agent with the PDF link, rather than going through the orchestrator.
- A coding agent encountering a build error queries a Q&A agent (trained on the project's documentation) without context-switching.
- Agents subscribe to event streams — "notify me when the test suite passes" — enabling asynchronous, event-driven collaboration.

Protocol implications: ACP will be the backbone of this communication. Early implementations use JSON-RPC over WebSockets, with agent capability discovery (announcing what each agent can do), task negotiation (offering and accepting tasks), and result delivery (structured responses with provenance metadata).

3.2 MCP Becomes the Universal "USB-C" for AI Tool Integration

The tool integration landscape is consolidating around MCP. The analogy to USB is increasingly apt:

• Before MCP: Every tool required a custom integration adapter — bespoke code, unique API patterns, inconsistent authentication, no discoverability.
• MCP today: An MCP server written once works with every MCP-compatible host (Claude Desktop, VS Code extensions, CLI tools, custom applications).
• MCP 2027: Expect MCP to be embedded at the OS level. Operating systems will expose filesystem, networking, and peripheral capabilities as MCP resources. Applications will advertise their MCP endpoints. Browser extensions will expose web content through MCP.

The ecosystem will bifurcate into:
- MCP Producers: Tools and services that expose their capabilities via MCP servers.
- MCP Consumers: AI hosts (IDEs, CLIs, agents, orchestrators) that discover and use MCP capabilities.

This creates a virtuous cycle: more MCP servers → more value for AI hosts → more users → more incentive to build MCP servers.

See 03-MCP-and-ACP-Protocols.md (§4) for protocol future directions.

3.3 Rise of AI Orchestrators as the Primary Interaction Pattern

The conversational chat interface that dominated 2023–2025 (ChatGPT, Claude Chat, Gemini) is being superseded by the orchestrator interface:

• Chatbots answer questions and perform simple actions.
• Orchestrators manage complex projects: "Build a full-stack expense tracker app with user auth, a REST API, SQLite database, and a dashboard" — and then execute it end-to-end by coordinating multiple specialist agents.

Key characteristics of orchestrator interfaces:
- Project-level state: The orchestrator maintains a persistent project context — decisions made, files created, architecture chosen, tests passed.
- Plan-before-execute: The orchestrator shows its plan before executing, allowing human approval or modification at each step.
- Transparent delegation: Users can see which agent is working on what and review intermediate outputs.
- Human-in-the-loop: Critical decisions (API design, database schema, security choices) are flagged for human review by default.

3.4 Specialised Agents Replace Monolithic AI Assistants

The era of the "one AI to rule them all" is ending. The trend is toward federations of specialised agents, each optimised for a narrow domain:

Orchestrators route tasks to the right specialist. This is analogous to how a microservices architecture routes requests to the right service, rather than having one monolithic application do everything.

Advantage: Each agent can be smaller, faster, and cheaper — a 7B-parameter code agent running locally can outperform a 70B-parameter generalist on code tasks, at a fraction of the latency and cost.

3.5 Persistent Memory and Self-Improving Agents

One of the biggest limitations of current AI agents is their statelessness — each session starts fresh with no memory of past projects, preferences, or lessons learned. This is changing rapidly:

2026–2027 developments:
- Agent memory stores built on vector databases (ChromaDB, Milvus, Weaviate) that persist across sessions. Agents store project decisions, user preferences, coding conventions, and error patterns.
- Reflection loops where agents review their own past work and update their memory with lessons learned. See 04-AI-Agents-and-Orchestrators.md (§1.2) for memory types.
- RAG-based memory retrieval (see 02-RAG-Retrieval-Augmented-Generation.md) enables agents to recall relevant past experiences before starting a new task.
- Profile-based identity — SOUL.md and SKILL.md files (see 06-SOUL-and-SKILL.md) encode an agent's identity, preferences, and procedures in a portable format, enabling consistent behavior across environments.

Self-improvement mechanism:
1. Agent completes a task
2. Agent reflects on what went well and what went wrong
3. Key insights are stored as memory embeddings
4. On the next similar task, agent retrieves and applies those lessons
5. Over time, the agent becomes measurably better at its domain

3.6 Smaller, Specialised Models (SLMs) vs Giant General Models

The conventional wisdom that "bigger is better" is being challenged by Small Language Models (SLMs) that are purpose-built for specific tasks:

The winning strategy: Use a small, fast SLM for 80% of tasks (routing, classification, simple code generation) and reserve the giant model for the 20% that requires deep reasoning. This is the same pattern as caching — use cache for common requests, hit the origin for misses.

Quantization (see 01-LLM-and-AI-Models.md (§7)) is a key enabler: a 70B model quantized to 4-bit fits in ~35 GB of VRAM, making it deployable on a single high-end consumer GPU.

4.1 Autonomous AI Development Teams

By 2028, the concept of an autonomous software development team — an AI orchestrator managing a squad of specialised coding agents — will be a standard approach for many projects. This is not replacing human developers; it is augmenting them with an AI development team that works alongside human teams.

The autonomous team structure:

Human Developer (Product Owner / Architect)
    |
    v
AI Orchestrator (Project Manager / Tech Lead)
    |
    ├── Coder Agent(s)         — writes implementation code
    ├── Reviewer Agent         — reviews code for quality, security, style
    ├── QA / Tester Agent      — writes and runs tests, reports failures
    ├── Docs Agent             — maintains documentation
    ├── DevOps Agent           — manages CI/CD, deployments, infrastructure
    └── Security Agent         — scans for vulnerabilities, checks compliance

Key capabilities emerging in this period:
- Autonomous bug fixing: The orchestrator receives a test failure report, assigns root cause analysis to a debug agent, routes the fix to a coder agent, and triggers re-testing — all without human intervention.
- Continuous refactoring: Background agents analyse code quality metrics and propose refactoring changes, with the orchestrator scheduling them during low-velocity periods.
- Cross-project learning: An agent that learned a pattern in one project (e.g., "always use parameterised queries to prevent SQL injection") propagates that knowledge across all projects in the organisation.

See 04-AI-Agents-and-Orchestrators.md (§4.3) for the current state of AI-powered software development pipelines.

4.2 Enterprise AI Governance and Compliance Frameworks

As AI agents gain autonomy in production, enterprise governance becomes critical. The period 2027–2028 will see the maturation of:

Governance layers:
- Policy enforcement: Policies encoded as machine-readable rules that agents check before actions. Example: "Never deploy to production on Friday" → the orchestrator blocks deployment actions on Fridays.
- Audit trails: Every agent action — tool calls, decisions, failures — is logged with full provenance. Blockchains or append-only databases are used for tamper-evident audit logs.
- Approval gates: Critical actions (production deployments, data deletion, financial transactions) require multi-factor human approval, enforced at the protocol level rather than within agent code.
- Compliance by design: Agents are pre-configured with regulatory constraints (GDPR, HIPAA, SOC2, PCI-DSS) that constrain their behaviour without requiring developer awareness.

The role of SOUL.md and SKILL.md:
Configuration files like SOUL.md and SKILL.md (see 06-SOUL-and-SKILL.md) become the standard way to encode governance constraints directly into agent identity. A SOUL.md file might include:
- "I must never access production databases directly"
- "I must log all actions to the audit stream"
- "I must obtain human approval before modifying authentication code"

4.3 On-Device AI Capable of Full Agentic Workflows

The hardware landscape is shifting to support AI on consumer devices:

2027–2028 hardware trends:
- Neural Processing Units (NPUs) become standard in laptops, tablets, and smartphones. Apple's Neural Engine, Qualcomm's AI Engine, and Intel's NPU provide dedicated hardware for inference.
- Unified memory (Apple Silicon M-series) continues to expand, with 64 GB+ RAM on laptops, enabling 7B–13B parameter models to run with full context windows.
- NPU-optimised models — quantized, distilled, and pruned — achieve GPT-3.5-class performance at 1–3 watts.
- Hybrid inference — run small models locally for speed/privacy, fall back to cloud for hard problems — becomes the default pattern.

What on-device AI enables:
- Always-available agents: No internet required for common agentic tasks — code completion, local file analysis, personal assistant functions.
- Privacy: Sensitive data never leaves the device. Code, legal documents, medical records are processed locally.
- Low latency: Local inference is 10–50x faster than cloud API calls, enabling real-time agent interactions.
- Cost savings: No per-token costs for the 80% of tasks handled locally.

4.4 Protocol Standardisation: MCP and ACP Converging or Complementing

By 2028, the protocol landscape will likely settle into one of two scenarios:

Scenario A: Convergence (more likely)
MCP and ACP merge into a unified protocol or a single specification with multiple profiles. The combined protocol covers both tool access (MCP's domain) and agent communication (ACP's domain). This is analogous to how HTTP/2 subsumed SPDY, or how USB-C subsumed multiple connector types.

Scenario B: Complementary Standardisation (also plausible)
MCP and ACP remain separate but with clearly defined boundaries:
- MCP handles the "southbound" interface — AI models connecting to tools, data, and services.
- ACP handles the "northbound" interface — AI agents communicating with each other and with orchestrators.
- A gateway/routing layer translates between the two protocols when needed.

Regardless of which scenario unfolds:
- The industry will converge on 1–2 open standards rather than the current fragmented landscape.
- Both protocols will incorporate security, authentication, and rate-limiting as first-class primitives.
- Protocol discovery — a service mesh for AI agents — will emerge, where agents register their capabilities and find each other dynamically.

5.1 Towards AGI? Multi-Agent Emergent Intelligence

The path to Artificial General Intelligence (AGI) may not be a single giant model, but rather emergent intelligence from multi-agent systems. This is the most debated question in AI research today:

The multi-agent emergence hypothesis:
- Individual AI agents are narrow specialists, each good at one domain.
- When orchestrated correctly, a sufficiently diverse set of agents can exhibit general intelligence — the ability to handle novel problems across domains.
- The orchestrator itself becomes the "general intelligence" layer, reasoning about which specialist to deploy for which problem.
- This mirrors human intelligence: individual neurons are simple, but their orchestration produces general intelligence.

Signs this is already happening:
- Multi-agent systems outperform single-agent systems on complex, novel tasks by 20–50% on benchmarks like SWE-bench and GAIA.
- The combination of a code agent + research agent + QA agent can solve problems that none could solve alone.
- Emergent capabilities — like cross-domain analogical reasoning — appear in multi-agent systems at a threshold of ~5–8 diverse agents.

Counter-argument: Critics argue that true AGI requires a unified world model, not just specialised modules glued together. The debate will intensify through 2028–2030.

5.2 AI-Native Operating Systems

The operating systems of 2030 will be fundamentally different from today's:

Current OS: Human-centric interface (mouse/keyboard/touch), applications are separate programs, filesystem is the primary data model.

AI-Native OS:
- Primary interface is natural language and intent. Users express goals, not commands. "Find the presentation I was working on last week about Q3 projections and email it to the executive team."
- Agents are first-class OS primitives. The OS manages a personal fleet of agents — a research agent, a file management agent, a communication agent — that persist across sessions and learn user preferences.
- MCP is the OS system bus. Every device capability (filesystem, network, peripherals, sensors) is exposed via MCP endpoints. AI applications discover and use hardware capabilities the same way they discover and use any tool.
- Filesystem as an agent memory store. The traditional hierarchical filesystem is augmented or replaced by a semantic memory store that supports vector search, relationship queries, and temporal queries. "Show me all documents related to the Q3 project" works without organising files into folders.
- Permissions and privacy are enforced at the agent level. Users grant or deny capabilities to agents (read files, send email, access camera) rather than to applications.

Early precursors:
- Apple Intelligence and Microsoft Copilot are early steps toward agent-augmented operating systems.
- MCP running on the host OS is a prototype of the AI-native system bus.
- SOUL.md and SKILL.md (see 06-SOUL-and-SKILL.md) are early examples of agent identity configuration that could be standardised at the OS level.

5.3 Universal Developer Interface: Natural Language > Code

The most transformative long-term change for software development:

The evolving stack:

What changes:
- Natural language becomes a compile target. Developers describe what they want in natural language, and the AI system generates the code, tests, documentation, and deployment configuration.
- Code review becomes architecture review. Human developers review AI-generated designs and architecture decisions, not individual lines of code. The code itself is treated as an intermediate representation.
- Debugging becomes conversation. Instead of reading stack traces, developers describe symptoms to a debug agent that traces the issue, proposes fixes, and verifies them.
- Testing becomes specification. Developers write test specifications in natural language ("The checkout flow should reject expired credit cards and show a friendly error message"), and the QA agent generates and runs the actual test code.

This does NOT mean developers are obsolete. It means:
- Developers become architects and orchestrators. The value shifts from writing code to designing systems, defining agent workflows, making architectural decisions, and ensuring quality.
- The bottleneck shifts from implementation capacity to design capacity. With AI handling implementation, the limiting factor becomes how well you can specify what to build.
- New skills emerge: Prompt engineering for agent orchestration, workflow design, agent quality assurance, and AI governance.

6.1 How Software Development Changes

The role of a software developer is transforming more dramatically than at any point in the last 30 years:

Activities that decrease in importance:
- Writing boilerplate code (AI generates it faster and more correctly)
- Manual debugging and log spelunking (AI agents automate root cause analysis)
- Writing routine tests (AI generates comprehensive test suites from specifications)
- Context switching between tools (orchestrators manage the tool chain)
- Remembering API signatures and framework details (agents have perfect recall)

Activities that increase in importance:
- System architecture and design: Deciding what to build, how components interact, what trade-offs to make.
- Agent workflow design: Defining how orchestrators decompose goals, which specialist agents to use, and how they collaborate.
- Quality assurance at scale: Reviewing AI-generated code for correctness, security, and alignment with intent.
- Prompt engineering and agent configuration: Crafting effective prompts for agents, configuring SOUL.md and SKILL.md files, tuning agent behaviour.
- AI governance: Understanding and enforcing ethical constraints, security policies, and regulatory compliance in AI-generated output.

6.2 New Skills Needed

For developers in 2026–2028:

6.3 Role of AI Orchestrators in the Development Lifecycle

The complete software development lifecycle (SDLC) is being reimagined around AI orchestrators:

The human developer's role in this model:
- Design review: The orchestrator proposes an architecture; the human approves or modifies it.
- Quality gate: The orchestrator flags code quality or security issues; the human makes the final call on blockers.
- Exception handling: When the orchestrator encounters a situation it can't resolve, it escalates to the human.
- Strategic direction: The human decides what to build and why; the orchestrator handles how.

7.1 What to Learn Now

Immediate (next 3 months):
1. Master an orchestrator tool. Learn Hermes Agent, Claude Code, or OpenCode. Understand how they decompose tasks, manage context, and call tools.
2. Understand MCP deeply. Build a simple MCP server. Connect it to an MCP host. See 03-MCP-and-ACP-Protocols.md.
3. Learn RAG fundamentals. Understand chunking, embedding, vector search. Build a simple RAG pipeline. See 02-RAG-Retrieval-Augmented-Generation.md.
4. Experiment with agent configuration. Write SOUL.md and SKILL.md files (see 06-SOUL-and-SKILL.md). Learn how identity and procedure files shape agent behaviour.

Short-term (3–6 months):
5. Study multi-agent architectures. Build a system with 2–3 specialised agents (coder + reviewer + tester) coordinated by an orchestrator.
6. Learn model selection. Understand when to use small models vs large, open vs closed, quantized vs full precision. See 01-LLM-and-AI-Models.md (§6, §7).
7. Explore agent memory systems. Implement persistent memory for an agent using a vector database.
8. Get comfortable with prompt patterns. ReAct, chain-of-thought, reflection, structured output formatting — these are the design patterns of the agent era.

Medium-term (6–12 months):
9. Build your first autonomous pipeline. A complete workflow from specification to deployed code, managed by an orchestrator.
10. Learn AI security fundamentals. Prompt injection prevention, data sanitisation, agent permission models.
11. Explore the ACP ecosystem. If you're building multi-agent systems, get ahead of the protocol standardisation.

7.2 What Tools/Standards to Bet On

High-confidence bets (adopt now):

Medium-confidence bets (monitor closely, invest strategically):

Avoid over-investing in:
- Proprietary agent platforms that lock you into one vendor's ecosystem.
- Custom tool integrations that don't use MCP (you'll have to rewrite them).
- Giant model dependency — build systems that work with multiple model sizes and can switch as costs change.

7.3 Building for Interoperability

The single most important architectural principle for the AI era: build everything with standard protocols, not custom integrations.

Design principles:
1. All tools get an MCP server. If you build a tool or service, expose it via MCP. This makes it usable by any AI system.
2. All agents support provenance. Every agent output should include metadata about how it was produced — which model, which context, which tools were called. This enables audit, debugging, and quality improvement.
3. All configurations are portable. Use SOUL.md/SKILL.md patterns (see 06-SOUL-and-SKILL.md) for agent identity. Don't hardcode preferences into agent implementations.
4. Model-agnostic architecture. Abstract the model layer behind a common interface. Your orchestrator should work with any LLM — local, cloud, open, closed.
5. Event-driven agent communication. Design agents to emit and consume events, not just respond to direct calls. This enables asynchronous, scalable multi-agent workflows.
6. Human-in-the-loop by default. Build approval gates into every workflow. Agents should be autonomous but not unconstrained.

The litmus test: If an AI system you build today can't be trivially adapted to use a different model, a different orchestrator, or a different protocol next year, you've over-coupled your architecture.

The AI landscape of 2026 is not the AI landscape of 2024, and it will be unrecognisable by 2028. The key trends are clear:

1. Orchestration replaces conversation. The chatbot was the first iteration; the orchestrator is the second. The industry is moving from asking questions to delegating goals.

2. Protocols become infrastructure. MCP and ACP are not mere technical specifications — they are foundational infrastructure that will shape the entire AI ecosystem, analogous to HTTP and TCP/IP for the internet.

3. Open-source wins the model race. The question is not whether open models will catch up, but how quickly. The economic and flexibility advantages of open-weight models are overwhelming.

4. Specialisation beats generalisation. A federation of small, specialised agents outperforms a single monolithic model on complex tasks. This will be the dominant architecture by 2028.

5. Developers evolve, not disappear. The developer role shifts from writing code to designing systems, managing agent workflows, and ensuring quality. The most valuable skill is no longer syntax fluency but architectural reasoning and orchestration design.

6. Interoperability is the only safe bet. Standards (MCP, ACP, SOUL.md, SKILL.md) are safer investments than tools or platforms. Build for portability, and your AI systems will survive the next wave of disruption.

The next three years will see changes that normally take a decade. The developers and organisations that embrace the orchestrator paradigm, invest in protocol literacy, and build for interoperability will define the next era of software. Those who resist will find themselves maintaining legacy systems in a world that has moved on.

Generated: May 2026 | AI Base Knowledge Library — Document 08 of 08

Modern AI agent systems have evolved beyond simple chatbot interfaces into sophisticated, tool-using, autonomous software entities. As these agents operate in increasingly complex environments, a need has emerged for structured documentation that tells the agent who it is and how to perform specific tasks. Two key file conventions have arisen to meet this need: SOUL.md and SKILL.md.

These files form a complementary pair: SOUL.md defines the agent's identity, values, and behavioral constraints (the "why" and "what"), while SKILL.md provides structured, executable procedures (the "how"). Together they create a powerful framework for shaping agent behavior in a repeatable, maintainable way.

This document explores both file types in depth, along with related conventions such as AGENTS.md, CLAUDE.md, and .cursorrules.

2.1 Definition and Purpose

A SOUL.md file is a Markdown document that defines the core identity, personality, values, and behavioral guidelines for an AI agent or software project. It serves as the agent's "constitution" — a reference the agent reads to understand what it is, what it stands for, and how it should behave in every interaction.

The name "SOUL" is intentional: it captures the idea that a project (or an agent serving it) has a spirit or character that goes beyond technical specifications. Just as a person's soul encompasses their values, communication style, and moral compass, a SOUL.md encapsulates the same for an AI-driven project.

Key purposes of SOUL.md:
- Establishes a consistent identity across all agent interactions
- Provides ethical guardrails and behavioral boundaries
- Defines communication style and tone
- Articulates core values and priorities
- Serves as a persistent reference that survives session resets

2.2 Origin and Philosophy

The SOUL.md concept emerged from the open-source AI agent ecosystem, particularly within projects like Hermes Agent (Nous Research), OpenCode, and various Agentic Coding frameworks. It was born out of practical necessity: developers found that AI agents would behave differently across sessions, lose context about project preferences, and fail to maintain consistent interaction patterns.

The philosophical foundation of SOUL.md rests on several key ideas:

1. Identity precedes action. Before an agent can act effectively, it must know what it is. A well-defined identity grounds decision-making.
2. Values drive behavior. Explicit value statements reduce ambiguity when the agent faces trade-offs or ethical decisions.
3. Persistence of character. The agent's personality should not be at the mercy of conversation history limits or model context windows.
4. Human-AI alignment. By writing down what matters, developers ensure the agent acts in accordance with human intent.
5. Openness and transparency. SOUL.md files are plain text, readable by humans and machines alike, embodying the open-source ethos.

2.3 How SOUL.md Is Used in AI Agent Systems

In practice, SOUL.md works through a mechanism called context injection. When an agent starts a session or loads a project, its runtime system (the orchestrator or agent framework) reads the SOUL.md file and injects its contents into the agent's context window — typically as a system prompt or early conversation message.

The flow is generally:

1. Agent startup or project loading occurs
2. The orchestrator locates SOUL.md (usually in the project root)
3. The file contents are read and incorporated into the agent's working context
4. The agent's behavior, tone, and decision-making are shaped by this identity
5. The agent may reference SOUL.md throughout the session for guidance

This process ensures that every interaction is grounded in the project's defined identity, regardless of how long the session runs or how many turns occur.

Common use cases:
- Project-level agents: An agent working on a specific codebase loads that project's SOUL.md to understand the project's coding style, priorities, and culture.
- Personal assistants: A user creates a SOUL.md describing their preferences, communication style, and values so their personal agent adapts to them.
- Team agents: Teams define shared SOUL.md files so all agents operating on a project behave consistently.
- Company agents: Organizations define corporate SOUL.md files that encode brand voice, compliance rules, and company values.

2.4 Structure and Typical Sections

While SOUL.md files are not bound to a strict specification, a well-structured one typically contains the following sections:

2.4.1 Identity

A concise statement of who or what the agent is. This may include a name, role, and high-level purpose.

# Identity

I am Hermes, an AI agent created by Nous Research. I am a helpful,
knowledgeable, and direct assistant. I assist users with a wide range
of tasks including answering questions, coding, analysis, creative
work, and executing actions via tools.

2.4.2 Core Values

The principles that guide decision-making and behavior. These help the agent navigate ambiguous situations.

# Core Values

- **Accuracy:** Prioritize factual correctness over speculation.
- **Honesty:** Admit uncertainty when appropriate.
- **Efficiency:** Be concise and targeted unless thoroughness is requested.
- **Autonomy:** Take initiative when the path forward is clear.

2.4.3 Behavior Rules

Specific, actionable rules for how the agent should behave. These are more concrete than values.

# Behavior Rules

- Always use tools to take action rather than describing what you would do.
- When you say you will perform an action, do it immediately in the same response.
- Never end your turn with a promise of future action — execute it now.
- Keep working until the task is complete; do not stop with a summary of plans.

2.4.4 Communication Style

Guidelines for tone, format, and interaction patterns.

# Communication Style

- Communicate clearly and directly.
- Use plain text rendered for terminal display, not rich markdown.
- Be professional but approachable.
- When referring to files, state absolute paths in plain text.

2.4.5 Domain Knowledge

Optional: project-specific knowledge, architecture notes, or domain expertise the agent should always be aware of.

# Domain Knowledge

- This project uses Python 3.11+, FastAPI, and PostgreSQL.
- The codebase follows a clean architecture pattern.
- Tests are run with pytest and must pass before any merge.

2.4.6 Constraints and Boundaries

What the agent should NOT do — a critical section for safety and alignment.

# Constraints

- Do not modify files outside the project without explicit permission.
- Do not assume user intent; ask for clarification when instructions are ambiguous.
- Do not execute arbitrary code without user confirmation.

2.5 Examples of Well-Crafted SOUL.md Files

Example 1: Development Agent SOUL.md

```markdown

SOUL — Project Identity

I am an AI coding assistant specialized in Python and web development.
I pair-program with developers, write tests, review code, and debug issues.

1. Clarity over cleverness — Write readable, maintainable code.
2. Test-first mindset — Every feature needs a test.
3. Progressive disclosure — Explain complex concepts step by step.

• When asked to write code, always include type hints and docstrings.
• Run tests after any code change; fix failures before continuing.
• Suggest improvements proactively, but do not implement without discussion.

• Use clear, simple English.
• Explain trade-offs when presenting options.
• Format code examples with proper syntax highlighting.
  ```

Example 2: Personal Assistant SOUL.md

```markdown

SOUL — Personal Agent Identity

You are my personal productivity agent. You help me manage tasks,
organize information, write documents, and stay on track.

• Time respect: Be efficient. Don't waste turns on pleasantries.
• Thoroughness: When I ask for research, cover all important angles.
• Proactivity: Remind me of things I might have forgotten.

• Use a friendly but professional tone.
• Be direct — I prefer "Here's what we need to do:" over "I was thinking maybe..."
• Bullet points are better than paragraphs for actionable information.

• Never share personal information outside our session.
• Do not make commitments on my behalf without confirmation.
  ```

Example 3: Open-Source Project SOUL.md

```markdown

Project Soul

We are the contributors and maintainers of Project Zen, an open-source
task management tool. Every action taken by AI agents on this project
should reflect our community values.

1. Inclusivity: All contributors are welcome regardless of experience.
2. Quality: Code review is mandatory; tests must pass at 90%+ coverage.
3. Documentation: No feature is complete without docs.