Skip to main content

Component Activation System Guide

For AI Agents and Users: Complete guide to managing component activation in the CODITECT framework with CLI tools and workflows.

Date: December 22, 2025 Status: Production System CLI Tool: scripts/update-component-activation.py Tracking File: .coditect/component-activation-status.json

Table of Contents​

  1. Overview
  2. CLI Commands
  3. Activation File Location
  4. Git Workflow
  5. Activation Philosophy
  6. Component States
  7. Best Practices
  8. Troubleshooting

Overview​

The Component Activation System provides explicit control over which CODITECT components are loaded and available in Claude Code sessions. This manual activation design prevents namespace pollution, improves startup performance, and provides security through human review.

Key Concepts:

  • Total components tracked in config/component-counts.json (agents, commands, skills, scripts, prompts, hooks)
  • Activated subset by default (critical framework components) - see config/component-activation-status.json
  • Remaining available on-demand (activate as needed)
  • Manual activation required (intentional design, not limitation)
  • Git-tracked activation state (audit trail + version control)

CLI for Managing Component Activation​

Activate a Component​

python3 scripts/update-component-activation.py activate agent orchestrator \
  --reason "Needed for project planning"

Deactivate a Component​

python3 scripts/update-component-activation.py deactivate skill old-skill \
  --reason "Deprecated"

Check Component Status​

python3 scripts/update-component-activation.py status agent codi-documentation-writer

List Activated Components​

python3 scripts/update-component-activation.py list --activated-only

List by Type​

# List all agents
python3 scripts/update-component-activation.py list --type agent

# List all commands
python3 scripts/update-component-activation.py list --type command

# List all skills
python3 scripts/update-component-activation.py list --type skill

List All Components​

python3 scripts/update-component-activation.py list

Activation File Location​

File: .coditect/component-activation-status.json

Format:

{
  "agents": [
    {
      "name": "orchestrator",
      "activated": true,
      "reason": "Needed for project planning",
      "date": "2025-12-04T10:30:00Z"
    },
    {
      "name": "session-analysis-agent",
      "activated": false,
      "reason": "Not yet needed",
      "date": "2025-12-04T10:30:00Z"
    }
  ],
  "commands": [...],
  "skills": [...],
  "scripts": [...],
  "prompts": [...],
  "hooks": [...]
}

Key Points:

  • Atomic JSON updates (prevents corruption)
  • Git-tracked (version control + audit trail)
  • Human-readable format
  • Timestamped changes
  • Reason field for documentation

Git Workflow​

Always commit activation changes with descriptive messages:

# After activating/deactivating components
git add .coditect/component-activation-status.json
git commit -m "chore: Activate [component] for [purpose]"
git push

Example commit messages:

git commit -m "chore: Activate session-analysis-agent for session tracking"
git commit -m "chore: Activate jsonl-session-processor for large session processing"
git commit -m "chore: Deactivate deprecated-component (superseded by new-component)"

Activation Philosophy​

Why Manual Activation?​

Explicit Control:

  • Prevents accidental activation of work-in-progress components
  • Human review before production use
  • Clear decision point for activation

Audit Trail:

  • Git history shows what was activated when
  • Reason field documents why
  • Easy rollback if needed

Security:

  • Prevents unauthorized component introduction
  • Validation step before components become active
  • Clear approval workflow

Performance:

  • Lean activation improves session startup speed (loads 11 vs. all components)
  • Only activated components consume memory
  • Faster initialization

Namespace Cleanliness:

  • Only activated components appear in agent lists
  • Reduces cognitive load (fewer choices)
  • Clear separation: available vs. active

Activate What You Need, When You Need It​

Recommended approach:

  1. Start with minimal activation (11 critical components)
  2. Activate additional components as needed
  3. Document activation reason clearly
  4. Review activation status periodically
  5. Deactivate components no longer needed

Component States​

Components can be in three states:

1. Activated (11 components)​

  • Loaded on session start
  • Immediately available for use
  • Listed in agent catalogs
  • Consume memory during session
  • Tracked in git history

