[copilot-cli-research] Copilot CLI Deep Research - 2026-08-25

Copilot CLI Capabilities Inventory (from pkg/workflow/copilot_engine*.go)

• CLI flags emitted by compiler automatically: --add-dir (workspace/tmp/agent dirs, cache-memory dirs, drive-memory dirs), --log-level all, --log-dir, --disable-builtin-mcps, --no-ask-user (v1.0.19+), --agent <name> (from engine.agent), --autopilot --max-autopilot-continues N (from max-continuations > 1), --allow-all-paths (when edit tool enabled), --no-custom-instructions (bare mode), --share <path> (internal detection-job use only), --headless --no-auto-update --host --port (copilot-sdk server mode).
• Engine configuration fields: engine.id, engine.version, engine.model, engine.args (raw passthrough), engine.env, engine.agent, engine.bare, engine.max-continuations, engine.copilot-sdk, engine.max-tool-denials (top-level, Copilot-only).
• MCP integration: pkg/workflow/copilot_mcp.go supports stdio and HTTP MCP servers, GitHub MCP in gh-proxy/direct modes with toolsets: filtering.
• Sandbox/network options: AWF firewall (network: {allowed: [...]}), sandbox.agent.runtime (gvisor/docker-sbx/cloud-hypervisor/docker-sudo-iptables).
• Other: plugins: (Agent Plugins format), cache-memory, repo-memory, cli-proxy tool.

Usage Statistics

• Total Workflows: 292
• Copilot Workflows: 109 (~37%)
• copilot-sdk: true: 61 workflows
• cli-proxy: true (GitHub tool proxy): 205 workflows
• gh-proxy GitHub MCP mode: 156 workflows
• cache-memory: 105+ workflows
• max-tool-denials: 55 workflows
• sandbox.agent.runtime: gvisor: 35 workflows
• bare: true: 21 workflows
• engine.version pinned for copilot: 0 workflows
• --share used manually: 0 workflows
• plugins: used: 0 workflows
• engine.agent (real custom personas): ~7 workflows

🔴 High Priority

Opportunity 1: Pin engine.version for Copilot workflows

• What: No workflow specifies engine.version, so every run uses whatever CLI version is resolved at compile/install time.
• Why It Matters: A CLI update with a breaking flag change or behavior shift would affect all 109 Copilot workflows at once with no easy rollback; scheduled/cron workflows are especially exposed since there's no PR review gate for the version bump.
• Where: All Copilot workflows, especially scheduled ones like weekly-editors-health-check.md, stale-pr-cleanup.md, daily-doc-updater.md.
• How to Implement: Add version: "<pinned-version>" under engine: in a shared defaults snippet, bump deliberately via PR.
• Example:

  engine:
    id: copilot
    version: "0.0.339"
    copilot-sdk: true

Opportunity 2: Adopt --share for debugging-critical workflows

• What: The compiler already knows how to emit --share <path>/conversation.md (used internally for detection jobs) but no workflow author-facing config surfaces this for the main agent run.
• Why It Matters: Workflows performing complex, multi-step reasoning (e.g. architecture-guardian.md, breaking-change-checker.md) would benefit from an exportable, human-readable conversation transcript artifact for post-run review, independent of the JSONL session logs.
• Where: Complex/long-running Copilot workflows with max-tool-denials or max-continuations set.
• How to Implement: Expose a documented engine.share-conversation: true (or similar) frontmatter option that adds --share and uploads the resulting file as a workflow artifact.

Opportunity 3: Enable Agent Plugins on at least pilot workflows

• What: plugins: (Agent Plugins format) has been documented as Copilot-supported for at least 3 research cycles with zero adoption.
• Why It Matters: Plugins could reduce duplicated tool/MCP boilerplate across the 109 Copilot workflows and give a standard extension point instead of ad hoc imports:.
• Where: Any workflow currently importing multiple shared snippets for tool config, e.g. ci-coach.md, code-scanning-fixer.md.
• How to Implement: Pilot one workflow with a minimal plugins: block per the Agent Plugins format and measure whether it simplifies frontmatter versus current imports:-heavy patterns.

🟡 Medium Priority

Opportunity 4: Increase adoption of engine.agent custom personas

