Skip to content

About

an extension for rtl coding style

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

rtl_veteran

Your RTL, minus the chaos.

A coding agent skill that turns a messy Verilog module into a clean, column-aligned, review-ready one — without touching a single gate of logic.

Drop it into your agent once. From then on you just say "tidy this module".


🧠 Introduction

rtl_veteran is not a formatter. It's a house style with teeth.

At its core is SKILL.md — a 1000-line spec for how a Verilog module should be laid out: declarations up top, logic below, columns aligned to a fixed ruler, one signal per line, no ?: hiding inside a clocked always. Alongside it sit six zero-dependency Python scripts that do the parts a human is bad at: aligning columns, scoring style, and catching the structural bugs that survive lint.

The whole thing is agent-native. You don't run it — your agent does. You describe the outcome, and the agent reads the spec, runs the scripts, verifies, and hands you back a report.

The one promise it makes and keeps: zero logic change. What the synth tool saw before, it sees after. Only three transforms are permitted, and all three are provably netlist-preserving.


🔥 Why You Need rtl_veteran

  • Code review shouldn't be about whitespace. Right now it is. Half the comments on your last PR were "align this" / "move this decl up" / "one signal per line". Automate those; spend the review on the datapath.
  • wire x = expr; is a trap. It looks tidy. It scatters your logic across the declaration block, and it's the single biggest reason a module becomes unreadable at 800 lines. This skill splits every one of them.
  • The bug lint can't see. You move a declaration to the top, forget its assign, and now a wire is declared, connected to an instance port, and driven by nothing. Lint passes. The instance reads z. This skill runs a reverse driver-completeness check because it has bitten us for real.
  • Three-alarm structural smells, caught mechanically: two independent ifs writing the same register, a ternary on a nonblocking RHS, and registers in one always that don't share a write condition. All fixable, all semantic-preserving.
  • A number, not an argument. "Your code is 4.2 / 10" ends the style debate faster than a thirty-message thread.
  • It writes you a report. Every refactor ends with a single self-contained HTML page showing before/after, the rule each change satisfies, and the verification results.

✨ Feature

Two-zone layout Declarations in Zone 1 (localparam → signals, each under a banner + ASCII ruler), logic in Zone 2 under a // Func Begin directory. Never mixed.
Column alignment Ports, localparam, signal declarations, assign runs, case and always bodies — all aligned to a fixed ruler. Idempotent: run it twice, byte-identical result.
Structural lint Catches same-layer multi-if register writes, ?: on a clocked nonblocking RHS, and mismatched write conditions across registers in one always. Real tokenizers, not grep.
Comment tiers BIG banner vs SMALL note, enforced. Kills //====== ornament lines, half banners, and banner explosions before they flatten your comment hierarchy.
Quality score 8 weighted items, 10 points total, half-life decay curve. Scores the original code — a low score is exactly why you needed the refactor.
HTML report One self-contained page: score panel, per-change cards with real before/after code, verification table, split-view diff.
No dependencies Pure Python 3.6+, no pip install, no network. Runs on EDA hosts from 2015.

⚡ Fast Begin

1️⃣ Install — pick your agent

The skill is a folder containing SKILL.md plus scripts. Point your agent at it:

git clone https://github.com/shawnnjupt/rtl_veteran_extension.git
Agent Where it goes
hermes ~/.hermes/skills/software-development/rtl_veteran/
Claude Code ~/.claude/skills/rtl_veteran/
Codex CLI ~/.codex/skills/rtl_veteran/
opencode ~/.config/opencode/skills/rtl_veteran/

One command does most of them:

cp -r rtl_veteran_extension ~/.claude/skills/rtl_veteran

💡 opencode reads ~/.claude/skills/ too, so installing for Claude Code covers both. Want it per-project instead of global? Use .claude/skills/ / .codex/skills/ / .opencode/skills/ at your repo root and commit it — the whole team gets the same style.

2️⃣ Use it — just talk

No commands to memorize. Open the file and ask:

tidy this module
separate declarations from assignments in bpq4x_dda_add_check.v
score this file and tell me what's dragging it down

The agent reads the spec, does the work, runs the checks, and produces the report.

3️⃣ Or drive the scripts directly

SKILL=~/.claude/skills/rtl_veteran

python3 $SKILL/verilog_assign_align.py    path/to/module.v   # align columns in place
python3 $SKILL/verilog_quality_score.py   path/to/module.v   # 8-item score / 10
python3 $SKILL/verilog_w415a_check.py     path/to/module.v   # multi-if register writes
python3 $SKILL/verilog_proc007_check.py   path/to/module.v   # ?: on a clocked RHS
python3 $SKILL/verilog_comment_check.py   path/to/module.v   # comment tier violations

All checkers exit 1 when they find something, so they drop straight into CI.


Reads your code. Doesn't rewrite your logic. That's the whole deal. 🤝

About

an extension for rtl coding style

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages