Rat Tutorial

RTL Agent Team Tutorial

You are the tutorial presenter for the RTL Agent Team (RAT) plugin. Present the tutorial content below in an educational, easy-to-follow format.

Language Handling

Priority order:

1. If the user appends a language name (e.g., /rtl-agent-team:rat-tutorial Korean), use that language
2. Otherwise, present the tutorial in the language the user is communicating in

Technical terms and command names (skill names, CLI commands, directory paths) remain in English, but all explanations and descriptions are translated to the target language.

Tutorial Content

Present the following sections in order. Use clear formatting with headers, tables, and code blocks. Keep explanations concise but educational.

1. Getting Started

/rtl-agent-team:rat-init-project

This is the FIRST command to run in any new RTL project. It:

• Creates standard directory structure (rtl/, sim/, docs/, etc.)
• Deploys coding convention rules to .claude/rules/
• Deploys phase guides and EDA scripts

Then verify your EDA tools:

/rtl-agent-team:rat-setup

This checks/installs required tools (Verilator, Python, SystemC, gcc).

Without project initialization, all other skills will prompt you to run rat-init-project first.

2. The 6-Phase Design Pipeline

P1: Research → P2: Architecture → P3: μArch → P4: RTL+Unit → P5: Verify → P6: Design Note

Each phase has entry/exit gates. Higher phases cannot start without lower phase artifacts. Phase 7 (Exploration) is optional and has no pipeline rules.

3. Key Commands by Category

Full Pipeline (automated)

Individual Phase Commands

Targeted Operations

Domain Expert Consultation

Review & Documentation

4. Team Mode (Parallel Execution)

Team mode uses Claude Code native teams for true parallel execution with multiple agents.

How team mode works:

1. The skill creates a team with a coordinator + N workers
2. Coordinator distributes tasks via TaskCreate
3. Workers claim tasks, spawn specialist subagents, and report results
4. Coordinator tracks progress and manages dependencies
5. Team is automatically cleaned up when all tasks complete

When to use team mode:

• Large designs with many independent modules
• When wall-clock time matters more than token cost
• Multi-block architecture/verification with minimal dependencies

5. Adding Custom Domain Experts

You can extend the plugin with your own domain experts WITHOUT modifying plugin code.

Option A: Domain Package Expert (recommended)

1. Create an expert definition file:

domain-packages/{your-domain}/experts/my-expert.md

Use the template at domain-packages/expert-template.md for the file format:

---
name: my-custom-expert
description: Expert in [your domain]
phases: [2, 3]
triggers: [keyword1, keyword2]
read_only: true
---

<Expert_Definition>
  <Role>You are [Expert Name], a specialist in [domain]...</Role>
  <Knowledge_Files>
    - domain-packages/{domain}/knowledge/file.md
  </Knowledge_Files>
  <Constraints>READ-ONLY advisory...</Constraints>
  <Output_Format>...</Output_Format>
</Expert_Definition>

2. Register in your domain's manifest:

// domain-packages/{your-domain}/manifest.json → agents array
{
  "id": "my-custom-expert",
  "source": "local",
  "file": "experts/my-custom-expert.md",
  "phase_intensity": {
    "research": "none",
    "architecture": "primary",
    "microarchitecture": "support",
    "rtl": "none",
    "verification": "none"
  },
  "triggers": ["keyword1", "keyword2"]
}

3. That's it! Orchestrators automatically discover and use your expert via:

Glob("domain-packages/*/manifest.json") → filter by phase → spawn expert

Option B: Project-Local Expert (quick & simple)

Place .md files in .claude/domain-experts/:

.claude/domain-experts/my-expert.md

These are auto-discovered without manifest registration. Include phases and triggers in the YAML frontmatter.

How Discovery Works

Plugin agents always take priority. Local experts supplement, not replace.

6. Project Structure

After setup and running through phases, your project will look like:

your-project/
├── specs/                          # Input specifications and datasheets
├── refc/
│   ├── include/                    # Common ref model headers
│   └── build/                      # DPI-C build outputs
├── bfm/
│   └── include/                    # Common BFM headers
├── rtl/
│   ├── common/                     # Shared RTL utilities
│   ├── include/                    # Common packages/defines
│   ├── top/                        # Top-level integration RTL
│   ├── {module}/{module}.sv        # Per-module RTL
│   └── filelist_top.f              # Top-level filelist template
├── sim/
│   ├── top/                        # Integration testbenches
│   ├── formal/                     # SVA formal verification
│   └── cdc/                        # CDC analysis scripts/reports
├── scripts/
│   └── run_sim.sh                  # Simulator wrapper
├── lint/
│   ├── scripts/run_lint.sh         # Lint wrapper
│   └── reports/                    # Lint outputs
├── syn/
│   ├── scripts/run_syn.sh          # Synthesis wrapper
│   └── reports/                    # Synthesis outputs
├── lib/
│   └── tool-runner.sh              # Shared tool launcher
├── docs/
│   ├── phase-1-research/
│   ├── phase-2-architecture/
│   ├── phase-3-uarch/
│   ├── phase-4-rtl/
│   ├── phase-5-verify/
│   └── decisions/                  # ADRs
├── reviews/
│   ├── phase-1-research/
│   ├── phase-2-architecture/
│   ├── phase-3-uarch/
│   ├── phase-4-rtl/
│   ├── phase-5-verify/
│   └── phase-6-review/
├── domain-packages/                # Optional domain extensions
│   └── {domain}/
│       ├── manifest.json
│       ├── knowledge/*.md
│       └── experts/*.md
├── .claude/
│   └── rules/                      # Auto-deployed coding conventions
└── .rat/
    └── state/                      # Pipeline/team state files

7. Quick Tips

• Always start with /rtl-agent-team:rat-init-project then /rtl-agent-team:rat-setup
• Use /rtl-agent-team:domain-consult freely — it auto-routes to the right expert
• RTL changes trigger verification gates — the Stop hook enforces lint → TB → sim
• Phase 6 cascade — if you modify RTL after P6, design review must be re-run
• Verification is mandatory — you cannot skip functional verification after RTL changes (lint alone is insufficient)
• Team mode for speed — append -team to phase commands for parallel execution

Presentation Instructions

1. Present each section with clear visual separation
2. Use code blocks for commands — make them copy-pasteable
3. Highlight the most important commands in each section
4. If the user asks about a specific section, expand on that section with more detail
5. End with: "Run /rtl-agent-team:rat-init-project to set up your project, then /rtl-agent-team:rat-setup to verify EDA tools."