@huaqiu/hqeda 0.1.1

package/guides/bom-review.md

@@ -0,0 +1,49 @@
+# BOM Review Guidance
+
+## Objective
+
+Identify high-risk components, lifecycle issues, duplicate parts, and
+manufacturing inconsistencies before sending the design to production.
+
+## Execution Flow
+
+1. Invoke capability `bom-get-bom` to retrieve the active project BOM.
+2. For each line item, evaluate against the checklist rules:
+   - Verify if any part is marked as **DNP** (Do Not Populate) but lacks
+     designator annotation.
+   - Flag missing Manufacturer Part Numbers (MPN).
+   - Detect duplicate MPNs assigned to differing PCB package footprints.
+   - Highlight lifecycle risks (e.g., EOL, NRND).
+3. Format output findings strictly according to the reporting template in
+   `prompts/reporting-template.md`.
+
+## Required Capabilities
+
+| Capability | Purpose |
+| --- | --- |
+| `bom-get-bom` | Retrieve the full BOM snapshot from the schematic. |
+| `project-get-active-project` | Resolve the active project context. |
+
+## Critical Guardrails
+
+- **Never** automatically alter component parameters or delete findings.
+- Group all findings by severity: `CRITICAL`, `WARNING`, `INFO`.
+- Reference exact component designators (e.g. `C12`, `R5`) in every finding.
+- A BOM row with zero references is always a `CRITICAL` finding — it indicates
+  an orphaned part entry that has no placement on the board.
+
+## Output Format
+
+```
+## BOM Review Report
+
+### CRITICAL
+- [bom-2] Duplicate MPN `XXX` on differing footprints: R5 (0603) vs R6 (0805)
+
+### WARNING
+- [bom-1] Row 14 has no designator assigned
+- [bom-4] Part `ABC123` is marked EOL
+
+### INFO
+- [bom-3] DNP part C8 lacks explicit annotation
+```

package/guides/erc-review.md

@@ -0,0 +1,48 @@
+# ERC Review Guidance
+
+## Objective
+
+Run the Electrical Rules Check (ERC), classify every finding by severity, and
+drive the resolution workflow end-to-end including canvas highlighting and
+report webview visibility.
+
+## Execution Flow
+
+1. Resolve the active project via `project-get-active-project`.
+2. Invoke `erc-run-checks` to execute the EDA's built-in ERC engine.
+3. Collect all findings from the response; do **not** filter or discard any
+   finding before classification.
+4. Group findings by severity:
+   - **CRITICAL** — blocks production release (e.g., conflicting power
+     drivers, unconnected mandatory pins).
+   - **WARNING** — should be reviewed but may be acceptable (e.g., unused
+     input pins, passive-only nets).
+   - **INFO** — informational (e.g., net naming suggestions, style hints).
+5. Push findings to the canvas via `erc-show-findings` so the user can
+   visually inspect each violation in the EDA view.
+6. Toggle the ERC report webview via `erc-set-erc-report-webview-visibility` so
+   the user sees the summary panel.
+7. After the user addresses a finding, invoke `erc-clear-findings` with the
+   resolved finding ids, then re-run ERC (step 2) to confirm the violation is
+   gone. If a full reset is needed, use `erc-clear-all-findings`.
+
+## Required Capabilities
+
+| Capability | Purpose |
+| --- | --- |
+| `erc-run-checks` | Execute the ERC engine and collect findings. |
+| `erc-show-findings` | Highlight findings on the EDA canvas. |
+| `erc-clear-findings` | Clear specific resolved findings before re-run. |
+| `erc-clear-all-findings` | Clear every finding for a full reset. |
+| `erc-set-erc-report-webview-visibility` | Show/hide the ERC report panel. |
+| `project-get-active-project` | Resolve the active project context. |
+
+## Critical Guardrails
+
+- Never auto-resolve or suppress a CRITICAL finding — surface it to the user.
+- Always re-run ERC after clearing findings to confirm the resolution.
+- When highlighting findings on the canvas, send the full finding list in a
+  single `erc-show-findings` call rather than one call per finding (reduces
+  RPC round-trips and canvas flicker).
+- Reference the exact designator and net name from the finding object in
+  every report line.

