---

name: erie-verilog-generator description: >- Use when Codex needs Chinese-language Verilog or RTL design, existing-RTL analysis, verify-repair planning, controlled refinement planning, semantic comparison, debugging, troubleshooting, independent static lint, self-checking testbench scaffolds, or ASIC-quality review for a Verilog-target design, including synthesizable Verilog-2001 RTL, local or remote Vivado/xsim validation, artifact extraction, and workflow trace diagnosis.

Erie Verilog Generator

Use this skill for Verilog-2001 RTL generation and existing-RTL analysis/refinement/verify-repair backed by the bundled runtime/verilog_generator Python workflow. Keep generated design RTL artifacts as Verilog .v files and use the stable facade in integration/verilog_adapter.py.

For new RTL generation, expose three user-facing workflow shells:

• regular: the standard staged generation path
• deep_review: one extra structured review stage before final RTL emission
• agentic_repair: the existing verify_existing_verilog(...) evidence-driven repair flow for existing RTL

These are workflow modes, not alternate correctness gates. Do not treat free-form model self-assessment text such as [DESIGN IS CORRECT] as authoritative validation evidence.

The same skill also exposes two local helper scripts for independent static lint and testbench scaffold generation without widening the skill beyond Verilog-2001:

• scripts/verilog_lint.py for independent static lint
• scripts/tb_generator.py for a self-checking Verilog testbench scaffold

These helper tools are optional workflow steps. They are part of the skill execution flow when the request benefits from them, but they are not mandatory entry gates.

For existing RTL assets, the same runtime now exposes:

• analyze_existing_verilog(...) to emit rtl_analysis.json, project_analysis.json, and design_explanation.md
• refine_existing_verilog(...) to emit rtl_transform_plan.json plus controlled helper artifacts such as a scaffold testbench, partition wrapper skeleton, merge-assist bundle, or optimize-assist plan bundle
• compare_verilog_semantics(...) to emit equivalence.json, qor_report.json, and transform_validation.json
• verify_existing_verilog(...) to emit project_analysis.json, verification_plan.json, tb_contract.json, log_diagnosis.json, patch_candidate.json, verification_result.json, and loop_state.json The same verify-repair flow also emits simulation_slice.json, timing_diagnostic.json, expected_trace.md, waveform_diff.json, testcase_matrix.json, run_summary.json, synth_readiness.json, and terminal_status.json so the verification closure is explicit even when the run stays in static mode. When RTL repair is applicable, the same flow also emits rtl_patch_plan.json, rtl_patch_diff.txt, rtl_intervention.json, post_apply_validation.json, and post_apply_equivalence.json.

Dependency Preflight

On first use in a Codex installation, and before any remote/Vivado/Vitis-related workflow, run the dependency check from this skill root:

python .\scripts\manage_skill_dependencies.py check --settings .\config\defaults.json

If required dependencies are missing, run prompt and ask the user whether to install each missing dependency before continuing:

python .\scripts\manage_skill_dependencies.py prompt --settings .\config\defaults.json

Install only after the user confirms, then run adapt and tell the user to restart Codex so newly installed skills are discovered. Do not install fpga-agent-skills during normal preflight. If FPGA developer tooling is missing, prefer vivado-developer, vitis-developer, or pds-developer; FPGA-Agent-Skills is manual fallback only. If the user declines required dependency installation, continue only with local static Verilog generation/validation and block remote SSH, Vivado, Vitis, execute, and implement readiness paths. If recommended dependencies are missing, ask the user whether to install or skip them; use skip <dependency-id> only for a user-declined recommended dependency.

FPGA Developer Routing

Before FPGA simulation, synthesis, implementation, constraints, debug, project creation, or other vendor tool work, inspect the developer routing state:

python .\scripts\manage_skill_dependencies.py fpga-route --settings .\config\defaults.json

If both AMD-Xilinx and PangoMicro developer skills are available and no current selection exists, ask the user which vendor to use for this workflow. Persist only the user-confirmed vendor choice:

python .\scripts\manage_skill_dependencies.py select-fpga-vendor --settings .\config\defaults.json amd_xilinx
python .\scripts\manage_skill_dependencies.py select-fpga-vendor --settings .\config\defaults.json pangomicro

