@farmslot/skills 0.1.2 → 0.1.3

package/scripts/worker-terminal-contract.cjs

@@ -1,382 +1,17 @@
-/** @typedef {'complete' | 'no-change' | 'blocked'} WorkerTerminalCommand */
+'use strict';
 
-/**
- * @typedef {object} WorkerTerminalCommandSpec
- * @property {string} [report]
- * @property {string[]} artifacts
- */
+const path = require('node:path');
+const { createRequire } = require('node:module');
 
-/**
- * @typedef {object} WorkerTerminalWhenPresentRule
- * @property {string} path
- * @property {string[]} alsoRequire
- * @property {boolean} [requireRecipeQuality]
- * @property {boolean} [requireRecipeCoverage]
- */
+const requireFromHere = createRequire(__filename);
 
-/**
- * @typedef {object} WorkerTerminalProjectConfig
- * @property {boolean} [requireSignal]
- * @property {Partial<Record<WorkerTerminalCommand, WorkerTerminalCommandSpec>>} [complete]
- * @property {Partial<Record<WorkerTerminalCommand, WorkerTerminalCommandSpec>>} [no-change]
- * @property {Partial<Record<WorkerTerminalCommand, WorkerTerminalCommandSpec>>} [blocked]
- * @property {Record<string, Partial<Record<WorkerTerminalCommand, WorkerTerminalCommandSpec>>>} [flows]
- * @property {WorkerTerminalWhenPresentRule[]} [whenPresent]
- */
-
-/**
- * @typedef {object} WorkerTerminalContractDocument
- * @property {1} schemaVersion
- * @property {string} flowType
- * @property {string} [mode]
- * @property {boolean} requireSignal
- * @property {Record<WorkerTerminalCommand, WorkerTerminalCommandSpec>} commands
- * @property {WorkerTerminalWhenPresentRule[]} whenPresent
- * @property {string} resolvedAt
- * @property {'builtin' | 'project'} source
- */
-
-const TERMINAL_MARK_RE = /(?:\.\/|\{\{TASK_DIR\}\}\/)mark\s+(complete|no-change|blocked)\b/;
-const TERMINAL_COMMANDS = /** @type {const} */ (['complete', 'no-change', 'blocked']);
-
-const LEARNINGS = 'artifacts/learnings.md';
-
-const PR_DESCRIPTION = 'artifacts/pr-description.md';
-
-/** @type {Record<string, Record<WorkerTerminalCommand, WorkerTerminalCommandSpec>>} */
-const BUILTIN_FLOW_COMMANDS = {
-  dev: {
-    complete: { report: PR_DESCRIPTION, artifacts: [LEARNINGS, PR_DESCRIPTION] },
-    'no-change': {
-      report: 'artifacts/no-change-report.md',
-      artifacts: [LEARNINGS, 'artifacts/no-change-report.md'],
-    },
-    blocked: { artifacts: [] },
-  },
-  'fix-bug': {
-    complete: { report: PR_DESCRIPTION, artifacts: [LEARNINGS, PR_DESCRIPTION] },
-    'no-change': {
-      report: 'artifacts/no-change-report.md',
-      artifacts: [LEARNINGS, 'artifacts/no-change-report.md'],
-    },
-    blocked: { artifacts: [] },
-  },
-  'review-pr': {
-    complete: {
-      report: 'artifacts/review.md',
-      artifacts: [LEARNINGS, 'artifacts/review.md', 'artifacts/line-comments.json'],
-    },
-    'no-change': {
-      report: 'artifacts/no-change-report.md',
-      artifacts: [LEARNINGS, 'artifacts/no-change-report.md'],
-    },
-    blocked: { artifacts: [] },
-  },
-  'pr-complete': {
-    complete: {
-      report: 'artifacts/comments-report.md',
-      artifacts: [LEARNINGS, 'artifacts/comments-report.md'],
-    },
-    'no-change': {
-      report: 'artifacts/no-change-report.md',
-      artifacts: [LEARNINGS, 'artifacts/no-change-report.md'],
-    },
-    blocked: { artifacts: [] },
-  },
-  'merge-main': {
-    complete: {
-      report: 'artifacts/report.md',
-      artifacts: [LEARNINGS, 'artifacts/report.md'],
-    },
-    'no-change': {
-      report: 'artifacts/no-change-report.md',
-      artifacts: [LEARNINGS, 'artifacts/no-change-report.md'],
-    },
-    blocked: { artifacts: [] },
-  },
-  'ci-fix': {
-    complete: { report: 'artifacts/report.md', artifacts: [LEARNINGS, 'artifacts/report.md'] },
-    'no-change': {
-      report: 'artifacts/no-change-report.md',
-      artifacts: [LEARNINGS, 'artifacts/no-change-report.md'],
-    },
-    blocked: { artifacts: [] },
-  },
-  'self-review': {
-    complete: { artifacts: [LEARNINGS] },
-    'no-change': {
-      report: 'artifacts/no-change-report.md',
-      artifacts: [LEARNINGS, 'artifacts/no-change-report.md'],
-    },
-    blocked: { artifacts: [] },
-  },
-  'self-review-fix': {
-    complete: { report: 'artifacts/report.md', artifacts: [LEARNINGS, 'artifacts/report.md'] },
-    'no-change': {
-      report: 'artifacts/no-change-report.md',
-      artifacts: [LEARNINGS, 'artifacts/no-change-report.md'],
-    },
-    blocked: { artifacts: [] },
-  },
-  'validate-dep': {
-    complete: { report: 'artifacts/report.md', artifacts: [LEARNINGS, 'artifacts/report.md'] },
-    'no-change': {
-      report: 'artifacts/no-change-report.md',
-      artifacts: [LEARNINGS, 'artifacts/no-change-report.md'],
-    },
-    blocked: { artifacts: [] },
-  },
-};
-
-const DEFAULT_WHEN_PRESENT = [
-  {
-    path: 'artifacts/recipe.json',
-    alsoRequire: ['artifacts/recipe-coverage.md', 'artifacts/evidence-manifest.json'],
-    requireRecipeQuality: true,
-    requireRecipeCoverage: true,
-  },
-];
-
-const DEFAULT_BLOCKED = { artifacts: [] };
-const DEFAULT_NO_CHANGE = {
-  report: 'artifacts/no-change-report.md',
-  artifacts: [LEARNINGS, 'artifacts/no-change-report.md'],
-};
-const DEFAULT_COMPLETE = {
-  report: 'artifacts/report.md',
-  artifacts: [LEARNINGS, 'artifacts/report.md'],
-};
-
-/** @param {WorkerTerminalCommandSpec | undefined} spec */
-function normalizeCommandSpec(spec) {
-  if (!spec) return { artifacts: [] };
-  const artifacts = [...new Set((spec.artifacts ?? []).filter(Boolean))];
-  if (spec.report && !artifacts.includes(spec.report)) artifacts.unshift(spec.report);
-  return {
-    ...(spec.report ? { report: spec.report } : {}),
-    artifacts,
-  };
-}
-
-/** @param {Partial<Record<WorkerTerminalCommand, WorkerTerminalCommandSpec>> | undefined} layer */
-function normalizeCommandLayer(layer) {
-  /** @type {Record<WorkerTerminalCommand, WorkerTerminalCommandSpec>} */
-  const out = {
-    complete: normalizeCommandSpec(layer?.complete ?? DEFAULT_COMPLETE),
-    'no-change': normalizeCommandSpec(layer?.['no-change'] ?? DEFAULT_NO_CHANGE),
-    blocked: normalizeCommandSpec(layer?.blocked ?? DEFAULT_BLOCKED),
-  };
-  return out;
-}
-
-/**
- * @param {WorkerTerminalProjectConfig | null | undefined} projectConfig
- * @param {string} flowType
- * @param {{ mode?: string | null, now?: string }} [options]
- * @returns {WorkerTerminalContractDocument}
- */
-function resolveWorkerTerminalContract(projectConfig, flowType, options = {}) {
-  const mode = options.mode ?? undefined;
-  const now = options.now ?? new Date().toISOString();
-  const flowKey = String(flowType || '').trim() || 'unknown';
-
-  const defaultsLayer = normalizeCommandLayer({
-    complete: projectConfig?.complete,
-    'no-change': projectConfig?.['no-change'],
-    blocked: projectConfig?.blocked,
-  });
-
-  const builtin = BUILTIN_FLOW_COMMANDS[flowKey];
-  const flowLayer = projectConfig?.flows?.[flowKey];
-  /** @type {Record<WorkerTerminalCommand, WorkerTerminalCommandSpec>} */
-  const commands = {
-    complete: normalizeCommandSpec(
-      flowLayer?.complete ?? builtin?.complete ?? defaultsLayer.complete,
-    ),
-    'no-change': normalizeCommandSpec(
-      flowLayer?.['no-change'] ?? builtin?.['no-change'] ?? defaultsLayer['no-change'],
-    ),
-    blocked: normalizeCommandSpec(flowLayer?.blocked ?? builtin?.blocked ?? defaultsLayer.blocked),
-  };
-
-  let requireSignal = projectConfig?.requireSignal ?? true;
-  if (flowKey === 'pr-complete' && mode === 'interactive') {
-    requireSignal = false;
-  }
-
-  const whenPresent = Array.isArray(projectConfig?.whenPresent)
-    ? projectConfig.whenPresent.map((rule) => ({
-        path: rule.path,
-        alsoRequire: [...(rule.alsoRequire ?? [])],
-        ...(rule.requireRecipeQuality ? { requireRecipeQuality: true } : {}),
-        ...(rule.requireRecipeCoverage ? { requireRecipeCoverage: true } : {}),
-      }))
-    : DEFAULT_WHEN_PRESENT.map((rule) => ({ ...rule, alsoRequire: [...rule.alsoRequire] }));
-
-  return {
-    schemaVersion: 1,
-    flowType: flowKey,
-    ...(mode ? { mode } : {}),
-    requireSignal,
-    commands,
-    whenPresent,
-    resolvedAt: now,
-    source: projectConfig ? 'project' : 'builtin',
-  };
-}
-
-/** @param {string} content */
-function templateUsesTerminalMark(content) {
-  return (
-    TERMINAL_MARK_RE.test(content) ||
-    /mark-checklist-step\.cjs[\s\S]{0,400}?\bcomplete\b/.test(content)
-  );
-}
-
-/** @param {string} content */
-function templateTerminalCommands(content) {
-  let scope = content;
-  const checklistIdx = content.indexOf('## Checklist');
-  if (checklistIdx >= 0) {
-    scope = content.slice(checklistIdx);
-  } else {
-    const completionIdx = content.indexOf('## Completion signal');
-    if (completionIdx >= 0) scope = content.slice(completionIdx);
-    else {
-      const taskIdx = content.indexOf('## Task');
-      if (taskIdx >= 0) scope = content.slice(taskIdx);
-    }
-  }
-  const commands = new Set();
-  for (const match of scope.matchAll(
-    /(?:\.\/|\{\{TASK_DIR\}\}\/)mark\s+(complete|no-change|blocked)\b/g,
-  )) {
-    commands.add(match[1]);
-  }
-  if (commands.size === 0 && /mark-checklist-step\.cjs[\s\S]{0,400}?\bcomplete\b/.test(scope)) {
-    commands.add('complete');
-  }
-  return [...commands];
-}
-
-/**
- * @param {string} templateContent
- * @param {WorkerTerminalContractDocument} contract
- */
-/** @param {string} content */
-function templateBodyScope(content) {
-  const checklistIdx = content.indexOf('## Checklist');
-  if (checklistIdx >= 0) return content.slice(checklistIdx);
-  const completionIdx = content.indexOf('## Completion signal');
-  if (completionIdx >= 0) return content.slice(completionIdx);
-  const taskIdx = content.indexOf('## Task');
-  if (taskIdx >= 0) return content.slice(taskIdx);
-  return content;
-}
-
-/**
- * Deterministic structure checks beyond terminal artifact contract.
- * @param {string} templateContent
- */
-function lintWorkerTemplateStructure(templateContent) {
-  /** @type {string[]} */
-  const issues = [];
-  if (/(?<!\{)\{TASK_DIR\}(?!\})/.test(templateContent)) {
-    issues.push('uses `{TASK_DIR}` — must be `{{TASK_DIR}}` (double braces)');
-  }
-
-  if (
-    templateUsesTerminalMark(templateContent) &&
-    !templateContent.includes('## Checklist') &&
-    !templateContent.includes('## Completion signal')
-  ) {
-    issues.push('terminal template missing `## Checklist` or `## Completion signal` section');
-  }
-
-  if (!templateContent.includes('## Task') && !templateContent.includes('TASK_DIR:')) {
-    issues.push('missing `## Task` block or `TASK_DIR:` metadata');
-  }
-
-  const scope = templateBodyScope(templateContent);
-  const steps = [...scope.matchAll(/\*\*(\d+)\./g)].map((match) => match[1]);
-  const duplicateSteps = [...new Set(steps.filter((step, index) => steps.indexOf(step) !== index))];
-  if (duplicateSteps.length > 0) {
-    issues.push(`duplicate checklist step number(s): ${duplicateSteps.join(', ')}`);
-  }
-
-  return issues;
-}
-
-function lintWorkerTemplateAgainstContract(templateContent, contract) {
-  /** @type {string[]} */
-  const issues = [];
-  if (!templateUsesTerminalMark(templateContent)) {
-    issues.push(
-      'terminal worker template must instruct `./mark complete`, `./mark no-change`, or `./mark blocked`',
-    );
-    return issues;
-  }
-
-  if (contract.requireSignal) {
-    if (!templateUsesTerminalMark(templateContent)) {
-      issues.push(
-        'requireSignal is true but template has no terminal `./mark` or mark-checklist-step command',
-      );
-    }
-    if (/never hand-write `SIGNAL\.json`|Do not write.*SIGNAL\.json/i.test(templateContent)) {
-      // allowed when paired with mark instructions
-    }
-  }
-
-  const commands = templateTerminalCommands(templateContent);
-  const commandSet = new Set(commands.length > 0 ? commands : ['complete']);
-  for (const command of commandSet) {
-    const spec = contract.commands[/** @type {WorkerTerminalCommand} */ (command)];
-    if (!spec) continue;
-    for (const artifactPath of spec.artifacts) {
-      if (!templateContent.includes(artifactPath)) {
-        issues.push(
-          `missing checklist/reference to required artifact \`${artifactPath}\` for \`${command}\``,
-        );
-      }
-    }
-  }
-
-  return issues;
-}
-
-/**
- * @param {WorkerTerminalContractDocument} contract
- * @param {WorkerTerminalCommand} command
- * @param {(relPath: string) => boolean} fileExists
- */
-function expandedArtifactsForCommand(contract, command, fileExists) {
-  const spec = contract.commands[command] ?? { artifacts: [] };
-  const required = new Set(spec.artifacts);
-  for (const rule of contract.whenPresent ?? []) {
-    if (!rule.path || !fileExists(rule.path)) continue;
-    for (const path of rule.alsoRequire ?? []) required.add(path);
+function resolveRuntimeScript() {
+  try {
+    return requireFromHere.resolve('@farmslot/agent-runtime/scripts/worker-terminal-contract.cjs');
+  } catch (error) {
+    if (error.code !== 'MODULE_NOT_FOUND') throw error;
+    return path.resolve(__dirname, '../../agent-runtime/scripts/worker-terminal-contract.cjs');
   }
-  return {
-    report: spec.report,
-    artifacts: [...required],
-    requireRecipeQuality: (contract.whenPresent ?? []).some(
-      (rule) => rule.path && fileExists(rule.path) && rule.requireRecipeQuality,
-    ),
-    requireRecipeCoverage: (contract.whenPresent ?? []).some(
-      (rule) => rule.path && fileExists(rule.path) && rule.requireRecipeCoverage,
-    ),
-  };
 }
 
-module.exports = {
-  TERMINAL_COMMANDS,
-  BUILTIN_FLOW_COMMANDS,
-  resolveWorkerTerminalContract,
-  lintWorkerTemplateAgainstContract,
-  lintWorkerTemplateStructure,
-  templateUsesTerminalMark,
-  templateTerminalCommands,
-  templateBodyScope,
-  expandedArtifactsForCommand,
-};
+module.exports = require(resolveRuntimeScript());

package/skills/packet/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: packet
+description: Communicate complex agent output as compact, reviewable Farmslot operator packets with artifact anchors and safe action requests
+compatibility: Claude, Codex, Cursor, and Markdown skill runners with access to the working directory
+metadata:
+  package: '@farmslot/skills'
+  adr: ADR-048
+  outputs: artifacts/interactive/*.packet.json and optional sibling markdown when supported
+allowed-tools: Read Write Bash(rg:*) Bash(node:*) Bash(git:*)
+---
+
+# Interactive Operator Packets
+
+Use this skill when a plan, decision, blocker, comparison, or evidence review would be easier for the operator to inspect as a structured review packet than as terminal prose.
+
+This skill teaches the communication pattern. It does not assume Farmslot runtime support is installed. If the current project does not support Interactive Operator Packets yet, produce a concise markdown fallback and do not claim that Command Center or Companion can render it.
+
+## Use When
+
+- You need the operator to review a plan before implementation.
+- You need a decision with clear options and consequences.
+- You found a blocker and need targeted human input.
+- You want feedback anchored to a diff, artifact, screenshot, recipe result, or report section.
+- You are summarizing evidence and want the operator to approve, reject, or request a revision.
+
+## Do Not Use When
+
+- A one-sentence answer is enough.
+- The operator asked for raw terminal output.
+- The action would be unsafe without an existing Farmslot confirmation surface.
+- You would need to execute arbitrary HTML or JavaScript to make the packet useful.
+- The packet would only restate a normal `SIGNAL.json`, recipe manifest, or PR description.
+
+## Packet Contract
+
+When the project supports packets, write JSON to:
+
+```text
+artifacts/interactive/<short-id>.packet.json
+```
+
+Use this shape:
+
+```json
+{
+  "schema": "farmslot.interactive.operator-packet.v1",
+  "id": "review-plan-1",
+  "title": "Review implementation plan",
+  "intent": "plan",
+  "summary": "Confirm the scoped approach before changes start.",
+  "body": {
+    "format": "markdown",
+    "path": "artifacts/interactive/review-plan-1.md"
+  },
+  "anchors": [
+    {
+      "id": "diff-risk",
+      "label": "Risky diff area",
+      "artifactPath": "artifacts/diff.txt",
+      "line": 42
+    }
+  ],
+  "actions": [
+    {
+      "id": "approve",
+      "label": "Approve plan",
+      "kind": "terminal.send",
+      "safety": "operator-confirmed",
+      "payload": {
+        "text": "Approved packet review-plan-1. Proceed with the scoped plan."
+      }
+    }
+  ],
+  "createdAt": "2026-07-03T00:00:00.000Z"
+}
+```
+
+Keep `body.text` or the sibling markdown short. A packet is a review surface, not a report dump.
+
+## Writing Rules
+
+1. Start with the operator's next decision or review task.
+2. Use a short title and one-sentence summary.
+3. Pick one intent: `plan`, `decision`, `review`, `blocker`, `evidence`, or `comparison`.
+4. Anchor feedback to concrete artifacts when possible.
+5. Offer only actions the operator can understand and confirm.
+6. Print a terminal fallback after writing the packet.
+
+Terminal fallback format:
+
+```text
+Interactive packet ready: <title>
+Packet: artifacts/interactive/<short-id>.packet.json
+Fallback: artifacts/interactive/<short-id>.md
+```
+
+If Farmslot deep links are known to be supported, also print the route. Never encode a mutating action in the link.
+
+## Action Safety
+
+Allowed v1 action kinds:
+
+- `terminal.send` — send a concise approved response back to the worker.
+- `decision.resolve` — resolve an existing Farmslot decision.
+- `copy` — copy text for manual use.
+- `open-artifact` — open a referenced artifact.
+
+Rules:
+
+- Mark mutating actions as `operator-confirmed`.
+- Keep generated `terminal.send` text short and specific.
+- Do not hide shell commands inside action payloads.
+- Do not ask the UI to execute arbitrary RPC methods.
+- Do not treat a deep link as approval.
+
+## Fallback Mode
+
+If packet runtime support is absent:
+
+1. Write the same information as markdown in the conversation or artifact directory.
+2. Include anchors as plain file paths and line numbers.
+3. Ask for the operator response in normal chat/terminal.
+4. Do not say that a packet has been opened, rendered, or sent to Companion.
+
+## Response Handling
+
+When the operator responds to a packet, continue with the referenced packet id and anchor ids:
+
+```text
+Received response for packet review-plan-1:
+- action: approve
+- anchor: diff-risk
+- note: Keep the protocol typed; defer HTML.
+```
+
+Then act on the feedback through the normal task flow. The packet is a communication aid; the runner session remains the source of execution truth.

package/skills/recipe-quality/SKILL.md

@@ -43,3 +43,5 @@ Return:
 - weak or missing claims
 - evidence gaps
 - concrete recipe delta
+
+When the task requires `artifacts/recipe-quality.json`, do not hand-author the full schema. Provide the compact fields to `farmslot-agent recipe-quality build` (or `buildRecipeQualityArtifact()` from `@farmslot/agent-runtime`) so the artifact passes the `@farmslot/protocol` validator.