Add explicit engine.agent field for Copilot CLI agent specification

[Copilot]

Summary: Add engine.agent frontmatter field

Successfully implemented the ability to explicitly specify the agent ID via engine.agent frontmatter field, which is passed to the Copilot CLI --agent flag. The --agent flag is exclusively controlled by engine.agent. Agent imports remain functional as a separate orthogonal feature for importing markdown content.

✅ All Requirements Met

• Added frontmatter field engine.agent = agentid
• --agent flag exclusively controlled by engine.agent
• Agent imports work for markdown content (orthogonal feature)
• Feature only supported for copilot engine
• All tests pass (fmt, lint, test-unit)
• Workflows updated to use explicit engine.agent
• Schema documentation updated

Implementation Details

Core Changes

1. pkg/workflow/engine.go: Added Agent string field to EngineConfig struct
2. pkg/workflow/engine.go: Updated ExtractEngineConfig() to parse engine.agent from frontmatter
3. pkg/workflow/copilot_engine_execution.go: --agent flag only set by engine.agent
4. pkg/parser/import_processor.go: Agent imports still work for importing markdown content (AgentFile field populated)
5. pkg/parser/schemas/main_workflow_schema.json: Added agent field to engine configuration schema
6. docs/src/content/docs/reference/frontmatter-full.md: Regenerated documentation to include agent field

Test Updates

• ✅ TestCopilotEngineWithAgentFromEngineConfig - validates engine.agent sets --agent flag
• ✅ TestCopilotEngineWithAgentFromImports - validates agent imports do NOT set --agent flag
• ✅ TestCopilotEngineAgentOnlyFromEngineConfig - validates only engine.agent controls the flag
• ✅ TestAgentImportWithToolsArray - validates agent import detection still works
• ✅ TestMultipleAgentImportsError - validates error on multiple agent imports
• ✅ All hash consistency tests pass

Migrated Workflows

Updated 3 workflows to explicitly use engine.agent:

• glossary-maintainer.md → engine.agent: technical-doc-writer
• hourly-ci-cleaner.md → engine.agent: ci-cleaner
• technical-doc-writer.md → engine.agent: technical-doc-writer

Feature Clarification: Two Orthogonal Features

1. engine.agent - Controls --agent Flag (New)

engine:
  id: copilot
  agent: my-custom-agent  # Exclusively controls --agent flag

2. Agent Imports - Import Markdown Content (Existing)

imports:
  - .github/agents/my-agent.md  # Imports markdown only, does NOT set --agent

Key Point: These are orthogonal features:

• engine.agent exclusively controls the --agent flag passed to Copilot CLI
• Agent imports import markdown content from .github/agents/ files
• Agent imports do NOT set the --agent flag

Usage Examples

Using engine.agent with agent import

engine:
  id: copilot
  agent: my-agent  # Controls --agent flag
imports:
  - .github/agents/my-agent.md  # Imports instructions/markdown

Using engine.agent without imports

engine:
  id: copilot
  agent: my-agent  # Agent must exist in Copilot CLI

Using agent import without engine.agent

engine: copilot
imports:
  - .github/agents/my-agent.md  # Only imports markdown, no --agent flag

Migration Required

⚠️ Workflows that previously relied on agent imports to set the --agent flag must add explicit engine.agent:

# Before: imports set --agent flag automatically (old behavior)
engine: copilot
imports:
  - .github/agents/ci-fixer.agent.md

# After: explicit engine.agent required for --agent flag
engine:
  id: copilot
  agent: ci-fixer  # Now required to set --agent flag
imports:
  - .github/agents/ci-fixer.agent.md  # Still imports markdown

Validation Status

✅ All checks passing:

• Code formatting (go fmt, prettier)
• Linting (golangci-lint)
• Unit tests (agent flag control)
• Integration tests (agent imports)
• Hash consistency tests
• Schema validation
• Workflow compilation

Notes

• Feature is copilot engine only as specified
• --agent flag is exclusively controlled by engine.agent
• Agent imports work independently for markdown content
• AgentFile field still populated from imports (for other engine types like Claude/Codex that use agent content differently)
• Clear separation between agent ID (engine.agent) and agent content (imports)

Original prompt

Add a frontmatter field

engine.agent = agentid

That specifies the agent id to pass to copilot --agent flag.

Remove special support in imports to infer the agent value.

This feature is only supported for copilot.

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[github-actions]

🔍 PR Triage Results

Category: feature | Risk: low | Priority: 45/100

Scores Breakdown

• Impact: 35/50 - New feature - medium-high impact
• Urgency: 0/30 - Recent PR
• Quality: 10/20 - Draft PR - needs finalization

📋 Recommended Action: BATCH REVIEW

This PR is suitable for batch review with similar PRs. Consider grouping with other feature PRs for efficient processing.

---

Triaged by PR Triage Agent on 2026-01-30

AI generated by PR Triage Agent

[pelikhan]

@copilot update main json schema

[Copilot]

@copilot update main json schema

Updated. Regenerated documentation from schema in commit 816fea2.

[pelikhan]

@copilot the engine.agentic and tbe agent import at separate orthogonal features

[Copilot]

@copilot the engine.agentic and tbe agent import at separate orthogonal features

Fixed in commit ebc9268. Both features are now orthogonal:

1. engine.agent - Explicit agent ID (new, takes priority)
2. Agent imports - Importing .github/agents/*.md files (existing, still works)

The agent import detection code has been restored. Both methods work independently, with engine.agent taking priority when both are specified.

[pelikhan]

@copilot --agent only controlled by engine.agent

[Copilot]

@copilot --agent only controlled by engine.agent

Fixed in commit 2eec812. The --agent flag is now exclusively controlled by engine.agent. Agent imports only import markdown content and do not set the flag.