Skip to main content

ADR-002: Integration Pattern — Submodule vs Fork vs Vendored

Status​

Proposed

Context​

Having decided to adopt Brainqub3 Agent Labs as a subsystem (ADR-001), we must determine the technical integration pattern. The framework exists as an external open-source repository, and CODITECT must decide how to incorporate and maintain it.

Agent Labs characteristics relevant to integration:

  • Active open-source project with ongoing development
  • MIT/Apache 2.0 license (permissive)
  • Python-based with dependencies: claude-agent-sdk, pandas, numpy, scikit-learn
  • CLI-driven with agent-labs command entrypoint
  • Structured as a Python package with clear API boundaries
  • Data stored in local filesystem (runs/, evaluators/, scenarios/)
  • No database or service dependencies

CODITECT uses git submodules for external dependencies when:

  • Tracking upstream improvements is valuable
  • Clear separation of concerns is needed
  • Versioning and updates need to be controlled

Alternative integration patterns include hard forking, vendored copies, or pip package dependencies.

Decision​

Use git submodule (read-only reference) at submodules/r-and-d/brainqub3-agent-labs/ with the following constraints:

  1. Read-Only Upstream: Track upstream via submodule, never push modifications back
  2. Version Pinning: Pin to specific commit SHA, update deliberately
  3. CODITECT Adapter Layer: All CODITECT-specific code lives in scripts/scaling-analysis/, never in the submodule
  4. Local Configuration: Override default paths to store data in ~/.coditect-data/scaling-experiments/
  5. Wrapper Commands: Create CODITECT slash commands (/scaling-run, /scaling-dashboard) that invoke Agent Labs CLI

This pattern treats Agent Labs as an external tool, similar to how CODITECT integrates other R&D frameworks (e.g., codestoryai/sidecar).

Alternatives Considered​

1. Hard Fork (Push to coditect-ai/agent-labs)​

Pros:

  • Full control over codebase
  • Can modify internals freely
  • No dependency on external repository availability

Cons:

  • Creates maintenance burden (must manually merge upstream improvements)
  • Diverges from paper-aligned reference implementation
  • Loses credibility of using "official" framework
  • High effort to stay synchronized with upstream research updates
  • Violates DRY principle (duplicate code evolution)

2. Vendored Copy (Copy source into coditect-core)​

Pros:

  • No git submodule complexity
  • Simplified repository structure

Cons:

  • No tracking of upstream changes
  • Difficult to update when Agent Labs improves
  • Violates single-source-of-truth principle
  • Loses git history and authorship attribution
  • Legal risk if license terms change

3. Pip Package Dependency (Install from PyPI)​

Pros:

  • Standard Python dependency management
  • Automatic version resolution
  • No git submodule overhead

Cons:

  • Agent Labs not currently published to PyPI
  • Would need to wait for package releases vs tracking latest commits
  • Less visibility into source code during development
  • Harder to debug integration issues
  • Cannot easily reference specific research versions

4. Embedded Library (Import as Python module)​

Pros:

  • Programmatic integration
  • Could vendor only needed components

Cons:

  • Agent Labs is CLI-first, not library-first
  • Would require refactoring upstream code
  • Breaks compatibility with official usage patterns
  • Loses evaluator validation and run management features

Consequences​

Positive​

  1. Upstream Tracking: Benefit from Agent Labs improvements, bug fixes, and research updates
  2. Clear Boundaries: Submodule boundary enforces separation between CODITECT adapter code and Agent Labs core
  3. Version Control: Explicit commit pinning prevents surprise breakage
  4. Low Maintenance: No need to maintain forked codebase
  5. Credibility: Using "official" framework maintains alignment with published research
  6. Offline Operation: Submodule cloned locally, no runtime dependency on external services
  7. Audit Trail: Git history preserved, can trace back to specific paper versions
  8. Flexibility: Can switch to fork pattern later if needed

