Enforce orchestrator architecture with ESLint rules

[ballidev]

Goal

Enforce the orchestrator architecture patterns using ESLint rules to prevent common violations.

Architectural Rules to Enforce

For Orchestrators

1. No new keyword - All dependencies must be injected via constructor
2. No template literals - Prevent report generation (orchestrators return raw data only)
3. No audience-based decisions - No if statements or conditionals based on audience parameter
4. Must implement proper interface - All orchestrators must have an execute() method returning LLMInfo
5. Constructor must accept dependencies - Enforce at least one parameter (dependency injection)

For Services

1. Must implement interfaces - All services should implement a defined interface
2. No LLMInfo in services - Services return typed data, not LLMInfo
3. Async methods only - All public methods should return promises

For DTOs and Data Keys (NEW)

1. No magic strings - All data keys must be defined as constants
2. DTOs must implement ILLMDataDTO - Enforce interface implementation
3. Prefer addDataFromDTO - Warn when using addData directly instead of addDataFromDTO
4. DTO keys must be const - DTO classes must define their keys as private static readonly Keys
5. Explicit return types - All methods must have explicit return types

Implementation Ideas

Option 1: Custom ESLint Plugin

Create eslint-plugin-orchestrator with rules:

• orchestrator/no-new-in-body
• orchestrator/no-template-literals
• orchestrator/no-audience-decisions
• orchestrator/require-di-constructor
• service/implement-interface
• service/no-llminfo-return
• dto/implement-interface (NEW)
• dto/no-magic-strings (NEW)
• dto/require-const-keys (NEW)
• general/prefer-addDataFromDTO (NEW)
• general/explicit-return-types (NEW)

Option 2: Use Existing Rules + Custom Config

• Use no-restricted-syntax for AST-based checks
• Use @typescript-eslint rules for type checking
• Create custom rule set for orchestrator files
• Use @typescript-eslint/explicit-function-return-type for return types

Option 3: Build-time TypeScript Checks

• Use TypeScript compiler API
• Create custom transformer
• Enforce at compile time rather than lint time

Acceptance Criteria

• ESLint catches when orchestrator creates new service instance
• ESLint catches when orchestrator generates formatted text
• ESLint catches audience-based conditionals
• ESLint catches magic strings in data keys
• ESLint enforces DTO interface implementation
• ESLint prefers addDataFromDTO over direct addData
• ESLint enforces explicit return types
• Rules are integrated into CI pipeline
• Clear error messages guide developers to correct patterns

References

• Architecture docs: cc-commands-ts/docs/Architecture.md
• DTO Architecture: cc-commands-ts/docs/DTOArchitecture.md
• Orchestrator patterns: cc-commands-ts/docs/archive/OrchestratorArchitecture.md
• Service patterns: cc-commands-ts/docs/ServicePatterns.md