Skip to content

Eriemon/verilog-generator

readable-verilog-generator

Verified

Use when creating, writing, reviewing, annotating, repairing, refactoring, or validating readable Verilog RTL, including synthesizable Verilog-2001 .v files, existing-RTL analysis, semantic comment annotation, testbench scaffold planning, ASIC-quality review, local or remote Vivado/xsim validation, evidence-backed repair, and workflow trace diagnosis.

FileKindSize
SKILL.mdskill md21.3 KB
agents/openai.yamlconfig363 B
assets/examples/existing_rtl/fsm_without_default.vother761 B
assets/examples/existing_rtl/fsm_without_default_spec.mdmarkdown311 B
assets/examples/existing_rtl/leaf_counter.vother314 B
assets/examples/existing_rtl/missing_output_register.vother423 B
assets/examples/existing_rtl/missing_output_register_spec.mdmarkdown331 B
assets/examples/existing_rtl/ready_valid_slice.vother967 B
assets/examples/existing_rtl/ready_valid_slice_spec.mdmarkdown420 B
assets/examples/existing_rtl/reset_gap_counter.vother319 B
assets/examples/existing_rtl/reset_gap_counter_spec.mdmarkdown212 B
assets/examples/existing_rtl/tb_ready_valid_slice.vother846 B
assets/examples/existing_rtl/top_counter.vother271 B
assets/examples/existing_rtl/traffic_light.vother2.5 KB
assets/examples/existing_rtl/traffic_light_spec.mdmarkdown585 B
assets/examples/readme/axis_packet_meter.vother10.2 KB
assets/examples/remote_fixtures/comb_hierarchy_budget/generated/rtl/comb_hierarchy_budget.vother1.9 KB
assets/examples/remote_fixtures/comb_hierarchy_budget/generated/tb/tb_comb_hierarchy_budget.vother2.5 KB
assets/examples/remote_fixtures/comb_hierarchy_budget/hierarchy_child_loop.vother447 B
assets/examples/remote_fixtures/comb_hierarchy_budget/hierarchy_over_budget.vother527 B
assets/examples/remote_fixtures/comb_hierarchy_budget/hierarchy_q_cut.vother467 B
assets/examples/remote_fixtures/comb_hierarchy_budget/hierarchy_within_budget.vother450 B
assets/examples/remote_fixtures/comb_hierarchy_budget/spec.jsonconfig1.7 KB
assets/examples/remote_fixtures/comb_operation_budget/comb_operation_budget_bad.vother187 B
assets/examples/remote_fixtures/comb_operation_budget/generated/rtl/comb_operation_budget.vother6.1 KB
assets/examples/remote_fixtures/comb_operation_budget/generated/tb/tb_comb_operation_budget.vother5.7 KB
assets/examples/remote_fixtures/comb_operation_budget/spec.jsonconfig2.9 KB
assets/examples/remote_fixtures/comb_parity_mux/generated/rtl/comb_parity_mux.vother2.1 KB
assets/examples/remote_fixtures/comb_parity_mux/generated/tb/tb_comb_parity_mux.vother2.8 KB
assets/examples/remote_fixtures/comb_parity_mux/spec.jsonconfig1.9 KB
assets/examples/remote_fixtures/pipeline_delay/generated/rtl/pipeline_delay.vother4.5 KB
assets/examples/remote_fixtures/pipeline_delay/generated/tb/tb_pipeline_delay.vother2.6 KB
assets/examples/remote_fixtures/pipeline_delay/spec.jsonconfig2.2 KB
assets/examples/remote_fixtures/ready_valid_slice/generated/rtl/ready_valid_slice.vother5.2 KB
assets/examples/remote_fixtures/ready_valid_slice/generated/tb/tb_ready_valid_slice.vother2.9 KB
assets/examples/remote_fixtures/ready_valid_slice/spec.jsonconfig2.6 KB
assets/examples/rtl_erie_verilog_spec.jsonconfig2.1 KB
assets/examples/use_case_templates/jesd_adc.jsonconfig2.4 KB
assets/examples/use_case_templates/jesd_dac.jsonconfig2.5 KB
assets/examples/use_case_templates/mxfe_mixed.jsonconfig2.7 KB
assets/examples/use_case_templates/spi_adc.jsonconfig2.8 KB
assets/examples/use_case_templates/spi_dac.jsonconfig2.7 KB
assets/examples/verilog_pattern_templates/axi4_lite_csr.jsonconfig2.1 KB
assets/examples/verilog_pattern_templates/axi_interconnect_dma.jsonconfig2.3 KB
assets/examples/verilog_pattern_templates/axis_ready_valid.jsonconfig2.3 KB
assets/examples/verilog_pattern_templates/conv_load_store.jsonconfig1.8 KB
assets/external_interface_catalog.jsonconfig2.9 KB
assets/ideal_bad_style_metrics.jsonconfig17.5 KB
assets/installer/manifest.projection.jsonconfig2.8 KB
assets/installer/platforms.jsonconfig1.3 KB
assets/interface_templates/ahb_lite_config.vincother2.3 KB
assets/interface_templates/apb_config.vincother861 B
assets/interface_templates/axi4_full_master.vincother1.8 KB
assets/interface_templates/axi4_full_slave.vincother1.8 KB
assets/interface_templates/axi4_lite_config.vincother1.6 KB
assets/interface_templates/axi_stream_duplex.vincother1.1 KB
assets/interface_templates/catalog.jsonconfig2.6 KB
assets/project_ip_interface_manifest.template.jsonconfig9.4 KB
assets/readme-workflow.pngbinary1.4 MB
assets/readme/design-profile-cn.pngbinary1.4 MB
assets/readme/design-profile.pngbinary1.4 MB
assets/readme/evidence-guard-cn.pngbinary1.4 MB
assets/readme/evidence-guard.pngbinary1.4 MB
assets/readme/hero-overview-cn.pngbinary1.5 MB
assets/readme/hero-overview.pngbinary1.5 MB
assets/readme/project-facts-cn.pngbinary1.2 MB
assets/readme/project-facts.pngbinary1.3 MB
assets/readme/rule-rendering-cn.pngbinary1.4 MB
assets/readme/rule-rendering.pngbinary1.2 MB
assets/style_templates/header_prompt_none_mode.txtmarkdown2.1 KB
assets/style_templates/header_prompt_table_mode.txtmarkdown2.5 KB
assets/style_templates/rtl_bus_grouping.tplother1.0 KB
assets/style_templates/rtl_fsm.tplother832 B
assets/style_templates/rtl_header_bilingual.tplother1.6 KB
assets/style_templates/rtl_instantiation.tplother496 B
assets/style_templates/rtl_region_order.tplother987 B
assets/use_case_templates/catalog.jsonconfig2.8 KB
assets/use_case_templates/jesd_adc/README.mdmarkdown699 B
assets/use_case_templates/jesd_adc/constraints/system_constr.xdcother454 B
assets/use_case_templates/jesd_adc/manifest.jsonconfig1.7 KB
assets/use_case_templates/jesd_adc/tcl/common_bd.tclother4.0 KB
assets/use_case_templates/jesd_adc/tcl/system_bd.tclother920 B
assets/use_case_templates/jesd_adc/tcl/system_project.tclother1.0 KB
assets/use_case_templates/jesd_adc/verilog/system_top.vother2.9 KB
assets/use_case_templates/jesd_dac/README.mdmarkdown745 B
assets/use_case_templates/jesd_dac/constraints/system_constr.xdcother299 B
assets/use_case_templates/jesd_dac/manifest.jsonconfig1.7 KB
assets/use_case_templates/jesd_dac/tcl/common_bd.tclother4.8 KB
assets/use_case_templates/jesd_dac/tcl/system_bd.tclother923 B
assets/use_case_templates/jesd_dac/tcl/system_project.tclother1.1 KB
assets/use_case_templates/jesd_dac/verilog/system_top.vother2.9 KB
assets/use_case_templates/mxfe_mixed/README.mdmarkdown739 B
assets/use_case_templates/mxfe_mixed/constraints/system_constr.xdcother380 B
assets/use_case_templates/mxfe_mixed/manifest.jsonconfig1.8 KB
assets/use_case_templates/mxfe_mixed/tcl/common_bd.tclother5.4 KB
assets/use_case_templates/mxfe_mixed/tcl/system_bd.tclother1.2 KB
assets/use_case_templates/mxfe_mixed/tcl/system_project.tclother1.2 KB
assets/use_case_templates/mxfe_mixed/verilog/system_top.vother3.4 KB
assets/use_case_templates/spi_adc/README.mdmarkdown925 B
assets/use_case_templates/spi_adc/constraints/system_constr.xdcother635 B
assets/use_case_templates/spi_adc/manifest.jsonconfig1.7 KB
assets/use_case_templates/spi_adc/tcl/common_bd.tclother6.3 KB
assets/use_case_templates/spi_adc/tcl/system_bd.tclother1.6 KB
assets/use_case_templates/spi_adc/tcl/system_project.tclother982 B
assets/use_case_templates/spi_adc/verilog/system_top.vother4.2 KB
assets/use_case_templates/spi_dac/README.mdmarkdown757 B
assets/use_case_templates/spi_dac/constraints/system_constr.xdcother546 B
assets/use_case_templates/spi_dac/manifest.jsonconfig1.6 KB
assets/use_case_templates/spi_dac/tcl/common_bd.tclother5.7 KB
assets/use_case_templates/spi_dac/tcl/system_bd.tclother1.0 KB
assets/use_case_templates/spi_dac/tcl/system_project.tclother981 B
assets/use_case_templates/spi_dac/verilog/system_top.vother3.5 KB
assets/verilog_formatter_config/defaults.jsonconfig6.2 KB
assets/verilog_formatter_config/profiles/conservative.jsonconfig283 B
assets/verilog_formatter_config/profiles/example_compat.jsonconfig484 B
assets/verilog_formatter_config/profiles/formatter-lint.jsonconfig121 B
assets/verilog_formatter_config/profiles/formatter-normalize.jsonconfig182 B
assets/verilog_formatter_config/profiles/formatter-preserve.jsonconfig385 B
assets/verilog_formatter_config/profiles/formatting.jsonconfig270 B
assets/verilog_formatter_config/profiles/lint.jsonconfig269 B
assets/verilog_formatter_config/profiles/migration.jsonconfig239 B
assets/verilog_formatter_config/profiles/stress_cases_compat.jsonconfig484 B
assets/verilog_formatter_config/profiles/vitis-wrapper.jsonconfig486 B
assets/verilog_formatter_config/schema.jsonconfig13.7 KB
assets/verilog_formatter_config/templates/task-batch.jsonconfig212 B
assets/verilog_formatter_config/templates/task-inplace.jsonconfig221 B
assets/verilog_formatter_config/templates/task-single-file.jsonconfig220 B
assets/verilog_pattern_templates/axi4_lite_csr_shell.vincother562 B
assets/verilog_pattern_templates/axi_interconnect_port_groups.vincother592 B
assets/verilog_pattern_templates/axis_ready_valid_slice.vincother494 B
assets/verilog_pattern_templates/catalog.jsonconfig2.2 KB
assets/verilog_pattern_templates/conv_load_store_pipeline.vincother457 B
assets/verilog_pattern_templates/counter_state_bridge.vincother443 B
assets/verilog_pattern_templates/equivalence_wrapper_probe.vincother306 B
assets/verilog_pattern_templates/fsm_state_transition.vincother1.0 KB
assets/verilog_pattern_templates/phase_output_registering.vincother404 B
assets/verilog_pattern_templates/wrapper_top_stitching.vincother608 B
assets/verilog_quality_gates.jsonconfig38.2 KB
assets/verilog_style_rules.jsonconfig11.8 KB
assets/xilinx_primitive_semantics.jsonconfig21.4 KB
references/checklists/capability-distillation-checklist.mdmarkdown3.0 KB
references/checklists/lint-checklist.mdmarkdown3.6 KB
references/checklists/verilog-readability-gate.mdmarkdown3.5 KB
references/corpus/verilog-style-observations.mdmarkdown4.6 KB
references/integration/configuration.mdmarkdown19.9 KB
references/integration/host-integration.mdmarkdown10.6 KB
references/rules/asic-verilog-quality.mdmarkdown3.9 KB
references/rules/erie-style.mdmarkdown6.3 KB
references/rules/testbench-patterns.mdmarkdown3.2 KB
references/rules/verilog-code-comment-naming-standard.mdmarkdown55.6 KB
references/rules/verilog-comment-placement.mdmarkdown8.4 KB
references/rules/verilog-pattern-templates.mdmarkdown1.1 KB
references/rules/verilog-quality-gates.mdmarkdown21.4 KB
references/rules/xilinx-primitive-exemptions.mdmarkdown10.6 KB
references/skill/installation.mdmarkdown6.1 KB
references/skill/script-guide.mdmarkdown7.5 KB
references/skill/skill-standards.mdmarkdown2.1 KB
references/workflows/verilog_dispatcher.mdmarkdown6.4 KB
references/workflows/workflow-contracts.mdmarkdown15.1 KB
scripts/__init__.pyscript53 B
scripts/python/__init__.pyscript55 B
scripts/python/corpus/analyze_verilog_style_corpus.pyscript25.3 KB
scripts/python/existing_rtl/existing_rtl.pyscript81.1 KB
scripts/python/existing_rtl/existing_rtl_improvement.pyscript109.9 KB
scripts/python/existing_rtl/intervention.pyscript8.3 KB
scripts/python/existing_rtl/optimizer.pyscript25.8 KB
scripts/python/existing_rtl/reflection.pyscript86.7 KB
scripts/python/existing_rtl/semantic_contract.pyscript45.6 KB
scripts/python/existing_rtl/verifier.pyscript15.3 KB
scripts/python/existing_rtl/verify_repair.pyscript4.6 KB
scripts/python/existing_rtl/verify_repair_core.pyscript45.7 KB
scripts/python/existing_rtl/verify_repair_patch_apply.pyscript23.5 KB
scripts/python/existing_rtl/verify_repair_patch_categories.pyscript35.5 KB
scripts/python/existing_rtl/verify_repair_patch_plan.pyscript25.1 KB
scripts/python/existing_rtl/verify_repair_patching.pyscript2.4 KB
scripts/python/existing_rtl/verify_repair_support.pyscript25.6 KB
scripts/python/existing_rtl/verify_repair_testbench.pyscript45.9 KB
scripts/python/existing_rtl/verify_reporting.pyscript16.1 KB
scripts/python/facade/__init__.pyscript45 B
scripts/python/facade/existing_rtl_api.pyscript14.0 KB
scripts/python/facade/quality_api.pyscript19.9 KB
scripts/python/facade/representative_cases.pyscript38.3 KB
scripts/python/facade/verilog_api.pyscript6.5 KB
scripts/python/facade/workflow_api.pyscript63.2 KB
scripts/python/generation/tb_generator.pyscript54.9 KB
scripts/python/header_contract.pyscript21.1 KB
scripts/python/installation/__init__.pyscript52 B
scripts/python/installation/bundle.pyscript16.3 KB
scripts/python/installation/catalog.pyscript16.6 KB
scripts/python/installation/cli.pyscript26.4 KB
scripts/python/installation/projection.pyscript14.2 KB
scripts/python/installation/receipt.pyscript13.4 KB
scripts/python/installation/transaction.pyscript29.0 KB
scripts/python/quality/clock_name_roles.pyscript1.0 KB
scripts/python/quality/comment_placement.pyscript49.5 KB
scripts/python/quality/declaration_region_policy.pyscript8.0 KB
scripts/python/quality/deliverable_gate.pyscript51.9 KB
scripts/python/quality/external_interface_stubs.pyscript41.5 KB
scripts/python/quality/formatter_ast.pyscript85.0 KB
scripts/python/quality/formatter_ast_instances.pyscript5.4 KB

