bug: agentic workflows fail with token limit overflow when repository has comprehensive custom instructions

[bindsi]

bug: agentic workflows fail with token limit overflow when repository has comprehensive custom instructions

Problem

Agentic workflows fail with CAPIError: 400 prompt token count exceeds the limit in repositories with comprehensive .github/ directories because the Copilot CLI auto-discovers and injects all custom instructions into the prompt unconditionally — exceeding the model's token limit before the workflow prompt is even processed. This makes agentic workflows broken out of the box for any serious prompt engineering or enterprise repository.

Large repositories should not be a problem. The whole point of agentic workflows is to automate work in real-world repositories — and real-world repositories grow. A repo with comprehensive coding standards, multiple agent definitions, and domain-specific skills is exactly the kind of repo that benefits most from automation. The current behavior punishes repos for being well-organized and instruction-rich, which is the opposite of what we want to encourage.

Context

Our repository (microsoft/hve-core) is a prompt engineering tooling project. The .github/ directory contains:

Path	Size	Approx. Tokens
.github/instructions/	~878 KB	~220K
.github/agents/	~517 KB	~130K
.github/skills/	~374 KB	~94K
Total	~2.6 MB	~440K+

The Copilot CLI 168K token limit is exceeded before the workflow prompt even gets a chance to run. But this is not an unreasonable repository — it's a well-structured project with organized instructions across multiple domains (coding standards, design thinking, security, ADO integration). Any enterprise repository with multiple teams contributing standards will hit similar sizes. Agentic workflows need to scale alongside the repos they serve, not collapse under them.

Reproduction

1. Create a repository with a large .github/instructions/ directory (>500 KB of .instructions.md files)

2. Create a simple agentic workflow:

   ---
   on:
     issues:
       types: [labeled]
       names: [agent-ready]
   engine: copilot
   ---
   
   # Implement the issue
   Read the issue and implement the requested change.

3. Trigger the workflow

4. The agent job fails with:

   CAPIError: 400 prompt token count of 186803 exceeds the limit of 168000
   

5. The workflow prompt itself is only ~5K tokens — the remaining ~181K comes entirely from auto-discovered custom instructions

Root Cause

The Copilot CLI auto-discovers and loads all files matching these patterns from $GITHUB_WORKSPACE:

• .github/copilot-instructions.md
• .github/instructions/**/*.instructions.md
• .github/agents/**/*.agent.md
• .github/skills/**/SKILL.md

There is no mechanism to:

• Filter which instruction files are loaded
• Set a token budget for auto-discovered content
• Exclude specific directories or files from discovery

The CLI has --no-custom-instructions but gh aw doesn't expose it, and it's too blunt (disables all instructions, including the ones the workflow actually needs).

Current Workaround

We use sparse-checkout in the workflow frontmatter to physically exclude heavy directories from disk so auto-discovery can't find them:

checkout:
  sparse-checkout: |
    .github/copilot-instructions.md
    .github/instructions/coding-standards/
    .github/instructions/hve-core/
    .github/instructions/shared/
    scripts/
    package.json

This works but is brittle and shifts the burden to every workflow author:

• Each workflow must manually curate which instruction subdirectories exist on disk
• Adding new instructions to the repo can silently break workflows by pushing them over the token budget
• The workflow author needs to know the byte sizes of every instruction directory to stay under budget
• It conflates "what files the agent can access" with "what instructions the agent should follow" — two fundamentally different concerns

Proposal

One or more of the following would solve this cleanly:

Option A: Frontmatter-level instruction filtering

custom-instructions:
  include:
    - .github/instructions/coding-standards/
    - .github/instructions/hve-core/
  exclude:
    - .github/agents/
    - .github/skills/

Option B: Expose --no-custom-instructions in frontmatter with imports as the sole instruction source

custom-instructions: false
imports:
  - ../agents/hve-core/task-implementor.agent.md

This would mean: "don't auto-discover anything, only use the explicitly imported files." This is the cleanest separation — imports for instructions, checkout for file access.

Option C: Token budget cap for auto-discovered content

Auto-discovered instructions are truncated or pruned (least-relevant-first) when they approach a configurable fraction of the model's context window, preserving space for the workflow prompt and conversation.

Why This Matters

The value proposition of agentic workflows grows with repository maturity. Repos that invest in coding standards, security instructions, and domain-specific agents are the repos that get the most out of automation. The current all-or-nothing auto-discovery makes agentic workflows progressively harder to use as repos mature — exactly when they should be getting easier.

Environment

• gh aw version: v0.63.1
• Copilot CLI: standalone mode (COPILOT_AGENT_RUNNER_TYPE: STANDALONE)
• Model token limit: 168,000

[pelikhan]

Good one. As we are looking into better controlling the agentic tooling environment, this is something we will want full control over.