aifmt: Instructions file for Codex

aifmt Agent Instructions

What is this project?

aifmt is an MCP server + Copilot CLI plugin that makes visual text content "just work" in AI coding assistants. It fixes, validates, and generates diagrams, tables, box-drawing art, and tree diagrams.

⚠️ CRITICAL: You Cannot Verify Rendering — Humans Must

This is the single most important rule for working on this project.

You (the AI) cannot see how text renders on GitHub, in terminals, or in any visual context. You can read source code and count characters, but you cannot verify that a box, table, or tree diagram actually looks correct when rendered.

Every visual output claim must be verified by a human looking at the rendered result. This means:

1. Never say "this looks correct" or "this is fixed" — you don't know that. Say "this is what the fixer produces — please verify on GitHub."
2. Never hand-write visual content (boxes, tables, trees) and claim it's correct. Always generate it by running the actual fixer code, then ask the human to verify.
3. When writing tests, the expected output for visual content should be human-verified, not assumed. Use # FIXME: human-verify comments for unverified expected values.
4. When fixing a visual bug, push to GitHub and ask the user to check the rendered result. A passing test does NOT mean the output renders correctly — the test might be checking the wrong thing.
5. The fixer's math can be wrong even when tests pass. We discovered that emoji = 2.5 cols on GitHub (not 2.0) only because a human looked at screenshots. No amount of unit testing would have caught that.

The Development Loop

You write code → You run tests → Tests pass → You push →
Human checks rendered output → Human reports what's wrong →
You fix → repeat

Do NOT skip the human verification step. Do NOT claim work is done until the human confirms the rendered output is correct.

Key Discovery: GitHub Emoji = 2.5 Columns

Through empirical testing (human screenshots), we discovered: