@farmslot/skills 0.1.2 → 0.2.0

package/CHANGELOG.md

@@ -6,9 +6,19 @@ All notable changes to `@farmslot/skills` are tracked here.
 
 - Active-development baseline; add user-facing changes here before release or package publication.
 
+## 0.2.0 - 2026-07-19
+
+- Teach recipe authors to inspect declared actions and reusable flows before creating new capabilities
+
+## 0.1.3 - 2026-07-08
+
+- Update recipe-quality skill guidance to delegate runtime artifact generation to `@farmslot/agent-runtime`
+- `packet`, a skill for packet-shaped operator communication aligned with ADR-048
+- Convert task lifecycle scripts to compatibility shims over `@farmslot/agent-runtime`
+
 ## 0.1.2 - 2026-07-03
 
-- Colocate finish-contract scripts in `packages/skills/scripts/` (`mark-checklist-step.cjs`, `worker-terminal-contract.cjs`, `check-task-artifact-contract.mjs`) as the canonical source for `@farmslot/skills` and consensys-skills delegation
+- Colocate finish-contract scripts in `packages/skills/scripts/` (`mark-checklist-step.cjs`, `worker-terminal-contract.cjs`, `check-task-artifact-contract.mjs`) for the initial `@farmslot/skills` and consensys-skills delegation path
 - **dev / fix-bug:** terminal `./mark complete` requires `artifacts/learnings.md` + `artifacts/pr-description.md` (not `report.md`)
 - `./mark` infers dev/fix-bug flow from embedded checklist `Skill:` header (standalone recipe skills)
 - Export `./scripts/worker-terminal-contract.cjs` and `./scripts/check-task-artifact-contract.mjs` from the package

package/README.md

@@ -42,6 +42,7 @@ Supported layouts:
 | `recipe-doctor`  | Check local readiness for recipe authoring or execution.                                        |
 | `recipe-harness` | Help install or run the local recipe runtime when the project has one.                          |
 | `project-adopt`  | Recommend the smallest useful Farmslot integration level for the project.                       |
+| `packet`         | Communicate plans, blockers, decisions, and evidence reviews as compact operator packets.       |
 
 ## Adoption Ladder
 
@@ -55,13 +56,13 @@ Supported layouts:
 
 - `src/`: TypeScript CLI and install-library entry points.
 - `skills/`: Packaged skill directories copied into consumer repos.
-- `scripts/`: CommonJS recipe-cook runner utilities exposed through package bin scripts.
+- `scripts/`: Compatibility shims for legacy runtime paths. Runtime logic lives in `@farmslot/agent-runtime`.
 - `templates/`: Scenario fixtures and task templates used by the recipe-cook workflow.
 - `test/`: Node TAP-style smoke and behavior tests for installers and runner scripts.
 
 ## Maintenance rules
 
-- `scripts/mark-checklist-step.cjs` mirrors consensys-skills `recipe-harness/scripts/mark-checklist-step.cjs`. Edit the recipe-harness copy first; sync the mirror before shipping Farmslot gateway or npm changes.
+- `scripts/mark-checklist-step.cjs`, `scripts/worker-terminal-contract.cjs`, and `scripts/check-task-artifact-contract.mjs` are compatibility shims that delegate to `@farmslot/agent-runtime`.
 - Keep package payloads self-contained; consumers should not need the Farmslot monorepo.
 - Update `CHANGELOG.md` before packaging or publishing.
 - Run the package readiness guard when files move, bins change, or exports are added.

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export declare const FARMSLOT_SKILLS_PACKAGE = "@farmslot/skills";
-export declare const FARMSLOT_SKILL_NAMES: readonly ["recipe-cook", "recipe-quality", "recipe-doctor", "recipe-harness", "project-adopt"];
+export declare const FARMSLOT_SKILL_NAMES: readonly ["recipe-cook", "recipe-quality", "recipe-doctor", "recipe-harness", "project-adopt", "packet"];
 export type FarmslotSkillName = (typeof FARMSLOT_SKILL_NAMES)[number];
 export declare const FARMSLOT_SKILL_INSTALL_LAYOUTS: readonly ["agents", "claude", "codex", "cursor"];
 export type FarmslotSkillInstallLayout = (typeof FARMSLOT_SKILL_INSTALL_LAYOUTS)[number];

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,uBAAuB,qBAAqB,CAAC;AAE1D,eAAO,MAAM,oBAAoB,gGAMvB,CAAC;AAEX,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEtE,eAAO,MAAM,8BAA8B,kDAAmD,CAAC;AAE/F,MAAM,MAAM,0BAA0B,GAAG,CAAC,OAAO,8BAA8B,CAAC,CAAC,MAAM,CAAC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,uBAAuB,qBAAqB,CAAC;AAE1D,eAAO,MAAM,oBAAoB,0GAOvB,CAAC;AAEX,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEtE,eAAO,MAAM,8BAA8B,kDAAmD,CAAC;AAE/F,MAAM,MAAM,0BAA0B,GAAG,CAAC,OAAO,8BAA8B,CAAC,CAAC,MAAM,CAAC,CAAC"}