2. Available (all components)​

  • Present in repository
  • Not loaded on session start
  • Require activation before use
  • Zero memory consumption
  • Can be activated anytime

3. Not Tracked (rare)​

  • Component exists in repository
  • Not in activation status JSON
  • Needs to be added to tracking
  • Usually new components not yet registered

Best Practices​

For AI Agents​

DO:

  • Check activation status before using components
  • Provide clear activation commands for humans
  • Explain why activation is needed
  • Offer alternative approaches (e.g., scripts don't require activation)
  • Verify activation worked before proceeding

DON'T:

  • Assume components are activated
  • Modify activation JSON directly
  • Skip activation status check
  • Proceed without human approval
  • Create duplicate components without checking existing

For Human Users​

DO:

  • Review activation requests from AI agents
  • Provide meaningful activation reasons
  • Commit activation changes immediately
  • Review activated components periodically
  • Deactivate unused components

DON'T:

  • Activate all components at once
  • Skip commit messages
  • Edit activation JSON manually (use CLI)
  • Activate untested components
  • Ignore activation requests

Troubleshooting​

Component Not Loading After Activation​

Symptoms:

  • Component activated in JSON
  • Not available in Claude Code session

Solutions:

  1. Verify JSON syntax: Check for malformed JSON
  2. Restart session: ./scripts/init.sh or restart Claude Code
  3. Check component file: Verify component file exists
  4. Review logs: Check session startup logs for errors

Activation JSON Corrupted​

Symptoms:

  • JSON parse errors
  • Components not loading
  • CLI tool fails

Solutions:

  1. Restore from git: git restore .coditect/component-activation-status.json
  2. Use last known good version: Check git history
  3. Rebuild from scratch: Use CLI to re-activate components

Component Activated But Not Working​

Symptoms:

  • Component shows as activated
  • Invocation fails or errors

Solutions:

  1. Check dependencies: Verify all required components activated
  2. Test component: Run minimal test invocation
  3. Review documentation: Check component's SKILL.md or agent definition
  4. Check logs: Review error messages

Too Many Activated Components (Performance Issues)​

Symptoms:

  • Slow session startup
  • High memory usage
  • Sluggish performance

Solutions:

  1. Review activation list: Deactivate unused components
  2. Identify culprits: Which components consume most resources?
  3. Optimize workflow: Use scripts instead of agents when possible
  4. Lean activation: Only activate what's actively used

Quick Reference​

Common Tasks​

# Activate component for specific project
python3 scripts/update-component-activation.py activate agent project-organizer \
  --reason "Project restructuring for client X"

# Deactivate after project complete
python3 scripts/update-component-activation.py deactivate agent project-organizer \
  --reason "Project X complete"

# Check what's activated
python3 scripts/update-component-activation.py list --activated-only

# Find component to activate
python3 scripts/update-component-activation.py list | grep session

# Commit activation changes
git add .coditect/component-activation-status.json
git commit -m "chore: Activate components for session tracking"
git push

Activation Request Template (for AI Agents)​

🚨 COMPONENT ACTIVATION REQUIRED

Component: [type]/[name].md
Purpose: [Brief description of what component does]
Current Status: NOT ACTIVATED

Activation needed because:
- [Reason 1]
- [Reason 2]
- [Reason 3]

To activate, please run:
```bash
cd /Users/halcasteel/PROJECTS/coditect-rollout-master/submodules/core/coditect-core
python3 scripts/update-component-activation.py activate [type] [name] \
  --reason "[Your reason]"
git add .coditect/component-activation-status.json
git commit -m "chore: Activate [name] for [purpose]"
git push

Alternative approach (if activation not desired): [Describe alternative using scripts or existing components]

Estimated activation time: 2 minutes Impact: [Describe what becomes possible after activation]


---

**Last Updated:** December 4, 2025
**Author:** AI Agent (Claude Sonnet 4.5)
**Related Guides:** [Memory Management](MEMORY-MANAGEMENT-GUIDE.md), [Git Workflow](GIT-WORKFLOW-AUTOMATION-GUIDE.md), [User Best Practices](USER-BEST-PRACTICES.md)