Rtl Orchestrate

RTL Design Flow — Orchestration Reference

Complete reference for orchestrating the RTL design pipeline. Use this when:

• Unsure which skill or agent to invoke for a given task
• Need the full routing table (natural language → skill mapping)
• Need the complete agent delegation matrix
• Want to review the design pipeline rules and principles

This skill is informational — it injects routing context, not an action workflow.

Skill Routing Table

When RTL/HDL/FPGA/ASIC related tasks are detected, route to Action Skills first. Orchestrator agents are internal execution units spawned only by Action Skills.

Invocation types:

• Action Skill: user-facing entry point via Skill(skill="rtl-agent-team:XXX")
• Convention: loaded by writer agents via their skills: frontmatter, not user-invocable
• Internal Reference: non-user-facing skill used for routing/context export only

Action Skill → Orchestrator Agent Mapping (internal)

Action Skills are user-facing. Each action delegates to one orchestrator agent, which loads one policy skill.

Cross-cutting policy skills (referenced by specialist agents, not tied to a single orchestrator):

Specialist agents (spawned by orchestrators, not user-invocable):

Agent Delegation Table

RTL tasks must be delegated to specialized agents. This applies to tasks handling .sv, .svh, .v, .vh files or using EDA tools.

Design Agents

Verification Agents

Expert Review Agents (spawn directly or through skills)

Phase 6 Agents

Orchestrator Agents (pipeline coordinators)

EDA/Infrastructure Agents

Domain Expert Agents

Pipeline Rules (policy + enforcement map)

These rules define the canonical pipeline order. Rule 5 is hook-enforced (hard gate); rules 1-4, 6-8 and 10-11 are policy declarations carried through skill-entry warnings (asymmetric phase gate design — exit strict, entry flexible). See CLAUDE.md "Pipeline Rules" section for the enforcement column.

1. No RTL without Spec (policy): Do not start RTL coding without a specification (spec-analyst first)
2. No TB without Ref Model (policy): Do not write a Testbench without a Reference Model
3. No Synthesis without RTL (policy): Do not run synthesis without RTL code
4. No Formal without Lint (policy — skill warning): Do not run Formal verification without passing Lint
5. Verification Required (HARD — rtl-verify-stop-gate.sh): Do not declare completion after RTL modification without functional verification (lint alone is insufficient)
6. Unit Tests for Phase Gate (policy — skill warning): Do not proceed to Phase 5 without per-module unit tests upon Phase 4 completion + Stream B early verification artifacts (SVA skeletons, CDC preliminary, TB skeletons)
7. Feedback Loop Limit (policy — orchestrator counter): When Phase 5 FAILs, allow a maximum of 2 Phase 4 feedback loops; escalate to user if exceeded
8. Phase 5 PASS Required (policy — skill warning): Do not proceed to Phase 6 without Phase 5 PASS (final-compliance.md verdict=PASS required)
9. Phase 7 Exempt: Phase 7 is exempt from pipeline rules — free exploration allowed without pipeline Gate
10. PPA-Opt Needs Phase 5 PASS (policy — skill warning): Do not start DC-based PPA optimization without Phase 5 PASS
11. PPA-Opt Iteration Gate (policy — orchestrator/skill internal guard): Every PPA-Opt iteration must pass equivalence + smoke before the patch is accepted; on failure, roll back

Core Design Principles

Hierarchical Spec Compliance

Lower stages must never violate the spec of upper stages.

Requirements(Spec) → Architecture → μArch → RTL → Verification
    ↑ Each stage must comply with the decisions of the stage to its left

• Architecture must implement all required functions from the Spec
• μArch must comply with Architecture's block boundaries and interfaces
• RTL must faithfully implement the μArch design
• Verification must validate against the original Spec requirements
• If functional changes needed → return to the upstream stage and obtain user approval

Design priorities (RTL quality criteria):

1. Functional Correctness (highest)
2. Interface Compliance
3. Timing/Performance
4. Area/Power

Cascading Quality

Higher abstraction levels require MORE iterative refinement.

Phase 2-3 converge when finding_delta < 0.1 and all critical issues are resolved. Time is NOT a constraint at upper levels. Spend extra review rounds perfecting architecture and μArch.

Asymmetric Phase Gate Design

Exit gates are strict, entry gates are flexible.

• Exit gates enforce artifact existence (e.g., Stream B files for P4→P5, iron-requirements.json for P1→P2). Missing artifacts → FAIL with specific file list.
• Entry gates scan upstream artifacts and emit WARNING for missing items, but proceed with adaptive scope reduction. Only rat-init-project is a hard entry block. Note: orchestrator "Context Preload" checks (verifying physical existence of input files a phase MUST read) use STOP, not WARNING — phases cannot function without their input data. This is distinct from entry gates which assess quality/completeness.
• Feedback loops are capped (max 2 iterations for P5→P4), then escalate to user via AskUserQuestion.

This ensures downstream phases never receive incomplete inputs, while allowing upstream-incomplete work to proceed with reduced scope.

