AI Capabilities Documentation

Overview

Structured documentation system for AI assistance using a two-level TypeScript interface structure: a consolidated main file and domain-specific capability files, each with a 500-line limit.

Status

• ✅ Initial consolidated capabilities file
• ✅ Core interfaces and types
• 🚧 Split into domain-specific files
• 🚧 Cross-reference system

NEXT_TASK: Implement cross-reference system between main capabilities.ts and domain-specific files using JSDoc references

Components

Core Components

1. System Capabilities Index

   • Location: toma/docs/ai/capabilities.ts
   • Size: Maximum 500 lines
   • Purpose: Core interfaces and common types
   • Content: Main interfaces and cross-domain types

2. Domain Capability Files

   • Location: toma/docs/ai/capabilities/{domain}/index.ts
   • Size: Maximum 500 lines per domain
   • Content: Domain-specific interfaces and types
   • Structure:

     capabilities/
     ├── capabilities.ts          # Main SystemCapabilities
     ├── mercury-bot/index.ts     # MercuryBotCapabilities
     ├── mercury-ta/index.ts      # MercuryTACapabilities
     ├── arcana-bot/index.ts      # ArcanaBotCapabilities
     └── infrastructure/index.ts  # InfrastructureCapabilities

Technical Implementation

File Organization

1. Main File (capabilities.ts):

   export interface SystemCapabilities {
     /** @see {MercuryBotCapabilities} ./mercury-bot/index.ts */
     mercuryBot: MercuryBotCapabilities;
   
     /** @see {MercuryTACapabilities} ./mercury-ta/index.ts */
     mercuryTA: MercuryTACapabilities;
   
     /** @see {ArcanaBotCapabilities} ./arcana-bot/index.ts */
     arcanaBot: ArcanaBotCapabilities;
   
     /** @see {InfrastructureCapabilities} ./infrastructure/index.ts */
     infrastructure: InfrastructureCapabilities;
   }
   
   // Common interfaces and types used across domains
   interface CommonTypes {
     // ...
   }

2. Domain Files ({domain}/index.ts):

   export interface DomainCapabilities {
     // Complete domain interfaces in single file
     // Maximum 500 lines
   }

Size Guidelines

1. Main File:

   • Maximum: 500 lines
   • Content:
     • SystemCapabilities interface
     • Common types and interfaces
     • Cross-domain utilities

2. Domain Files:

   • Maximum: 500 lines per domain
   • Content: Complete domain interfaces
   • When to split: Create new domain if exceeding 500 lines

Documentation Standards

1. Cross-References:

   /** @see {DomainCapabilities} ./domain/index.ts */
   type ServiceRef = DomainCapabilities;

2. Interface Documentation:

   /**
    * Domain capability description
    * @package domain-name
    */
   interface DomainCapabilities {
     /** Feature description */
     feature: FeatureInterface;
   }

Development Guidelines

1. File Organization:

   • Keep main file focused on core interfaces
   • One file per domain
   • Clear JSDoc references

2. Size Management:

   • Hard limit: 500 lines per file
   • Create new domain when limit reached
   • Keep related interfaces together

3. Updates:

   • Add new services to main file
   • Keep domain files focused
   • Maintain JSDoc references

Usage Examples

1. Adding New Service:

   // 1. Add to capabilities.ts
   interface SystemCapabilities {
     /** @see {NewServiceCapabilities} ./new-service/index.ts */
     newService: NewServiceCapabilities;
   }
   
   // 2. Create domain file
   // new-service/index.ts
   export interface NewServiceCapabilities {
     // Complete service interfaces...
     // Maximum 500 lines
   }

2. Updating Domain:

   // domain/index.ts
   export interface DomainCapabilities {
     // Update domain interfaces
     // Keep under 500 lines
   }