@huaqiu/dsh-kicad 0.4.12 → 0.5.1

package/README.md

@@ -1,20 +1,29 @@
 # @huaqiu/dsh-kicad
 
 KiCad agent capabilities for DeepSeek Harness, shipped as **one** DSH plugin: the
-executable KiCad tools *and* the `kicad-ipc` skill that teaches the agent how to use
-them. Installing the Huaqiu DSH PCB/EDA bundle makes both available out of the box —
+executable KiCad tools *and* the bundled skills that teach the agent how to use them.
+Installing the Huaqiu DSH PCB/EDA bundle makes both available out of the box —
 there is no separate skill installation step.
 
-Migrated from the standalone `kicad-agent` repository.
+Migrated from the standalone `kicad-agent` repository, which now tracks this package: its
+`skills/` tree is kept **byte-identical** to the one below, so picking up an upstream
+change is a plain `cp -r` and never a merge. A local test asserts that lockstep.
 
 ## What you get
 
 ```
 @huaqiu/dsh-kicad
 ├── Tools     10 KiCad tools, registered with ctx.tools.register(defineTool(...))
-└── Skills    kicad-ipc — SKILL.md + references/ + 11 python script templates
+└── Skills    every skill under skills/, registered with ctx.skills.register(...)
+              ├── kicad-ipc               SKILL.md + references/ + 11 python script templates
+              └── hardware-design-brief   SKILL.md + 3 reference guides
 ```
 
+The skill set is data, not code: `src/skills.ts` is the registry, so adding a skill
+from `kicad-agent` is a directory copy plus one registry entry. There is no rename and no
+translation step — upstream agrees with this package on directory names, skill ids and
+language. Exactly one skill (`kicad-ipc`) owns the Python templates the tools execute.
+
 ### Tools
 
 | Tool | Script | Effect |
