# avikmaj/soc-dv-agent-stack architecture

> Architecture diagram of the GitHub repository avikmaj/soc-dv-agent-stack, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/avikmaj/soc-dv-agent-stack
- Repository: https://github.com/avikmaj/soc-dv-agent-stack

## Overview

SoC DV Agent Stack is a vendor-neutral set of AI-agent skills and project-local Claude Code/Codex adapters for ASIC and SoC design verification. Engineers provide design specifications, source, and tool evidence; agents produce plans, reviews, closure analyses, and signoff assessments. The optional Cupel layer organizes evidence-gated verification roles and verdicts. The README documents canonical skills, adapters, schemas, templates, and safety tooling; sampled source confirms adapter synchronization, validation, and safe tool execution. Skill internals were not sampled, so skill-to-skill wiring is intentionally omitted.

Main entry points: [`skills`](https://github.com/avikmaj/soc-dv-agent-stack/tree/main/skills) (Canonical Skills), [`skills/spec-to-vplan/SKILL.md`](https://github.com/avikmaj/soc-dv-agent-stack/blob/main/skills/spec-to-vplan/SKILL.md) (Spec Planning), [`skills/coverage-closure/SKILL.md`](https://github.com/avikmaj/soc-dv-agent-stack/blob/main/skills/coverage-closure/SKILL.md) (Coverage Closure), [`skills/regression-triage/SKILL.md`](https://github.com/avikmaj/soc-dv-agent-stack/blob/main/skills/regression-triage/SKILL.md) (Regression Triage)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Agent Access"]
  node_claude["Claude Adapter<br/>[skills]"]
  node_codex["Codex Adapter<br/>[skills]"]
  node_canonical["Canonical Skills"]
end

subgraph group_skills["DV Workflows"]
  node_specplan["Spec Planning<br/>[SKILL.md]"]
  node_designreview["Design Review<br/>[SKILL.md]"]
  node_uvm["UVM Architecture<br/>[SKILL.md]"]
  node_integration["Integration Verification<br/>[SKILL.md]"]
  node_formal["Formal And CDC<br/>[SKILL.md]"]
  node_lowpower["Low Power<br/>[SKILL.md]"]
  node_coverage["Coverage Closure<br/>[SKILL.md]"]
  node_regression["Regression Triage<br/>[SKILL.md]"]
  node_signoff["Signoff Audit<br/>[SKILL.md]"]
end

subgraph group_artifacts["Evidence Artifacts"]
  node_schemas["Artifact Schemas"]
  node_templates["Artifact Templates"]
  node_toolrunner["Safe Tool Runner<br/>[run_tool.py]"]
end

subgraph group_cupel["Cupel Organisation"]
  node_cupelentry["Case Marshal<br/>[case-marshal.md]"]
  node_departments["Review Departments"]
  node_vault["Evidence Vault<br/>[evidence-vault.md]"]
  node_challenge["Challenge Chamber"]
  node_verdict["Final Verdict"]
end

node_engineer(("DV Engineer"))
node_projecttools(("Project DV Tools"))

node_engineer -->|"invokes"| node_claude
node_engineer -->|"invokes"| node_codex
node_claude -->|"adapts"| node_canonical
node_codex -->|"adapts"| node_canonical
node_canonical -->|"provides skill"| node_specplan
node_canonical -->|"provides skill"| node_designreview
node_canonical -->|"provides skill"| node_uvm
node_canonical -->|"provides skill"| node_integration
node_canonical -->|"provides skill"| node_formal
node_canonical -->|"provides skill"| node_lowpower
node_canonical -->|"provides skill"| node_coverage
node_canonical -->|"provides skill"| node_regression
node_canonical -->|"provides skill"| node_signoff
node_engineer -->|"submits specification"| node_specplan
node_engineer -->|"submits design"| node_designreview
node_specplan -->|"uses contracts"| node_schemas
node_specplan -->|"uses examples"| node_templates
node_toolrunner -->|"executes approved"| node_projecttools
node_engineer -->|"requests run"| node_toolrunner
node_projecttools -->|"returns evidence"| node_regression
node_projecttools -->|"returns reports"| node_coverage
node_coverage -->|"informs assessment"| node_signoff
node_regression -->|"informs assessment"| node_signoff
node_engineer -.->|"invokes optionally"| node_cupelentry
node_cupelentry -.->|"routes review"| node_departments
node_departments -.->|"registers evidence"| node_vault
node_vault -.->|"mints records"| node_challenge
node_challenge -.->|"issues verdict"| node_verdict

click node_claude "https://github.com/avikmaj/soc-dv-agent-stack/tree/main/.claude/skills"
click node_codex "https://github.com/avikmaj/soc-dv-agent-stack/tree/main/.agents/skills"
click node_canonical "https://github.com/avikmaj/soc-dv-agent-stack/tree/main/skills"
click node_specplan "https://github.com/avikmaj/soc-dv-agent-stack/blob/main/skills/spec-to-vplan/SKILL.md"
click node_designreview "https://github.com/avikmaj/soc-dv-agent-stack/blob/main/skills/rtl-design-review/SKILL.md"
click node_uvm "https://github.com/avikmaj/soc-dv-agent-stack/blob/main/skills/uvm-env-architect/SKILL.md"
click node_integration "https://github.com/avikmaj/soc-dv-agent-stack/blob/main/skills/soc-integration-verification/SKILL.md"
click node_formal "https://github.com/avikmaj/soc-dv-agent-stack/blob/main/skills/formal-sva/SKILL.md"
click node_lowpower "https://github.com/avikmaj/soc-dv-agent-stack/blob/main/skills/low-power-upf/SKILL.md"
click node_coverage "https://github.com/avikmaj/soc-dv-agent-stack/blob/main/skills/coverage-closure/SKILL.md"
click node_regression "https://github.com/avikmaj/soc-dv-agent-stack/blob/main/skills/regression-triage/SKILL.md"
click node_signoff "https://github.com/avikmaj/soc-dv-agent-stack/blob/main/skills/signoff-audit/SKILL.md"
click node_schemas "https://github.com/avikmaj/soc-dv-agent-stack/tree/main/schemas"
click node_templates "https://github.com/avikmaj/soc-dv-agent-stack/tree/main/templates"
click node_toolrunner "https://github.com/avikmaj/soc-dv-agent-stack/blob/main/scripts/run_tool.py"
click node_cupelentry "https://github.com/avikmaj/soc-dv-agent-stack/blob/main/orgs/cupel/agents/case-marshal.md"
click node_departments "https://github.com/avikmaj/soc-dv-agent-stack/tree/main/orgs/cupel/agents"
click node_vault "https://github.com/avikmaj/soc-dv-agent-stack/blob/main/orgs/cupel/agents/evidence-vault.md"
click node_challenge "https://github.com/avikmaj/soc-dv-agent-stack/blob/main/orgs/cupel/agents/challenge-chamber.md"
click node_verdict "https://github.com/avikmaj/soc-dv-agent-stack/blob/main/orgs/cupel/schemas/final-verdict.schema.json"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_claude,node_codex,node_canonical toneBlue
class node_specplan,node_designreview,node_uvm,node_integration,node_formal,node_lowpower,node_coverage,node_regression,node_signoff toneAmber
class node_schemas,node_templates,node_toolrunner toneMint
class node_cupelentry,node_departments,node_vault,node_challenge,node_verdict toneRose
class node_engineer,node_projecttools toneIndigo
```

## Components

### Agent Access

- [Claude Adapter](https://github.com/avikmaj/soc-dv-agent-stack/tree/main/.claude/skills): `.claude/skills`
- [Codex Adapter](https://github.com/avikmaj/soc-dv-agent-stack/tree/main/.agents/skills): `.agents/skills`
- [Canonical Skills](https://github.com/avikmaj/soc-dv-agent-stack/tree/main/skills): `skills`

### DV Workflows

- [Spec Planning](https://github.com/avikmaj/soc-dv-agent-stack/blob/main/skills/spec-to-vplan/SKILL.md): `skills/spec-to-vplan/SKILL.md`
- [Design Review](https://github.com/avikmaj/soc-dv-agent-stack/blob/main/skills/rtl-design-review/SKILL.md): `skills/rtl-design-review/SKILL.md`
- [UVM Architecture](https://github.com/avikmaj/soc-dv-agent-stack/blob/main/skills/uvm-env-architect/SKILL.md): `skills/uvm-env-architect/SKILL.md`
- [Integration Verification](https://github.com/avikmaj/soc-dv-agent-stack/blob/main/skills/soc-integration-verification/SKILL.md): `skills/soc-integration-verification/SKILL.md`
- [Formal And CDC](https://github.com/avikmaj/soc-dv-agent-stack/blob/main/skills/formal-sva/SKILL.md): `skills/formal-sva/SKILL.md`
- [Low Power](https://github.com/avikmaj/soc-dv-agent-stack/blob/main/skills/low-power-upf/SKILL.md): `skills/low-power-upf/SKILL.md`
- [Coverage Closure](https://github.com/avikmaj/soc-dv-agent-stack/blob/main/skills/coverage-closure/SKILL.md): `skills/coverage-closure/SKILL.md`
- [Regression Triage](https://github.com/avikmaj/soc-dv-agent-stack/blob/main/skills/regression-triage/SKILL.md): `skills/regression-triage/SKILL.md`
- [Signoff Audit](https://github.com/avikmaj/soc-dv-agent-stack/blob/main/skills/signoff-audit/SKILL.md): `skills/signoff-audit/SKILL.md`

### Evidence Artifacts

- [Artifact Schemas](https://github.com/avikmaj/soc-dv-agent-stack/tree/main/schemas): `schemas`
- [Artifact Templates](https://github.com/avikmaj/soc-dv-agent-stack/tree/main/templates): `templates`
- [Safe Tool Runner](https://github.com/avikmaj/soc-dv-agent-stack/blob/main/scripts/run_tool.py): `scripts/run_tool.py`

### Cupel Organisation

- [Case Marshal](https://github.com/avikmaj/soc-dv-agent-stack/blob/main/orgs/cupel/agents/case-marshal.md): `orgs/cupel/agents/case-marshal.md`
- [Review Departments](https://github.com/avikmaj/soc-dv-agent-stack/tree/main/orgs/cupel/agents): `orgs/cupel/agents`
- [Evidence Vault](https://github.com/avikmaj/soc-dv-agent-stack/blob/main/orgs/cupel/agents/evidence-vault.md): `orgs/cupel/agents/evidence-vault.md`
- [Challenge Chamber](https://github.com/avikmaj/soc-dv-agent-stack/blob/main/orgs/cupel/agents/challenge-chamber.md): `orgs/cupel/agents/challenge-chamber.md`
- [Final Verdict](https://github.com/avikmaj/soc-dv-agent-stack/blob/main/orgs/cupel/schemas/final-verdict.schema.json): `orgs/cupel/schemas/final-verdict.schema.json`

### Other components

- **DV Engineer**
- **Project DV Tools**

## Connections

- DV Engineer → Claude Adapter: invokes
- DV Engineer → Codex Adapter: invokes
- Claude Adapter → Canonical Skills: adapts
- Codex Adapter → Canonical Skills: adapts
- Canonical Skills → Spec Planning: provides skill
- Canonical Skills → Design Review: provides skill
- Canonical Skills → UVM Architecture: provides skill
- Canonical Skills → Integration Verification: provides skill
- Canonical Skills → Formal And CDC: provides skill
- Canonical Skills → Low Power: provides skill
- Canonical Skills → Coverage Closure: provides skill
- Canonical Skills → Regression Triage: provides skill
- Canonical Skills → Signoff Audit: provides skill
- DV Engineer → Spec Planning: submits specification
- DV Engineer → Design Review: submits design
- Spec Planning → Artifact Schemas: uses contracts
- Spec Planning → Artifact Templates: uses examples
- Safe Tool Runner → Project DV Tools: executes approved
- DV Engineer → Safe Tool Runner: requests run
- Project DV Tools → Regression Triage: returns evidence
- Project DV Tools → Coverage Closure: returns reports
- Coverage Closure → Signoff Audit: informs assessment
- Regression Triage → Signoff Audit: informs assessment
- DV Engineer → Case Marshal: invokes optionally
- Case Marshal → Review Departments: routes review
- Review Departments → Evidence Vault: registers evidence
- Evidence Vault → Challenge Chamber: mints records
- Challenge Chamber → Final Verdict: issues verdict