package/guides/manufacturing-readiness.md

@@ -0,0 +1,51 @@
+# Manufacturing Readiness Guidance
+
+## Objective
+
+Gate the production release on a combined set of DFM, DRC, and BOM-freeze
+criteria. This playbook combines BOM integrity, ERC cleanliness, and project
+persistence into a single go/no-go gate.
+
+## Execution Flow
+
+1. **BOM integrity gate** — invoke `bom-get-bom` and apply the BOM review
+   checklist (see `guides/bom-review.md`). Any `CRITICAL` BOM finding blocks
+   the gate.
+2. **ERC cleanliness gate** — invoke `erc-run-checks`. If any `CRITICAL`
+   finding is present, the gate fails. Clear all findings via
+   `erc-clear-all-findings`, ask the user to fix the violations, then re-run
+   ERC. The gate passes only when the re-run returns zero `CRITICAL`
+   findings.
+3. **Project persistence gate** — invoke `project-save-project` to ensure the
+   latest schematic state is persisted to disk before generating
+   manufacturing outputs (Gerber, BOM CSV, pick-and-place).
+4. Emit a combined go/no-go report using the reporting template.
+
+## Required Capabilities
+
+| Capability | Purpose |
+| --- | --- |
+| `bom-get-bom` | Retrieve the BOM for the integrity gate. |
+| `erc-run-checks` | Run the ERC engine for the cleanliness gate. |
+| `erc-clear-all-findings` | Reset findings between ERC runs. |
+| `project-get-active-project` | Resolve the active project context. |
+| `project-save-project` | Persist the schematic state before output. |
+
+## Go / No-Go Decision Matrix
+
+| Gate | Fail Condition | Action |
+| --- | --- | --- |
+| BOM integrity | Any `CRITICAL` BOM finding | Block — surface findings to user |
+| ERC cleanliness | Any `CRITICAL` ERC finding | Block — surface findings, clear, re-run |
+| Project persistence | `project-save-project` fails | Block — check file permissions / disk |
+
+All three gates must pass for a **GO** decision.
+
+## Critical Guardrails
+
+- Never skip a gate even if the user insists — manufacturing release is
+  irreversible.
+- Always persist the project (`project-save-project`) as the final step before
+  generating manufacturing outputs.
+- If the user interrupts the gate, leave findings on the canvas for visual
+  inspection; do not auto-clear.

package/guides/schematic-review.md

@@ -0,0 +1,38 @@
+# Schematic Review Guidance
+
+## Objective
+
+Verify net connectivity, power-rail integrity, symbol/footprint consistency,
+and ERC compliance across the schematic before board layout.
+
+## Execution Flow
+
+1. Resolve the active project via `project-get-active-project`.
+2. Retrieve the kernel snapshot via `kernel-get-snapshot` to access the
+   symbol definitions, net list, and connectivity graph.
+3. Walk the net list and evaluate each rule in the checklist:
+   - Every net must have at least two pins connected (dangling-net check).
+   - Power nets must use explicit named labels (not implicit wire joins).
+   - Active-component pins (ICs, transistors) must be connected or explicitly
+     marked No-Connect.
+4. For visual inspection, use `selection-set-selection` to highlight a
+   specific symbol or net on the canvas, then read back the current selection
+   via `selection-get-selection` to confirm the highlight landed.
+
+## Required Capabilities
+
+| Capability | Purpose |
+| --- | --- |
+| `kernel-get-snapshot` | Read the symbol/net graph for static analysis. |
+| `selection-set-selection` | Highlight a symbol/net for visual inspection. |
+| `selection-get-selection` | Confirm the active selection. |
+| `project-get-active-project` | Resolve the active project context. |
+
+## Critical Guardrails
+
+- Do **not** modify the schematic during review — this is a read-only audit.
+- Report findings grouped by severity with the offending designator and net
+  name.
+- An unconnected power pin is always `CRITICAL` regardless of component type.
+- Use exact net names as returned by the kernel snapshot; never fabricate net
+  identifiers.

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@huaqiu/hqeda",
+  "version": "0.1.1",
+  "description": "Official HQ EDA Skill Package — executable SDK capabilities and human-authored review playbooks for Huaqiu EDA engines.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./skill": "./SKILL.md",
+    "./manifest": "./skill.json",
+    "./registry": "./generated/capability-registry.json"
+  },
+  "files": [
+    "SKILL.md",
+    "skill.json",
+    "dist",
+    "generated/capability-registry.json",
+    "playbooks",
+    "guides",
+    "prompts",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@bufbuild/protobuf": "^2.6.3",
+    "@hqedge/connect": "0.1.11",
+    "@huaqiu/huaqiu-client": "0.0.3"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^4.1.10"
+  },
+  "keywords": [
+    "huaqiu",
+    "hqeda",
+    "eda",
+    "skill",
+    "erc",
+    "bom",
+    "pcb",
+    "capability",
+    "connect-rpc"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Huaqiu-Electronics/skills.git",
+    "directory": "hqeda"
+  },
+  "homepage": "https://github.com/Huaqiu-Electronics/skills/tree/main/hqeda",
+  "bugs": {
+    "url": "https://github.com/Huaqiu-Electronics/skills/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "test": "vitest run"
+  }
+}