Negative​

  1. Submodule Complexity: Developers must understand git submodule update --init --recursive
  2. Version Pinning Overhead: Must manually update submodule pointer when upstream improves
  3. CLI Indirection: CODITECT commands must wrap Agent Labs CLI, adding abstraction layer
  4. Path Management: Must configure Agent Labs to use CODITECT data directories
  5. Dependency Conflicts: Agent Labs dependencies (e.g., pandas version) could conflict with CODITECT requirements
  6. No Direct Modification: Cannot quickly patch bugs in Agent Labs code (must work around or upstream)

Risks​

  1. Upstream Breaking Changes: Agent Labs refactors could break CODITECT adapter

    • Mitigation: Pin to stable commit; test before updating; maintain adapter test suite

  2. Submodule Detached HEAD: Common git submodule issue confuses developers

    • Mitigation: Document workflow in submodules/r-and-d/brainqub3-agent-labs/README.md

  3. Dependency Conflicts: Agent Labs and CODITECT might require incompatible package versions

    • Mitigation: Use separate virtual environment for scaling experiments if needed

  4. Upstream Disappearance: Repository could be deleted or moved

    • Mitigation: Fork as backup; submodule code already cloned locally

  5. API Stability: Agent Labs CLI interface might change

    • Mitigation: Wrap CLI calls in adapter functions; version-specific handling

  6. Data Location Coupling: Agent Labs assumes data in ./runs/, must override

    • Mitigation: Use environment variables or CLI flags to redirect paths

Implementation Notes​

Submodule Setup​

# Add submodule
cd /path/to/coditect-core
git submodule add https://github.com/brainqub3/agent-labs.git \
  submodules/r-and-d/brainqub3-agent-labs

# Pin to specific commit (example)
cd submodules/r-and-d/brainqub3-agent-labs
git checkout a3f2b1c  # Replace with actual stable commit
cd ../../..
git add submodules/r-and-d/brainqub3-agent-labs
git commit -m "chore: Pin agent-labs to commit a3f2b1c"

CODITECT Adapter Structure​

scripts/scaling-analysis/
├── adapter.py          # CODITECT agent → Agent Labs architecture mapping
├── run_experiment.py   # Wrapper for agent-labs run
├── compare_runs.py     # Wrapper for agent-labs compare
├── dashboard.py        # Wrapper for agent-labs dashboard
└── config.py           # Path overrides, CODITECT-specific settings

Wrapper Command Example​

# commands/scaling-run.md implementation
import subprocess
from pathlib import Path

AGENT_LABS = Path(__file__).parent.parent / "submodules/r-and-d/brainqub3-agent-labs"
DATA_DIR = Path.home() / ".coditect-data/scaling-experiments"

def run(scenario: str, architecture: str):
    subprocess.run([
        "python", "-m", "agent_labs.cli", "run",
        "--scenario", scenario,
        "--architecture", architecture,
        "--data-dir", str(DATA_DIR)
    ], cwd=AGENT_LABS)

Version Update Workflow​

# When Agent Labs releases improvements
cd submodules/r-and-d/brainqub3-agent-labs
git fetch origin
git log HEAD..origin/main  # Review changes
git checkout <new-commit>
cd ../../..

# Test compatibility
pytest scripts/scaling-analysis/tests/

# Commit submodule update
git add submodules/r-and-d/brainqub3-agent-labs
git commit -m "chore(submodules): Update agent-labs to <version>"

Data Directory Override​

Set in CODITECT environment:

export AGENT_LABS_DATA_DIR=~/.coditect-data/scaling-experiments

References​

  • ADR-001: Agent Labs Adoption as CODITECT Subsystem
  • Git Submodules Documentation: https://git-scm.com/book/en/v2/Git-Tools-Submodules
  • CODITECT Submodule Pattern: submodules/r-and-d/sidecar/ (similar approach)
  • CODITECT Safety Directives: .claude/CLAUDE.md → "Never modify protected installation"
  • Agent Labs Repository: https://github.com/brainqub3/agent-labs
  • Related ADRs:
    • ADR-003: Agent Orchestration Mapping
    • ADR-004: Scaling Model for Agent Selection

Author: Claude (Sonnet 4.5) Date: 2026-02-16 Track: H (Framework) Task ID: H.0