amethyst/.claude/skills/amy-expert/SKILL.md

name, description

name

description

amy-expert

Patterns for extending `amy`, the Amethyst CLI in `cli/`. Use when adding an `amy <verb>` command, touching files under `cli/src/main/kotlin/…/cli/`, wiring a new subcommand into `Main.kt`, writing an interop test script that drives Amy, or extracting logic out of `amethyst/` into `commons/` so a CLI command can call it. Enforces the thin-assembly-layer rule (no Nostr protocol or business logic inside `cli/`), the JSON-output contract (single-line object on stdout, exit codes 0/1/2/124), and the extract-from-Android recipe. Complements `nostr-expert` (protocol in Quartz), `kotlin-multiplatform` (expect/actual for extraction), and `feed-patterns` / `account-state` / `relay-client` (where the business logic should end up). NOT for general Nostr or Kotlin work — those have their own skills.

Amy CLI Expert

Practical patterns for touching the cli/ module without breaking its public contract.

When to use this skill

• Adding a new amy <verb> subcommand.
• Editing anything under cli/src/main/kotlin/…/cli/.
• Writing a shell script or test harness that drives Amy.
• Extracting code out of amethyst/ so the CLI can call it (this is the single most common reason an Amy feature request stalls).
• Deciding whether a piece of logic belongs in cli/ vs commons/ vs quartz/ (answer: almost never cli/).

Not for: general Nostr protocol work (nostr-expert), general Kotlin (kotlin-expert), Compose UI (compose-expert), Android-only flows (android-expert), gradle/build (gradle-expert).

The rules that matter

Amy has a small number of hard rules. Any change that breaks them is a breaking change to the CLI's public API, and breaks the interop- test harnesses that depend on it.

Rule 1 — cli/ is a thin assembly layer

No new Nostr protocol, filter assembly, state machines, or encryption lives in cli/. Ever. If you need logic that doesn't exist yet:

• Protocol piece (event kind, tags, signing)? Add it to quartz/.
• Business logic (state, defaults, ordering, filter assembly)? Add it to commons/ — extract from amethyst/ first if needed (see Rule 5).

A commands/*.kt file longer than ~200 lines is a code smell. Either the command is doing too many things, or the logic has leaked in from where it should have lived.

Rule 2 — stdout JSON, stderr humans

• Every success: one line, one JSON object on stdout, via Json.writeLine(mapOf(...)).
• Every failure: Json.error("code", "detail") → single-line JSON on stderr, non-zero exit.
• Exit codes: 0 success · 1 runtime · 2 bad args · 124 await timeout.
• Keys are stable, snake_case. Adding a key is safe; renaming or removing one is a breaking change and needs the commit message to say so.

See references/output-conventions.md.

Rule 3 — Non-interactive, ever

No readLine(), no TTY prompts, no hidden interactive behaviour. Passwords, names, keys, anything — all flags. Any network wait is an explicit await verb with --timeout.

Rule 4 — Data-dir is the whole world

State is reloaded from --data-dir PATH on every invocation. No singletons, no in-process caches that survive across runs. This is what lets 100 parallel interop scenarios share a harness safely.

Files live in well-known locations — see cli/README.md § Data-dir layout. Don't add unstructured state; if you need new persisted state, add it to Config.kt or stores/FileStores.kt with a named JSON schema.

Rule 5 — Extract before adding

If the command you're about to add needs logic from amethyst/, land the extraction first, in its own commit:

1. Identify the class in amethyst/src/main/java/…/.
2. List its Android-only dependencies (Context, SharedPreferences, WorkManager, Log, Bitmap, Uri, …).
3. For each, choose: inline, platform-abstract via expect/actual, or take-as-constructor-arg.
4. Move the file to commons/commonMain/….
5. Update the Android caller to use the new location. Add a JVM test.
6. Then add the cli/commands/… file.

Full checklist: references/extraction-recipe.md.

Standard command shape

Every new command follows the same shape — parse args, open Context, prepare, call into commons/quartz, publish or drain, emit one JSON line. The template is in references/command-template.md; copy it rather than re-deriving it.

Wire-up checklist:

1. New file in cli/commands/ with the object pattern.
2. Add a branch in Commands.kt.
3. Add a branch in Main.kt's dispatch (or under marmotDispatch / a new group dispatcher).
4. Extend printUsage() in Main.kt.
5. Add the row to cli/README.md's command table.
6. Update cli/ROADMAP.md — move the row from 🆕 / 📦 to ✅.
7. If the verb changes observable wire behaviour (a new event kind, a new relay-routing rule, a new JSON discriminator), add a case in the appropriate harness under cli/tests/ — cli/tests/marmot/ for MLS flows, cli/tests/dm/ for NIP-17, or a new sibling suite if it's neither.

If you change output shape: note it in the commit message, bump the example in README.md, update any interop fixtures under cli/tests/.

Where things live

cli/
├── README.md              # user-facing: commands, JSON contract, quick start
├── DEVELOPMENT.md         # touch-the-code: architecture, conventions, testing
├── ROADMAP.md             # parity matrix + ordered milestones
├── plans/                 # dated design docs (use for new subsystems)
├── tests/                 # end-to-end shell harnesses against a local relay
│   ├── lib.sh             # shared logging + result tracking
│   ├── headless/          # shared amy wrappers + assertions
│   ├── marmot/            # MLS group-messaging interop (vs whitenoise-rs)
│   └── dm/                # NIP-17 DM interop (two amy clients)
└── src/main/kotlin/…/cli/
    ├── Main.kt            # argv dispatch
    ├── Args.kt            # flag parser
    ├── Json.kt            # stdout/stderr JSON
    ├── Config.kt          # Identity, RelayConfig, RunState, DataDir
    ├── Context.kt         # per-run wiring — the backbone
    ├── stores/            # file-backed persistence
    └── commands/          # one file per top-level verb group

Shared logic consumed by Amy lives in commons/:

• commons/account/ — account bootstrap
• commons/marmot/ — MLS / group state
• commons/defaults/ — default relays, kinds
• Consult commons/plans/ for cross-cutting design work in flight.

Common mistakes to refuse

• Adding protocol logic to cli/. Push back, offer to extract.
• Silently changing a JSON key. Flag as breaking.
• Using println or print. Use Json.writeLine / Json.error. Plain System.err.println is fine for progress logs but never for user-consumable output.
• runBlocking inside a command — the top-level main already does that. Commands are suspend fun.
• Depending on :amethyst or :desktopApp. Never. If you need something from there, Rule 5.
• Re-inventing identifier parsing. Use Context.requireUserHex or resolveUserHexOrNull in quartz/nip05DnsIdentifiers/.
• Re-inventing publish-and-confirm. Use Context.publish.
• Re-inventing one-shot subscription. Use Context.drain.

Plans & design docs

Cross-cutting design work goes in dated plan docs, in the module that owns the code being created — not in docs/plans/, which is frozen.

• cli/plans/ — Amy-specific subsystems.
• commons/plans/ — shared code Amy consumes (e.g. 2026-04-21-event-renderer.md).

Cross-references

• cli/README.md
• cli/DEVELOPMENT.md
• cli/ROADMAP.md
• references/command-template.md
• references/extraction-recipe.md
• references/output-conventions.md