When to Use This Skill

✅ Use when:

Creating a new CODITECT submodule from scratch
Setting up distributed intelligence (.coditect symlinks) in existing repository
Initializing project templates (project-plan.md, tasklist.md, README.md)
Establishing git submodule integration with parent repository
Automating batch setup of multiple submodules

❌ Don't use when:

Submodule already has .coditect symlinks (use submodule-validation instead)
Only need to verify existing setup (use submodule-validation)
Making changes to existing submodule configuration (use submodule-configuration)
Running health checks on operational submodule (use submodule-health)

Core Capabilities

1. Directory Structure Creation

Creates complete CODITECT-compliant directory structure for new submodule including:

Root directory at correct location (submodules/{category}/{repo-name}/)
Standard subdirectories (src/, docs/, tests/, scripts/, etc.)
Configuration directories (.github/, .vscode/ if applicable)
Proper permissions and ownership

2. Symlink Chain Establishment

Creates the critical symlink architecture that enables distributed intelligence:

.coditect -> ../../../.coditect (links to parent rollout-master/.coditect/)
.claude -> .coditect (Claude Code compatibility layer)
Verifies symlink integrity and accessibility
Handles relative path calculation for nested submodules

3. Template Generation

Generates project templates from CODITECT standards:

project-plan.md with phased implementation structure
tasklist.md with checkbox-based progress tracking
README.md with submodule purpose and getting started
.gitignore with CODITECT-specific exclusions
Environment-specific configurations

4. Git Submodule Integration

Configures git submodule relationship with parent repository:

Adds submodule to parent .gitmodules file
Initializes submodule git repository
Sets up remote tracking to GitHub
Configures branch tracking (main/master)
Commits submodule reference to parent repository

Usage Pattern

Step 1: Verify Parent Directory Structure

Before creating submodule, verify the category directory exists and is correct location:

# Check that category directory exists

## How to Use This Skill

1. Review the patterns and examples below
2. Apply the relevant patterns to your implementation
3. Follow the best practices outlined in this skill

ls submodules/cloud/  # or dev/, gtm/, labs/, etc.

# Verify parent .coditect is accessible
ls .coditect/agents/  # Should show all agents files

Step 2: Create Submodule Directory and Symlinks

Create the submodule directory structure and establish symlink chains:

# Create submodule directory
mkdir -p submodules/cloud/coditect-cloud-new-service

# Create symlink chains
cd submodules/cloud/coditect-cloud-new-service
ln -s ../../../.coditect .coditect
ln -s .coditect .claude

# Verify symlinks work
ls .coditect/agents/  # Should show agents from parent

Step 3: Generate Project Templates

Use templates to create initial project files:

Read template files from .coditect/templates/submodule/
Customize project-plan.md with submodule-specific phases
Customize tasklist.md with initial tasks
Customize README.md with submodule purpose
Generate .gitignore from template

Step 4: Initialize Git Repository

Set up git repository and link to remote:

git init
git remote add origin https://github.com/coditect-ai/repo-name.git
git checkout -b main
git add .
git commit -m "Initial commit: CODITECT submodule setup"

Step 5: Add to Parent Repository

cd ../../..  # Return to rollout-master root
git submodule add https://github.com/coditect-ai/repo-name.git submodules/cloud/repo-name
git commit -m "Add cloud/repo-name submodule"

Examples

See examples/ directory for:

basic-setup.sh - Simple single submodule setup
batch-setup.py - Batch setup for multiple submodules
verification-checklist.md - Post-setup verification steps

Templates

See templates/ directory for:

PROJECT-PLAN.template.md - Standard project plan structure
TASKLIST.template.md - Checkbox task list template
README.template.md - Submodule README template
.gitignore.template - Standard exclusions

Integration Points

Works with:

submodule-validation skill - Verify setup completed correctly
github-integration skill - Create GitHub repository and configure
submodule-orchestrator agent - Coordinate complete lifecycle

Calls:

Bash tool for directory creation and symlink operations
Write tool for template file generation
Read tool to access template files from .coditect/templates/

Success Criteria

Setup is complete when:

Directory structure exists at submodules/{category}/{repo-name}/
Symlinks .coditect and .claude are functional
project-plan.md, tasklist.md, README.md exist with content
Git repository initialized with remote configured
Submodule added to parent .gitmodules
All verification checks pass (see submodule-validation skill)

Common Issues

Symlink not working:

# Check symlink target
ls -la .coditect
# Should show: .coditect -> ../../../.coditect

# Verify target exists
ls ../../../.coditect/agents/  # Should list agents

Parent directory doesn't exist:

# Create category directory first
mkdir -p submodules/cloud/
# Then create submodule

Git submodule path mismatch:

