feat!: align engine front matter with gh-aw and hook up Engine enum (#286)

* feat!: align engine front matter with gh-aw and hook up Engine enum

BREAKING CHANGE: The engine front matter format changed from model names
(engine: claude-opus-4.5) to engine identifiers (engine: copilot). Model
is now a sub-field in the object form (engine: { id: copilot, model: ... }).

- Redefine EngineConfig to use engine identifiers aligned with gh-aw
- Add full gh-aw field set: id, version, model, agent, api-target, args,
  env, command, timeout-minutes
- Replace Engine trait + dyn dispatch with Engine enum (Engine::Copilot)
- Add get_engine() factory that rejects non-copilot identifiers
- Supply resolved Engine in CompileContext
- Route generate_copilot_params through ctx.engine.args()
- Consolidate engine env vars (GITHUB_TOKEN, COPILOT_OTEL_*) into
  Engine::env(), remove from pipeline templates
- Rename {{ copilot_ado_env }} to {{ engine_env }}
- Remove SYSTEM_ACCESSTOKEN injection from agent sandbox step
- Remove AZURE_DEVOPS_EXT_PAT from engine env (handled by MCPG)
- Remove cancel_previous_builds functionality (used System.AccessToken)
- Update examples to new engine format

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* chore: remove engine from example front matters

Default engine (copilot) and model (claude-opus-4.5) are applied
automatically when engine: is omitted.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* docs(engine): update AGENTS.md and engine.rs for new engine format

- Update AGENTS.md front matter example to use `engine: copilot` instead
  of the old `engine: claude-opus-4.5` format (which now fails at compile)
- Update Engine Configuration section to document `id` field, object form
  with `id: copilot`, and all new EngineOptions fields
- Add compile-time warnings for engine options that are parsed but not yet
  wired into the pipeline (args, version, agent, api-target, command, env)
- Fix 8-space indent in copilot_args() body left over from impl extraction
- Add #[allow(dead_code)] and clarifying doc comment to Engine::command()
- Remove obsolete {{ cancel_previous_builds }} section from AGENTS.md

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* fix(prompts): update dispatcher prompts for new engine format, simplify generate_copilot_params

- Fix create-ado-agentic-workflow.md: Step 2 now teaches engine as an
  engine identifier (not a model name), object form includes id: copilot,
  complete example uses object form with model selection
- Fix debug-ado-agentic-workflow.md: Model/Engine Failures section now
  shows correct format and explains the engine vs model distinction
- Remove redundant front_matter parameter from generate_copilot_params —
  ctx.front_matter is the same value; updated all 25+ call sites

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* refactor(engine): remove generate_copilot_params wrapper, use Engine::args directly

The wrapper was a trivial one-liner delegating to ctx.engine.args().
All call sites (production + 25 tests) now call Engine::args() directly
via the CompileContext, removing an unnecessary layer of indirection.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: jamesadevine

AGENTS.md

@@ -121,8 +121,9 @@ The compiler expects markdown files with YAML front matter similar to gh-aw:
 name: "name for this agent"
 description: "One line description for this agent"
 target: standalone # Optional: "standalone" (default) or "1es". See Target Platforms section below.
-engine: claude-opus-4.5 # AI engine to use. Defaults to claude-opus-4.5. Other options include claude-sonnet-4.5, gpt-5.2-codex, gemini-3-pro-preview, etc.
+engine: copilot # Engine identifier. Defaults to copilot. Currently only 'copilot' (GitHub Copilot CLI) is supported.
 # engine:                        # Alternative object format (with additional options)
+#   id: copilot
 #   model: claude-opus-4.5
 #   timeout-minutes: 30
 schedule: daily around 14:00 # Fuzzy schedule syntax - see Schedule Syntax section below
@@ -314,14 +315,15 @@ schedule:
 
 ### Engine Configuration
 
-The `engine` field specifies which AI model to use and optional execution parameters. It accepts both a simple string format (model name only) and an object format with additional options.
+The `engine` field specifies which engine to use for the agentic task. The string form is an engine identifier (currently only `copilot` is supported). The object form uses `id` for the engine identifier plus additional options like model selection and timeout.
 
 ```yaml
-# Simple string format (just a model name)
-engine: claude-opus-4.5
+# Simple string format (engine identifier, defaults to copilot)
+engine: copilot
 
 # Object format with additional options
 engine:
+  id: copilot
   model: claude-opus-4.5
   timeout-minutes: 30
 ```
@@ -330,11 +332,20 @@ engine:
 
 | Field | Type | Default | Description |
 |-------|------|---------|-------------|
+| `id` | string | `copilot` | Engine identifier. Currently only `copilot` (GitHub Copilot CLI) is supported. |
 | `model` | string | `claude-opus-4.5` | AI model to use. Options include `claude-sonnet-4.5`, `gpt-5.2-codex`, `gemini-3-pro-preview`, etc. |
 | `timeout-minutes` | integer | *(none)* | Maximum time in minutes the agent job is allowed to run. Sets `timeoutInMinutes` on the `Agent` job in the generated pipeline. |
+| `version` | string | *(none)* | Engine CLI version to install (e.g., `"0.0.422"`, `"latest"`). **Not yet wired** — parsed but ignored with a warning. |
+| `agent` | string | *(none)* | Custom agent file identifier (Copilot only). **Not yet wired** — parsed but ignored with a warning. |
+| `api-target` | string | *(none)* | Custom API endpoint hostname for GHES/GHEC (e.g., `"api.acme.ghe.com"`). **Not yet wired** — parsed but ignored with a warning. |
+| `args` | list | `[]` | Custom CLI arguments injected before the prompt. **Not yet wired** — parsed but ignored with a warning. |
+| `env` | map | *(none)* | Engine-specific environment variables. **Not yet wired** — parsed but ignored with a warning. |
+| `command` | string | *(none)* | Custom engine executable path (skips default installation). **Not yet wired** — parsed but ignored with a warning. |
 
 > **Deprecated:** `max-turns` is still accepted in front matter for backwards compatibility but is ignored at compile time (a warning is emitted). It was specific to Claude Code and is not supported by Copilot CLI.
 
+> **Note:** Fields marked "not yet wired" are accepted in the schema for forward compatibility with gh-aw but produce a compile-time warning. Pipeline wiring for these fields is incremental.
+
 #### `timeout-minutes`
 
 The `timeout-minutes` field sets a wall-clock limit (in minutes) for the entire agent job. It maps to the Azure DevOps `timeoutInMinutes` job property on `Agent`. This is useful for:
@@ -838,29 +849,6 @@ Tool names are validated at compile time:
 - Names must contain only ASCII alphanumerics and hyphens (shell injection prevention)
 - Unrecognized names (not in `ALL_KNOWN_SAFE_OUTPUTS`) emit a warning to catch typos
 
-## {{ cancel_previous_builds }}
-
-When `triggers.pipeline` is configured, this generates a bash step that cancels any previously queued or in-progress builds of the same pipeline definition. This prevents multiple builds from accumulating when the upstream pipeline triggers rapidly (e.g., multiple PRs merged in quick succession).
-
-The step:
-- Uses the Azure DevOps REST API to query builds for the current pipeline definition
-- Filters to only `notStarted` and `inProgress` builds
-- Excludes the current build from cancellation
-- Cancels each older build via PATCH request
-
-Example output:
-```yaml
-- bash: |
-    CURRENT_BUILD_ID=$(Build.BuildId)
-    BUILDS=$(curl -s -u ":$SYSTEM_ACCESSTOKEN" \
-      "$(System.CollectionUri)$(System.TeamProject)/_apis/build/builds?definitions=$(System.DefinitionId)&statusFilter=notStarted,inProgress&api-version=7.1" \
-      | jq -r --arg current "$CURRENT_BUILD_ID" '.value[] | select(.id != ($current | tonumber)) | .id')
-    # ... cancels each build
-  displayName: "Cancel previous queued builds"
-  env:
-    SYSTEM_ACCESSTOKEN: $(System.AccessToken)
-```
-
 ## {{ threat_analysis_prompt }}
 
 Should be replaced with the embedded threat detection analysis prompt from `src/data/threat-analysis.md`. This prompt template includes markers for `{{ source_path }}`, `{{ agent_name }}`, `{{ agent_description }}`, and `{{ working_directory }}` which are replaced during compilation.

examples/azure-devops-mcp.md

@@ -2,7 +2,6 @@
 name: "ADO Work Item Triage"
 description: "Triages work items using the Azure DevOps MCP"
 schedule: daily around 9:00
-engine: claude-sonnet-4.5
 tools:
   azure-devops:
     toolsets: [core, work, work-items]

examples/lean-verifier.md

@@ -1,7 +1,6 @@
 ---
 name: "Lean Formal Verifier"
 description: "Analyzes code and builds formal Lean 4 proofs of critical invariants"
-engine: claude-opus-4.5
 schedule: weekly on friday around 17:00
 tools:
   cache-memory: true

prompts/create-ado-agentic-workflow.md

@@ -62,20 +62,23 @@ name: "Weekly Dependency Updater"
 description: "Checks for outdated dependencies and opens PRs to update them"
 ```
 
-### Step 2 — AI Model (engine)
+### Step 2 — Engine
 
-Default is `claude-opus-4.5`. Only include `engine:` if the user requests a different model.
+Default engine is `copilot` (GitHub Copilot CLI). The `engine:` field is an engine identifier, not a model name. Only include `engine:` if you need to set a non-default model or timeout.
 
-| Value | Use when |
+The default model is `claude-opus-4.5`. To use a different model, use the object form:
+
+| Model | Use when |
 |---|---|
 | `claude-opus-4.5` | Default. Best reasoning, complex tasks. |
 | `claude-sonnet-4.5` | Faster, cheaper, simpler tasks. |
 | `gpt-5.2-codex` | Code-heavy tasks. |
 | `gemini-3-pro-preview` | Google ecosystem tasks. |
 
-Object form with extra options:
+Object form with model selection and extra options:
 ```yaml
 engine:
+  id: copilot
   model: claude-sonnet-4.5
   timeout-minutes: 30
 ```
@@ -427,7 +430,9 @@ Use `noop` with a brief summary of what was reviewed.
 ---
 name: "Dependency Updater"
 description: "Checks for outdated npm dependencies and opens PRs to update them"
-engine: claude-sonnet-4.5
+engine:
+  id: copilot
+  model: claude-sonnet-4.5
 schedule: weekly on monday around 9:00
 tools:
   azure-devops: true

prompts/debug-ado-agentic-workflow.md

@@ -133,10 +133,20 @@ network:
 
 **Common causes**:
 
-- **Invalid model name**: Check the `engine:` field matches a supported model (`claude-opus-4.5`, `claude-sonnet-4.5`, `gpt-5.2-codex`, `gemini-3-pro-preview`, etc.)
+- **Invalid engine or model**: The `engine:` field is an engine identifier (e.g., `copilot`), not a model name. To specify a model, use the object form. Check that the engine identifier is valid and the model name is correct:
+  ```yaml
+  # Wrong — model name as engine identifier
+  engine: claude-opus-4.5
+
+  # Correct — engine identifier with model
+  engine:
+    id: copilot
+    model: claude-opus-4.5
+  ```
 - **Timeout**: Agent hits the Azure DevOps job timeout (default 60 minutes). Set an explicit timeout:
   ```yaml
   engine:
+    id: copilot
     model: claude-opus-4.5
     timeout-minutes: 120
   ```