| name | rat-init-project |
| description | Initialize RTL project workspace: directory structure, coding rules, phase guides. Run once per project. Triggers: 'init project', 'new project'. |
| user-invocable | true |
Initialize a new RTL design project with the standard directory structure, coding convention
rules, phase guides, and template files required by the 6-Phase pipeline.
This is a per-project operation — run once per new project workspace.
For EDA tool installation and environment verification, use `/rtl-agent-team:rat-setup` instead.
<Use_When>
- Starting a new RTL/FPGA/ASIC design project
- First time using this plugin in a new workspace
- User says "init project", "initialize project", "new project", "project init"
- Agent Step 0 detects missing project structure (.claude/rules/ not found)
</Use_When>
<Do_Not_Use_When>
- Project directories already exist and rules are deployed (check
.claude/rules/rtl-coding-conventions.md)
- Only need to verify/install EDA tools (use
/rtl-agent-team:rat-setup)
- Designing architecture or writing RTL (use p2-arch-design or rtl-p4-implement)
</Do_Not_Use_When>
<Why_This_Exists>
The 6-Phase pipeline expects a standard directory layout (rtl/, refc/, bfm/, sim/, lint/, syn/, etc.)
and coding convention rules deployed to .claude/rules/. Without proper project initialization,
agents fail with missing directory errors and coding conventions are not enforced.
This skill ensures the project workspace is ready before design work begins.
</Why_This_Exists>
<Execution_Policy>
- Do not overwrite existing project templates, guides, rules, or directories
- Managed exceptions: update only the RAT block in project
CLAUDE.md, refresh
rat_config.json tool detection, and regenerate config.mk
- Preserve usable user tool path overrides; refresh stale or unusable paths from
the detected environment
- Generate a project initialization report at the end
- Quick EDA tool status check (informational only — does NOT install tools)
- If required tools are missing, recommend running
/rtl-agent-team:rat-setup for installation
</Execution_Policy>
1. **Check plugin setup** (advisory, not a hard gate):
Check `${CLAUDE_PLUGIN_DATA:-$HOME/.config/rtl-agent-team}/.setup-complete` for `/rtl-agent-team:rat-setup` completion.
If marker is missing, advise: "Run `/rtl-agent-team:rat-setup` first to verify EDA tools and configure the plugin environment."
Proceed anyway — project structure can be created without tools, but warn about missing EDA environment.
1a. Check project root: Verify current directory is suitable (has .git or is empty).
- Create directory structure (skip existing):
specs/ # Input specifications and datasheets
refc/ # C reference model (DPI-C compatible)
include/ # Common ref model headers
build/ # Build output (.so for DPI-C)
bfm/ # Bus Functional Models
include/ # Common BFM headers
rtl/ # Synthesizable SystemVerilog source
common/ # Shared utility modules (ICG, synchronizer, CDC primitives)
include/ # Common defines, packages
top/ # Top-level module instantiation
sim/ # Simulation & testbenches
top/ # Tier 4: integration tests
formal/ # SVA formal verification (.sby configs)
lint/ # Lint flow
scripts/ # Lint scripts (run_lint.sh)
reports/ # Per-module lint results
syn/ # Synthesis flow
scripts/ # Synthesis scripts (run_syn.sh)
reports/ # Per-module synthesis results
docs/ # Design documentation
phase-1-research/ # Phase 1 artifacts
phase-2-architecture/ # Phase 2 artifacts
phase-3-uarch/ # Phase 3 artifacts
phase-4-rtl/ # Phase 4 artifacts
phase-5-verify/ # Phase 5 artifacts
decisions/ # Architecture Decision Records (ADR)
reviews/ # Phase gate review reports (Markdown)
phase-1-research/
phase-2-architecture/
phase-3-uarch/
phase-4-rtl/
phase-5-verify/
phase-6-review/ # Phase 6 review deliverables
.rat/
state/ # Plugin state files (auto-managed)
Note: Per-module subdirectories under refc/, bfm/, rtl/, sim/ are created
during Phase 2 (architecture) when module decomposition is decided.
2a. Inject project CLAUDE.md (RAT-managed section):
Run the injection script to create or update the RAT-managed section in the project root CLAUDE.md.
User content outside <!-- RAT:START --> / <!-- RAT:END --> tags is never modified.
bash "${CLAUDE_PLUGIN_ROOT}/skills/rat-init-project/scripts/inject_claude_md.sh" .
Idempotent — safe to re-run on every rat-init-project invocation.
2b. Generate project config (rat_config.json):
Run the config generator to detect available EDA tools and create the project configuration file.
If rat_config.json already exists, tool availability and paths are refreshed while
user-owned configuration is preserved. A usable explicit path override remains unchanged;
a stale or unusable path is replaced when the tool is found in the current environment.
bash "${CLAUDE_PLUGIN_ROOT}/skills/rat-init-project/scripts/generate_config.sh" . "$(basename "$(pwd)")"
The config file stores:
tools: 24 EDA tools across 8 categories (simulators, synthesis, lint, formal, equivalence, cdc, debug, coverage). Each tool has detected, path, and env_source fields. Set env_source per-tool for tools needing setup (e.g., "env_source": "source /tools/synopsys/vcs/setup.sh"). Each env_source is trusted project input and is evaluated by Bash on every generator run; do not populate it from untrusted data.preferences: preferred tool per category (auto-set to first detected commercial tool, user-overridable)technology: target library path, SRAM lib, NAND2 cell pattern (auto-extracted from liberty if set)coverage: targets (line≥90%, toggle≥80%, FSM≥70%, branch≥80%, functional≥95%), seeds, fail ratewaivers: custom paths for lint/CDC waiver files
Users should edit per-tool env_source, technology.liberty, and waivers after generation.
config.mk is plugin-managed output and is regenerated from the refreshed configuration.
2c. Deploy rules (skip if already deployed globally via /rtl-agent-team:rat-setup):
For each rule file, check ~/.claude/rules/ first. If the same file exists globally,
skip the local copy to avoid duplicate injection. Only deploy locally if neither exists.
Diagram rules are injected into ~/.claude/CLAUDE.md by /rtl-agent-team:rat-setup via <markdown_diagram_rule> tag.
If the tag is missing (/rtl-agent-team:rat-setup not run), write an inline fallback file.
mkdir -p .claude/rules
[ ! -f ~/.claude/rules/rtl-coding-conventions.md ] && [ ! -f .claude/rules/rtl-coding-conventions.md ] && cp "${CLAUDE_PLUGIN_ROOT}/skills/rat-init-project/templates/rules/rtl-coding-conventions.md" .claude/rules/
[ ! -f ~/.claude/rules/rtl-verification-gate.md ] && [ ! -f .claude/rules/rtl-verification-gate.md ] && cp "${CLAUDE_PLUGIN_ROOT}/skills/rat-init-project/templates/rules/rtl-verification-gate.md" .claude/rules/
If grep -q '<markdown_diagram_rule>' ~/.claude/CLAUDE.md fails AND .claude/rules/diagram-rules.md
does not exist, use Write tool to create .claude/rules/diagram-rules.md with:
---
paths:
- "docs/**/*.md"
- "reviews/**/*.md"
---
# Diagram Policy
| Diagram Type | Tool | Use For |
|-------------|------|---------|
| **Block diagram** | **D2** | Architecture, module hierarchy, HW block decomposition |
| **Flow / Interaction** | **Mermaid** | Pipeline stages, FSM, data/control flow, sequence diagrams |
| **ASCII flow diagram** | **Prohibited** | Do NOT use ASCII art — use D2 or Mermaid |
2d. Deploy guides (copy CLAUDE.md to each directory if not already present):
[ ! -f rtl/CLAUDE.md ] && cp "${CLAUDE_PLUGIN_ROOT}/skills/rat-init-project/templates/guides/rtl-guide.md" rtl/CLAUDE.md
[ ! -f sim/CLAUDE.md ] && cp "${CLAUDE_PLUGIN_ROOT}/skills/rat-init-project/templates/guides/sim-guide.md" sim/CLAUDE.md
[ ! -f docs/CLAUDE.md ] && cp "${CLAUDE_PLUGIN_ROOT}/skills/rat-init-project/templates/guides/docs-guide.md" docs/CLAUDE.md
[ ! -f reviews/CLAUDE.md ] && cp "${CLAUDE_PLUGIN_ROOT}/skills/rat-init-project/templates/guides/reviews-guide.md" reviews/CLAUDE.md
[ ! -f refc/CLAUDE.md ] && cp "${CLAUDE_PLUGIN_ROOT}/skills/rat-init-project/templates/guides/refc-guide.md" refc/CLAUDE.md
[ ! -f syn/CLAUDE.md ] && cp "${CLAUDE_PLUGIN_ROOT}/skills/rat-init-project/templates/guides/syn-guide.md" syn/CLAUDE.md
-
Generate lessons-learned.md (if docs/lessons-learned.md does not exist):
Create docs/lessons-learned.md with initial header:
# Lessons Learned
> Cross-phase knowledge base. Entries are appended after each bug fix (especially Phase 5→4 feedback).
> Agents in Phase 4/5 should read this file to avoid repeating known issues.
>
> Entry format: LL-{NNN} with sections: Symptom, Root Cause, Fix Applied, Prevention, Related (REQ IDs, module, fix commit, ADR, Phase 5 Sub-phase)
---
-
Generate filelist templates (if rtl/ has no .f files):
- Copy
skills/rat-init-project/templates/filelist.f to rtl/filelist_top.f as starting point.
- Per-module filelists (
rtl/filelist_{module}.f) are created during Phase 4 when modules are coded.
- Filelist convention (3 types):
| Type | Location | Required |
|---|
| Module-level | rtl/filelist_{module}.f | MUST exist per module |
| Top-level | rtl/filelist_top.f | MUST exist (includes module filelists) |
| TB/test | in sim/ scope | Dynamic (scripts add at runtime) |
4.5. Install run_sim.sh (if scripts/run_sim.sh does not exist):
Copy scripts/run_sim.sh and make executable:
chmod +x scripts/run_sim.sh
This simulator-agnostic script supports iverilog, verilator, vcs, xrun, questa.
4.7. Install EDA scripts (if script folders are empty):
Create lint, synthesis, CDC, and equivalence checking scripts plus the shared tool runner library.
All scripts use lib/tool-runner.sh for transparent Docker fallback when local tools are missing.
- Tool runner:
lib/tool-runner.sh — run_tool() tries local binary first, falls back to persistent Docker container
- Lint:
lint/scripts/run_lint.sh — verilator/verible/slang + spyglass
- Synthesis:
syn/scripts/run_syn.sh — yosys + dc_shell (Synopsys) + genus (Cadence)
- Equivalence checking:
syn/scripts/run_formality.sh (Synopsys) + syn/scripts/run_conformal.sh (Cadence)
- CDC:
lint/scripts/run_cdc.sh — structural quick check + spyglass/vc_cdc/questa_cdc
- Runtime hook integration:
hooks/rtl-skill-activation.sh runs
skills/rat-init-project/scripts/install_project_templates.sh automatically when rat-init-project starts.
4.9. Deploy project Makefile (if project root has no Makefile):
Copy the unified build system Makefile that wraps all EDA scripts:
[ ! -f Makefile ] && cp "${CLAUDE_PLUGIN_ROOT}/skills/rat-init-project/templates/Makefile" Makefile
Open-source tools by default (make sim, make lint, make syn, make formal).
Commercial EDA via _tool suffix (make sim_xrun, make lint_spyglass, make syn_dc).
Run make help to see all targets and variables.
4.10. Deploy UVM regression runner (if sim/uvm/scripts/ has no run_regression_uvm.sh):
mkdir -p sim/uvm/scripts
[ ! -f sim/uvm/scripts/run_regression_uvm.sh ] && cp "${CLAUDE_PLUGIN_ROOT}/skills/rtl-p5s-uvm-verify/scripts/run_regression_uvm.sh" sim/uvm/scripts/run_regression_uvm.sh && chmod +x sim/uvm/scripts/run_regression_uvm.sh
Multi-seed UVM regression with VCS/Xcelium/Questa, coverage merge, failure halt.
Referenced by Makefile uvm_regression target.
- Generate cocotb Makefile template (if sim/ has no Makefile):
Copy
skills/rat-init-project/templates/cocotb-makefile to sim/top/Makefile as reference.
Per-module cocotb Makefiles are created in sim/{module}/Makefile during Phase 4-5.
Adapters MUST retain .DEFAULT_GOAL := sim (from the template) so bare make
runs the cocotb sim target. If a helper target (e.g. ref: to build a DPI-C
reference model) is added ABOVE the cocotb include, either keep .DEFAULT_GOAL := sim
or make the helper a prerequisite of sim (e.g. sim: ref) — otherwise bare
make no-ops with "Nothing to be done".
5.5. Deploy Phase 6 PDF Makefile (if reviews/phase-6-review/ has no Makefile):
Copy skills/rat-init-project/templates/phase6-pdf-makefile to reviews/phase-6-review/Makefile.
5.7. Generate SV testbench template (inform user):
Reference skills/rtl-p4s-unit-test/templates/sv-testbench-template.sv for Tier 2 unit tests.
Replace {{MODULE_NAME}} and {{DOMAIN}} placeholders when creating per-module TBs.
-
Generate module template (if rtl/ has no .sv files):
Create rtl/include/template_module.sv demonstrating project naming conventions:
// template_module.sv — Template demonstrating project coding conventions
// Style: lowRISC SV Style Guide + project overrides (i_/o_ prefix, {domain}_clk/rst_n)
module template_module
import template_module_pkg::*;
#(
parameter int DATA_WIDTH = 32
) (
input logic sys_clk, // Clock: {domain}_clk format
input logic sys_rst_n, // Reset: {domain}_rst_n format
input logic [DATA_WIDTH-1:0] i_data, // Input: i_ prefix
input logic i_valid, // Input: i_ prefix
output logic [DATA_WIDTH-1:0] o_result, // Output: o_ prefix
output logic o_ready // Output: o_ prefix
);
// Use logic only (no reg/wire), typedef enum for FSM, u_ instance prefix, gen_ generate prefix
endmodule
-
Quick EDA tool status (informational only, does NOT install):
Check availability of required tools and report status.
If any required tool is missing, recommend: "Run /rtl-agent-team:rat-setup to install missing tools."
-
Report project initialization summary:
## RTL Project Initialization Report
- Directory structure: [N] directories created, [M] already existed
- Rules deployed: .claude/rules/ ([2] files + diagram-rules fallback if needed)
- Guides deployed: [6] CLAUDE.md files
- Templates: filelist, Makefile, EDA scripts, module template
- Coding conventions: lowRISK SV Style + project overrides
- Port prefix: i_/o_/io_ (NOT suffix _i/_o)
- Clock: {domain}_clk (e.g., sys_clk)
- Reset: {domain}_rst_n (e.g., sys_rst_n)
- EDA tools: [X/Y] required tools available
- Missing tools: [list] → run /rtl-agent-team:rat-setup to install
- Project ready: Yes/No
<Tool_Usage>
# Directory creation (Bash CLI)
Bash: mkdir -p specs refc/include refc/build bfm/include rtl/common rtl/include rtl/top sim/top formal lint/cdc lint/cdc/reports lint/scripts lint/lint syn/{scripts,constraints,db,vnet,svf,scr,rpt,log,temp,work} docs/phase-{1-research,2-architecture,3-uarch,4-rtl,5-verify,7-exploration} docs/decisions reviews/phase-{1-research,2-architecture,3-uarch,4-rtl,5-verify,6-review,7-exploration} .rat/state .rat/scratch
# Rules deployment (skip if already global, non-destructive)
Bash: mkdir -p .claude/rules
Bash: [ ! -f ~/.claude/rules/rtl-coding-conventions.md ] && [ ! -f .claude/rules/rtl-coding-conventions.md ] && cp "${CLAUDE_PLUGIN_ROOT}/skills/rat-init-project/templates/rules/rtl-coding-conventions.md" .claude/rules/ || true
Bash: [ ! -f ~/.claude/rules/rtl-verification-gate.md ] && [ ! -f .claude/rules/rtl-verification-gate.md ] && cp "${CLAUDE_PLUGIN_ROOT}/skills/rat-init-project/templates/rules/rtl-verification-gate.md" .claude/rules/ || true
# Diagram rules: if <markdown_diagram_rule> tag missing from ~/.claude/CLAUDE.md,
# use Write tool to create .claude/rules/diagram-rules.md with inline content (see Step 2a)
# Guide deployment (non-destructive, copy as CLAUDE.md)
Bash: [ ! -f rtl/CLAUDE.md ] && cp "${CLAUDE_PLUGIN_ROOT}/skills/rat-init-project/templates/guides/rtl-guide.md" rtl/CLAUDE.md || true
Bash: [ ! -f sim/CLAUDE.md ] && cp "${CLAUDE_PLUGIN_ROOT}/skills/rat-init-project/templates/guides/sim-guide.md" sim/CLAUDE.md || true
Bash: [ ! -f docs/CLAUDE.md ] && cp "${CLAUDE_PLUGIN_ROOT}/skills/rat-init-project/templates/guides/docs-guide.md" docs/CLAUDE.md || true
Bash: [ ! -f reviews/CLAUDE.md ] && cp "${CLAUDE_PLUGIN_ROOT}/skills/rat-init-project/templates/guides/reviews-guide.md" reviews/CLAUDE.md || true
Bash: [ ! -f refc/CLAUDE.md ] && cp "${CLAUDE_PLUGIN_ROOT}/skills/rat-init-project/templates/guides/refc-guide.md" refc/CLAUDE.md || true
Bash: [ ! -f syn/CLAUDE.md ] && cp "${CLAUDE_PLUGIN_ROOT}/skills/rat-init-project/templates/guides/syn-guide.md" syn/CLAUDE.md || true
# Quick tool status (informational)
Bash: verilator --version 2>&1 || echo "NOT_FOUND"
Bash: python3 -c "import cocotb; print(cocotb.__version__)" 2>&1 || echo "NOT_FOUND"
Bash: verible-verilog-lint --version 2>&1 || echo "NOT_FOUND"
Bash: slang --version 2>&1 || echo "NOT_FOUND"
# Template deployment (non-destructive, idempotent)
Bash: bash "${CLAUDE_PLUGIN_ROOT}/skills/rat-init-project/scripts/install_project_templates.sh" "$PWD"
Bash: [ -f rtl/filelist_top.f ] || cp "${CLAUDE_PLUGIN_ROOT}/skills/rat-init-project/templates/filelist.f" rtl/filelist_top.f
Bash: [ -f sim/top/Makefile ] || cp "${CLAUDE_PLUGIN_ROOT}/skills/rat-init-project/templates/cocotb-makefile" sim/top/Makefile
Bash: mkdir -p reviews/phase-6-review && cp -n "${CLAUDE_PLUGIN_ROOT}/skills/rat-init-project/templates/phase6-pdf-makefile" reviews/phase-6-review/Makefile
Write: rtl/include/template_module.sv — convention reference template (i_/o_ prefix, sys_clk/sys_rst_n)
All EDA tools are executed via Bash CLI directly. No MCP tool servers for EDA.
</Tool_Usage>
<Escalation_And_Stop_Conditions>
- Directory creation permission denied → report error, suggest user fix permissions
- Existing project detected (rtl/ has .sv files in subdirectories) → warn user, ask whether to skip template generation
- No write access to project directory → halt, cannot create structure
- Required EDA tools missing → recommend
/rtl-agent-team:rat-setup (do NOT attempt installation here)
</Escalation_And_Stop_Conditions>
<Final_Checklist>