• What: Only ~7 of 109 Copilot workflows set a real engine.agent value; the mechanism exists (archie.md → adr-writer, contribution-check.md → contribution-checker) but is rarely reused elsewhere.
• Why It Matters: Custom agent files centralize persona-specific instructions/behavior and reduce prompt duplication in workflow markdown bodies.
• Where: Workflows with long, repeated instruction blocks that resemble a specialized persona (e.g. tidy.md, craft.md).
• How to Implement: Extract common instruction patterns into .github/agents/*.md and reference via engine: {id: copilot, agent: <name>}.

Opportunity 5: Standardize model slug conventions

• What: Mixed usage of size aliases (small/large, 48 combined), CLI-prefixed slugs (copilot/gpt-5.4, copilot/claude-sonnet-4.5), and bare vendor slugs (claude-sonnet-4.6, gpt-5.4-mini) with no documented policy on when to use which form.
• Why It Matters: Makes it hard to audit cost/quality trade-offs fleet-wide or bulk-migrate model versions.
• Where: All Copilot (and other-engine) workflows.
• How to Implement: Document a convention (e.g., "use size aliases for routine automation, explicit slugs only for benchmarked/critical workflows") in .github/aw/github-agentic-workflows.md.

Opportunity 6: Create a shared/copilot-defaults.md snippet

• What: shared/otlp.md exists for telemetry defaults, but no equivalent exists for common Copilot engine settings (version pin, harness/retry tuning, --no-custom-instructions policy).
• Why It Matters: Would let all 109 Copilot workflows inherit best practices via a single imports: line rather than duplicating engine config, and is the natural vehicle for fixing Opportunities 1 and 5 at scale.
• Where: New shared file, imported by existing Copilot workflows incrementally.
• How to Implement: Add .github/workflows/shared/copilot-defaults.md with a pinned engine: block; migrate 2-3 workflows as a pilot.

🟢 Low Priority

Opportunity 7: Document --allow-all-paths interaction more explicitly

• What: --allow-all-paths is auto-added whenever the edit tool is enabled (per github.com/github/copilot-cli/issues/67), but this is an implicit side-effect not obvious from workflow frontmatter.
• Why It Matters: Workflow authors may be surprised by broadened path permissions when they only intended to enable file editing.
• How to Implement: Add a note in docs/src/content/docs/reference/engines.md clarifying this automatic linkage.

Opportunity 8: Broaden network: allowed: [defaults] explicit usage

• What: Only 1 workflow explicitly sets allowed: [defaults]; most either omit network: or hand-list domains, though 169 workflows configure network: in some form.
• Why It Matters: Explicit [defaults] improves readability/auditability versus implicit behavior.
• How to Implement: Low-effort documentation nudge; not urgent.

Opportunity 9: Investigate docker-sbx/cloud-hypervisor sandbox adoption

• What: These stronger isolation runtimes exist but weren't measured as widely adopted versus gvisor (35 workflows).
• Why It Matters: Security-sensitive workflows (auto-merge, code-scanning-fixer) may benefit from stronger isolation guarantees.
• How to Implement: Follow-up research to quantify adoption and identify candidate workflows for upgrade.

Workflow: weekly-editors-health-check.md / daily-doc-updater.md / stale-pr-cleanup.md (scheduled, engine: copilot)

• Current State: Simple engine: copilot form, no version pin, no --share.
• Recommended Changes: Migrate to engine: {id: copilot, version: "<pinned>"} once a shared defaults snippet exists.
• Expected Benefits: Predictable, auditable CLI version across scheduled runs.

Workflow: archie.md / contribution-check.md

• Current State: Already using engine.agent custom personas — good examples to reference/document as the pattern for others.
• Recommended Changes: None needed; use as internal documentation examples for Opportunity 4.

Workflow: architecture-guardian.md / breaking-change-checker.md

• Current State: copilot-sdk: true, max-tool-denials: 3, no conversation export.
• Recommended Changes: Pilot --share-based conversation export (Opportunity 2) here given their complex multi-step reasoning.
• Expected Benefits: Easier post-hoc debugging of nuanced decisions.

This is the third research cycle (previous runs: 2026-08-23, 2026-08-24; this run: 2026-08-25).

• Persistent gaps across all 3 runs: engine.version pinning (still 0), --share manual usage (still 0), Agent Plugins (still 0%). These are stable, repeated findings — worth escalating from "opportunity" to a concrete tracked action item since data confirms they are not organically improving.
• Adoption growth: copilot-sdk: true steady at 61 (unchanged from run 2), cache-memory/repo-memory usage continues to be common, max-tool-denials now measured at 55 (new metric this run, not directly comparable to prior runs' data).
• Custom agent adoption stagnant: ~7 workflows across all 3 runs — no growth despite being flagged as an opportunity twice before.
• No shared Copilot-defaults snippet created yet despite being recommended in run 2 — still open.