AGENT SKILL

vhl-concepts

Architectural foundation for Virtual Hardware Laboratory (VHL). Explains the four fundamental VHL concepts (Module vs Assembly, Interface Boundary, Git Worktree Workspace Isolation, and Shared Circuit Understanding Document), why VHL uses them, their core invariants, and when an agent must reason about them. Trigger this skill whenever reasoning about VHL architecture, defining boundaries, identifying module/assembly scope, or referencing SCUD artifacts.

License 许可
GPL-2.0
最近更新
2026-08-23
Stars
★ 0
Forks
0

01 前言 Front Matter

name
vhl-concepts
description
Architectural foundation for Virtual Hardware Laboratory (VHL). Explains the four fundamental VHL concepts (Module vs Assembly, Interface Boundary, Git Worktree Workspace Isolation, and Shared Circuit Understanding Document), why VHL uses them, their core invariants, and when an agent must reason about them. Trigger this skill whenever reasoning about VHL architecture, defining boundaries, identifying module/assembly scope, or referencing SCUD artifacts.

02 资源文件 8

03 SKILL.md 正文

VHL Concepts

This skill provides the architectural model, core invariants, and progressive-disclosure mapping for the four fundamental concepts in the Virtual Hardware Laboratory (VHL): Module vs Assembly, Interface Boundary, Git Worktree Workspace, and Shared Circuit Understanding Document (SCUD).


1. Architectural Principle & Knowledge Tiers

VHL separates engineering knowledge into three distinct, decoupled tiers:

VHL Concepts
    = What things are and why they exist (Architectural definitions & invariants)

Engineering Methodologies
    = How engineering reasoning is performed using those concepts

Engineering Workflows
    = How specific multi-step VHL tasks are executed

This ECP focuses strictly on VHL Concepts. It teaches an agent to recognize and reason about these foundational concepts and their constraints. Detailed operational procedures, multi-step reconciliation logic, task workflows, and automated verification pipelines are progressively disclosed through referenced Methodologies and Workflows.


2. Core VHL Concepts

2.1 Module & Assembly

What it means

VHL partitions every hardware design into a two-tier structural hierarchy:

  • Module: A self-contained, isolated functional building block (e.g., power supply, microcontroller block, battery monitor).
    • Sub-units: Discrete electronic components, ICs, passives, and semiconductors.
    • Scope: Resides in a dedicated module Git branch and isolated Git worktree workspace.
  • Assembly: A top-level integration circuit that connects modules through their interface boundaries to achieve system-level functionality and define board physical layout.
    • Sub-units: Hardware Modules (not raw loose discrete components).
    • Scope: Resides in the root Git worktree (main/master branch).

Why VHL uses it

  • Decoupling: Splits complex multi-domain hardware designs into manageable, independent sub-problems.
  • Parallel Agent Execution: Enables isolated development by dedicated agent teams without cross-module interference.
  • Domain Separation: Distinguishes internal schematic implementation (Module) from top-level interconnect and layout (Assembly).

Fundamental invariants / constraints

  1. Sub-unit Hierarchy Invariant: Sub-units of a Module are discrete components/ICs; sub-units of an Assembly are Modules. Assemblies do not contain raw loose components unless required for top-level interconnect logic.
  2. Workspace Isolation Invariant: Each Module MUST operate inside its own dedicated Git worktree and branch. Assemblies MUST operate in the root worktree.
  3. Agent Ownership: A Module is owned by a Module Archy agent; an Assembly is owned by the System Archy agent.

When an agent needs to think about it

  • When assigned a design task, to determine whether the task scope is a single functional sub-block (Module) or top-level integration (Assembly).
  • When structuring circuit code (.tsx) or determining component vs. module instantiation.

Progressive-disclosure references


2.2 Interface Boundary

What it means

An Interface Boundary is a formal, black-box contract that defines and constrains how a hardware module interacts with other modules and the external environment.

Every boundary explicitly articulates 4 Pillars:

  1. Consumes: Required input resources, supply voltages, reference clocks, and incoming signals.
  2. Produces: Output resources, regulated power rails, telemetry, and status signals generated for external consumption.
  3. Enforces: Spatial, electrical, and mechanical constraints (e.g., maximum voltage ripple, differential impedance, isolation barriers, operating temperature limits).
  4. Functional Contract: Black-box behavioral transformation definition (what the module does, independent of internal schematic implementation).

VHL distinguishes between Module Boundaries (owned by Module Archy) and System Boundaries (owned by System Archy).

Why VHL uses it

  • Contractual Autonomy: Serves as an absolute contract between independent modules, enabling asynchronous development.
  • Verifiable Interconnect: Allows downstream synthesis, validation, and layout tools to verify compatibility without inspecting internal module implementation details.
  • Boundary Encapsulation: Prevents scope creep and uncontrolled inter-module signal pollution.

