@dzhechkov/harness-core 0.3.19 → 0.3.21

package/src/operations.ts

@@ -51,6 +51,12 @@ export interface InitReport {
   readonly skillsDir: string;
   readonly projectRoot: string;
   readonly skills: InitSkillResult[];
+  /**
+   * Selected skill ids that were NOT found in `skillsDir`. Empty when no
+   * `select` was given. Lets callers surface a warning instead of silently
+   * installing fewer skills than the selection asked for.
+   */
+  readonly missing: string[];
 }
 
 // ---------------------------------------------------------------------------
@@ -142,9 +148,13 @@ export async function runInit(options: InitOptions): Promise<InitReport> {
   const adapter = TARGETS[options.target];
   const skills: InitSkillResult[] = [];
   const selection = options.select;
-  const ids = discoverSkillIds(options.skillsDir).filter(
+  const discovered = discoverSkillIds(options.skillsDir);
+  const ids = discovered.filter(
     (id) => selection === undefined || selection.includes(id),
   );
+  const missing = selection === undefined
+    ? []
+    : selection.filter((id) => !discovered.includes(id));
   for (const id of ids) {
     const skill = loadSkillFromDir(options.skillsDir, id);
     const emit = await adapter.compile(skill, { targetRoot: options.projectRoot });
@@ -157,7 +167,7 @@ export async function runInit(options: InitOptions): Promise<InitReport> {
     });
     skills.push({ id, written: applied.written, skipped: applied.skipped, warnings: [...emit.warnings] });
   }
-  return { target: options.target, skillsDir: options.skillsDir, projectRoot: options.projectRoot, skills };
+  return { target: options.target, skillsDir: options.skillsDir, projectRoot: options.projectRoot, skills, missing };
 }
 
 // ---------------------------------------------------------------------------

package/src/registry.ts

