[plan] Phase 1: Introduce EngineDefinition, EngineCatalog, and ResolvedEngineTarget

[github-actions]

Objective

Separate engine definition data from runtime adapter code by introducing first-class types for engine definitions, a catalog, and a resolved target — without changing any workflow behavior.

Context

Issue #20416 identifies that the current engine system mixes runtime implementation with engine identity metadata, duplicates engine lists across many files, and requires multi-file edits to add a new engine. This is the foundational phase to address that.

Approach

1. Create pkg/workflow/engine_definition.go

Define the following types:

type EngineDefinition struct {
    ID          string
    DisplayName string
    Description string
    RuntimeID   string            // maps to existing CodingAgentEngine ID
    Provider    ProviderSelection
    Models      ModelSelection
    Auth        []AuthBinding
    Options     map[string]any
}

type EngineCatalog struct {
    definitions map[string]*EngineDefinition
}

type ResolvedEngineTarget struct {
    Definition *EngineDefinition
    Config     *EngineConfig     // resolved merged config
    Runtime    CodingAgentEngine // resolved adapter
}

2. Register built-in engines as catalog entries

In pkg/workflow/agentic_engine.go (or new engine_catalog.go), create a NewEngineCatalog() that registers claude, codex, copilot, gemini as built-in EngineDefinition entries.

The existing NewEngineRegistry() stays for runtime adapters; the catalog is an additional layer on top.

3. Add a Resolve(id string, config EngineConfig) (*ResolvedEngineTarget, error) method to EngineCatalog

It should:

• Look up the definition by engine ID
• Fall back to runtime-ID lookup for backward compat
• Return a ResolvedEngineTarget combining definition + config + runtime

4. Update compiler_orchestrator_engine.go to resolve once

Replace inline engine lookups with a single catalog.Resolve(...) call at the top of orchestration, then pass ResolvedEngineTarget downstream.

5. Add regression tests

In pkg/workflow/engine_definition_test.go:

• All four built-ins resolve correctly
• Legacy engine: claude / engine.id: claude both resolve to the same target
• Unknown engine IDs return a validation error

Files to Modify

• Create: pkg/workflow/engine_definition.go
• Create: pkg/workflow/engine_definition_test.go
• Modify: pkg/workflow/agentic_engine.go — register built-ins in catalog
• Modify: pkg/workflow/compiler_orchestrator_engine.go — use Resolve()
• Run: make agent-finish before committing

Acceptance Criteria

• EngineDefinition, EngineCatalog, ResolvedEngineTarget types defined
• Built-in engines (claude, codex, copilot, gemini) registered as catalog entries
• Catalog Resolve() returns correct runtime adapter for each built-in
• Orchestrator uses resolved target instead of ad-hoc lookup
• All existing unit tests still pass (make test-unit)
• New regression tests covering all four built-ins and unknown engine error
  Related to GitHub Agentic Workflow Engine Enhancement Proposal #20416

Generated by Plan Command for issue #20416 · ◷

• expires on Mar 13, 2026, 2:45 AM UTC