ironbee-devtools-skills: Instructions file for Codex

Agent Guidelines for ironbee-devtools-skills

Keep this file up to date. When you change conventions, structure, or the relationship to the upstream ironbee-devtools project, update the relevant sections here as part of the same change. This file is the source of truth for AI coding agents working on this skills repository.

What this project is

ironbee-devtools-skills ships skills.sh-installable skills for IronBee DevTools. Each skill is a Markdown file (plus a references/ folder for CLI skills) that AI coding agents — Claude Code, Cursor, Windsurf, etc. — load to drive the IronBee DevTools CLIs.

This repo is purely documentation / agent prompts. There is no source code, no build step, and no runtime. Every change here is content edits to Markdown files, and correctness is judged by:

1. Whether the CLI examples actually run against the IronBee DevTools binaries.
2. Whether the documented flag names and input shapes match the tool schemas in the upstream ironbee-devtools project.
3. Whether the cross-references between SKILL.md files and references/*.md files resolve.

Upstream source of truth: ironbee-devtools

This repo is downstream of ironbee-devtools. Every CLI subcommand, every flag, every default value, every domain folder, every MCP server-instructions paragraph — all of that is generated by code in the upstream repo. If you change anything here, verify it against the upstream tool definitions, never the other way around.

Specifically:

• A tool's CLI subcommand name comes from its name() method: domain_command-name → CLI domain command-name. Tools whose name has no underscore (e.g. scenario-add, execute) fall under the auto-generated default domain — with one special case: execute is special-cased to run execute in the CLI runner. scenario-run is constructed with a ToolRegistry (so scripts can compose other scenarios) and is therefore not in any platform's cliProvider.tools; the CLI runner appends it to every platform via withSharedCliTools (src/cli/utils.ts), so it IS a direct CLI subcommand on all six platforms — cli default scenario-run --name '...' (flags --name, --args, repeatable --param key=value, --timeout-ms, plus the step-engine flags --resume, --resume-output, --cache, --step-by-step, --refresh, --persist-cache; no --scope). The scenario CRUD set (scenario-{add,update,delete,list,search,recorded-actions}) is registered on all six platforms too — each platform's tools/index.ts spreads the shared tools/scenario (src/tools/scenario).
• A tool's allowed CLI flags come from its Zod inputSchema(): every camelCase field becomes a kebab-case flag. Object / record fields become a single JSON-valued flag (--metadata '{...}') — never split into per-key flags. Array fields render as a variadic flag (--flag <value...>) with no per-element JSON parsing, so each token is a raw string: arrays of scalars are passed as repeated/space-separated tokens (e.g. scenario-run's --param key=value --param key2=value2), and arrays whose elements are themselves objects (e.g. scenario-add's --params) effectively cannot be set from the CLI — declare them via MCP / run execute. Boolean fields typed z.boolean().optional() (without .default(true)) become a single switch — passing it sends true, omitting it sends undefined and the server applies its default. --no-<flag> is NOT auto-registered; only z.boolean().default(true) wraps generate both --flag and --no-flag. To force false from CLI on these fields, call via run execute / MCP.
• A tool's description in the skill prose should match the substance of description() in code, not invent new behavior.
• The CLI binary names live in upstream package.json's bin block: ironbee-devtools-cli (browser default, alias ironbee-browser-devtools-cli), ironbee-node-devtools-cli, ironbee-python-devtools-cli, ironbee-backend-devtools-cli, ironbee-android-devtools-cli, ironbee-terminal-devtools-cli. Never use the legacy browser-devtools-cli / node-devtools-cli / python-devtools-cli / backend-devtools-cli / android-devtools-cli / terminal-devtools-cli / browser-devtools-mcp names. (Upstream also has an ios platform folder, but it ships no CLI binary yet — do not add an iOS skill until package.json bin lists ironbee-ios-devtools-cli.)
• The compose meta-platform is MCP-only — it has NO CLI skill. Upstream PLATFORM=compose (COMPOSE_PLATFORMS=browser,backend,node,…) multiplexes several platforms' tools behind one MCP server, each under a prefix (browser bdt_, backend bedt_, node ndt_, python pdt_, android adt_, terminal tdt_) — and since 0.25.0 the shared, platform-agnostic tools (execute, scenario-*, jira_*, linear_*, o11y_*) carry the common prefix ibdt_ instead of being exposed unprefixed (config.COMPOSE_COMMON_PREFIX). It ships ironbee-compose-devtools-mcp in bin but no ironbee-compose-devtools-cli (PlatformInfo.cliInfo is omitted), so — exactly like iOS — do not add a ironbee-compose-devtools-cli/ skill until upstream package.json bin lists a compose CLI binary. The six CLI skills already document every tool compose can expose; the prefixing is an MCP-session concern, not a CLI one.
• The default daemon port is 2020 for all six CLIs. When multiple daemons run simultaneously the examples should pick different --port values (browser 2020, node 2021, backend 2022, android 2023, terminal 2024, python 2025 by convention).