Component Capability Schema

Component Capability Schema

Purpose: Enable CODITECT self-awareness through unified capability indexing across all component types.

Version: 1.1.0 Status: Implemented Last Updated: 2025-12-20 Database: context-storage/component-index.db (2.2 MB) Indexer: scripts/component-indexer.py

---

The Self-Awareness Problem

CODITECT has 1,700+ components but no unified way to answer:

• "What can handle security code review?"
• "When should I use council-orchestrator vs code-reviewer?"
• "What inputs does this component need?"
• "What have I used successfully for similar tasks?"

Self-awareness requires:

1. Capability Discovery - What can each component do?
2. Situational Matching - When should each be used?
3. Relationship Understanding - How do components work together?
4. Experience Learning - What worked before?

---

Unified Component Schema

Core Identity

component:
  # === IDENTITY ===
  id: "council-orchestrator"           # Unique identifier
  type: "agent"                         # agent | command | skill | script | hook | workflow
  name: "Council Orchestrator"          # Human-readable name
  version: "1.0.0"
  status: "operational"                 # operational | beta | deprecated | experimental

  # === LOCATION ===
  path: "agents/council-orchestrator.md"
  category: "orchestration"             # Primary category
  subcategory: "code-review"            # Optional subcategory

Capabilities (What It Does)

capabilities:
  # === PRIMARY CAPABILITIES ===
  # What this component CAN DO (verb phrases)
  primary:
    - "coordinate multi-agent code review"
    - "execute 3-stage review pipeline"
    - "generate consensus-based verdicts"
    - "produce compliance audit trails"

  # === CAPABILITY TAGS ===
  # Normalized tags for search/matching
  tags:
    - code-review
    - multi-agent
    - consensus
    - compliance
    - security
    - quality-assurance

  # === DOMAINS ===
  # What domains/areas this component serves
  domains:
    - software-development
    - quality-assurance
    - compliance
    - security

  # === ACTIONS ===
  # Verbs this component handles (for intent matching)
  actions:
    - review
    - evaluate
    - synthesize
    - coordinate
    - audit

Triggers (When To Use)

triggers:
  # === USE WHEN ===
  # Conditions that suggest using this component
  use_when:
    - "code needs multi-perspective review"
    - "compliance audit trail required"
    - "high-stakes code change"
    - "consensus-based decision needed"
    - "regulated industry (HIPAA, FDA, SOC2)"

  # === DON'T USE WHEN ===
  # Conditions that suggest NOT using this
  avoid_when:
    - "simple single-file change"
    - "quick feedback needed (use code-reviewer)"
    - "no compliance requirements"

  # === KEYWORDS ===
  # Natural language triggers
  keywords:
    - "council review"
    - "peer review"
    - "multi-agent review"
    - "compliance review"
    - "consensus"
    - "anonymous review"

  # === COMPLEXITY ===
  # What complexity level this handles
  complexity: "high"  # low | medium | high | enterprise

  # === URGENCY ===
  # Time sensitivity this handles
  urgency: "standard"  # immediate | standard | batch | scheduled

Interface (Inputs/Outputs)

interface:
  # === INPUTS ===
  inputs:
    required:
      - name: "target"
        type: "file_path | directory | glob"
        description: "Code to review"
    optional:
      - name: "reviewers"
        type: "string[]"
        default: ["security", "compliance", "performance", "testing"]
        description: "Reviewer types to include"
      - name: "threshold"
        type: "float"
        default: 0.6
        description: "Consensus threshold for approval"
      - name: "compliance"
        type: "string[]"
        description: "Compliance frameworks (hipaa, soc2, fda)"

  # === OUTPUTS ===
  outputs:
    - name: "verdict"
      type: "CouncilVerdict"
      description: "Structured review decision"
    - name: "findings"
      type: "Finding[]"
      description: "List of identified issues"
    - name: "audit_hash"
      type: "string"
      description: "Hash chain for compliance"

  # === OUTPUT FORMATS ===
  formats:
    - json
    - markdown
    - ci-status

Relationships (How It Connects)