Document-as-Memory

Design artifacts serve as persistent memory across phases and agents.

iron-requirements.json + open-requirements.json → arch-designer → architecture.md → uarch-designer → docs/phase-3-uarch/*.md → rtl-coder
reviews/phase-N/ → Quality Gate → next phase proceeds or fails

• Each phase reads upstream documents as input context and writes downstream documents as output
• No agent needs to "remember" another agent's output — it reads the document
• Enables resumability: any phase can restart by re-reading its input documents
• Each phase generates phase-N-summary.md on completion for downstream context efficiency

Cross-Phase Artifact Functional Consistency

Verification artifacts MUST be functionally validated against their upstream reference — not merely checked for existence and compilation. Phase 1 (Research) and Phase 6 (Design Note) are excluded as they produce no executable verification artifacts.

Phase 2 refC ──compare──→ external golden C model (if provided, e.g., vendor_ref/) OR Phase 1 requirements
Phase 3 BFM  ──compare──→ Phase 2 refC (shared test vectors, per-block output match) [enforced: G4b gate]
Phase 4 unit ──compare──→ Phase 2 refC golden output [enforced: DPI-C/file; gap: BFM I/O logs]
Phase 5 TB   ──compare──→ Phase 1 requirements via Phase 2 refC as oracle [enforced]

• Validation gates must verify functional correctness (output comparison), not just structural correctness (file exists + compiles)
• If external golden C model is provided (e.g., JM/HM, vendor model): Phase 2 refC AND Phase 3 BFM must both match it
• If no external golden: each phase builds on Phase 1 requirements with progressively more detail
• A verification artifact that compiles but produces wrong output is worse than no artifact — it provides false confidence and propagates errors downstream
• BFM validation gate (P3 G4b) must run both models with shared test vectors, compare per-block outputs against refC, and FAIL on mismatch before proceeding to review
• P3 G4b is the most explicit gate; P4/P5 enforce refC comparison via existing policies; gap: P4 does not yet consume BFM I/O logs

Phase-Aware Invocation Cues (Dynamic Spawn Basis)

Use these cues to justify dynamic spawning of the four high-value specialists:

Phase 1 Proactive Requirement Clarification

If the user's request is ambiguous or incomplete in Phase 1, proactively use AskUserQuestion to clarify.

When to use AskUserQuestion:

• Target resolution/frame rate/codec not specified
• Interface protocol (AXI/APB/custom) not specified
• Clock frequency or timing constraints unclear
• Functional scope ambiguous (encoder/decoder/both, profiles/levels)
• spec-analyst flags [AMBIGUITY] or [CONFLICT]

When NOT to use:

• User provided a detailed spec document
• Standard has only one valid interpretation
• Matter decided by design convention (e.g., active-low reset)

Mandatory Verification After RTL Changes

This rule applies to ALL tasks that modify .sv/.svh/.v/.vh files.

Anti-pattern (prohibited): RTL modify → lint pass → "done" Correct flow: RTL modify → lint pass → TB create/update → simulation PASS → "done"

Gate signals:

• Verification done: touch .rat/state/rtl-verify-done
• Waiver (non-functional changes): touch .rat/state/rtl-verify-waiver

Phase 4 Parallel Streams:

• Stream A: RTL coding (wave-based) → lint → unit TB → unit sim
• Stream B: SVA skeletons + CDC topology + TB skeletons (from uarch, parallel with Stream A)

6+1 Phase Design Pipeline (+Phase 7 Optional)

Phase 1: Research    → docs/phase-1-research/       (spec, domain knowledge)
Phase 2: Arch/Ref    → docs/phase-2-architecture/    + refc/ (C golden)
Phase 3: μArch/TLM   → docs/phase-3-uarch/           + BFM
Phase 4: RTL+Unit    → rtl/{module}/ + sim/{module}/  + docs/phase-4-rtl/
Phase 5: Verify      → formal/ + docs/phase-5-verify/
Phase 6: Design Note → reviews/phase-6-review/
Phase 7: Exploration → docs/phase-7-exploration/      (optional, no pipeline rules)

Artifact separation:

• docs/phase-N-*/ = Design artifacts (guides for next phase)
• reviews/phase-N-*/ = Verdict documents (upper spec compliance check)

4-Tier Testing Hierarchy

Coverage targets (Tier 3): line ≥ 90%, toggle ≥ 80%, FSM ≥ 70%

Coding Conventions (Core Overrides)

1. Port prefix: i_, o_, io_ required (NOT suffix _i, _o). Clock/reset are exceptions (no prefix)
2. Clock: clk (single) or {domain}_clk (multiple). Reset: rst_n or {domain}_rst_n. Active-low async
3. No CamelCase: Parameters → ALL_CAPS. Localparam → L_ prefix. Enum values → ALL_CAPS. All identifiers snake_case or ALL_CAPS
4. Language Standards: SV RTL IEEE 1800-2009, SV Verification IEEE 1800-2012, C ref model C11, C++ BFM C++17
5. Convention skills are loaded by writer agents via their skills: frontmatter (rtl-coder→systemverilog, bfm-dev→systemc, testbench-dev/sva-extractor/protocol-checker→systemverilog-assertion/uvm); naming basics also enforced by the deployed .claude/rules file on .sv access

