[Code Quality] Refactor CodingAgentEngine interface using Interface Segregation Principle

[github-actions]

Description

The CodingAgentEngine interface contains 18 methods that mix multiple unrelated concerns (metadata, capabilities, workflow, rendering, parsing, security), violating the Interface Segregation Principle and Single Responsibility Principle. This forces all implementations to implement or inherit all methods, making testing difficult and adding new engine types harder.

Background

Identified during Sergo analysis on 2026-01-23 (discussion #11477). The interface has grown from 16 methods to 18 methods (+12.5%) in just 5 days, indicating continued bloat.

Current state: Single monolithic interface with 18 methods
Trend: Growing worse (16 methods on 2026-01-18 → 18 methods on 2026-01-23)
Impact: Tight coupling, difficult testing, hard to add new engines

Files Affected

• pkg/workflow/agentic_engine.go:19-81 - Interface definition
• pkg/workflow/claude_engine.go:14-16 - ClaudeEngine implementation
• pkg/workflow/copilot_engine.go:25-27 - CopilotEngine implementation
• pkg/workflow/custom_engine.go - CustomEngine implementation
• pkg/workflow/codex_engine.go - CodexEngine implementation
• 90+ files importing the workflow package

Suggested Changes

Split into focused interfaces using composition:

// Core identity - required by all
type Engine interface {
    GetID() string
    GetDisplayName() string
    GetDescription() string
    IsExperimental() bool
}

// Capability detection - compose as needed
type CapabilityProvider interface {
    SupportsToolsAllowlist() bool
    SupportsHTTPTransport() bool
    SupportsMaxTurns() bool
    SupportsWebFetch() bool
    SupportsWebSearch() bool
    SupportsFirewall() bool
}

// Workflow execution - required for compilation
type WorkflowExecutor interface {
    GetInstallationSteps(*WorkflowData) []GitHubActionStep
    GetExecutionSteps(*WorkflowData, string) []GitHubActionStep
    GetDeclaredOutputFiles() []string
}

// MCP configuration - optional
type MCPConfigRenderer interface {
    RenderMCPConfig(*strings.Builder, map[string]any, []string, *WorkflowData)
}

// Log parsing - optional
type LogParser interface {
    ParseLogMetrics(string, bool) LogMetrics
    GetLogParserScriptId() string
    GetLogFileForParsing() string
}

// Security - optional
type SecurityProvider interface {
    GetDefaultDetectionModel() string
    GetRequiredSecretNames(*WorkflowData) []string
}

// Composite for backward compatibility
type CodingAgentEngine interface {
    Engine
    CapabilityProvider
    WorkflowExecutor
    MCPConfigRenderer
    LogParser
    SecurityProvider
}

Implementation Steps

1. Define new focused interfaces
2. Update engine implementations to use composition
3. Refactor EngineRegistry to accept Engine interface
4. Update call sites to use specific interfaces
5. Add type assertions for optional capabilities
6. Run existing tests for backward compatibility
7. Add tests for new interface compositions

Success Criteria

• 6 focused interfaces created (Engine, CapabilityProvider, WorkflowExecutor, MCPConfigRenderer, LogParser, SecurityProvider)
• All engine implementations updated to use composition
• Call sites use specific interfaces where appropriate
• Backward compatibility maintained via composite interface
• All tests pass
• New tests added for interface compositions
• make agent-finish passes

Priority

High - Architectural improvement that prevents further bloat

Estimated effort: Large (4-6 hours, affects 90+ files)

Source

Extracted from Sergo Interface Segregation analysis discussion #11477

Analysis quote:

"##### 1. CodingAgentEngine Interface Segregation Principle Violation

The CodingAgentEngine interface contains 18 methods that mix multiple unrelated concerns...

Impact:

• Forces all implementations to implement or inherit all methods
• Violates Single Responsibility Principle
• Makes testing difficult (must mock all 18 methods)
• Hard to add new engine types with different capability sets
• Tight coupling - changes to one concern affect all implementers

Trend: Getting worse! Was 16 methods on 2026-01-18, now 18 methods (+12.5% growth)."

AI generated by Discussion Task Miner - Code Quality Improvement Agent

• expires on Feb 6, 2026, 2:07 PM UTC

[github-actions]

🍪 Issue Monster has assigned this to Copilot!

I've identified this issue as a good candidate for automated resolution and assigned it to the Copilot agent.

The Copilot agent will analyze the issue and create a pull request with the fix.

Om nom nom! 🍪

AI generated by Issue Monster