readable-verilog-generator
VerifiedUse 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.
references/integration/host-integration.md
View on GitHub# Integration Guide
## Table of Contents
- [Facade](#facade)
- [Generation Modes](#generation-modes)
- [Required Inputs](#required-inputs)
- [Run Directories](#run-directories)
- [Host Profile](#host-profile)
- [Boundary](#boundary)
## Facade
Use the Verilog-only facade:
```python
from scripts.python.facade.verilog_api import (
analyze_existing_verilog,
check_verilog_deliverable,
check_verilog_quality,
compare_verilog_semantics,
improve_existing_verilog,
load_default_workflow_config,
load_workflow_result,
route_verilog_request,
run_verilog_batch,
run_verilog_cases,
run_verilog_quality_gate,
verify_existing_verilog,
run_verilog_workflow,
render_verilog_prompt,
validate_verilog_artifacts,
write_verilog_specs,
)
```
Use `run_verilog_workflow(...)` for full staged execution and resume. Use `write_verilog_specs(...)` as the shared spec-first companion writer for generated and modified RTL; it emits one same-name `*_spec.md` plus WaveJSON/SVG evidence per module and can cross-check explicit sources. Use `run_verilog_batch(...)` when the caller has multiple generation specs and wants one aggregate summary while keeping each case in its own run directory. Use `render_verilog_prompt(...)` when the host already owns the model call. Use `validate_verilog_artifacts(...)` to gate generated `.v` files before downstream use. Use `analyze_existing_verilog(...)` to build `rtl_analysis.json`, `project_analysis.json`, and `design_explanation.md` from an existing design, `improve_existing_verilog(...)` to create `rtl_transform_plan.json` plus controlled helper artifacts, `compare_verilog_semantics(...)` to emit `equivalence.json`, `qor_report.json`, and `transform_validation.json`, and `verify_existing_verilog(...)` to run the log-driven verify-repair flow with stable run artifacts plus a diagnostics pack.
Use `route_verilog_request(...)` before selecting a workflow when the host has mixed inputs. It is read-only and returns `route_decision` with `recommended_flow`, `entry_mode`, `required_inputs`, `missing_inputs`, `next_action`, `safe_recovery_hint`, `blocking_findings`, and `provenance_policy`. It must not generate RTL, run validation, mutate source files, create backups, or start remote actions.
Use `check_verilog_quality(...)` for the stable dict-returning quality facade and `check_verilog_deliverable(...)` for the stricter final-delivery facade. `run_verilog_quality_gate(...)` is the lower-level entry that returns a `QualityGateReport`; hosts that need a JSON-compatible contract should prefer `check_verilog_quality(...)`. Use `run_verilog_cases(...)` only when representative-case artifacts are intentionally requested because it writes governed case outputs. `load_default_workflow_config()` reads the bundled defaults without starting a run, while `load_workflow_result(...)` reads an existing run directory's `workflow_result.json` without mutating that run.
## Generation Modes
`run_verilog_workflow(...)` accepts `generation_mode`:
- `regular`: the existing staged generation path
- `deep_review`: inserts a structured `review` stage between the Python semantic model and RTL generation
`verify_existing_verilog(...)` remains the stable repair entrypoint and should be presented by hosts as the `agentic_repair` mode for existing RTL. Do not replace its evidence gates with free-form model self-assessment strings such as `[DESIGN IS CORRECT]`.
The same generation facade also accepts `stream=True` when the selected provider supports streaming. Streaming improves interaction only; validation, extraction, semantic gates, and diagnostics still operate on the finalized response artifact.
## Required Inputs
Specs keep `target="rtl"` for compatibility. Calls may omit `target`; the facade resolves it to `rtl`. Any other target is rejected before prompt generation or workflow execution.
Existing RTL analysis/improvement flows do not require a generation spec. They operate on existing `.v` files, optionally accept a Markdown/text behavioral note source, and always write stable JSON evidence in the caller-selected output directory.
The route decision uses four Erie entry modes:
- `spec-first generation`: start from a spec and build the requirements plus codegen plan before generation.
- `plan-seeded generation`: use an existing ready codegen plan as a seed only; do not bypass requirements confirmation or validation.
- `existing-RTL assist/repair`: analyze, refine, compare, or verify existing Verilog sources with explicit automation boundaries.
- `evidence-first debug/repair`: classify logs, validation reports, waveform clues, or remote-readiness requests before selecting repair or rerun.
`run_verilog_batch(...)` is generation-only in v1. It intentionally does not cover existing-RTL mutation or decision-resume flows.
`verify_existing_verilog(...)` requires an explicit `automation_mode`. The host must ask or otherwise surface that choice; the runtime must not silently default the mode. Supported modes are:
- `conservative`: report findings only
- `semi_auto`: generate candidate artifacts but require confirmation before source overwrite
- `auto_apply`: caller explicitly allows automatic source mutation when the workflow has safe evidence
When `tb_mode="augment"`, the host may pass `testbench_source` explicitly. If omitted, the runtime may fall back to auto-detecting a TB from the provided source list, but explicit `testbench_source` always wins.
When resuming an RTL repair confirmation, the host may pass `decision_source` so the same `verify_existing_verilog(...)` entrypoint applies the approved patch and immediately runs post-apply verification.
`improve_existing_verilog(..., improve_goal="merge_assist")` is also assist-only. It emits `merge_plan.json`, `merge_wrapper.v`, `merge_validation.json`, and `merge_equivalence.json` so a host can guide wrapper-first repartition or recompose work without automatically mutating the source RTL.
`improve_existing_verilog(..., improve_goal="optimize_assist")` follows the assist-only behavior and candidate-compare boundary defined in `references/workflows/workflow-contracts.md`; the host must not reinterpret that flow as implicit rewrite or acceptance.
`verify_existing_verilog(...)` keeps RTL generation scope unchanged: source RTL and verification testbenches remain Verilog-2001 `.v` artifacts. In augment mode, the runtime preserves the original TB body, emits an augment plan and diff artifact, and records original/backup/active TB paths in `tb_contract.json`. In RTL repair mode, the runtime emits `rtl_patch_plan.json`, `rtl_patch_diff.txt`, `rtl_intervention.json`, and post-apply verification artifacts while keeping backup/active RTL paths inside `patch_candidate.json` and `verification_result.json`. Every run 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 hosts can consume structured closure state instead of scraping logs. The patch planner now classifies deterministic repair candidates such as `reset_initialization_completion`, `case_default_completion`, `state_hold_clear_completion`, and `output_register_completion`; only reset-initialization completion remains eligible for immediate `auto_apply`, while the newer categories intentionally downgrade to confirmation-driven resume.
Before generation, provide a confirmed requirement contract:
- `design_requirements.target = "rtl"`
- `design_requirements.pipeline_required`
- `design_requirements.streamability`
- `design_requirements.interface_family`
- `design_requirements.interface_profile`
- `design_requirements.confirmed_by_user = true`
- `design_requirements.confirmation_notes`
When the task is streamable, explicitly choose `native`, `axi_stream`, `axi4`, `axi4_lite`, `ahb`, `apb`, or `custom`. Do not let the runtime infer a bus protocol from vague wording when the user has already expressed a bus preference.
`interface_profile.template_id` is optional. If omitted, the runtime selects a local template from `assets/interface_templates/catalog.json` for standard bus families and records it as `selected_interface_template_id` in the requirements payload and codegen plan. Supported template IDs are `axi_stream_duplex`, `axi4_lite_config`, `axi4_full_master`, `axi4_full_slave`, `ahb_lite_config`, and `apb_config`. Treat these snippets as strict-preferred port contracts, not standalone synthesizable modules.
`workflow.use_case_template_id` is optional. When provided, it must be one of `spi_adc`, `spi_dac`, `jesd_adc`, `jesd_dac`, or `mxfe_mixed`. The runtime resolves the matching bundle from `assets/use_case_templates/`, records it as `selected_use_case_template_id` plus `use_case_template` in the requirements payload and codegen plan, and injects the selected Verilog or Tcl or XDC guidance into prompts as board-level context.
When `rtl_style_profile=erie_strict`, the runtime also layers in curated Erie style constraints from `references/rules/erie-style.md` and `assets/style_templates/`. Hosts should expect stronger prompt guidance around bilingual headers, FSM naming, instance naming, generate labels, and grouped standard-bus port declarations.
## Run Directories
When dict inputs are passed to the workflow runner, the facade materializes the stable `_adapter_inputs/` contract defined in `references/workflows/workflow-contracts.md`. The host can inspect those files even when the workflow later blocks for a human decision.
When `stream=True`, each model-generated stage also writes a streaming transcript file under the stage directory. Hosts should treat the transcript as interaction evidence and the final response file as the extraction source of truth.
## Host Profile
In GUI-hosted Code Design sessions, the GUI owns artifact writing, formatter/parser checks, server staging, server-side Vivado admission, and final project insertion. The model turn should return host artifacts rather than running the standalone workflow unless the host explicitly asks for facade operations.
Local external tools are optional diagnostics unless the host explicitly requests compile,
execute, or implement readiness. If requested tools are missing, report the missing tools and
block the standalone readiness gate instead of claiming external validation succeeded.
## Boundary
Keep host-specific behavior in `scripts/python/facade/`. Do not add new Python workflow implementations outside `scripts/python/`. Avoid patching unrelated `scripts/python/<function>/` modules unless intentionally changing the shared internal Verilog workflow backend.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 119k | Updated | Claude CodeCodex | Verified | Install |
| 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: 118k | Updated | Claude CodeCodex | Verified | Install |
| 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: 108k | Updated | Claude CodeCodex | Verified | Install |
| 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: 108k | Updated | Claude CodeCodex | Verified | Install |