Infrastructure

Skill: Infrastructure Setup

Invocation

• If invoked by a user presenting a setup task: immediately spawn the digital-chip-design-agents:infrastructure-orchestrator agent and pass the full user request and any available context. Do not execute stages directly.
• If invoked by the infrastructure-orchestrator mid-flow: do not spawn a new agent. Treat this file as read-only — return the requested stage rules, sign-off criteria, or loop-back guidance to the calling orchestrator.

Spawning the orchestrator from within an active orchestrator run causes recursive delegation and must never happen.

Purpose

Detect open-source and proprietary EDA tools, generate an installation script for missing tools, deploy output-filtering shell wrappers that emit compact JSON instead of raw 10,000–50,000-line logs, configure MCP server templates, and validate the complete environment before any domain orchestrator begins work.

Supported EDA Tools

Open-Source

• Verilator (verilator) — fast RTL simulator and linter
• Slang (slang) — SystemVerilog compiler and language server
• Surelog (surelog) — SystemVerilog pre-processor and parser
• sv2v (sv2v) — SystemVerilog to Verilog converter
• Icarus Verilog (iverilog) — Verilog simulator
• Yosys (yosys) — open synthesis framework
• ABC (abc) — logic synthesis and verification tool
• OpenROAD (openroad) — RTL-to-GDS flow
• LibreLane / OpenLane2 (openlane) — open-source ASIC flow
• KLayout (klayout) — GDS/OASIS viewer and DRC engine
• OpenSTA (sta) — gate-level static timing analysis
• SymbiYosys (sby) — formal hardware verification
• gem5 (gem5) — full-system micro-architectural simulator
• Bambu HLS (bambu-hls) — high-level synthesis from C/C++
• nextpnr (nextpnr) — FPGA place-and-route
• openFPGALoader (openFPGALoader) — FPGA programming tool
• cocotb (Python package cocotb) — Python-based RTL co-simulation
• LLVM (llvm-config) — compiler infrastructure
• GCC (gcc) — GNU compiler collection
• OpenOCD (openocd) — on-chip debugger
• xschem (xschem) — schematic capture and simulation netlist tool
• GTKWave (gtkwave) — waveform viewer for VCD/FST simulation output
• uv (uv) — fast Python package and project manager (required for cocotb installs)

Roles and dialects (open-source)

role groups tools that do the same job. dialect names the command-line option and source-language vocabulary a tool accepts. Two tools with the same role and a different dialect are not substitutable — a command line built for one is not valid for the other.

Every other open-source tool — slang, surelog, sv2v, abc, openFPGALoader, cocotb, llvm-config, gcc, openocd, xschem, gtkwave, uv, python3 — has no same-role peer here and is recorded "role": null, "dialect": null. Never invent a role to fill the field: a null cannot produce a false conflict.

Proprietary (detect only — never install)

vcs -ID also prints a FLEXlm host ID. Parse and store the Compiler version value only — never write the host ID into tool-status.json.

A probe flag is listed only once confirmed on a real install — a guessed flag can open an interactive shell or check out a license. The flags above were each measured: exit 0 with the named line present, in 1–26 s, no license queue. dc_shell -version prints an unrelated ASLR advisory first, so parse the line containing version, never the first line of output. genus -version was measured the same way: 26 s cold, 12 s warm, which is why rule 4 below sets the probe timeout at 60 s rather than the original 10 s.

The two original UNVERIFIED rows are unverified upstream, not an oversight. Neither could be confirmed on the reference host, and in both cases the obstacle was the install rather than the flag: innovus -version exits 0 reporting an expired build authorisation, and vsim -version exits 0 failing to load libXext.so.6. A site with a working install of either should confirm the flag and contribute it here.

The remaining UNVERIFIED rows above have no probe evidence at all, which is worth recording precisely so a later contributor does not re-measure it blind: voltus -version and tempus -version each exit 0 but with cds_plat.dat absent, the same shape as the innovus failure. joules, conformal, starrc, liberate, and jg did not resolve to a binary under <root>/linux/<version>/bin/ on the reference host at all. Three of the exit-0 cases print no version line, which is exactly why rule 4's WARN conditions below treat "exits 0, no version line" as its own case rather than a pass.

