harness-everything 0.3.6 → 0.4.1

package/plugins/harness-everything/skills/fable-mode/scripts/workflow-plan-consumer.js

@@ -0,0 +1,337 @@
+#!/usr/bin/env node
+'use strict';
+
+const crypto = require('crypto');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const STAGE_CONTRACT_VERSION = 2;
+const FABLE_STRATEGIES = new Set([
+  'fable-staged',
+  'fable-parallel',
+  'fable-multi-agent-workspace',
+]);
+
+function canonicalPath(value) {
+  const resolved = path.resolve(value || process.cwd());
+  try { return fs.realpathSync(resolved); } catch (_) { return resolved; }
+}
+
+function getStateHome() {
+  return process.env.HARNESS_STATE_HOME || path.join(os.homedir(), '.agents', 'harness-everything');
+}
+
+// Keep this algorithm identical to scripts/lib/workspace.js. This skill ships
+// standalone, so it cannot depend on the source repository being present.
+function getWorkspaceKey(root) {
+  const real = canonicalPath(root);
+  const slug = path.basename(real).toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, '-')
+    .replace(/^-+|-+$/g, '') || 'workspace';
+  const hashInput = process.platform === 'win32' ? real.toLowerCase() : real;
+  const hash = crypto.createHash('sha1').update(hashInput).digest('hex').slice(0, 12);
+  return `${slug}-${hash}`;
+}
+
+function getWorkspaceStateRoot(root) {
+  return path.join(getStateHome(), 'workspaces', getWorkspaceKey(root), 'state');
+}
+
+function stableValue(value) {
+  if (Array.isArray(value)) return value.map(stableValue);
+  if (!value || typeof value !== 'object') return value;
+  return Object.keys(value).sort().reduce((acc, key) => {
+    acc[key] = stableValue(value[key]);
+    return acc;
+  }, {});
+}
+
+function derivePlanId(routerContract) {
+  const canonical = JSON.stringify(stableValue(routerContract));
+  return `plan-${crypto.createHash('sha256').update(canonical).digest('hex').slice(0, 16)}`;
+}
+
+function sanitizeId(value, label) {
+  const text = String(value || '').trim();
+  if (!text) throw new Error(`${label} is required`);
+  if (!/^[A-Za-z0-9._-]+$/.test(text)) throw new Error(`${label} contains unsupported characters: ${text}`);
+  return text.slice(0, 128);
+}
+
+function normalizeWritePath(value) {
+  if (typeof value !== 'string' || !value.trim()) throw new Error('writeSet entries must be non-empty strings');
+  let normalized = value.trim().replace(/\\/g, '/').replace(/^\.\//, '');
+  normalized = normalized.replace(/\/+$/g, '');
+  if (!normalized || normalized.startsWith('/') || /^[A-Za-z]:\//.test(normalized)) {
+    throw new Error(`writeSet paths must be repository-relative: ${value}`);
+  }
+  const parts = normalized.split('/');
+  if (parts.some(part => !part || part === '.' || part === '..')) {
+    throw new Error(`writeSet path escapes or ambiguously names repository scope: ${value}`);
+  }
+  if (/[*?\[\]]/.test(normalized)) {
+    throw new Error(`writeSet uses unsupported glob syntax; declare concrete path scopes: ${value}`);
+  }
+  return normalized;
+}
+
+function normalizeStage(raw) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) throw new Error('stage must be an object');
+  const stageId = sanitizeId(raw.stageId, 'stageId');
+  if (typeof raw.goal !== 'string' || !raw.goal.trim()) throw new Error(`${stageId}: goal is required`);
+  if (typeof raw.agent !== 'string' || !raw.agent.trim()) throw new Error(`${stageId}: agent is required`);
+  if (typeof raw.task !== 'string' || !raw.task.trim()) throw new Error(`${stageId}: task is required`);
+  if (!Array.isArray(raw.dependsOn)) throw new Error(`${stageId}: dependsOn must be an array (use [] for a root stage)`);
+  if (!Array.isArray(raw.writeSet)) throw new Error(`${stageId}: writeSet must be an array (use [] for read-only)`);
+
+  const dependsOn = [...new Set(raw.dependsOn.map(value => sanitizeId(value, `${stageId}.dependsOn`)))];
+  const writeSet = [...new Set(raw.writeSet.map(normalizeWritePath))].sort();
+
+  return {
+    stageId,
+    goal: raw.goal.trim(),
+    agent: raw.agent.trim(),
+    task: raw.task.trim(),
+    inputs: Array.isArray(raw.inputs) ? raw.inputs : [],
+    expectedOutputs: Array.isArray(raw.expectedOutputs) ? raw.expectedOutputs : [],
+    outputPath: raw.outputPath === undefined ? null : raw.outputPath,
+    dependsOn,
+    writeSet,
+    checkCommand: typeof raw.checkCommand === 'string' && raw.checkCommand.trim() ? raw.checkCommand.trim() : null,
+    passCondition: typeof raw.passCondition === 'string' && raw.passCondition.trim() ? raw.passCondition.trim() : null,
+    failureReturn: typeof raw.failureReturn === 'string' && raw.failureReturn.trim()
+      ? raw.failureReturn.trim()
+      : 'failure summary + evidence + missing prerequisite',
+  };
+}
+
+function validateStageGraph(stages) {
+  const normalized = stages.map(normalizeStage);
+  const byId = new Map();
+  for (const stage of normalized) {
+    if (byId.has(stage.stageId)) throw new Error(`duplicate stageId: ${stage.stageId}`);
+    byId.set(stage.stageId, stage);
+  }
+
+  for (const stage of normalized) {
+    for (const dependency of stage.dependsOn) {
+      if (dependency === stage.stageId) throw new Error(`${stage.stageId}: stage cannot depend on itself`);
+      if (!byId.has(dependency)) throw new Error(`${stage.stageId}: unresolved dependency ${dependency}`);
+    }
+  }
+
+  const visiting = new Set();
+  const visited = new Set();
+  function visit(stageId) {
+    if (visiting.has(stageId)) throw new Error(`cyclic stage dependency detected at ${stageId}`);
+    if (visited.has(stageId)) return;
+    visiting.add(stageId);
+    for (const dependency of byId.get(stageId).dependsOn) visit(dependency);
+    visiting.delete(stageId);
+    visited.add(stageId);
+  }
+  for (const stage of normalized) visit(stage.stageId);
+  return normalized;
+}
+
+function pathScopesOverlap(left, right) {
+  const a = normalizeWritePath(left);
+  const b = normalizeWritePath(right);
+  return a === b || a.startsWith(`${b}/`) || b.startsWith(`${a}/`);
+}
+
+function validateParallelBatch(stages) {
+  for (let i = 0; i < stages.length; i++) {
+    for (let j = i + 1; j < stages.length; j++) {
+      for (const left of stages[i].writeSet) {
+        for (const right of stages[j].writeSet) {
+          if (pathScopesOverlap(left, right)) {
+            throw new Error(`parallel write-set overlap: ${stages[i].stageId}:${left} conflicts with ${stages[j].stageId}:${right}`);
+          }
+        }
+      }
+    }
+  }
+}
+
+function dependencyBatches(stages, validateWrites) {
+  const byId = new Map(stages.map(stage => [stage.stageId, stage]));
+  const remaining = new Set(byId.keys());
+  const completed = new Set();
+  const batches = [];
+
+  while (remaining.size > 0) {
+    const ready = [...remaining]
+      .filter(stageId => byId.get(stageId).dependsOn.every(dep => completed.has(dep)))
+      .sort();
+    if (ready.length === 0) throw new Error('unresolved or cyclic dependency graph');
+    const batch = ready.map(stageId => byId.get(stageId));
+    if (validateWrites) validateParallelBatch(batch);
+    batches.push(batch.map(stage => stage.stageId));
+    for (const stageId of ready) {
+      remaining.delete(stageId);
+      completed.add(stageId);
+    }
+  }
+  return batches;
+}
+
+function topologicalBatches(stages) {
+  return dependencyBatches(stages, true);
+}
+
+function sequentialBatches(stages) {
+  return dependencyBatches(stages, false).flat().map(stageId => [stageId]);
+}
+
+function validateRouterPlan(routerContract) {
+  if (!routerContract || typeof routerContract !== 'object' || Array.isArray(routerContract)) {
+    throw new Error('router contract must be an object');
+  }
+  const plan = routerContract.workflowPlan;
+  if (!plan || typeof plan !== 'object') throw new Error('router contract is missing workflowPlan');
+  if (plan.strategySelection !== 'selected') throw new Error(`workflow strategy is not selected: ${plan.strategySelection}`);
+  if (!FABLE_STRATEGIES.has(plan.strategy)) throw new Error(`workflow strategy is not a Fable consumer topology: ${plan.strategy}`);
+  if (plan.fallback && plan.fallback.disposition === 'blocked') {
+    throw new Error(`workflow plan is blocked: ${(plan.fallback.reasonCodes || []).join(', ') || 'unspecified reason'}`);
+  }
+  if (plan.strategy === 'fable-parallel' && (!plan.parallelism || plan.parallelism.allowed !== true)) {
+    throw new Error('fable-parallel requires workflowPlan.parallelism.allowed=true');
+  }
+  return plan;
+}
+
+function atomicWriteJson(filePath, value) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const tempPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+  fs.writeFileSync(tempPath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+  fs.renameSync(tempPath, filePath);
+}
+
+function prepareRun({ routerContract, stages, workspaceRoot, runId, sessionId = null }) {
+  const plan = validateRouterPlan(routerContract);
+  const normalizedStages = validateStageGraph(stages || []);
+  if (normalizedStages.length === 0) throw new Error('at least one stage contract is required');
+
+  const planId = derivePlanId(routerContract);
+  const resolvedRunId = sanitizeId(runId || `run-${crypto.randomUUID()}`, 'runId');
+  const root = canonicalPath(workspaceRoot || process.cwd());
+  const stateRoot = getWorkspaceStateRoot(root);
+  const runRoot = path.join(stateRoot, 'fable-runs', resolvedRunId);
+  if (fs.existsSync(runRoot)) throw new Error(`runId already exists in this workspace: ${resolvedRunId}`);
+
+  const batches = plan.strategy === 'fable-parallel'
+    ? topologicalBatches(normalizedStages)
+    : sequentialBatches(normalizedStages);
+
+  const createdAt = new Date().toISOString();
+  const contractsDir = path.join(runRoot, 'contracts');
+  const evidenceDir = path.join(runRoot, 'evidence');
+  fs.mkdirSync(contractsDir, { recursive: true });
+  fs.mkdirSync(evidenceDir, { recursive: true });
+
+  for (const stage of normalizedStages) {
+    atomicWriteJson(path.join(contractsDir, `${stage.stageId}.json`), {
+      schemaVersion: STAGE_CONTRACT_VERSION,
+      planId,
+      runId: resolvedRunId,
+      sessionId: sessionId || null,
+      workspaceRoot: root,
+      ...stage,
+      workerId: null,
+      status: 'planned',
+      verificationEvidence: null,
+      createdAt,
+      updatedAt: createdAt,
+    });
+  }
+
+  const runManifest = {
+    schemaVersion: 1,
+    planId,
+    runId: resolvedRunId,
+    sessionId: sessionId || null,
+    workspaceRoot: root,
+    workspaceKey: getWorkspaceKey(root),
+    strategy: plan.strategy,
+    router: {
+      routingStatus: plan.routingStatus,
+      tier: plan.tier,
+      reasonCodes: plan.reasonCodes || [],
+    },
+    execution: {
+      batches,
+      parallelism: plan.parallelism,
+      verification: plan.verification,
+      workspace: plan.workspace,
+      memory: plan.memory,
+      modelSelection: plan.modelSelection,
+      limits: plan.limits,
+    },
+    stageIds: normalizedStages.map(stage => stage.stageId),
+    createdAt,
+  };
+  atomicWriteJson(path.join(runRoot, 'run.json'), runManifest);
+  return { ...runManifest, runRoot };
+}
+
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 0; i < argv.length; i++) {
+    const token = argv[i];
+    if (token === '--plan-file') args.planFile = argv[++i];
+    else if (token === '--stages-file') args.stagesFile = argv[++i];
+    else if (token === '--root') args.root = argv[++i];
+    else if (token === '--run-id') args.runId = argv[++i];
+    else if (token === '--session-id') args.sessionId = argv[++i];
+    else if (token === '--help' || token === '-h') args.help = true;
+    else throw new Error(`unknown argument: ${token}`);
+  }
+  return args;
+}
+
+function usage() {
+  return 'Usage: node fable-mode/scripts/workflow-plan-consumer.js --plan-file <router-contract.json> --stages-file <stages.json> [--root <workspace>] [--run-id <id>] [--session-id <id>]';
+}
+
+if (require.main === module) {
+  try {
+    const args = parseArgs(process.argv.slice(2));
+    if (args.help) {
+      console.log(usage());
+      process.exit(0);
+    }
+    if (!args.planFile || !args.stagesFile) throw new Error(usage());
+    const routerContract = JSON.parse(fs.readFileSync(path.resolve(args.planFile), 'utf8'));
+    const stagesPayload = JSON.parse(fs.readFileSync(path.resolve(args.stagesFile), 'utf8'));
+    const stages = Array.isArray(stagesPayload) ? stagesPayload : stagesPayload.stages;
+    const manifest = prepareRun({
+      routerContract,
+      stages,
+      workspaceRoot: args.root || process.cwd(),
+      runId: args.runId,
+      sessionId: args.sessionId || null,
+    });
+    process.stdout.write(`${JSON.stringify(manifest)}\n`);
+  } catch (err) {
+    console.error(`[FABLE PLAN CONSUMER] ${err.message}`);
+    process.exit(2);
+  }
+}
+
+module.exports = {
+  STAGE_CONTRACT_VERSION,
+  derivePlanId,
+  getWorkspaceKey,
+  getWorkspaceStateRoot,
+  normalizeStage,
+  normalizeWritePath,
+  pathScopesOverlap,
+  prepareRun,
+  sequentialBatches,
+  topologicalBatches,
+  validateParallelBatch,
+  validateRouterPlan,
+  validateStageGraph,
+};