@@ -43,17 +52,32 @@ retry), `UNAVAILABLE` (KiCad unreachable — retry once after checking the envir
 `DEADLINE_EXCEEDED` (timed out), `INVALID_ARGUMENT` (board untouched), `INTERNAL`
 (script failed; the commit was dropped).
 
-### Skill
+### Skills
+
+Every directory under `skills/` is registered as a DSH skill, so one installation
+delivers the operating guidance along with the tools. Each is progressive-disclosure:
+the agent reads `SKILL.md` first and opens `references/` only when the task needs it.
+
+**`skills/kicad-ipc/`** — how to operate KiCad: when to use it, how to inspect current
+state, how to verify mutations, and when to stop and ask. It is *not* an IPC API
+specification — the tool schemas are the executable interface, the skill is the
+reasoning around them. Its `references/ipc-pcb-workflows.md` holds version matrices,
+the public CRUD table and failure handling; `scripts/` holds the runnable templates
+the tools execute.
+
+**`skills/hardware-design-brief/`** — how to turn a market need into verifiable
+requirement documents: staged questioning, the `docs/01-MRD.md` →
+`docs/02-hardware-PRD.md` → `docs/03-design-brief.md` chain, and the discipline of
+separating confirmed facts from suggestions, assumptions and open questions. It is
+knowledge-only: no tools, no scripts. Its three guides (`mrd-guide.md`,
+`hardware-prd-guide.md`, `design-brief-guide.md`) are loaded on demand.
 
-`skills/kicad-ipc/SKILL.md` is the agent's operating guidance: when to use KiCad, how to
-inspect current state, how to verify mutations, and when to stop and ask. It is *not* an
-IPC API specification — the tool schemas are the executable interface, the skill is the
-reasoning around them.
+The two skills compose: `hardware-design-brief` produces the design inputs,
+`kicad-ipc` (and the `kicad_pcb_*` tools) implements them on a real board. Each
+skill documents its side of that handoff.
 
-Progressive disclosure: `references/ipc-pcb-workflows.md` holds version matrices, the
-public CRUD table and failure handling; `scripts/` holds runnable templates. Both are
-reachable by the agent because the skill is registered with a `resourceBase` pointing at
-its directory.
+Both are reachable by the agent because each is registered with a `resourceBase`
+pointing at its own directory.
 
 ## How the plugin is wired
 
@@ -67,17 +91,21 @@ its directory.
 
 `inject` must match `export const inject` in `src/index.ts`. `skills` is required —
 that is the DSH runtime's own plugin-bundled skill channel (`ctx.skills.register`).
-`apply()` registers the skill and the ten tools and returns a single disposer.
+`apply()` registers every bundled skill and the ten tools, and returns a single
+disposer. Loading is degraded per skill: a skill that fails to resolve is logged at
+error level and skipped, and the rest of the plugin still loads — a broken
+`hardware-design-brief` must never take the KiCad tools down with it, and vice versa.
 
-The skill is located relative to the **loaded module**, not the source tree, so one
+The skills are located relative to the **loaded module**, not the source tree, so one
 resolver works for `src/` (tests), `lib/` (built) and an npm install:
 
 ```
-<package>/lib/index.mjs  ->  <package>/skills/kicad-ipc
+<package>/lib/index.mjs  ->  <package>/skills  ->  <package>/skills/<skill-id>
 ```
 
-That is why `files[]` must contain `skills` — otherwise npm strips it and `apply()`
-throws loudly instead of silently degrading.
+`skillsDir` / `$DSH_KICAD_SKILLS_DIR` overrides the **root** (`skills/`), not one
+skill's directory, so it relocates the whole set at once. `skills` must be in
+`files[]` — otherwise npm strips it and every skill resolution fails.
 
 ## Runtime requirements
 
@@ -105,7 +133,7 @@ package never guesses, hardcodes or scans for them.
 | Setting | Env | Default |
 |---|---|---|
 | `pythonPath` | `DSH_KICAD_PYTHON` | `python3` |
-| `skillsDir` | `DSH_KICAD_SKILLS_DIR` | bundled `skills/kicad-ipc` |
+| `skillsDir` | `DSH_KICAD_SKILLS_DIR` | bundled `skills/` (the root holding every skill) |
 | `timeoutMs` | — | `30000` |
 | `diagnosticTimeoutMs` | — | `15000` |
 | `refillTimeoutMs` | — | `150000` |
@@ -124,17 +152,23 @@ package never guesses, hardcodes or scans for them.
 
 ```
 packages/dsh-kicad/
-  src/index.ts     # plugin entry: apply() registers skill + tools
+  src/index.ts     # plugin entry: apply() registers every bundled skill + the tools
   src/tools.ts     # 10 defineTool definitions
   src/ipc.ts       # KiCad IPC adapter (script runner + error classification)
-  src/scripts.ts   # bundled script registry
-  src/paths.ts     # runtime skill-directory resolution
+  src/scripts.ts   # bundled script registry (the kicad-ipc templates)
+  src/skills.ts    # bundled skill registry (ids, summaries, which owns the scripts)
+  src/paths.ts     # runtime skills-root + per-skill directory resolution
   src/config.ts    # python interpreter / timeouts
-  skills/kicad-ipc/
-    SKILL.md
-    agents/openai.yaml
-    references/ipc-pcb-workflows.md
-    scripts/*.py
+  skills/
+    kicad-ipc/
+      SKILL.md
+      agents/openai.yaml
+      references/ipc-pcb-workflows.md
+      scripts/*.py
+    hardware-design-brief/
+      SKILL.md
+      agents/openai.yaml
+      references/{mrd,hardware-prd,design-brief}-guide.md
   test/            # plugin loading, tool registration, skill discovery, bundling
 ```
 
@@ -144,6 +178,6 @@ packages/dsh-kicad/
 pnpm --filter @huaqiu/dsh-kicad test
 ```
 
-46 tests covering plugin loading, the disposer, skill discovery, tool registration, argv
+58 tests covering plugin loading, the disposer, skill discovery, tool registration, argv
 construction, pre-flight validation, semantic error mapping and packaging. Execution is
 exercised against a fake interpreter, so no KiCad or `kipy` is needed.

package/cordis.patch.yml

@@ -1,9 +1,10 @@
 # DSH bundle patch: inserts the Huaqiu KiCad plugin into a profile's layer stack.
 #
 # This one row delivers BOTH halves of `dsh-kicad` (task: dsh-kicad-skill-plugin):
-# the KiCad tools and the bundled `kicad-ipc` skill. The plugin registers the
-# skill itself at load time via `ctx.skills.register()`, so there is no separate
-# skill installation step and no second skill registration mechanism.
+# the KiCad tools and every skill bundled under `skills/` (currently `kicad-ipc`
+# and `hardware-design-brief`). The plugin registers the skills itself at load
+# time via `ctx.skills.register()`, so there is no separate skill installation
+# step and no second skill registration mechanism.
 #
 # The entry `inject` MUST match the node-half module contract (`src/index.ts`
 # `export const inject`): `skills` + `tools`. `skills` is REQUIRED — without it

package/lib/index.d.mts

@@ -20,7 +20,12 @@ interface KicadConfig {
    * official `kicad-python` package (`kipy`) installed.
    */
   pythonPath: string;
-  /** Scripts directory override (defaults to the bundled skill's `scripts/`). */
+  /**
+   * Skills root override — the directory that CONTAINS the bundled skill
+   * directories (`<root>/kicad-ipc`, `<root>/hardware-design-brief`). Defaults
+   * to the package's own `skills/`. Relocates the whole skill set at once; the
+   * per-skill layout below it never changes.
+   */
   skillsDir?: string;
   /** Per-script timeout in milliseconds. */
   timeoutMs: number;
@@ -36,9 +41,10 @@ type KicadConfigInput = Partial<KicadConfig>;
  * Registry of the KiCad IPC script templates bundled with this package.
  *
  * The scripts are the migrated `kicad-agent` executable surface. They live
- * under `skills/kicad-ipc/scripts/` and are shipped verbatim — this module only
- * describes them so the DSH tools and the skill stay in sync. Nothing here
- * reimplements KiCad IPC: the scripts own it (see `./ipc.ts`).
+ * under `skills/<KICAD_SCRIPT_SKILL_ID>/scripts/` — the `kicad-ipc` skill (see
+ * `./skills.ts`, which owns the skill ids) — and are shipped verbatim: this
+ * module only describes them so the DSH tools and the skill stay in sync.
+ * Nothing here reimplements KiCad IPC: the scripts own it (see `./ipc.ts`).
  *
  * @module
  */
@@ -77,8 +83,6 @@ declare const KICAD_SCRIPT_IDS: readonly string[];
  * @throws when the id is not part of the bundled set.
  */
 declare function kicadScript(id: string): KicadScript;
-/** The canonical skill directory name shipped by this package. */
-declare const KICAD_SKILL_NAME = "kicad-ipc";
 //#endregion
 //#region src/ipc.d.ts
 /**
@@ -156,6 +160,73 @@ declare function invokeKicadScript(options: RunScriptOptions): Promise<{
   error?: KicadError;
 }>;
 //#endregion
+//#region src/skills.d.ts
+/**
+ * Registry of the skills bundled with this package.
+ *
+ * The skills under `skills/` are the migrated `kicad-agent` knowledge, shipped
+ * verbatim (see `README.md` and `docs/dsh-kicad-migration.md`) — this module
+ * only *describes* them, so `apply()` can register each one with
+ * `ctx.skills.register()` without hardcoding paths or names.
+ *
+ * The registry is the single source of truth for three things that must not
+ * drift apart:
+ *
+ *   - the DSH skill id, which MUST equal the directory name under `skills/`
+ *     (the bundling tests assert this, because a mismatch silently produces a
+ *     skill whose `resourceBase` points somewhere else);
+ *   - the fallback catalogue description, used only when SKILL.md frontmatter
+ *     has no parseable `description` (the shipped file always wins);
+ *   - which skill owns the Python script templates the KiCad tools run.
+ *
+ * Adding a skill from `kicad-agent` means: copy the directory, add an entry
+ * here, and register it — nothing else in `src/` is skill-specific.
+ *
+ * @module
+ */
+/** A skill this package bundles and registers at load time. */
+interface KicadBundledSkill {
+  /** DSH skill id — must match the directory name under `skills/`. */
+  readonly id: string;
+  /**
+   * Agent-facing catalogue description, used ONLY when the bundled SKILL.md has
+   * no parseable `description` frontmatter. The shipped file is authoritative,
+   * so this cannot be the normal path — DSH ignores a skill without a
+   * description, so an empty value here would silently break discovery.
+   */
+  readonly summary: string;
+  /**
+   * Whether this skill owns `skills/<id>/scripts/` — the runnable Python
+   * templates that back the DSH tools. Exactly one bundled skill does; the
+   * tools resolve their interpreter scripts through it (`./paths.ts`).
+   */
+  readonly ownsScripts: boolean;
+}
+/**
+ * The skill that owns the script templates behind the KiCad tools.
+ *
+ * The tools are the *executable* half of this skill: `kicad_pcb_*` shells out
+ * to `skills/kicad-ipc/scripts/*.py`. Kept as a named constant because the
+ * tools must keep resolving correctly even when that particular skill fails to
+ * load (they then fail per-call with a typed `FAILED_PRECONDITION` instead of
+ * silently pointing at another skill's directory).
+ */
+declare const KICAD_SCRIPT_SKILL_ID = "kicad-ipc";
+/**
+ * Every skill bundled with `@huaqiu/dsh-kicad`, keyed by id.
+ *
+ * Mirrors `skills/` 1:1 — the bundling test asserts that every entry exists on
+ * disk with a valid SKILL.md, and that no directory is left unregistered.
+ */
+declare const KICAD_SKILLS: Readonly<Record<string, KicadBundledSkill>>;
+/** The bundled skill ids, in registration order. */
+declare const KICAD_SKILL_IDS: readonly string[];
+/**
+ * Look up one bundled skill by id.
+ * @throws when the id is not part of the bundled set.
+ */
+declare function kicadSkill(id: string): KicadBundledSkill;
+//#endregion
 //#region src/tools.d.ts
 /** Everything a tool needs to reach the bundled scripts. */
 interface KicadToolEnv {
@@ -177,24 +248,33 @@ declare function kicadToolNames(): string[];
 //#endregion
 //#region src/paths.d.ts
 /**
- * Absolute path of the bundled `kicad-ipc` skill directory.
+ * Absolute path of the directory holding every bundled skill.
  *
  * Resolution order: an explicit override (config / `DSH_KICAD_SKILLS_DIR`),
  * then the package-relative location.
  *
  * @param moduleUrl - `import.meta.url` of the calling module.
- * @param override - explicit directory (plugin config or env var).
+ * @param override - explicit skills root (plugin config or env var).
+ * @returns the resolved directory, whether or not it exists yet.
+ */
+declare function skillsRoot(moduleUrl: string, override?: string): string;
+/**
+ * Absolute path of one bundled skill directory.
+ *
+ * @param moduleUrl - `import.meta.url` of the calling module.
+ * @param skillId - bundled skill id; MUST equal the directory name.
+ * @param override - explicit skills root (plugin config or env var).
  * @returns the resolved directory, whether or not it exists yet.
  */
-declare function resolveSkillDir(moduleUrl: string, override?: string): string;
+declare function resolveSkillDir(moduleUrl: string, skillId: string, override?: string): string;
 /**
- * Resolve the skill directory and assert the skill is actually present.
+ * Resolve one skill directory and assert the skill is actually present.
  *
  * @throws when `SKILL.md` is missing — this is a packaging failure, not a
  * runtime condition, so it must be loud rather than silently degraded.
  */
-declare function requireSkillDir(moduleUrl: string, override?: string): string;
-/** Absolute path of the bundled Python script directory. */
+declare function requireSkillDir(moduleUrl: string, skillId: string, override?: string): string;
+/** Absolute path of the bundled Python script directory inside a skill. */
 declare function scriptsDir(skillDir: string): string;
 //#endregion
 //#region src/index.d.ts
@@ -204,7 +284,7 @@ declare const name = "@huaqiu/dsh-kicad";
  * Cordis services this half depends on.
  *
  * `skills` is REQUIRED: it is the DSH runtime's skill registry, and registering
- * the bundled `kicad-ipc` skill is this plugin's core job. Without the inject,
+ * the bundled skills is this plugin's core job. Without the inject,
  * `apply()`'s `ctx.skills` access would throw
  * `cannot get property "skills" without inject`.
  *
@@ -255,27 +335,37 @@ declare module '@deepseek-ai/cordis' {
  * Extract the `description` field from SKILL.md YAML frontmatter.
  *
  * Only the single-line form is supported (quoted or bare), which is what the
- * migrated skill uses. Returns `undefined` when absent so the caller can fall
+ * migrated skills use. Returns `undefined` when absent so the caller can fall
  * back rather than registering a skill with an empty description — DSH ignores
  * frontmatter-less skills entirely, so an empty description would silently
  * break discovery.
  */
 declare function skillDescription(markdown: string): string | undefined;
-/**
- * Read the bundled `kicad-ipc` SKILL.md.
- *
- * Exposed for tests and for callers that want the skill body without loading
- * the plugin (e.g. a packaging check).
- */
-declare function readBundledSkill(moduleUrl: string, override?: string): {
-  dir: string;
+/** One bundled skill, as read from disk and ready for `ctx.skills.register()`. */
+interface BundledSkill {
+  /** Skill id — equals the directory name and the DSH-catalogued id. */
   name: string;
+  /** Directory holding SKILL.md, `references/` and `scripts/`. */
+  dir: string;
+  /** Catalogue description (from SKILL.md frontmatter, else the registry). */
   description: string;
+  /** Full SKILL.md body. */
   content: string;
-};
+}
+/**
+ * Read one bundled SKILL.md.
+ *
+ * Exposed for tests and for callers that want a skill body without loading the
+ * plugin (e.g. a packaging check).
+ *
+ * @param moduleUrl - `import.meta.url` of the calling module.
+ * @param skillId - bundled skill id (see `./skills.ts`).
+ * @param override - explicit skills root (plugin config or env var).
+ */
+declare function readBundledSkill(moduleUrl: string, skillId: string, override?: string): BundledSkill;
 /**
- * Read the bundled skill, or `null` when the installed package does not carry
- * one.
+ * Read one bundled skill, or `null` when the installed package does not carry
+ * it.
  *
  * ── Why this degrades instead of throwing ──────────────────────────────────
  * A missing `skills/` tree is a PACKAGING failure, and the honest signal for a
@@ -287,31 +377,29 @@ declare function readBundledSkill(moduleUrl: string, override?: string): {
  * That actually happened: HQ Edge's builtin-plugin staging copied only
  * `package.json` + `lib/`, so `skills/` never reached the bundle and the
  * server could not start at all. The correct blast radius for "this plugin's
- * skill is missing" is "this plugin is degraded", so we log at error level
- * with the exact path and remedy, skip skill registration, and keep the tools
- * (which fail per-call with a typed `FAILED_PRECONDITION` rather than at load).
+ * skill is missing" is "this skill is unavailable", so we log at error level
+ * with the exact path and remedy and skip that skill — per skill, so a broken
+ * `kicad-ipc` never hides a perfectly good `hardware-design-brief`. The tools
+ * are always kept (they fail per-call with a typed `FAILED_PRECONDITION`
+ * rather than at load).
  *
  * @param moduleUrl - `import.meta.url` of the calling module.
- * @param override - explicit skill directory (plugin config or env var).
+ * @param skillId - bundled skill id (see `./skills.ts`).
+ * @param override - explicit skills root (plugin config or env var).
  */
-declare function tryReadBundledSkill(moduleUrl: string, override?: string): {
-  dir: string;
-  name: string;
-  description: string;
-  content: string;
-} | null;
+declare function tryReadBundledSkill(moduleUrl: string, skillId: string, override?: string): BundledSkill | null;
 /**
- * Host plugin body — register the `kicad-ipc` skill and the KiCad tools.
+ * Host plugin body — register every bundled skill and the KiCad tools.
  *
- * Both halves are registered here so that one installation delivers both. The
- * skill's `resourceBase` points at the bundled skill directory, which is how
- * the agent reaches `references/ipc-pcb-workflows.md` and `scripts/` as
- * progressive-disclosure resources.
+ * Both halves are registered here so that one installation delivers both. Each
+ * skill's `resourceBase` points at its own bundled directory, which is how the
+ * agent reaches `references/` and `scripts/` as progressive-disclosure
+ * resources.
  *
  * @param ctx - real cordis context (node side).
  * @param config - plugin overlay config (python interpreter, timeouts).
- * @returns disposer — unregisters the skill and the tools on plugin dispose.
+ * @returns disposer — unregisters every skill and tool on plugin dispose.
  */
 declare function apply(ctx: Context, config?: KicadConfigInput): () => void;
 //#endregion
-export { KICAD_SCRIPTS, KICAD_SCRIPT_IDS, KICAD_SKILL_NAME, type KicadConfig, type KicadConfigInput, type KicadError, type KicadErrorKind, type KicadScript, type ScriptEffect, type ScriptRun, SkillRegistration, apply, classifyRun, createKicadTools, inject, invokeKicadScript, kicadScript, kicadToolNames, name, readBundledSkill, requireSkillDir, resolveSkillDir, runKicadScript, scriptsDir, skillDescription, tryReadBundledSkill };
+export { BundledSkill, KICAD_SCRIPTS, KICAD_SCRIPT_IDS, KICAD_SCRIPT_SKILL_ID, KICAD_SKILLS, KICAD_SKILL_IDS, type KicadBundledSkill, type KicadConfig, type KicadConfigInput, type KicadError, type KicadErrorKind, type KicadScript, type ScriptEffect, type ScriptRun, SkillRegistration, apply, classifyRun, createKicadTools, inject, invokeKicadScript, kicadScript, kicadSkill, kicadToolNames, name, readBundledSkill, requireSkillDir, resolveSkillDir, runKicadScript, scriptsDir, skillDescription, skillsRoot, tryReadBundledSkill };