Note on Formality: the primary command is fm_shell. formality is the legacy GUI wrapper and is absent from recent installs, so it is listed as the alternate.

Same role with a different dialect means the two tools are not interchangeable however similar their purpose. environment_validation reports such coexistence.

Single-member roles are intentional, not an oversight — each is a role whose only plausible peers are already claimed by their primary role, so the role can never produce a dialect-conflict WARN today:

• lint_cdc holds only spyglass. jg and vsim also do clock-domain-crossing work, but jg is recorded under formal and vsim under rtl_simulator — a tool carries one role in tool-status.json, and each already does its primary job elsewhere.
• mem_compiler holds only artisan. Synopsys's memory compiler shares a binary with siliconsmart, which is recorded under characterisation — the job that binary performs.
• extraction holds only starrc. No skill in this repo names a second extraction tool.
• power_analysis has three single-command peers plus three commandless ones (below); none of voltus, primepower, joules, or powerpro has a second same-dialect alternative.
• embedded_compiler holds only armcc with a command; Green Hills and IAR are its commandless peers.

Products named in domain skills with no documented command, so not detectable by this table (the table is keyed on which <command>; a row with no command cannot be probed): Synopsys Platform Architect (arch_simulator/synopsys), ARM Performance Models (arch_simulator/arm), Cadence Virtual System Platform (arch_simulator/cadence), Green Hills MULTI (embedded_compiler/greenhills), IAR Embedded Workbench (embedded_compiler/iar), Synopsys Synplify (synthesis/synopsys), Siemens Aprisa (physical_design/siemens), Synopsys PrimePower, Cadence Joules RTL, and Siemens Questa PowerPro (all power_analysis), Synopsys VC Static (lint_cdc/synopsys). A command name is not guessed here any more than a probe flag is above; each is instead given its role and dialect at the point of use in its domain skill.

MCP Architecture — Two Tiers

Tier 1: Batch MCP servers (short, self-contained runs)

Use these for tools whose output fits inside a single request/response cycle (seconds to a few minutes). Each call spawns the wrapper script, captures its compact JSON output, and returns it.

The adapter is plugins/infrastructure/tools/mcp-adapter.py. Each server runs the one wrapper named by --wrapper, except verilator: mode: "lint" runs wrap-verilator-lint.sh from the same directory as the configured wrap-verilator-sim.sh, because the sim wrapper's first argument is a compiled simulation binary. The 8 batch servers therefore use 9 of the 11 wrapper scripts; wrap-vcs-compile.sh and wrap-xrun-compile.sh are invoked directly, not through MCP.

Tier 2: Interactive session MCP servers (stateful, query-based)

Use these when an agent iterates many times over an already-loaded design (e.g. ECO timing loops). The process stays alive between calls — no re-loading per query.

The adapter is plugins/infrastructure/tools/mcp-session-adapter.py.

Full-flow tools — do NOT use MCP

These tools run for 30 min–2+ hours and produce structured output files on disk. Agents must launch them via Bash and read the output files directly.

Execution Hierarchy (per domain agent)

1. Tier 2 session MCP — if the tool supports a session and the design is already loaded
2. Tier 1 batch MCP — if the tool has a batch MCP server configured
3. Wrapper script — if MCP is not configured; wrapper emits compact JSON
4. Direct execution — last resort; raw logs consume significant context

Domain agents must check whether the relevant MCP server is active in .claude/settings.json before falling back to the wrapper or direct execution.

Stage: tool_discovery

Domain Rules

1. Run which <command> and <command> --version (or -version) for every open-source tool