package/dist/index.js

@@ -5,6 +5,7 @@ export const FARMSLOT_SKILL_NAMES = [
     'recipe-doctor',
     'recipe-harness',
     'project-adopt',
+    'packet',
 ];
 export const FARMSLOT_SKILL_INSTALL_LAYOUTS = ['agents', 'claude', 'codex', 'cursor'];
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,uBAAuB,GAAG,kBAAkB,CAAC;AAE1D,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,aAAa;IACb,gBAAgB;IAChB,eAAe;IACf,gBAAgB;IAChB,eAAe;CACP,CAAC;AAIX,MAAM,CAAC,MAAM,8BAA8B,GAAG,CAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,CAAU,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,uBAAuB,GAAG,kBAAkB,CAAC;AAE1D,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,aAAa;IACb,gBAAgB;IAChB,eAAe;IACf,gBAAgB;IAChB,eAAe;IACf,QAAQ;CACA,CAAC;AAIX,MAAM,CAAC,MAAM,8BAA8B,GAAG,CAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,CAAU,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farmslot/skills",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -32,6 +32,9 @@
     "prepack": "cd ../.. && node scripts/quality/check-farmslot-package-readiness.mjs --require-changelog --packages @farmslot/skills && yarn workspace @farmslot/skills build",
     "prepublishOnly": "node ../../scripts/quality/check-farmslot-package-readiness.mjs --publish --packages @farmslot/skills"
   },
