cleveragents-core/docs/adr/ADR-002-namespace-system.md

adr_number, title, status_history, tier, authors, superseded_by, related_adrs, acceptance

adr_number	title	status_history	tier	authors	superseded_by	related_adrs	acceptance
2	Namespace System	2026-02-16 Proposed Jeffrey Phillips Freeman 2026-02-16 Accepted Jeffrey Phillips Freeman	1	Jeffrey Phillips Freeman	null	number title relationship 9 Project Model Projects are namespace-scoped entities that use the naming convention number title relationship 10 Actor and Agent Architecture Actors and agents are identified and resolved via namespaced names number title relationship 11 Tool System Tools use namespaced identifiers for discovery and conflict resolution number title relationship 12 Skill System Skills use namespaced names and resolve tool name conflicts via qualification number title relationship 23 Server Mode Server mode introduces server-prefixed namespaces for multi-server resolution	votes_for votes_against abstentions voter comment Jeffrey Phillips Freeman <Jeffrey.Freeman@CleverThis.com> A universal naming scheme avoids ambiguity and makes entity resolution predictable across all contexts

Context

CleverAgents manages a wide variety of named entities — actors, tools, skills, resources, resource types, actions, projects, and plans. These entities must be uniquely identifiable, scopeable to different ownership levels (local machine, personal server account, organization), and discoverable across deployment boundaries. Without a uniform naming scheme, entity references would be ambiguous, collision-prone, and incompatible between local and server modes.

The system must also support connecting to multiple servers simultaneously and resolving names unambiguously in that context.

Decision Drivers

• Entities (actors, tools, skills, resources, projects, plans) must be uniquely identifiable across deployment boundaries
• Must support multiple ownership scopes: local machine, personal server account, and organization
• Local-first development must work with zero server configuration
• System must handle simultaneous connections to multiple servers without name collisions
• Naming scheme must be uniform across all entity types to reduce cognitive overhead
• Transition from local-only to shared/collaborative usage should not require structural migration

Decision

All named entities in CleverAgents use a universal namespace-qualified name format: [[server:]namespace/]name. Four namespace types define ownership and storage scope. The local/ namespace is the default when no namespace is specified.

Design

Name Format

The fully qualified form is server:namespace/name. Components may be omitted with well-defined defaults:

Form	Resolution
name	local/name (default namespace is local)
namespace/name	Uses the specified namespace on the default server
server:namespace/name	Fully qualified — explicit server and namespace

Namespace Types

local/ — Reserved namespace for machine-local entities. Stored in the local SQLite database. Fast iteration, no sharing, no server dependency. This is the default namespace when none is specified.

<username>/ (e.g., freemo/, jsmith/) — Personal server namespace created when a user registers. Stored on the server, synced to the local machine when connected. Enables reusable entities across machines. Only the owning user can create or modify items.

<orgname>/ (e.g., cleverthis/, acme/) — Organization namespace created when an organization is registered. Shared across team members. All entity types can be centrally managed under the org namespace.

Built-in provider namespaces (openai/, anthropic/, google/, etc.) — Reserved for built-in LLM actors. Automatically available when API keys are configured (via environment variables in local mode, or server-side keys in server mode). Cannot be used for custom actors.

Server-Qualified Names

When connected to multiple servers, the server prefix disambiguates:

• dev:freemo/code-coverage — personal namespace on the dev server
• prod:cleverthis/deploy-action — org namespace on the prod server

Resolution Rules

1. If the server prefix is omitted, the default server is assumed — unless the namespace is local, which always resolves locally.
2. If the namespace is omitted, local is used (configurable via core.namespace).
3. Names are stable identifiers; kebab-case is recommended.

Entities Using This System

All of the following entity types follow the namespace/name convention: actors, tools, skills, resources, resource types, actions, projects, and plans.

Constraints

• The local/ namespace is reserved and must never be synced to a server.
• Built-in provider namespaces (openai/, anthropic/, google/, etc.) are reserved and must not be used for custom entity registration.
• Entity names within a namespace must be unique per entity type. The tuple (namespace, entity_type, name) is the uniqueness key.
• The core.namespace configuration key controls the default namespace prefix applied when creating entities without an explicit namespace.

Consequences

Positive

• A single naming convention applies uniformly to all entity types, reducing cognitive overhead.
• Local-first development requires zero server configuration — local/ is always available.
• Transitioning from local to shared usage is a namespace change, not a structural migration.
• Multi-server support is built into the naming scheme from the start, avoiding future retrofitting.

Negative

• Entity names become longer when fully qualified, which may be verbose in CLI usage.
• Name resolution logic must be implemented in every subsystem that handles entity references.
• Namespace synchronization between client and server adds operational complexity.

Risks

• Namespace collisions between user and organization names must be prevented at registration time.
• If the default namespace configuration is changed inadvertently, entity resolution may silently resolve to the wrong scope.

Alternatives Considered

None — specification-driven requirement. The universal namespace system is a foundational design choice that enables the local-first-to-collaborative progression and multi-server deployment model prescribed by the specification.

Compliance

• Registration validation: The agents <entity> add commands validate that the namespace is well-formed, not reserved (for custom entities), and that the user has write permissions to the target namespace.
• Name format tests: Unit tests verify that entity name parsing correctly handles all forms (name, namespace/name, server:namespace/name) and rejects malformed inputs.
• Integration tests: Multi-namespace scenarios (local + server, multiple servers) are exercised in integration test suites.
• Code review: New entity types must demonstrate they follow the namespace convention before merging.