fix: broaden engine.driver schema description to match runtime multi-language support

[Copilot]

The engine.driver JSON schema description and frontmatter-full.md docs only mentioned .js/.cjs/.mjs, while the runtime (engine_validation.go, copilot_engine_execution.go) already supports .py, .ts, .mts, .rb, and bare command names for the copilot engine. This mismatch caused valid Copilot SDK driver configs to appear rejected or undocumented.

Changes

• pkg/parser/schemas/main_workflow_schema.json — Updated engine.driver description to enumerate all supported extensions by engine:
  • All engines: .js, .cjs, .mjs, bare command name
  • Copilot engine additionally: .py, .ts, .mts, .rb
• docs/src/content/docs/reference/frontmatter-full.md — Updated the engine.driver comment block to match

No schema pattern change needed — the existing regex already permits these values; only the human-readable description was wrong.

Example configs now accurately documented as valid:

engine:
  id: copilot
  driver: .github/drivers/my_driver.py      # Python — copilot engine
  # driver: .github/drivers/my_driver.ts    # TypeScript
  # driver: my-copilot-driver               # bare command in PATH

[github-actions]

🤖 PR Triage

Field	Value
Category	docs
Risk	🟢 low
Score	25/100 (impact:12 urgency:5 quality:8)
Action	⏸ defer
Batch	docs-chore (with #44312, #44314)

Status: DRAFT — needs undraft + CI before review.

Tiny schema fix (9+/6-): broadens engine.driver JSON schema description to enumerate all supported extensions (.py, .ts, .mts, .rb, bare command) already supported by the runtime. Part of docs-chore batch.

Run §28966928999

Generated by 🔧 PR Triage Agent · 106.9 AIC · ⌖ 10.9 AIC · ⊞ 5.4K · ◷

[github-actions]

🧠 Matt Pocock Skills Reviewer has completed the skills-based review. ✅

[github-actions]

✅ Design Decision Gate 🏗️ completed the design decision gate check.

No ADR enforcement needed: PR #44355 does not have the 'implementation' label and has only 1 new line of code in business logic directories (threshold: 100).

[github-actions]

✅ Test Quality Sentinel completed test quality analysis.

No test files were added or modified in this PR. Test Quality Sentinel skipped.

[github-actions]

⚠️ PR Code Quality Reviewer failed during code quality review.

[Copilot]

Pull request overview

Aligns the human-readable engine.driver documentation with the runtime’s existing multi-language driver support (especially for the Copilot SDK driver mode), reducing confusion where valid configs looked “unsupported” in schema/docs text.

Changes:

• Expanded the engine.driver JSON schema description to enumerate supported driver extensions and bare-name usage by engine.
• Updated the engine.driver reference comment block in frontmatter-full.md to match the schema text.

Show a summary per file

File	Description
pkg/parser/schemas/main_workflow_schema.json	Updates engine.driver schema description to document multi-language + bare-name driver support by engine.
docs/src/content/docs/reference/frontmatter-full.md	Updates engine.driver reference docs to match the expanded schema description.

Review details

Tip

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

• Files reviewed: 2/2 changed files
• Comments generated: 2
• Review effort level: Low

[github-actions]

Review: fix: broaden engine.driver schema description to match runtime multi-language support

The changes are correct and accurately describe the existing runtime behaviour. I verified the new descriptions against engine_validation.go and copilot_engine_execution.go — all listed extensions (.py, .ts, .mts, .rb) are already validated and dispatched by the runtime for the copilot engine, and the per-engine distinction is accurately represented.

One minor observation (non-blocking):

The new description says bare names are "executable in PATH" for all engines, but the pi engine actually resolves bare names from the gh-aw setup-action directory rather than from PATH. The old text was more precise on this point. This is a very minor imprecision and does not affect copilot-engine users (the primary audience of this fix), so it does not warrant a request-for-changes.

Everything else is accurate and the fix cleanly closes the documentation gap.

🧵 Reviewed using Impeccable skills by Impeccable Skills Reviewer · 33.1 AIC · ⌖ 5.96 AIC · ⊞ 4.8K

[github-actions]

Skills-Based Review 🧠

Applied /grill-with-docs — requesting changes on one factual inaccuracy present in both changed files.

📋 Key Themes & Highlights

Issue Found

• Bare-name resolution description is wrong for the pi engine: the new text says bare driver names are treated as "executable in PATH" for any engine. In reality, only the copilot engine resolves bare names from PATH. The pi engine resolves them from ${RUNNER_TEMP}/gh-aw/actions/<name> (see buildPiDriverCommand() in pkg/workflow/pi_engine.go and the Driver field comment in pkg/workflow/engine.go). The original docs correctly captured this — the rewrite silently dropped it.

This inaccuracy appears in both changed files:

• docs/src/content/docs/reference/frontmatter-full.md (line 2328)
• pkg/parser/schemas/main_workflow_schema.json (line 12418)

Positive Highlights

• ✅ Excellent motivation: the runtime already supported .py, .ts, .mts, .rb for the copilot engine; surfacing that in the schema and docs is clearly the right thing to do.
• ✅ No code logic changed — purely descriptive alignment, which is exactly the right scope.
• ✅ Clean PR description with a worked example.

🧠 Reviewed using Matt Pocock's skills by Matt Pocock Skills Reviewer · 51.2 AIC · ⌖ 6.88 AIC · ⊞ 6.6K
_{Comment /matt to run again}

[github-actions]

[/grill-with-docs] The phrase "executable in PATH" is inaccurate for the pi engine — it drops a correct detail from the original docs and contradicts the internal implementation.

💡 Details and suggested fix

Per buildPiDriverCommand() in pkg/workflow/pi_engine.go (line 562–572) and the Driver field comment in pkg/workflow/engine.go (line 61), a bare name for the pi engine is resolved from the setup-action directory (${RUNNER_TEMP}/gh-aw/actions/<name>), not from PATH. Only the copilot engine treats bare names as arbitrary PATH executables.

The original docs correctly said:

a bare filename without a path separator resolved from the gh-aw setup-action directory

Suggested replacement for the last comment line before the (optional) marker:

  # (treated as a built-in driver from the setup-action directory for the pi engine,
  # or as an executable in PATH for the copilot engine). Examples:

This preserves the accurate per-engine distinction that was lost in the rewrite.

@copilot please address this.

[github-actions]

[/grill-with-docs] Same bare-name accuracy issue: the schema description says bare names are treated as "executable in PATH" for any engine, but for the pi engine they are resolved from the setup-action directory.

💡 Suggested wording

Current:

A bare name without an extension is also valid for any engine (treated as a built-in driver or executable in PATH).

Suggested:

A bare name without an extension is also valid for any engine (for the pi engine, resolved from the gh-aw setup-action directory; for the copilot engine, resolved as an executable in PATH).

This aligns the JSON schema description with the runtime behaviour in buildPiDriverCommand() and the field-level comment in engine.go.

@copilot please address this.

[github-actions]

REQUEST_CHANGES — One medium factual regression in both changed files.

### Blocking issue: bare-name resolution misrepresented for the `pi` engine

The PR correctly broadens the copilot-engine extension list (.py, .ts, .mts, .rb, bare names) — all backed by the runtime. The problem is in the bare-name explanation:

"A bare name without an extension is also valid for any engine (treated as a built-in driver or executable in PATH)."

This is wrong for the pi engine. pi_engine.go::buildPiDriverCommand resolves bare names from the setup-action directory (${RUNNER_TEMP}/gh-aw/actions/<name>), not from PATH. The old docs got this right ("resolved from the gh-aw setup-action directory"). This regression appears in both the frontmatter comment and the JSON Schema description field.

🔎 Code quality review by PR Code Quality Reviewer · 146.4 AIC · ⌖ 6.56 AIC · ⊞ 5.4K
_{Comment /review to run again}

[github-actions]

Factual error: bare names for the pi engine are not resolved from PATH — they resolve from the setup-action directory (${RUNNER_TEMP}/gh-aw/actions/<name>).

💡 Details and suggested fix

What the runtime actually does

pi_engine.go::buildPiDriverCommand uses this logic for bare names (no / in the name):

// no "/" → resolve from setup-action directory
driverPath = fmt.Sprintf(`"%s/%s"`, SetupActionDestinationShell, driverName)

So pi_agent_core_driver.cjs resolves to ${RUNNER_TEMP}/gh-aw/actions/pi_agent_core_driver.cjs, not $PATH.

The old wording was correct: "resolved from the gh-aw setup-action directory."

The copilot engine does treat bare names (no extension) as arbitrary executables in PATH — but the updated text accidentally generalises this to "any engine", which is wrong for pi.

Suggested wording

# A bare name without an extension is also valid: for the copilot engine it is
# treated as an arbitrary executable in PATH; for other engines (e.g. pi) it is
# resolved from the gh-aw setup-action directory.

[github-actions]

Schema description does not match docs: the engine.driver description in main_workflow_schema.json now says bare names are valid for "any engine (treated as a built-in driver or executable in PATH)" — same as the docs comment — but for the pi engine a bare name resolves from the setup-action directory, not PATH.

💡 Details

The JSON Schema description on line 34 of the diff says:

A bare name without an extension is also valid for any engine (treated as a built-in driver or executable in PATH).

This is accurate for the copilot engine, but for the pi engine pi_engine.go::buildPiDriverCommand resolves bare names as:

driverPath = fmt.Sprintf(`"%s/%s"`, SetupActionDestinationShell, driverName)

i.e., ${RUNNER_TEMP}/gh-aw/actions/<name> — not from PATH. Schema descriptions are used by IDEs/tooling as inline help; this misleads pi-engine users about where their driver will be looked up.

Suggested replacement for the bare-name clause:

A bare name without an extension is also valid: for the copilot engine it is treated as an arbitrary executable in PATH; for other engines (e.g. pi) it is resolved from the gh-aw setup-action directory.

[github-actions]

🎉 This pull request is included in a new release.

Release: v0.82.7