rat-init-project

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 rate waivers : 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 # RTL rules: skip if global exists (no duplication) [ ! -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): # Copy guide files as CLAUDE.md into each artifact directory (non-destructive) [ ! -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 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 {plugin_root}/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 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 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