package/playbooks/bom-review.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "https://schema.huaqiu.com/skills/v1/playbook.schema.json",
+  "id": "playbook-bom-review",
+  "name": "BOM Review Playbook",
+  "version": "1.0.0",
+  "domain": "bom",
+  "description": "Guides the agent through verifying component availability, footprint consistency, lifecycle risks, and assembly variants before production release.",
+  "requiredCapabilities": [
+    "bom-get-bom",
+    "project-get-active-project"
+  ],
+  "outputTemplate": "guides/bom-review.md",
+  "guidanceFile": "guides/bom-review.md",
+  "checklist": {
+    "items": [
+      {
+        "id": "bom-1",
+        "title": "Every BOM line has a designator",
+        "severity": "WARNING",
+        "rule": "Each row in the BOM must have at least one reference designator (e.g. R1, C12). Rows with empty references are flagged."
+      },
+      {
+        "id": "bom-2",
+        "title": "No duplicate MPNs on differing footprints",
+        "severity": "CRITICAL",
+        "rule": "If the same manufacturer part number appears on rows with different footprint/package values, flag as a footprint mismatch."
+      },
+      {
+        "id": "bom-3",
+        "title": "DNP parts are explicitly annotated",
+        "severity": "INFO",
+        "rule": "Components marked Do Not Populate should carry a designator annotation so they are not confused with missing parts."
+      },
+      {
+        "id": "bom-4",
+        "title": "Lifecycle risk check",
+        "severity": "WARNING",
+        "rule": "Flag any part whose lifecycle status is EOL (End of Life) or NRND (Not Recommended for New Designs)."
+      }
+    ]
+  }
+}

package/playbooks/erc-review.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "https://schema.huaqiu.com/skills/v1/playbook.schema.json",
+  "id": "playbook-erc-review",
+  "name": "ERC Review Playbook",
+  "version": "1.0.0",
+  "domain": "erc",
+  "description": "Orchestrates ERC runs, classifies findings by severity, and drives the resolution workflow including canvas highlighting and report visibility.",
+  "requiredCapabilities": [
+    "erc-run-checks",
+    "erc-show-findings",
+    "erc-clear-findings",
+    "erc-clear-all-findings",
+    "erc-set-erc-report-webview-visibility",
+    "project-get-active-project"
+  ],
+  "outputTemplate": "guides/erc-review.md",
+  "guidanceFile": "guides/erc-review.md",
+  "checklist": {
+    "items": [
+      {
+        "id": "erc-1",
+        "title": "Run ERC and collect all findings",
+        "severity": "CRITICAL",
+        "rule": "Invoke erc-run-checks and collect every finding returned. Do not filter or discard findings before classification."
+      },
+      {
+        "id": "erc-2",
+        "title": "Classify findings by severity",
+        "severity": "WARNING",
+        "rule": "Group findings into CRITICAL, WARNING, INFO. CRITICAL findings block production release."
+      },
+      {
+        "id": "erc-3",
+        "title": "Highlight findings on canvas",
+        "severity": "INFO",
+        "rule": "Use erc-show-findings to push findings to the EDA canvas so the user can visually inspect each violation."
+      },
+      {
+        "id": "erc-4",
+        "title": "Clear resolved findings after re-run",
+        "severity": "INFO",
+        "rule": "After the user addresses a finding, invoke erc-clear-findings with the resolved finding ids, then re-run ERC to confirm."
+      }
+    ]
+  }
+}

