iago CLAUDE.md

CLAUDE.md

Single source of truth for every coding agent (Claude Code, Codex, Cursor, Aider, Copilot, Gemini, …) working on or with this repo. When this file and any other doc disagree, this file wins.

Project overview

Iago is a skill for AI coding agents that appends a Mermaid diagram (sequence / flow / class / entity-relation) to a GitHub pull request's /review comment. The host agent draws the diagram with the LLM it's already running; Iago's helper posts it via gh. The diagram type is auto-detected from the diff (overridable).

It is skill-first, distributed three ways:

• skill folders (iago/, squawk/) copied into an agent's skills dir,
• a Claude Code plugin (.claude-plugin/),
• a TypeScript installer CLI (cli/, published as @drakulavich/iago).

Critical rules (read before changing anything)

• No GitHub Action. Iago used to ship a server-side Action with its own LLM-provider SDKs + a heuristic fallback. That was removed deliberately. Do not reintroduce an Action, an API-key/provider path, or a heuristic diagram generator — the diagram is always drawn by the host agent's LLM.
• Runtime is bun + gh, nothing else. The helper (iago/scripts/post.ts) is TypeScript run by bun; GitHub writes go through authenticated gh. The old install.sh (shell) and sanitize_mermaid.py (Python) were removed — don't bring shell/python back into the skill runtime.
• The skill folder stays dependency-free. iago/scripts/*.ts may import only Node built-ins (node:*) + each other. Never add a package.json or node_modules under iago/ — the folder is copied verbatim into agent dirs.
• Mermaid: never use reserved keywords as participant/node ids. loop, alt, opt, par, note, end, activate (case-insensitive) break GitHub's renderer. (Incident: a participant Loop made sequence.md fail to render.) Likewise never start an unquoted flowchart node label with @ — Mermaid lexes [@ as edge-ID/shape syntax (incident: N[@utils/utils -> …] killed a posted diagram; sanitize.ts now auto-quotes these). Repo example diagrams are parse-validated by cd cli && bun test (cli/tests/mermaid-validation.test.ts); field rendering incidents go into cli/tests/fixtures/mermaid/{valid,invalid}/ verbatim.
• post.ts gh PATCH uses -f (raw-field), not -F. gh api -F/--field treats a leading @ as a file-read; comment bodies starting with @mention would break. -f/--raw-field is the safe static-string flag. Keep it.
• Never commit local dev state. .omc/, .claude/, .codegraph/ are gitignored. Do not git add -A — stage files explicitly. (These dirs were once swept into a PR by git add -A.)
• Versions stay aligned. cli/package.json, .claude-plugin/plugin.json, and .claude-plugin/marketplace.json (both version fields) move together.
• No eval suite. Diagram quality is validated by dogfooding (run /iago on real PRs when the rubric changes), not a formal benchmark — a deterministic classifier no longer exists in skill-first, and an LLM-judge harness is overkill here. Don't rebuild evals/.