references/rules/verilog-comment-placement.md

View on GitHub
# Verilog Comment Placement Contract

Use this reference when generating, reviewing, or validating comments in generated RTL and testbench `.v` files.

The comment gate checks placement and basic usefulness at the code-entity level. Parameters, ports, declarations, assigns, FSM branches, instances, generate blocks, and non-trivial procedural blocks need comments that explain intent, ownership, reset/enable behavior, or interface meaning. Do not add mechanical comments to every syntax-only line merely to satisfy density. Pure comments may introduce a block, but they do not satisfy unrelated entities.

## Strict Placement Rules

- Block comments are forbidden. Any `/*` or `*/` marker fails the gate; use `//` only.
- Signal definitions, including `reg`, `wire`, `integer`, `real`, `input`, `output`, and `inout`, require same-line right-side comments.
- Assign statements and assignments inside `always`, `function`, `task`, `generate`, or `initial` blocks require same-line right-side comments.
- `parameter` and `localparam` definitions require same-line right-side comments.
- Instance `.formal(actual)` parameter and port mappings require same-line right-side comments.
- Same-line `//` markers align to the current region banner right-side `//` display column. If the code is too long, the marker may move right, but it must not be left of that anchor.
- Leading comments for `always`, `function`, `task`, `generate`, `initial`, `case(state_current)` branches (`ST_*:begin` and `default:begin`), definition groups, and instances sit immediately above the target, align with the target start column, and have exactly one blank line above unless they directly follow a region banner.
- The formatter binds pure comments immediately before a `case` item to that item and emits them before the label at the item indentation. A same-line label comment is normalized to the same leading position, while a comment between a label-only item and its first body statement remains the first child of that body. Comments that cannot be bound before `endcase` fail closed instead of being discarded.
- Formatting a `case` statement must converge in one pass: a second formatter pass produces byte-identical output, including the leading comments for `ST_*` and `default` items.
- If a pure comment introduces an `assign` subgroup, it is optional, but once written it must follow the same one-blank-line rule above the comment unless it directly follows a region banner or a stacked pure-comment group.
- Parameter and signal definition sections require a pure group comment above each group. A region banner is only an anchor and does not satisfy the group-comment requirement. Module instances require a pure function comment above the instance.
- When a `parameter_check` region exists, place it as the final internal region before `endmodule`, and keep each parameter-check branch comment adjacent to the concrete constraint it explains.
- Entity comments must be unique to the hardware object they describe. Reusing the same sentence, a numbered variant, or a lightly edited template across parameters, ports, signals, assigns, procedural assignments, or instance mappings fails `VG066` in strict mode.