2. Python interpreter detection — run once at the start of tool_discovery, before checking any Python packages. Detection order (first match wins):

   Step A — Module system probe (runs before PATH check): a. Classify the module system and prove it is invocable using the detection rules and the invocation ladder in module_discovery below. Do not re-derive either here, and never treat $MODULESHOME alone as proof that module can be run. b. If a listing was obtained (module_listing is "LISTED"), search it for entries matching python or python3 (case-insensitive). c. If one or more Python module entries are found: select one per Module version selection in module_discovery below — never by a plain sort — then load it via module load <python-module> and run which python3 to resolve PYTHON_EXEC. The non-release exclusion matters more here than anywhere else: an interpreter chosen here stays loaded for the whole run, so a _test or -debug build selected at this step becomes the Python every later stage resolves against. Set python_env.type = "module" and record python_env.module_name with the loaded module name. Keep the module loaded for the entire orchestrator run — do not unload it; subsequent stages (tool_installation, wrapper_deployment, environment_validation) all depend on PYTHON_EXEC being resolvable. The generated load-modules.sh handles persistent loading for future shell sessions. d. Proceed to Step B where module_system is "none", where the ladder was exhausted (module_listing is "UNAVAILABLE"), or where the listing holds no Python module entries. A detected-but-unlistable module system is not the same as no module system: it still falls through to the PATH interpreter here, but the WARN it owes is emitted by module_discovery and is not suppressed because this step recovered an interpreter.

   Step B — PATH-based fallback: e. Run which python3 to get the interpreter path; store as PYTHON_EXEC. f. If which python3 fails or returns empty: record python3 as MISSING in tool-status.json and FAIL immediately (required for all wrapper scripts and Python packages). g. Classify the interpreter:

   • system → PYTHON_EXEC == /usr/bin/python3
   • custom → any other path (pyenv, conda, virtualenv, custom prefix, etc.)

   Step C — Finalize: h. Set PYTHON_BIN_DIR = $(dirname "$PYTHON_EXEC") regardless of how PYTHON_EXEC was resolved. i. Record under a top-level key python_env in tool-status.json:

   {
     "python_env": {
       "exec": "<absolute path>",
       "type": "module | system | custom",
       "bin_dir": "<absolute dir>",
       "module_name": "<module name, or null if not module-based>"
     }
   }

   j. Capture "$PYTHON_EXEC" --version and store it as a regular entry in the tools array (with "tool": "python3", "command": "python3", "status": "FOUND", "version": "<output>", "path": "<PYTHON_EXEC>"). This makes python3 visible to module_discovery for module-status upgrades (FOUND_PREFER_MODULE).

3. Exception — Python packages:

   • cocotb: detection depends on the Python interpreter type determined in rule 2:
     • If python_env.type == "custom" or "module": check "$PYTHON_BIN_DIR/cocotb-config" --version first; if that exits zero, record FOUND with the returned version string. Only if absent or non-zero, fall back to cocotb-config --version (PATH-based).
     • If python_env.type == "system": use cocotb-config --version (PATH-based) only.
     • Report MISSING if all attempted checks fail.
   • openlane: run "$PYTHON_EXEC" -m pip show openlane 2>/dev/null; if exit code 0 and Name: openlane appears in output, record FOUND and extract the Version: field; otherwise MISSING.
   • uv: if python_env.type == "custom" or "module": check "$PYTHON_BIN_DIR/uv" --version first; fall back to uv --version (PATH). If python_env.type == "system": use uv --version only.

4. Proprietary tools: check PATH using which <primary-executable> (primary and alternate names are in the Proprietary table above); never attempt install; record as PROPRIETARY_ONLY if found, MISSING otherwise. For a tool found in PATH that has a version probe in that table, run the probe with a 60 s timeout, parse the documented line, and store the parsed string in version. Do not use a short timeout: a Cadence Common UI tool starts a full shell to answer -version and takes tens of seconds on a cold NFS cache (genus -version measured 26 s cold, 12 s warm). For vcs, store the Compiler version value only — discard the FLEXlm host ID.

   Leave version empty and emit a WARN naming the tool and the reason when the table lists no probe, when the probe times out, when it exits non-zero, or when it exits 0 without printing the documented line. Record a version only when that line was actually found: exit 0 does not mean a version was printed.

   Measured on the reference host by invoking each tool directly: innovus -version answers 0 with an expired build authorisation, voltus -version answers 0 with "cannot find a proper installation", and vsim -version answers 0 having failed to load a shared library. None of those three has a probe in the table above, so this stage reaches an empty version for them through the no-probe condition, not the last one. They are cited as evidence that a broken install answers 0 whatever the vendor — which is why the last condition has to guard the five tools that do carry a probe, whose installs can break the same way. A version probe never fails the stage.

