amcli: Instructions file for Claude Code

amcli — notes for agents working on this repo

amcli is a CLI over ArchiMate model files. Rust workspace, one static binary, no runtime dependencies.

The rule that overrides everything else

A parse-then-write round trip must be byte-identical. If a change makes tests/corpus fail the identity test, the change is wrong — not the test. The whole product proposition is that editing a model produces a diff a human can review, and that only holds if untouched bytes stay untouched.

Practically: never re-serialize what you did not edit. amcli-xml blits untouched subtrees straight out of the source buffer, and any new code that touches the document must preserve that property.

Layout

Crate	Job
crates/amcli-xml	Format-preserving XML tree with byte spans. Knows nothing about ArchiMate.
crates/amcli-model	The ArchiMate IR: types, folders, concepts, views, containers (plain XML or the ZIP an embedded image makes of it).
crates/amcli-view	View geometry, layout, notation — and icons.rs, the type icons.
crates/amcli-render	A compiled view to SVG, or to PNG through resvg (pure Rust, so the binary stays static).
crates/amcli-cli	The binary; src/web/ is amcli web, the read-only viewer.
xtask	Codegen from the vendored Archi assets.

skills/amcli/ is shipped, not documentation

npx skills add arslanr-com/amcli copies that directory out of the default branch verbatim, and crates/amcli-cli/src/skill.rs embeds the same files with include_str! for the binary-first route. Both routes must produce identical bytes — both_install_routes_ship_the_same_bytes walks the directory and fails if a file is there but not in FILES.

Consequences worth knowing before you edit it:

• Nothing may be generated into it. A file written only by skill install makes the two routes differ; a committed generated file goes stale on the next release. That is why there is no references/commands.md and why amcli skill commands exists instead.
• The executable bit does not survive. The skills CLI has two install paths, and its blob fast path writes every file 0644. Invoke scripts as sh scripts/install.sh, never ./scripts/install.sh.
• The skill ships from the branch, the binary from the newest tag, so the skill is normally the newer of the two. Never tell an agent to reconcile that by reinstalling the skill — it would downgrade itself. The reconciliation lives in parse_or_hint in main.rs.
• Every release updates the skill, and the version line is only half of it. "written for amcli X.Y.Z" in SKILL.md is pinned to the workspace version by a test, so a release commit bumps Cargo.toml, Cargo.lock and that line or cargo test is red. The half no test can check is the prose: a command or flag the release adds is invisible to an agent until SKILL.md describes it, because that file — not --help — is what it reads. So before tagging, diff the release against amcli skill commands and ask of each new subcommand, flag and batch op: is it in SKILL.md, or in references/batch.md if it only matters inside a batch? Shipping a feature nobody is told about is the same as not shipping it.
• The skill's Setup runs the installer every session. That is only fine because install.sh / install.ps1 short-circuit when the newest release is already installed and keep the installed binary when there is no network. Keep those two properties if you touch the installers.
• Files beginning with a dot are never copied, so no .gitattributes or .version inside the skill folder.