ADR-198: Namespaced Component Registry Architecture

Status

PROPOSED (2026-02-14)

Context

Problem Statement

CODITECT's component system (agents, skills, commands, hooks, scripts, workflows) currently operates as a flat namespace in a single repository (coditect-core). At ~2,000 components this works well. But as CODITECT scales to serve multiple customers across multiple industry verticals, the component count will grow by orders of magnitude:

Layer	Projected Count	Growth Driver
Core framework	~2,000	Slow, curated additions
Industry domains (x50 verticals)	~10,000	Per-vertical domain expertise
Customer-specific (x10K customers x30 avg)	~300,000	Per-customer customizations
Team/user custom	Unbounded	Organic growth
Marketplace/community	Unbounded	Ecosystem contributions

At platform scale, CODITECT will manage hundreds of thousands to potentially millions of agentic components. But no single session, project, or customer should ever see more than ~100-200 relevant components.

Current State

• 776 agents, 445 skills, 377 commands, 118 hooks — all in flat directories in coditect-core
• Every project gets ALL components via the .coditect symlink (no scoping)
• platform.db indexes all components but has no namespace concept
• ADR-188 established ~/.coditect-data/extensions/ for customer extensions — but only addresses WHERE components live, not HOW they are discovered, resolved, or scoped
• BIO-QMS project TRACKs reference agents by name (e.g., frontend-react-typescript-expert) but these resolve only from core — there is no domain-specific or project-specific resolution

Analogous Problems Solved by Industry

Platform	Total Items	What a User Sees	Resolution Mechanism
npm	2.5M packages	~200 per project	package.json + scoped packages @org/pkg
Docker Hub	15M+ images	~20 per deployment	Namespaced registries org/image:tag
Kubernetes	Unbounded resources	Per-namespace	Namespaces + RBAC
Salesforce	Millions of custom objects	Per-org	Managed packages + namespaces
VS Code	50K+ extensions	~30 installed	Extension marketplace + manifest

Requirements

1. No single session loads all components — lazy resolution, not bulk loading
2. Deterministic resolution — given a component name, the same project always resolves to the same component
3. Override capability — a customer can override a core agent with their own version
4. Isolation — Customer A's components are invisible to Customer B
5. Backward compatible — current flat naming (senior-architect) continues to work, resolving to core
6. Forward compatible — namespaced names (@bio-qms/fda-validator) work when registries exist
7. Offline capable — local resolution works without cloud connectivity

Decision

Three-Tier Component Architecture

Components are organized into three tiers with a priority-based resolution chain:

┌─────────────────────────────────────────────────────────────────┐
│                    Component Resolution Chain                    │
│                                                                  │
│  Request: "fda-validator"                                       │
│                                                                  │
│  ┌──────────────────┐                                           │
│  │ Tier 3: Project   │ ← Highest priority (project-local)      │
│  │ ./agents/         │   Checked first                          │
│  └────────┬─────────┘                                           │
│           │ (not found)                                          │
│  ┌────────▼─────────┐                                           │
│  │ Tier 2: Domain    │ ← Industry-specific components           │
│  │ @bio-qms/         │   Via domain submodule or registry       │
│  └────────┬─────────┘                                           │
│           │ (not found)                                          │
│  ┌────────▼─────────┐                                           │
│  │ Tier 1: Core      │ ← Framework components (always present)  │
│  │ @coditect/core/   │   Via .coditect symlink                  │
│  └──────────────────┘                                           │
│                                                                  │
│  Resolution: First match wins (highest tier takes priority)     │
└─────────────────────────────────────────────────────────────────┘

Tier Definitions

Tier 1: Core Framework (@coditect/core/)

• Location: ~/.coditect/ (protected installation, read-only)
• Scope: Available to ALL projects, ALL customers
• Content: Industry-agnostic agents, skills, commands, hooks
• Examples: senior-architect, testing-specialist, /classify, /sync
• Governance: Curated by CODITECT team, versioned with coditect-core releases
• Current count: ~2,000 components

Tier 2: Domain Components (@{domain}/)