relationships:
  # === DEPENDS ON ===
  # Components this requires
  depends_on:
    - id: "security-specialist"
      role: "reviewer"
      required: false
    - id: "compliance-checker-agent"
      role: "reviewer"
      required: false
    - id: "council-chairman"
      role: "synthesizer"
      required: true

  # === INVOKES ===
  # Components this calls
  invokes:
    - "security-specialist"
    - "compliance-checker-agent"
    - "application-performance"
    - "testing-specialist"
    - "council-chairman"

  # === INVOKED BY ===
  # What can call this component
  invoked_by:
    - "orchestrator"
    - "use-case-analyzer"
    - "/council-review command"

  # === ALTERNATIVES ===
  # Components that solve similar problems
  alternatives:
    - id: "code-reviewer"
      difference: "Single agent, faster, less thorough"
    - id: "orchestrator-code-review"
      difference: "ADR compliance focus, 40/40 scoring"

  # === COMPLEMENTS ===
  # Components that work well together
  complements:
    - id: "council-review skill"
      relationship: "Provides core patterns"
    - id: "uncertainty-orchestrator"
      relationship: "Can be used for research phases"

Quality & Maturity

quality:
  # === MATURITY ===
  maturity: "production"  # experimental | beta | production | stable

  # === CONFIDENCE ===
  # How confident are we in this component
  confidence: 0.85

  # === TEST COVERAGE ===
  test_coverage: null  # Percentage if applicable

  # === DOCUMENTATION ===
  documentation_quality: "complete"  # stub | partial | complete | comprehensive

  # === LAST VALIDATED ===
  last_validated: "2025-12-20"

  # === USAGE STATS ===
  # Populated from session history
  usage:
    invocation_count: 0
    success_rate: null
    avg_duration: null
    last_used: null

Use Cases (Situational Examples)

use_cases:
  - name: "Compliance-Critical PR Review"
    scenario: "Healthcare company reviewing patient data handling code"
    configuration:
      reviewers: ["security", "compliance"]
      compliance: ["hipaa"]
      threshold: 0.8
    expected_outcome: "Verdict with audit trail for compliance"

  - name: "High-Stakes Feature Review"
    scenario: "Payment processing code before release"
    configuration:
      reviewers: ["security", "performance", "testing"]
      threshold: 0.7
    expected_outcome: "Consensus-based approval with security focus"

  - name: "Quick Team Review"
    scenario: "Standard feature PR needing multiple perspectives"
    configuration:
      reviewers: ["security", "testing"]
      threshold: 0.6
    expected_outcome: "Balanced review with reasonable speed"

---

Schema by Component Type

Agent-Specific Extensions

agent_extensions:
  model: "sonnet"                    # Recommended model
  tools: ["Read", "Write", "Task"]   # Available tools
  auto_trigger: true                 # Part of auto-trigger framework
  token_budget: "medium"             # low | medium | high | unlimited

Command-Specific Extensions

command_extensions:
  syntax: "/council-review <target> [options]"
  aliases: ["/cr", "/council"]
  interactive: false
  background: false

Skill-Specific Extensions

skill_extensions:
  reusable: true
  composable: true                   # Can be combined with other skills
  standalone: false                  # Requires agent to execute

Workflow-Specific Extensions

workflow_extensions:
  steps: 12
  estimated_duration: "2 hours"
  parallelizable: true
  checkpoint_enabled: true
  industry: ["healthcare", "finance"]

---

Capability Index Structure

SQLite Schema (IMPLEMENTED)

Database: context-storage/component-index.db Status: Production (2025-12-20) Statistics: 522 components, 11,412 capabilities, 4,190 triggers, 3,421 relationships

-- Core component table (IMPLEMENTED)
CREATE TABLE components (
    id TEXT PRIMARY KEY,
    type TEXT NOT NULL,                    -- agent, command, skill, script, hook, workflow
    name TEXT NOT NULL,
    version TEXT,
    status TEXT DEFAULT 'operational',     -- operational, beta, deprecated, experimental
    path TEXT NOT NULL,
    category TEXT,
    subcategory TEXT,
    description TEXT,                      -- Extracted from component file
    complexity TEXT DEFAULT 'medium',      -- low, medium, high, enterprise
    maturity TEXT DEFAULT 'production',    -- experimental, beta, production, stable
    confidence REAL DEFAULT 0.5,
    documentation_quality TEXT DEFAULT 'partial',
    content_hash TEXT,                     -- SHA256 for incremental updates
    indexed_at TEXT,
    created_at TEXT DEFAULT CURRENT_TIMESTAMP,
    updated_at TEXT DEFAULT CURRENT_TIMESTAMP
);

