| name | rat-setup |
| description | One-time EDA toolchain setup wizard: verify or install tools, build Docker EDA image. Triggers: 'setup tools', 'install tools', 'EDA setup'. |
| user-invocable | true |
Interactive one-time environment setup wizard for the RTL Agent Team plugin.
Audits EDA tools, test infrastructure, and plugin configuration.
Guides the user through installation choices with categorized questions.
For per-project directory structure and rules deployment, use `rat-init-project` instead.
<Use_When>
- First time installing the plugin on a new machine
- Verifying EDA toolchain is properly installed
- Installing missing required EDA tools
- User says "setup tools", "install tools", "EDA setup", "check tools"
- User says "docker image", "make docker", "EDA environment container"
- Recommended by
rat-init-project when required tools are missing
</Use_When>
<Do_Not_Use_When>
- Initializing a new project workspace (use
rat-init-project)
- Tools are already verified and working
- Only need to run a specific EDA tool (use the tool-specific skill)
</Do_Not_Use_When>
<Why_This_Exists>
The 6-Phase pipeline depends on EDA CLI tools (Verilator, verible/slang, cocotb, etc.).
Without proper tool installation, design and verification agents fail with tool-not-found errors.
This skill ensures the EDA environment is ready before any design work begins.
</Why_This_Exists>
<Execution_Policy>
- Interactive: ask the user before installing anything or changing configuration
- Report tool status honestly: installed version or "NOT FOUND"
- If any required tool is missing, mark setup as NOT READY and explicitly require installation
- Default to user-local installs under
~/.local/bin, ~/.local, or ~/tools (LLM has no sudo access)
- For
global mode, print sudo commands for the user to run manually
- Never overwrite existing user configuration without confirmation
</Execution_Policy>
Paths below are relative to this skill's base directory (announced at invocation as "Base directory for this skill").
<Reference_Files>
| Path | Read When |
|---|
references/tool-check-commands.md | Before Phase 1 Discovery — exact Bash CLI check commands for every tier. |
references/install-commands.md | After Q1 collects a remediation choice for a missing Tier 1 tool. |
references/docker-environment.md | User chooses docker mode, or asks about the Docker EDA image. |
references/output-templates.md | Producing the Phase 2 report, Q2b prompts, NAND2 extraction, or the Phase 5 final report. |
| </Reference_Files> | |
Phase 1: Discovery (silent scan — no questions yet)
Read references/tool-check-commands.md for the exact Bash CLI commands, then
run all checks in parallel via the Bash tool (never MCP) and collect results.
1a. EDA Tool Audit
Categorize tools into three tiers:
Tier 1 — Required (pipeline cannot function without these):
- python3 — cocotb runtime, hook JSON parsing
- gcc/g++ — Reference model build (C11/C++17)
- make — Build system
- verilator — Simulation + Lint
- cocotb — Functional verification
- systemc — SystemC/TLM-2.0 (ref model, BFM)
- lint tool —
verible-verilog-lint AND/OR slang; at least ONE required
- cdc tool —
svlens OR a commercial CDC tool (sg_shell/vc_cdc/questa_cdc); at least ONE
required. svlens also supplements lint (width/type/dangling checks via svlens conn) when
verible/slang are missing
Tier 2 — Recommended (significantly improves workflow):
- jq — Hook JSON parser (robust state gating)
- sv-renamer — SV identifier rename + semantic diff
- sv_to_ipxact — SV → IP-XACT XML auto-generation
- slang-server — SV Language Server (LSP for Claude Code)
- verible (if slang only) — Style lint + formatting
- slang (if verible only) — Deep semantic lint
Tier 3 — Optional (needed for specific phases):
- iverilog — Fallback simulator
- yosys — Synthesis (Phase 5B+)
- sby — Formal verification (SymbiYosys)
- gtkwave — Waveform viewer
- docker — EDA tool fallback container
- sv2v — SV→Verilog for formal tools
1b. Test Infrastructure Audit
- pytest — Plugin unit test runner
- cocotb-bus — Bus protocol models
- numpy — BD-rate calculations
- hjson — Config file parsing
1c. Plugin Configuration State
test -d ~/.claude/rules && ls ~/.claude/rules/ 2>/dev/null
test -f ~/.claude/settings.json && cat ~/.claude/settings.json
claude plugin list --json 2>/dev/null || echo "PLUGIN_LIST_UNAVAILABLE"
1d. Commercial Tool Scan
Probe commonly used commercial EDA tools (optional, but significantly enhance the pipeline
when available): vcs, xrun, vsim (simulators); dc_shell, genus (synthesis);
sg_shell, vc_cdc, questa_cdc (lint/CDC); fm_shell, lec (equivalence); verdi,
simvision (debug).
Check commands, vendors, and categories: references/tool-check-commands.md.
Record for each: detected (true/false), path, version string (if available). Separate
detected tools from undetected for Phase 3 Q2b.
Phase 2: Report (show categorized results)
Present results in a clear categorized table: Tier 1/2/3 tool status, Test Infrastructure,
Commercial Tools (PATH scan), Plugin Configuration, and a final "Ready to start: Yes/No"
line (No if any required tool is missing).
Exact template with example values:
references/output-templates.md (§ Phase 2 Report).
Phase 3: Interactive Decisions (AskUserQuestion for each category)
Only ask questions for items that need action. Skip categories where everything is already satisfied.
Q1: Required tool remediation (if any Tier 1 tool is missing)
If required tools are missing, installation is required before real design work can begin.
CDC tool special rule: The Tier 1 cdc tool requirement is satisfied if ANY of
the following is present: svlens, sg_shell, vc_cdc, questa_cdc. Check Phase 1d
results first — if a commercial CDC tool is detected, mark the cdc tool requirement as
satisfied and skip svlens from the missing list. Otherwise, include svlens in the
missing required tools list and install it (open-source, no license required).
Lint tool rule: The Tier 1 lint tool requirement is satisfied if at least one of
verible-verilog-lint or slang is present. If neither is present AND svlens is also
missing, install BOTH svlens (for CDC) and at least one lint tool. If svlens is present
but lint is missing, still install a lint tool — svlens conn mode catches some lint
issues (width/type/dangling) but does not replace style/semantic lint.
Before installing missing required tools, ask the user:
Required tools missing: [list]
How would you like to install them?
local — install under ~/.local/bin (I'll execute directly, recommended)global — print sudo commands for user to run manuallydocker — use Docker EDA image as fallback (requires docker)skip — skip for now (pipeline will NOT be fully functional)
Q2: Optional/Recommended Tools (if any Tier 2-3 tools are missing)
Optional tools available for installation: [list with purpose]
Which would you like to install? (comma-separated numbers, 'all', or 'none')
- jq — robust JSON parsing in hooks
- yosys + sby — synthesis + formal verification
- slang-server — SV LSP integration for Claude Code
- iverilog — fallback simulator
- gtkwave — waveform viewer
Q2b: Commercial Tool Configuration
Only ask this if any commercial tools were scanned in Phase 1d. Group tools into two
lists: detected and undetected.
For detected commercial tools — confirm correctness: present the detected tools
(# / Tool / Vendor / Path) and ask whether these are the versions the user wants to use
(yes / no — correct individually / skip). If user says "no", ask which tool to correct
and what env_source command to use instead.
For undetected commercial tools — ask if the user has a setup script: present the
undetected tools (# / Tool / Vendor / Purpose) and ask the user to enter sourcing
commands in number: command format, or skip.
Exact prompt wording and example tables:
references/output-templates.md (§ Q2b Examples).
After collecting responses, verify each provided env_source by running:
bash -c 'eval "$1" >/dev/null 2>&1 && command -v -- "$2"' \
_ "$env_source" "$tool" 2>/dev/null
Report results: if the tool is now found, mark as OK. If still not found, warn the user
and offer to re-enter or skip.
Q2c: Synthesis Target Library (optional)
Synthesis target library configuration.
Providing a Liberty timing library (.lib) enables accurate gate-count estimation
and is required for commercial synthesis (DC/Genus).
Yosys works without a Liberty file using built-in models.
- Provide path to Liberty file (.lib)
skip — no library (Yosys built-in model only)
If providing a path, optionally specify:
- Technology description (e.g., "TSMC 28nm", "Sky130")
- NAND2 cell name pattern if different from default (default:
NAND2X1)
If user provides a Liberty path, validate file exists:
test -f "$liberty_path" && echo "OK" || echo "File not found"
Q3: Plugin Global Configuration
Plugin conventions can be deployed globally for access in ALL projects.
This makes RTL conventions available even without running rat-init-project per project.
Deploy global configuration? (yes/no)
What will be deployed:
~/.claude/rules/rtl-coding-conventions.md — port naming (i_/o_), clock/reset conventions~/.claude/rules/rtl-verification-gate.md — mandatory lint→TB→sim after RTL changes~/.claude/CLAUDE.md — diagram convention block (if not already present)
Diagram Rule Injection
Check if ~/.claude/CLAUDE.md already contains <markdown_diagram_rule> tag.
- If tag found → skip (already deployed)
- If tag NOT found → append the following block:
<markdown_diagram_rule>
## Diagram Policy
| Diagram Type | Tool | Use For |
|-------------|------|---------|
| **Block diagram** | **D2** | Architecture, module hierarchy, HW block decomposition |
| **Flow / Interaction** | **Mermaid** | Pipeline stages, FSM, data/control flow, sequence diagrams |
| **ASCII flow diagram** | **Prohibited** | Do NOT use ASCII art — use D2 or Mermaid |
D2: architecture diagrams (`.d2` code blocks), per-module internal structure.
Mermaid: FSM (`stateDiagram-v2`), data flow (`flowchart`), sequences (`sequenceDiagram`).
</markdown_diagram_rule>
Implementation:
if ! grep -q '<markdown_diagram_rule>' ~/.claude/CLAUDE.md 2>/dev/null; then
:
fi
Q4: Test Infrastructure (if pytest/cocotb deps missing)
Test dependencies missing: [list]
Install in the managed RTL Agent Team virtual environment? (yes/no)
RAT_EDA_VENV="$HOME/.local/share/rtl-agent-team/venv"
mkdir -p "$(dirname "$RAT_EDA_VENV")"
python3 -m venv "$RAT_EDA_VENV"
"$RAT_EDA_VENV/bin/python" -m pip install pytest cocotb cocotb-bus numpy hjson
IMPORTANT: After receiving all Q1-Q5 answers, immediately proceed to Phase 4 execution
in the same response. Do NOT pause or wait for user confirmation between Phase 3 and Phase 4.
The user has already made their decisions — execute them without an extra turn boundary.
Phase 4: Execute (based on user answers)
4a. Tool Installation
Execute installation commands based on Q1/Q2 answers.
local mode: LLM executes directly (no sudo)global mode: print sudo commands for user to run manuallydocker mode: build Docker image if not present
Actively look up the latest stable version from official upstream sources before
giving install commands for fast-moving tools such as Verilator and SystemC. Exact
per-mode install scripts: references/install-commands.md.
4b. Commercial Tool Configuration (if Q2b answered)
For each tool where the user provided an env_source command or corrected a path,
record the information in the machine-wide env-config.json:
PLUGIN_DIR="${CLAUDE_PLUGIN_DATA:-$HOME/.config/rtl-agent-team}"
mkdir -p "$PLUGIN_DIR"
Store collected commercial tool sourcing commands in the tools section
of $PLUGIN_DIR/env-config.json. These values will be seeded into
per-project rat_config.json when rat-init-project runs generate_config.sh.
For each provided env_source, verify the tool is accessible:
bash -c 'eval "$1" >/dev/null 2>&1 && command -v -- "$2"' \
_ "$env_source" "$tool" 2>/dev/null
Report verification results (Tool / env_source / Status: OK or FAILED). If a tool is not
found after sourcing, warn but proceed — the user can fix env_source later in
rat_config.json and re-run generate_config.sh.
4b-tech. Target Library Configuration (if Q2c answered)
If the user provided a Liberty file path:
- Validate the file exists.
- Extract NAND2 area using the same logic as
generate_config.sh — exact awk script:
references/output-templates.md (§ NAND2 Area Extraction).
- Record the technology name, liberty path, NAND2 cell pattern, and extracted area in
env-config.json's
technology section (exact JSON shape in the same reference).
- Report result: technology name, liberty path, extracted NAND2 area (or "not found in lib").
4c. Plugin Config Deployment (if Q3 = yes)
RTL rules → ~/.claude/rules/ (path-scoped, RTL files only):
mkdir -p ~/.claude/rules
[ ! -f ~/.claude/rules/rtl-coding-conventions.md ] && cp "${CLAUDE_PLUGIN_ROOT}/skills/rat-init-project/templates/rules/rtl-coding-conventions.md" ~/.claude/rules/
[ ! -f ~/.claude/rules/rtl-verification-gate.md ] && cp "${CLAUDE_PLUGIN_ROOT}/skills/rat-init-project/templates/rules/rtl-verification-gate.md" ~/.claude/rules/
Diagram rule → ~/.claude/CLAUDE.md (tagged block, all projects):
if ! grep -q '<markdown_diagram_rule>' ~/.claude/CLAUDE.md 2>/dev/null; then
:
fi
See Q3 section for the exact block content.
4d. Test Infra Installation (if Q4 = yes)
RAT_EDA_VENV="$HOME/.local/share/rtl-agent-team/venv"
mkdir -p "$(dirname "$RAT_EDA_VENV")"
python3 -m venv "$RAT_EDA_VENV"
"$RAT_EDA_VENV/bin/python" -m pip install pytest cocotb cocotb-bus numpy hjson
Phase 5: Verify & Final Report
Re-check installed tools and present final status: Tool Status by tier
(installed/total/PASS-PARTIAL), Commercial Tools, Target Technology, Plugin Configuration.
Exact template with example values:
references/output-templates.md (§ Phase 5 Final Report).
Setup Marker + Environment Config (advisory)
Write setup completion marker and machine-wide EDA environment config to
${CLAUDE_PLUGIN_DATA} (persistent plugin data directory, survives plugin updates).
The actual enforcement gate remains .claude/rules/rtl-coding-conventions.md (project-level).
Exact bash (marker + env-config.json heredoc template):
references/output-templates.md (§ Setup Marker + Environment Config).
Note to orchestrator: The env-config.json tools/preferences placeholders must be
replaced with actual Phase 1 scan results, using the same detection logic and output
format as generate_config.sh.
Next Steps
- Run
/rtl-agent-team:rat-init-project in your project directory to initialize project structure
- Run
/rtl-agent-team:rat-tutorial for a guided walkthrough of the pipeline
<Tool_Usage>
All EDA tools are executed via Bash CLI directly (never MCP). Run every Tier 1/2/3, test
infrastructure, commercial-tool, and plugin-config check command in parallel — the exact
commands live in references/tool-check-commands.md.
Interactive questions (Q1-Q4) use AskUserQuestion.
</Tool_Usage>
<Install_Instructions>
When tools are missing, provide installation commands based on the user's choice of
local (default), global, docker, or macOS (Homebrew). Before installing fast-moving
tools (Verilator, SystemC), resolve the latest stable version from upstream sources.
RHEL/CentOS-family distros may need a newer GCC toolset activated before source builds.
Exact commands for all modes: references/install-commands.md.
</Install_Instructions>
## Docker EDA Image Details
Only needed when the user chooses the docker install mode (Q1) or asks about the
Docker EDA image build args, run commands, or included tool versions.
Read references/docker-environment.md for the build/run commands and
the included-tools version table.
<Escalation_And_Stop_Conditions>
- Required tool not found → report with install commands, require installation
- Neither verible nor slang found → report as REQUIRED
- Only one of verible/slang → proceed with WARNING recommending the other
- Neither svlens nor commercial CDC tool (sg_shell/vc_cdc/questa_cdc) found → report as REQUIRED (svlens is open-source default)
- svlens missing but commercial CDC tool present → mark CDC requirement satisfied, still offer svlens install as open-source supplement
- Before installing → ask user: local (default) / global / docker / skip
- Before installing fast-moving tools → verify latest stable version from upstream
- Before deploying global rules → confirm with user (never overwrite existing)
jq not found → report as recommended (hooks fall back to python/sed)- Python version < 3.9 → report incompatibility
- Commercial tool detected → confirm with user before recording (Q2b)
- Commercial tool not detected → offer env_source entry, verify in subshell (Q2b)
- User-provided env_source fails verification → warn, allow re-entry or skip
- Liberty file path not found → warn, allow re-entry or skip (Q2c)
- NAND2 pattern not found in Liberty → warn, record liberty path with null area
</Escalation_And_Stop_Conditions>
<Final_Checklist>