Ensure path in git submodule add exactly matches directory structure
Use relative paths from rollout-master root: submodules/{category}/{repo-name}

Multi-Context Window Support

This skill supports long-running submodule setup tasks across multiple context windows using Claude 4.5's enhanced state management capabilities.

State Tracking

Checkpoint State (JSON):

{
  "setup_id": "setup_20251129_150000",
  "submodule_path": "submodules/cloud/new-service",
  "phase": "symlinks_created",
  "directory_created": true,
  "symlinks_verified": true,
  "templates_generated": ["project-plan.md", "tasklist.md", "README.md", ".gitignore"],
  "git_initialized": true,
  "git_remote_configured": false,
  "parent_integration": false,
  "validation_passed": false,
  "token_usage": 8500,
  "created_at": "2025-11-29T15:00:00Z"
}

Progress Notes (Markdown):

# Submodule Setup Progress - 2025-11-29

## Completed
- Created directory: submodules/cloud/new-service
- Established symlink chains (.coditect, .claude)
- Verified symlinks functional (all agents accessible)
- Generated project-plan.md from template
- Generated tasklist.md with initial 25 tasks
- Generated README.md with service description

## In Progress
- Git repository initialization
- Remote configuration pending

## Next Actions
- Configure git remote to GitHub
- Add to parent .gitmodules
- Run submodule-validation checks

Session Recovery

When starting a fresh context window after submodule setup work:

Load Checkpoint State: Read .coditect/checkpoints/submodule-setup-latest.json
Review Progress Notes: Check submodule-setup-progress.md for narrative context
Verify Directory State: Use LS tool to confirm directory structure exists
Check Symlinks: Verify .coditect and .claude symlinks functional
Resume From Phase: Continue from last completed phase

Recovery Commands:

# 1. Check latest checkpoint
cat .coditect/checkpoints/submodule-setup-latest.json | jq '.'

# 2. Review progress
tail -30 submodule-setup-progress.md

# 3. Verify directory exists
ls -la submodules/cloud/new-service/

# 4. Check symlinks
cd submodules/cloud/new-service
ls -la .coditect .claude
ls .coditect/agents/ | wc -l  # Should show 50+

# 5. Check git status
git status
git remote -v

State Management Best Practices

Checkpoint Files (JSON Schema):

Store in .coditect/checkpoints/submodule-setup-{submodule-name}.json
Include phase completion tracking (directory, symlinks, templates, git, validation)
Track template files generated for rollback capability
Record validation results for quality assurance

Progress Tracking (Markdown Narrative):

Maintain submodule-setup-progress.md with timestamp entries
Document decisions made (directory structure choices, template customizations)
Note issues encountered and resolutions
List next steps with specific commands

Git Integration:

Create checkpoint before git operations (init, remote add, submodule add)
Commit setup work incrementally (directory → templates → git → parent)
Use conventional commit format for consistency
Tag completion: git tag submodule-setup-complete-{name}

Progress Checkpoints

Natural Breaking Points:

After directory structure created
After symlinks established and verified
After all templates generated
After git repository initialized
After parent repository integration complete

Checkpoint Creation Pattern:

# Automatic checkpoint creation at critical phases
if phase in ["symlinks_created", "templates_generated", "git_initialized"]:
    create_checkpoint({
        "submodule_path": submodule_path,
        "phase": phase,
        "templates_generated": templates_list,
        "validation_status": validation_results,
        "tokens": current_token_usage
    })

Example: Multi-Context Batch Setup

Context Window 1: First 3 Submodules

{
  "checkpoint_id": "ckpt_batch_setup_part1",
  "phase": "partial_completion",
  "submodules_completed": [
    "submodules/cloud/service-1",
    "submodules/cloud/service-2",
    "submodules/cloud/service-3"
  ],
  "submodules_pending": [
    "submodules/dev/tool-1",
    "submodules/dev/tool-2"
  ],
  "next_action": "Continue with dev category",
  "token_usage": 18000
}

Context Window 2: Remaining Submodules

# Resume from checkpoint
cat .coditect/checkpoints/ckpt_batch_setup_part1.json

# Continue with pending submodules
# (Context restored in 3 minutes vs 25 minutes from scratch)

# Complete remaining setup
{
  "checkpoint_id": "ckpt_batch_setup_complete",
  "phase": "all_complete",
  "total_submodules": 5,
  "all_validated": true,
  "token_usage": 15000
}

Token Savings: 18000 (first context) + 15000 (second context) = 33000 total vs. 55000 without checkpoint = 40% reduction

Reference: See docs/CLAUDE-4.5-BEST-PRACTICES.md for complete multi-context window workflow guidance.

Success Output

When successful, this skill MUST output:

✅ SKILL COMPLETE: submodule-setup

