한국어 문서: README_kr.md

RTL Agent Team

A Claude Code plugin for automated RTL design and verification. 99 specialized AI agents + 97 skills automate the 6-Phase pipeline: Research → Architecture → μArch → RTL → Verify → Design Note.

A Claude Code plugin for automated RTL design and verification.

Automates the 6-Phase design pipeline (Research → Architecture → μArch → RTL → Verify → Design Note) with 99 specialized AI agents + 97 skills + 27 reference documents.

Marketplace

This repository serves as the RTL Agent Marketplace, providing hardware design plugins.

Additional plugins (domain knowledge packages, MCP servers, specialized skills, etc.) will be added to the Marketplace over time.

Quick Start

The workflow has three distinct stages, each with a different scope and frequency:

Run each stage from its appropriate working directory: Stage A runs anywhere; Stages B and C should run from inside the target project directory (artifacts like docs/phase-*/, rtl/, .rat/state/ are written relative to CWD).

Stage A — Machine Setup (one-time, per machine)

Installs the plugin, audits the EDA toolchain interactively, and optionally deploys global coding conventions.

# A1. Register the Marketplace (one-time)
/plugin marketplace add babyworm/rtl-agent-team

# A2. Install plugins (one-time)
/plugin install rtl-agent-team
/plugin install systemverilog-lsp   # (optional) SV LSP

# A3. EDA toolchain audit (interactive interview — all steps are opt-in)
#     - Q1 Required tools: python3, g++, make, verilator, cocotb, systemc
#            + lint (verible AND/OR slang — at least one)
#            + CDC (svlens OR sg_shell OR vc_cdc OR questa_cdc — at least one)
#            — prompt to install missing ones (local/global/docker/skip)
#     - Q2 Recommended/optional tools — user picks which to install:
#            jq, yosys + sby, slang-server, iverilog, gtkwave
#     - Q2b Commercial tool scan (vcs, xrun, dc_shell, sg_shell, vc_cdc, ...)
#            — scan + collect env_source; not an install
#     - Q2c Liberty file path for synthesis (optional)
#     - Q3 Optional global deployment (yes/no) — deploys:
#            ~/.claude/rules/rtl-coding-conventions.md
#            ~/.claude/rules/rtl-verification-gate.md
#            ~/.claude/CLAUDE.md diagram rule block (if tag missing)
/rtl-agent-team:rat-setup

If systemverilog-lsp is installed but slang-server is missing, the sub-plugin checks on SessionStart and prompts for local (~/.local/bin, recommended), global, or skip.

Stage B — Project Initialization (one-time, per project)

Scaffolds project directory structure, deploys per-project rules and guides, and auto-installs EDA wrapper scripts. Run from inside the project directory. Existing templates and rules are left intact; managed exceptions are the RAT block in project CLAUDE.md, refreshed tool detection in rat_config.json, and regenerated config.mk. Usable tool path overrides are preserved, while stale or unusable paths are refreshed.

# B1. cd into your project directory
cd ~/work/my-rtl-project

# B2. Initialize project structure (run inside project)
#     - Creates docs/, rtl/, sim/, refc/, lint/, syn/, formal/, reviews/
#     - Deploys .claude/rules/ (coding conventions, verification gate)
#     - Deploys subdirectory CLAUDE.md (phase-specific guides)
#     - Auto-installs run_sim.sh, run_lint.sh, run_syn.sh, run_cdc.sh
#     - Existing templates/rules are not overwritten; managed config is refreshed
/rtl-agent-team:rat-init-project

Stage C — Design Work (recurring, inside project)

Execute RTL design and verification pipeline. Run from inside an initialized project — artifacts are created relative to CWD, so an uninitialized directory will not have the expected structure.

# C1. Full automation (6-Phase pipeline)
/rtl-agent-team:rat-auto-design
# Example natural-language usage:
#   /rtl-agent-team:rat-auto-design "Design an H.264 TQ subsystem"
#   /rtl-agent-team:rat-auto-design "implement VDC-M 1.2 encoder using reference C
#     model in ../vdc-m/refc. Target 4K 60fps at 500MHz, margin 40% under TSMC 28nm"

# C2. OR split pipeline (for human review between stages)
/rtl-agent-team:rat-dse               # Phase 1→2: DSE (algorithm + architecture)
/rtl-agent-team:rat-p1p3-spec-uarch   # Phase 1→3: Spec → μArch design docs
/rtl-agent-team:rat-p4p5-impl-verify  # Phase 4→5: RTL implementation + verification

