When to Use This Skill

✅ Use when:

Verifying new submodule setup completed correctly
Troubleshooting submodule configuration issues
Running health checks after updates
Validating batch submodule operations
Auditing submodule compliance with CODITECT standards

❌ Don't use when:

Initial setup hasn't been completed (use submodule-setup first)
Creating new submodule (validation comes after setup)
Modifying configuration (use submodule-configuration)
Monitoring ongoing operations (use submodule-health)

Core Capabilities

1. Symlink Integrity Verification

Validates that symlink chains are correctly established and functional:

.coditect symlink exists and points to ../../../.coditect
.claude symlink exists and points to .coditect
Symlink targets are accessible (not broken)
CODITECT framework is accessible through symlinks (agents/, skills/, commands/)
Relative paths are correct for submodule location

2. Template Verification

Confirms required project templates exist and have content:

project-plan.md exists with valid structure
tasklist.md exists with checkbox format
README.md exists with submodule description
.gitignore exists with standard exclusions
Templates follow CODITECT standards

3. Git Configuration Validation

Verifies git repository and remote configuration:

Git repository initialized (.git directory exists)
Remote 'origin' configured with GitHub URL
Branch tracking configured (main branch)
.gitmodules entry exists in parent repository
Submodule can push/pull from remote

4. Framework Accessibility Testing

Tests that CODITECT framework is fully accessible:

Can read agents from .coditect/agents/
Can read skills from .coditect/skills/
Can read commands from .coditect/commands/
Can execute scripts from .coditect/scripts/
STANDARDS.md and other core files accessible

Usage Pattern

Step 1: Navigate to Submodule

Change to submodule directory to validate:

cd submodules/cloud/coditect-cloud-service

Step 2: Run Validation Checks

Execute validation script or manual checks:

# Check symlinks

## 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 -la .coditect
ls -la .claude

# Verify CODITECT access
ls .coditect/agents/ | wc -l  # Should show 50+
ls .coditect/skills/ | wc -l  # Should show 24+
ls .coditect/commands/ | wc -l # Should show 74+

# Check templates
ls project-plan.md tasklist.md README.md .gitignore

# Check git
git remote -v
git status

Step 3: Verify Parent Integration

Check that parent repository recognizes submodule:

cd ../../..  # Return to rollout-master root

# Check .gitmodules
grep "coditect-cloud-service" .gitmodules

# Check submodule status
git submodule status | grep coditect-cloud-service

Step 4: Run Automated Validation

Use validation script for comprehensive check:

# From rollout-master root
.coditect/scripts/verify-submodules.sh submodules/cloud/coditect-cloud-service

Step 5: Review Validation Report

Review output and fix any issues found:

✅ All checks passed - submodule ready
❌ Failed checks - review errors and fix
⚠️ Warnings - optional items to address

Validation Checklist

Symlinks:

.coditect symlink exists
.coditect points to ../../../.coditect
.coditect is accessible (not broken)
.claude symlink exists
.claude points to .coditect
Can list .coditect/agents/ (50+ files)
Can list .coditect/skills/ (24+ directories)
Can list .coditect/commands/ (74+ files)

Templates:

Git Configuration:

.git directory exists
Git remote 'origin' configured
Remote URL is GitHub coditect-ai repository
Main branch exists
Can push to remote (authentication works)

Parent Integration:

Entry in parent .gitmodules
Submodule registered with git
Submodule path matches directory

Examples

See examples/ directory for:

quick-validation.sh - Fast validation check
comprehensive-validation.py - Detailed validation report
batch-validation.sh - Validate multiple submodules

Templates

See templates/ directory for:

validation-report.md - Standard validation report format
validation-checklist.txt - Printable checklist

Common Issues and Fixes

Broken symlink:

# Remove and recreate
rm .coditect
ln -s ../../../.coditect .coditect

Missing template:

# Copy from template
cp ../../../.coditect/templates/submodule/PROJECT-PLAN.template.md project-plan.md

Git remote not configured:

git remote add origin https://github.com/coditect-ai/repo-name.git

Not in .gitmodules:

# From rollout-master root
git submodule add https://github.com/coditect-ai/repo-name.git submodules/category/repo-name

Integration Points

Works with:

submodule-setup skill - Run validation after setup
submodule-health skill - Ongoing monitoring
verify-submodules.sh script - Automated validation

Used by:

submodule-orchestrator agent - Verify setup steps

Success Criteria

Validation passes when:

submodule-setup - Initial setup
submodule-health - Ongoing monitoring
submodule-configuration - Configuration management

submodule-orchestrator - Coordinates validation

Multi-Context Window Support

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

State Tracking

Checkpoint State (JSON):

{
  "validation_id": "val_20251129_150000",
  "submodule_path": "submodules/cloud/service-name",
  "phase": "validation_in_progress",
  "checks_completed": {
    "symlinks": true,
    "templates": true,
    "git_config": false,
    "parent_integration": false
  },
  "checks_passed": {
    "symlinks": 8,
    "templates": 7,
    "git_config": 0,
    "parent_integration": 0
  },
  "checks_failed": [],
  "warnings": ["README.md missing submodule purpose section"],
  "token_usage": 5200,
  "created_at": "2025-11-29T15:00:00Z"
}

Progress Notes (Markdown):

# Submodule Validation Progress - 2025-11-29

## Completed Checks
- ✅ Symlinks (8/8 passed)
  - .coditect symlink exists and functional
  - .claude symlink exists and functional
  - Can access all agents, all skills, all commands
- ✅ Templates (7/7 passed)
  - project-plan.md exists with phases
  - tasklist.md exists with checkboxes
  - README.md exists (1 warning: missing purpose)

## In Progress
- Git configuration validation
- Parent repository integration

## Next Actions
- Verify git remote configuration
- Check .gitmodules entry
- Run comprehensive validation report

Session Recovery

When starting a fresh context window after validation work:

Load Checkpoint State: Read .coditect/checkpoints/submodule-validation-latest.json
Review Progress Notes: Check submodule-validation-progress.md for status
Verify Completed Checks: Don't re-run passed validations
Resume Failed Checks: Focus on checks that failed or weren't started
Generate Report: Compile final validation report from checkpoint data

Recovery Commands:

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

# 2. Review progress
tail -20 submodule-validation-progress.md

# 3. Quick status check
cd submodules/cloud/service-name
ls -la .coditect .claude  # Verify symlinks
git remote -v             # Check git config

# 4. Check parent integration
cd ../../..
grep "service-name" .gitmodules
git submodule status | grep service-name

State Management Best Practices

Checkpoint Files (JSON Schema):

Store in .coditect/checkpoints/submodule-validation-{submodule-name}.json
Track check categories (symlinks, templates, git, parent integration)
Record pass/fail counts for each category
Include warnings and recommendations for improvement

Progress Tracking (Markdown Narrative):

Maintain submodule-validation-progress.md with check results
Document failures with specific error messages and fixes
List warnings with recommendations
Track validation score (passed / total checks)

Git Integration:

No git commits during validation (read-only operation)
Save validation report to .coditect/reports/validation-{date}.md
Create issue if critical failures found (GitHub integration)

Progress Checkpoints

Natural Breaking Points:

After symlink validation complete
After template validation complete
After git configuration validation complete
After parent integration validation complete
After comprehensive report generation

Checkpoint Creation Pattern:

# Automatic checkpoint creation after each category
if category_validation_complete:
    create_checkpoint({
        "submodule_path": submodule_path,
        "checks_completed": completed_categories,
        "checks_passed": pass_counts,
        "checks_failed": failure_list,
        "tokens": current_token_usage
    })

Example: Multi-Context Batch Validation

Context Window 1: Validate First 5 Submodules

{
  "checkpoint_id": "ckpt_batch_val_part1",
  "phase": "partial_validation",
  "submodules_validated": [
    {"path": "submodules/cloud/service-1", "status": "passed", "score": "100%"},
    {"path": "submodules/cloud/service-2", "status": "passed", "score": "95%"},
    {"path": "submodules/cloud/service-3", "status": "failed", "score": "60%"}
  ],
  "submodules_pending": [
    "submodules/dev/tool-1",
    "submodules/dev/tool-2"
  ],
  "next_action": "Fix failures in service-3, then continue",
  "token_usage": 12000
}

Context Window 2: Fix and Continue

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

# Fix identified issues
# Continue with remaining submodules
# (Context restored in 2 minutes vs 15 minutes from scratch)

{
  "checkpoint_id": "ckpt_batch_val_complete",
  "phase": "all_validated",
  "total_submodules": 5,
  "passed": 5,
  "failed": 0,
  "average_score": "98%",
  "token_usage": 8000
}

Token Savings: 12000 (first context) + 8000 (second context) = 20000 total vs. 35000 without checkpoint = 43% 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-validation

