ADR-049: Component Creation Lifecycle

Status

Accepted - January 3, 2026

Context

CODITECT has 3,458 framework components across multiple types:

Type	Count	Location
Agents	776	agents/*.md
Commands	377	commands/*.md
Skills	445	skills/*/SKILL.md
Scripts	581	scripts/**/*.py, *.sh
Hooks	118	hooks/*.md
Workflows	1,153	workflows/**/*.yaml

Problems Identified

1. No standardized creation process - Components created ad-hoc with inconsistent metadata
2. Missing registration - Components exist on disk but not in registries
3. Incomplete activation - Components not appearing in component-activation-status.json
4. Missing classification - No MoE frontmatter for AI-assisted discovery
5. Inconsistent templates - Each component type had different structures

Requirements

• Single command to create any component type
• Automatic template generation with proper frontmatter
• Automatic inventory update (component-counts.json)
• Framework registration (SQLite, framework-registry.json)
• Activation status update
• MoE classification for discoverability

Decision

Implement a Component Creation Lifecycle with a dedicated command (/component-create) and script (scripts/component-create.sh) that executes a 5-step standardized process.

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                  COMPONENT CREATION LIFECYCLE                    │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│   USER INPUT                                                     │
│       │                                                          │
│       ▼                                                          │
│   ┌──────────────────┐                                          │
│   │  /component-create│                                          │
│   │  --type agent     │                                          │
│   │  --name my-agent  │                                          │
│   └────────┬─────────┘                                          │
│            │                                                     │
│            ▼                                                     │
│   ┌──────────────────────────────────────────────────────────┐  │
│   │                    5-STEP PROCESS                         │  │
│   ├──────────────────────────────────────────────────────────┤  │
│   │                                                           │  │
│   │  Step 1: CREATE FROM TEMPLATE                             │  │
│   │     └─→ Generate component file with frontmatter         │  │
│   │                                                           │  │
│   │  Step 2: UPDATE INVENTORY                                 │  │
│   │     └─→ python3 update-component-counts.py               │  │
│   │     └─→ config/component-counts.json                     │  │
│   │                                                           │  │
│   │  Step 3: REGISTER IN FRAMEWORK                            │  │
│   │     └─→ python3 ensure_component_registered.py           │  │
│   │     └─→ SQLite platform.db (ADR-118 Tier 1)              │  │
│   │     └─→ config/framework-registry.json                   │  │
│   │     └─→ config/component-activation-status.json          │  │
│   │                                                           │  │
│   │  Step 4: ACTIVATE COMPONENT                               │  │
│   │     └─→ Set status: 'active'                             │  │
│   │                                                           │  │
│   │  Step 5: CLASSIFY WITH MoE                                │  │
│   │     └─→ python3 moe_classifier/classify.py               │  │
│   │     └─→ Add moe_confidence, moe_classified               │  │
│   │                                                           │  │
│   └──────────────────────────────────────────────────────────┘  │
│            │                                                     │
│            ▼                                                     │
│   ┌──────────────────┐                                          │
│   │  Component Ready  │                                          │
│   │  for Use          │                                          │
│   └──────────────────┘                                          │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Component Types and Templates

Type	Directory	File Pattern	Template Source
agent	agents/	{name}.md	create_agent_template()
skill	skills/{name}/	SKILL.md	create_skill_template()
command	commands/	{name}.md	create_command_template()
hook	hooks/	{name}.md	create_hook_template()
script	scripts/	{name}.py or .sh	create_script_template()
workflow	workflows/	{name}.yaml	create_workflow_template()

Usage

# Interactive mode
/component-create

# With arguments
/component-create agent my-agent --summary "Analyzes data"

# Non-interactive
./scripts/component-create.sh \
  --type skill \
  --name api-testing \
  --summary "API testing patterns" \
  --non-interactive

Storage Integration (ADR-118 Compliant)

Component registration uses platform.db (Tier 1):

# Register in platform.db (Tier 1 - regenerable)
from scripts.core.paths import get_platform_db_path

def register_component(component_type: str, name: str, path: str, metadata: dict):
    """Register component in platform.db."""
    conn = sqlite3.connect(get_platform_db_path())
    conn.execute("""
        INSERT OR REPLACE INTO components
        (type, name, path, description, version, status, created_at, updated_at)
        VALUES (?, ?, ?, ?, ?, 'active', datetime('now'), datetime('now'))
    """, (component_type, name, path, metadata.get('description'), metadata.get('version')))
    conn.commit()

Template Examples

Agent Template Structure

---
title: My Agent
component_type: agent
version: 1.0.0
status: active
summary: Agent description
invocation_pattern: /agent my-agent '<task>'
model: sonnet
tools: Read, Write, Edit, Grep, Glob
---
# My Agent

Description and instructions...

Skill Template Structure

---
title: My Skill
component_type: skill
version: 1.0.0
status: active
summary: Skill description
---
# My Skill

## When to Use
...

## Steps
...

Command Template Structure

---
title: My Command
component_type: command
invocation: /my-command
---
# /my-command

System prompt and usage...

Post-Creation Workflow

After creating a component:

1. Edit the component - Customize the generated template

   code agents/my-agent.md

2. Test the component

   # For agents
   /agent my-agent "test task"
   
   # For commands
   /my-command
   
   # For scripts
   python3 scripts/my-script.py --help

3. Verify registration

   # Check component counts
   cat config/component-counts.json
   
   # Search for component
   /which my-agent

Consequences

Positive

1. Consistency - All components follow the same structure and metadata
2. Discoverability - Components immediately available via /which, search, MoE
3. Complete registration - No orphaned components on disk
4. Reduced errors - Templates prevent common mistakes
5. Audit trail - Created date, version tracked from start

Negative

1. Template maintenance - Templates must be updated when standards change
2. Script dependency - Requires Python 3.10+ for registration scripts
3. Additional step - More process than simply creating a file

Neutral

1. Learning curve - Contributors must learn the command
2. Validation overhead - Name validation enforces kebab-case

Related Documents

• ADR-013: Agent Skills Framework Adoption
• ADR-046: Continual Learning System
• ADR-118: Four-Tier Database Architecture
• Component Reference

---

Author: CODITECT Team Approved: January 3, 2026 Migration: Migrated from cloud-infra per ADR-150 on 2026-02-03