gabrielmoreira Custom Engine Implementation
Use this skill when adding a new agentic engine definition or extending the behavior-defined engine infrastructure.
Choose the smallest implementation
Prefer a shared Markdown engine definition. Installation, execution, MCP
configuration, provider routing, caching, manifests, plugins, network defaults,
harness scripts, and log parsing can already be declared through
engine.behaviors.
Only change Go code when the engine needs a reusable behavior that the declarative model cannot express. Add a dedicated Go engine only when the shared behavior-defined runtime cannot run the engine at all.
| Need | Implementation |
|---|---|
| Existing behaviors are sufficient | Add an imported shared engine definition |
| A reusable declarative behavior is missing | Extend the definition model and behavior-defined runtime |
| The shared runtime is fundamentally unsuitable | Add a dedicated Go engine and register it |
The relevant implementation is in:
pkg/workflow/engine_definition.gofor the definition model and catalogpkg/workflow/behavior_defined_engine.gofor the shared runtimepkg/workflow/engine_definition_loader.gofor embedded built-in definitionspkg/workflow/agentic_engine.gofor dedicated Go engine registrationpkg/parser/schemas/main_workflow_schema.jsonfor the workflow schema
Study representative engines
Read the closest examples before making changes:
.github/workflows/shared/opencode.md: npm installation, merged configuration, MCP, provider routing, and log parsing.github/workflows/shared/aider.md: Python installation and a custom harness without native MCP.github/workflows/shared/crush.md: native MCP configuration adapter and harness.github/workflows/shared/cursor.md: plugin support.github/workflows/shared/deepseek-harness.md: provider endpoint discovery and a headless profile
Use the examples to identify a pattern, not as a reason to copy optional behaviors.
Add a shared engine definition
- Create
.github/workflows/shared/<engine>.md. - Declare
engine.id,display-name,description,experimental, provider metadata, authentication, and only the requiredbehaviors. - Pin a default CLI version. Make installation deterministic and provide a verification command.
- Document setup, authentication, model syntax, MCP support, and limitations in the Markdown body. Keep in-repository integrations clearly identified as unsupported samples.
- Add the engine ID and shared definition path to
.github/aw/engines.json. Imported behavior-defined engines are registered dynamically; do not add them toNewEngineRegistry(). - Add
.github/workflows/smoke-<engine>.md, following the closest existing smoke workflow. Import the shared definition and exercise the capabilities the engine claims to support. - Update the unsupported sample table in
docs/src/content/docs/reference/engines.md. - Add a changeset when the engine is a user-visible repository sample. New
experimental engines have precedent as a
minorchange. - Run
make recompileand include the generated smoke workflow.lock.yml.
TestKnownEngineImportsFile_MatchesSharedEngineFiles in
pkg/workflow/engine_definition_test.go enforces catalog coverage for shared
external engines.
Design the definition
Keep the definition declarative and minimal:
- Select the correct package manager, package name, binary name, version, and
verification command under
behaviors.installation. - Put invocation arguments and non-secret environment variables under
behaviors.execution. - Use an existing secret strategy and provider environment mode where possible.
- Declare native MCP support only when the CLI can consume the generated configuration. Otherwise use a harness or the gh-aw CLI proxy pattern.
- Add only required default domains and map provider-specific domains under
behaviors.network.provider-domains. - Declare manifest files, cache paths, and plugin support only when the CLI consumes them.
- Add a log parser only when its emitted event format can be tested.
Treat inline JavaScript in harnesses, configuration adapters, and log parsers as production code. Avoid shell interpolation, validate paths and child-process arguments, preserve nonzero exit codes, and never print secret values. Enabling package lifecycle scripts requires a pinned version and an explicit reason.
For log and error regular expressions, also load
.github/skills/error-pattern-safety/SKILL.md.
Extend declarative infrastructure
When an engine exposes a generally useful capability that existing behaviors cannot express:
- Add the smallest field to the types in
pkg/workflow/engine_definition.go. - Validate and render it in the focused behavior-defined engine files.
- Update
pkg/parser/schemas/main_workflow_schema.json. - Add focused tests for parsing, validation, and rendered execution behavior.
- Run
make generate-schema-docswhen generated schema documentation changes.
Do not add a schema field for a behavior that can be represented by existing installation, execution, environment, harness, or adapter fields.
For a dedicated Go runtime, implement the engine interfaces by composing the
existing helpers, keep engine-specific code in its own files, and register the
engine in pkg/workflow/agentic_engine.go. Cover configuration, commands,
environment, authentication, tools, logs, and failure handling with focused
tests.
Test the right layers
Use tests that match the changed behavior:
| Area | Tests and examples |
|---|---|
| Harness, configuration, MCP, and environment | behavior_defined_engine_harness_test.go |
| Log parsing | behavior_defined_engine_log_parser_test.go |
| Cache behavior | behavior_defined_engine_cache_test.go |
| Definitions, catalog, and known imports | engine_definition_test.go, engine_catalog_test.go |
| Embedded definitions | engine_definition_loader_test.go |
| Real shared workflow harness | aider_workflow_test.go |
| Sandboxed CLI visibility | docker_sbx_test.go |
| Generated smoke workflows | compiled_lock_files_test.go |
Test both definition parsing and the generated installation/execution steps. Include negative cases for unsafe paths, invalid configuration, missing credentials, or malformed logs when relevant.
Validate
After Go changes:
make build
make fmt
After workflow Markdown changes:
make recompile
Run focused go test commands for the changed behavior while iterating. Before
an intermediate progress report, run:
make agent-report-progress-no-test
Before the final progress report, run:
make agent-report-progress
Use make agent-finish for the final repository validation when time allows.
Do not trigger a smoke workflow from a Copilot cloud agent run.
Completion checklist
- The declarative path was preferred unless its limitations are documented.
- The engine definition uses a pinned, verified installation.
- Authentication, provider/model handling, MCP, and network access are covered.
- Harnesses and adapters do not expose secrets or interpolate untrusted input.
.github/aw/engines.json, smoke workflow, generated lock file, documentation, and changeset are updated when applicable.- Focused tests cover parsing and rendered runtime behavior.
- Repository validation passes.