# Iago

> Append a Mermaid diagram (sequence, flow, class, or entity-relation) to a GitHub PR's existing /review comment. Like Iago the parrot from Aladdin, this skill loudly squawks a visual summary on top of an existing review. Also triggered by /squawk. Use after the /review skill finishes, or when the user asks to add/append a diagram to a pull request review, or says "squawk". Auto-detects the most us…

- **Type:** Skill
- **Install:** `agentstack add skill-drakulavich-iago-iago`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [drakulavich](https://agentstack.voostack.com/s/drakulavich)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [drakulavich](https://github.com/drakulavich)
- **Source:** https://github.com/drakulavich/iago/tree/main/iago
- **Website:** https://drakulavich.github.io/iago/

## Install

```sh
agentstack add skill-drakulavich-iago-iago
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# PR Diagrams — append Mermaid diagrams to /review output

You generate ONE Mermaid diagram that visualizes the most important change in a
pull request and append it to the existing `/review` comment on that PR (so the
diagram lives next to the rest of the review, not as a separate comment).

GitHub and GitLab natively render fenced ` ```mermaid ` code blocks, so no
external service is needed.

---

## Inputs

Parse `$ARGUMENTS` permissively:

- **PR number** — first integer-looking token. If absent, derive it:
  1. `gh pr view --json number -q .number` (current branch).
  2. If that fails, fall back to `gh pr list --head "$(git rev-parse --abbrev-ref HEAD)" --json number -q '.[0].number'`.
  3. If still unknown, ask the user.
- **Type override** — one of: `sequence`, `flow`, `class`, `er`
  (aliases: `flowchart` → `flow`, `entity-relation` / `entity` / `erd` → `er`).
  If absent, auto-detect (see below).
- **Mode** — `--mode=append` (default) or `--mode=comment`.
  `append` edits the existing /review comment; `comment` posts a new standalone comment.
  If no /review comment is found in `append` mode, fall back to `comment` and tell the user.

---

## Workflow

1. **Resolve the PR.**
   - `PR=` from arguments or detection above.
   - `REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner)`.

2. **Gather context.** Run in parallel where possible:
   - `gh pr view "$PR" --json title,body,files,baseRefName,headRefName,additions,deletions`
   - `gh pr diff "$PR"` (capture full diff; if it exceeds ~150 KB, fall back to `gh pr diff "$PR" --name-only` plus targeted `git diff` per file).
   - List changed files; classify each by extension and path.

3. **Pick the diagram type** (skip if user passed an override):

   Apply these rules in order — first match wins. See
   `references/diagram-selection.md` for the full rubric and tie-breakers.

   | Signal in the diff | Type |
   |---|---|
   | Migration files, schema/model changes, `*.sql`, `*.prisma`, `models/*.py`, ORM entity files | `er` |
   | New/changed classes, inheritance, interfaces, traits across ≥2 OO files | `class` |
   | Cross-service calls, new HTTP/RPC handlers, queue producers/consumers, multi-component request flow | `sequence` |
   | Control-flow / business-logic changes inside one component, new conditionals, state machines | `flow` |
   | Trivial change (docs-only, single-line fix, dependency bump, formatting) | **none — abort with a friendly note, do not post** |

4. **Build the Mermaid block.**

   Follow `references/mermaid-templates.md` for syntax patterns. Hard rules:

   - Use exactly one fenced block: ` ```mermaid ` … ` ``` `.
   - Keep it under ~40 nodes / ~60 edges. If the change is bigger, abstract — group by module/service, not by individual function.
   - Use real names from the diff (functions, classes, services, tables) — never placeholders like `ServiceA`.
   - For `sequence`: label arrows with the actual method/endpoint, mark async with `-)`, sync with `->>`.
   - For `flow`: prefer `flowchart TD`; use `{}` for decisions, `[]` for steps, `[[ ]]` for subroutines.
   - **Never start an unquoted node label with `@`.** Mermaid parses `[@` as
     its edge-ID/shape syntax, so `N[@utils/utils -> x]` fails the whole
     diagram. Wrap the label in double quotes: `N["@utils/utils -> x"]`.
     (`@` in the middle of a label is fine.)
   - For `class`: include only classes touched by the diff plus their direct collaborators; show new members with `+` and removed with `-`.
   - For `er`: only include tables/entities touched by the migration plus their FK neighbors.
   - No HTML, no inline styles unless necessary for readability. No emoji in node labels.
   - **Never put `;` inside a `sequenceDiagram` message label.** GitHub's Mermaid
     parser treats `;` as a statement separator inside sequence diagrams, so
     `Boot-->>User: printUsage(); exit 0` is split into two statements and
     the trailing half breaks the diagram. Use `,` or split into two
     messages. This is the most common rendering failure in this skill —
     re-read your generated block and replace any `;` with `,` in message
     labels before continuing.

5. **Wrap it.** Produce this exact block (the markers let later runs find and replace it idempotently):

   ```markdown
   
   ### 🗺️ Change diagram — 

   _Auto-generated by [iago](https://github.com/drakulavich/iago). Edit or remove this block; it will be replaced on the next run._

   ```mermaid
   
   ```
   
   ```

6. **Append (or replace) in the /review comment.**

   **You MUST use the helper script. Do NOT call `gh pr comment`,
   `gh api -X PATCH .../comments/...`, or any other direct GitHub write
   yourself for the diagram.** The script is the only sanctioned write path:
   it locates the right comment, idempotently replaces any prior iago block,
   handles new-comment fallback, and runs a deterministic Mermaid sanitizer
   that catches model mistakes (e.g. stray `;` in sequence message labels)
   before posting. Bypassing it means the diagram ships unchecked and is
   the #1 source of broken renders.

   The helper lives at `scripts/post.ts` in this skill's own directory (run
   with `bun`). Different runtimes expose that directory differently —
   `${CLAUDE_SKILL_DIR}` in Claude Code, `${OPENCODE_SKILL_DIR}` in OpenCode,
   etc. Pick the one your runtime sets, or resolve it from the path of this
   `SKILL.md` file (typically `~/.claude/skills/iago/`,
   `~/.agents/skills/iago/`, or `~/.config/opencode/skills/iago/`).

   Required tools: **bun** + **gh** (GitHub CLI, authenticated).

   ```bash
   # Pick the env var your runtime sets, or substitute the absolute path:
   SKILL_DIR="${CLAUDE_SKILL_DIR:-${OPENCODE_SKILL_DIR:-$(dirname "$0")}}"
   bun run "$SKILL_DIR/scripts/post.ts" \
     --repo "$REPO" \
     --pr "$PR" \
     --mode "$MODE" \
     --diagram-file "$DIAGRAM_FILE"
   ```

   Where `$DIAGRAM_FILE` is a temp file you wrote in step 5 containing the full
   wrapped block. The script:
   - Locates the most recent comment authored by the /review skill (matched via the marker ``, falling back to the most recent comment authored by the current user that contains the heading `## Review` or `# Review`).
   - If found and `--mode=append`: updates that comment via `gh api -X PATCH /repos/{owner}/{repo}/issues/comments/{id}`. Replaces any prior `iago:begin/end` block in place; otherwise appends the new block to the bottom.
   - If not found, or `--mode=comment`: posts a new comment via `gh pr comment`.
   - Prints the URL of the updated/created comment.

7. **Report back.** In your final message:
   - State the chosen type and why (one sentence).
   - Include the comment URL.
   - If you abstained (trivial PR), say so.

---

## Behavioral guardrails

- **Never** open a new PR, push commits, or modify code. This skill is read-only against the repo and write-only against PR comments.
- **Never** post more than one `iago` block per PR — always replace the previous one.
- If `gh` is not authenticated (`gh auth status` fails), stop and tell the user.
- If the diff is empty, stop and tell the user — there is nothing to diagram.
- If the user says "no diagram needed" or the PR is labeled `skip-diagram` / `no-diagram`, stop without posting.

---

## Examples

See `examples/` for sample outputs across all four diagram types.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [drakulavich](https://github.com/drakulavich)
- **Source:** [drakulavich/iago](https://github.com/drakulavich/iago)
- **License:** MIT
- **Homepage:** https://drakulavich.github.io/iago/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-drakulavich-iago-iago
- Seller: https://agentstack.voostack.com/s/drakulavich
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.