readable-verilog-generator

# Readable Verilog Generator

Generate, analyze, improve, and verify readable Verilog-2001 RTL through the bundled runtime under `scripts/python/`. Keep design RTL and verification testbenches in `.v` files, use `scripts/python/facade/verilog_api.py` for host integration, and treat formatter-AST and external-tool evidence as stronger than model self-assessment.

## Route

- `create/write`: confirm the design contract, then use `requirements -> codegen_plan -> spec_document -> python -> rtl`.
- `deep_review`: insert a non-empty structured review between the Python semantic model and RTL; it must cover interface, reset, timing/pipeline, handshake or FSM behavior, width, synthesis, testbench coverage, and risks.
- `review/analyze`: remain read-only and report the eight public gate states before suggesting changes.
- `annotate`: preserve an immutable normalized baseline, change only `//` comments, prove token equivalence from that baseline, and rerun the final deliverable gate.
- `repair/refactor`: bind the task to real RTL, reproduce or validate the issue, and apply the smallest evidence-backed change.
- `agentic_repair`: use the existing-RTL `verify_existing_verilog(...)` loop with an explicit `conservative`, `semi_auto`, or `auto_apply` choice.
- `validate`: collect static or external evidence without implicitly editing RTL.

- Load `references/workflows/verilog_dispatcher.md` before routing. Existing assets, logs, waveform clues, and mixed inputs use its read-only entry decision before any generation, validation, backup, or remote action.

## Install v2.0.0

The package root contains `install.ps1`, `install.sh`, and `install.bat` beside this `SKILL.md`. They share the package-local Python backend and read only the generated installer projection under `assets/installer/` plus the same-level bootstrap descriptor. Platform IDs, root resolution, target templates, status text, exit codes, transaction policy, and verification cases are data-driven by `config/installer/`; do not add platform branches or current test values to code or comments.

Install only from a versioned payload with the configured `RELEASE_RECEIPT.json`. Use `--DryRun`/`--dry-run` to validate without creating transaction resources; use replacement flags only when the target and overwrite intent are explicit. A transaction handles one platform and one target, preserves unlisted target files, writes an install receipt, and attempts rollback on failure. Unknown IDs and source directories without a valid release receipt fail closed. See `references/skill/installation.md` for the complete contract and parameterized invocation templates.

## Generate And Modify

1. Confirm module name, ports, clock/reset, behavior, pipeline expectation, interface family, and verification cases.
2. Use `regular` by default; use `deep_review` only when its extra review stage adds value; use `agentic_repair` only for existing RTL.
3. Generate a Python semantic model before RTL in the staged workflow and use it as the testbench semantic contract.
4. Select local interface and ADC/DAC family templates only when the confirmed design matches them; record every adaptation in the requirements and codegen plan.
5. Keep batch execution generation-only, with one run directory per confirmed spec. Do not use batch mode for existing-RTL mutation or decision resume.
6. Treat streaming as provider interaction only. The finalized response artifact remains the extraction source of truth.
7. Run the strict generated-deliverable gate before downstream use. Optional lint and testbench helpers never replace it.

Every module generated or modified by this skill must ship with a same-name `<module>_spec.md` companion. The canonical JSON contract accepts a single legacy module projection or a `modules` array, but each normalized module must declare a safe `.v` `rtl_path`, complete interface ports, clock/reset semantics, cycle behavior, constraints, corner cases, verification cases, and at least one `timing_diagrams` entry. A timing entry contains `id`, `title`, `scenario`, `description`, and WaveJSON with named signals. `python -m scripts.python.workflow.cli write-spec --spec <spec.json> --out-dir <artifact-root> [--source <rtl.v>] --language <zh|en>` writes `spec/<feature>/<module>_spec.md` plus sibling `spec/<feature>/waveforms/<module>_<scenario>.json5` and `.svg`. The `--source` form fails closed when a module or port is undeclared; the no-source form validates and renders only the confirmed spec and never infers behavior from RTL. All waveform rendering goes through the renderer runtime declared by the settings authority and fails closed when its configured Node/npm prerequisites, package identity, version, or executable are unavailable. A render failure stages diagnostics without overwriting the previous valid bundle.

The default profile is `erie_strict`. Its authoritative naming, bilingual header, region, FSM, comment, port-order, runtime-message, and formatter-AST rules live in `references/rules/verilog-code-comment-naming-standard.md`, `references/rules/erie-style.md`, `references/rules/verilog-comment-placement.md`, and machine-readable assets. Do not duplicate those rule catalogs in this entry document.

## Quality

Strict quality control is mandatory. ASIC quality review, independent static lint, and testbench scaffold are optional workflow steps selected only when the task needs their evidence. Optional helper tools are inside the workflow and never replace the generated-deliverable gate.

Generated deliverables must pass the formatter-backed gate with zero errors and zero strict warnings. The public result matrix is exactly `compile`, `ast`, `readability`, `comment`, `naming`, `profile`, `testbench`, and `toolchain`; static compile evidence does not imply that an external simulator, synthesis, or remote validation ran.

Verilog/SystemVerilog filenames must describe real function. Functional digits are valid; VG148 reject