• Location: Domain-specific submodule or registry package
• Scope: Available to all projects within a domain vertical
• Content: Industry-specific agents, skills, commands, workflows
• Examples: @bio-qms/fda-validator, @bio-qms/capa-workflow, @fintech/pci-auditor
• Governance: Curated per-vertical, versioned independently
• Project config: coditect.domain field in project manifest

Tier 3: Project Components (project-local)

• Location: Project repository (./agents/, ./skills/, etc.) or ~/.coditect-data/extensions/ (ADR-188)
• Scope: Available only to the specific project or customer
• Content: Project-specific customizations, overrides, client-specific workflows
• Examples: ./agents/acme-deviation-handler.md, customer-specific approval chains
• Governance: Project owner, version controlled with project

Naming Convention

# Unqualified (backward compatible) — resolves via chain
senior-architect

# Fully qualified — resolves to specific tier
@coditect/core/senior-architect       # Tier 1 explicit
@bio-qms/fda-validator                # Tier 2 domain
@acme-pharma/custom-workflow          # Tier 3 customer (via registry)

# With version pinning (Phase 3+)
@coditect/core@3.2.0/senior-architect
@bio-qms@1.5.0/fda-validator

Project Manifest

Each project declares its component sources via a coditect.json (or frontmatter in existing project config):

{
  "project": "coditect-biosciences-qms-platform",
  "component_sources": [
    {
      "tier": 1,
      "namespace": "@coditect/core",
      "source": "symlink",
      "path": ".coditect"
    },
    {
      "tier": 2,
      "namespace": "@bio-qms",
      "source": "submodule",
      "path": "submodules/domains/coditect-bio-qms"
    }
  ],
  "component_overrides": {
    "senior-architect": "@bio-qms/bio-senior-architect"
  }
}

Resolution Algorithm

def resolve_component(name: str, type: str, project_config: dict) -> Component:
    """
    Resolve a component by name using the three-tier priority chain.

    Priority: project-local → domain → core
    First match wins.
    """
    # 1. Check for fully qualified name
    if name.startswith("@"):
        namespace, component_name = parse_qualified_name(name)
        return lookup_in_namespace(namespace, component_name, type)

    # 2. Check for explicit override in project config
    if name in project_config.get("component_overrides", {}):
        return resolve_component(project_config["component_overrides"][name], type, project_config)

    # 3. Walk resolution chain (highest tier first)
    for source in sorted(project_config["component_sources"], key=lambda s: -s["tier"]):
        component = lookup_in_source(source, name, type)
        if component:
            return component

    # 4. Fallback: core framework (always available)
    return lookup_in_core(name, type)

Registry Database Schema

Extend platform.db (ADR-118, Tier 1 regenerable) with namespace support:

-- Component registry with namespace support
CREATE TABLE components (
    id INTEGER PRIMARY KEY,
    namespace TEXT NOT NULL DEFAULT '@coditect/core',
    name TEXT NOT NULL,
    type TEXT NOT NULL,  -- agent, skill, command, hook, script, workflow
    version TEXT,
    path TEXT NOT NULL,
    tier INTEGER NOT NULL DEFAULT 1,  -- 1=core, 2=domain, 3=project

    -- Metadata
    title TEXT,
    summary TEXT,
    keywords TEXT,  -- JSON array
    agent_primary TEXT,  -- for track-linked components

    -- Indexing
    indexed_at TEXT NOT NULL,
    content_hash TEXT,

    UNIQUE(namespace, name, type)
);

-- Namespace registry
CREATE TABLE namespaces (
    namespace TEXT PRIMARY KEY,
    tier INTEGER NOT NULL,
    source_type TEXT NOT NULL,  -- 'symlink', 'submodule', 'registry', 'local'
    source_path TEXT,
    source_url TEXT,
    version TEXT,
    registered_at TEXT NOT NULL
);

-- Resolution cache (for performance)
CREATE TABLE resolution_cache (
    project_id TEXT NOT NULL,
    component_name TEXT NOT NULL,
    component_type TEXT NOT NULL,
    resolved_namespace TEXT NOT NULL,
    resolved_path TEXT NOT NULL,
    cached_at TEXT NOT NULL,
    PRIMARY KEY(project_id, component_name, component_type)
);

Implementation Phases

Phase 1: Foundation (Current — 2K components)