Developer routing preference is: vivado-developer, then vitis-developer, for AMD-Xilinx work; pds-developer for PangoMicro work. When any of these developer skills is installed, do not install the FPGA-Agent-Skills Vivado/Vitis child skills. If no developer skill is installed, treat FPGA-Agent-Skills as a manual fallback that requires explicit user direction and the --allow-fpga-agent-fallback install flag.

Workflow

1. Confirm the design intent before generation: module name, ports, clock/reset, behavior, pipeline expectation, interface family, and verification cases.
2. Choose the generation shell explicitly when it matters:
   • regular for the default staged pipeline
   • deep_review when one extra structured self-review stage would improve prompt completeness or reviewability
   • agentic_repair only when starting from existing RTL and needing the verify-repair loop
3. Use the staged pipeline:
   • regular: requirements -> codegen_plan -> python -> rtl
   • deep_review: requirements -> codegen_plan -> python -> review -> rtl
4. When the request clearly matches one of the local ADC/DAC board families, set workflow.use_case_template_id to one of spi_adc, spi_dac, jesd_adc, jesd_dac, or mxfe_mixed so the runtime can inject the matching board-level template bundle from assets/use_case_templates/.
5. Generate a Python reference model before RTL when running the workflow; use it as the semantic contract for the Verilog testbench.
6. Streaming is optional and applies only to provider interaction. Use it when the selected provider supports streaming and the host benefits from partial output visibility. The finalized response artifact remains the extraction source of truth.
7. Batch generation is generation-only in v1. Use run_verilog_batch(...) for multiple confirmed specs, keep each case in its own run directory, and do not use batch mode for existing-RTL mutation or decision-resume flows.
8. Run the mandatory quality gate before claiming usable output. validate_verilog_artifacts(...) and scripts/validate_verilog_skill.py are required quality-control steps; skipping optional helpers does not bypass this gate.
9. Use optional helper tools only when they add value to the request:
   • Run scripts/verilog_lint.py when the user asks for independent static lint, standalone review findings, or a quick local lint pass on existing RTL or testbench files.
   • Run scripts/tb_generator.py when the user asks for a fast self-checking testbench scaffold or when a repair starts from module ports rather than the full staged workflow.
10. If the request includes compile, execute, or implement readiness, continue into the local or remote backend validation path. Prefer Vivado xsim first, then VCS+Verdi, then iverilog/vvp. Use yosys only for implement readiness.
11. If the request starts from an existing RTL file instead of a fresh spec, choose the existing-RTL branch first:
    • analyze_existing_verilog(...) for structural understanding, feature mapping, and a durable design_explanation.md
    • verify_existing_verilog(...) when the task is to build a log-driven verification loop, classify failures, or prepare patch candidates with explicit automation boundaries; present this path as agentic_repair Use testbench_source when the user already has a legacy testbench that should be augmented in place or through a caller-managed overwrite flow.
    • refine_existing_verilog(..., refine_goal="tb_scaffold"|"style_refine"|"partition_assist"|"merge_assist"|"optimize_assist") for controlled assist flows
    • compare_verilog_semantics(...) before claiming two RTL variants are equivalent enough for downstream work
12. For verify_existing_verilog(...), always require an explicit automation-mode choice from the caller or user: conservative, semi_auto, or auto_apply. Do not silently choose one.
13. When an existing RTL repair needs confirmation, let the caller or user provide a follow-up decision file and resume the same verify-existing flow rather than inventing a separate repair command.

Strict Quality Policy

Strict quality control is mandatory. The required quality chain is:

