archdiagram

# AGENTS.md

Guidance for AI coding agents (Cursor, Claude Code/Desktop, Codex, etc.) using
this repository.

## What this repo does

`archdiagram` converts a JSON architecture **spec** into an editable diagram
whose nodes are official vendor service icons (Azure, AWS, GCP, Kubernetes),
exported as `.pdf`, `.drawio`, or `.vsdx` (all Lucidchart-importable).

Your job as an agent: translate the user's natural-language architecture into
the JSON spec, then render it.

## Two ways to use it

1. **Skill** - read [skill/SKILL.md](skill/SKILL.md) and follow it. It contains
   the spec schema, catalog lookup, and render commands.
2. **MCP server** - run `python -m mcp_server.server` and call the tools
   `validate_spec`, `render_diagram`, `search_catalog`, `list_catalog`. A sample
   client config is in [examples/mcp.json](examples/mcp.json).

## Quick start

```bash
python -m tools.download_icons            # fetch vendor icons into ./icons
cd node && npm install && cd ..           # optional: PDF + crisp raster icons
python -m archdiagram.cli catalog search "kubernetes"
python -m archdiagram.cli render spec.json -f pdf -o out/arch.pdf
```

## Conventions

- Core engine is **stdlib-only** (no third-party Python deps). Keep it that way.
- The `mcp` SDK is allowed **only** under `mcp_server/`.
- Node (`@resvg/resvg-js`, `pdfkit`, `svg-to-pdfkit`) is optional and confined to
  `node/` + `archdiagram/rasterize/`.
- Vendor icons are **not committed**; they are fetched by `tools/download_icons.py`.
- Tests use stdlib `unittest`: `python -m unittest discover -s tests`.


## Cursor↔Claude live-review bridge

A reviewer running in **Cursor** watches the executing agent (**Claude**, in the
terminal) and steers it *without interrupting the chat*, via **bridge files**. This
convention works in every repo (a user-scope hook activates it automatically).

- **Bridge files are named `suggestions_*.md`** — e.g. `plans/suggestions_NN_<slug>.md`
  beside a plan, or a top-level `suggestions_<topic>.md`. The **Cursor reviewer owns**
  them (creates / rewrites / erases). The executor never deletes a reviewer's directives.
- **Claude polls** the relevant `suggestions_*.md` before starting a task and after
  every task/checkbox.
- **`## Open Directives` (`- [ ]`) are binding.** On conflict with the plan/spec body,
  the directive wins (the reviewer has fresher context).
- **Claude acknowledges** under `## Claude Acknowledgements`, ticking `- [ ]` → `- [x]`
  and referencing the code/tests that close each one. Blockers are surfaced there.
- **Automated — no manual nudge.** A user-scope `Stop` hook
  (`~/.claude/hooks/suggestions_watch.py`, wired in `~/.claude/settings.json`) runs at
  the end of every turn: if a `suggestions_*.md` changed and still has unchecked
  directives, it blocks the stop and re-injects them. It baselines on first sight,
  guards against loops, and fails open. Hooks load at session start, so restart an
  in-flight session (or run `/hooks`) if the bridge does not fire.
- **When you are the Cursor reviewer:** write `suggestions_*.md` with a
  `## Open Directives` list of short, testable `- [ ]` items plus a
  `## Claude Acknowledgements` heading, and reference the bridge file from the plan/spec.