Skills Agents Inventory System Design Document

assetactive

Skills Agents Inventory System Design Document

Source: skills-agents-inventory-system-design-document.md (ingested 2026-03-28)

Design Document: Skills & Agents Inventory System

Overview

The Skills & Agents Inventory System is a TypeScript-based solution that discovers, indexes, and serves metadata about skills, agents, and CLI tools across a workspace. The system consists of three main components:

  1. Discovery Engine: Scans the workspace filesystem to identify components
  2. Inventory Service: REST API that serves inventory queries
  3. CLI Integration: Commands for Kiro CLI to interact with the inventory

The system uses a file-based persistence layer (SQLite) for efficient querying and supports cross-platform path resolution for Windows/WSL/Linux environments.

Architecture

System Components

graph TB
    subgraph "Kiro CLI"
        CLI[CLI Commands]
        Cache[Local Cache]
    end
    
    subgraph "Inventory System"
        Discovery[Discovery Engine]
        Indexer[Metadata Indexer]
        DB[(SQLite Database)]
        API[REST API Service]
    end
    
    subgraph "Workspace"
        FS[File System]
        Components[Skills/Agents/CLIs]
    end
    
    FS --> Discovery
    Components --> Discovery
    Discovery --> Indexer
    Indexer --> DB
    DB --> API
    API --> CLI
    CLI --> Cache
    Cache -.fallback.-> CLI

Technology Stack

  • Language: TypeScript (Node.js runtime)
  • Database: SQLite with better-sqlite3 driver
  • API Framework: Fastify (high performance, TypeScript-first)
  • CLI Framework: Commander.js
  • Testing: Jest with ts-jest
  • Path Resolution: Custom cross-platform path normalizer

Components and Interfaces

1. Path Resolver

Handles cross-platform path normalization between Windows, WSL, and Linux.

interface PathResolver {
  normalize(path: string): string;
  toWindows(path: string): string;
  toLinux(path: string): string;
  toWSL(path: string): string;
  isWindows(path: string): boolean;
  isLinux(path: string): boolean;
  isWSL(path: string): boolean;
}

Key Operations:

  • Detect path format from pattern matching
  • Convert between formats using bidirectional mapping
  • Maintain canonical format internally (Linux-style)
  • Return format appropriate for requesting environment

2. Discovery Engine

Scans workspace filesystem to identify components.

interface DiscoveryEngine {
  scan(rootPath: string, options: ScanOptions): Promise<Component[]>;
  scanIncremental(rootPath: string, since: Date): Promise<Component[]>;
}

interface ScanOptions {
  maxDepth: number;
  followSymlinks: boolean;
  excludePatterns: string[];
  includePatterns: string[];
}

interface Component {
  id: string;
  type: 'skill' | 'agent' | 'cli';
  name: string;
  path: string;
  relativePath: string;
  metadata: ComponentMetadata;
  discoveredAt: Date;
  lastModified: Date;
}

Discovery Strategy:

  1. Traverse directory tree recursively
  2. Identify component markers (package.json, agent config, CLI entry points)
  3. Extract metadata from each discovered component
  4. Handle errors gracefully (log and continue)
  5. Return complete component list

3. Metadata Extractors

Extract rich metadata from different component types.

interface MetadataExtractor {
  canExtract(path: string): boolean;
  extract(path: string): Promise<ComponentMetadata>;
}

interface ComponentMetadata {
  name: string;
  version?: string;
  description?: string;
  summary?: string;
  language?: string;
  capabilities?: string[];
  commands?: CommandInfo[];
  dependencies?: Record<string, string>;
  customFields?: Record<string, any>;
}

interface CommandInfo {
  name: string;
  description: string;
  arguments?: ArgumentInfo[];
}

Extractor Types:

  • PackageJsonExtractor: Extracts from package.json files
  • ReadmeExtractor: Extracts summary from README.md
  • AgentConfigExtractor: Extracts agent-specific metadata
  • CLIExtractor: Extracts CLI commands and descriptions

4. Inventory Database

Persists and queries component inventory using SQLite.

interface InventoryDatabase {
  initialize(): Promise<void>;
  insert(component: Component): Promise<void>;
  update(component: Component): Promise<void>;
  markInactive(componentId: string): Promise<void>;
  query(criteria: QueryCriteria): Promise<Component[]>;
  getById(id: string): Promise<Component | null>;
  getAll(): Promise<Component[]>;
}

interface QueryCriteria {
  name?: string;
  type?: ComponentType[];
  language?: string;
  keywords?: string[];
  fuzzyMatch?: boolean;
  limit?: number;
  offset?: number;
}

