Skip to main content

ADR-213: Documentation Externalization to coditect-documentation

Status​

Accepted — 2026-02-19

Context​

coditect-core contains ~9,490 markdown files (~87 MB) — a mix of operational content (agents, commands, skills, hooks, scripts needed at runtime) and documentary content (ADRs, analysis, research, project plans, guides, standards) that doesn't need to ship with the framework.

Problems​

  1. Protected installation bloat: ~/Library/Application Support/CODITECT/core/ contains ~41 MB of documentary content that is never used at runtime. Every machine running coditect-core downloads and stores this content unnecessarily.

  2. No centralized documentation source: Documentary content is scattered across coditect-core's internal/, docs/, docs-contributor/, and coditect-core-standards/ directories, plus individual submodule repos. There is no single source of truth for platform documentation.

  3. docs.coditect.ai dependency on coditect-core: The docs-sync.py pipeline pulls documentary content from coditect-core, creating a tight coupling between the framework repo and the documentation site.

  4. Research artifacts in coditect-core: The analyze-new-artifacts/ directory (6.1 GB, 10,939 files) contains research topics and investigations that are not part of the operational framework.

  5. Cross-submodule documentation: 97 submodules each contain their own docs/, internal/, and documentation files with no unified organization or publishing pipeline.

Decision​

1. Create coditect-ai/coditect-documentation as the SSOT for all documentary content​

All non-operational markdown content moves to a dedicated repository, organized by submodule name:

coditect-documentation/
├── coditect-core/
│   ├── adrs/           # From internal/architecture/adrs/ (212+ ADRs)
│   ├── analysis/       # From internal/analysis/
│   ├── architecture/   # From internal/architecture/ (non-ADR)
│   ├── archive/        # From internal/archive/
│   ├── contributor/    # From docs-contributor/
│   ├── guides/         # From docs/guides/ + docs/getting-started/
│   ├── project/        # From internal/project/ (tracks, sprints, epics)
│   ├── reference/      # From docs/reference/
│   ├── research/       # From internal/research/
│   ├── standards/      # From coditect-core-standards/
│   ├── templates/      # From docs/templates/
│   └── workflows/      # From docs/workflows/
├── coditect-cloud-infra/   # Cloud infra docs
├── coditect-bot/           # Bot docs
├── ...                     # All other submodule docs
└── session-logs/           # Cross-project session logs
    └── projects/{id}/{machine}/SESSION-LOG-*.md

2. Create coditect-ai/coditect-research-lab for research artifacts​

The analyze-new-artifacts/ directory moves to a separate repository for research topics under investigation:

coditect-research-lab/
├── ai-guardrails-research/
├── agent-zero-research/
├── scaling-agent-systems/
├── universal-document-object-model/
├── ...                              # 100+ research topics
└── archive/

3. Keep operational content in coditect-core​

The following directories remain in coditect-core as they are required at runtime:

DirectoryFilesWhy
agents/805Runtime: /agent, /which, registry_loader.py
commands/390Runtime: command execution pipeline
skills/*/SKILL.md451Runtime: CEF loading, skill-selector.py
hooks/128Runtime: PostToolUse auto-invocation
scripts/617Automation scripts
config/variesComponent counts, schemas
CODITECT.md1Claude Code instructions (ADR-212)

4. Update docs-sync.py to source from coditect-documentation​

The documentation publishing pipeline (docs-sync.py v2.0.0) reads documentary content from coditect-documentation (priority 0) and operational content from coditect-core (priority 1). The Docusaurus deployment pipeline at docs.coditect.ai remains unchanged.

5. Submodule integration​

Both new repos are added as submodules in coditect-rollout-master:

submodules/docs/coditect-documentation   # Documentary content SSOT
submodules/labs/coditect-research-lab    # Research idea factory

Consequences​

Positive​

  • Protected installation shrinks by ~41 MB (~1,085 files removed from coditect-core)
  • Single source of truth for all platform documentation across 97 submodules
  • docs.coditect.ai can be updated independently of framework releases
  • Research artifacts are properly separated from the operational framework
  • Cross-submodule docs are organized consistently by submodule name
  • Git history is preserved — content is copied (not moved with git mv) to maintain original repo history

Negative​

  • Two repos to maintain instead of one for documentary content
  • Path references in CODITECT.md, hooks, and scripts need updating
  • Transition period where content may exist in both locations temporarily
  • Submodule management adds complexity to the rollout-master workflow

Neutral​

  • ADR numbering is unaffected — ADR numbers are immutable identifiers regardless of storage location
  • Session log SSOT remains at ~/.coditect-data/session-logs/ locally; coditect-documentation provides the git-backed archive
  • docs-sync.py transformation logic is unchanged; only source paths are updated

Implementation​

Phase 1: Repository Creation and Content Migration (Complete)​

StepStatus
Create coditect-ai/coditect-documentationDone (441f266)
Create coditect-ai/coditect-research-labDone (8e69100)
Migrate coditect-core documentary content (1,607 files)Done
Migrate session logs (75 files, 16 projects)Done
Migrate other submodule docs (2,591 files from 82 repos)Done
Migrate research artifacts (100+ topics)Done
Add submodules to rollout-masterDone (eff01682, a263d61d)

Phase 2: Update Consumers (Complete)​

StepStatus
Update docs-sync.py SOURCE_REPOS and CONTENT_MAPPINGSDone (v2.0.0)
Update scripts/core/paths.py with get_docs_dir()Done (already implemented)
Update governance hooks (5 hooks with hardcoded paths)Done (4321b5fd)
Update CODITECT.md path referencesDone (a9c2e76d, v4.1.0)

Phase 3: Automation (Complete)​

StepStatus
Create doc-externalizer.py PostToolUse hookDone
Configure GitHub Action for auto-publish (trigger-docs-rebuild.yml)Done
Set up daily backup automation (daily-docs-backup.yml)Done
Update docs-deploy.yml with docs-sync CI stepDone

Phase 4: Cleanup (Complete)​

StepStatus
Remove analyze-new-artifacts/ from coditect-core (3.8 GB)Done (a9c2e76d)
Remove internal/ from coditect-core (51 MB, 838 files)Done (a9c2e76d)
Remove coditect-core-standards/ from coditect-core (1.7 MB, 89 files)Done (a9c2e76d)
Update CODITECT.md v4.1.0 with coditect-documentation pathsDone (a9c2e76d)
Deploy docs.coditect.ai v2.0.0-centralizedPending (requires CODITECT_DOCS_DEPLOY_PAT secret)
Verify all consumers read from new locationsPending
  • ADR-065: Documentation Sync Architecture (original docs-sync.py design)
  • ADR-114: User Data Separation (session log local SSOT)
  • ADR-155: Session Log SSOT Location
  • ADR-212: CODITECT.md Controlled CLAUDE.md Symlink
  • Repository: coditect-documentation
  • Repository: coditect-research-lab