/submodule-init - Interactive Submodule Initialization

Initialize any folder as a CODITECT-compatible git submodule with automatic GitHub repository creation, symlink chain setup, and parent repository registration.

System Prompt

EXECUTION DIRECTIVE: When the user invokes this command, you MUST:

1. Run the interactive script - Execute scripts/submodule-init.sh
2. Collect user inputs - Target folder, parent project, GitHub org, visibility
3. Execute 5-step workflow:
   • Validate prerequisites
   • Initialize git repository
   • Create GitHub repository
   • Setup CODITECT symlinks
   • Register submodule with parent
4. Report results - Show completion status with repo URL

REQUIRES CONFIRMATION: This command modifies files, creates GitHub repos, and pushes commits.

---

Usage

/submodule-init                              # Interactive mode
/submodule-init path/to/folder               # With target folder
/submodule-init path/to/folder --org myorg   # With custom org

Examples

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

# Specify non-default GitHub org
/submodule-init submodules/cloud/api-service --org my-github-org

# Make public instead of private
/submodule-init submodules/docs/handbook --visibility public

Interactive Prompts

The script will prompt for:

1. Target folder path (required)

   • The folder to convert to a submodule
   • Must exist and contain files
   • Example: submodules/gtm/coditect-pricing-analysis

2. Parent project path (default: /Users/halcasteel/PROJECTS/coditect-rollout-master)

   • The repository that will contain the submodule
   • Must be a valid git repository

3. GitHub organization (default: coditect-ai)

   • Where the new repository will be created
   • Must have push access

4. Repository visibility (default: private)

   • Either private or public

What It Does

Step 1: Validation

• Checks target folder exists
• Verifies parent project is a git repo
• Confirms gh CLI is authenticated
• Validates git user configuration

Step 2: Initialize Repository

cd <target_folder>
git init
git branch -M main
git add .
git commit -m "Initial commit"

Step 3: Create GitHub Repository

gh repo create <org>/<repo-name> --private --source=. --push

Step 4: Setup Symlinks

Creates the CODITECT distributed intelligence symlink chain:

# Calculate relative path to coditect-core
ln -s <relative-path-to-coditect-core> .coditect
ln -s .coditect .claude
git add .coditect .claude
git commit -m "Add CODITECT symlink chain"
git push

Step 5: Register with Parent

cd <parent_project>
git submodule add <repo-url> <relative-path>
git commit -m "Add submodule: <name>"
git push

Related Commands

After submodule setup, use these for component management:

• /component-create - Create new agents, skills, commands, etc.
• /classify - Classify documents with MoE
• /orient - Begin a development session

Symlink Architecture

The symlinks enable CODITECT distributed intelligence:

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

This provides access to:

• 148 AI agents
• all slash commands
• 218 skills
• All CODITECT automation

Script Location

scripts/submodule-init.sh

Direct Script Usage

# Interactive mode
./scripts/submodule-init.sh

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

# Non-interactive (all args provided)
./scripts/submodule-init.sh \
  --target submodules/gtm/my-project \
  --parent /Users/halcasteel/PROJECTS/coditect-rollout-master \
  --org coditect-ai \
  --visibility private

Prerequisites

• gh CLI - GitHub CLI must be installed and authenticated
• git - Git must be configured with user.name and user.email
• Target folder - Must exist and contain files to commit
• Parent repo - Must be a valid git repository

Error Handling

The script will abort and report errors if:

• Target folder doesn't exist
• Parent project is not a git repo
• gh CLI is not authenticated
• GitHub repo creation fails
• Git operations fail

Success Output

======================================================
  Submodule Initialization Complete!
======================================================

Repository: https://github.com/coditect-ai/my-project
Local path: submodules/gtm/my-project

Completed steps:
  ✓ Step 1: Validation
  ✓ Step 2: Git initialization
  ✓ Step 3: GitHub repository creation
  ✓ Step 4: Symlink chain setup
  ✓ Step 5: Parent submodule registration

Next: Run /component-create to add agents/skills/commands

Symlink chain:
  .coditect -> ../../../core/coditect-core
  .claude -> .coditect

CODITECT access enabled:
  - 148 AI agents
  - all slash commands
  - 218 reusable skills

Rollback

If something goes wrong after partial completion:

# Remove from parent's .gitmodules
git config -f .gitmodules --remove-section submodule.<path>
git rm --cached <path>

# Delete the GitHub repo (if created)
gh repo delete <org>/<name> --yes

# Clean up local folder's git
rm -rf <target>/.git <target>/.coditect <target>/.claude

---

Action Policy

<default_behavior> This command requires explicit user confirmation before:

• Creating a new GitHub repository
• Pushing commits to GitHub
• Modifying the parent repository's .gitmodules

Shows a preview of all actions before execution. </default_behavior>

After execution, verify: - GitHub repository exists and is accessible - Symlink chain is functional (.coditect, .claude) - Submodule is registered in parent .gitmodules - All commits pushed to both repos

Success Output

When submodule initialization completes:

✅ COMMAND COMPLETE: /submodule-init
Target: <path>
Repository: <github-url>
Symlinks: .coditect, .claude configured
Parent: Registered in .gitmodules
Access: 148 agents, 169 commands, 218 skills

Completion Checklist

Before marking complete:

• Prerequisites validated
• Git repository initialized
• GitHub repository created
• Symlink chain established
• Submodule registered with parent
• All commits pushed

Failure Indicators

This command has FAILED if:

• ❌ Target folder doesn't exist
• ❌ gh CLI not authenticated
• ❌ GitHub repo creation failed
• ❌ Symlinks not functional
• ❌ Parent registration failed

When NOT to Use

Do NOT use when:

• Folder already a git repo
• Submodule already exists
• No GitHub access
• Just need symlinks (use /setup-submodule)

Anti-Patterns (Avoid)

Anti-Pattern	Problem	Solution
Skip prerequisites	Partial completion	Validate first
Wrong org	Access denied	Verify org access
Skip symlinks	No CODITECT access	Always setup symlinks

Principles

This command embodies:

• #3 Complete Execution - 5-step lifecycle
• #5 No Assumptions - Validate prerequisites

Full Standard: CODITECT-STANDARD-AUTOMATION.md

---

Version: 1.2.0 Created: 2026-01-03 Updated: 2026-01-03 Author: CODITECT Team