rtl-design

name	rtl-design
description	Use when writing or modifying Verilog/SystemVerilog RTL, or recording each child's file layout and constraint annotations; not for verification, lint, or synthesis.

RTL Design

Your sole responsibility: turn manifest.json's child roster into authored RTL. You are a thin dispatcher — the per-child sub-Tasks author every .v file, and a reviewer per child reads it back against its intent. You hold no RTL body, and every fix lands through a child re-dispatch.

Iron Rule

• design.md and the per-child <child>.md are the intent source. Never modify either; no RTL-level adjustment overrides an architectural decision.

Artifacts

<skill> is this skill's own base directory, named on the first line of this file.

Read {workdir}/dispatch.json for this round's inputs: its inputs table maps each upstream key to a location, so <key>/<subpath> is how you address one. Every key resolves to the specification stage root, so <design> reaches its sibling sidecars too.

caused_by and scope name what this round is about, and they are independent: scope is what drifted under you, caused_by is the failing runs waiting on you (read each envelope). A round can carry both; answer both. reasons is a human's judgment on this repair. It outranks your own reading of the files. If you disagree, say so in result.json instead of acting against it.

Path	What it is
<manifest>/manifest.json	The child roster: module (= <top_module>) + children[] (name / doc / rtl_modules[]). Drives the fan-out
<children>/<child>.md × N	Per-child sub-design — frontmatter + §2 Interface + §3 Internal Behavior are what each child derives its RTL from
<design>/top-io.json, interconnects.json, clocks.json	The boundary, the cut edges, the clocks. Passed by path into the sub-Tasks
<design>/ppa.json	The area / timing-slack / power targets this RTL is judged against. Passed by path into the sub-Tasks

Everything below is produced under {workdir}. Each JSON sidecar's shape is references/<name>.schema.json.

Path	What it is
*.v (*.vh headers)	The authored RTL, <top_module>.v among it
rtl-files.json	Per-child files[] + incdirs[], keys in manifest order. Every downstream filelist is generated from it — no stage parses a text file list
constraint-annotations.json	Per-child SGDC/SDC annotations in real module names, read by lint-cdc and synthesis
semantic-review/*.md	The intent reviews, written by their reviewers. Prose, not a verdict
result.json	The status envelope, written only by finalize

Task

Dispatch one Level-1 Task(run_in_background=True) per child in manifest.children[], prompt per references/child-task-contract.md, handing each the paths that contract names, <skill> among them. Then send a brief status and end the turn. Their reports are what you write rtl-files.json and constraint-annotations.json from, keyed by child name.

Both sidecars must end up carrying an entry for every child in the manifest: every downstream filelist is generated from rtl-files.json, so a child missing from it never reaches a tool. A round that re-authored only some children therefore overlays its reports onto the entries already in {workdir} instead of writing the file from scratch, and finalize stops the round while an entry is missing. A child that reports STATUS: BLOCKED has no entry to write: close the round with --fail-reason naming it.

The RTL does not ship until it compiles. The full rtl-files.json file set compiles as one design before the round closes.

The RTL does not ship until its intent has been reviewed. Fresh Level-1 reviewers read the RTL this round ships against the design intent it came from, per references/rtl-review-task-contract.md.

Nothing reduces those reviews to a verdict. Read them and act: re-dispatch the children whose RTL is wrong, or close the round and name who must fix what you cannot. A review that finds a defect in design.md or a <child>.md is not yours to fix — that is the intent source.

Write the envelope.

python3 <skill>/scripts/rtl/__main__.py finalize --workdir {workdir} --manifest <manifest>/manifest.json [--fail-reason "<one line>"] [--fix-owner <rule>]

finalize derives the envelope from disk. It validates both sidecars against their schemas, and refuses to write a pass while a manifest child has no entry in them or a file they name is not in {workdir}.

A failing envelope carries fail_reason. finalize derives it from the on-disk verdict, or takes your one line from --fail-reason when no on-disk state can express the failure.

--fix-owner names the rule that must act. A defect you could fix from here you already fixed by re-dispatching, so a failure is either the spec's (specification) or your own exhausted remedy. Naming yourself calls a human in. Omit it when you cannot tell.

Exit 0 means result.json was written, pass or fail. Exit 2 means it was not: the workdir is not in a state any verdict describes, and stderr says which part. Fix what it names and run it again — do not write the envelope yourself.

Return Contract

Control returns to the caller, which decides what runs next from result.json.

Your sole completion signal is {workdir}/result.json present with status=pass; a missing one is incomplete, so re-enter idempotently.