# C3. OR individual phase/sub-phase skills (see Usage section below)

---

Installation (Stage A alternatives)

The Quick Start Stage A already covers plugin installation. The alternatives below are for users who prefer CLI or development symlinks. After installing the plugin, still run /rtl-agent-team:rat-setup once to audit the EDA toolchain.

Install from Claude Code chat (recommended)

/plugin marketplace add babyworm/rtl-agent-team
/plugin install rtl-agent-team

Verify installation: /plugin

Install from CLI

claude plugin marketplace add babyworm/rtl-agent-team
claude plugin install rtl-agent-team

Local plugin development

When developing with direct access to the plugin source, launch Claude Code from the standalone clone root with the supported --plugin-dir option:

git clone https://github.com/babyworm/rtl-agent-team.git
cd rtl-agent-team
claude --plugin-dir .

Usage (Stage C — in-project design work)

This section assumes Stage A (machine setup) and Stage B (project init) are already complete. All commands in this section run from inside an initialized project directory. See Quick Start for the full stage map.

Routing contract

• Route user intent to Action Skills first (for example, /rtl-agent-team:rat-auto-design, /rtl-agent-team:rtl-p5-verify).
• Orchestrator agents are internal execution units and are spawned by Action Skills via Task(...).
• Policy skills are loaded by orchestrators via skills: [*-policy].
• rtl-orchestrate is an internal routing reference skill (user-invocable: false), not a user slash command.

Full automation

/rtl-agent-team:rat-auto-design

Runs the entire 6-Phase pipeline automatically. You can also use natural language, e.g., “Design an H.264 TQ subsystem”.

Autopilot escalation ladder

rat-auto-design gates use a per-gate retry ladder:

• 1..N: primary strategy
• N+1..2N: fallback strategy (scope split + agent composition switch)
• 2N+1: last-chance alternative (one automatic attempt)
• after last-chance fail: stop and ask user guidance

Dynamic fallback guidance is injected through state (orchestration_control.dynamic_prompt_text) and surfaced by Stop hooks.

Pipeline composition (split execution)

/rtl-agent-team:rat-dse              # Phase 1→2: Deep algorithm + architecture exploration (DSE)
/rtl-agent-team:codec-rd-eval        # BD-PSNR/BD-rate evaluation for algorithm comparison
/rtl-agent-team:codec-conformance-eval  # Decoder conformance evaluation (JVET/JCTVC/3rd party)
/rtl-agent-team:rat-p1p3-spec-uarch    # Phase 1→3: Spec → μArch design documents
/rtl-agent-team:rat-p4p5-impl-verify  # Phase 4→5: μArch → RTL implementation + verification

Split the pipeline for human review between design and implementation:

• rat-dse: Deep Design Space Exploration — compare multiple algorithms and architecture candidates with quantitative trade-offs. Can also transform an existing functional C model into an architectural reference model. Stops at Phase 2 for review.
• rat-p1p3-spec-uarch: Standard Phase 1→3 — produce design documents through μArch. Stops for review before RTL.
• rat-p4p5-impl-verify: Phase 4→5 — implement RTL and run full verification from approved μArch documents.

Resume interrupted pipeline

If rat-auto-design is interrupted, progress is saved automatically. Re-run the same command to resume from the last incomplete step — completed phases are skipped.

Note: Project initialization (rat-init-project) and EDA tool setup (rat-setup) belong to Stages A/B and are described in Quick Start.

Individual skills

/rtl-agent-team:rtl-lint-check           # RTL lint check
/rtl-agent-team:rtl-p5s-func-verify      # cocotb functional verification
/rtl-agent-team:rtl-synth-check          # Yosys synthesis
/rtl-agent-team:rtl-p5s-sva-check        # SVA formal verification
/rtl-agent-team:p2-arch-design           # Architecture design
/rtl-agent-team:domain-consult           # Domain expert consultation

Skill categories (97 skills)

Assets (Templates, Scripts, References, Examples) are distributed across the 97 skills — see each skill directory for its bundled assets.

Project Artifact Structure

Each Phase’s design artifacts (docs/) serve as inputs to the next Phase, forming a pipeline. Spec compliance verdicts (reviews/) are managed separately.

