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

Copilot CLI Capabilities Inventory

Sourced from pkg/workflow/copilot_engine.go, copilot_engine_execution.go, copilot_engine_tools.go, copilot_mcp.go:

• CLI flags available: --add-dir, --share (not found in execution code this cycle — likely compiler-internal or deprecated; flagged for verification), --disable-builtin-mcps, --no-ask-user, --agent <name>, --autopilot --max-autopilot-continues N, --log-level all --log-dir, --allow-all-paths, --no-custom-instructions, --headless --no-auto-update --host --port (SDK server mode)
• Engine capabilities (EngineCapabilities struct): ToolsAllowlist, MCP, MaxTurns, MaxContinuations (via --autopilot), WebSearch: false (no built-in web search), BareMode (via --no-custom-instructions), BashCommandAllowlist (via --allow-tool shell(cmd)), Plugins: true (Agent Plugins)
• Engine config options: engine.id, engine.version, engine.model, engine.agent (custom persona file), engine.args, engine.env, copilot-sdk: true (SDK/server mode), BYOK via COPILOT_PROVIDER_* env vars
• MCP support: full MCP server rendering via copilot_mcp.go, GitHub MCP gateway proxy mode (github.mode: gh-proxy), MCP scripts
• Sandbox: AWF (Agentic Workflow Firewall) and gVisor (sandbox.agent.runtime: gvisor) supported
• Other: max-tool-denials, strict: true mode, harness retry script (copilot_harness.cjs) for transient CAPIError 400s

Usage Statistics

• Total Workflows: 294
• Copilot Workflows: 108 (~37%)
• cache-memory usage: 80 workflows
• repo-memory usage: 30 workflows
• copilot-sdk: true: 61 workflows (56% of Copilot workflows) — flat for 4 cycles
• max-tool-denials: 55 workflows
• engine.agent (custom persona): 7 workflows — archie, contribution-check, daily-file-diet, glossary-maintainer, hourly-ci-cleaner, technical-doc-writer, workflow-generator
• engine.version pinning: 0 workflows (5th cycle confirming)
• --share flag manual use: 0 workflows
• plugins usage: 0 workflows across all 294
• model overrides: 40+ workflows use model: at various nesting levels (some small/large aliases, some concrete slugs like copilot/gpt-5.4)
• timeout-minutes: highly scattered — 30 (76×), 20 (47×), 10 (47×), 15 (37×), 45 (33×), 5 (17×), 60 (9×), 25 (8×), 90 (3×), 120 (2×), plus several one-offs (8, 35, 40, 180)

🔴 High Priority

Opportunity 1: Create shared/copilot-defaults.md (3rd cycle overdue)

• What: A reusable shared snippet (like existing shared/otlp.md, shared/reporting.md) that bundles recommended Copilot engine defaults: pinned engine.version, sensible model default, and harness retry tuning.
• Why It Matters: Currently every Copilot workflow author manually configures (or omits) version pinning and model choice. A shared import would standardize this in one place and make future CLI upgrades a single-file change instead of 108 individual edits.
• Where: All 108 Copilot workflows could import it; new workflows would get sane defaults automatically.
• How to Implement: Create .github/workflows/shared/copilot-defaults.md with a documented engine: block; update docs/src/content/docs/reference/engines.md to reference it as the recommended pattern.
• Example:

  # shared/copilot-defaults.md
  ---
  engine:
    id: copilot
    version: "0.x.y"  # pin to last-verified-good release
  ---

Opportunity 2: Pin engine.version for Copilot workflows

• What: None of the 108 Copilot workflows pin a CLI version; all float to latest.
• Why It Matters: Reproducibility and supply-chain risk — an upstream Copilot CLI regression or breaking change can silently affect all 108 workflows simultaneously with no rollback path.
• Where: All Copilot workflows, ideally centralized via Opportunity 1's shared snippet.
• How to Implement: Add version: "<pinned>" under engine: in the shared defaults file, override per-workflow only when a newer feature is explicitly needed.

🟡 Medium Priority

Opportunity 3: Investigate copilot-sdk adoption plateau (61/108, flat for 4 cycles)

• What: SDK mode (copilot-sdk: true) growth stalled after an initial adoption wave.
• Why It Matters: If SDK mode has real advantages (session control, structured logs) but the remaining 47 workflows aren't migrating, there may be a friction point (docs gap, missing example, perceived risk) worth investigating directly rather than re-measuring.
• Where: Non-SDK Copilot workflows, e.g. daily-doc-updater.md.
• How to Implement: Survey 3-5 non-SDK workflow authors or check for a known blocking bug; if none found, add a migration note to docs.

