ADR-050: Submodule Initialization Lifecycle

Status: Accepted Date: January 3, 2026 Authors: CODITECT AI Team Deciders: Hal Casteel

Context

CODITECT uses a distributed repository architecture with 74+ git submodules organized across 8 categories:

coditect-rollout-master/
└── submodules/
    ├── archives/     # Archived projects
    ├── cloud/        # Cloud infrastructure
    ├── compliance/   # Compliance frameworks
    ├── core/         # Core framework (coditect-core)
    ├── dev/          # Development tools
    ├── docs/         # Documentation
    ├── gtm/          # Go-to-market
    ├── integrations/ # Third-party integrations
    ├── investors/    # Investor materials
    ├── labs/         # Experimental projects
    ├── market/       # Market research
    ├── ops/          # Operations
    ├── products/     # Product definitions
    └── r-and-d/      # Research & development

The Distributed Intelligence Pattern

Every submodule connects to the CODITECT framework through a symlink chain:

submodule/
├── .coditect -> ../../../core/coditect-core  (relative path)
├── .claude -> .coditect
└── ... (project files)

This enables:

Access to 148 AI agents
Access to 169 slash commands
Access to 218 reusable skills
Consistent AI behavior across all projects

Problems Identified

Manual, error-prone process - Setting up submodules required 10+ git commands
Inconsistent symlinks - Relative path calculation often wrong
No GitHub automation - Manual repo creation via web UI
Forgotten parent registration - Submodules not added to parent .gitmodules
No validation - Missing prerequisite checks (gh auth, git config)

Requirements

Single command to convert any folder to a submodule
Automatic GitHub repository creation
Correct relative symlink calculation
Automatic parent repository registration
Prerequisite validation

Decision

Implement a Submodule Initialization Lifecycle with a dedicated command (/submodule-init) and script (scripts/submodule-init.sh) that executes a 5-step standardized process.

Architecture

┌─────────────────────────────────────────────────────────────────┐
│               SUBMODULE INITIALIZATION LIFECYCLE                 │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│   USER INPUT                                                     │
│       │                                                          │
│       ▼                                                          │
│   ┌──────────────────────────────┐                              │
│   │  /submodule-init             │                              │
│   │  submodules/gtm/my-project   │                              │
│   └─────────────┬────────────────┘                              │
│                 │                                                │
│                 ▼                                                │
│   ┌──────────────────────────────────────────────────────────┐  │
│   │                    5-STEP PROCESS                         │  │
│   ├──────────────────────────────────────────────────────────┤  │
│   │                                                           │  │
│   │  Step 1: VALIDATE PREREQUISITES                           │  │
│   │     └─→ Check folder exists                              │  │
│   │     └─→ Check parent is git repo                         │  │
│   │     └─→ Check gh CLI authenticated                       │  │
│   │     └─→ Check git user configured                        │  │
│   │                                                           │  │
│   │  Step 2: INITIALIZE GIT REPOSITORY                        │  │
│   │     └─→ git init                                         │  │
│   │     └─→ git branch -M main                               │  │
│   │     └─→ git add . && git commit                          │  │
│   │                                                           │  │
│   │  Step 3: CREATE GITHUB REPOSITORY                         │  │
│   │     └─→ gh repo create org/name --private               │  │
│   │     └─→ git push -u origin main                          │  │
│   │                                                           │  │
│   │  Step 4: SETUP SYMLINK CHAIN                              │  │
│   │     └─→ Calculate relative path to coditect-core         │  │
│   │     └─→ ln -s <path> .coditect                           │  │
│   │     └─→ ln -s .coditect .claude                          │  │
│   │     └─→ Commit and push symlinks                         │  │
│   │                                                           │  │
│   │  Step 5: REGISTER WITH PARENT                             │  │
│   │     └─→ cd parent_project                                │  │
│   │     └─→ git submodule add <url> <path>                   │  │
│   │     └─→ git commit && git push                           │  │
│   │                                                           │  │
│   └──────────────────────────────────────────────────────────┘  │
│                 │                                                │
│                 ▼                                                │
│   ┌──────────────────────────────┐                              │
│   │  Submodule Ready for Use     │                              │
│   │  with CODITECT Framework     │                              │
│   └──────────────────────────────┘                              │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Symlink Path Calculation

The script uses Python's os.path.relpath() to calculate correct relative paths:

# Example calculations
# From: submodules/gtm/my-project/
# To:   submodules/core/coditect-core/
# Result: ../../core/coditect-core

# From: submodules/gtm/category/my-project/
# To:   submodules/core/coditect-core/
# Result: ../../../core/coditect-core

Implementation

Command: commands/submodule-init.md Script: scripts/submodule-init.sh

# Interactive mode
/submodule-init

# With target folder
/submodule-init submodules/gtm/my-project

# Non-interactive
./scripts/submodule-init.sh \
  --target submodules/gtm/my-project \
  --org coditect-ai \
  --visibility private \
  --non-interactive

Consequences