-- Capabilities (IMPLEMENTED - 11,412 rows)
CREATE TABLE capabilities (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    component_id TEXT REFERENCES components(id) ON DELETE CASCADE,
    capability TEXT NOT NULL,
    capability_type TEXT NOT NULL          -- primary, tag, domain, action
);

-- Triggers (IMPLEMENTED - 4,190 rows)
CREATE TABLE triggers (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    component_id TEXT REFERENCES components(id) ON DELETE CASCADE,
    trigger_type TEXT NOT NULL,            -- use_when, avoid_when, keyword
    description TEXT NOT NULL
);

-- Relationships (IMPLEMENTED - 3,421 rows)
CREATE TABLE relationships (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    source_id TEXT REFERENCES components(id) ON DELETE CASCADE,
    target_id TEXT,
    relationship_type TEXT NOT NULL,       -- invokes, invoked_by, alternative, complement
    notes TEXT
);

-- Usage statistics (IMPLEMENTED - awaiting population)
CREATE TABLE usage_stats (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    component_id TEXT REFERENCES components(id) ON DELETE CASCADE,
    invocation_count INTEGER DEFAULT 0,
    success_count INTEGER DEFAULT 0,
    failure_count INTEGER DEFAULT 0,
    avg_duration_ms INTEGER,
    last_used TEXT,
    updated_at TEXT DEFAULT CURRENT_TIMESTAMP
);

-- Full-text search index (IMPLEMENTED)
CREATE VIRTUAL TABLE component_search USING fts5(
    id,
    name,
    type,
    description,       -- Component description
    capabilities,      -- Concatenated capabilities
    triggers           -- Concatenated triggers
);

-- B-Tree indexes for query performance (IMPLEMENTED)
CREATE INDEX idx_components_type ON components(type);
CREATE INDEX idx_components_category ON components(category);
CREATE INDEX idx_components_status ON components(status);
CREATE INDEX idx_capabilities_component ON capabilities(component_id);
CREATE INDEX idx_capabilities_type ON capabilities(capability_type);
CREATE INDEX idx_triggers_component ON triggers(component_id);
CREATE INDEX idx_relationships_source ON relationships(source_id);
CREATE INDEX idx_relationships_target ON relationships(target_id);

Schema Notes

Deferred for Phase 2:

• use_cases table - Will be added when use case extraction is implemented
• role and required columns in relationships - Simplified for initial implementation

---

Query Patterns for Self-Awareness

"What can handle X?"

-- Find components that can handle security code review
SELECT c.id, c.name, c.type, c.confidence
FROM component_search
JOIN components c ON component_search.id = c.id
WHERE component_search MATCH 'security AND code AND review'
ORDER BY c.confidence DESC, c.maturity DESC;

"When should I use X vs Y?"

-- Compare council-orchestrator vs code-reviewer
SELECT
    c.id,
    c.name,
    GROUP_CONCAT(CASE WHEN t.trigger_type = 'use_when' THEN t.description END) as use_when,
    GROUP_CONCAT(CASE WHEN t.trigger_type = 'avoid_when' THEN t.description END) as avoid_when
FROM components c
JOIN triggers t ON c.id = t.component_id
WHERE c.id IN ('council-orchestrator', 'code-reviewer')
GROUP BY c.id;

"What works with X?"

-- Find components that complement council-orchestrator
SELECT
    r.target_id,
    c.name,
    c.type,
    r.relationship_type,
    r.notes
FROM relationships r
JOIN components c ON r.target_id = c.id
WHERE r.source_id = 'council-orchestrator'
AND r.relationship_type IN ('invokes', 'complements');

"What worked before for similar tasks?"

-- Find most successful components for compliance review
SELECT
    c.id,
    c.name,
    u.invocation_count,
    CAST(u.success_count AS FLOAT) / u.invocation_count as success_rate
FROM components c
JOIN usage_stats u ON c.id = u.component_id
JOIN capabilities cap ON c.id = cap.component_id
WHERE cap.capability LIKE '%compliance%'
AND u.invocation_count > 5
ORDER BY success_rate DESC, u.invocation_count DESC;

---

Self-Reflection Patterns

Pattern 1: Task Decomposition

User: "I need to review this PR for a healthcare app"

