Problem

Zeph's system prompt is fully hardcoded in crates/zeph-core/src/context.rs. There is no mechanism to load project-specific instruction files at runtime, and no support for the instruction file conventions used by other AI coding agents.

Different providers and tools use different standard filenames:

When developers have these files in their repo (which most do), Zeph ignores them — missing critical project-specific context that other agents receive.

Proposed Solution

1. Auto-detection by active provider

On startup, InstructionLoader scans CWD for provider-standard files based on the active llm.provider and orchestrator providers:

When multiple providers are active (orchestrator), the union of detected files is loaded with deduplication.

2. Config options

[agent]
instruction_auto_detect = true   # enable auto-detection (default: true)
instruction_files = []           # explicit list overrides auto-detect

[llm]
instruction_file = ""            # per-provider override

[orchestrator.providers.<name>]
instruction_file = ""            # per-orchestrator-provider override

3. System prompt injection

Instruction file content is injected between the static preamble and the skills block:

[static preamble]
[instruction file blocks — one per file, with source path header]
[skills XML block]
[tool catalog]

Implementation Plan

1. zeph-core/src/instructions.rs — new InstructionLoader module
   • load_instructions(config, provider_kinds) -> Vec<InstructionBlock>
   • InstructionBlock { source: PathBuf, content: String }
2. zeph-core/src/context.rs — add instructions: &[InstructionBlock] to build_system_prompt()
3. zeph-core/src/config/types.rs — extend AgentConfig, LlmConfig, OrchestratorProviderConfig
4. zeph-core/src/agent/mod.rs — invoke loader on startup
5. config/default.toml — document new fields

Full research and design: .local/plan/provider-instruction-files.md

References

• AGENTS.md spec: https://developers.openai.com/codex/guides/agents-md/
• GEMINI.md docs: https://geminicli.com/docs/cli/gemini-md/
• CLAUDE.md docs: https://code.claude.com/docs/en/memory
• Open AGENTS.md standard: https://agents.md/
• Aider conventions: https://aider.chat/docs/usage/conventions.html
• Cursor rules: https://cursor.com/docs/context/rules

Out of Scope

• Per-directory recursive scanning (Gemini/Codex style) — deferred
• Hot-reload of instruction files at runtime — separate issue
• TUI panel to display loaded instruction files — separate issue