5. Record each tool as one of: FOUND, MISSING, or PROPRIETARY_ONLY

6. Capture the exact version string for every tool found in PATH — FOUND tools via rule 1, and PROPRIETARY_ONLY tools that have a version probe in the Proprietary table via rule 4

7. Set role and dialect on every entry in the tools array from the Proprietary and Roles-and-dialects tables above; use null for both where the tool appears in neither

8. Never attempt installation in this stage

9. Write results to tool-status.json before advancing

QoR Metrics to Evaluate

• tools_detected: count of FOUND tools (target ≥ 10 for a functional open-source flow)
• tools_missing: count of MISSING open-source tools
• proprietary_found: count of PROPRIETARY_ONLY tools detected in PATH
• proprietary_versioned: count of PROPRIETARY_ONLY tools with a non-empty version

dialect_conflicts is not this stage's metric, although it reads the role and dialect recorded here: environment_validation rule 7 computes it and declares it.

Output Required

• tool-status.json — contains two top-level keys:
  • python_env: { "exec": "", "type": "module|system|custom", "bin_dir": "", "module_name": "" } — populated by rule 2
  • tools: array of { "tool": "", "command": "", "status": "FOUND|MISSING|PROPRIETARY_ONLY", "version": "", "path": "", "role": null, "dialect": null }

role and dialect are always present on every entry — a string from the tables above, or null. version is non-empty for every FOUND tool and for every PROPRIETARY_ONLY tool whose probe succeeded.

tool and command both hold the command — the executable name which is run against, as listed in backticks in the Open-Source and Proprietary tables above. module-status.json records the same value ("tool": "<command>"), which is what lets module_discovery match its entries back into this file. Product names belong in prose and in the first column of the Proprietary table; never in a field a rule matches on. A rule that names a product cannot find its entry wherever the two differ — OpenSTA's command is sta, Formality's is fm_shell — and "no entry found" is not the same answer as "tool missing".

This applies to tool-status.json and module-status.json only. The Wrapper JSON Output Schema below deliberately uses a different convention — "tool": "<tool-name>", a wrapper label such as opensta or verilator-sim — because that field identifies which wrapper produced the record, not an entry to match. Do not "correct" the wrappers to emit commands.

Note: module-based availability (FOUND_PREFER_MODULE, MISSING_LOAD_MODULE) and the module_names/versions_available fields are added in the next stage (module_discovery).

Stage: module_discovery

Domain Rules

Module system detection

A set environment variable is not proof that module can be run. Classify first, then prove invocability with the ladder below — the ladder decides, not the classification.

1. modulecmd is in PATH ⇒ module_system: "tclmod". Record in module_system_detail whether $MODULESHOME is also set.
2. $MODULESHOME is set and modulecmd is not in PATH ⇒ module_system: "custom". Read this as not confirmed Environment Modules, never as proven bespoke: a classic install can have modulecmd off PATH, and rung 3 below is what tells the two apart.
3. Neither ⇒ module_system: "none", module_listing: "UNAVAILABLE", module_listing_error: "no module system present"; emit the "none" WARN below, skip the remaining rules, write module-status.json, advance to tool_installation.

Module invocation ladder

module is frequently a shell function or alias, not a binary, so it is absent from a non-interactive shell even on a host where a module system is plainly installed. Probe the invocation; never infer it from an env var. Try these in order, stop at the first rung that succeeds by the test below, and record that rung verbatim in module_invocation.