package/playbooks/manufacturing-review.json

@@ -0,0 +1,45 @@
+{
+  "$schema": "https://schema.huaqiu.com/skills/v1/playbook.schema.json",
+  "id": "playbook-manufacturing-review",
+  "name": "Manufacturing Readiness Playbook",
+  "version": "1.0.0",
+  "domain": "manufacturing",
+  "description": "Gates production release on DFM, DRC, and BOM freeze criteria. Combines BOM integrity, ERC cleanliness, and project persistence checks into a single go/no-go gate.",
+  "requiredCapabilities": [
+    "bom-get-bom",
+    "erc-run-checks",
+    "erc-clear-all-findings",
+    "project-get-active-project",
+    "project-save-project"
+  ],
+  "outputTemplate": "guides/manufacturing-readiness.md",
+  "guidanceFile": "guides/manufacturing-readiness.md",
+  "checklist": {
+    "items": [
+      {
+        "id": "mfg-1",
+        "title": "BOM is complete and frozen",
+        "severity": "CRITICAL",
+        "rule": "BOM must have no empty designators, no duplicate MPNs on differing footprints, and all parts must have valid MPNs."
+      },
+      {
+        "id": "mfg-2",
+        "title": "ERC has zero CRITICAL findings",
+        "severity": "CRITICAL",
+        "rule": "Run erc-run-checks; if any CRITICAL finding is present, the gate fails. Clear all findings and re-run to confirm."
+      },
+      {
+        "id": "mfg-3",
+        "title": "Project is saved and persisted",
+        "severity": "WARNING",
+        "rule": "Invoke project-save-project to ensure the latest schematic state is persisted before generating manufacturing outputs."
+      },
+      {
+        "id": "mfg-4",
+        "title": "Designator coverage",
+        "severity": "INFO",
+        "rule": "Every component in the BOM should have a unique designator. Duplicate or missing designators are flagged for review."
+      }
+    ]
+  }
+}

package/playbooks/schematic-review.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "https://schema.huaqiu.com/skills/v1/playbook.schema.json",
+  "id": "playbook-schematic-review",
+  "name": "Schematic Review Playbook",
+  "version": "1.0.0",
+  "domain": "schematic",
+  "description": "Checks net connectivity, power-rail integrity, symbol/footprint consistency, and ERC compliance across the schematic.",
+  "requiredCapabilities": [
+    "kernel-get-snapshot",
+    "selection-set-selection",
+    "selection-get-selection",
+    "project-get-active-project"
+  ],
+  "outputTemplate": "guides/schematic-review.md",
+  "guidanceFile": "guides/schematic-review.md",
+  "checklist": {
+    "items": [
+      {
+        "id": "sch-1",
+        "title": "All nets have at least two connections",
+        "severity": "WARNING",
+        "rule": "A net with only one connection is a dangling net and should be reviewed."
+      },
+      {
+        "id": "sch-2",
+        "title": "Power rails are explicitly named",
+        "severity": "INFO",
+        "rule": "Power nets (VCC, GND, 3V3, etc.) should use named labels rather than implicit wire connections."
+      },
+      {
+        "id": "sch-3",
+        "title": "No unconnected pins on active components",
+        "severity": "CRITICAL",
+        "rule": "Every pin on an active component (IC, transistor) must be either connected or explicitly marked No-Connect."
+      },
+      {
+        "id": "sch-4",
+        "title": "Symbol footprint matches BOM package",
+        "severity": "WARNING",
+        "rule": "The footprint assigned to each symbol must match the package declared in the BOM for the same designator."
+      }
+    ]
+  }
+}