docs/phase-1-research/ ──→ docs/phase-2-architecture/ ──→ docs/phase-3-uarch/
        ──→ docs/phase-4-rtl/ ──→ docs/phase-5-verify/ ──→ reviews/phase-6-review/
        ──→ docs/phase-7-exploration/ (optional, free exploration)

Plugin Structure

rtl-agent-team/
├── .claude-plugin/
│   ├── plugin.json             # Plugin manifest (auto-discovery)
│   └── marketplace.json        # Marketplace definition
├── CLAUDE.md                   # 6-Phase pipeline rules
├── agents/                     # 99 agents (design/verification/review/EDA/domain/orchestrators)
├── scripts/
│   └── run_sim.sh              # Simulator-agnostic compile+run wrapper (replay-enabled)
├── skills/                     # 97 skills (SKILL.md + templates/ + examples/)
│   ├── rtl-orchestrate/        # Internal routing SSOT + SessionStart hook export source
│   ├── rat-init-project/
│   │   ├── scripts/
│   │   │   └── install_project_templates.sh  # Hook-driven template auto-installer
│   │   └── templates/          # run_lint.sh, run_syn.sh, run_cdc.sh + other templates
│   ├── rtl-p5s-func-verify/
│   │   ├── scripts/            # run_regression.sh, merge_coverage.sh
│   │       └── run_regression.sh  # Multi-seed regression runner (local-first)
│   ├── systemverilog/          # RTL coding conventions (lowRISC + overrides)
│   ├── systemverilog-assertion/ # SVA coding conventions (bind, SymbiYosys)
│   ├── uvm/                    # UVM coding conventions (factory, TLM, coverage)
│   ├── systemc/                # SystemC/TLM-2.0 (AT non-blocking, AMBA-PV)
│   └── {skill}/references/     # 27 reference documents (distributed per skill)
│       ├── coding-style-guide.md   # SV naming conventions (in systemverilog/)
│       ├── axi-protocol-rules.md   # AXI4 per-channel SVA templates (in rtl-p5s-protocol-verify/)
│       ├── sva-patterns.md         # SVA temporal operators + pattern library (in rtl-p5s-sva-check/)
│       ├── cocotb-ecosystem.md     # cocotb API, cocotb-bus, coverage (in rtl-p5s-func-verify/)
│       └── ...                     # + 23 more (CDC, UVM, Yosys, SDC, etc.)
├── hooks/                      # Event-driven enforcement (14 hook scripts / 15 registrations)
│   ├── rtl-skill-activation.sh # PreToolUse:Skill — setup check + template bootstrap
│   └── ...                     # + 13 more (routing inject, verify gate, cascade, etc.)
├── docker/                     # EDA tool Docker image
│   └── Dockerfile              # Open-source EDA full bundle
└── domain-packages/            # Domain knowledge packages
    ├── video-codec/            # H.264/H.265 knowledge, conformance data
    └── video-processing/       # Color conversion, denoise, HDR/ISP (3 agents)

Routing sync for contributors

When modifying routing/delegation docs:

sh scripts/sync_orchestrator_inject.sh
python3 -m pytest -q tests/unit/test_agent_skill_structure.py tests/unit/test_hooks.py tests/unit/test_plugin_runtime_contract.py

Agent Team

Agent Composition (99 agents: 97 Opus, 2 Sonnet)

Model policy:

• Use opus for reasoning-heavy analysis, architecture decisions, and debugging.
• Use sonnet only for documentation generation or tool-result summarization/formatting.

6-Phase Pipeline (+Phase 7 Optional Exploration)

Additional pipeline artifacts: Each Phase (1-5) generates phase-N-summary.md for downstream context compression. Phase 4 Stream B produces SVA/CDC/TB skeletons in parallel with RTL coding. Phase 2-3 record Architecture Decision Records in docs/decisions/.

Post-Verify PPA Optimization (new in v0.10.0)

Optional stage between Phase 5 (verify PASS) and Phase 6 (design note). Runs an iterative Design Compiler synthesis → JSON report → RTL patch → equivalence

• smoke → convergence-check loop until one of three termination tiers fires: normal convergence (3-iter streak × |Δ|<2%), early plateau (iter 1-2 ×|Δ|<1% → escalate to user, EDA tools already near optimum), or max cycles (default 4). Timing-first heuristic (default weights 0.7 / 0.2 / 0.1).

Requirements:

• dc_shell (Synopsys Design Compiler) OR genus (Cadence) in PATH
• requirements.json["ppa_targets"] section (scaffold auto-written on first run)
• Phase 5 PASS (reviews/phase-5-verify/final-compliance.md verdict=PASS)
• Clean git tree under rtl/${top}/

Artifacts: docs/ppa-opt/iter-{N}/ (reports, patch, rationale, equiv/smoke evidence), docs/ppa-opt/final-report.md, reviews/ppa-opt/convergence-review.md. Every iteration that worsens WNS by >20 ps or fails equivalence/smoke is automatically rolled back. See plugin_docs/specs/2026-04-17-ppa-optimizer-dc-design.md for the full spec.

Coding Convention Skills

3-Layer Documentation Structure (Progressive Disclosure)

EDA Tools

The eda-runner agent executes local EDA CLI tools directly via Bash.

Use /rtl-agent-team:rat-setup to check tool installation status and configure commercial tools interactively.

For detailed commercial tool setup (env_source, technology library, vendor examples), see the EDA Setup Guide.

EDA Wrapper Scripts

Project EDA wrappers record timestamped runs and generate _latest.sh replay scripts for reproducibility. The regression runner is a plugin-bundled helper with its own per-seed and aggregate JSON reports; it does not generate replay scripts.

rat-init-project installs the project wrappers listed above plus formal/equivalence and UVM regression helpers. Simulation, lint, CDC, and equivalence runs write replay scripts under {outdir}/replay/; synthesis writes them under {syn_root}/scr/replay/. Regression helpers generate reports rather than replay scripts. run_regression.sh remains under {plugin_root} and is invoked by the functional-verification skill.

Regression runner defaults to --mode local with max(1, nproc-2) parallel jobs. AWS Batch requires explicit opt-in (RTL_ALLOW_AWS=1 + RTL_AWS_BATCH_RUNNER).

Docker EDA Image (Recommended)

If installing EDA tools individually is cumbersome, you can build a Docker image containing all tools:

# Run these build commands from a standalone rtl-agent-team clone root.
cd /path/to/rtl-agent-team

# Build image (one-time)
docker build -t rtl-eda-tools docker/

# Run with an RTL project mounted
docker run -it --rm \
  --user "$(id -u):$(id -g)" --env HOME=/tmp \
  --mount "type=bind,src=/absolute/path/to/rtl-project,dst=/workspace" \
  --workdir /workspace rtl-eda-tools

# Build with specific versions
docker build -t rtl-eda-tools \
  --build-arg VERILATOR_VERSION=5.024 \
  --build-arg SLANG_VERSION=v11.0 \
  --build-arg SVLENS_VERSION=v0.3.6 \
  --build-arg SYSTEMC_VERSION=3.0.2 \
  docker/

Included tools: Verilator, Verible, Yosys, Icarus Verilog, slang, svlens (CDC + structural analysis), slang-server (SV LSP), SystemC/TLM-2.0, SymbiYosys (+ boolector, z3), GTKWave, cocotb, cocotb-bus, cocotbext-axi, gcc/g++.

You can also build from Claude Code: “Build the EDA Docker image” or run /rtl-agent-team:rat-setup and select the Docker option.

Marketplace Structure

This repository operates as a marketplace, not a single plugin. The systemverilog-lsp entry is sourced from its external GitHub repository and is not vendored in this tree.

rtl-agent-team/                          # Marketplace root
├── .claude-plugin/
│   ├── plugin.json                      # rtl-agent-team plugin manifest
│   └── marketplace.json                 # Marketplace definition (plugin list)
├── agents/                              # rtl-agent-team agents (99)
├── skills/                              # rtl-agent-team skills (97, with 27 reference docs)
└── domain-packages/                     # Domain knowledge packages
    ├── video-codec/                     # H.264/H.265 codec knowledge
    └── video-processing/                # Color, denoise, HDR/ISP

To add a new plugin to the Marketplace, add an entry to the plugins array in .claude-plugin/marketplace.json:

• Same repo: "source": "./plugins/new-plugin"
• External repo: "source": {"source": "github", "repo": "owner/repo"}

Development

This plugin is declarative-first (.md + .json skill definitions with helper .py/.sh scripts) — no build step required.

git clone https://github.com/babyworm/rtl-agent-team.git
cd rtl-agent-team
claude --plugin-dir .

License

MIT