Feature: Native `workflow.instructions` config for auto-loading repo convention files

[franklixuefei]

Feature: Native workflow.instructions config for auto-loading repo convention files

Summary

Conductor should natively support discovering and injecting repository instruction files (coding standards, architecture patterns, conventions) into agent context. Today, agents start with no awareness of repo conventions — they must discover them via tool calls, which is unreliable, wasteful, and inconsistent across providers.

Problem

Repositories increasingly use instruction files to codify conventions for AI coding assistants:

File Pattern	Purpose
.github/instructions/*.instructions.md	AI assistant instructions with applyTo glob patterns
.github/copilot-instructions.md	Global AI assistant instructions
CONTEXT.md	Domain glossary, bounded context definitions
CONTEXT-MAP.md	Multi-context repository maps

Host environments (Copilot CLI, Cursor, VS Code) automatically inject these into their sessions. Conductor agents are independent sessions that don't inherit this — regardless of which provider (copilot, claude, or future providers) is used.

Current workaround

A type: script agent can be added to workflow YAMLs to glob + cat instruction files at workflow start (see azure-core/octane#534). This works but has limitations:

• Every workflow template must add the script agent manually
• Platform-specific (sh vs powershell) — workflow authors must handle both
• No semantic understanding of applyTo patterns — dumps all instructions regardless of relevance
• No integration with conductor's context management — instructions are just raw stdout

Proposed Feature

Add a workflow.instructions config to conductor core that handles instruction file discovery and injection as a first-class capability.

API Design

workflow:
  name: my-workflow
  
  instructions:
    # Option 1: Auto-discover (recommended default)
    auto_discover: true
    # Scans for known instruction file patterns:
    #   .github/instructions/**/*.md
    #   .github/copilot-instructions.md
    #   CONTEXT.md
    #   CONTEXT-MAP.md
    
    # Option 2: Explicit paths
    paths:
      - .github/instructions/
      - CONTEXT.md
      - docs/conventions.md
    
    # Control which agents receive instructions (default: all)
    inject_into: [coder, epic_reviewer, fixer]
    # Or: inject_into: all  (default)
    
    # Control injection position in agent prompt
    position: system  # 'system' (append to system_prompt) or 'context' (add to context)

Behavior

1. At workflow initialization (before any agent runs):

   • Scan working directory for instruction files matching configured patterns
   • Read and parse each file, extracting any applyTo metadata from frontmatter
   • Store as structured instruction context

2. Per agent execution:

   • For agents listed in inject_into, prepend/append instruction content to their system prompt or context
   • If instruction files have applyTo glob patterns, only inject instructions relevant to the files the agent is working with (matched against the epic's file list)

3. Graceful degradation:

   • If no instruction files found, proceed normally (no error)
   • If instructions config is omitted, no scanning occurs (backward compatible)

applyTo pattern matching (advanced)

Instruction files often have frontmatter like:

---
applyTo: "**/*.cs"
---
# C# Coding Standards
...

When an epic specifies files it will touch, conductor could match instruction files by applyTo patterns and only inject relevant ones. This keeps agent context focused.

Why this belongs in conductor core (not workflow YAML)

Concern	type: script workaround	Native workflow.instructions
Platform handling	Workflow author writes sh + powershell variants	Conductor handles internally
applyTo matching	Not possible — dumps everything	Matches instructions to epic file patterns
Context management	Raw stdout in accumulated context	Structured injection into system prompt or context
Reusability	Every workflow template must add the script	One config line, works for all workflows
Provider independence	Script output format varies	Consistent injection regardless of provider

Design Principles

1. Opt-in, backward compatible — no instructions config = no scanning, zero behavior change
2. Provider-agnostic — works identically with copilot, claude, or any future provider
3. Deterministic — file I/O at initialization, no LLM involvement in discovery
4. Efficient — read files once, reuse across all agent iterations
5. Composable — works with existing context.mode settings without conflict

References

• azure-core/octane#534 — immediate type: script workaround for implement.yaml
• .github/instructions — GitHub Copilot instruction files documentation