• A rung succeeds only where it exits 0 and its output holds at least one entry-shaped line. Either test alone is insufficient; a failed rung means advance to the next, never conclude the host has no modules. Both halves are measured. Rung 5 on the reference host exits 1 and prints Usage: [-n] subcommand [arguments ...] — and that usage text itself contains the lines modulename/scope, modulename/version and modulename/scope/version, so an output-shape test on its own reads a failed rung as a successful listing of three modules named modulename. The converse case — exit 0 with no listing — is the failure mode already documented for version probes in tool_discovery rule 4, where a broken install answers 0 whatever the vendor.
• Wrap the shell, not the command. timeout execs a binary and cannot wrap a shell function: measured, timeout 60 module avail returns 127 with timeout: failed to run command 'module' on a host where rung 4 had just succeeded. Run every rung as timeout 300 bash -c '<rung>; module avail </dev/null 2>&1'.
• Budget 300 s, not the 60 s used for version probes. The listing walks every modulefile tree: 159.5 s measured on a warm NFS cache, emitting ls: cannot access ... noise from stale paths on the way. A short budget records a working module system as unprobeable.
• Always redirect stdin from /dev/null. A wrapper that prompts would otherwise block the whole run and produce no output to diagnose.
• Where every rung is exhausted: set module_listing: "UNAVAILABLE" and put the last rung's stderr in module_listing_error. Only an exhausted ladder is a WARN — an individual failed rung is not.

Listing entry format

Entries hold two or more /-separated segments and may carry a trailing parenthesised annotation. Measured on the reference host: klayout/adi/0.29.0, verilator/adi/3.922, klayout/adi/0.27.11 (adi default). Take the version as the last /-separated segment after removing any trailing (...) annotation, and keep the entry string without that annotation in module_names. Never assume <name>/<version> — that records adi as the version of klayout/adi/0.29.0.

The annotation is data, not noise. An entry whose annotation contains default (case-insensitive) is the module system's own default for that tool — on the reference host klayout/adi/0.27.11 (adi default) marks it. Record which entry carried it; the selection rule below prefers it over any version this stage computes.

Match the mapping table against the entry read as a list of /-delimited tokens, case-insensitively: a pattern matches only where it covers whole tokens — one token, or a contiguous run of them for a pattern that itself contains /. Never match an arbitrary substring. Measured against a real 3812-entry listing, substring matching produced two classes of false positive: a module whose name merely ends with a mapped command (an optimisation tool named ...slang matched slang), and a module whose name or version string merely contains one (a verification tool whose version ends _python2, and a GUI tool bundle whose name contains python3, both matched python3). The second class is the damaging one: tool_discovery Step A loads the selected matched Python module and keeps it loaded for the whole orchestrator run, and the top-ranking substring match was that GUI bundle rather than an interpreter. Whole-token matching drops both classes and leaves the 12 genuine tools.

Module version selection

Wherever this skill chooses a version for a tool — tool_discovery rule 2 Step A c and rule 9 below — it uses this rule. Do not restate it at the call sites and do not substitute a plain sort: "highest lexicographic" and "newest" are different answers, and on a real tree the lexicographic one is wrong: measured on the reference host, a 13-version Python tree spanning 3.6.x–3.14.x has newest 3.14.6 and lexicographic maximum 3.9.7 — the fourth-oldest — because "9" > "1" at the second segment.

The result is the version this host should use, which is not always the newest one: where the module system marks a default, that default wins, and a site default is commonly an older, qualified build. On the same host the annotated default differed from the newest available for every tool checked, by several versions for some. That is intended, not a bug to work around.

Selection order. Take the first that applies:

1. the entry the listing annotates as the system's default, where it marks one — that is the site's own answer and outranks anything computed here;
2. otherwise the highest release version by the comparator below;
3. otherwise the highest version at all — only where every candidate is non-release.

Non-release versions are those with any segment equal to dev, test, debug, rc, alpha, beta, snapshot or nightly, case-insensitively. They stay in versions_available — they exist and a user may want one — but they are never selected automatically while a release exists. This matters because such builds sit in the same trees as releases: the reference host carries 3.12.2_test, 3.6.2-debug and 5.24-dev alongside normal versions. Note the list is deliberately short: a site revision tag such as 3.12.2.R10, or a patch letter such as 3.9.7n, is a release and is ordered by the comparator like any other.