Fundamental invariants / constraints

  1. Signal Encapsulation Invariant: Internal feedback nodes, current-sense feedback loops, and local bias nets MUST remain encapsulated inside the module and MUST NOT be exposed on the module boundary.
  2. Structural Phase Enforcement Invariant: Boundary contracts MUST be enforced deterministically through runtime verification gates and artifact checks, not by relying on LLM agent cognitive discipline.
  3. Contract Completeness: Every signal or power rail entering or leaving a module MUST belong to an explicit boundary port declared under Consumes or Produces.

When an agent needs to think about it

  • When defining a module specification or establishing interface contracts between modules.
  • When evaluating whether a proposed schematic change alters external pinouts or electrical constraints.
  • When validating system-level electrical compatibility across module interfaces.

Progressive-disclosure references


2.3 Git Worktree / Workspace Isolation

What it means

In VHL:

  • The central repository acts as the shared object database and single source of truth(the trunk branch/worktree).
  • Each agent operates in a dedicated workspace provisioned as a Git worktree linked to a specific feature branch.

Why VHL uses it

  • Performance & Disk Efficiency: Worktree creation is instantaneous and avoids full filesystem cloning (shutil.copytree), sharing a single .git object database.
  • Native Versioning & Auditability: Agent progression is recorded via standard Git commits, providing clear auditability and standard merge capabilities.
  • Context Protection: Prevents concurrent agents working on different modules from overwriting each other's workspace files.

Fundamental invariants / constraints

  1. Single Repository Anchor: All agent worktrees MUST originate from the central project repository object database (.git).
  2. Workspace-Branch One-to-One Binding: Each active worktree MUST be bound to a distinct Git branch corresponding to its target module.
  3. Deterministic Persistence: Progress MUST be saved using Git commits (git commit), mapping state snapshots directly to Git history.

When an agent needs to think about it

  • When initializing an agent session or context, to ensure execution occurs within the designated worktree.
  • When committing state iterations or preparing module branches for merging into the assembly.

Progressive-disclosure references


2.4 Shared Circuit Understanding Document (SCUD)

What it means

The Shared Circuit Understanding Document (SCUD) is the canonical, human- and LLM-readable representation of VHL's current understanding of a circuit.

It serves as a semantic anchor and single source of interpreted circuit intent between agents.

SCUD is structured into 5 mandatory sections:

  1. Module Overview & System Context
  2. Components Inventory
  3. Connectivity & Signal Flow
  4. Uncertainties, Assumptions & Confidence
  5. Library Mapping

Why VHL uses it

  • Intent Bridge: Connects high-level architectural specifications to low-level executable code (.tsx).
  • Uncertainty Visibility: Prevents silent assumptions by explicitly recording incomplete knowledge, confidence levels, and engineering assumptions.
  • Incremental Refinement: Provides a human-auditable intermediate representation of design intent that evolves incrementally as new evidence becomes available.

Fundamental invariants / constraints

  1. Semantic, Not Formal: SCUD describes functional intent and understanding. SCUD is NOT a netlist, circuit graph, layout file, or executable code.
  2. No Silent Inference: Ambiguities and missing documentation MUST NOT be resolved through silent agent guessing; they MUST remain explicitly logged in Section 4 (Uncertainties, Assumptions & Confidence).
  3. Evidence-Based Traceability: Every statement in SCUD must be traceable to available evidence (boundary specs, datasheets, reference designs, or explicit engineering decisions).
  4. Document Status Protocol (IN_PROGRESS): If incomplete data or unresolved ambiguities block SCUD completion, the token IN_PROGRESS MUST be appended as a standalone line at the end of the file.

When an agent needs to think about it

  • When parsing reference schematics or specifications to extract circuit intent.
  • When transferring circuit understanding to downstream synthesis agents (e.g., ANA).
  • When recording engineering decisions, component choices, or uncertainties.

Progressive-disclosure references


3. Workflow & Operational Execution (Progressive Disclosure)

VHL operationalizes its core concepts through specialized Engineering Workflows and Artifact Methodologies. When an agent transitions from conceptual reasoning to task execution, it defers to these specific capability packages:

  • Single-Module Design Lifecycle: To provision a Git worktree, extract SCUD intent, prepare component libraries, and synthesize module code, consult the Module Synthesis Workflow.

  • Top-Level System Composition: To integrate module branches into the root worktree, synthesize top-level interconnects, and coordinate placement, consult the Assembly Integration Workflow.

  • SCUD Extraction & Intent Drafting: To draft, structure, and incrementally refine a 5-section SCUD artifact from evidence documents, consult the SCUD Creation Methodology & Guidelines.

  • Boundary Alignment & Reconciliation: To validate cross-module interface contracts and perform atomic multi-artifact reconciliation passes, consult the Boundary Alignment Document and Boundary Reconciliation Methodology.


4. Conceptual Integrity

The four concepts impose invariants that must remain true:

  • Module/Assembly hierarchy remains valid.
  • Module boundaries do not expose internal signals.
  • Module workspace remains isolated from other module workspaces.
  • SCUD remains a semantic representation rather than executable/formal circuit representation.

Detailed verification procedures are delegated to the relevant methodologies and validation workflows.

04 同仓库更多 Skills