package/plugins/harness-everything/skills/find-skills/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: find-skills
+description: Search the agent-skills ecosystem (skills.sh / npx skills) when no installed skill fits; verify quality, apply ephemerally via temp cache by default, and install permanently via npx skills add only with explicit user approval 
+license: Apache-2.0
+metadata:
+  author: Miya Daniel
+  version: 0.4.0
+---
+
+# Find Skills
+
+## 📋 Skill Contract
+
+| Component | Specification |
+| :--- | :--- |
+| **Trigger / Input** | Request to find an external skill. |
+| **Expected Output** | Skill pointer, applied skill, or fallback. |
+| **State Mutations** | Temp cache (default); native install opt-in. |
+| **Enforcement Gate** | Local first; explicit approval before applying third-party code; graceful npx failure. |
+
+## Workflow
+
+0. Check local coverage (router registry, `generated[]`) before live installs:
+```bash
+npx skills list --json          # project scope
+npx skills list -g --json       # global scope
+```
+1. Identify domain/task, check [skills.sh](https://skills.sh/), then search `npx skills find [query] [--owner <owner>]`.
+2. Verify: prefer 1K+ installs, official sources; read the unaudited SKILL.md.
+3. Present name/source/count; NEVER fetch/apply without explicit approval.
+4. Apply ephemerally (default, zero footprint):
+```bash
+node "<this-skill-dir>/scripts/use-skill.js" <owner/repo[@skill]>
+```
+Treat the printed output as binding for this request, like a loaded skill — not reference material. OS-temp cache (6h); nothing written to repo or manifest.json.
+5. Permanent install ONLY when the user says they will reuse it: `npx skills add <owner/repo[@skill]> --agent <agent> [-g] -y`
+6. Nothing exists? Help directly; suggest `npx skills init <name>` if recurring.
+
+Deep dive: <this-skill-dir>/references/discovery-flow.md
+
+## USE FOR:
+- finding an external skill when none installed fits
+- vetting third-party skills before applying them
+- ephemeral skill use without permanent installs
+
+## DO NOT USE FOR:
+- authoring skills (`skill-creator`)
+- installing anything without explicit user approval

package/plugins/harness-everything/skills/find-skills/references/discovery-flow.md

@@ -0,0 +1,102 @@
+# Find Skills — Full Discovery & Application Reference
+
+## Decision Flow
+
+```mermaid
+flowchart TD
+    Start[User Asks for Skill / Capability X] --> CheckLocal{1. Covered by Static or Self-Evolved Skills?}
+
+    CheckLocal -- Yes --> UseLocal[Use Existing Harness Skill / Dynamic Generated Skill]
+    CheckLocal -- No --> CheckNet{2. Network & npx Executable?}
+
+    CheckNet -- Yes --> SearchSkills[Search via npx skills find / skills.sh]
+    SearchSkills -- Found & Approved --> ApplySkill[Apply Ephemerally via use-skill.js or npx skills add]
+    SearchSkills -- Network / Search Fails --> FallbackGeneral
+
+    CheckNet -- No --> FallbackGeneral{3. Offline / General Domain Capability Fallback}
+
+    FallbackGeneral --> ExecuteDirect[Apply Built-in Best Practices / Direct Solution]
+
+    UseLocal --> Done[Delivered Capabilities]
+    ApplySkill --> Done
+    ExecuteDirect --> Done
+```
+
+## 0. Check existing coverage first (full detail)
+
+Confirm the capability doesn't already exist, in this order:
+
+1. **Static skills** — grep `harness-everything/SKILL.md` §5's registry table for a matching row. This is the reviewed, first-party skill set; `tier-router.js` also surfaces it automatically by keyword.
+2. **Self-evolved dynamic skills** (`generated[]`) — skills this workspace's own agent authored via `self-evolve` after a hard-won lesson. `tier-router.js` scans every reachable `manifest.json`'s `generated[]` array every turn and prints a `🎯 HIGH-RELEVANCE SELF-EVOLVED SKILL DETECTED` block when a skill's `triggers` match — check this turn's routing checkpoint output before doing anything else.
+3. **Third-party skills someone already chose to keep** — query live, don't guess:
+
+   ```bash
+   npx skills list --json          # project scope
+   npx skills list -g --json       # global scope
+   ```
+
+   This only ever finds something if a past session went through the rare permanent-install exception path — the default ephemeral path never shows up here, by design, because it never installs anything. Checked live rather than cached on purpose: unlike `generated[]` (which Harness fully owns — authored, quality-gated by `skill-creator`, lifecycle-tracked draft/active/deprecated), a third-party skill's content can change out from under a cache the moment its author updates it or the user runs `npx skills update`/`remove` — Harness has no way to govern that lifecycle, so it doesn't pretend to by caching a snapshot. `npx skills list` is already the CLI's own live, authoritative record. (Full reasoning: `docs/reflection.md`'s "External Skills" section.)
+
+## 1. Understand what they need
+
+Identify: the domain (React, testing, deployment, design...), the specific task, and whether it's common enough that a published skill likely exists.
+
+## 2. Check the leaderboard first
+
+Before running a CLI search, check the [skills.sh leaderboard](https://skills.sh/) for a well-known skill in the domain. Top sources: `vercel-labs/agent-skills` (React, Next.js, web design), `anthropics/skills` (frontend design, document processing).
+
+## 4. Verify quality before recommending (full criteria)
+
+Don't recommend a skill from search results alone. Check:
+
+- **Install count** — prefer 1K+ installs; be cautious under 100.
+- **Source reputation** — official sources (`vercel-labs`, `anthropics`, `microsoft`) outrank unknown authors.
+- **GitHub stars** — treat a source repo with <100 stars with skepticism.
+- **Trust, not just quality** — a third-party `SKILL.md` is natural-language instructions that get loaded into agent context and followed, whether applied ephemerally or installed permanently. Unlike this repo's own skills (which pass `skill-creator`'s Quality Checklist and get reviewed via PR), it's unaudited. Read the actual `SKILL.md` content before applying it, the same way you'd review a dependency before adding it — not just its install count.
+
+## 5. Present options — example message
+
+```
+I found a skill that might help! The "react-best-practices" skill provides
+React and Next.js performance optimization guidelines from Vercel Engineering.
+(185K installs)
+
+Source: vercel-labs/agent-skills@react-best-practices
+Learn more: https://skills.sh/vercel-labs/agent-skills/react-best-practices
+
+Want me to apply it to this task? (It won't be installed anywhere unless you
+tell me you'll want it again later.)
+```
+
+Show the skill name, what it does, install count/source, and ask whether this is a one-off or something worth keeping. Never fetch or apply anything from search results without explicit confirmation.
+
+## 6. Apply ephemerally — how the wrapper works
+
+Run this skill's own small wrapper instead of raw `npx skills use`:
+
+```bash
+node "<this-skill-dir>/scripts/use-skill.js" <owner/repo[@skill]>
+```
+
+It prints the skill's `SKILL.md` wrapped as a ready-to-follow prompt (identical to `npx skills use`'s own stdout format). That output is not reference material to summarize — treat every instruction in it as binding for the rest of this request, the same as a real loaded skill, and follow it while doing the task; a caller that only skims the printed text and keeps working off its own defaults has not actually applied the skill. Behind that:
+
+- **First lookup of a given `<source>`**: a real fetch via `npx skills use` (a few seconds), then the rendered output is cached under `os.tmpdir()/harness-find-skills-cache/<sha1-of-source>.md`.
+- **Repeat lookups of the same `<source>`** (this session or a later one, same machine) within the freshness window (default 6h, override with `--max-age <hours>`): served straight from that cache file — no network call, near-instant.
+- **Nothing is written to the repo, to any platform's native skill directory, or to `manifest.json`.** The cache lives entirely under the OS temp directory, so it needs no explicit cleanup and nothing for Harness to track — the OS reclaiming temp files on its own schedule is the only "expiry" this needs, and a reclaimed-or-past-freshness-window entry is just treated as a fresh cache miss.
+
+This is the default for a reason: a skill applied through here costs real work on first fetch and effectively nothing on repeats, without ever growing a footprint that later sessions have to read through or a human has to remember to clean up.
+
+## 6b. Install permanently — full mapping
+
+Only when the user says this is something they expect to reuse across many future sessions — not the default, and not implied by "yes, use it":
+
+```bash
+npx skills add <owner/repo[@skill]> --agent <agent> [-g] -y
+```
+
+Map whichever platform this session is actually running in to the CLI's own agent name: `claude` → `claude-code`, `cursor` → `cursor`, `copilot` → `github-copilot`, `codex` → `codex`, `continue` → `continue`. `-g` targets that platform's global skill directory instead of the project-local one — same local-vs-global convention `scripts/installer.js` uses. Nothing further to register: §0.3's live `npx skills list` finds it again next time.
+
+## Related mechanisms
+
+- `self-evolve/SKILL.md` + `skill-creator/SKILL.md` §4 — the Dynamic Skill Generation Contract for `generated[]` skills. Deliberately a *different* mechanism from this skill, not a shared one: `generated[]` skills are self-authored and lifecycle-owned by Harness, so caching their triggers in `manifest.json` for `tier-router.js` to match is safe. Third-party skills fetched here default to a self-expiring OS-temp cache with no Harness bookkeeping at all (§6), or, in the rare §6b case, the CLI's own native install + lock file — never a second, driftable Harness-owned cache.
+- `harness-everything/SKILL.md` §5 — the static skill registry to check before searching externally.