Comparator. Split each version on ., - and _, then compare segment by segment:

• both segments numeric — compare as integers, so 3.14.6 > 3.9.7;
• a segment of digits followed by letters (7n, 03b) — compare its numeric prefix first, then its letter suffix as text, so 3.9.7n > 3.9.7;
• one numeric and one not — the numeric ranks higher;
• neither numeric — compare as text.

Where every shared segment is equal, the version with more segments ranks higher — both 3.12.2.1 > 3.12.2 and 3.12.2.R10 > 3.12.2, since an extra segment denotes a revision of the shorter version. Do not special-case a non-numeric extra segment to rank lower: the case that motivates it, 5.24 over 5.24-dev, is already handled by the non-release exclusion above, and inside the release pool the only remaining extras are post-release revision tags, for which longer genuinely is newer.

This set is the one that breaks every naive form, and is worth checking any implementation against — 3.9.7, 3.9.7n, 3.12.2, 3.12.2.1, 3.12.2.R10, 3.14.6, 5.048, 5.24-dev: text comparison picks 3.9.7, splitting on . and comparing as integers raises on R10, and comparing by segment count alone picks 5.24-dev unless the non-release exclusion has already removed it.

Record the outcome per tool in module-status.json as selected, selected_basis and candidates, so a wrong pick is visible in the artifact rather than only in the loaded environment.

WARN taxonomy

An empty tools_via_modules is evidence that the host offers no modules only when module_listing is "LISTED". Never report an exhausted ladder as "no modules found": the two are indistinguishable in the artifact unless module_listing is read.

The fix text names both init scripts because the probes all run under bash -c regardless of the user's login shell, but a user re-running by hand may be in either bash or tcsh.

Module-to-tool mapping table

Rules

1. Classify the module system using the detection rules above
2. Obtain a listing using the invocation ladder above; record module_invocation and module_listing, and on exhaustion module_listing_error
3. If module_listing is "UNAVAILABLE": emit the matching WARN from the taxonomy above — escalating first where a critical-path tool is MISSING — write module-status.json with tools_via_modules: [], and advance. Skip rules 4-9: no tool can be matched against a listing that was never obtained, and an unmatched tool is not evidence that no module provides it
4. For each entry in the listing, test against the mapping table (case-insensitive)
5. For each matched tool, collect all available version strings per the entry-format rules above
6. Write module-status.json before advancing
7. For each tool marked FOUND in tool-status.json that also has a module available: change status to FOUND_PREFER_MODULE, add module_names and versions_available fields, include in load-modules.sh — module takes precedence over PATH version
8. For each tool marked MISSING in tool-status.json that has modules available: change status to MISSING_LOAD_MODULE, add module_names and versions_available fields
9. Generate load-modules.sh for all FOUND_PREFER_MODULE and MISSING_LOAD_MODULE tools; choose each tool's version per Module version selection above; comment out alternative versions inline, and state the basis in the selected line's trailing comment
10. Never auto-run load-modules.sh — print: "Review and source load-modules.sh to load EDA modules, then re-run the flow"

Extended tool-status.json schema

Fields added by this stage to each entry in the tools array (backward-compatible additions):

{
  "tool": "",
  "command": "",
  "status": "FOUND | FOUND_PREFER_MODULE | MISSING | MISSING_LOAD_MODULE | PROPRIETARY_ONLY",
  "version": "",
  "path": "",
  "role": null,
  "dialect": null,
  "module_names": [],
  "versions_available": []
}

Note: The top-level python_env object is preserved unchanged during this stage — only entries in the tools array are modified. The python3 tool entry is treated like any other: if python_env.type == "module", its tools array status is upgraded from FOUND to FOUND_PREFER_MODULE and it is included in load-modules.sh. The version, role and dialect fields written by tool_discovery are also preserved unchanged — this stage adds module fields and may change status, nothing else.