@@ -46,6 +46,8 @@ function categoryFromPack(pack: string): string {
   if (pack.includes('web3')) return 'web3';
   if (pack.includes('mcp')) return 'mcp';
   if (pack.includes('qe')) return 'qe';
+  if (pack.includes('academic')) return 'academic';
+  if (pack.includes('ecc')) return 'ecc';
   if (pack.includes('meta')) return 'meta';
   if (pack.includes('bto')) return 'bto';
   if (pack.includes('health')) return 'health';

package/src/setup.ts

@@ -29,6 +29,8 @@ export interface SetupOptions {
   readonly noMemory?: boolean | undefined;
   readonly noPretrain?: boolean | undefined;
   readonly force?: boolean | undefined;
+  /** Also deploy the operating-instructions "driver" skill + agent docs. */
+  readonly installDriver?: boolean | undefined;
 }
 
 /** Setup result. */
@@ -122,6 +124,125 @@ function isAgentdbAvailable(): boolean {
 }
 
 /** Run full environment setup. */
+/** Marker that brackets the dz-harness section in a shared CLAUDE.md/AGENTS.md. */
+const DRIVER_MARKER_START = '<!-- dz-harness-driver:start -->';
+const DRIVER_MARKER_END = '<!-- dz-harness-driver:end -->';
+
+/**
+ * Operating instructions for a coding agent that should *drive* the dz CLI
+ * correctly. Inspired by Visa VVAH `--install-agents`: the toolkit ships its own
+ * "how to operate me" doc so agents use the CLI as intended rather than guessing.
+ */
+function generateDriverInstructions(): string {
+  return `# Operating dz-harness-hub (CLI driver)
+
+You have the \`dz\` CLI (\`@dzhechkov/harness-cli\`) available. It manages cross-platform
+AI skills (the agentskills.io \`SKILL.md\` format) across Claude Code, Codex, OpenCode,
+Hermes, and OpenClaude.
+
+## Core commands
+
+| Command | Use it when |
+|---------|-------------|
+| \`dz recommend "<task>"\` | The user describes a task — suggests the right skills/preset/npx package. Start here. |
+| \`dz setup --target <t> [--preset <p>] [--memory agentdb]\` | Bootstrap a project: config, hooks, learning memory. |
+| \`dz init --target <t> [--preset <p>] [--select id,id]\` | Install skills into a project for a platform. |
+| \`dz benchmark <skill-dir>\` | Score a skill (L0 structural checks, grade A–F, cost band). |
+| \`dz pretrain\` | Detect the project's tech stack and pre-load relevant skills. |
+| \`dz scout [--deep]\` | Discover new skill sources across the ecosystem. |
+| \`dz import-ecc\` | Import skills from an ECC repo. |
+
+## Rules for driving this CLI
+
+1. **Do NOT hand-edit \`SKILL.md\` files to make a benchmark pass** — fix the underlying
+   structure (missing frontmatter, sections, schema) instead.
+2. **Do NOT hand-write \`.dz/config.json\`** — run \`dz setup\` and let it generate config.
+3. **Skills are agentskills.io format** — YAML frontmatter (name, description, trust_tier,
+   validation) + a Markdown body with a Protocol and Anti-Patterns section.
+4. **Presets bundle skills**; prefer \`--preset\` over selecting individual skills unless the
+   user wants a minimal install.
+5. **Trust tiers**: tier 1 (Structured) → run \`/bto-test\` to promote to tier 2 (Validated).
+6. When unsure which skills fit, run \`dz recommend\` first and follow its output.
+
+## Targets (platform install dirs)
+
+claude-code → \`.claude/skills/\` · codex → \`.agents/skills/\` · opencode → \`.opencode/\` ·
+hermes → \`.hermes/\` · openclaude → \`.claude/skills/\`. The SKILL.md format is identical
+across all five — only the directory differs.
+`;
+}
+
+/** The same instructions packaged as a loadable Claude Code skill. */
+function generateDriverSkill(): string {
+  return `---
+name: dz-harness-driver
+description: >
+  Operating instructions for the dz-harness-hub CLI (@dzhechkov/harness-cli). Load this when
+  asked to install/manage AI skills, set up a project with dz, benchmark a skill, or pick
+  the right preset. Tells you which dz command to run and the rules for driving the toolkit.
+  Triggers on: "dz setup", "install skills", "benchmark skill", "which preset", "dz recommend".
+trust_tier: 0
+trust_tier_label: "Reference"
+---
+
+${generateDriverInstructions()}
+`;
+}
+
+/**
+ * Write the driver docs non-destructively. New files are created; an existing
+ * CLAUDE.md/AGENTS.md gets a marked section appended only if not already present.
+ * Returns a short detail string for the setup step.
+ */
+function installDriverDocs(projectRoot: string, force: boolean): string {
+  const written: string[] = [];
+  const skipped: string[] = [];
+
+  // 1. The loadable skill (own directory — always safe to write/refresh)
+  const skillDir = join(projectRoot, '.claude', 'skills', 'dz-harness-driver');
+  const skillPath = join(skillDir, 'SKILL.md');
+  if (!existsSync(skillPath) || force) {
+    mkdirSync(skillDir, { recursive: true });
+    writeFileSync(skillPath, generateDriverSkill());
+    written.push('skill');
+  } else {
+    skipped.push('skill');
+  }
+
+  // 2. Standalone agent docs — create only if absent (never clobber the user's).
+  const instructions = generateDriverInstructions();
+  for (const name of ['AGENTS.md', 'GEMINI.md']) {
+    const p = join(projectRoot, name);
+    if (!existsSync(p)) {
+      writeFileSync(p, instructions);
+      written.push(name);
+    } else {
+      skipped.push(name);
+    }
+  }
+
+  // 3. CLAUDE.md — append a marked block if the file lacks one (additive, idempotent).
+  const claudePath = join(projectRoot, 'CLAUDE.md');
+  const block = `\n${DRIVER_MARKER_START}\n\n${instructions}\n${DRIVER_MARKER_END}\n`;
+  if (!existsSync(claudePath)) {
+    writeFileSync(claudePath, block.trimStart());
+    written.push('CLAUDE.md');
+  } else {
+    const existing = readFileSync(claudePath, 'utf-8');
+    if (!existing.includes(DRIVER_MARKER_START)) {
+      writeFileSync(claudePath, existing + block);
+      written.push('CLAUDE.md(appended)');
+    } else {
+      skipped.push('CLAUDE.md');
+    }
+  }
+
+  const parts: string[] = [];
+  if (written.length) parts.push(`wrote ${written.join(', ')}`);
+  if (skipped.length) parts.push(`skipped ${skipped.join(', ')}`);
+  return parts.join('; ') || 'no changes';
+}
+
 export function runSetup(opts: SetupOptions): SetupResult {
   const steps: SetupStep[] = [];
   const dzDir = join(opts.projectRoot, '.dz');
@@ -268,6 +389,12 @@ export function runSetup(opts: SetupOptions): SetupResult {
     steps.push({ name: 'Create .gitignore', status: 'done', detail: 'with .dz entries' });
   }
 
+  // Step 7: Install the CLI-driver skill + agent docs (--install-driver)
+  if (opts.installDriver) {
+    const detail = installDriverDocs(opts.projectRoot, opts.force ?? false);
+    steps.push({ name: 'Install driver skill', status: 'done', detail });
+  }
+
   return {
     steps,
     totalSteps: steps.length,

package/src/sync-upstream.ts

@@ -57,7 +57,11 @@ export function loadSourcesManifest(packageDir: string): SourcesManifest | undef
   const sourcesPath = join(packageDir, 'sources.json');
   if (!existsSync(sourcesPath)) return undefined;
   const raw = readFileSync(sourcesPath, 'utf-8');
-  return JSON.parse(raw) as SourcesManifest;
+  const parsed = JSON.parse(raw) as Record<string, unknown>;
+  // Only return if it has the expected origin + skills structure
+  if (!parsed.origin || typeof parsed.origin !== 'object') return undefined;
+  if (!parsed.skills || typeof parsed.skills !== 'object') return undefined;
+  return parsed as unknown as SourcesManifest;
 }
 
 /** Info about a package with external sources. */