Alexandria AI Platform Developer

This skill provides comprehensive guidance for developing on Alexandria, an AI-driven customer care platform with a sophisticated microkernel architecture and plugin system.

What This Skill Does

This skill helps you navigate and contribute to the Alexandria repository, which serves dual purposes:

1. **Advanced Prompt Engineering Templates** - Collection of AI-assisted content generation templates for software architecture, API documentation, code explanation, and educational content

2. **Modular AI-Enhanced Customer Care Platform** - Enterprise application with microkernel architecture, event-driven communication, and plugin system

Core Development Instructions

1. Understand the Non-Negotiable Rules

Before making any changes, internalize these critical rules:

**Rule 1: Never Replace Complex Components**

Always fix the actual problem in existing code

Never create "simplified" replacement versions

Preserve existing functionality and complexity when it serves a purpose

**Rule 2: Always Fix Root Causes**

Diagnose and address underlying issues

Never create workarounds or patches that mask problems

Trace errors to their source before implementing solutions

**Rule 3: Ask for Clarification**

When requirements are ambiguous, ask specific questions

Never make assumptions about unclear specifications

Confirm understanding before implementing

**Rule 4: Match Requirements Exactly**

Implement precisely what was requested

No extra features unless explicitly approved

No altered behavior without confirmation

**Rule 5: Handle All Errors and Edge Cases**

Every function must validate inputs

Implement graceful error handling

Consider and handle edge conditions

2. Follow the Architecture Principles

**Microkernel Architecture:**

Maintain strict separation between core and plugin functionalities

Core system provides minimal essential services

Plugins extend functionality without modifying core

Use dependency injection for loose coupling

**Event-Driven Communication:**

Use the event bus for cross-component communication

Publish events for state changes

Subscribe to events for reactive behavior

Maintain event naming conventions

**Plugin Lifecycle Management:**

Implement proper lifecycle hooks: `install`, `activate`, `deactivate`, `uninstall`

Clean up resources during deactivation

Validate plugin dependencies before activation

Handle version compatibility

3. Implement Robust Error Handling

**Comprehensive Error Strategy:**

```typescript

// Always provide context-rich error information

try {

// operation

} catch (error) {

logger.error('Operation failed', {

context: 'specific-operation',

error: error instanceof Error ? error.message : String(error),

stack: error instanceof Error ? error.stack : undefined,

metadata: { /* relevant context */ }

});

throw new ApplicationError('User-friendly message', { cause: error });

}

```

**Error Handling Requirements:**

Catch and handle all errors at appropriate levels

Provide user-friendly error messages

Log detailed error information for debugging

Implement fallback mechanisms where appropriate

Never expose sensitive information in error messages

4. Maintain Strong Type Safety

**TypeScript Best Practices:**

Use strict TypeScript configuration

Define interfaces for all data structures

Avoid `any` type unless absolutely necessary

Use generics for reusable components

Leverage type guards for runtime type checking

**Type Definition Example:**

```typescript

interface PluginMetadata {

id: string;

name: string;

version: string;

dependencies?: string[];

capabilities: PluginCapability[];

}

type PluginCapability = 'file-analysis' | 'data-visualization' | 'export';

```

5. Write Testable Code

**Testing Requirements:**

Write unit tests for all business logic

Implement integration tests for plugin interactions

Use dependency injection for testability

Mock external dependencies in tests

Aim for high code coverage

**Test Structure:**

```typescript

describe('PluginManager', () => {

let pluginManager: PluginManager;

let mockEventBus: jest.Mocked<EventBus>;

beforeEach(() => {

mockEventBus = createMockEventBus();

pluginManager = new PluginManager(mockEventBus);

});

it('should activate plugin successfully', async () => {

// Arrange

const plugin = createTestPlugin();

// Act

await pluginManager.activate(plugin.id);

// Assert

expect(plugin.state).toBe('active');

expect(mockEventBus.publish).toHaveBeenCalledWith('plugin:activated', {

pluginId: plugin.id

});

```

6. Performance Optimization

**Performance Considerations:**

Profile code for bottlenecks

Implement lazy loading for plugins

Use memoization for expensive computations

Optimize bundle size with code splitting

Monitor memory usage and prevent leaks

7. Documentation Standards

**Code Documentation:**

Write clear, concise comments for complex logic

Document public APIs with JSDoc

Maintain README files for each plugin

Update architecture documentation when making structural changes

**JSDoc Example:**

```typescript

/**

* Analyzes crash files and extracts relevant error information

* @param filePath - Path to the crash file

* @param options - Analysis options

* @returns Promise resolving to analysis results

* @throws {FileNotFoundError} If the file doesn't exist

* @throws {InvalidFormatError} If the file format is unsupported

async function analyzeCrashFile(

filePath: string,

options?: AnalysisOptions

): Promise<AnalysisResult>

```

Working with the Crash File Analyzer Plugin

The Crash File Analyzer is a core plugin demonstrating the platform's capabilities:

**Key Features:**

Parse various crash log formats

Extract error patterns and stack traces

Generate analysis reports

Integrate with AI for root cause analysis

**Integration Points:**

Implements standard plugin interface

Uses event bus for status updates

Provides UI components via React

Exports analysis data in multiple formats

Common Tasks

Adding a New Plugin

1. Create plugin directory structure

2. Implement plugin interface with lifecycle methods

3. Define plugin metadata and capabilities

4. Register event handlers

5. Create UI components (if needed)

6. Write comprehensive tests

7. Document plugin functionality

Modifying Core System

1. Assess impact on existing plugins

2. Maintain backward compatibility

3. Update plugin API documentation

4. Implement migration path if needed

5. Test with all active plugins

Debugging Issues

1. Check logs for error context

2. Verify plugin dependencies

3. Test plugin lifecycle transitions

4. Validate event bus communications

5. Use browser DevTools for frontend issues

Best Practices

Follow the repository's established patterns

Prioritize code readability and maintainability

Write self-documenting code with clear naming

Implement progressive enhancement

Consider accessibility in UI components

Use semantic versioning for plugins

Keep security in mind (input validation, sanitization)

Project Status and Roadmap

**Completed:**

Phase 1 implementation (core systems and plugin architecture)

Comprehensive testing infrastructure

Performance optimization mechanisms

Error recovery systems

**Current Focus:**

Preparing for Phase 2 implementation

Enhancing AI integration capabilities

Expanding plugin ecosystem

Improving performance monitoring tools

**Ongoing Priorities:**

Robust error handling

Type safety enforcement

Performance optimization

Security enhancements

Continuous documentation updates

Important Constraints

Never sacrifice code quality for speed

Always validate user input

Maintain plugin isolation

Preserve core system stability

Follow established coding guidelines

Prioritize enterprise-grade reliability

When to Ask for Help

Request clarification when:

Requirements are ambiguous or contradictory

Multiple implementation approaches are viable

Changes could impact system architecture

Security implications are unclear

Performance trade-offs need evaluation

Breaking changes to plugin API are considered

Remember: It's always better to ask than to assume incorrectly.

Alexandria AI Platform Developer

Alexandria AI Platform Developer

What This Skill Does

Core Development Instructions

1. Understand the Non-Negotiable Rules

2. Follow the Architecture Principles

3. Implement Robust Error Handling

4. Maintain Strong Type Safety

5. Write Testable Code

6. Performance Optimization

7. Documentation Standards

Working with the Crash File Analyzer Plugin

Common Tasks

Adding a New Plugin

Modifying Core System

Debugging Issues

Best Practices

Project Status and Roadmap

Important Constraints

When to Ask for Help

Reviews (0)