Full coding rules: .claude/rules/rtl-coding-conventions.md Verification gate rules: .claude/rules/rtl-verification-gate.md Diagram rules: <markdown_diagram_rule> in CLAUDE.md (or .claude/rules/diagram-rules.md fallback)

Domain Packages

Domain packages provide pre-built knowledge bases. Active packages:

Domain expert agents MUST read relevant knowledge files from domain-packages/{domain}/knowledge/ BEFORE producing analysis. Each agent's prompt lists the specific files to read in its "Before analysis, read domain knowledge files:" section.

Hook-Based Enforcement

Stop hook order (current): rtl-verify-stop-gate → rtl-p6-cascade-gate → rtl-skill-completion-gate → rtl-coverage-exclusion-gate → stop-gate. (Authoritative registration + order: hooks/hooks.json. Full 14-hook inventory: CLAUDE.md Hook-Based Enforcement table.)

State Files

Hook-enforced (quality gates):

• .rat/state/rat-auto-design-state.json — Full pipeline progress (stop-gate)
• .rat/state/rat-auto-design-state.json::orchestration_control — Active gate counters/strategy (N→2N→last-chance) and dynamic prompt payload
• .rat/state/rtl-verify-done — RTL verification completion gate (rtl-verify-stop-gate)
• .rat/state/rtl-verify-waiver — Verification waiver (rtl-verify-stop-gate)
• .rat/state/skill-active.json — Skill completion loop state (rtl-skill-activation, rtl-skill-completion-gate)
• .rat/state/phase6-stale — Phase 6 cascade marker (rtl-edit-tracker, rtl-p6-cascade-gate)
• .rat/state/phase6-cascade-done — Phase 6 cascade completion (rtl-p6-cascade-gate)
• .rat/state/rtl-modified-files.txt — Modified RTL file tracking (rtl-edit-tracker, rtl-verify-stop-gate)

Agent-managed (orchestrator resumability):

• .rat/state/rat-p1p3-spec-uarch-state.json — Spec-to-μArch pipeline progress
• .rat/state/rat-p4p5-impl-verify-state.json — μArch-to-Verify pipeline progress
• .rat/state/rat-dse-state.json — DSE pipeline progress
• .rat/state/feedback-loop-state.json — Phase 5→4 feedback loop tracking
• .rat/state/{module}-phase-3-complete.json — Per-module Phase 3 completion marker

Templates:

• ${CLAUDE_PLUGIN_ROOT}/skills/rat-auto-design/templates/autopilot-state.json (or skills/rat-auto-design/templates/autopilot-state.json in repo context) — v3.0 state schema with orchestration_control
• ${CLAUDE_PLUGIN_ROOT}/skills/rat-auto-design/templates/escalation-prompts.json (or skills/rat-auto-design/templates/escalation-prompts.json in repo context) — fallback prompt templates for ladder transitions

SessionStart Hook Export (SSOT)

This block is the single source for SessionStart routing injection. scripts/sync_orchestrator_inject.sh copies it into hooks/rtl-orchestrator-inject.sh.

RTL Agent Team — Active Project Rules

Pipeline Rules (Rule 5 hard-enforced; others advisory)

1. No RTL coding without specification (run spec-analyst first) — policy
2. No Testbench without Reference Model — policy
3. No synthesis without RTL code — policy
4. No Formal verification without passing Lint — policy (skill warning)
5. No completion after RTL modification without functional verification (lint alone is insufficient) — HARD (rtl-verify-stop-gate.sh)
6. No Phase 5 without per-module unit tests upon Phase 4 completion + Stream B early verification artifacts — policy (skill warning)
7. Phase 5 FAIL → max 2 Phase 4 feedback loops; escalate to user if exceeded — policy (orchestrator counter)
8. No Phase 6 without Phase 5 PASS (final-compliance.md verdict=PASS required) — policy (skill warning)
9. Phase 7 is exempt — free exploration allowed without pipeline Gate
10. No DC-based PPA optimization without Phase 5 PASS — policy (skill warning)
11. Every PPA-Opt iteration must pass equivalence + smoke before the patch is accepted; on failure, roll back — policy (orchestrator guard)

Iron Requirements Protocol

• Each phase produces iron-requirements.json (binding constraints for downstream) and open-requirements.json (homework for next phase)
• Iron requirements from upper phases MUST NOT be violated
• Authority hierarchy: P1(functional) > P2(architecture) > P3(micro-arch)
• Violation triggers graduated escalation; infeasibility triggers Upstream Challenge with quantitative PPA evidence
• Phase exit requires compliance-checker PASS against all upstream iron

Routing (key patterns → Action Skill)

Always route user intent to Action Skills first. Orchestrators are internal and spawned by skills.

…(truncated)