adom-cli-design

@@ -248,13 +248,9 @@ Skills are prose, and we edit them *a lot* more often than we rebuild the Rust c  **The rule:** -- SKILL.md and BUILD-SKILL.md ship as **independent assets on the wiki page**. Upload them alongside the binary:-  ```bash-  adom-wiki asset upload apps/my-tool --asset-type skill       --file SKILL.md-  adom-wiki asset upload apps/my-tool --asset-type build-skill --file BUILD-SKILL.md-  ```+- SKILL.md and BUILD-SKILL.md ship as **independent assets on the wiki page**. Publish them alongside the binary with `adompkg publish`. - The binary's `install` subcommand **fetches the latest SKILL.md from the wiki** at install time (and falls back to a bundled copy if the wiki is unreachable). The fallback is a safety net, not the primary path.-- Bumping a skill becomes: edit `SKILL.md` in the repo → `adom-wiki asset upload …` → done. No binary rebuild, no version bump. The next user to run `my-tool install` (or re-run gallia's Tier A refresh) picks up the new prose.+- Bumping a skill becomes: edit `SKILL.md` in the repo → `adompkg publish` → done. No binary rebuild, no version bump. The next user to run `my-tool install` (or re-run gallia's Tier A refresh) picks up the new prose.  Same rule applies to any other rapidly-changing prose asset (policy docs, prompt templates, wiki `body.md`). Binary-side data that is *strictly coupled* to the binary's own structure (e.g., a `VSIX` whose API matches the current binary's RPC schema, or baked-in default config schemas used by the Rust types) can still be embedded via `include_bytes!` — couple-to-code, not couple-to-prose. @@ -267,7 +263,7 @@ Same rule applies to any other rapidly-changing prose asset (policy docs, prompt    const FALLBACK_SKILL_MD: &str = include_str!("../../SKILL.md");     fn fetch_skill_md() -> Cow<'static, str> {-       let url = "https://wiki-ufypy5dpx93o.adom.cloud/static/apps/my-tool/SKILL.md";+       let url = "https://wiki.adom.inc/static/apps/my-tool/SKILL.md";        match ureq::get(url).timeout(Duration::from_secs(5)).call() {            Ok(r) => r.into_string().map(Cow::Owned).unwrap_or(Cow::Borrowed(FALLBACK_SKILL_MD)),            Err(_) => {

@@ -1,6 +1,6 @@ {   "slug": "adom-cli-design",-  "version": "1.0.0",+  "version": "1.0.1",   "type": "skill",   "description": "Design conventions for every Rust CLI in the Adom ecosystem. Output formats (OK:/ERROR: + JSON companion), no-color-when-piped, --json for machines and pretty for humans, exit codes, subcommand layout",   "dependencies": {},

@@ -1,50 +1,16 @@ {-  "schema_version": 1,-  "type": "skill",   "slug": "adom-cli-design",-  "title": "adom CLI design",-  "brief": "Design conventions for every Rust CLI in the Adom ecosystem. Output formats (OK:/ERROR: + JSON companion), no-color-when-piped, --json for machines and pretty for humans, exit codes, subcommand layout",-  "version": "1.0.0",-  "tags": [],-  "license": "MIT",-  "sample_prompts": [-    {-      "label": "CLI conventions",-      "prompt": "What output format should my new Adom CLI use?"-    },-    {-      "label": "No ANSI piped",-      "prompt": "How do I gate ANSI escapes on isatty?"-    },-    {-      "label": "OK ERROR",-      "prompt": "How do I emit OK:/ERROR: lines for AI parseability?"-    },-    {-      "label": "JSON companion",-      "prompt": "Add a JSON companion line to my CLI output"-    },-    {-      "label": "Exit codes",-      "prompt": "What exit codes does Adom expect?"-    }-  ],-  "source_path": "SKILL.md",-  "readme": "---\nname: adom-cli-design\ndescription: Guidelines for building CLI tools in the Adom ecosystem. Use when creating a new CLI, adding commands to an existing one, or deciding between CLI vs MCP vs HTTP API. Covers Rust CLI conventions, AI-oriented output, skill files, and why we prefer CLIs over MCP servers. Trigger words: build a cli, new cli tool, cli design, cli guidelines, mcp vs cli, should I use mcp, make a tool for the ai.\n---\n\n# Building CLI Tools for Adom\n\n## Why CLI over MCP\n\nWe use Rust CLIs as the primary interface between Claude Code and Adom tools. **Do not build MCP servers** for new tools.\n\n| | MCP Server | Rust CLI |\n|---|---|---|\n| Context cost | High — tool schemas injected into every conversation | Zero — skill file loaded only when triggered |\n| Discoverability | Always visible, clutters tool list | Skill-triggered, on-demand |\n| Reliability | Stdio transport can hang, crash, or desync | Process runs and exits cleanly |\n| Debugging | Opaque — hard to see what happened | Just run the command in terminal |\n| Distribution | Requires .mcp.json wiring per container | Single binary, `cp` to `/usr/local/bin/` |\n| AI usability | AI must guess tool params from schema | AI reads skill examples, runs bash |\n\n**The pattern:** Rust CLI binary + Claude Code skill file. The AI reads the skill to learn the commands, then runs them via Bash.\n\n## CLI Conventions\n\n### Language: Rust\n\n- Use `clap` with derive macros for argument parsing\n- Use `serde_json` for JSON input/output\n- Minimize dependencies — prefer raw TCP over `reqwest` for simple HTTP calls\n- Build with `--release`, `opt-level = \"z\"`, `lto = true`, `strip = true` for small binaries\n- Install to `/usr/local/bin/` so it's on PATH everywhere\n\n### Output: AI-Oriented\n\nThe CLI output is consumed by Claude Code, not humans. Design accordingly:\n\n**Every response starts with `OK:` or `ERROR:`** — the AI can instantly determine success/failure.\n\n**Success output is descriptive and confirms what happened:**\n```text\nOK: Opened /home/adom/project/README.md in VS Code editor tab.\nOK: Injected shot-2026-03-28T14-30-22.png (1920x1080, 245 KB) into channel \"dart2\".\nOK: Server listening on port 8820, recovered 3 channels from disk.\n```\n\n**Error output includes a `Hint:` line with the next action:**\n```text\nERROR: Cannot connect to shotlog server on port 8820.\nHint: Start the server with `shotlog serve &`\n\nERROR: File not found: /home/adom/project/missing.png\nHint: Check the path exists. Use `ls /home/adom/project/` to list files.\n\nERROR: Adom Bridge extension not responding on port 8821.\nHint: The extension may need a window reload. Run: adom-bridge health\n```\n\n**Never output ambiguous or empty responses.** If a command succeeds silently, still print `OK:`.\n\n### Colored output\n\nUse ANSI escape codes for colored terminal output. No crate needed — raw escape codes work everywhere. But colors are for **humans at interactive terminals only**: when the CLI's output is piped (`cmd | grep`, `cmd > log`, `nohup cmd > log.txt 2>&1`, bash command substitution, etc.), ANSI escape codes leak into log files and into the AI's stdout capture as ugly garbage like `[36mstarting server[0m`. Every CLI MUST strip ANSI when stdout/stderr is not a TTY.\n\n**Required pattern** — `is_terminal()` check gated on each output helper, with a matching `strip_ansi` fallback. Both `println!` / `eprintln!` calls that embed color constants AND internal progress messages need this — not just the `ok` / `err` / `hint` / `warn` helpers:\n\n```rust\nuse std::io::IsTerminal;\nuse std::sync::OnceLock;\n\nconst GREEN: &str = \"\\x1b[32m\";\nconst RED: &str = \"\\x1b[31m\";\nconst YELLOW: &str = \"\\x1b[33m\";\nconst CYAN: &str = \"\\x1b[36m\";\nconst BOLD: &str = \"\\x1b[1m\";\nconst DIM: &str = \"\\x1b[2m\";\nconst RESET: &str = \"\\x1b[0m\";\n\nstatic STDOUT_IS_TTY: OnceLock<bool> = OnceLock::new();\nstatic STDERR_IS_TTY: OnceLock<bool> = OnceLock::new();\npub fn stdout_is_tty() -> bool { *STDOUT_IS_TTY.get_or_init(|| std::io::stdout().is_terminal()) }\npub fn stderr_is_tty() -> bool { *STDERR_IS_TTY.get_or_init(|| std::io::stderr().is_terminal()) }\n\npub fn strip_ansi(s: &str) -> String {\n    // Strip CSI sequences like \\x1b[36m, \\x1b[0m, \\x1b[1;32m etc.\n    let mut out = String::with_capacity(s.len());\n    let mut chars = s.chars().peekable();\n    while let Some(c) = chars.next() {\n        if c == '\\x1b' && chars.peek() == Some(&'[') {\n            chars.next();\n            for c2 in chars.by_ref() { if c2.is_ascii_alphabetic() { break; } }\n            continue;\n        }\n        out.push(c);\n    }\n    out\n}\n\nfn ok(msg: impl std::fmt::Display) {\n    if stdout_is_tty() {\n        println!(\"{GREEN}{BOLD}OK:{RESET} {msg}\");\n    } else {\n        println!(\"OK: {}\", strip_ansi(&msg.to_string()));\n    }\n}\nfn err(msg: impl std::fmt::Display) {\n    if stderr_is_tty() {\n        eprintln!(\"{RED}{BOLD}ERROR:{RESET} {msg}\");\n    } else {\n        eprintln!(\"ERROR: {}\", strip_ansi(&msg.to_string()));\n    }\n}\nfn hint(msg: impl std::fmt::Display) {\n    if stderr_is_tty() {\n        eprintln!(\"{DIM}Hint:{RESET} {msg}\");\n    } else {\n        eprintln!(\"Hint: {}\", strip_ansi(&msg.to_string()));\n    }\n}\n\n// And — critically — `note!` for every internal progress message\n// (\"starting server on port X\", \"running ffmpeg...\", \"filter graph:\n// N chars\", etc.). These are the ones that tend to get written as\n// bare `println!(\"{CYAN}...{RESET}\")` and leak raw escape codes into\n// logs when the CLI is run under nohup or backgrounded to a file.\n// Route them all through a `note!` macro so the isatty gate is\n// unmissable:\nmacro_rules! note {\n    ($($arg:tt)*) => {{\n        let __s = format!($($arg)*);\n        if $crate::stdout_is_tty() {\n            println!(\"{}\", __s);\n        } else {\n            println!(\"{}\", $crate::strip_ansi(&__s));\n        }\n    }};\n}\n```\n\n- `OK:` in green bold, paths/values in cyan, search terms in yellow.\n- `ERROR:` in red bold, hints in dim.\n- The AI reads `OK:` / `ERROR:` prefixes; colors are for human readability **only**.\n- **Never leak raw ANSI escape codes to pipes.** If you see `[36m` or `[0m` in a log file, a CLI is broken. The `video-post` crate (adom-inc/video-post on GitHub) implements the full pattern above in `src/main.rs` — `note!` + `enote!` macros + `ok/err/hint/warn` helpers all gated on isatty. Copy from there for any new CLI.\n\n### Bash tab completions\n\nUse `clap_complete` to generate bash completions. The `install` command should write them to `~/.local/share/bash-completion/completions/<tool>` and append an `eval` line to `.bashrc`:\n\n```rust\n// In Cargo.toml:\nclap_complete = \"4\"\n\n// Generate completions:\nlet mut cmd = Cli::command();\nlet mut buf = Vec::new();\nclap_complete::generate(clap_complete::Shell::Bash, &mut cmd, \"my-tool\", &mut buf);\nfs::write(format!(\"{completions_dir}/my-tool\"), &buf).ok();\n```\n\nUsers get tab completion immediately in new terminals -- `my-tool <TAB>` shows all subcommands.\n\n### Subcommand Structure\n\nUse subcommands for logical grouping:\n```text\ntoolname <verb> [options] [args]\n\nshotlog serve --port 8820\nshotlog inject --channel dart2 --desc \"...\" file.png\nshotlog open --channel dart2\n\nadom-bridge open /path/to/file.png\nadom-bridge reveal /path/to/folder/\nadom-bridge claude new\nadom-bridge extensions search \"python\"\n```\n\n### Port Registration\n\n**Before picking a port**, check `/home/adom/gallia/PORT-REGISTRY.md`. Add your service to the registry before writing code. Port ranges are pre-allocated by category (8820–8829 for Adom tools, 8850–8899 for user/ephemeral, etc.).\n\n### Health Check\n\nEvery CLI that talks to a server should have a `health` subcommand:\n```text\ntoolname health\n```\nReturns `OK: ...` if the server is reachable, `ERROR: ...` with a hint if not. This lets the AI self-diagnose connection issues.\n\n## Skill File\n\nEvery CLI **must** have a `SKILL.md` so Claude Code knows how to use it.\n\n### Where it lives\n\n- Source: in the tool's own repo (e.g., `/home/adom/project/my-tool/SKILL.md`)\n- Embedded in the binary via `include_str!`\n- Deployed to `~/.claude/skills/<tool-name>/SKILL.md` by `my-tool install`\n\n### What it contains\n\n```markdown\n---\nname: tool-name\ndescription: \"One-line description with trigger words...\"\n---\n\n# Tool Name\n\nBrief description of what it does.\n\n## Commands\n\n### `toolname verb`\nWhat it does.\n\n| Flag | Required | Default | Description |\n|------|----------|---------|-------------|\n| `--flag` | yes | — | What it controls |\n\n**Example:**\n\\`\\`\\`bash\ntoolname verb --flag value /path/to/thing\n\\`\\`\\`\n```\n\nInclude **concrete examples** for every command. The AI copies from examples — if the example is wrong or missing, the AI will guess and get it wrong.\n\n### Register in the capabilities table\n\nAdd a row to `~/.claude/skills/adom/SKILL.md`:\n```text\n| Tool Name | \"trigger words\" | Standalone skill: `~/.claude/skills/<tool>/SKILL.md` |\n```\n\n## Distribution\n\n### Own GitHub repo (recommended)\n\nEvery shared CLI should live in its own `adom-inc/<tool-name>` repo. This keeps the tool self-contained, gives it its own release cycle, and avoids bloating gallia with build artifacts. Examples: `adom-inc/adom-cli`, `adom-inc/adom-vscode`.\n\n### The `install` command pattern\n\n**The binary owns its own install.** One command — `my-tool install` — sets up everything: the skill, shell completions, companion pieces (VSIX, config files, etc.). `gallia/install.mjs` just downloads the binary and runs it.\n\n#### DO NOT embed SKILL.md / BUILD-SKILL.md in the binary (hard rule)\n\nSkills are prose, and we edit them *a lot* more often than we rebuild the Rust code — adding triggers, clarifying tool-use patterns, patching a broken sentence an AI misinterpreted. If a skill is compiled into the binary via `include_str!`, every single prose fix requires a full binary rebuild, a GitHub release, a wiki asset upload, and a re-install on every user container. That's way too much ceremony for a 10-character typo. Worse: until a user reinstalls the binary, they silently run the stale skill.\n\n**The rule:**\n\n- SKILL.md and BUILD-SKILL.md ship as **independent assets on the wiki page**. Upload them alongside the binary:\n  ```bash\n  adom-wiki asset upload apps/my-tool --asset-type skill       --file SKILL.md\n  adom-wiki asset upload apps/my-tool --asset-type build-skill --file BUILD-SKILL.md\n  ```\n- The binary's `install` subcommand **fetches the latest SKILL.md from the wiki** at install time (and falls back to a bundled copy if the wiki is unreachable). The fallback is a safety net, not the primary path.\n- Bumping a skill becomes: edit `SKILL.md` in the repo → `adom-wiki asset upload …` → done. No binary rebuild, no version bump. The next user to run `my-tool install` (or re-run gallia's Tier A refresh) picks up the new prose.\n\nSame rule applies to any other rapidly-changing prose asset (policy docs, prompt templates, wiki `body.md`). Binary-side data that is *strictly coupled* to the binary's own structure (e.g., a `VSIX` whose API matches the current binary's RPC schema, or baked-in default config schemas used by the Rust types) can still be embedded via `include_bytes!` — couple-to-code, not couple-to-prose.\n\n#### Implementation — `install` subcommand\n\n1. **Fetch skill from the wiki, fall back to a bundled copy:**\n   ```rust\n   // Bundled SKILL.md is the fallback used only when the wiki is unreachable.\n   // `// SAFETY NET — do not rely on for release propagation.`\n   const FALLBACK_SKILL_MD: &str = include_str!(\"../../SKILL.md\");\n\n   fn fetch_skill_md() -> Cow<'static, str> {\n       let url = \"https://wiki-ufypy5dpx93o.adom.cloud/static/apps/my-tool/SKILL.md\";\n       match ureq::get(url).timeout(Duration::from_secs(5)).call() {\n           Ok(r) => r.into_string().map(Cow::Owned).unwrap_or(Cow::Borrowed(FALLBACK_SKILL_MD)),\n           Err(_) => {\n               warn(\"wiki unreachable — installing bundled SKILL.md (may be stale)\");\n               Cow::Borrowed(FALLBACK_SKILL_MD)\n           }\n       }\n   }\n   ```\n\n2. **Add an `install` subcommand** that handles all setup:\n   ```rust\n   Commands::Install => {\n       // 1. Install companion pieces (VSIX, config, etc.)\n       // 2. Install skill — fetched fresh from the wiki\n       let skill_dir = format!(\"{home}/.claude/skills/my-tool\");\n       fs::create_dir_all(&skill_dir).ok();\n       fs::write(format!(\"{skill_dir}/SKILL.md\"), fetch_skill_md().as_ref()).ok();\n       // 3. Install bash completions\n       let comp_dir = format!(\"{home}/.local/share/bash-completion/completions\");\n       fs::create_dir_all(&comp_dir).ok();\n       let mut cmd = Cli::command();\n       let mut buf = Vec::new();\n       clap_complete::generate(Shell::Bash, &mut cmd, \"my-tool\", &mut buf);\n       fs::write(format!(\"{comp_dir}/my-tool\"), &buf).ok();\n       // 4. Add to .bashrc if not already there\n       let bashrc = fs::read_to_string(format!(\"{home}/.bashrc\")).unwrap_or_default();\n       if !bashrc.contains(\"# my-tool completions\") {\n           fs::OpenOptions::new().append(true).open(format!(\"{home}/.bashrc\"))\n               .map(|mut f| f.write_all(b\"\\n# my-tool completions\\neval \\\"$(my-tool completions bash 2>/dev/null)\\\"\\n\")).ok();\n       }\n   }\n   ```\n\n3. **Attach binary to GitHub Releases** — no Rust toolchain needed on user containers\n\n4. **`gallia/install.mjs` is just two lines:**\n   ```javascript\n   execSync('gh release download --repo adom-inc/my-tool --pattern \"my-tool\" --output /usr/local/bin/my-tool --clobber');\n   execSync('sudo chmod +x /usr/local/bin/my-tool && my-tool install');\n   ```\n\nThe binary is the primary artifact for *code*. The wiki is the primary artifact for *prose*. `gallia/install.mjs` never needs to know the internals — it just downloads the binary and runs `install`, which then reaches back to the wiki for the skills.\n\n### build.sh (for local development)\n\nEvery tool should have a `build.sh` for building locally before cutting a release:\n1. Build the binary (`cargo build --release`)\n2. Install to `/usr/local/bin/`\n3. Run `my-tool install` (installs everything locally)\n\n## Examples of This Pattern\n\n| Tool | Port | What it does |\n|------|------|-------------|\n| `shotlog` | 8820 | Screenshot log viewer + injector |\n| `adom-vscode` | 8821 | VS Code control API (open files, reveal, extensions, Claude Code) |\n| `adom-cli` | — | Adom platform API (containers, repos, users, workspaces) |\n",+  "version": "1.0.1",+  "type": "skill",+  "description": "Design conventions for every Rust CLI in the Adom ecosystem. Output formats (OK:/ERROR: + JSON companion), no-color-when-piped, --json for machines and pretty for humans, exit codes, subcommand layout",+  "dependencies": {},+  "scripts": {+    "install": "./install.sh",+    "uninstall": "./uninstall.sh"+  },+  "org": "adom",   "author": {-    "id": "695820315b5f1e4db2fcf602",     "name": "Kyle Bergstedt",     "email": "[email protected]"-  },-  "visibility": {-    "public": true-  },-  "hero": null,-  "discovery_triggers": [],-  "discovery_pitch": null,-  "metadata": {},-  "created_at": "2026-05-28T05:29:40.324Z",-  "updated_at": "2026-05-28T05:29:40.324Z",-  "sub_skills": [],-  "parent_app": null+  } }\ No newline at end of file