Completed:
- [x] Directory structure created at submodules/{category}/{repo-name}/
- [x] Symlinks established (.coditect → ../../../.coditect, .claude → .coditect)
- [x] Symlinks verified functional (agents accessible)
- [x] Templates generated (project-plan.md, tasklist.md, README.md, .gitignore)
- [x] Git repository initialized with remote configured
- [x] Submodule added to parent .gitmodules
- [x] All verification checks passed

Outputs:
- submodules/{category}/{repo-name}/ directory structure
- Functional symlink chains (.coditect, .claude)
- Project templates customized for submodule purpose
- Git repository with remote: {github_url}
- Parent .gitmodules entry

Next Steps:
- Push initial commit to remote: git push -u origin main
- Run submodule-validation skill to verify setup
- Begin development using project-plan.md phases

Completion Checklist

Before marking this skill as complete, verify:

Directory exists at correct path: submodules/{category}/{repo-name}/
Symlinks created: ls -la .coditect .claude shows correct targets
Symlinks functional: ls .coditect/agents/ | wc -l returns >130
Templates exist: project-plan.md, tasklist.md, README.md, .gitignore
Git initialized: .git/ directory exists
Remote configured: git remote -v shows correct GitHub URL
Parent .gitmodules has entry for submodule
No broken symlinks or permission errors
All template content customized (no placeholder text)

Failure Indicators

This skill has FAILED if:

❌ Directory created in wrong location (not under submodules/{category}/)
❌ Symlinks broken (target does not exist or is inaccessible)
❌ Symlink targets wrong level (e.g., ../../.coditect instead of ../../../.coditect)
❌ Templates not generated or contain uncustomized placeholders
❌ Git repository not initialized (no .git/ directory)
❌ Remote not configured or URL incorrect
❌ Parent .gitmodules missing submodule entry
❌ Permission errors on directory or symlinks
❌ Category directory doesn't exist and wasn't created

When NOT to Use

Do NOT use this skill when:

Submodule already exists and has .coditect symlinks (use submodule-validation instead)
Only verifying existing setup (use submodule-validation skill)
Modifying existing submodule configuration (use submodule-configuration skill)
Running health checks on operational submodule (use submodule-health skill)
Cloning existing submodule to new location (use git clone + re-setup)
Just updating templates in existing submodule (edit files directly)
Need to change category of existing submodule (requires manual migration)

Use alternative skills:

submodule-validation - Verify existing submodule setup
submodule-configuration - Modify existing submodule config
submodule-health - Check operational status

Anti-Patterns (Avoid)

Anti-Pattern	Problem	Solution
Creating submodule without category directory	Wrong path structure	Always use `submodules/{category}/{repo}/` format
Wrong symlink depth (../../ vs ../../../)	Broken symlinks	Count directory levels carefully: 3 levels deep
Not verifying symlinks immediately	Broken setup not detected	Run `ls .coditect/agents/` right after creation
Skipping template customization	Generic placeholders remain	Customize all {repo-name}, {description} placeholders
Not initializing git before symlinks	Symlinks not tracked	Create directory → symlinks → git init → add all
Adding to .gitmodules manually	Typos, wrong paths	Use `git submodule add <url> <path>` command
Using absolute symlink paths	Non-portable, breaks on clone	Always use relative paths (../../../.coditect)
Not testing parent .coditect access	Setup appears OK but broken	Verify `ls ../../../.coditect/agents/` succeeds

Principles

This skill embodies:

#1 Recycle → Extend → Re-Use → Create - Reuse parent .coditect via symlinks
#2 Full Automation - Complete setup from single skill invocation
#5 Eliminate Ambiguity - Explicit directory structure and symlink patterns
#6 Clear, Understandable, Explainable - Step-by-step verification checklist
#7 Inform for Non-Destructive, Confirm for Destructive - Directory creation auto, no confirmation needed
#8 No Assumptions - Verify each step (directory exists, symlinks work, git configured)

Full Principles: CODITECT-STANDARD-AUTOMATION.md

Core Capabilities​

1. Directory Structure Creation​

2. Symlink Chain Establishment​

3. Template Generation​

4. Git Submodule Integration​

Usage Pattern​

Step 1: Verify Parent Directory Structure​

Step 2: Create Submodule Directory and Symlinks​

Step 3: Generate Project Templates​

Step 4: Initialize Git Repository​

Step 5: Add to Parent Repository​

Examples​

Templates​

Integration Points​

Success Criteria​

Common Issues​

Multi-Context Window Support​

State Tracking​

Session Recovery​

State Management Best Practices​

Progress Checkpoints​

Example: Multi-Context Batch Setup​

Success Output​

Completion Checklist​

Failure Indicators​

When NOT to Use​

Anti-Patterns (Avoid)​

Principles​