1. Generate only synthesizable Verilog-2001 RTL. Verification testbenches may stay in Verilog-2001 or use SystemVerilog when the verify-repair flow needs assertion/property support.
2. Prefer standardized interfaces: AXI-Stream for streaming data, AXI4-Lite for control/status registers, AXI4 for memory-mapped bulk transfers, and AHB/APB when a platform requires them. If a custom shape still needs bus unification, extend AXI-Stream with explicit sideband metadata in interface_profile.
3. Use the local standard bus templates in assets/interface_templates whenever interface_family is axi_stream, axi4_lite, axi4, ahb, or apb. Treat their port names, parameter names, and Chinese comments as strict-preferred defaults; only adapt them when the confirmed spec explicitly conflicts, and record the adaptation reason in the generated checks.
4. When workflow.use_case_template_id is set, preserve the selected family bundle from assets/use_case_templates/ as board-level guidance and keep any adaptation visible in the generated checks and codegen plan.
5. When rtl_style_profile=erie_strict, also follow the ref-derived Erie naming, header, FSM, instance, and bus-grouping conventions captured in references/erie-ref-style.md and assets/style_templates/.
6. Treat semantic comment placement as a hard validation gate: every non-empty generated Verilog code line in RTL and testbench .v files must have a same-line explanatory comment in the requested language, and each construct type must follow references/verilog-comment-placement.md. Blank lines and pure comment lines are exempt; missing, misplaced, shared-adjacent, or generic Chinese comments under comment_language=zh are blocking errors.
7. Avoid Verilog function and task blocks in generated Verilog, especially synthesizable RTL; prefer explicit always/assign logic and inline testbench checks for easier waveform debugging.
8. Apply ASIC quality review rules for generated RTL: complete combinational assignments, case defaults, no raw gated clocks, documented CDC/reset assumptions, and timing-reviewable datapath/control structure. Load references/asic-verilog-quality.md for detailed review guidance.
9. Validate with static checks by default; when external simulation is requested, select the highest available backend in this order: Vivado xsim, VCS+Verdi, then iverilog/vvp. Use yosys only for implement readiness.

For optimize_assist, QoR output is advisory by default: it produces structural summaries and optional yosys evidence when available, but it does not automatically approve or rewrite RTL. For merge_assist, the flow stays plan-only by default: it emits merge_plan.json, merge_wrapper.v, merge_validation.json, and merge_equivalence.json to support wrapper-first repartition or recompose work without silently rewriting the source RTL.

For verify-repair flows, conservative is report-only, semi_auto requires user confirmation before overwriting source RTL or testbench files, and auto_apply may only apply candidate changes after the caller explicitly selected that mode. When tb_mode="augment", preserve the original testbench body, emit tb_augment_plan.json plus tb_augment_diff.txt, back up the original testbench before any overwrite, and record original/backup/active paths in tb_contract.json. When RTL mutation is available, emit rtl_patch_plan.json plus rtl_patch_diff.txt, back up every affected RTL file before overwrite, record backup/active paths in patch_candidate.json, and use rtl_intervention.json plus decision.json for confirmation-driven resume. Current patch categories include reset_initialization_completion, case_default_completion, state_hold_clear_completion, and output_register_completion; only reset_initialization_completion keeps auto_apply eligibility, while the newer control/timing categories downgrade to confirmation before apply even when the requested mode is auto_apply. Every verify-repair run must also preserve the standardized diagnostics pack and terminal-status artifact so downstream tooling can distinguish pass, not_run, timeout, and confirmation-blocked closures without scraping free-form logs.

Optional helper tools are inside the workflow, but strict quality control is the only mandatory gate.

Remote Vivado Fallback

When the user requests compile, simulation, execute, or implement readiness, treat external validation as remote-first by default. Do not silently fall back to local Vivado, xsim, VCS, iverilog, or yosys. Keep project-local Verilog settings in .settings/verilog.local.json, keep the remote server registry in .settings/server_list.local.json, keep the user-confirmed remote target in .settings/remote-selection.local.json, and require the selected remote workdir to provide .settings/verilog.remote.json before remote external validation continues. First run the erie-remote-ssh discovery and choice flow:

python <erie-remote-ssh>\scripts\remote_ssh.py discover --settings <remote-settings> --config <server-list>
python <erie-remote-ssh>\scripts\remote_ssh.py choices --settings <remote-settings> --config <server-list>

Ask the user to select a remote server unless they already named one in the current request. A configured default server is only a recommendation; it is not user confirmation. After selection, use erie-remote-ssh for check, scan-software, workspace-check, request creation, and run-request --execute. If remote discovery sees multiple Vivado settings64.sh candidates, stop and ask the user which version to use; persist that confirmed choice into the remote workdir .settings/verilog.remote.json before development or validation continues. Remote validation directories are retained by default under .erie-verilog-generator-validation/run-YYYYMMDDTHHMMSS/erie-verilog-generator, including _smoke_runs outputs; use --cleanup-remote only when the user wants the validation directory deleted. The remote gate must execute the canonical workflow plus the fixed RTL fixtures in assets/examples/remote_fixtures and retain each fixture validation.json. Use --report-runs for a read-only summary of retained remote runs. Do not add direct ssh or scp commands to this skill.

