When to Use This Skill

✅ Use when:

• Updating project templates (project-plan.md, tasklist.md)
• Synchronizing configuration changes across multiple submodules
• Applying new CODITECT standards to existing submodules
• Managing environment-specific configurations (dev, staging, prod)
• Updating repository settings or metadata

❌ Don't use when:

• Initial submodule setup (use submodule-setup)
• Verifying configuration (use submodule-validation)
• Monitoring health (use submodule-health)
• Making code changes (use development workflow)

Core Capabilities

1. Template Update Management

Updates project templates while preserving customizations:

• Update project-plan.md structure while keeping content
• Refresh tasklist.md format while preserving task status
• Update README.md sections while keeping custom content
• Merge template changes with existing files
• Track template versions and changes

2. Configuration Synchronization

Keeps configuration consistent across submodules:

• Apply standard .gitignore updates to all submodules
• Synchronize CI/CD configurations (.github/workflows)
• Update common scripts and tools
• Propagate security updates
• Maintain version consistency

3. Environment Configuration

Manages environment-specific settings:

• Development environment configurations
• Staging environment settings
• Production configurations
• Environment variable templates
• Secret management integration

4. Metadata Management

Updates repository and project metadata:

• Repository descriptions and topics
• License files and copyright notices
• Contributing guidelines
• Code of conduct
• Issue and PR templates

Usage Pattern

Step 1: Identify Configuration Change Needed

Determine what configuration needs updating:

• Template format changes
• New CODITECT standards
• Security updates
• Environment changes
• Metadata updates

Step 2: Test Configuration Change

Test the change on a single submodule first:

# Navigate to test submodule

## 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

cd submodules/labs/test-project

# Apply configuration change
# (specific commands depend on what's being updated)

# Verify change works
git diff
git status

Step 3: Apply to Multiple Submodules

Once tested, apply to all relevant submodules:

# Use batch script
.coditect/scripts/update-submodule-config.py \
  --config-type gitignore \
  --categories cloud,dev,gtm

Step 4: Verify Changes

Verify configuration applied correctly:

