feat: tip for known external engines (opencode, crush) missing their import by Copilot · Pull Request #51088 · github/gh-aw

Copilot · 2026-08-07T14:02:13Z

When engine: opencode or engine: crush is used without importing the engine definition file, the compiler currently emits a generic "invalid engine" error with no guidance. These engines exist in shared/opencode.md / shared/crush.md but are not built into the binary.

Changes

pkg/workflow/engine_definition.go — adds knownEngineImports map (engine ID → import path) for opencode and crush; EngineCatalog.Resolve appends an import tip to the error message when the unknown engine ID is in the map
pkg/workflow/engine_definition_test.go — adds TestEngineCatalog_Resolve_KnownImportTip (opencode, crush) and TestEngineCatalog_Resolve_UnknownNoTip

Error message before / after

# before
invalid engine: opencode. Valid engines are: claude, codex, copilot, gemini, pi.

# after
invalid engine: opencode. Valid engines are: claude, codex, copilot, gemini, pi.

Tip: "opencode" is a known engine with a shared definition file. Import it before using this engine:

imports:
  - shared/opencode.md

New engines can be added by appending to knownEngineImports — no other code changes required.

Run context: https://github.com/github/gh-aw/actions/runs/31190216100> Generated by 👨‍🍳 PR Sous Chef · gpt54 · 21.1 AIC · ⊞ 8.3K · ◷

_{Comment /souschef to run again}

Generated by 👨‍🍳 PR Sous Chef · gpt54 · 8 AIC · ⊞ 8.4K · ◷
_{Comment /souschef to run again}

Generated by 👨‍🍳 PR Sous Chef · gpt54 · 10.2 AIC · ⊞ 8.4K · ◷
_{Comment /souschef to run again}

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

github-actions · 2026-08-07T14:14:58Z

⚠️ Security scanning failed for Design Decision Gate 🏗️. Review the logs for details.

No ADR enforcement needed: PR does not have the 'implementation' label and has ≤100 new lines of code in business logic directories (87 additions detected).

github-actions · 2026-08-07T14:15:02Z

⚠️ Security scanning failed for PR Code Quality Reviewer. Review the logs for details.

github-actions · 2026-08-07T14:15:09Z

⚠️ Security scanning failed for Test Quality Sentinel. Review the logs for details.

github-actions · 2026-08-07T14:15:17Z

⚠️ Security scanning failed for Matt Pocock Skills Reviewer. Review the logs for details.

pelikhan · 2026-08-07T14:16:51Z

@copilot ensure all engines in this repository are in the list.
move the list into a JSON file in this repository (.github/aw/engines.json) and download it on the fly. Silent failure.

Copilot

Pull request overview

Adds actionable import guidance when resolving known external engines that lack their shared definitions.

Changes:

Maps external engine IDs to shared definition imports.
Appends import instructions to invalid-engine errors.
Tests known and unknown engine error behavior.

Show a summary per file

File	Description
`pkg/workflow/engine_definition.go`	Adds known-engine import tips.
`pkg/workflow/engine_definition_test.go`	Tests tip generation and omission.

Review details

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Suppressed comments (2)

pkg/workflow/engine_definition.go:446

