[plan] Phase 2: Make EngineCatalog the single source of truth for engine metadata

[github-actions]

Objective

Eliminate duplicated engine metadata by making the EngineCatalog (introduced in Phase 1) the single source of truth, then deriving all other engine lists from it.

Context

Issue #20416 identifies that engine metadata is duplicated in at least 6 places:

• NewEngineRegistry() in pkg/workflow/agentic_engine.go
• EngineOptions in pkg/constants/constants.go
• AgenticEngines in pkg/constants/constants.go
• Schema enums in pkg/parser/schemas/main_workflow_schema.json
• Docs in docs/src/content/docs/reference/engines.md
• CLI selection logic in pkg/cli/add_interactive_engine.go

This is already causing drift (gemini missing from EngineOptions and AgenticEngines).

Prerequisite: Phase 1 sub-issue (EngineDefinition/EngineCatalog/ResolvedEngineTarget) must be merged first.

Approach

1. Add catalog helper methods

Add to EngineCatalog:

func (c *EngineCatalog) IDs() []string          // sorted list of all engine IDs
func (c *EngineCatalog) DisplayNames() []string  // for CLI prompts
func (c *EngineCatalog) All() []*EngineDefinition

2. Replace EngineOptions and AgenticEngines in pkg/constants/constants.go

Replace hard-coded constant slices with catalog-derived values. If constants must stay for other callers, add a // Deprecated comment and have them delegate to catalog methods.

3. Update pkg/cli/add_interactive_engine.go

Replace the hard-coded engine list used in interactive prompts with catalog.DisplayNames() or catalog.IDs().

4. Update JSON schema enum

In pkg/parser/schemas/main_workflow_schema.json, the engine property enum should list the catalog IDs. Add a code-generation step or a test that asserts the schema enum matches catalog.IDs() to prevent future drift.

Note: Schema files are embedded via //go:embed — run make build after changes.

5. Fix the gemini drift

Verify gemini appears correctly in all derived locations after the consolidation.

6. Add drift-detection test

In pkg/workflow/engine_catalog_test.go (or a new pkg/constants/engine_sync_test.go), add a test that asserts the schema enum, constants, and catalog are in sync:

func TestEngineCatalogMatchesSchema(t *testing.T) {
    // catalog IDs should match schema enum exactly
}

Files to Modify

• Modify: pkg/constants/constants.go — remove/deprecate hard-coded lists
• Modify: pkg/cli/add_interactive_engine.go — use catalog
• Modify: pkg/parser/schemas/main_workflow_schema.json — align enum with catalog
• Modify: pkg/workflow/engine_catalog.go (or agentic_engine.go) — add helper methods
• Create: test asserting catalog/schema/constants stay in sync
• Run: make build && make agent-finish (schema embedded in binary)

Acceptance Criteria

• EngineOptions and AgenticEngines constants derived from catalog (not hard-coded)
• CLI interactive engine selection uses catalog IDs/display names
• Schema enum matches catalog IDs exactly
• gemini appears in all derived locations
• A test fails if schema enum and catalog drift apart
• All existing tests pass (make test-unit)
  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