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).

2. 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

3. 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)
   
   ---
   

4. 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.

5. 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.

6. 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
   

7. 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."

8. 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>

• All required directories exist
• Rules deployed to .claude/rules/ (2 rule files + diagram-rules fallback if needed)
• Guides deployed as CLAUDE.md (6 files)
• Template files created for empty directories
• Module template (rtl/include/template_module.sv) demonstrates naming conventions
• EDA scripts installed (lint, synthesis, CDC, equivalence, tool-runner)
• Quick tool status reported
• Missing tools → recommended /rtl-agent-team:rat-setup
• Project initialization report displayed to user </Final_Checklist>