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/workflows/workflow-contracts.md

View on GitHub
# Workflow Contracts

## Table of Contents

- [Run Directory](#run-directory)
- [Entry Routing](#entry-routing)
- [Script Entry Points](#script-entry-points)
- [Model Providers](#model-providers)
- [Fixed Generation Pipeline](#fixed-generation-pipeline)
- [Delivery Gate Matrix](#delivery-gate-matrix)
- [Existing RTL Assist Flows](#existing-rtl-assist-flows)
- [Terminal Statuses](#terminal-statuses)
- [Resume Behavior](#resume-behavior)
- [Optional Tools](#optional-tools)
- [Language Governance](#language-governance)
- [Trace Semantics](#trace-semantics)

## Run Directory

Every `run_verilog_workflow(...)` execution writes a self-contained run directory with:

- `plan.json`
- `workflow_config.json`
- `workflow_result.json`
- `workflow-state.json`
- `trace.jsonl`

The adapter also materializes preflight inputs under `_adapter_inputs/`:

- `spec.json`
- `spec/<feature>/<module>_spec.md` plus sibling `spec/<feature>/waveforms/<module>_<scenario>.json5` and `.svg`
- `requirements.json`
- `codegen_plan.json`
- optional `evidence.json`
- optional `decision.json`

Each attempt lives under `attempt-001/`, `attempt-002/`, and so on. Stage outputs are separated by stage, for example `python/generated/...`, `rtl/generated/...`, `validation.json`, `repair_plan.json`, and `intervention.json`.

## Entry Routing

`route_verilog_entry(...)` is a read-only classifier. It may inspect caller-provided specs, codegen plans, RTL paths, testbench paths, logs, validation summaries, waveform clues, or an artifact directory, but it must not write source artifacts, start model calls, run validation, create backups, or trigger remote commands.

The stable route decision fields are:

- `recommended_flow`
- `entry_mode`
- `required_inputs`
- `missing_inputs`
- `next_action`
- `safe_recovery_hint`
- `blocking_findings`
- `provenance_policy`

Entry modes are limited to:

- `spec-first generation`
- `plan-seeded generation`
- `existing-RTL assist/repair`
- `evidence-first debug/repair`

`plan-seeded generation` only means an existing codegen plan can seed the workflow. It does not bypass requirement confirmation, Verilog-2001 target checks, Python semantic generation, extraction, validation, or downstream quality gates.

Route summaries may be copied into `workflow_config.json` and `workflow_result.json` as evidence. They are advisory and must not change `WORKFLOW_STATUSES`.

## Script Entry Points

Script implementations live under `scripts/python/<function>/`. The supported function buckets are `validation`, `quality`, `generation`, `remote`, `toolchain`, and `corpus`.

The old top-level script wrappers remain v0.3.x compatibility wrappers. They must forward to the canonical implementation while preserving CLI arguments, stdout/stderr behavior, and exit codes. New workflow documentation and tests should prefer the canonical paths.

Canonical examples:

- `scripts/python/validation/validate_verilog_skill.py`
- `scripts/python/remote/remote_validate_verilog_skill.py`
- `python -m scripts.python.quality.verilog_lint`
- `python -m scripts.python.generation.tb_generator`
- `python -m scripts.python.validation.validate_verilog_skill`
- `python -m scripts.python.remote.remote_validate_verilog_skill`

Runtime modules may call `runtime` and `scripts/python/*` helpers as needed, but runtime modules must not import the legacy host integration facade. The public Python facade lives at `scripts/python/facade/verilog_api.py`.

## Model Providers

`run-workflow` and `run-batch` accept `--model-provider mock|manual|command`; the default is `manual`. `mock` is deterministic test support. `manual` reads the response file already staged for the current generation step and does not call a model. `command` is the real non-interactive provider and requires `--model-command`; omitting that command fails closed with a non-zero exit instead of falling back to `mock` or `manual`.

Use `--model-timeout` to bound command-provider execution. `--stream` and `--no-stream` select streamed or buffered consumption when the provider supports it. Provider selection never relaxes requirement confirmation, extraction, validation, retry, or delivery gates.

## Fixed Generation Pipeline

The staged generation workflow uses:

1. `requirements`
2. `codegen_plan`
3. `python`
4. `rtl`

The workflow does not enter prompt-driven code generation until the confirmed requirement contract is complete. If planning finds unresolved requirements, it stops with `blocked_human`.

`deep_review` inserts a `review` stage between `python` and `rtl`. The stage must write a non-empty `*plan_review.md` artifact that covers interface, reset, timing/pipeline, handshake or FSM behavior, width, synthesis, testbench coverage, and risk. Empty JSON, placeholder text, or missing coverage keeps the attempt failed.

## Delivery Gate Matrix

`run_verilog_deliverable_gate(...)` returns the public delivery contract. The stable top-level fields are:

- `version=3`
- `delivery_ready`
- `repair_required`
- `rerun_required_after_repair`
- `delivery_issues_by_rule`
- `checks`
- `findings`

`findings` is the Agent-facing actionable projection. Every applicable active VG rule that is not `passed` must contribute one or more entries with `rule_id`, `status`, `severity`, a structured `location` and `evidence`, a concrete `problem`, and `guidance`. `guidance` contains the direct change instruction, ordered steps, risk, human-review obligation, and a non-empty `examples` list whose objects expose `kind`, `bad`, `good`, and `note`. Exact locations use `scope=file` with confirmed one-based `line_start`/`line_end`; unknown or aggregate locations keep `scope=file`, `scope=cross_file`, or `scope=run`, set line fields to `null`, and carry a boundary `note`.

The `checks` object must contain exactly these eight public gates:

- `compile`: local static syntax, parser, and basic lint evidence. It does not mean xsim, VCS, iverilog, or any external simulator compile ran.
- `ast`: formatter AST coverage, parse-error evidence, and formatter-template consistency. Any non-empty `formatter_violations` count fails this gate and contributes to top-level `errors`.
- `readability`: Verilog readable quality gate evidence.
- `comment`: semantic comment placement and comment coverage evidence.
- `naming`: naming and prefix-related rule evidence.
- `profile`: style profile, rulebook, wrapper profile, and project profile evidence.
- `testbench`: testbench static/readability evidence when explicitly included; otherwise `not_requested`.
- `toolchain`: optional simulator, synthesis, or remote validation evidence. Local deliverable gate reports this as `not_requested` unless validation readiness supplied external evidence.

In strict mode, any blocker or warning in a delivery-relevant gate means:

- `delivery_ready=false`
- `repair_required=true`
- `rerun_required_after_repair=true`
- a non-zero CLI exit code

Repair is complete only when the Verilog is readable and syntax/AST checks pass. For workflow execution, the attempt may be marked `passed` only when validation is OK, stage gates are ready, and all eight delivery matrix entries are ready. A `toolchain_issue` remains an external environment blocker; it must not consume local repair attempts, but the workflow also must not claim simulation, synthesis, or remote validation passed.

## Existing RTL Assist Flows

Existing-RTL helper flows do not use the staged generation pipeline. They are separate stable subflows exposed through the facade and CLI:

- `analyze_existing_verilog(...)` writes `rtl_analysis.json` and `project_analysis.json`
- `analyze_existing_verilog(...)` also writes `design_explanation.md`
- `improve_existing_verilog(..., improve_goal="tb_scaffold"|"style_improve"|"partition_assist"|"merge_assist"|"optimize_assist")` writes `rtl_transform_plan.json`, `transform_validation.json`, and goal-specific helper artifacts
- `compare_verilog_semantics(...)` writes `equivalence.json`, `qor_report.json`, and `transform_validation.json`
- `verify_existing_verilog(...)` writes `verification_plan.json`, `tb_contract.json`, `log_diagnosis.json`, `patch_candidate.json`, `verification_result.json`, and `loop_state.json`
  The same run also writes `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`.

`optimize_assist` is assist-only by default. Without a candidate RTL, it produces optimization plans, wrapper/probe artifacts, partition maps, and advisory QoR summaries. With a candidate RTL, it additionally emits semantic-compare evidence. It does not implicitly rewrite or accept RTL.

`merge_assist` is assist-only by default. It produces a merge plan, wrapper skeleton, validation summary, and equivalence-review contract so repartition or recompose work remains explicit and reviewable.

`verify_existing_verilog(...)` is a verification loop entrypoint rather than a fresh RTL generator. It stages source RTL into a project-local verification workspace, emits a log-driven scaffold testbench or augments an existing one, normalizes diagnosis results, and records the selected automation boundary. The caller must provide the automation mode explicitly. Existing source RTL uses diagnostic comment gates: comment-density and placement failures are warnings so compile, semantic, interface, and high-confidence lint errors stay visible.

Existing RTL, target, and context modes require real caller-provided assets. Missing source RTL, missing target RTL, or missing contextual evidence must fail with `TARGET_OR_CODE_REQUIRED` or the nearest equivalent rule. The skill must not invent placeholder RTL, replacement assets, or directly replaceable template code for comment/report-only requests. Comment and report flows may locate issues and describe findings, but generated code patches require explicit modify/repair intent and real target files.

Existing-RTL verify-repair reports may add `diagnosis_route` to `run_summary.json` and `terminal_status.json`. The allowed values are `local_rtl_issue`, `spec_ambiguity`, `dut_tb_contract_drift`, `toolchain_issue`, `needs_external_validation`, and `unknown_or_mixed`. This field is an advisory routing summary and must not change terminal success semantics.

Existing RTL CLI commands use strict exit semantics. If a generated report contains a blocker, warning, failed status, or a linked terminal summary with `toolchain_issue`, `needs_external_validation`, `blocked`, `failed`, or equivalent failure routing, the command returns non-zero. A report being written successfully is not the same as command success.

For `tb_mode="augment"`, the run directory also writes:

- `tb_augment_plan.json`
- `tb_augment_diff.txt`

`tb_contract.json` records `original_testbench_path`, `backup_testbench_path`, `active_testbench_path`, `language_before`, `language_after`, and `augmentation_actions`.

When an RTL patch candidate is available, the same run directory also writes:

- `rtl_patch_plan.json`
- `rtl_patch_diff.txt`
- `rtl_intervention.json` when confirmation is required
- `post_apply_validation.json` after an approved or automatic apply
- `post_apply_equivalence.json` after an approved or automatic apply

`patch_candidate.json` records candidate/backup/active RTL paths, compare evidence, equivalence readiness, apply blockers, patch category, line hints, and root-cause evidence. `rtl_patch_plan.json` records the selected patch category plus `risk_level`, `target_line_hints`, `root_cause_evidence`, and `apply_gate` details so the caller can distinguish true `auto_apply` cases from categories that must be resumed through `decision.json`. `decision.json` may be supplied on a later `verify-existing` run to resume a confirmation-gated RTL apply.

## Terminal Statuses

`workflow_result.json` only uses:

- `passed`
- `failed`
- `blocked_human`
- `blocked_toolchain`
- `max_attempts`
- `invalid_response`

Unsupported targets are rejected as input errors before the workflow starts.

## Resume Behavior

When the workflow stops at `blocked_human`, it writes `intervention.json`. A host can later supply `decision.json` and resume through the facade or CLI. Resume appends a new attempt and preserves trace history.

## Optional Tools

The workflow may call these environment-provided tools when readiness requires them:

- Vivado xsim backend: `xvlog`, `xelab`, `xsim`
- VCS+Verdi backend: `vcs`, `verdi`
- iverilog backend: `iverilog`, `vvp`
- Implementation readiness: `yosys`

VCS+Verdi coverage in this skill means scripted backend selection, availability checks, compile, and simulation execution. It does not imply complete Verdi GUI/session automation, waveform-debug orchestration, or arbitrary Verdi feature coverage.

Simulation backend selection uses the configured fallback order: xsim, then VCS+Verdi, then
iverilog/vvp. Missing higher-priority simulators are recorded in validation metrics and warnings,
but they do not block if a lower-priority backend actually runs. If no simulator backend is
available, validation reports a `toolchain_issue` error and workflow execution stops at
`blocked_toolchain`. Do not claim compile, execute, or implementation validation unless the
reported tool actually ran. Use `--no-external` only for static readiness; if a caller asks for
compile, execute, or implement readiness with external execution disabled, validation reports a
`toolchain_issue` error and separates `static_passed`, `compile_not_run`, `sim_not_run`, and
remote-required status in metrics.

That fallback order is a general compatibility capability, not this repository's release acceptance
matrix. The release gate uses the server and simulator selected by the settings authority; VCS+Verdi remains an optional
compatible backend and is not a required release condition.

Verification testbenches remain Verilog-2001 `.v` artifacts. Source RTL and generated
verification files use the same Verilog-only boundary.

## Language Governance

Any implementation change that creates, edits, reviews, refactors, or repairs Python must first use `readable-python-generator`. The agent must classify the task as generate/modify/explain/review/repair, state the functional intent contract, follow the current-project Chinese style, and pass the readable-python strict gates before claiming VerilogGenerator readiness.

Any implementation change that creates, edits, reviews, refactors, or repairs bat/cmd, shell/bash, PowerShell, or Tcl must first use `readable-script-generator`. The agent must identify the script language, classify the task, state the script intent contract, and pass the readable-script strict gates before claiming VerilogGenerator readiness. Comment-only script changes must prove executable source order and AST/CST equivalence when the language tooling supports it.

Mixed Python and script-family changes must run both governance paths. Installed skill contents under Codex home remain read-only unless the user explicitly requests installation or replacement.

## Trace Semantics

`trace.jsonl` is append-only and records prompt rendering, model generation, extraction, validation, interface/reference audits, verifier gates, reflection, and human intervention markers.
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