ADR-188: Customer Extensions Architecture

Status

ACCEPTED (2026-01-27)

Context

Problem Statement

CODITECT customers need the ability to extend the framework with their own custom:

• Agents
• Skills
• Hooks
• Commands
• Scripts
• Tools

Currently, session logs and other customer data are scattered across multiple locations:

1. ~/.coditect/session-logs/ (framework directory - WRONG)
2. ~/PROJECTS/.coditect-data/session-logs/ (correct per ADR-114)
3. ~/PROJECTS/.coditect-data/context-storage/session-logs-git/ (git-synced)
4. Various machine-specific directories with UUID or hostname naming

Requirements

1. Single unified location for all customer data and extensions
2. Read-only framework - customers cannot modify coditect-core
3. Extendable architecture - customers can add their own components
4. No overwrites - customer extensions cannot overwrite framework components
5. Backup-friendly - single location for GCS backup
6. Multi-machine aware - support for multiple machines per customer

Options Evaluated

Four options were evaluated using MoE (Mixture of Experts) judge panel analysis:

Option	Description	Architecture	Security	DevEx
A	Expand ~/.coditect-data/	9.25/10	7.8/10	8.7/10
B	New ~/.coditect-customer/	8.35/10	7.5/10	7.0/10
C	~/PROJECTS/.coditect-extensions/	7.0/10	5.5/10	6.5/10
D	Per-project + global hybrid	7.6/10	9.0/10	6.0/10

Decision

Option A: Expand ~/.coditect-data/ is the selected architecture.

Rationale

1. Already exists - ADR-114 established .coditect-data/ for user data
2. No new directories - Reduces proliferation
3. Single backup target - GCS sync only needs one location
4. Clear separation - Framework (read-only) vs User data (read-write)
5. Highest combined score - Best balance of architecture, security, and DevEx

Final Structure

~/PROJECTS/.coditect-data/                  # User data root (ADR-114)
├── machine-id.json                         # Machine identification (ADR-058)
├── checkpoints/                            # Session checkpoints
├── backups/                                # Local backup staging
│
├── context-storage/                        # Databases (ADR-118)
│   ├── org.db                              # TIER 2: Accumulated knowledge
│   ├── sessions.db                         # TIER 3: Session messages
│   ├── platform.db                         # TIER 1: Component index
│   ├── context.db                          # Legacy (deprecated)
│   ├── unified_messages.jsonl              # Session source of truth
│   └── session-logs-git/                   # Git repo for /sync-logs
│
├── session-logs/                           # Session log files (CONSOLIDATED)
│   └── SESSION-LOG-*.md                    # Daily session logs
│
└── extensions/                             # Customer extensions (NEW)
    ├── agents/                             # Custom agents
    │   └── *.md                            # Agent definitions
    ├── skills/                             # Custom skills
    │   └── */SKILL.md                      # Skill packages
    ├── hooks/                              # Custom hooks
    │   └── *.py                            # Python hooks
    ├── commands/                           # Custom commands
    │   └── *.md                            # Command definitions
    ├── scripts/                            # Custom scripts
    │   └── *.py                            # Utility scripts
    ├── tools/                              # Custom tools
    │   └── */                              # Tool packages
    └── config/                             # Extension config
        ├── extensions.json                 # Extension registry
        └── tracks.json                     # Customer track definitions

Consequences

Positive

1. Unified location - All customer data in one place
2. Easy backup - ~/.coditect-data/ is the only backup target
3. Clear separation - Framework cannot be modified
4. Consistent discovery - paths.py and paths.rs provide discovery
5. Namespace isolation - Extensions prefixed with customer/ in component index

Negative

1. Single point of failure - If .coditect-data/ corrupts, all data lost
2. Disk space - All data on same volume
3. Migration required - Existing scattered session logs need consolidation

Mitigation

1. Automated backups - Daily GCS backup via context watcher
2. Disk monitoring - Alert when disk usage exceeds 80%
3. Migration script - scripts/migrate-session-logs.py to consolidate

Implementation

Phase 1: Session Log Consolidation

# Create migration script
python3 ~/.coditect/scripts/migrate-session-logs.py --dry-run
python3 ~/.coditect/scripts/migrate-session-logs.py --execute

Phase 2: Extensions Directory

# Create extensions structure
mkdir -p ~/.coditect-data/extensions/{agents,skills,hooks,commands,scripts,tools,config}

# Initialize extensions registry
cat > ~/.coditect-data/extensions/config/extensions.json << 'EOF'
{
  "version": "1.0.0",
  "extensions": []
}
EOF

Phase 3: Component Discovery Update

Update scripts/core/paths.py to include:

def get_extensions_dir() -> Path:
    """Get the customer extensions directory."""
    return get_user_data_dir() / "extensions"

EXTENSIONS_DIR = get_extensions_dir()

Phase 4: Component Indexer Update

Update scripts/component-indexer.py to:

1. Scan extensions/ directory
2. Prefix customer components with customer/
3. Never overwrite framework components

Security Considerations

1. Namespace isolation - Customer components prefixed customer/
2. No framework access - Extensions cannot modify coditect-core
3. Validation - Hook validator rejects malicious extensions
4. Audit trail - All extension activations logged

Related ADRs

• ADR-114: User Data Separation from Framework (parent)
• ADR-118: Four-Tier Database Architecture
• ADR-103: Four-Database Separation
• ADR-058: Machine-Specific Session Logs

MoE Evaluation Summary

Judge Panel

Judge	Expertise	Verdict
Technical Architect	System design	APPROVED - Best unified architecture
Security Analyst	Data protection	APPROVED - With namespace isolation
DevEx Evaluator	Developer experience	APPROVED - Single predictable location

Scoring

Criterion	Score	Notes
Architecture coherence	9.25/10	Builds on ADR-114, minimal new concepts
Security posture	7.8/10	Requires namespace isolation safeguards
Developer experience	8.7/10	Single location, easy discovery
Overall	8.6/10	RECOMMENDED

Changelog

Date	Author	Change
2026-01-27	Claude Opus 4.5	Initial creation
2026-01-27	MoE Panel	Evaluation complete