[plan] Phase 3: Extend schema and parser for inline and catalog-defined engine definitions

[github-actions]

Objective

Extend the frontmatter schema and parser to support inline engine definitions and named catalog-defined engine definitions, so users can add engines without modifying Go code.

Context

Issue #20416 Phase 3 goal: support engines outside the built-in set by extending schema and parsing to accept inline definitions and resolve them through the same EngineCatalog as built-ins.

Prerequisite: Phase 1 (EngineDefinition/EngineCatalog) and Phase 2 (single source of truth) must be merged first.

Approach

1. Extend the engine frontmatter field

Currently engine accepts:

• engine: copilot (string shorthand)
• engine:\n id: copilot (structured)

Add support for inline definitions:

engine:
  runtime:
    id: codex
    version: 0.105.0
  provider:
    id: openai
    model: gpt-5
    auth:
      secret: OPENAI_API_KEY

And named catalog entries (declared elsewhere in frontmatter or imported):

engine: my-custom-engine

2. Update pkg/parser/schemas/main_workflow_schema.json

Add schema definitions for:

• EngineRuntimeRef (id, version)
• EngineProviderRef (id, model, auth)
• EngineInlineDefinition (combines runtime + provider)
• Allow engine to be one of: string, structured-with-id, or inline definition

Run make build after schema changes (files are embedded).

3. Update pkg/workflow/engine.go parser

In parseEngineConfig() (or equivalent), detect when the engine field contains an inline definition and construct an EngineDefinition on the fly, then register it in the session catalog.

4. Add validation

In the appropriate validation file (follow 100-200 line validator guideline):

• Unknown runtime IDs → clear error with list of known runtimes
• Inline definition missing required runtime.id → validation error
• Duplicate engine IDs between inline and catalog → validation error

5. Add tests

In pkg/workflow/engine_definition_test.go or a new parser test file:

• Inline engine definition parses correctly
• Inline definition resolves through catalog.Resolve()
• Named unknown engine returns a helpful validation error
• Legacy engine: copilot still resolves correctly (regression)

Files to Modify

• Modify: pkg/parser/schemas/main_workflow_schema.json — add inline definition schema
• Modify: pkg/workflow/engine.go — parse inline definitions
• Modify or create: validation file for engine definition validation
• Create: pkg/workflow/engine_inline_test.go (or similar)
• Run: make build && make agent-finish

Acceptance Criteria

• Inline engine definition (engine.runtime + engine.provider) parses without error
• Inline engine resolves through the catalog to a runtime adapter
• Schema validation catches missing runtime.id with a clear error
• Unknown named engine produces a helpful error listing known engines
• All legacy engine forms still compile correctly (regression tests pass)
• make test-unit passes
  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