Schema:

CREATE TABLE components (
  id TEXT PRIMARY KEY,
  type TEXT NOT NULL,
  name TEXT NOT NULL,
  path TEXT NOT NULL,
  relative_path TEXT NOT NULL,
  metadata TEXT NOT NULL, -- JSON
  discovered_at TEXT NOT NULL,
  last_modified TEXT NOT NULL,
  is_active INTEGER DEFAULT 1
);

CREATE INDEX idx_name ON components(name);
CREATE INDEX idx_type ON components(type);
CREATE INDEX idx_active ON components(is_active);
CREATE VIRTUAL TABLE components_fts USING fts5(name, description, content=components);

5. REST API Service

Exposes inventory through HTTP endpoints.

interface InventoryService {
  start(port: number): Promise<void>;
  stop(): Promise<void>;
}

// API Endpoints
GET  /api/v1/components          // List all components
GET  /api/v1/components/:id      // Get component by ID
POST /api/v1/components/search   // Search components
POST /api/v1/refresh             // Trigger inventory refresh
GET  /api/v1/health              // Health check

Request/Response Examples:

// Search Request
POST /api/v1/components/search
{
  "query": "authentication",
  "type": ["agent", "skill"],
  "fuzzyMatch": true,
  "limit": 10
}

// Search Response
{
  "results": [
    {
      "id": "auth-agent-001",
      "type": "agent",
      "name": "authentication-agent",
      "path": "/mnt/c/Users/mesha/Desktop/GitHub/morphism/packages/auth-agent",
      "metadata": { ... },
      "score": 0.95
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 10
}

6. CLI Integration

Commands for interacting with inventory from Kiro CLI.

interface InventoryCLI {
  search(query: string, options: SearchOptions): Promise<void>;
  list(options: ListOptions): Promise<void>;
  refresh(): Promise<void>;
  show(componentId: string): Promise<void>;
}

CLI Commands:

kiro inventory search <query>     # Search for components
kiro inventory list [--type=...]  # List all components
kiro inventory refresh            # Refresh inventory
kiro inventory show <id>          # Show component details

Data Models

Component Model

class Component {
  constructor(
    public id: string,
    public type: ComponentType,
    public name: string,
    public path: string,
    public relativePath: string,
    public metadata: ComponentMetadata,
    public discoveredAt: Date,
    public lastModified: Date,
    public isActive: boolean = true
  ) {}

  static fromPackageJson(path: string, content: any): Component {
    // Factory method for package.json-based components
  }

  static fromAgentConfig(path: string, content: any): Component {
    // Factory method for agent components
  }

  toJSON(): object {
    // Serialization for API responses
  }
}

Configuration Model

interface InventoryConfig {
  workspace: {
    root: string;
    excludePatterns: string[];
    includePatterns: string[];
  };
  discovery: {
    maxDepth: number;
    followSymlinks: boolean;
    autoRefreshInterval?: number;
  };
  service: {
    port: number;
    host: string;
    enableCORS: boolean;
    authToken?: string;
  };
  database: {
    path: string;
  };
  cache: {
    enabled: boolean;
    ttl: number;
  };
}

Default Configuration:

{
  "workspace": {
    "root": "/mnt/c/Users/mesha/Desktop/GitHub",
    "excludePatterns": ["node_modules", ".git", "dist", "build"],
    "includePatterns": ["**"]
  },
  "discovery": {
    "maxDepth": 10,
    "followSymlinks": true
  },
  "service": {
    "port": 3000,
    "host": "localhost",
    "enableCORS": true
  },
  "database": {
    "path": ".inventory/inventory.db"
  },
  "cache": {
    "enabled": true,
    "ttl": 300
  }
}

Correctness Properties

A property is a characteristic or behavior that should hold true across all valid executions of a system—essentially, a formal statement about what the system should do. Properties serve as the bridge between human-readable specifications and machine-verifiable correctness guarantees.

Property 1: Path Normalization Idempotence

For any path string, normalizing it multiple times should produce the same result as normalizing it once.

Validates: Requirements 1.1, 1.2, 1.3

Property 2: Path Round-Trip Consistency

For any valid path in one format (Windows/Linux/WSL), converting to another format and back should preserve the semantic meaning (same file location).

Validates: Requirements 1.4

Property 3: Discovery Completeness

For any workspace directory tree, if a component exists and matches the discovery criteria, it should be found by the discovery engine.

Validates: Requirements 2.1, 2.2, 2.3

Property 4: Metadata Extraction Consistency

For any component with valid metadata files, extracting metadata multiple times should produce equivalent results.

Validates: Requirements 3.1, 3.2, 3.3, 3.4

Property 5: Query Result Relevance

For any search query, all returned results should match the query criteria (no false positives).

Validates: Requirements 6.1, 6.2, 6.3, 6.4

Property 6: Incremental Update Correctness

For any inventory state, performing an incremental update should produce the same final state as a full rescan (modulo timing differences).

Validates: Requirements 8.2, 8.3

Property 7: Inactive Component Preservation

For any component that is removed from the workspace, its historical data should remain in the database marked as inactive.

Validates: Requirements 4.3

Property 8: API Response Time Bound

For any cached query, the API response time should be less than 200ms.

Validates: Requirements 5.4

Property 9: Error Isolation

For any component that fails metadata extraction, the discovery process should continue and successfully process other components.

Validates: Requirements 10.1, 10.2

Property 10: Configuration Validation

For any invalid configuration, the system should reject it with a descriptive error message before starting.

Validates: Requirements 9.4

Error Handling

Error Categories

  1. File System Errors

    • Permission denied: Log warning, skip component, continue
    • File not found: Log warning, mark component inactive
    • Symlink cycle: Detect and break cycle, log warning

  2. Metadata Extraction Errors

    • Malformed JSON: Log error, store partial metadata, flag component
    • Missing required fields: Use defaults, log warning
    • Encoding issues: Attempt UTF-8 fallback, log warning

  3. Database Errors

    • Connection failure: Retry with exponential backoff (3 attempts)
    • Constraint violation: Log error, skip insert
    • Corruption: Detect on startup, trigger full rescan

  4. API Errors

    • Invalid request: Return 400 with validation errors
    • Not found: Return 404 with suggestions
    • Server error: Return 500, log stack trace
    • Timeout: Return 504, log slow query

  5. Configuration Errors

    • Invalid path: Exit with error code 1
    • Missing required field: Exit with error code 2
    • Type mismatch: Exit with error code 3

Error Response Format

interface ErrorResponse {
  error: {
    code: string;
    message: string;
    details?: any;
    suggestions?: string[];
  };
}

Testing Strategy

Unit Tests

Focus on individual components and edge cases:

  • Path Resolver: Test all format conversions, edge cases (UNC paths, relative paths)
  • Metadata Extractors: Test parsing of various file formats, malformed inputs
  • Database Operations: Test CRUD operations, query filtering, pagination
  • API Endpoints: Test request validation, error responses, authentication

Property-Based Tests

Verify universal properties across randomized inputs (minimum 100 iterations per test):

  • Property 1 Test: Generate random paths, verify normalization idempotence

    • Feature: skills-agents-inventory, Property 1: Path normalization idempotence

  • Property 2 Test: Generate random paths, verify round-trip consistency

    • Feature: skills-agents-inventory, Property 2: Path round-trip consistency

  • Property 3 Test: Create random directory structures, verify all components discovered

    • Feature: skills-agents-inventory, Property 3: Discovery completeness

  • Property 4 Test: Generate random metadata, verify extraction consistency

    • Feature: skills-agents-inventory, Property 4: Metadata extraction consistency

  • Property 5 Test: Generate random queries and datasets, verify no false positives

    • Feature: skills-agents-inventory, Property 5: Query result relevance

  • Property 6 Test: Generate random workspace changes, verify incremental = full scan

    • Feature: skills-agents-inventory, Property 6: Incremental update correctness

  • Property 7 Test: Remove random components, verify historical data preserved

    • Feature: skills-agents-inventory, Property 7: Inactive component preservation

  • Property 8 Test: Generate random cached queries, verify response time < 200ms

    • Feature: skills-agents-inventory, Property 8: API response time bound

  • Property 9 Test: Inject random extraction failures, verify isolation

    • Feature: skills-agents-inventory, Property 9: Error isolation

  • Property 10 Test: Generate random invalid configs, verify rejection with errors

    • Feature: skills-agents-inventory, Property 10: Configuration validation

Integration Tests

Test end-to-end workflows:

  • Full discovery → persistence → query cycle
  • API service startup → query → shutdown
  • CLI command execution with mocked API
  • Cache fallback when service unavailable

Testing Tools

  • Jest: Test runner and assertion library
  • fast-check: Property-based testing library
  • supertest: HTTP API testing
  • tmp: Temporary directory creation for filesystem tests
  • mock-fs: Filesystem mocking for unit tests