+  "dependencies": {
+    "@farmslot/agent-runtime": "0.2.0"
+  },
   "devDependencies": {
     "@types/node": "^22.0.0",
     "eslint": "^10.3.0",

package/scripts/check-task-artifact-contract.mjs

@@ -1,310 +1,24 @@
 #!/usr/bin/env node
-import { existsSync, readFileSync, statSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
 import { createRequire } from 'node:module';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 
-const require = createRequire(import.meta.url);
-const { expandedArtifactsForCommand } = require('./worker-terminal-contract.cjs');
+const requireFromHere = createRequire(import.meta.url);
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 
-const taskDir = process.argv[2];
-const rawArgs = process.argv.slice(3);
-const flags = new Set();
-let contractPath;
-let terminalCommand;
-for (let i = 0; i < rawArgs.length; i += 1) {
-  const arg = rawArgs[i];
-  if (arg === '--contract') {
-    contractPath = rawArgs[i + 1];
-    i += 1;
-    continue;
-  }
-  if (arg === '--terminal') {
-    terminalCommand = rawArgs[i + 1];
-    i += 1;
-    continue;
-  }
-  flags.add(arg);
-}
-
-if (!taskDir) {
-  console.error(
-    'usage: check-task-artifact-contract.mjs <task-dir> [--contract path] [--terminal complete|no-change|blocked] [--require-recipe-quality-if-recipe] [--require-recipe-coverage-if-recipe] [--require-learnings] [--skip-learnings]',
-  );
-  process.exit(2);
-}
-
-const issues = [];
-const mediaExt = /\.(png|jpe?g|gif|mp4|mov|webm)$/i;
-const internalArtifactPath =
-  /^artifacts\/(?:harness-launch|harness-relaunch|harness-relaunch-node20|runtime-launch|runtime-relaunch|runner-blockers)\//;
-const allowedManifestKeys = new Set([
-  'version',
-  'preferred_mode',
-  'summary',
-  'before_after_pairs',
-  'standalone',
-  'omit',
-  'videos',
-  'before_state_capture',
-]);
-const allowedPairKeys = new Set(['label', 'covers', 'before', 'after', 'note']);
-const allowedStandaloneKeys = new Set(['label', 'covers', 'file', 'note']);
-const allowedVideoKeys = new Set(['before', 'after', 'preferred', 'note']);
-const allowedOmitKeys = new Set(['file', 'reason']);
-
-function fileExists(rel) {
-  try {
-    return statSync(path.join(taskDir, rel)).isFile();
-  } catch {
-    return false;
-  }
-}
-
-function readText(rel) {
-  const p = path.join(taskDir, rel);
-  return existsSync(p) ? readFileSync(p, 'utf8') : null;
-}
-
-function isRecord(value) {
-  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
-}
-
-function unknownKeys(record, allowed, prefix) {
-  for (const key of Object.keys(record)) {
-    if (!allowed.has(key)) issues.push(`${prefix}.${key}: unknown key`);
-  }
-}
-
-function optionalString(record, key, prefix) {
-  if (record[key] !== undefined && typeof record[key] !== 'string') {
-    issues.push(`${prefix}.${key}: expected string`);
-  }
-}
-
-function optionalStringArray(record, key, prefix) {
-  if (record[key] === undefined) return;
-  if (!Array.isArray(record[key]) || record[key].some((entry) => typeof entry !== 'string')) {
-    issues.push(`${prefix}.${key}: expected string[]`);
-  }
-}
-
-function normalizeArtifactPath(value) {
-  if (typeof value !== 'string') return null;
-  const trimmed = value.trim();
-  if (!trimmed || /^(?:[a-z][a-z0-9+.-]*:|\/\/|#)/i.test(trimmed)) return null;
-  const pathPart = trimmed.split(/[?#]/, 1)[0];
-  const normalized = pathPart.replace(/\\/g, '/').replace(/^\.\/+/g, '');
-  if (!normalized || path.posix.isAbsolute(normalized) || normalized.includes('\0')) return null;
-  const segments = normalized.split('/').filter(Boolean);
-  if (segments.some((segment) => segment === '.' || segment === '..')) return null;
-  const withoutArtifacts =
-    segments[0] === 'artifacts' ? segments.slice(1).join('/') : segments.join('/');
-  if (!withoutArtifacts || !mediaExt.test(withoutArtifacts)) return null;
-  return `artifacts/${withoutArtifacts}`;
-}
-
-function addRef(refs, value) {
-  const normalized = normalizeArtifactPath(value);
-  if (!normalized) return;
-  if (internalArtifactPath.test(normalized)) {
-    issues.push(`evidence-manifest references internal artifact: ${normalized}`);
-    return;
-  }
-  refs.add(normalized);
-}
-
-function validateRecipeQualityArtifact() {
-  const text = readText('artifacts/recipe-quality.json');
-  if (!text) return;
-  let artifact;
-  try {
-    artifact = JSON.parse(text);
-  } catch (error) {
-    issues.push(`recipe-quality.json: invalid JSON: ${error.message}`);
-    return;
-  }
-  if (!isRecord(artifact)) {
-    issues.push('recipe-quality.json: expected object');
-    return;
-  }
-  if (artifact.version !== 1) issues.push('recipe-quality.json: version must be 1');
-  if (!['pass', 'warn', 'fail'].includes(artifact.verdict)) {
-    issues.push('recipe-quality.json: verdict must be pass, warn, or fail');
-  }
-  if (!isRecord(artifact.compact) || !['PASS', 'WARN', 'FAIL'].includes(artifact.compact.verdict)) {
-    issues.push('recipe-quality.json: compact.verdict must be PASS, WARN, or FAIL');
-  }
-}
-
-function parseManifest() {
-  const text = readText('artifacts/evidence-manifest.json');
-  if (!text) return null;
-  let manifest;
+function resolveRuntimeScript() {
   try {
-    manifest = JSON.parse(text);
-  } catch (error) {
-    issues.push(`evidence-manifest.json: invalid JSON: ${error.message}`);
-    return null;
-  }
-  if (!isRecord(manifest)) {
-    issues.push('evidence-manifest.json: expected object');
-    return null;
-  }
-  unknownKeys(manifest, allowedManifestKeys, 'manifest');
-  if (manifest.version !== undefined && typeof manifest.version !== 'number') {
-    issues.push('manifest.version: expected number');
-  }
-  if (
-    manifest.preferred_mode !== undefined &&
-    !['screenshots', 'video'].includes(manifest.preferred_mode)
-  ) {
-    issues.push('manifest.preferred_mode: expected screenshots or video');
-  }
-  optionalString(manifest, 'summary', 'manifest');
-
-  if (manifest.before_after_pairs !== undefined) {
-    if (!Array.isArray(manifest.before_after_pairs)) {
-      issues.push('manifest.before_after_pairs: expected array');
-    } else {
-      manifest.before_after_pairs.forEach((entry, index) => {
-        const prefix = `manifest.before_after_pairs[${index}]`;
-        if (!isRecord(entry)) return issues.push(`${prefix}: expected object`);
-        unknownKeys(entry, allowedPairKeys, prefix);
-        if (typeof entry.label !== 'string' || !entry.label.trim())
-          issues.push(`${prefix}.label: expected non-empty string`);
-        optionalStringArray(entry, 'covers', prefix);
-        optionalString(entry, 'before', prefix);
-        optionalString(entry, 'after', prefix);
-        optionalString(entry, 'note', prefix);
-        if (entry.before === undefined && entry.after === undefined)
-          issues.push(`${prefix}: expected before or after`);
-      });
-    }
-  }
-
-  if (manifest.standalone !== undefined) {
-    if (!Array.isArray(manifest.standalone)) {
-      issues.push('manifest.standalone: expected array');
-    } else {
-      manifest.standalone.forEach((entry, index) => {
-        const prefix = `manifest.standalone[${index}]`;
-        if (!isRecord(entry)) return issues.push(`${prefix}: expected object`);
-        unknownKeys(entry, allowedStandaloneKeys, prefix);
-        if (typeof entry.label !== 'string' || !entry.label.trim())
-          issues.push(`${prefix}.label: expected non-empty string`);
-        optionalStringArray(entry, 'covers', prefix);
-        if (typeof entry.file !== 'string' || !entry.file.trim())
-          issues.push(`${prefix}.file: expected non-empty string`);
-        optionalString(entry, 'note', prefix);
-      });
-    }
-  }
-
-  if (manifest.videos !== undefined) {
-    if (!isRecord(manifest.videos)) {
-      issues.push('manifest.videos: expected object');
-    } else {
-      unknownKeys(manifest.videos, allowedVideoKeys, 'manifest.videos');
-      optionalString(manifest.videos, 'before', 'manifest.videos');
-      optionalString(manifest.videos, 'after', 'manifest.videos');
-      optionalString(manifest.videos, 'note', 'manifest.videos');
-      if (
-        manifest.videos.preferred !== undefined &&
-        typeof manifest.videos.preferred !== 'boolean'
-      ) {
-        issues.push('manifest.videos.preferred: expected boolean');
-      }
-    }
-  }
-
-  if (manifest.omit !== undefined) {
-    if (!Array.isArray(manifest.omit)) {
-      issues.push('manifest.omit: expected array');
-    } else {
-      manifest.omit.forEach((entry, index) => {
-        const prefix = `manifest.omit[${index}]`;
-        if (typeof entry === 'string') return;
-        if (!isRecord(entry)) return issues.push(`${prefix}: expected string or object`);
-        unknownKeys(entry, allowedOmitKeys, prefix);
-        if (typeof entry.file !== 'string' || !entry.file.trim())
-          issues.push(`${prefix}.file: expected non-empty string`);
-        optionalString(entry, 'reason', prefix);
-      });
-    }
-  }
-
-  const refs = new Set();
-  for (const pair of manifest.before_after_pairs ?? []) {
-    addRef(refs, pair?.before);
-    addRef(refs, pair?.after);
-  }
-  for (const entry of manifest.standalone ?? []) addRef(refs, entry?.file);
-  addRef(refs, manifest.videos?.before);
-  addRef(refs, manifest.videos?.after);
-
-  for (const ref of [...refs].sort()) {
-    if (!fileExists(ref)) issues.push(`evidence-manifest references missing artifact: ${ref}`);
-  }
-  return { manifest, refs };
-}
-
-const hasRecipe = fileExists('artifacts/recipe.json');
-if (
-  hasRecipe &&
-  flags.has('--require-recipe-quality-if-recipe') &&
-  !fileExists('artifacts/recipe-quality.json')
-) {
-  issues.push('recipe.json exists but artifacts/recipe-quality.json is missing');
-}
-if (
-  hasRecipe &&
-  flags.has('--require-recipe-coverage-if-recipe') &&
-  !fileExists('artifacts/recipe-coverage.md')
-) {
-  issues.push('recipe.json exists but artifacts/recipe-coverage.md is missing');
-}
-validateRecipeQualityArtifact();
-
-const parsed = parseManifest();
-const coverage = readText('artifacts/recipe-coverage.md');
-if (coverage && /\|\s*(visual|mixed)\s*\|/i.test(coverage)) {
-  const refCount = parsed?.refs?.size ?? 0;
-  if (refCount === 0)
-    issues.push(
-      'recipe-coverage.md declares visual/mixed proof but evidence-manifest has no media references',
+    return requireFromHere.resolve(
+      '@farmslot/agent-runtime/scripts/check-task-artifact-contract.mjs',
     );
-}
-
-if (flags.has('--require-learnings')) {
-  const learnings = readText('artifacts/learnings.md');
-  if (!learnings?.trim()) {
-    issues.push('artifacts/learnings.md: required non-empty learnings artifact');
-  }
-}
-
-if (contractPath && existsSync(contractPath) && terminalCommand) {
-  const contract = JSON.parse(readFileSync(contractPath, 'utf8'));
-  const expanded = expandedArtifactsForCommand(contract, terminalCommand, fileExists);
-  for (const artifactPath of expanded.artifacts) {
-    if (flags.has('--skip-learnings') && artifactPath === 'artifacts/learnings.md') continue;
-    if (artifactPath.endsWith('.md') && !readText(artifactPath)?.trim()) {
-      issues.push(`${artifactPath}: required non-empty artifact (worker terminal contract)`);
-    }
-    if (!fileExists(artifactPath)) {
-      issues.push(`${artifactPath}: required artifact missing (worker terminal contract)`);
-    }
-  }
-  if (expanded.requireRecipeQuality && hasRecipe && !fileExists('artifacts/recipe-quality.json')) {
-    issues.push('recipe.json exists but artifacts/recipe-quality.json is missing');
-  }
-  if (expanded.requireRecipeCoverage && hasRecipe && !fileExists('artifacts/recipe-coverage.md')) {
-    issues.push('recipe.json exists but artifacts/recipe-coverage.md is missing');
+  } catch (error) {
+    if (error.code !== 'MODULE_NOT_FOUND') throw error;
+    return path.resolve(packageRoot, '../agent-runtime/scripts/check-task-artifact-contract.mjs');
   }
 }
 
-if (issues.length > 0) {
-  console.error('TASK_ARTIFACT_CONTRACT_FAIL');
-  for (const issue of issues) console.error(`- ${issue}`);
-  process.exit(1);
-}
-console.log('TASK_ARTIFACT_CONTRACT_PASS');
+const result = spawnSync(process.execPath, [resolveRuntimeScript(), ...process.argv.slice(2)], {
+  stdio: 'inherit',
+});
+process.exit(result.status ?? 1);