CODITECT Self-Reflection:
1. Parse intent: review + healthcare → compliance-critical review
2. Query capabilities: "review AND (healthcare OR hipaa OR compliance)"
3. Results:
   - council-orchestrator (confidence: 0.85, triggers: compliance, multi-perspective)
   - compliance-checker-agent (confidence: 0.80, triggers: hipaa)
   - code-reviewer (confidence: 0.70, but avoid_when: compliance required)
4. Decision: Use council-orchestrator with compliance-checker-agent as reviewer

Pattern 2: Alternative Selection

User: "Review this quickly, don't need full audit"

CODITECT Self-Reflection:
1. Parse constraints: quick, no audit → speed over thoroughness
2. Query: capabilities="review" AND avoid_when NOT MATCH "quick"
3. Compare alternatives:
   - council-orchestrator: avoid_when="quick feedback needed"
   - code-reviewer: use_when="quick feedback", complexity="low"
4. Decision: Use code-reviewer (better fit for constraints)

Pattern 3: Experience Learning

User: "Deploy this to GCP"

CODITECT Self-Reflection:
1. Query capabilities: "deploy AND gcp"
2. Results: devops-engineer, cloud-architect, google-cloud-build skill
3. Query usage_stats: What worked before?
   - devops-engineer: 45 invocations, 89% success
   - cloud-architect: 12 invocations, 75% success
4. Query session history (/cxq): Any past GCP deployment patterns?
5. Decision: Use devops-engineer (highest success rate) with google-cloud-build skill

---

Implementation Plan

Phase 1: Schema & Indexer (Week 1)

• Finalize schema specification
• Create component indexer script
• Extract capabilities from existing component files
• Build SQLite database with FTS5

Phase 2: Query Interface (Week 2)

• Add component search to /cxq or create /discover
• Implement natural language → SQL translation
• Build comparison queries

Phase 3: Self-Reflection Integration (Week 3)

• Update use-case-analyzer to query capability index
• Add usage tracking to capture success/failure
• Integrate with orchestrators for automatic discovery

Phase 4: Learning Loop (Week 4)

• Track component invocations from session history
• Update success rates automatically
• Surface recommendations based on experience

---

Example: Council Components in New Schema

# council-orchestrator capability record
component:
  id: "council-orchestrator"
  type: "agent"
  name: "Council Orchestrator"
  version: "1.0.0"
  status: "operational"
  path: "agents/council-orchestrator.md"
  category: "orchestration"
  subcategory: "code-review"

capabilities:
  primary:
    - "coordinate multi-agent code review"
    - "execute 3-stage review pipeline"
    - "generate consensus-based verdicts"
  tags: [code-review, multi-agent, consensus, compliance, security]
  domains: [software-development, quality-assurance, compliance]
  actions: [review, evaluate, synthesize, coordinate]

triggers:
  use_when:
    - "code needs multi-perspective review"
    - "compliance audit trail required"
    - "regulated industry (HIPAA, FDA, SOC2)"
  avoid_when:
    - "simple single-file change"
    - "quick feedback needed"
  keywords: ["council review", "peer review", "consensus", "compliance review"]
  complexity: "high"

interface:
  inputs:
    required: [{name: "target", type: "file_path"}]
    optional: [{name: "reviewers", type: "string[]"}, {name: "threshold", type: "float"}]
  outputs:
    - {name: "verdict", type: "CouncilVerdict"}
    - {name: "audit_hash", type: "string"}

relationships:
  invokes: ["security-specialist", "council-chairman"]
  alternatives:
    - {id: "code-reviewer", difference: "Single agent, faster"}
    - {id: "orchestrator-code-review", difference: "ADR compliance focus"}

quality:
  maturity: "production"
  confidence: 0.85
  documentation_quality: "complete"

---

This schema enables CODITECT to be truly self-aware:

• Know what it can do (capabilities)
• Know when to do it (triggers)
• Know what works together (relationships)
• Learn from experience (usage stats)

---

Implementation Status

Status: Phase 1 Complete (2025-12-20)

Milestone	Status
Schema design	Complete
Component indexer	Complete
Database populated	Complete (522 components)
/discover command	Pending
Usage tracking	Pending

Related Documentation

• ADR-010-component-capability-schema.md - Architecture decision
• ADR-011-self-awareness-framework.md - Self-awareness patterns
• DATABASE-ARCHITECTURE-UNIFIED.md - Database architecture
• scripts/component-indexer.py - Indexer implementation

---

Last Updated: 2025-12-20 Author: CODITECT Core Team