# Check each submodule
for dir in submodules/cloud/*; do
  echo "Checking $dir..."
  cd "$dir"
  git diff .gitignore
  cd ../../..
done

Step 5: Commit and Push

Commit configuration changes:

# From each submodule
git add .gitignore
git commit -m "Update .gitignore with CODITECT standards"
git push

# Update parent repository references
cd ../../..
git add submodules/
git commit -m "Update submodule references: configuration sync"
git push

Configuration Types

Template Configurations

• project-plan.md - Project plan structure
• tasklist.md - Task list format
• README.md - Documentation structure
• .gitignore - Exclusion patterns

CI/CD Configurations

• .github/workflows/*.yml - GitHub Actions
• .github/dependabot.yml - Dependency updates
• .github/CODEOWNERS - Code ownership

Development Configurations

• .vscode/settings.json - VSCode settings
• .editorconfig - Editor configurations
• pyrightconfig.json - Python type checking
• tsconfig.json - TypeScript configuration

Environment Configurations

• .env.template - Environment variable template
• config/development.yml - Dev environment
• config/staging.yml - Staging environment
• config/production.yml - Prod environment

Examples

See examples/ directory for:

• update-gitignore.sh - Update .gitignore across submodules
• sync-ci-config.py - Synchronize CI/CD configurations
• update-templates.sh - Refresh project templates

Templates

See templates/ directory for:

• Standard configuration files for each type
• Migration guides for version updates
• Rollback procedures

Integration Points

Works with:

• submodule-validation skill - Verify configuration changes
• batch-setup.py script - Apply to multiple submodules
• Version control - Track configuration history

Used by:

• submodule-orchestrator agent - Coordinate updates
• DevOps automation - Configuration management

Success Criteria

Configuration update complete when:

• Change tested on single submodule
• Applied to all relevant submodules
• Validation checks pass
• Changes committed and pushed
• Parent repository updated
• Documentation updated

Best Practices

Before Making Changes:

• Test on single submodule first
• Back up existing configurations
• Document what's changing and why
• Plan rollback procedure

During Changes:

• Apply incrementally (one category at a time)
• Verify each batch before proceeding
• Monitor for errors or issues
• Keep change log

After Changes:

• Run validation checks
• Update documentation
• Notify team of changes
• Monitor for issues

Common Scenarios

Update .gitignore

# Copy new .gitignore template
cp .coditect/templates/submodule/.gitignore.template .gitignore

# Merge with existing exclusions
# Review and commit

Sync CI/CD Workflows

# Copy workflow from template
cp .coditect/templates/github-workflows/ci.yml .github/workflows/

# Customize for submodule
# Test workflow
# Commit and push

Update Environment Config

# Update environment template
cp config/development.template.yml config/development.yml

# Fill in environment-specific values
# Validate configuration
# Deploy to environment

Related Skills

• submodule-setup - Initial setup
• submodule-validation - Verify changes
• submodule-health - Monitor after changes

Related Agents

• submodule-orchestrator - Coordinate configuration updates

---

Multi-Context Window Support

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

State Tracking

Checkpoint State (JSON):

{
  "config_update_id": "config_20251129_150000",
  "update_type": "gitignore_sync",
  "phase": "testing_complete",
  "test_submodule": "submodules/labs/test-project",
  "test_successful": true,
  "submodules_updated": [
    "submodules/cloud/service-1",
    "submodules/cloud/service-2"
  ],
  "submodules_pending": [
    "submodules/dev/tool-1",
    "submodules/dev/tool-2",
    "submodules/gtm/crm"
  ],
  "changes_committed": false,
  "token_usage": 6800,
  "created_at": "2025-11-29T15:00:00Z"
}

Progress Notes (Markdown):

# Configuration Update Progress - 2025-11-29

## Completed
- Tested .gitignore update on labs/test-project ✅
- Applied to cloud/service-1 ✅
- Applied to cloud/service-2 ✅
- Verified changes with git diff

## In Progress
- dev category (0/2 complete)
- gtm category (0/1 complete)

## Next Actions
- Apply to dev/tool-1, dev/tool-2
- Apply to gtm/crm
- Commit changes in each submodule
- Update parent repository pointers

Session Recovery

When starting a fresh context window after configuration updates:

1. Load Checkpoint State: Read .coditect/checkpoints/submodule-config-latest.json
2. Review Progress Notes: Check submodule-config-progress.md for update status
3. Verify Completed Updates: Check git diff in updated submodules
4. Resume Pending Updates: Continue with submodules not yet updated
5. Commit Changes: Finalize all updates with git commits

Recovery Commands:

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

# 2. Review progress
tail -25 submodule-config-progress.md

# 3. Verify completed updates
for sub in $(cat .coditect/checkpoints/submodule-config-latest.json | jq -r '.submodules_updated[]'); do
  echo "=== $sub ==="
  cd $sub
  git diff .gitignore
  cd ../../..
done

# 4. Check pending submodules
ls -la submodules/dev/

State Management Best Practices

Checkpoint Files (JSON Schema):

• Store in .coditect/checkpoints/submodule-config-{update-type}.json
• Track test results from single submodule before batch application
• Record updated vs pending submodules for resumability
• Include commit status to prevent duplicate commits

Progress Tracking (Markdown Narrative):

• Maintain submodule-config-progress.md with update results
• Document configuration changes applied
• Note any customizations or variations per submodule
• List commit messages for each submodule

Git Integration:

• Test configuration change on single submodule first
• Commit incrementally (per submodule or per category)
• Update parent repository after all submodule commits
• Tag batch updates: git tag config-sync-{type}-{date}

Progress Checkpoints

Natural Breaking Points:

1. After test submodule update successful
2. After each category completed (cloud, dev, gtm, etc.)
3. After all submodules updated
4. After all submodule commits pushed
5. After parent repository updated

Checkpoint Creation Pattern:

# Automatic checkpoint creation after each category or 5 submodules
if category_complete or len(submodules_updated) % 5 == 0:
    create_checkpoint({
        "update_type": config_type,
        "phase": current_phase,
        "submodules_updated": updated_list,
        "submodules_pending": pending_list,
        "tokens": current_token_usage
    })

Example: Multi-Context Configuration Sync

Context Window 1: Test + First 10 Submodules

{
  "checkpoint_id": "ckpt_config_sync_part1",
  "update_type": "ci_workflow_sync",
  "phase": "partial_update",
  "test_successful": true,
  "submodules_updated": 10,
  "submodules_pending": 31,
  "categories_completed": ["cloud"],
  "next_action": "Continue with dev, gtm, labs categories",
  "token_usage": 12000
}

Context Window 2: Remaining Submodules + Commits

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

# Continue with pending updates
# (Context restored in 2 minutes vs 18 minutes from scratch)

{
  "checkpoint_id": "ckpt_config_sync_complete",
  "phase": "all_committed",
  "total_submodules_updated": 41,
  "all_changes_committed": true,
  "parent_updated": true,
  "token_usage": 16000
}

Token Savings: 12000 (first context) + 16000 (second context) = 28000 total vs. 50000 without checkpoint = 44% 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-configuration

Completed:
- [x] Configuration change tested on single submodule
- [x] Applied to all relevant submodules (X total)
- [x] Validation checks passed
- [x] Changes committed in each submodule
- [x] Parent repository updated with new references
- [x] Documentation updated

Configuration Updated:
- Type: [gitignore/ci-config/templates/environment/metadata]
- Submodules affected: X
- Categories: [cloud, dev, gtm, labs, etc.]
- Validation: All checks passed

Outputs:
- Updated configuration files in each submodule
- Git commits with clear messages
- Parent repository submodule reference updates

Completion Checklist

Before marking this skill as complete, verify:

• Configuration change need identified and documented
• Change tested on single test submodule first
• Test validation passed (no errors)
• Backup of existing configurations taken
• Applied to all relevant submodules (batch script or manual)
• Each submodule verified individually (git diff)
• Configuration matches expected template
• Validation checks run successfully
• Changes committed in each submodule with clear messages
• Changes pushed to remote for each submodule
• Parent repository submodule references updated
• Parent repository committed and pushed
• Documentation updated (if applicable)
• Team notified of configuration changes

Failure Indicators

This skill has FAILED if:

• ❌ Test submodule validation failed (configuration broken)
• ❌ Configuration applied inconsistently across submodules
• ❌ Validation checks fail after applying changes
• ❌ Changes committed but not pushed (incomplete sync)
• ❌ Parent repository not updated (references stale)
• ❌ Existing customizations overwritten (data loss)
• ❌ CI/CD pipelines broken after config update
• ❌ Environment-specific values hardcoded (security risk)
• ❌ No rollback plan (cannot undo changes)
• ❌ Changes applied without testing first

When NOT to Use

Do NOT use submodule-configuration when:

• Initial submodule setup - Use submodule-setup skill instead
• Verifying configuration - Use submodule-validation skill
• Health monitoring - Use submodule-health skill
• Code changes - Use standard development workflow
• Single submodule update - Manual update more efficient
• Breaking changes - Requires human approval and careful planning
• Production secrets - Use secure secret management tools
• Major version updates - Requires comprehensive testing

Use submodule-setup when: Creating new submodules Use submodule-validation when: Checking configuration correctness Use this skill when: Synchronizing configuration across multiple submodules

Anti-Patterns (Avoid)

Anti-Pattern	Problem	Solution
Skip test submodule	Break all submodules at once	Always test on single submodule first
No backup	Cannot rollback broken changes	Backup existing configs before updating
Overwrite customizations	Lose submodule-specific settings	Merge templates, don't replace entirely
No validation	Broken configs deployed	Run validation checks after each update
Batch without verification	Propagate errors to all submodules	Verify each batch before proceeding
Forget parent update	Submodule references stale	Always update parent repository after changes
Hardcode secrets	Security vulnerability	Use environment variable templates
No change log	Cannot track what changed when	Document all changes with clear messages
Apply to wrong category	Inappropriate config for submodule type	Filter by category before applying
No rollback plan	Stuck with broken configuration	Document rollback procedure before changes

Principles

This skill embodies the following CODITECT principles:

#1 Recycle → Extend → Re-Use → Create:

• Reuse standard configuration templates across submodules
• Extend templates for submodule-specific needs
• Don't create new configs from scratch each time

#4 Measure and Verify:

• Test on single submodule before batch application
• Verify each batch of updates
• Validate final state matches expectations

#5 Eliminate Ambiguity:

• Clear configuration types (gitignore, CI/CD, templates, etc.)
• Explicit category filtering (cloud, dev, gtm)
• Document what changed and why

#8 No Assumptions:

• Never assume configuration will work (test it)
• Verify validation checks before trusting configuration
• Confirm parent repository updated (don't assume)

#10 Automation First:

• Use batch scripts for multi-submodule updates
• Automated validation checks
• Scripted rollback procedures

Full Standard: CODITECT-STANDARD-AUTOMATION.md