AI Prompt Files — ai/ Folder

Overview

The ai/ folder contains all AI agent prompt files — rulebooks that govern how autonomous agents (opencode, CI workflows) operate on this repository. These files are NOT project documentation; they are agent instructions.

Files

File	Purpose	Used by
ai/AGENTS.md	Master rulebook — modernization rules, workflow etiquette, CI factory awareness	modernize.yml, fix-bug.yml, fix-bug-oldest.yml, merge-stale-branches.yml, opencode.json
ai/FIX-ISSUE.md	Bug-fixing rulebook — how to pick, fix, document, and close issues	fix-bug.yml, fix-bug-oldest.yml
ai/ISSUES.md	Documentation rulebook — how to document bugs (INVESTIGATION → ROOT CAUSE → FIX → VERIFY)	fix-bug.yml, fix-bug-oldest.yml
ai/MERGE-STALE-BRANCHES.md	Branch merge rulebook — how to safely merge stale fix/* branches	merge-stale-branches.yml

Why ai/ (not root)?

• Root is for project files (README, config, code)
• Prompt files are agent-specific instructions, not project docs
• Keeps root clean and makes the agent system obvious to new contributors
• opencode.json points to ai/AGENTS.md as the entry point

How agents find these files

1. opencode.json → "instructions": ["ai/AGENTS.md"] (local dev)
2. CI workflows → "instructions": ["ai/AGENTS.md", "ai/FIX-ISSUE.md", "ai/ISSUES.md"] (embedded in each workflow)
3. PROMPT strings in workflows → "Read ai/AGENTS.md in the repo root FIRST..."

Cross-references

• ai/AGENTS.md → references ai/FIX-ISSUE.md (rule 18)
• ai/FIX-ISSUE.md → references ai/AGENTS.md (line 5)
• ai/MERGE-STALE-BRANCHES.md → references ai/ISSUES.md (line 8)

Adding new prompt files

1. Create the file in ai/
2. Add it to the relevant workflow's "instructions": [...] array
3. Add a PROMPT line in the workflow: "Read ai/FILENAME.md in the repo root FIRST..."
4. Update this wiki page