## Gate Ownership

- `VG063` keeps ownership of leading-comment adjacency, alignment, and blank-line layout for procedural blocks, instances, and `case(state_current)` branches via `comments.case_branch_leading_comment`.
- The formatter AST stores comments bound before a branch label on the corresponding `CaseItem.leading_comments`; renderers must preserve that field before the item label so formatter output cannot create a later `VG063` violation.
- `VG067` owns pure `assign` subgroup spacing via `comments.assign_group_spacing`. The gate does not require every `assign` subgroup to exist; it only constrains the layout when such a pure comment is present.
- `VG150` owns semantic-integrity checks for formatter-bound entity comments. Configured workflow evidence phrases are reported on their entity line, while unrelated tail strings are blocked only after the same entity category forms the configured high-confidence rotation family; banners and ordinary Chinese descriptions remain outside this detector.
- `VG054` keeps ownership of next-state defaults, holds, and branch closure. `VG144` additionally requires a separate procedural combinational next-state process, forbids continuous assignment to `state_next`, and requires blocking `state_next = ...;` assignments in that process.

## Placement Matrix

- File header: keep the fixed bilingual header at the file top when `rtl_style_profile=erie_strict`; describe module purpose, version, revision date, and history there.
- Macro: single-line `define` uses a same-line comment. Multiline backslash macros use one pure leading comment bound to the macro name; continuation lines should not carry inline explanatory comments.
- Module: the `module <name>` declaration is covered by the fixed bilingual header and nearby module-purpose comment. `endmodule` may carry a close phrase when it improves readability, but do not add noise to trivial closures.
- Parameter and localparam: each definition uses a same-line comment explaining configurability or state meaning.
- Port: group protocol/channel ports with pure comments; each port line still uses a same-line comment explaining direction, role, validity condition, or width meaning.
- Signal: each `reg`, `wire`, `integer`, and `genvar` declaration uses a same-line comment explaining driver, purpose, or clock domain.
- Assign: each `assign` line uses a same-line comment explaining the left-hand output and source semantics. If a pure comment introduces an `assign` subgroup, it follows the `VG067` one-blank-line-or-region-banner rule.
- Region banner: banners are navigation only and never replace same-line comments on code statements.
- Always and initial: a pure leading block-purpose comment is required for non-trivial blocks; it should explain combinational/sequential intent, trigger, target register family, or test phase. Parameter-check `initial` blocks should state which constraint family they enforce.
- FSM and case: each FSM block has a fixed block comment; `case` comments name the selector; every `ST_*:begin` and `default:begin` branch under `case(state_current)` has a pure leading comment immediately above it, aligned with the branch label, and explains the transition or output behavior when the branch is not self-evident.
- If and else: branch comments explain reset, enable, exception, or default behavior when that intent is not already clear from the nearby entity comment. Do not comment every `end` line mechanically.
- Instance: add a pure leading instance-purpose comment; instance, parameter mapping, and port mapping lines use same-line comments.
- Generate: branches use `gen_` labels and same-line comments; `endgenerate` names the generated structure being closed.
- Task and function: generated RTL forbids `task` and `function`. Testbenches may use helpers only with a pure leading purpose comment plus same-line comments on declaration, body, local signals, and end lines.
- Testbench statements: stimulus, checks, PASS/FAIL reporting, timeout, waveform setup, and finish calls use same-line comments explaining verification purpose. Human-readable Verilog `$display` messages must start with ` > INFO: [Verilog]`, ` > WARNING: [Verilog]`, or ` > ERR: [Verilog]`; machine-readable transcript tags such as `VERILOG-GEN-RESULT` stay exempt.

## Rejected Comment Forms

- Generic filler such as "line comment", "generic comment", "placeholder", "reset", "state task", or "bypass path".
- Formatter fallback comments such as `parameter`, `port signal`, `signal`, `assign`, `output bridge`, or `internal output signal`.
- Hollow Chinese comments whose meaning is only "Chinese comment", "signal comment", "logic handling", "module logic", "data handling", or "port description".
- Exact or near-duplicate entity comments after removing decorative dashes, numbering, identifier-only noise, and zero-width characters.
- Workflow/evidence slogans attached to an RTL entity, or a fixed-length periodic tail family that is unrelated to that entity's meaning; the detector is configuration-driven and does not reject an isolated Chinese word by itself.
- A pure comment placed between two code lines and reused for both.
- Mechanical line-by-line comments that restate syntax without design meaning.
- A continuation comment on a multiline macro that can hide or break backslash continuation semantics.
planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies.Stars: 108kUpdated Claude CodeCodexVerifiedInstall
meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要".Stars: 108kUpdated Claude CodeCodexVerifiedInstall