Completed:
- [x] Symlink integrity verified (.coditect, .claude)
- [x] Template files validated (project-plan.md, tasklist.md, README.md, .gitignore)
- [x] Git configuration verified (remote, branch tracking)
- [x] Parent integration confirmed (.gitmodules entry)
- [x] CODITECT framework accessibility tested

Validation Results:
- Symlink checks: X/8 passed
- Template checks: Y/7 passed
- Git config checks: Z/5 passed
- Parent integration: W/4 passed
- Overall validation score: XX%

Outputs:
- Validation report: .coditect/reports/validation-YYYY-MM-DD.md
- Checkpoint state: .coditect/checkpoints/submodule-validation-{name}.json
- Issues identified: N (P0: X, P1: Y, P2: Z)

Completion Checklist

Before marking this skill as complete, verify:

Failure Indicators

This skill has FAILED if:

❌ Broken symlinks (.coditect or .claude point to non-existent paths)
❌ Missing required templates (project-plan.md, tasklist.md, README.md)
❌ Git repository not initialized or remote not configured
❌ Submodule not registered in parent .gitmodules
❌ Cannot access CODITECT framework components (agents/, skills/, commands/)
❌ File permission errors prevent validation operations
❌ Validation script execution errors
❌ Checkpoint state corruption or write failures
❌ Parent repository not found or not a git repo
❌ Validation score below 80% with P0 issues unresolved

When NOT to Use

Do NOT use this skill when:

Initial submodule setup not yet completed (use submodule-setup first)
Creating a new submodule from scratch (setup comes before validation)
Modifying submodule configuration (use submodule-configuration instead)
Monitoring ongoing operations (use submodule-health for continuous monitoring)
Bulk operations across all submodules (use batch-submodule-validation workflow)
Submodule doesn't use CODITECT framework (validation assumes .coditect symlinks)
Parent repository is not coditect-rollout-master (different validation rules may apply)
Git submodule system not in use (use git-repository-validation instead)

Use alternatives:

Initial setup → submodule-setup skill
Configuration changes → submodule-configuration skill
Continuous monitoring → submodule-health skill
Batch operations → batch-submodule-validation workflow
Non-CODITECT repos → git-repository-validation skill

Anti-Patterns (Avoid)

Anti-Pattern	Problem	Solution
Running validation before setup complete	False failures, confusing results	Complete submodule-setup first, then validate
Not checking validation score	Miss critical failures	Review overall score, prioritize P0 issues
Ignoring symlink warnings	Broken framework access later	Fix symlink issues immediately, they cascade
Validating from wrong directory	Incorrect path resolution	Always cd to submodule directory first
Not saving validation reports	Can't track improvements	Always generate and save reports to .coditect/reports/
Running without parent repo context	Miss integration issues	Verify parent .gitmodules before marking complete
Batch validating without chunking	Context window overflow	Use batch workflow for >10 submodules
Not using checkpoints for multi-context	Restart validation from scratch	Save checkpoints after each category validation
Auto-fixing without review	May break working configurations	Review issues first, then fix deliberately
Not tracking validation history	Can't measure improvement trends	Maintain validation reports over time

Principles

This skill embodies:

#1 Recycle → Extend → Re-Use → Create - Reuses validation patterns across all submodules
#4 Separation of Concerns - Validates symlinks, templates, git, and parent integration separately
#5 Eliminate Ambiguity - Clear pass/fail criteria for each check
#6 Clear, Understandable, Explainable - Detailed validation reports with reasoning
#8 No Assumptions - Verifies every aspect of submodule configuration
#9 Quality Over Speed - Comprehensive validation prevents future issues

Full Standard: CODITECT-STANDARD-AUTOMATION.md

Core Capabilities​

1. Symlink Integrity Verification​

2. Template Verification​

3. Git Configuration Validation​

4. Framework Accessibility Testing​

Usage Pattern​

Step 1: Navigate to Submodule​

Step 2: Run Validation Checks​

Step 3: Verify Parent Integration​

Step 4: Run Automated Validation​

Step 5: Review Validation Report​

Validation Checklist​

Examples​

Templates​

Common Issues and Fixes​

Integration Points​

Success Criteria​

Related Skills​

Related Agents​

Multi-Context Window Support​

State Tracking​

Session Recovery​

State Management Best Practices​

Progress Checkpoints​

Example: Multi-Context Batch Validation​

Success Output​

Completion Checklist​

Failure Indicators​

When NOT to Use​

Anti-Patterns (Avoid)​

Principles​