@farmslot/skills 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+All notable changes to `@farmslot/skills` are tracked here.
+
+## Unreleased
+
+- Add the generic recipe-first skills package and migrate the former top-level recipe cooking kit into `skills/recipe-cook`.

package/README.md

@@ -0,0 +1,74 @@
+# @farmslot/skills
+
+Generic Farmslot recipe skills for Claude, Codex, Cursor, and repo-local agent skill folders.
+
+Public guide: https://farmslot.io/docs/guides/recipe-skills-adoption
+
+## What This Package Is
+
+`@farmslot/skills` is the recipe-first adoption kit. It teaches an agent how to write, review, diagnose, and adopt validation recipes before a team installs the full Farmslot OS.
+
+It does not require Gateway, Command Center, a pool file, slots, or Companion for first use.
+
+## Install
+
+Install all skills into a repo-local generic agent folder:
+
+```bash
+npx @farmslot/skills install --target . --layout agents
+```
+
+Install a subset:
+
+```bash
+npx @farmslot/skills install --target . --layout agents --include recipe-cook,recipe-doctor
+```
+
+Supported layouts:
+
+| Layout   | Destination under `--target` |
+| -------- | ---------------------------- |
+| `agents` | `.agents/skills/`            |
+| `codex`  | `.codex/skills/`             |
+| `claude` | `.claude/skills/`            |
+| `cursor` | `.cursor/skills/`            |
+
+## Skills
+
+| Skill            | Purpose                                                                                         |
+| ---------------- | ----------------------------------------------------------------------------------------------- |
+| `recipe-cook`    | Turn acceptance criteria, PR intent, or investigation findings into a validation recipe.        |
+| `recipe-quality` | Critique recipe and evidence quality; flag fake proof, hidden state injection, and weak claims. |
+| `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.                       |
+
+## Adoption Ladder
+
+1. Skills only: author and review recipes without a runner.
+2. Recipe runner: add a local command that can execute one recipe and emit artifacts.
+3. Project recipe layer: add recipes, runner manifests, project actions, and artifact conventions.
+4. Farmslot project integration: add `project.json` hooks for Command Center and slots.
+5. Full OS: adopt multi-slot dispatch, live steering, Companion supervision, and retrospectives.
+
+## Source layout
+
+- `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.
+- `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
+
+- 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.
+
+## Local quality
+
+```bash
+yarn workspace @farmslot/skills build
+yarn workspace @farmslot/skills test
+node scripts/quality/check-farmslot-package-readiness.mjs --packages @farmslot/skills
+```

package/bin/farmslot-skills.mjs

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const skillsRoot = path.join(packageRoot, 'skills');
+const knownSkills = readdirSync(skillsRoot)
+  .filter((entry) => existsSync(path.join(skillsRoot, entry, 'SKILL.md')))
+  .sort();
+
+const layoutDirs = {
+  agents: '.agents/skills',
+  claude: '.claude/skills',
+  codex: '.codex/skills',
+  cursor: '.cursor/skills',
+};
+
+function parseArgs(argv) {
+  const parsed = {
+    command: argv[0] || 'help',
+    target: '.',
+    layout: 'agents',
+    include: [],
+    force: false,
+  };
+  for (let index = 1; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--target') parsed.target = argv[++index] || '.';
+    else if (arg.startsWith('--target=')) parsed.target = arg.slice('--target='.length);
+    else if (arg === '--layout') parsed.layout = argv[++index] || 'agents';
+    else if (arg.startsWith('--layout=')) parsed.layout = arg.slice('--layout='.length);
+    else if (arg === '--include') parsed.include = splitCsv(argv[++index] || '');
+    else if (arg.startsWith('--include='))
+      parsed.include = splitCsv(arg.slice('--include='.length));
+    else if (arg === '--force') parsed.force = true;
+  }
+  return parsed;
+}
+
+function splitCsv(value) {
+  return String(value)
+    .split(',')
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+function usage() {
+  return [
+    'Usage: farmslot-skills <command> [options]',
+    '',
+    'Commands:',
+    '  list                         List bundled skills',
+    '  install                      Install skills into a target layout',
+    '  init                         Alias for install',
+    '  doctor                       Print target install destination',
+    '',
+    'Options:',
+    '  --target <dir>               Target root, default .',
+    '  --layout <agents|claude|codex|cursor>',
+    '  --include <a,b>              Skill names to install, default all',
+    '  --force                      Replace existing installed skill directories',
+  ].join('\n');
+}
+
+function selectedSkills(include) {
+  const selected = include.length > 0 ? include : knownSkills;
+  const unknown = selected.filter((skill) => !knownSkills.includes(skill));
+  if (unknown.length > 0) {
+    throw new Error(
+      `Unknown skill(s): ${unknown.join(', ')}. Known skills: ${knownSkills.join(', ')}`,
+    );
+  }
+  return selected;
+}
+
+function install(args) {
+  const relativeDest = layoutDirs[args.layout];
+  if (!relativeDest) {
+    throw new Error(
+      `Unknown layout: ${args.layout}. Expected one of: ${Object.keys(layoutDirs).join(', ')}`,
+    );
+  }
+  const targetRoot = path.resolve(args.target);
+  const destRoot = path.join(targetRoot, relativeDest);
+  mkdirSync(destRoot, { recursive: true });
+
+  for (const skill of selectedSkills(args.include)) {
+    const source = path.join(skillsRoot, skill);
+    const dest = path.join(destRoot, skill);
+    if (existsSync(dest)) {
+      if (!args.force) {
+        throw new Error(`Refusing to overwrite existing skill without --force: ${dest}`);
+      }
+      rmSync(dest, { recursive: true, force: true });
+    }
+    cpSync(source, dest, { recursive: true });
+    console.log(`${skill} -> ${dest}`);
+  }
+}
+
+function doctor(args) {
+  const relativeDest = layoutDirs[args.layout];
+  if (!relativeDest) {
+    throw new Error(
+      `Unknown layout: ${args.layout}. Expected one of: ${Object.keys(layoutDirs).join(', ')}`,
+    );
+  }
+  const targetRoot = path.resolve(args.target);
+  const destRoot = path.join(targetRoot, relativeDest);
+  console.log(
+    `package: ${JSON.parse(readFileSync(path.join(packageRoot, 'package.json'), 'utf8')).name}`,
+  );
+  console.log(`layout: ${args.layout}`);
+  console.log(`destination: ${destRoot}`);
+  console.log(`skills: ${knownSkills.join(', ')}`);
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.command === 'list') console.log(knownSkills.join('\n'));
+  else if (args.command === 'install' || args.command === 'init') install(args);
+  else if (args.command === 'doctor') doctor(args);
+  else {
+    console.log(usage());
+    if (args.command !== 'help' && args.command !== '--help' && args.command !== '-h')
+      process.exitCode = 1;
+  }
+}
+
+main();

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+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 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];
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +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"}

package/dist/index.js

@@ -0,0 +1,10 @@
+export const FARMSLOT_SKILLS_PACKAGE = '@farmslot/skills';
+export const FARMSLOT_SKILL_NAMES = [
+    'recipe-cook',
+    'recipe-quality',
+    'recipe-doctor',
+    'recipe-harness',
+    'project-adopt',
+];
+export const FARMSLOT_SKILL_INSTALL_LAYOUTS = ['agents', 'claude', 'codex', 'cursor'];
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +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"}

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@farmslot/skills",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "farmslot-skills": "./bin/farmslot-skills.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./skills/*": "./skills/*/SKILL.md",
+    "./schemas/*": "./schemas/*"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit --project tsconfig.json",
+    "test": "node test/prepare-cooking-run.test.cjs && node test/run-cooking-lane.test.cjs && node test/validator-loop.test.cjs && node test/package-exports.test.cjs",
+    "format": "prettier --write --ignore-path ../../.prettierignore .",
+    "format:check": "prettier --check --ignore-path ../../.prettierignore .",
+    "lint": "eslint \"src/**/*.ts\"",
+    "lint:fix": "eslint \"src/**/*.ts\" --fix",
+    "quality": "prettier --check --ignore-path ../../.prettierignore . && eslint \"src/**/*.ts\" && tsc --noEmit --project tsconfig.json && yarn build && yarn test",
+    "build": "rm -rf dist && tsc --project tsconfig.build.json",
+    "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"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "eslint": "^10.3.0",
+    "prettier": "^3.8.3",
+    "typescript": "^5.6.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deeeed/farmslot.git",
+    "directory": "packages/skills"
+  },
+  "bugs": {
+    "url": "https://github.com/deeeed/farmslot/issues"
+  },
+  "license": "MIT",
+  "homepage": "https://farmslot.io/docs/guides/recipe-skills-adoption",
+  "keywords": [
+    "farmslot",
+    "skills",
+    "recipe",
+    "validation",
+    "agentic-engineering"
+  ],
+  "files": [
+    "README.md",
+    "CHANGELOG.md",
+    "bin/**/*.mjs",
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "dist/**/*.d.ts.map",
+    "dist/**/*.js.map",
+    "schemas/**/*.json",
+    "scripts/**/*.cjs",
+    "skills/**/*.md",
+    "templates/**/*.json"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/schemas/recipe-cook-learning.schema.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "recipe-cook-learning.schema.json",
+  "type": "object",
+  "required": [
+    "run_id",
+    "scenario_type",
+    "target_repo",
+    "branch",
+    "validation_results",
+    "evidence_verdict",
+    "artifact_dir",
+    "recipe_path",
+    "next_delta",
+    "touched_files"
+  ],
+  "properties": {
+    "run_id": { "type": "string" },
+    "scenario_type": { "type": "string" },
+    "target_repo": { "type": "string" },
+    "branch": { "type": ["string", "null"] },
+    "artifact_dir": { "type": "string" },
+    "recipe_path": { "type": "string" },
+    "recipe_cook_path": { "type": ["string", "null"] },
+    "validation_results": { "type": ["object", "null"] },
+    "evidence_verdict": { "type": ["string", "null"] },
+    "next_delta": { "type": "string" },
+    "touched_files": { "type": "array", "items": { "type": "string" } }
+  },
+  "additionalProperties": true
+}

package/schemas/recipe-cook-patch-metadata.schema.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "recipe-cook-patch-metadata.schema.json",
+  "type": "object",
+  "required": [
+    "before_version_id",
+    "after_version_id",
+    "scenario_ids",
+    "touched_files",
+    "expected_score_impact"
+  ],
+  "properties": {
+    "before_version_id": { "type": "string" },
+    "after_version_id": { "type": "string" },
+    "scenario_ids": { "type": "array", "items": { "type": "string" } },
+    "touched_files": { "type": "array", "items": { "type": "string" } },
+    "expected_score_impact": { "type": "string" }
+  }
+}

package/schemas/recipe-cook-run-ledger-entry.schema.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "recipe-cook-run-ledger-entry.schema.json",
+  "type": "object",
+  "required": [
+    "run_id",
+    "version_id_under_test",
+    "task_artifact_dir",
+    "learning_artifact_path",
+    "recipe_path",
+    "recipe_cook_path",
+    "validator_manifest_path",
+    "scenario_lane",
+    "result_summary",
+    "quality_semantic",
+    "quality",
+    "pass_rate",
+    "inference_cost_usd",
+    "source_run_id"
+  ],
+  "properties": {
+    "run_id": { "type": "string" },
+    "version_id_under_test": { "type": "string" },
+    "task_artifact_dir": { "type": "string" },
+    "learning_artifact_path": { "type": "string" },
+    "recipe_path": { "type": "string" },
+    "recipe_cook_path": { "type": ["string", "null"] },
+    "validator_manifest_path": { "type": "string" },
+    "scenario_lane": { "type": "string" },
+    "result_summary": { "type": "string" },
+    "quality_semantic": { "type": "string", "enum": ["good", "ok", "bad"] },
+    "quality": { "type": "number" },
+    "pass_rate": { "type": ["number", "null"] },
+    "inference_cost_usd": { "type": ["number", "null"] },
+    "source_run_id": { "type": "string" }
+  }
+}

package/schemas/recipe-cook-validator-manifest.schema.json

@@ -0,0 +1,92 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "recipe-cook-validator-manifest.schema.json",
+  "type": "object",
+  "required": [
+    "run_id",
+    "iteration_id",
+    "base_version_id",
+    "task_artifact_dir",
+    "learning_artifact_path",
+    "recipe_path",
+    "recipe_cook_path",
+    "candidate_patch_path",
+    "validator_manifest_path",
+    "touched_files",
+    "scenario_bundle",
+    "lane_results",
+    "score_vector",
+    "decision",
+    "decision_reason"
+  ],
+  "properties": {
+    "run_id": { "type": "string" },
+    "iteration_id": { "type": "string" },
+    "base_version_id": { "type": "string" },
+    "task_artifact_dir": { "type": "string" },
+    "learning_artifact_path": { "type": "string" },
+    "recipe_path": { "type": "string" },
+    "recipe_cook_path": { "type": ["string", "null"] },
+    "candidate_patch_path": { "type": "string" },
+    "validator_manifest_path": { "type": "string" },
+    "touched_files": { "type": "array", "items": { "type": "string" } },
+    "scenario_bundle": { "type": "array", "items": { "type": "string" } },
+    "lane_results": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "lane",
+          "scenario_id",
+          "task_artifact_dir",
+          "learning_artifact_path",
+          "recipe_path",
+          "recipe_cook_path",
+          "quality_semantic",
+          "quality_reasoning",
+          "live_run_exit",
+          "pass_rate_input",
+          "inference_cost_usd",
+          "source_artifacts"
+        ],
+        "properties": {
+          "lane": { "type": "string" },
+          "scenario_id": { "type": "string" },
+          "task_artifact_dir": { "type": "string" },
+          "learning_artifact_path": { "type": "string" },
+          "recipe_path": { "type": "string" },
+          "recipe_cook_path": { "type": ["string", "null"] },
+          "quality_semantic": { "type": "string", "enum": ["good", "ok", "bad"] },
+          "quality_reasoning": { "type": "string" },
+          "live_run_exit": { "type": ["integer", "null"] },
+          "pass_rate_input": { "type": ["number", "null"] },
+          "inference_cost_usd": { "type": ["number", "null"] },
+          "source_artifacts": {
+            "type": "object",
+            "properties": {
+              "grade_path": { "type": ["string", "null"] },
+              "meta_path": { "type": ["string", "null"] },
+              "session_metrics_path": { "type": ["string", "null"] },
+              "probe_state_path": { "type": ["string", "null"] }
+            },
+            "additionalProperties": true
+          }
+        },
+        "additionalProperties": true
+      }
+    },
+    "score_vector": {
+      "type": "object",
+      "required": ["quality", "pass_rate", "cost_efficiency", "balanced_score"],
+      "properties": {
+        "quality": { "type": "number" },
+        "pass_rate": { "type": ["number", "null"] },
+        "cost_efficiency": { "type": ["number", "null"] },
+        "balanced_score": { "type": ["number", "null"] }
+      }
+    },
+    "decision": { "type": "string", "enum": ["keep", "reject"] },
+    "decision_reason": { "type": "string" }
+  },
+  "additionalProperties": true
+}

package/schemas/recipe-cook-version-ledger.schema.json

@@ -0,0 +1,49 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "recipe-cook-version-ledger.schema.json",
+  "type": "object",
+  "required": ["versions"],
+  "properties": {
+    "versions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "version_id",
+          "parent_version_id",
+          "patch_artifact_path",
+          "source_run_id",
+          "source_validator_manifest_path",
+          "source_task_artifact_dirs",
+          "source_learning_artifact_paths",
+          "scenarios_covered",
+          "aggregate_score_vector",
+          "decision",
+          "decision_rationale"
+        ],
+        "properties": {
+          "version_id": { "type": "string" },
+          "parent_version_id": { "type": "string" },
+          "patch_artifact_path": { "type": "string" },
+          "source_run_id": { "type": "string" },
+          "source_validator_manifest_path": { "type": "string" },
+          "source_task_artifact_dirs": { "type": "array", "items": { "type": "string" } },
+          "source_learning_artifact_paths": { "type": "array", "items": { "type": "string" } },
+          "scenarios_covered": { "type": "array", "items": { "type": "string" } },
+          "aggregate_score_vector": {
+            "type": "object",
+            "required": ["quality", "pass_rate", "cost_efficiency", "balanced_score"],
+            "properties": {
+              "quality": { "type": "number" },
+              "pass_rate": { "type": ["number", "null"] },
+              "cost_efficiency": { "type": ["number", "null"] },
+              "balanced_score": { "type": ["number", "null"] }
+            }
+          },
+          "decision": { "type": "string", "enum": ["keep", "reject"] },
+          "decision_rationale": { "type": "string" }
+        }
+      }
+    }
+  }
+}