For Vivado/Vitis project creation, Tcl execution, synthesis/implementation strategy, timing analysis, constraints, debug, simulation, or Vitis HLS work, follow FPGA developer routing first. Use vivado-developer or vitis-developer for AMD-Xilinx and use pds-developer for PangoMicro. Do not install or route to FPGA-Agent-Skills Vivado/Vitis child skills unless the user explicitly requests that manual fallback.

Host Integration

Use integration.verilog_adapter:

• run_verilog_workflow(...) for full staged execution or resume.
• run_verilog_batch(...) for generation-only batch execution across isolated case run directories.
• render_verilog_prompt(...) when the host owns the model call.
• validate_verilog_artifacts(...) before downstream use.
• verify_existing_verilog(...) for the stable existing-RTL verify-repair entrypoint and agentic_repair mode.

For GUI-hosted Code Design sessions, return artifacts through the host artifact protocol when requested. Do not require local external tools for GUI admission; local tool checks are optional diagnostics.

Reference Loading

• Load ENGINEERING_DESIGN_GOALS.md when changing this skill's architecture or scope.
• Load references/skill-standards.md when changing SKILL frontmatter, trigger wording, progressive disclosure, supporting-resource layout, or skill-level evaluation gates.
• Load references/configuration.md when changing paths, validation gates, remote SSH settings, or temporary run locations.
• Load references/erie-ref-style.md when changing Erie strict naming rules, bilingual headers, FSM conventions, instance naming, or grouped bus-port style.
• Load references/verilog-comment-placement.md when changing generated Verilog comments, comment validation, testbench scaffolds, prompt rules, or fixtures that contain RTL/testbench comments.
• Load references/integration.md when wiring the facade into another host.
• Load assets/use_case_templates/catalog.json and the selected bundle under assets/use_case_templates/<family>/ when adding or reviewing ADC/DAC board-level family guidance.
• Load references/workflow-contracts.md when handling run directories, statuses, resume behavior, or traces.
• Load references/asic-verilog-quality.md when reviewing RTL for ASIC quality, static lint findings, reset/CDC assumptions, raw gated clocks, latch risk, or timing-reviewable structure.
• Load references/lint-checklist.md when running independent static lint, preparing review findings, or deciding whether a warning should become a blocking issue.
• Load references/testbench-patterns.md when generating or repairing a Verilog-2001 self-checking testbench scaffold.
• Use assets/examples/rtl_erie_verilog_spec.json as the canonical Verilog-only fixture.
• Use assets/examples/use_case_templates/*.json when verifying ADC/DAC family-template selection and prompt injection.
• Use evals/evals.json when measuring pass-rate delta for the canonical Verilog flow and the ADC/DAC family-template flows.
• Load references/verilog-template-patterns.md when refining compact reusable Verilog design patterns distilled from the local repository reference RTL instead of copying large reference modules.
• Use assets/interface_templates/catalog.json and the referenced .vinc snippets when verifying or updating standard AXI-Stream, AXI4-Lite, AXI4, AHB, or APB interface guidance.
• Use assets/refined_verilog_templates/catalog.json and the referenced .vinc snippets when the task benefits from compact AXI4-Lite CSR, AXIS ready/valid, AXI interconnect grouping, or convolution load/store pattern hints.
• Use assets/style_templates/ when refining Erie strict header, region-order, FSM, instance, or bus-grouping style guidance.
• Use assets/examples/remote_fixtures when verifying real-style remote xsim coverage across combinational logic, sequential pipeline logic, and ready/valid handshakes.

Boundaries

• Do not generate non-Verilog hardware flows, C/C++ kernels, or alternate RTL dialects.
• Do not claim external tool validation happened unless the tool actually ran.
• Do not add direct SSH/SCP logic; use erie-remote-ssh and configured JSON for remote validation.
• Treat VCS+Verdi support as scripted backend invocation only; full Verdi GUI/session automation is out of scope unless it is explicitly added and validated.
• Keep workflow outputs in caller-selected run directories such as reports/; do not store generated run artifacts inside the skill.