package/prompts/reporting-template.md

@@ -0,0 +1,45 @@
+# Reporting Template
+
+Use this template verbatim for every review report. Replace the bracketed
+placeholders with actual data. Do not remove sections even if empty — emit
+`_(none)_` instead.
+
+```markdown
+## <Review Name> Report
+
+**Project:** <project-id>
+**Generated:** <ISO-8601 timestamp>
+**ERC run count:** <n>
+
+### CRITICAL
+
+<list of critical findings, or "_none_">
+
+### WARNING
+
+<list of warnings, or "_none_">
+
+### INFO
+
+<list of informational notes, or "_none_">
+
+### Summary
+
+- Total findings: <n>
+- Critical: <n>
+- Warnings: <n>
+- Info: <n>
+
+### Recommendations
+
+<optional, ordered list of suggested next steps — only if findings exist>
+```
+
+## Rules
+
+1. The `CRITICAL` section appears first, always.
+2. Within each section, sort findings by designator (alphanumeric).
+3. The `Summary` counts must match the findings listed above.
+4. The `Recommendations` section is omitted entirely when there are zero
+   findings.
+5. Timestamps use the ISO-8601 format (`2026-07-17T12:34:56Z`).

package/prompts/review-style.md

@@ -0,0 +1,41 @@
+# Review Style Guide
+
+## Tone
+
+- **Direct and technical.** The audience is a hardware engineer reviewing a
+  schematic — avoid hedging or marketing language.
+- **Evidence-first.** Every finding must cite the designator, net name, or
+  rule id that triggered it. Never state "this might be wrong" without naming
+  the exact component and the violated rule.
+
+## Severity Definitions
+
+| Severity | Meaning | Blocks production? |
+| --- | --- | --- |
+| `CRITICAL` | Electrical safety or functionality risk. | Yes |
+| `WARNING` | Likely a problem; user should review. | No |
+| `INFO` | Suggestion or style note. | No |
+
+## Finding Format
+
+Every finding line MUST follow this shape:
+
+```
+- [rule-id] <component designator or net name>: <one-line description>
+```
+
+Examples:
+```
+- [erc-1] U3 pin 14 (VDD): unconnected power pin
+- [bom-2] R5/R6: duplicate MPN ABC123 on differing footprints (0603 vs 0805)
+- [sch-2] VCC: power rail uses implicit wire join, expected named label
+```
+
+## Forbidden Patterns
+
+- Do **not** use first-person voice ("I think", "I found").
+- Do **not** propose fixes in the findings list — fixes belong in a separate
+  "Recommendations" section.
+- Do **not** reference capability ids in user-facing findings — the user sees
+  designators and net names, not skill ids.
+- Do **not** group by capability; group by severity, then by designator.

package/skill.json