Positive

Single command - Replaces 10+ manual git commands
Correct symlinks - Automated path calculation prevents errors
GitHub automation - No manual web UI interaction
Complete registration - Parent .gitmodules always updated
Validation - Prerequisites checked before execution

Negative

GitHub CLI dependency - Requires gh installed and authenticated
Network dependency - Requires internet for GitHub operations
Organization access - User must have push access to GitHub org

Neutral

Default values - Assumes coditect-ai org and private visibility
Rollout-master focus - Optimized for coditect-rollout-master structure

How to Use

Quick Start

# Convert a folder to a submodule
/submodule-init submodules/gtm/my-new-project

Interactive Mode

Run without arguments for guided prompts:

/submodule-init

The script will prompt for:

Target folder path - The folder to convert (required)
Parent project path - Default: /Users/halcasteel/PROJECTS/coditect-rollout-master
GitHub organization - Default: coditect-ai
Repository visibility - Default: private

Prerequisites

Before running, ensure:

GitHub CLI installed and authenticated

# Install
brew install gh

# Authenticate
gh auth login

# Verify
gh auth status

Git user configured

git config --global user.name "Your Name"
git config --global user.email "your@email.com"

Target folder exists with content
```
ls -la submodules/gtm/my-project/
```

Full Workflow Example

# Step 1: Prepare your folder with content
mkdir -p submodules/gtm/pricing-research
cp -r ~/Documents/pricing-analysis/* submodules/gtm/pricing-research/

# Step 2: Initialize as submodule
/submodule-init submodules/gtm/pricing-research

# Step 3: Verify symlinks work
ls -la submodules/gtm/pricing-research/.claude/CLAUDE.md

# Step 4: Navigate and start working
cd submodules/gtm/pricing-research
/orient

Post-Initialization

After submodule initialization:

Add components (optional)

cd submodules/gtm/my-project
/component-create agent data-analyst
/component-create skill validation-patterns

Verify CODITECT access

# Check symlink
ls -la .claude/

# Test command access
/which analyze data

Start development session
```
/orient
```

Cloning a Repository with Submodules

When cloning rollout-master:

# Clone with all submodules
git clone --recursive https://github.com/coditect-ai/coditect-rollout-master.git

# Or initialize after clone
git clone https://github.com/coditect-ai/coditect-rollout-master.git
cd coditect-rollout-master
git submodule update --init --recursive

Troubleshooting

GitHub CLI Not Authenticated

[ERROR] GitHub CLI is not authenticated
[INFO] Run: gh auth login

Solution: Run gh auth login and follow prompts.

Target Folder Already a Git Repo

[ERROR] Target folder is already a git repository

Solution: The folder already has .git/. Either use a different folder or remove existing git initialization.

Submodule Already Registered

fatal: 'path/to/folder' already exists in the index

Solution: The submodule is already in .gitmodules. Check with git submodule status.

Symlink Verification Failed

# Check symlink points to valid location
ls -la .coditect

# Verify CLAUDE.md accessible
cat .claude/CLAUDE.md

Rollback

If initialization fails partially:

# 1. Remove from parent's .gitmodules
cd /Users/halcasteel/PROJECTS/coditect-rollout-master
git config -f .gitmodules --remove-section submodule.submodules/gtm/my-project
git rm --cached submodules/gtm/my-project

# 2. Delete GitHub repository (if created)
gh repo delete coditect-ai/my-project --yes

# 3. Clean up local folder's git
cd submodules/gtm/my-project
rm -rf .git .coditect .claude

Separation of Concerns

This ADR covers submodule lifecycle only. For creating CODITECT framework components (agents, skills, commands), see:

ADR-049 Component Creation Lifecycle

Typical Complete Workflow

# 1. SUBMODULE LIFECYCLE - Create the project structure
/submodule-init submodules/gtm/my-project

# 2. COMPONENT CREATION - Add framework components
cd submodules/gtm/my-project
/component-create agent project-analyzer
/component-create skill data-validation
/component-create command analyze

# 3. START WORKING
/orient

Component	Purpose
`commands/submodule-init.md`	Command definition
`scripts/submodule-init.sh`	Initialization script
`commands/component-create.md`	Component creation (separate concern)
`.gitmodules`	Parent submodule registry

References

Version: 1.0.0 Last Updated: January 3, 2026 Author: CODITECT Team

Context​

The Distributed Intelligence Pattern​

Problems Identified​

Requirements​

Decision​

Architecture​

Symlink Path Calculation​

Implementation​

Consequences​

Positive​

Negative​

Neutral​

How to Use​

Quick Start​

Interactive Mode​

Prerequisites​

Full Workflow Example​

Post-Initialization​

Cloning a Repository with Submodules​

Troubleshooting​

GitHub CLI Not Authenticated​

Target Folder Already a Git Repo​

Submodule Already Registered​

Symlink Verification Failed​

Rollback​

Separation of Concerns​

Typical Complete Workflow​

Related Components​

References​