Lowercasing only the tip lookup makes the guidance ineffective for inputs such as OpenCode: catalog registration and prefix resolution above remain case-sensitive, so importing the suggested lower-case definition still leaves OpenCode invalid and repeats this same tip. Match the known ID exactly here, or explicitly instruct the user to change the engine ID to its lower-case form.

	if importPath, ok := knownEngineImports[strings.ToLower(id)]; ok {

pkg/workflow/engine_definition.go:350

Kiro is also a non-built-in engine with a shared definition (.github/workflows/shared/kiro.md, documented alongside these samples in docs/src/content/docs/reference/engines.md:27-35), but it is omitted here. As a result, engine: kiro still receives the generic error while the other shared engines receive the new guidance. Add it to this catalog and to the table-driven tip test.

	"goose":    "github/gh-aw/.github/workflows/shared/goose.md@main",

Files reviewed: 2/2 changed files
Comments generated: 1
Review effort level: Balanced

+// To add a new well-known engine, append an entry here with the engine ID as the
+// key and the fully-qualified path to its shared engine definition file as the value.
+var knownEngineImports = map[string]string{
+	"opencode": "github/gh-aw/.github/workflows/shared/opencode.md@main",


github-actions

The implementation is clean and correct. knownEngineImports map is well-documented, the strings.ToLower lookup handles case-insensitive engine IDs properly, the tip is appended only after the existing error (not replacing it), and all 5 engines have corresponding tests. No blocking issues found.

🧵 Reviewed using Impeccable skills by Impeccable Skills Reviewer · sonnet46 · 17.2 AIC · ⊞ 5.3K

github-actions

Skills-Based Review 🧠

Applied /diagnosing-bugs and /tdd — two minor observations, no blocking issues.

📋 Key Themes & Highlights

Key Themes

@main hardcoding — all five import paths pin to @main. If users are on a tagged release, the tip could direct them to a mismatched file. A shared constant for the ref would future-proof this.
Missing case-insensitive test — the production code normalises the engine ID with strings.ToLower, but no test exercises mixed-case input (e.g. "OpenCode").

Positive Highlights

✅ Clean, additive design: new engines need only one line in knownEngineImports
✅ Solid test coverage: five known-engine cases + a negative case for truly unknown engines
✅ Error message is actionable — shows the exact imports: block the user needs to add
✅ Good comment on the exported map documenting the expected key/value format

🧠 Reviewed using Matt Pocock's skills by Matt Pocock Skills Reviewer · sonnet46 · 21.8 AIC · ⊞ 7.1K
_{Comment /matt to run again}

github-actions · 2026-08-07T14:20:05Z

+// To add a new well-known engine, append an entry here with the engine ID as the
+// key and the fully-qualified path to its shared engine definition file as the value.
+var knownEngineImports = map[string]string{
+	"opencode": "github/gh-aw/.github/workflows/shared/opencode.md@main",


[/diagnosing-bugs] Import paths are hardcoded to @main, so users on a pinned release may follow a tip that points at a schema mismatched to their binary version.

💡 Suggestion

Consider exposing the ref as a constant (e.g. derived from the binary version) so all five entries can be updated in one place:

const knownEngineImportRef = "main" // or Version var knownEngineImports = map[string]string{ "opencode": fmt.Sprintf("github/gh-aw/.github/workflows/shared/opencode.md@%s", knownEngineImportRef), ... }

@copilot please address this.

github-actions · 2026-08-07T14:20:05Z

+	registry := NewEngineRegistry()
+	catalog := NewEngineCatalog(registry)
+
+	_, err := catalog.Resolve("totally-unknown-engine", nil)


[/tdd] No test covers case-insensitive lookup. The production code calls strings.ToLower(id), but there is no test that passes e.g. "OpenCode" or "CRUSH" and asserts the tip still appears.

💡 Suggested test case to add to TestEngineCatalog_Resolve_KnownImportTip

{ name: "opencode case-insensitive", engineID: "OpenCode", wantImportPath: "github/gh-aw/.github/workflows/shared/opencode.md@main", },

Without this, a future change to the strings.ToLower call would break the feature silently.

@copilot please address this.

github-actions · 2026-08-07T14:20:42Z

🧪 Test Quality Sentinel Report

⚠️ Test Quality Score: 75/100 — Acceptable

Analyzed 8 test(s): 8 design, 0 implementation, 0 violation(s).

📊 Metrics (8 tests)

Metric	Value
Analyzed	8 (Go: 8, JS: 0)
✅ Design	8 (100%)
⚠️ Implementation	0 (0%)
Edge/error coverage	4 (50%)
Duplicate clusters	0
Inflation	YES (test +63 lines vs prod +24 lines = 2.6:1)
🚨 Violations	0

Test	File	Classification	Issues
`TestNewEngineCatalog_BuiltIns`	`engine_definition_test.go:15`	design_test, high_value	None
`TestEngineCatalog_Resolve_LegacyStringFormat`	`engine_definition_test.go:49`	design_test, high_value	None
`TestEngineCatalog_Resolve_PrefixFallback`	`engine_definition_test.go:71`	design_test, high_value	None
`TestEngineCatalog_Resolve_UnknownEngine`	`engine_definition_test.go:85`	design_test, high_value	None
`TestEngineCatalog_Resolve_KnownImportTip`	`engine_definition_test.go:104`	design_test, high_value	None
`TestEngineCatalog_Resolve_UnknownNoTip`	`engine_definition_test.go:154`	design_test, high_value	None
`TestEngineCatalog_Resolve_ConfigPassthrough`	`engine_definition_test.go:166`	design_test, low_value	None
`TestEngineCatalog_Register_Custom`	`engine_definition_test.go:178`	design_test, high_value	None

Verdict

✅ passed. 0% implementation tests (threshold: 30%). Score penalized 10pts for test inflation (2.6:1 lines ratio); all tests are strong behavioral contracts.

🧪 Test quality analysis by Test Quality Sentinel · sonnet46 · 40.9 AIC · ⊞ 7.7K · ◷
_{Comment /review to run again}

github-actions

✅ Test Quality Sentinel: 75/100. 0% implementation tests (threshold: 30%).

github-actions

Verdict: Approve with non-blocking suggestions

Small, well-tested addition (import-tip map + Resolve error enrichment). No correctness or security bugs found in the changed lines; flagged concerns are maintainability hardening, not blockers.

Themes

@main-pinned import suggestions in the tip message are a drift/reproducibility risk (low severity today since nothing auto-fetches them).
knownEngineImports is a second source of truth versus the actual files in .github/workflows/shared/*.md; nothing currently validates the two stay in sync.
No collision guard between knownEngineImports keys and future built-in engine IDs.
Test coverage for the five new entries and the negative (unknown-engine, no-tip) case is solid.

🔎 Code quality review by PR Code Quality Reviewer · auto · 40.7 AIC · ⊞ 7.8K
_{Comment /review to run again}

github-actions · 2026-08-07T14:21:13Z

+	"crush":    "github/gh-aw/.github/workflows/shared/crush.md@main",
+	"cursor":   "github/gh-aw/.github/workflows/shared/cursor.md@main",
+	"aider":    "github/gh-aw/.github/workflows/shared/aider.md@main",
+	"goose":    "github/gh-aw/.github/workflows/shared/goose.md@main",


Import tip pins engines to the mutable @main branch rather than a tagged release or SHA.

💡 Why this matters

All five suggested import paths (opencode, crush, cursor, aider, goose) use @main. Since main is a moving target, the shared definition file content a user imports today can differ from what they get next week if main is force-pushed, rebased, or the shared engine file changes shape. docs/reference/imports.md explicitly documents that refs can be a semantic tag, branch, or commit SHA — a pinned tag/SHA would give reproducible, auditable imports instead of drifting silently.

var knownEngineImports = map[string]string{ "opencode": "github/gh-aw/.github/workflows/shared/opencode.md@v1.2.3", // or a pinned commit SHA }

This is only a suggested fix in an error message today (nothing auto-fetches it), so the risk is low-severity now, but it normalizes an anti-pattern that could get copy-pasted into places that do auto-resolve imports.

github-actions · 2026-08-07T14:21:13Z

 	Runtime    CodingAgentEngine // resolved adapter from the EngineRegistry
 }

+// knownEngineImports maps engine IDs that are not built into the binary to the


knownEngineImports duplicates knowledge that already lives in .github/workflows/shared/*.md, and nothing keeps the two in sync.

💡 Why this matters

The map is a second source of truth for which engine IDs have a shared definition file and where it lives. If a shared file under .github/workflows/shared/ is ever renamed, moved, or deleted, this map will keep emitting a tip pointing at a broken import path, and none of the new tests (TestEngineCatalog_Resolve_KnownImportTip) would catch the drift because they only assert against the map's own values, not against the actual filesystem.

A cheap guard would be a test that globs .github/workflows/shared/*.md and asserts every knownEngineImports value resolves to an existing file (and optionally that every existing shared engine file has a corresponding map entry), so the two never silently diverge.

github-actions · 2026-08-07T14:21:13Z

+//
+// To add a new well-known engine, append an entry here with the engine ID as the
+// key and the fully-qualified path to its shared engine definition file as the value.
+var knownEngineImports = map[string]string{


No safeguard stops a future built-in engine ID from colliding with an entry already present in knownEngineImports.

💡 Why this matters

Resolve only consults knownEngineImports after both the exact catalog lookup and the runtime-ID prefix fallback fail, so today there's no functional bug. But if a new built-in engine is ever added under one of these five names (e.g. a native cursor engine ships later), the map entry becomes stale dead code that nobody is prompted to remove, and — more importantly — there's no test or init-time check that would flag the naming collision to a reviewer. A simple init()-time assertion (or a unit test) that knownEngineImports keys don't overlap with registry.GetSupportedEngines() would catch this automatically instead of relying on someone remembering to grep the map.

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

gh-aw-bot · 2026-08-07T15:04:55Z

@copilot Please address the latest maintainer feedback, refresh the branch if GitHub can update it cleanly, and run the pr-finisher skill before handing back to maintainers.

Open review items to address (newest first):

pelikhan: feat: tip for known external engines (opencode, crush) missing their import #51088 (comment)

Branch refresh was requested.

Run context: https://github.com/github/gh-aw/actions/runs/31190216100

Generated by 👨‍🍳 PR Sous Chef · gpt54 · 21.1 AIC · ⊞ 8.3K · ◷
_{Comment /souschef to run again}

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

pelikhan · 2026-08-07T15:22:17Z

@copilot run pr-finisher skill

pelikhan · 2026-08-07T15:57:43Z

+const (
+	knownEngineImportsOwner   = "github"
+	knownEngineImportsRepo    = "gh-aw"
+	knownEngineImportsPath    = ".github/aw/engines.json"


@copilot must be laoded from github through a raw user path

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

gh-aw-bot · 2026-08-07T16:04:42Z

@copilot Please address the remaining maintainer/review feedback, refresh the branch if GitHub can update it cleanly, and run the pr-finisher skill before handing back to maintainers.

Open items to address (newest first):

pelikhan: feat: tip for known external engines (opencode, crush) missing their import #51088 (comment)
pelikhan: feat: tip for known external engines (opencode, crush) missing their import #51088 (comment)

Branch refresh was requested.

Run context: https://github.com/github/gh-aw/actions/runs/31195256639

Generated by 👨‍🍳 PR Sous Chef · gpt54 · 8 AIC · ⊞ 8.4K · ◷
_{Comment /souschef to run again}

pelikhan · 2026-08-07T16:36:00Z

+  "engines": [
+    {
+      "id": "aider",
+      "import": "github/gh-aw/.github/workflows/shared/aider.md@e3caca541fa7311d84947e25d3a7bfe4be3b431f"


@copilot let the cli add the sha/release version that embedded in the cli.

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

pelikhan · 2026-08-07T17:15:55Z

@copilot resolve the merge conflicts in this pull request . take claude golden from main

…er-agent-imports # Conflicts: # pkg/workflow/testdata/TestWasmGolden_AllEngines/claude.golden Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Copilot · 2026-08-07T17:41:49Z

@copilot resolve the merge conflicts in this pull request . take claude golden from main

Resolved in bf911d0 — merged origin/main and took pkg/workflow/testdata/TestWasmGolden_AllEngines/claude.golden from main.

gh-aw-bot · 2026-08-07T18:02:21Z

@copilot Please triage this PR, refresh the branch if possible, and run the pr-finisher skill before handing back to maintainers.

Unresolved review threads to re-check:

pelikhan: feat: tip for known external engines (opencode, crush) missing their import #51088 (comment)
pelikhan: feat: tip for known external engines (opencode, crush) missing their import #51088 (comment)
github-actions: feat: tip for known external engines (opencode, crush) missing their import #51088 (comment)
github-actions: feat: tip for known external engines (opencode, crush) missing their import #51088 (comment)
github-actions: feat: tip for known external engines (opencode, crush) missing their import #51088 (comment)
github-actions: feat: tip for known external engines (opencode, crush) missing their import #51088 (comment)
github-actions: feat: tip for known external engines (opencode, crush) missing their import #51088 (comment)
copilot-pull-request-reviewer: feat: tip for known external engines (opencode, crush) missing their import #51088 (comment)
pelikhan: feat: tip for known external engines (opencode, crush) missing their import #51088 (comment)
pelikhan: feat: tip for known external engines (opencode, crush) missing their import #51088 (comment)

Run context: https://github.com/github/gh-aw/actions/runs/31204567664

Generated by 👨‍🍳 PR Sous Chef · gpt54 · 10.2 AIC · ⊞ 8.4K · ◷
_{Comment /souschef to run again}

feat: add known engine imports tip for opencode and crush

9bc7b2f

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Copilot AI assigned Copilot and pelikhan Aug 7, 2026

Copilot AI changed the title ~~feat: add known engine imports tip for opencode and crush~~ feat: tip for known external engines (opencode, crush) missing their import Aug 7, 2026

Copilot created this pull request from a session on behalf of pelikhan August 7, 2026 14:02 View session

Copilot finished work on behalf of pelikhan August 7, 2026 14:02

Copilot AI requested a review from pelikhan August 7, 2026 14:02

pelikhan reviewed Aug 7, 2026

View reviewed changes

Comment thread pkg/workflow/engine_definition.go Outdated

Comment thread pkg/workflow/engine_definition.go Outdated

Copilot started work on behalf of pelikhan August 7, 2026 14:04 View session

feat: add cursor, aider, goose; use fully qualified import specs

56a4f3a

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Copilot AI requested a review from pelikhan August 7, 2026 14:13

Copilot finished work on behalf of pelikhan August 7, 2026 14:13

pelikhan marked this pull request as ready for review August 7, 2026 14:13

Copilot AI balanced review requested due to automatic review settings August 7, 2026 14:14

Copilot started reviewing on behalf of pelikhan August 7, 2026 14:14 View session

Copilot AI reviewed Aug 7, 2026

View reviewed changes

github-actions Bot approved these changes Aug 7, 2026

View reviewed changes

github-actions Bot reviewed Aug 7, 2026

View reviewed changes

github-actions Bot approved these changes Aug 7, 2026

View reviewed changes

github-actions Bot reviewed Aug 7, 2026

View reviewed changes

Copilot started work on behalf of pelikhan August 7, 2026 14:21 View session

github-actions Bot mentioned this pull request Aug 7, 2026

[pr-sous-chef] PR Sous Chef run report #50950

Open

Copilot AI and others added 2 commits August 7, 2026 14:45

Move known engine imports to JSON catalog

1ee6a39

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Address engine catalog review feedback

facd3c3

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Copilot AI and others added 4 commits August 7, 2026 14:51

Guard engine import catalog cache

f7a3d8d

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Refine engine catalog cache locking

725d57f

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Protect engine catalog download override

6de143f

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Replace engine catalog once cache

1e6bbe1

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

github-actions Bot and others added 2 commits August 7, 2026 15:04

Merge branch 'main' into copilot/update-compiler-agent-imports

7a009c2

Document engine catalog cold fetch tradeoff

28c3ac5

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Copilot finished work on behalf of pelikhan August 7, 2026 15:10

Copilot started work on behalf of gh-aw-bot August 7, 2026 15:10 View session

Copilot AI requested a review from gh-aw-bot August 7, 2026 15:36

Copilot started work on behalf of pelikhan August 7, 2026 15:36 View session

pelikhan reviewed Aug 7, 2026

View reviewed changes

Finish engine import catalog feedback

8d73d74

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Copilot AI requested a review from pelikhan August 7, 2026 16:04

Copilot started work on behalf of gh-aw-bot August 7, 2026 16:05 View session

pelikhan reviewed Aug 7, 2026

View reviewed changes

Copilot started work on behalf of pelikhan August 7, 2026 16:46 View session

Let CLI pin engine import tips

4380d7f

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Copilot AI requested a review from pelikhan August 7, 2026 17:04

Copilot started work on behalf of pelikhan August 7, 2026 17:27 View session

Merge remote-tracking branch 'origin/main' into copilot/update-compil…

bf911d0

…er-agent-imports # Conflicts: # pkg/workflow/testdata/TestWasmGolden_AllEngines/claude.golden Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Copilot finished work on behalf of pelikhan August 7, 2026 17:47

Merge branch 'main' into copilot/update-compiler-agent-imports

b036583

pelikhan merged commit 18e8ecb into main Aug 7, 2026

pelikhan deleted the copilot/update-compiler-agent-imports branch August 7, 2026 18:18

Uh oh!

Conversation

Copilot AI commented Aug 7, 2026 • edited by github-actions Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Error message before / after

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Aug 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Aug 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Aug 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Aug 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pelikhan commented Aug 7, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Review details

Uh oh!

github-actions Bot left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions Bot left a comment

Choose a reason for hiding this comment

Skills-Based Review 🧠

Key Themes

Positive Highlights

Uh oh!

github-actions Bot Aug 7, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Aug 7, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Aug 7, 2026

🧪 Test Quality Sentinel Report

Verdict

Uh oh!

github-actions Bot left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions Bot left a comment

Choose a reason for hiding this comment

Verdict: Approve with non-blocking suggestions

Uh oh!

github-actions Bot Aug 7, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Aug 7, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Aug 7, 2026

Choose a reason for hiding this comment

Uh oh!

gh-aw-bot commented Aug 7, 2026

Uh oh!

pelikhan commented Aug 7, 2026

Uh oh!

pelikhan Aug 7, 2026

Choose a reason for hiding this comment

Uh oh!

gh-aw-bot commented Aug 7, 2026

Uh oh!

pelikhan Aug 7, 2026

Choose a reason for hiding this comment

Uh oh!

pelikhan commented Aug 7, 2026

Uh oh!

Copilot AI commented Aug 7, 2026

Uh oh!

gh-aw-bot commented Aug 7, 2026

Copilot AI commented Aug 7, 2026 •

edited by github-actions Bot

Loading

github-actions Bot commented Aug 7, 2026 •

edited

Loading

github-actions Bot commented Aug 7, 2026 •

edited

Loading

github-actions Bot commented Aug 7, 2026 •

edited

Loading

github-actions Bot commented Aug 7, 2026 •

edited

Loading