Opportunity 4: Decide fate of plugins feature (0% adoption, 5th cycle)

• What: Agent Plugins capability is fully implemented (Plugins: true, GetPluginInstallationSteps) but has zero adoption across all 294 workflows.
• Why It Matters: Either this is a genuinely valuable feature that needs promotion/examples, or it should be deprioritized to stop it showing up as a false "gap" every cycle.
• Where: N/A — repo-wide policy decision needed.
• How to Implement: Maintainer decision: (a) add a documented example workflow using plugins, or (b) mark as experimental/low-priority in docs and stop flagging in future research cycles.

Opportunity 5: Standardize timeout-minutes tiers

• What: Timeout values are scattered across 12+ distinct values (5 through 180 minutes) with no visible tiering convention.
• Why It Matters: Inconsistent timeouts make it hard to reason about expected workflow cost/duration and can mask misconfigured retries or unnecessarily generous budgets.
• Where: Repo-wide.
• How to Implement: Define 3-4 standard tiers (e.g., quick: 10, standard: 20-30, deep-research: 45-60, long-running: 90+) and document them in docs/src/content/docs/reference/engines.md or the shared defaults file.

🟢 Low Priority

Opportunity 6: Promote --share for conversation tracking

• What: --share flag exists for shareable conversation links but is unused; note it wasn't found directly in copilot_engine_execution.go this cycle — worth confirming it's still exposed via engine.args passthrough rather than a first-class flag.
• Why It Matters: Could aid debugging/support workflows if genuinely available; low priority since impact is narrow (debugging convenience).
• Where: Debugging-focused workflows, or none if verification shows the flag isn't currently wired up.
• How to Implement: Verify flag still exists in current CLI; if so, document an opt-in pattern via engine.args: ["--share"].

Opportunity 7: Model slug consistency

• What: Mixed use of alias models (small, large) and concrete slugs (copilot/gpt-5.4, claude-haiku-4.5) across workflows.
• Why It Matters: Minor developer-experience inconsistency; not a functional problem, but complicates auditing which workflows use which real model.
• Where: Repo-wide.
• How to Implement: Document a convention (e.g., prefer aliases for sub-agents, concrete slugs for primary agent) in the shared defaults file.

Workflow: daily-doc-updater.md

• Current State: Uses engine: copilot without copilot-sdk: true or version pin.
• Recommended Changes: Adopt shared/copilot-defaults.md once created; consider SDK mode.
• Expected Benefits: Standardized configuration, reproducible CLI version.

Workflow: workflow-health-manager.md

• Current State: Already uses repo-memory with custom max-file-size/max-patch-size tuning — a good example of advanced feature usage worth referencing in docs as a pattern.
• Recommended Changes: None urgent; could be cited as a best-practice example in engine docs.
• Expected Benefits: Documentation value for other authors.

Workflow: archie.md

• Current State: Good example of engine.agent: adr-writer custom persona usage.
• Recommended Changes: None; flag as a reference example for the 6 other agent-persona workflows and for documentation.
• Expected Benefits: Helps close the awareness gap for engine.agent seen in earlier cycles' undercounting.

Comparing against runs on 08-23, 08-24, 08-25, and 08-26:

• copilot-sdk: true: flat at 61 for a 4th consecutive measurement — confirmed genuine plateau, not noise.
• engine.agent: corrected this cycle. Run 4 reported 0 due to an overly strict query; ground-truth check confirms 7 genuine engine.agent usages (archie, contribution-check, daily-file-diet, glossary-maintainer, hourly-ci-cleaner, technical-doc-writer, workflow-generator), consistent with runs 2-3's ~7 estimate.
• shared/copilot-defaults.md: still not created — 3rd cycle since recommendation, 2nd cycle since escalation. This is the most persistent unactioned item across the research history.
• engine.version pinning, --share, plugins: all confirmed at 0% for a 5th consecutive cycle.
• max-tool-denials: stable at 55 (matches run 3/4).
• cache-memory/repo-memory/total workflow counts: this cycle measured 80/30/294 for cache-memory/repo-memory/total, roughly matching run 4's figures (80/30/294), suggesting the run-4 methodology (vs. run 2/3's higher counts) is the more consistent baseline going forward.