Docs: Updated ADRs and specification to include details about standards

docs/specification.md

@@ -8,6 +8,20 @@ In **server mode**, CleverAgents becomes a collaborative hub where teams can sha
 
 While CleverAgents leverages LangGraph and LangChain for the underlying LLM runtime primitives (tool calling, graphs, routing), its value lies in what it builds on top:
 
+### Standards Alignment
+
+CleverAgents deliberately adopts open, versioned protocols wherever possible so that clients, tools, and skills can interoperate without bespoke integrations. Two guiding principles govern protocol adoption:
+
+* **Prefer open protocols** — align with community standards to keep integrations portable and reduce vendor lock-in.
+* **Keep adapters at the edge** — standards map into stable internal domain models so core logic remains protocol-agnostic.
+
+The following standards are integrated into the architecture:
+
+* **Agent Client Protocol (ACP)** — defines the versioned client-server contract for sessions, plan lifecycle, registry access, and event streaming across all Presentation-layer clients (CLI, TUI, Web, IDE). This makes clients interchangeable and enables reliable remote execution in server mode.
+* **Model Context Protocol (MCP)** — the standard for discovering and invoking external tools over a server boundary. MCP servers are bridged into the Tool Registry via adapters, giving CleverAgents plug-and-play access to a growing ecosystem of tool providers.
+* **Language Server Protocol (LSP)** — the standard for IDE integration. The CleverAgents IDE plugin is an LSP server that surfaces plan-aware code actions, diagnostics, and context lookups, communicating with the backend exclusively through ACP. This provides editor-agnostic IDE support without bespoke plugins.
+* **Agent Skills ([https://AgentSkills.io](https://AgentSkills.io))** — the standard for packaging instruction-driven, multi-step workflows as `SKILL.md` with progressive disclosure. Agent Skills complement MCP tools by teaching agents *how* to accomplish complex tasks rather than simply exposing callable functions.
+
 **CleverAgents** provides:
 
   * A **first-class plan lifecycle** (Action templates driving Strategize/Execute/Apply phases) for breaking down and tracking complex work,
@@ -37,13 +51,17 @@ While CleverAgents leverages LangGraph and LangChain for the underlying LLM runt
 * **Virtual Resource**: A resource representing an abstract equivalence identity that links physical resources sharing the same content, hash, or name. Has no location; cannot be directly read or written. Equivalence relationships update when underlying physical resources diverge.
 * **Resource Binding**: The association between a tool and the resources it operates on, declared via typed resource slots. Slots resolve through contextual binding (from the plan's project), static binding (hardcoded at registration), or parameter binding (passed at invocation).
 * **Resource Registry**: The persistent catalog of all registered resources and their DAG relationships (parent/child links). One of the core registries, alongside the Tool Registry, Skill Registry, Actor Registry, and Provider Registry.
-* **Skill**: A composable, namespaced collection of tools assembled by referencing named tools, defining inline anonymous tools, including other skills, or exposing MCP server / Agent Skills Standard tools. Actors reference skills by name to acquire capabilities. Namespaced as `[[server:]namespace/]name`.
-* **Tool**: The atomic unit of execution: a namespaced, independently registered callable operation. Defined by JSON Schema inputs/outputs, capability metadata (`read_only`, `writes`, `checkpointable`), and a four-stage lifecycle (`discover`/`activate`/`execute`/`deactivate`). Sources: MCP servers, Agent Skills Standard folders, built-ins, or custom Python. Namespaced as `[[server:]namespace/]name`.
+* **Skill**: A composable, namespaced collection of tools assembled by referencing named tools, defining inline anonymous tools, including other skills, or exposing Model Context Protocol (MCP) server tools and Agent Skills ([https://AgentSkills.io](https://AgentSkills.io)) tools. Actors reference skills by name to acquire capabilities. Namespaced as `[[server:]namespace/]name`.
+* **MCP (Model Context Protocol)**: A standard for exposing tools and resources over a server boundary via JSON-RPC. CleverAgents discovers MCP tools through the MCPToolAdapter and registers them in the Tool Registry with extended capability metadata. MCP tools can be composed into skills and used as tool nodes in actor graphs.
+* **Agent Skills ([https://AgentSkills.io](https://AgentSkills.io))**: A standard for packaging instruction-driven, multi-step workflows as `SKILL.md` files with optional `scripts/`, `references/`, and `assets/` directories, using progressive disclosure. In CleverAgents, Agent Skills are surfaced as tools inside skills and loaded on demand by the actor runtime. Within actor graphs they appear as tool nodes and may orchestrate multiple MCP tools during execution.
+* **Tool**: The atomic unit of execution: a namespaced, independently registered callable operation. Defined by JSON Schema inputs/outputs, capability metadata (`read_only`, `writes`, `checkpointable`), and a four-stage lifecycle (`discover`/`activate`/`execute`/`deactivate`). Sources: Model Context Protocol (MCP) servers, Agent Skills ([https://AgentSkills.io](https://AgentSkills.io)) folders, built-ins, or custom Python. Namespaced as `[[server:]namespace/]name`.
 * **Validation**: A Tool subtype adding: a `mode` (`required` | `informational`) controlling whether failure blocks execution; a structured JSON return with mandatory `passed` boolean, optional `data`, and optional `message`. Always read-only (`writes = false`, `checkpointable = false`). May wrap an existing Tool via `wraps` + `transform` to reuse its implementation. Shares the Tool naming namespace — no name collisions allowed. Usable anywhere a Tool is expected, but not vice versa. Managed via `agents validation add/attach/detach`; listed, inspected, and removed through standard `agents tool` commands. Always attached to a resource, optionally scoped to a project or plan.
 * **Anonymous Tool**: An inline tool definition embedded in a skill YAML or actor graph node. Same schema as a named tool but unregistered, unnamespaced, and scoped only to its defining context.
 * **Actor**: A YAML-configured conversational unit — either a single LLM/agent or a composed LangGraph of actors and tool nodes. Specialized roles: strategy actor, execution actor, estimation actor, invariant reconciliation actor. Namespaced as `[[server:]namespace/]name`.
 * **Session**: A persistent conversation thread tied to an orchestrator actor. Maintains message history across plans and serves as the user's natural-language interface.
 * **Server**: An optional shared backend providing multi-user storage, namespace resolution, and remote plan execution.
+* **ACP (Agent Client Protocol)**: A versioned client-server protocol that defines authentication, session lifecycle, plan operations, registry access, and event streaming for all Presentation-layer clients (CLI, TUI, Web, IDE plugin). In local mode ACP maps to in-process service facade calls; in server mode it is implemented by the REST API over HTTPS. Ensures clients are interchangeable and supports third-party clients.
+* **LSP (Language Server Protocol)**: A standard for IDE integration. The CleverAgents IDE plugin runs as an LSP server that translates code actions and diagnostics into plan operations and validation results, communicating with the backend through ACP. This enables editor-agnostic IDE support without bespoke plugins per editor.
 * **Namespace**: The scoping segment in the name format `[[server:]namespace/]name`. Defaults to `local/` when omitted. `local/` is reserved for local-only items (no server applies). Non-`local/` namespaces with server omitted assume the default configured server. `<username>/` and `<orgname>/` are server-stored. Built-in LLM actors use provider prefixes (e.g., `openai/`, `anthropic/`). Built-in resource types are unnamespaced.
 * **Decision**: A persisted choice point in a plan's decision tree, created during Strategize or Execute. Records the question, chosen option, alternatives, confidence score, rationale, context snapshot, and downstream dependencies. Types: `prompt_definition`, `invariant_enforced`, `strategy_choice`, `subplan_spawn`, `subplan_parallel_spawn`, among others. Execute-phase decisions are constrained by Strategize-phase decisions and arise from runtime discoveries. Supports targeted correction with selective subtree recomputation.
 * **Invariant**: A natural-language constraint on plan execution scoped to global, project, action, or plan level. Precedence: plan > action > project > global. Reconciled by the Invariant Reconciliation Actor at the start of Strategize; recorded as `invariant_enforced` decisions that propagate to child plans.
@@ -6681,6 +6699,9 @@ This enables a pattern where:
 
 #### What an Actor Is
 
+!!! adr "Architecture Decision"
+    The canonical definition of an actor — anything conversational, actor-as-graph principle, hierarchical composition, and the actor/agent distinction — is formalized in [ADR-031: Actor Abstraction Definition](adr/ADR-031-actor-abstraction-definition.md).
+
 An **actor** is the abstraction that generalizes "agent" into "anything conversational."
 
 * It can be as small as a single LLM agent.
@@ -6805,6 +6826,9 @@ This enables hierarchical composition where:
 
 #### Actor vs Agent (Relationship)
 
+!!! adr "Architecture Decision"
+    The formal actor/agent distinction — actors as the general abstraction, agents as a specialized subset — is defined in [ADR-031: Actor Abstraction Definition](adr/ADR-031-actor-abstraction-definition.md).
+
 * **Agent**: an actor that is specifically an LLM with tools and reasoning behaviors.
 * **Actor**: may be an agent, but may also be:
 
@@ -6830,6 +6854,9 @@ A robust actor schema should include:
 
 #### Actor Composition and Graphs
 
+!!! adr "Architecture Decision"
+    Hierarchical actor composition, the actor-as-graph principle, and graph node types are defined in [ADR-031: Actor Abstraction Definition](adr/ADR-031-actor-abstraction-definition.md).
+
 Actors can reference:
 
 * other actors (by namespaced name)
@@ -6843,6 +6870,9 @@ This is central to enabling both:
 
 #### Nodes in the Graph: Actors and Tools
 
+!!! adr "Architecture Decision"
+    The two graph node types (actor nodes and tool nodes) and their relationship to the skill and tool systems are defined in [ADR-031: Actor Abstraction Definition](adr/ADR-031-actor-abstraction-definition.md) and [ADR-030: Skill Abstraction Definition](adr/ADR-030-skill-abstraction-definition.md).
+
 Graph nodes can be any of:
 
 * an **actor** (another LLM agent or composite workflow, referenced by name),
@@ -7854,7 +7884,9 @@ This approach means:
 #### MCP Integration Details
 
 !!! adr "Architecture Decision"
-    The MCP integration strategy, concept mapping, and extended capabilities are defined in [ADR-022: LangChain/LangGraph Integration](adr/ADR-022-langchain-langgraph-integration.md).
+    MCP adoption, tool-to-skill mapping, and actor-graph usage are defined in [ADR-029: Model Context Protocol (MCP) Adoption](adr/ADR-029-model-context-protocol.md).
+
+CleverAgents integrates with the Model Context Protocol (MCP) to discover and invoke external tools, then normalizes them into the Tool Registry with extended capability metadata and sandbox-aware execution. MCP tools are composed into skills and appear as tool nodes in actor graphs, giving them the same lifecycle, change-tracking, and checkpoint semantics as built-in tools.
 
 ##### MCP Concepts Mapping
 
@@ -7919,6 +7951,11 @@ This ensures MCP tools respect sandbox boundaries even though they have no aware
 
 #### Agent Skills Integration Details
 
+!!! adr "Architecture Decision"
+    The Agent Skills standard integration is defined in [ADR-028: Agent Skills Standard (AgentSkills.io)](adr/ADR-028-agent-skills-standard.md).
+
+Agent Skills follow the Agent Skills standard from [https://AgentSkills.io](https://AgentSkills.io), which defines the `SKILL.md` structure and the progressive disclosure model used by the runtime. Within actor graphs, Agent Skills appear as tool nodes — the actor runtime loads the skill's instructions into the LLM context when the node activates, enabling the agent to follow multi-step procedures that may invoke MCP tools, built-in tools, or other Agent Skills during execution.
+
 ##### Discovery and Progressive Disclosure
 
 Agent Skills follow a three-tier progressive disclosure model that maps directly to the tool lifecycle:
@@ -8592,6 +8629,9 @@ agents plan use local/implement-feature local/api-service
 
 #### What a Skill Is
 
+!!! adr "Architecture Decision"
+    The canonical definition of a skill — its four tool sources, flattening model, and role as the unit of capability assignment — is formalized in [ADR-030: Skill Abstraction Definition](adr/ADR-030-skill-abstraction-definition.md).
+
 A **skill** is a namespaced, reusable **collection of tools** that is registered in the system via its own YAML configuration file and managed through `agents skill` CLI commands. Skills are the unit of capability composition in CleverAgents — they define *what an actor can do* by assembling tools into coherent, reusable bundles.
 
 A skill is **not** a single tool. It is a **container** that references one or more tools (by name from the Tool Registry) and/or defines anonymous inline tools, along with metadata describing the collection's purpose, capabilities, and safety characteristics. Tools are independently registered, callable operations (see the **Tools** section above). Skills organize them into reusable groups.
@@ -8606,6 +8646,9 @@ A skill is **not** a single tool. It is a **container** that references one or m
 
 #### The Skill / Tool Distinction
 
+!!! adr "Architecture Decision"
+    The formal distinction between skills (containers) and tools (atomic operations), and the source-agnostic flattening model, are defined in [ADR-030: Skill Abstraction Definition](adr/ADR-030-skill-abstraction-definition.md).
+
 ```kroki-plantuml
 @startuml
 skinparam packageStyle rectangle
@@ -9022,6 +9065,21 @@ A server is an optional mode that enables:
 
 **It is possible to run a client with no server at all.** Server is optional.
 
+#### Agent Client Protocol (ACP)
+
+!!! adr "Architecture Decision"
+    The Agent Client Protocol is defined in [ADR-026: Agent Client Protocol (ACP)](adr/ADR-026-agent-client-protocol.md).
+
+ACP is the versioned contract between every Presentation-layer client (CLI, TUI, Web, IDE plugin) and the CleverAgents backend. It defines canonical operations for:
+
+* **Session lifecycle** — create, resume, list, export, import.
+* **Plan lifecycle** — use, execute, apply, cancel, status, tree, artifacts.
+* **Registries** — list / show / add / update / remove for actors, skills, tools, validations, resources, projects, and actions.
+* **Context operations** — context show / inspect / simulate, context policy updates.
+* **Event streaming** — plan state changes, tool execution events, validation results, and structured log events.
+
+In **local mode** ACP maps directly to in-process service facade calls (no network). In **server mode** ACP is implemented by the REST API over HTTPS with token-based authentication. This duality means every client works identically regardless of deployment mode, and third-party clients can rely on a stable, versioned surface.
+
 #### Plan Execution Location
 
 Where a plan executes depends on the project type:
@@ -25012,6 +25070,18 @@ DS -down-> IDX
 @enduml
 ```
 
+#### Standards and Protocols in the Architecture
+
+!!! adr "Architecture Decision"
+    The four protocol standards and their architectural roles are defined across [ADR-026: Agent Client Protocol (ACP)](adr/ADR-026-agent-client-protocol.md), [ADR-027: Language Server Protocol (LSP) Integration](adr/ADR-027-language-server-protocol.md), [ADR-028: Agent Skills Standard (AgentSkills.io)](adr/ADR-028-agent-skills-standard.md), and [ADR-029: Model Context Protocol (MCP) Adoption](adr/ADR-029-model-context-protocol.md).
+
+Each adopted standard maps to an explicit architectural boundary:
+
+* **ACP (Agent Client Protocol)** — connects Presentation-layer clients (CLI, TUI, Web, IDE) to the Service Facade / REST API. Covers sessions, plans, registries, and event streaming. In local mode it resolves to in-process calls; in server mode it is the HTTPS contract. This keeps clients interchangeable and supports third-party client development.
+* **LSP (Language Server Protocol)** — the IDE plugin is an LSP server that maps editor code actions and diagnostics to plan operations and validation results, pulling all data through ACP. This enables editor-agnostic IDE support without per-editor plugin maintenance.
+* **MCP (Model Context Protocol)** — external MCP servers reside in the Infrastructure layer. The MCPToolAdapter bridges them into first-class Tools in the Domain model with extended capability metadata. MCP tools are composed into skills and used as tool nodes in actor graphs, giving the system standardized tool discovery and invocation.
+* **Agent Skills ([https://AgentSkills.io](https://AgentSkills.io))** — Agent Skills are ingested into the Skill Registry and loaded by the actor runtime via progressive disclosure. Inside actor graphs they appear as tool nodes whose execution is instruction-driven — the agent follows multi-step procedures that may call MCP tools, built-ins, or other Agent Skills. This adds portable, reusable workflows that complement schema-driven MCP tools.
+
 #### Architectural Principles
 
 1. **Hexagonal Architecture (Ports and Adapters)**: The domain layer defines abstract repository interfaces (ports). The infrastructure layer provides concrete implementations (adapters). This allows swapping SQLite for PostgreSQL, FAISS for Qdrant, or local execution for remote server execution without touching domain logic.