@@ -0,0 +1,132 @@
+{
+  "$schema": "https://schema.huaqiu.com/skills/v1/skill.schema.json",
+  "id": "hqeda",
+  "name": "HQ EDA Official Skill",
+  "vendor": "Huaqiu Electronics",
+  "version": "0.1.0",
+  "description": "Executable capabilities and review playbooks for HQ EDA.",
+  "skillMarkdown": "./SKILL.md",
+  "entry": "./dist/index.js",
+  "capabilities": [
+    "ai-execute-prompt",
+    "bom-get-bom",
+    "canvas-align-objects",
+    "canvas-can-paste",
+    "canvas-clear-all-sel",
+    "canvas-copy-selected",
+    "canvas-delete-selected",
+    "canvas-distribute-objects",
+    "canvas-get-align-type",
+    "canvas-get-selected-object-json",
+    "canvas-get-selected-objects-json",
+    "canvas-mirror-objects",
+    "canvas-move-selected-objs",
+    "canvas-on-canvas-escape",
+    "canvas-pan-canvas",
+    "canvas-paste-selected",
+    "canvas-rotate-objects",
+    "canvas-screen-to-canvas-local",
+    "canvas-select-all",
+    "canvas-select-object-at",
+    "canvas-set-align-type",
+    "canvas-set-page-size",
+    "canvas-set-page-size-rect",
+    "canvas-zoom-all",
+    "canvas-zoom-area-by-double-box",
+    "canvas-zoom-area-by-int-box",
+    "canvas-zoom-area-by-points",
+    "canvas-zoom-in",
+    "canvas-zoom-out",
+    "canvas-zoom-selected",
+    "capability-get-capabilities",
+    "context-get-context",
+    "discovery-get-server-info",
+    "erc-clear-all-findings",
+    "erc-clear-findings",
+    "erc-run-checks",
+    "erc-set-erc-report-webview-visibility",
+    "erc-set-report-webview-state",
+    "erc-show-findings",
+    "event-subscribe",
+    "export-export-bom",
+    "export-export-target",
+    "graph-get-connectivity",
+    "graph-query-graph",
+    "import-import-design",
+    "kernel-get-entity",
+    "kernel-get-snapshot",
+    "obj-place-add-bus-segment",
+    "obj-place-add-ellipse",
+    "obj-place-add-free-line-segment",
+    "obj-place-add-line",
+    "obj-place-add-rect",
+    "obj-place-add-wire-segment",
+    "obj-place-cancel-bus-draw",
+    "obj-place-cancel-ellipse-arc-draw",
+    "obj-place-cancel-ellipse-draw",
+    "obj-place-cancel-free-line-draw",
+    "obj-place-cancel-line-draw",
+    "obj-place-cancel-rect-draw",
+    "obj-place-cancel-wire-draw",
+    "obj-place-handle-bus-draw-click",
+    "obj-place-handle-ellipse-arc-draw-click",
+    "obj-place-handle-ellipse-draw-click",
+    "obj-place-handle-free-line-draw-click",
+    "obj-place-handle-image-draw-click",
+    "obj-place-handle-line-draw-click",
+    "obj-place-handle-net-alias-draw-click",
+    "obj-place-handle-rect-draw-click",
+    "obj-place-handle-table-draw-click",
+    "obj-place-handle-text-draw-click",
+    "obj-place-handle-wire-draw-click",
+    "obj-place-place-bus",
+    "obj-place-place-ellipse",
+    "obj-place-place-ellipse-arc",
+    "obj-place-place-ellipse-arc-from-virtual",
+    "obj-place-place-free-line",
+    "obj-place-place-image",
+    "obj-place-place-line",
+    "obj-place-place-net-alias",
+    "obj-place-place-rect",
+    "obj-place-place-table",
+    "obj-place-place-table-from-virtual",
+    "obj-place-place-text",
+    "obj-place-place-text-from-virtual",
+    "obj-place-place-wire",
+    "placement-cancel-block-draw",
+    "placement-clear-net-alias-attach-obj",
+    "placement-handle-block-draw-click",
+    "placement-handle-part-draw-click",
+    "placement-handle-symbol-draw-click",
+    "placement-place-block",
+    "placement-place-part",
+    "placement-place-symbol",
+    "placement-set-net-alias-attach-obj",
+    "project-close-project",
+    "project-get-active-project",
+    "project-get-project",
+    "project-list-open-projects",
+    "project-open-project",
+    "project-save-project",
+    "runtime-execute-commands",
+    "runtime-validate-commands",
+    "selection-clear-selection",
+    "selection-get-selection",
+    "selection-set-selection",
+    "transaction-commit",
+    "transaction-open",
+    "transaction-redo",
+    "transaction-rollback",
+    "transaction-undo"
+  ],
+  "playbooks": [
+    "playbooks/bom-review.json",
+    "playbooks/schematic-review.json",
+    "playbooks/erc-review.json",
+    "playbooks/manufacturing-review.json"
+  ],
+  "resources": {
+    "guides": "./guides",
+    "prompts": "./prompts"
+  }
+}