Status: Partially complete

• Flat file components in coditect-core (existing)
• platform.db component index (existing, ADR-118)
• ~/.coditect-data/extensions/ for customer components (ADR-188)
• Add namespace column to platform.db components table
• Update component-indexer.py to populate namespace from source path
• Create coditect.json manifest format for projects
• Update /which command to show namespace in results

Trigger: BIO-QMS implementation tracks (C-D) requiring domain-specific agents.

Phase 2: Domain Namespaces (5K-50K components)

• Create domain submodule template (coditect-domain-template)
• Implement resolution chain in scripts/core/component_resolver.py
• Update /agent, /which to resolve via chain
• Create first domain: coditect-bio-qms with FDA/HIPAA/GxP agents
• Update platform.db indexer to walk multiple component sources
• Add component_sources to project registration (projects.db)
• Version pinning for domain components

Trigger: Second customer or second industry vertical requiring shared domain components.

Phase 3: Cloud Registry (50K-500K components)

• Registry API service (Cloud Run)
• coditect install @bio-qms/fda-validator CLI command
• Component signing (SHA-256 + author verification)
• Version resolution (@bio-qms@^1.0.0/fda-validator)
• Dependency declaration between components
• Cloud-synced resolution cache
• Usage analytics (which components are most used)

Trigger: 10+ customers or partner ecosystem requiring component distribution.

Phase 4: Marketplace (500K+ components)

• Community contribution pipeline with review/curation
• Paid component distribution (partners monetize domain expertise)
• Component compatibility matrix (which components work together)
• Rating and trust scoring
• Automated testing for contributed components
• Component deprecation and migration tooling

Trigger: Ecosystem growth, partner revenue model.

Consequences

Positive

1. No architectural ceiling — scales from 2K to millions without redesign
2. Clean separation — core stays lean, domains grow independently
3. Override capability — customers can customize any component
4. Backward compatible — unqualified names continue to work
5. Revenue opportunity — marketplace enables partner monetization
6. Domain expertise compounds — bio-QMS components reused across all bio customers

Negative

1. Resolution complexity — multi-tier lookup is more complex than flat directory
2. Namespace collisions — need governance for namespace reservation
3. Version management — multiple versions of components in different tiers
4. Discovery UX — /which must search across tiers, showing provenance

Mitigations

1. Resolution cache — resolution_cache table in platform.db avoids repeated lookups
2. Namespace reservation — @coditect/* reserved, domain namespaces registered centrally
3. Version pinning — project manifest locks versions; coditect update for upgrades
4. Enhanced /which — show tier, namespace, and override status in results

Relationship to ADR-188

ADR-188 (Customer Extensions Architecture) established WHERE customer components are stored (~/.coditect-data/extensions/). This ADR establishes:

• HOW components are discovered across multiple sources
• HOW resolution priority works when the same name exists in multiple tiers
• HOW the system scales beyond a single storage location
• HOW domain-specific components are shared across customers in the same vertical

ADR-188's extensions/ directory becomes the Tier 3 project-local source in this architecture. The two ADRs are complementary, not conflicting.

Track-Skills Index Impact

The BIO-QMS "Total Skills: 0, Total Tracks: 0" issue is resolved by this architecture:

1. Current state: Track files reference agents by name, but no skills exist in the project
2. With ADR-198: The Track-Skills Index can resolve agent/skill references across tiers:
   • Track A references frontend-react-typescript-expert → resolved from Tier 1 (core)
   • Track D will reference fda-validator → resolved from Tier 2 (bio-qms domain, when created)
3. The index becomes cross-tier: Shows which tier each component comes from

Decision Rationale

The three-tier architecture was chosen because:

1. It mirrors proven patterns — npm scopes, Docker namespaces, K8s namespaces
2. Phase 1 is nearly free — just add a column to platform.db and a manifest file
3. Each phase is independently valuable — no need to build the full stack upfront
4. The trigger-based roadmap prevents over-engineering — build each phase when actually needed
5. Domain submodules create compound value — every new bio customer benefits from prior bio customers' domain components

---

Author: Hal Casteel Reviewed By: (pending) ADR: 198 Created: 2026-02-14