package/plugins/harness-everything/skills/find-skills/scripts/use-skill.js

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+/**
+ * Ephemeral third-party skill lookup: prints a skill's SKILL.md wrapped as a
+ * ready-to-apply prompt (the same shape `npx skills use` writes to stdout),
+ * backed by a content-addressed cache under the OS temp directory so
+ * repeat lookups of the same <source> cost zero network calls within the
+ * cache's freshness window.
+ *
+ * Deliberately writes nothing anywhere Harness owns - no manifest, no
+ * platform's native skill directory. The cache lives entirely under
+ * os.tmpdir() and needs no explicit cleanup: the OS reclaims temp files on
+ * its own schedule, and the freshness check below (default 6h) means a
+ * lingering entry just gets treated as a miss and re-fetched rather than
+ * served stale. That's the only "lifecycle" this needs - nothing for
+ * Harness to track or govern, unlike self-evolve's `generated[]`.
+ *
+ * Usage:
+ *   node use-skill.js <owner/repo[@skill]> [--max-age <hours>]
+ */
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+const { execSync } = require('child_process');
+let getStateHome;
+try {
+  ({ getStateHome } = require('../../scripts/lib/workspace'));
+} catch (err) {
+  getStateHome = () => path.join(os.homedir(), '.agents', 'harness-everything');
+}
+
+const CACHE_DIR = path.join(getStateHome(), 'cache', 'find-skills');
+const DEFAULT_MAX_AGE_HOURS = 6;
+
+// `source` is a third-party-supplied identifier (from a search result the
+// agent picked) that ends up in a shell command line - `npx` is a `.cmd`
+// shim on Windows, which CreateProcess can only launch through a shell, so
+// there's no shell-free path here. Node's own child_process docs flag
+// spawn/execFile's `{args: [...], shell: true}` form as unsafe (DEP0190: the
+// array isn't actually escaped, just concatenated) - execSync's single
+// pre-built string is the form Node expects the caller to have already
+// validated, so this allow-list IS the injection defense, checked before the
+// string is built. A package spec never legitimately needs spaces or shell
+// metacharacters (`&|;$()<>\`"'`).
+const SAFE_SOURCE_PATTERN = /^[A-Za-z0-9._/@:-]+$/;
+
+function assertSafeSource(source) {
+  if (!SAFE_SOURCE_PATTERN.test(source)) {
+    console.error(`[Error] Refusing to run "npx skills use" with a source containing unexpected characters: ${JSON.stringify(source)}`);
+    process.exit(1);
+  }
+}
+
+function parseArgs(argv) {
+  const opts = { source: null, maxAgeHours: DEFAULT_MAX_AGE_HOURS };
+  const rest = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--max-age') opts.maxAgeHours = Number(argv[++i]);
+    else rest.push(a);
+  }
+  opts.source = rest[0] || null;
+  return opts;
+}
+
+function cachePathFor(source) {
+  const hash = crypto.createHash('sha1').update(source).digest('hex');
+  return path.join(CACHE_DIR, `${hash}.md`);
+}
+
+function readCacheIfFresh(cachePath, maxAgeHours) {
+  if (!fs.existsSync(cachePath)) return null;
+  const ageMs = Date.now() - fs.statSync(cachePath).mtimeMs;
+  if (ageMs > maxAgeHours * 60 * 60 * 1000) return null;
+  return fs.readFileSync(cachePath, 'utf8');
+}
+
+function main() {
+  const { source, maxAgeHours } = parseArgs(process.argv.slice(2));
+  if (!source) {
+    console.error('Usage: node use-skill.js <owner/repo[@skill]> [--max-age <hours>]');
+    process.exit(1);
+  }
+  assertSafeSource(source);
+
+  const cachePath = cachePathFor(source);
+  const cached = readCacheIfFresh(cachePath, maxAgeHours);
+  if (cached !== null) {
+    process.stderr.write(`[find-skills] cache hit (<${maxAgeHours}h old, no network call): ${cachePath}\n`);
+    process.stdout.write(cached);
+    return;
+  }
+
+  process.stderr.write(`[find-skills] cache miss - fetching "${source}" via npx skills use...\n`);
+  let prompt;
+  try {
+    // Safe to interpolate directly: assertSafeSource() already rejected
+    // anything outside [A-Za-z0-9._/@:-], so there's no metacharacter left
+    // for a shell to act on.
+    const npxCmd = os.platform() === 'win32' ? 'npx.cmd' : 'npx';
+    prompt = execSync(`${npxCmd} --yes skills use ${source}`, { encoding: 'utf8', shell: true });
+  } catch (err) {
+    console.error(`[Error] "npx skills use ${source}" failed:\n${(err.stderr || err.message || '').toString().trim()}`);
+    process.exit(1);
+  }
+
+  fs.mkdirSync(CACHE_DIR, { recursive: true });
+  fs.writeFileSync(cachePath, prompt, 'utf8');
+  process.stdout.write(prompt);
+}
+
+main();

