ADR-001: CODITECT Framework Architecture

Status

ACCEPTED (2026-02-03)

Context

CODITECT is an AI-powered software development intelligence framework that extends Claude Code with organizational knowledge, skill libraries, and automated workflows. The framework needed a clear architectural foundation to support:

1. Distributed Intelligence - Framework components accessible from any project
2. Component Modularity - Independent agents, skills, commands, scripts, hooks
3. Claude Code Integration - Seamless extension of built-in capabilities
4. Multi-LLM Support - Context preservation across Claude, Codex, Gemini, KIMI

Decision

Core Architecture Principles

┌─────────────────────────────────────────────────────────────────┐
│                    CODITECT FRAMEWORK                           │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
│  │    Agents    │  │    Skills    │  │   Commands   │          │
│  │   (210+)     │  │   (405+)     │  │   (323+)     │          │
│  └──────────────┘  └──────────────┘  └──────────────┘          │
│                                                                  │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
│  │   Scripts    │  │    Hooks     │  │  Workflows   │          │
│  │   (488+)     │  │   (102+)     │  │  (1152+)     │          │
│  └──────────────┘  └──────────────┘  └──────────────┘          │
│                                                                  │
├─────────────────────────────────────────────────────────────────┤
│                    COMPONENT TOTAL: 2,688+                      │
└─────────────────────────────────────────────────────────────────┘

Directory Structure

coditect-core/
├── agents/              # 210+ AI agent definitions (.md)
├── commands/            # 323+ slash commands (.md)
├── skills/              # 405+ reusable skills (*/SKILL.md)
├── scripts/             # 488+ automation scripts (.py, .sh)
├── hooks/               # 102+ event triggers
├── workflows/           # 1152+ workflow definitions
├── prompts/             # System prompts
├── config/              # Framework configuration
│   ├── component-counts.json      # Component inventory
│   ├── framework-registry.json    # Component registry
│   ├── component-activation-status.json
│   └── experience-packs.json      # CEF persona packs
├── coditect-core-standards/       # Standards documentation
├── docs/                # Customer documentation
├── internal/            # Contributor documentation
│   ├── architecture/    # ADRs and system design
│   └── project/         # Project plans (PILOT tracks)
└── .venv/               # Python virtual environment

Distributed Intelligence Model

CODITECT uses symlinks to provide framework access from any project:

~/Library/Application Support/CODITECT/core/  ← Protected Installation
                        ↑
~/.coditect ────────────┘  (backward compatibility)
                        ↑
~/PROJECTS/.coditect ───┘  (primary access)
                        ↑
~/PROJECTS/.claude ─────┘  (Claude Code integration)

This enables:

• Project-agnostic access: ~/.coditect/agents/ works from anywhere
• Claude Code loading: .claude/ symlink triggers CLAUDE.md loading
• Protected updates: Framework updates don't touch user data

Component Types

Component	Location	Format	Invocation
Agents	agents/*.md	YAML frontmatter + Markdown	/agent <name> "<task>"
Commands	commands/*.md	YAML frontmatter + Markdown	/<command> [args]
Skills	skills/*/SKILL.md	YAML frontmatter + Markdown	Skill(skill="name")
Scripts	scripts/**/*.py	Python with CLI	python3 script.py
Hooks	hooks/*.py	Python event handlers	Auto-triggered
Workflows	workflows/**/*.yaml	YAML definitions	/execute-workflow

Claude Code Integration

CODITECT extends Claude Code through:

1. CLAUDE.md Hierarchy - Context files loaded per directory
2. Custom Agent Types - 210+ specialized agents beyond built-in types
3. Skill System - Reusable capability modules
4. Hook System - Pre/Post tool use hooks for governance
5. MCP Servers - Custom tool providers

Configuration System

# Primary configuration files
config/
├── component-counts.json        # Auto-generated inventory
├── framework-registry.json      # All components with metadata
├── component-activation-status.json  # Activation state
├── experience-packs.json        # CEF persona skill packs
├── llm-watchers.json           # Multi-LLM export config
├── judge-personas.json         # MoE verification judges
└── model-pricing.json          # Token cost tracking

Database Architecture

Four-tier database architecture (ADR-118):

Tier	Database	Purpose	Backup
1	platform.db	Component metadata	Regenerable
2	org.db	Critical knowledge	CRITICAL
3	sessions.db	Session data	Regenerable
4	projects.db	Project embeddings	Regenerable

Consequences

Positive

1. Extensibility - Add components without modifying core
2. Portability - Same framework works across projects
3. Discoverability - Component indexing with search
4. Governance - Hooks enforce standards
5. Multi-LLM - Context preserved across LLM providers

Negative

1. Complexity - Many component types to understand
2. Symlink Dependency - Requires proper symlink setup
3. Learning Curve - New users must learn framework structure

Risks

Risk	Mitigation
Component conflicts	Unique naming, type prefixing
Symlink breakage	Validation in initial setup
Version drift	Git-based updates from protected location

Implementation

Initial Setup (ADR-057)

# Install CODITECT framework
python3 coditect-core/scripts/CODITECT-CORE-INITIAL-SETUP.py

Component Discovery

# Search components
python3 scripts/component-indexer.py --search "security audit"

# List by type
python3 scripts/component-indexer.py --type agent --stats

Framework Updates

# Update protected installation
cd ~/Library/Application\ Support/CODITECT/core
git pull

Related

• ADR-003: Agent System
• ADR-057: Initial Setup Process
• ADR-114: Protected Installation and User Data Separation
• ADR-118: Four-Tier Database Architecture

---

Track: H (Framework Autonomy) Task: F.12.2.1