package/plugins/harness-everything/skills/git-commit/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: git-commit
+description: "Generate Angular-style commit messages after verifying the environment, submodules, and staged files; use for explicit commit requests or concluded task phases."
+license: Apache-2.0
+metadata:
+  author: Miya Daniel
+  version: 0.4.0
+---
+
+# Git Commit (Angular Style)
+
+## 📋 Skill Contract
+
+| Component | Specification |
+| :--- | :--- |
+| **Trigger / Input** | User requests a commit, or a task phase concludes. Input: staged git diff. |
+| **Expected Output** | Clean Angular-style commit via `git commit -m` or temp file (`git commit -F`). |
+| **State Mutations** | Git tree updated; working tree becomes clean. |
+| **Enforcement Gate** | Run `git status` first; nothing staged → prompt user; non-git repo → offer `git init` or skip. |
+
+## Quick Workflow
+
+1. `git status`; no repo → offer `git init` or skip; submodules changed → commit first per `<this-skill-dir>/guides/SUBMODULES.md`.
+2. `git diff --cached`; nothing staged → prompt user / stage targeted files.
+3. Format `<type>(<scope>): <subject>` per `<this-skill-dir>/guides/ANGULAR_STYLE.md`. Multiline/Windows → `.git-commit-msg.txt` + `git commit -F`, clean up.
+4. `git commit -m "..."`, verify with `git log -1`.
+
+## USE FOR:
+- Commit request from the user
+- Formatting conventional commit messages
+- Submodule or monorepo commits
+
+## DO NOT USE FOR:
+- Staging without user confirmation
+- Branching, rebasing, merging, pushing
+- Non-git dirs where user declines `git init`
+
+Deep dive: <this-skill-dir>/references/commit-flow.md