selftune 0.2.22 → 0.2.24

package/cli/selftune/workflows/skill-scaffold.ts

@@ -0,0 +1,241 @@
+/**
+ * skill-scaffold.ts
+ *
+ * Builds draft workflow skills from repeated telemetry-discovered workflows.
+ * The draft is preview-first by default so agents can review the scaffold before
+ * writing it into a local skill registry.
+ */
+
+import { join } from "node:path";
+
+import type { DiscoveredWorkflow } from "../types.js";
+import { findGitRepositoryRoot } from "../utils/skill-discovery.js";
+
+export interface WorkflowSkillDraft {
+  title: string;
+  skill_name: string;
+  description: string;
+  output_dir: string;
+  skill_dir: string;
+  skill_path: string;
+  content: string;
+  source_workflow: {
+    workflow_id: string;
+    skills: string[];
+    occurrence_count: number;
+    synergy_score: number;
+    representative_query: string;
+  };
+}
+
+export interface WorkflowSkillDraftOptions {
+  outputDir?: string;
+  skillName?: string;
+  description?: string;
+  cwd?: string;
+}
+
+const STOPWORDS = new Set([
+  "a",
+  "an",
+  "and",
+  "for",
+  "from",
+  "in",
+  "into",
+  "of",
+  "on",
+  "or",
+  "the",
+  "to",
+  "with",
+]);
+
+function splitWords(value: string): string[] {
+  return value
+    .replace(/[^A-Za-z0-9]+/g, " ")
+    .trim()
+    .split(/\s+/)
+    .filter(Boolean);
+}
+
+function titleCase(value: string): string {
+  return splitWords(value)
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
+    .join(" ");
+}
+
+export function slugifyWorkflowSkillName(value: string): string {
+  return splitWords(value)
+    .map((word) => word.toLowerCase())
+    .join("-")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "");
+}
+
+function deriveBaseLabel(workflow: DiscoveredWorkflow): string {
+  const filteredQueryWords = splitWords(workflow.representative_query).filter(
+    (word) => !STOPWORDS.has(word.toLowerCase()),
+  );
+
+  if (filteredQueryWords.length >= 2) {
+    return filteredQueryWords.slice(0, 5).join(" ");
+  }
+
+  return `${workflow.skills.join(" ")} workflow`;
+}
+
+function formatList(items: string[]): string {
+  if (items.length === 0) return "";
+  if (items.length === 1) return items[0];
+  if (items.length === 2) return `${items[0]} and ${items[1]}`;
+  return `${items.slice(0, -1).join(", ")}, and ${items[items.length - 1]}`;
+}
+
+function wrapFoldedScalar(value: string, width = 78): string[] {
+  const words = value.split(/\s+/).filter(Boolean);
+  const lines: string[] = [];
+  let current = "";
+
+  for (const word of words) {
+    const candidate = current.length === 0 ? word : `${current} ${word}`;
+    if (candidate.length > width && current.length > 0) {
+      lines.push(`  ${current}`);
+      current = word;
+    } else {
+      current = candidate;
+    }
+  }
+
+  if (current.length > 0) lines.push(`  ${current}`);
+  return lines.length > 0 ? lines : ["  "];
+}
+
+export function getDefaultWorkflowSkillOutputDir(cwd: string = process.cwd()): string {
+  const repoRoot = findGitRepositoryRoot(cwd);
+  return join(repoRoot ?? cwd, ".agents", "skills");
+}
+
+export function buildWorkflowSkillDescription(
+  workflow: DiscoveredWorkflow,
+  override?: string,
+): string {
+  if (override && override.trim().length > 0) return override.trim();
+
+  const chain = formatList(workflow.skills);
+  const query = workflow.representative_query.trim();
+  if (query.length > 0) {
+    return `Use when the user wants to ${query}. Coordinates ${chain} in sequence.`;
+  }
+
+  return `Use when the task consistently needs ${chain} in sequence.`;
+}
+
+export function buildWorkflowSkillContent(
+  workflow: DiscoveredWorkflow,
+  title: string,
+  skillName: string,
+  description: string,
+): string {
+  const workflowName = title.endsWith("Workflow") ? title : `${title} Workflow`;
+  const chain = workflow.skills.join(" → ");
+  const query = workflow.representative_query.trim();
+  const foldedDescription = wrapFoldedScalar(description).join("\n");
+
+  const whenToUseLines =
+    query.length > 0
+      ? [
+          `- The user asks to "${query}"`,
+          `- The request repeatedly needs this skill chain: ${chain}`,
+        ]
+      : [`- The request repeatedly needs this skill chain: ${chain}`];
+
+  const executionPlanLines = workflow.skills.map(
+    (skill, index) =>
+      `${index + 1}. Invoke \`${skill}\` in its established role for this workflow.`,
+  );
+
+  return `---
+name: ${skillName}
+description: >
+${foldedDescription}
+metadata:
+  author: selftune-autogen
+  version: 0.1.0
+  category: developer-tools
+  generated_by: selftune workflows scaffold
+  source_workflow_id: ${workflow.workflow_id}
+---
+
+# ${title}
+
+This draft skill was scaffolded by selftune from repeated workflow telemetry.
+Review the routing language and execution notes before broad distribution.
+
+## When to Use
+
+${whenToUseLines.join("\n")}
+
+## Execution Plan
+
+${executionPlanLines.join("\n")}
+
+## Workflows
+
+### ${workflowName}
+- **Skills:** ${chain}
+${query.length > 0 ? `- **Trigger:** ${query}\n` : ""}- **Source:** Discovered from ${workflow.occurrence_count} sessions (synergy: ${workflow.synergy_score.toFixed(2)})
+
+## Notes
+
+- This is a proposal scaffold, not a silently published marketplace skill.
+- Add tighter scope boundaries and richer examples before publishing.
+`;
+}
+
+export function buildWorkflowSkillDraft(
+  workflow: DiscoveredWorkflow,
+  options: WorkflowSkillDraftOptions = {},
+): WorkflowSkillDraft {
+  const baseLabel = options.skillName?.trim() || deriveBaseLabel(workflow);
+  const skillName = slugifyWorkflowSkillName(baseLabel);
+  const title = titleCase(baseLabel) || titleCase(`${workflow.skills.join(" ")} workflow`);
+  const description = buildWorkflowSkillDescription(workflow, options.description);
+  const outputDir = options.outputDir?.trim() || getDefaultWorkflowSkillOutputDir(options.cwd);
+  const skillDir = join(outputDir, skillName);
+  const skillPath = join(skillDir, "SKILL.md");
+
+  return {
+    title,
+    skill_name: skillName,
+    description,
+    output_dir: outputDir,
+    skill_dir: skillDir,
+    skill_path: skillPath,
+    content: buildWorkflowSkillContent(workflow, title, skillName, description),
+    source_workflow: {
+      workflow_id: workflow.workflow_id,
+      skills: workflow.skills,
+      occurrence_count: workflow.occurrence_count,
+      synergy_score: workflow.synergy_score,
+      representative_query: workflow.representative_query,
+    },
+  };
+}
+
+export function formatWorkflowSkillDraft(draft: WorkflowSkillDraft): string {
+  const lines = [
+    `Draft workflow skill: ${draft.title}`,
+    `Skill name: ${draft.skill_name}`,
+    `Output path: ${draft.skill_path}`,
+    `Source workflow: ${draft.source_workflow.workflow_id}`,
+    `Occurrences: ${draft.source_workflow.occurrence_count} | Synergy: ${draft.source_workflow.synergy_score.toFixed(2)}`,
+  ];
+
+  if (draft.source_workflow.representative_query.trim().length > 0) {
+    lines.push(`Representative query: "${draft.source_workflow.representative_query.trim()}"`);
+  }
+
+  lines.push("", draft.content.trimEnd());
+  return lines.join("\n");
+}

package/cli/selftune/workflows/workflows.ts

@@ -8,13 +8,14 @@
  *  - cliMain()          (reads logs, discovers workflows, prints output or saves)
  */
 
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { parseArgs } from "node:util";
 
 import { getDb } from "../localdb/db.js";
 import { querySessionTelemetry, querySkillUsageRecords } from "../localdb/queries.js";
 import type {
   CodifiedWorkflow,
+  DiscoveredWorkflow,
   SessionTelemetryRecord,
   SkillUsageRecord,
   WorkflowDiscoveryReport,
@@ -22,6 +23,38 @@ import type {
 import { CLIError } from "../utils/cli-error.js";
 import { discoverWorkflows } from "./discover.js";
 import { appendWorkflow } from "./skill-md-writer.js";
+import { buildWorkflowSkillDraft, formatWorkflowSkillDraft } from "./skill-scaffold.js";
+
+function resolveWorkflowSelection(
+  report: WorkflowDiscoveryReport,
+  selection: string | undefined,
+): DiscoveredWorkflow {
+  if (!selection) {
+    throw new CLIError(
+      "Usage: selftune workflows <save|scaffold> <name-or-index>",
+      "MISSING_FLAG",
+      "Provide a workflow name or index (e.g., selftune workflows scaffold 1).",
+    );
+  }
+
+  let workflow = report.workflows.find((w) => w.workflow_id === selection);
+  if (!workflow) {
+    const idx = Number.parseInt(selection, 10);
+    if (!Number.isNaN(idx) && idx >= 1 && idx <= report.workflows.length) {
+      workflow = report.workflows[idx - 1];
+    }
+  }
+
+  if (!workflow) {
+    throw new CLIError(
+      `No workflow found matching "${selection}".`,
+      "INVALID_FLAG",
+      "Run 'selftune workflows' to see discovered workflows and their indices.",
+    );
+  }
+
+  return workflow;
+}
 
 // ---------------------------------------------------------------------------
 // formatWorkflows — pure formatter
@@ -69,12 +102,41 @@ export async function cliMain(): Promise<void> {
       window: { type: "string" },
       skill: { type: "string" },
       "skill-path": { type: "string" },
+      "output-dir": { type: "string" },
+      "skill-name": { type: "string" },
+      description: { type: "string" },
+      write: { type: "boolean" },
+      force: { type: "boolean" },
       json: { type: "boolean" },
+      help: { type: "boolean", short: "h" },
     },
     strict: true,
     allowPositionals: true,
   });
 
+  if (values.help) {
+    console.log(`selftune workflows — Discover repeated multi-skill patterns
+
+Usage:
+  selftune workflows [options]
+  selftune workflows save <name-or-index> [--skill-path <path>]
+  selftune workflows scaffold <name-or-index> [--output-dir <path>] [--skill-name <name>] [--description <text>] [--write] [--force] [--json]
+
+Options:
+  --min-occurrences <n>  Minimum workflow frequency to show (default: 3)
+  --window <n>           Only analyze the most recent N sessions
+  --skill <name>         Only show workflows containing the named skill
+  --skill-path <path>    Target SKILL.md for the save subcommand
+  --output-dir <path>    Target skill registry dir for scaffold previews/writes
+  --skill-name <name>    Override the generated draft skill name
+  --description <text>   Override the generated draft skill description
+  --write                Persist the scaffolded draft skill to disk
+  --force                Overwrite an existing scaffold path when combined with --write
+  --json                 Emit machine-readable JSON
+  -h, --help             Show this help message`);
+    process.exit(0);
+  }
+
   const subcommand = positionals[0];
   const minOccurrences = values["min-occurrences"]
     ? Number.parseInt(values["min-occurrences"], 10)
@@ -101,31 +163,7 @@ export async function cliMain(): Promise<void> {
 
   if (subcommand === "save") {
     // Save subcommand: find workflow, append to SKILL.md
-    const nameArg = positionals[1];
-    if (!nameArg) {
-      throw new CLIError(
-        "Usage: selftune workflows save <name-or-index>",
-        "MISSING_FLAG",
-        "Provide a workflow name or index (e.g., selftune workflows save 1).",
-      );
-    }
-
-    // Match by numeric index (1-based) or workflow_id
-    let workflow = report.workflows.find((w) => w.workflow_id === nameArg);
-    if (!workflow) {
-      const idx = Number.parseInt(nameArg, 10);
-      if (!Number.isNaN(idx) && idx >= 1 && idx <= report.workflows.length) {
-        workflow = report.workflows[idx - 1];
-      }
-    }
-
-    if (!workflow) {
-      throw new CLIError(
-        `No workflow found matching "${nameArg}".`,
-        "INVALID_FLAG",
-        "Run 'selftune workflows' to see discovered workflows and their indices.",
-      );
-    }
+    const workflow = resolveWorkflowSelection(report, positionals[1]);
 
     // Determine SKILL.md path
     let skillPath = values["skill-path"];
@@ -187,6 +225,42 @@ export async function cliMain(): Promise<void> {
     return;
   }
 
+  if (subcommand === "scaffold") {
+    const workflow = resolveWorkflowSelection(report, positionals[1]);
+    const draft = buildWorkflowSkillDraft(workflow, {
+      outputDir: values["output-dir"],
+      skillName: values["skill-name"],
+      description: values.description,
+    });
+
+    if (values.write) {
+      if (existsSync(draft.skill_path) && !values.force) {
+        throw new CLIError(
+          `Refusing to overwrite existing draft at ${draft.skill_path}.`,
+          "FILE_EXISTS",
+          "Re-run with --force to overwrite the existing draft skill.",
+        );
+      }
+
+      mkdirSync(draft.skill_dir, { recursive: true });
+      writeFileSync(draft.skill_path, draft.content, "utf-8");
+
+      if (values.json || !process.stdout.isTTY) {
+        console.log(JSON.stringify({ ...draft, written: true }, null, 2));
+      } else {
+        console.log(`Scaffolded skill "${draft.skill_name}" to ${draft.skill_path}`);
+      }
+      return;
+    }
+
+    if (values.json || !process.stdout.isTTY) {
+      console.log(JSON.stringify({ ...draft, written: false }, null, 2));
+    } else {
+      console.log(formatWorkflowSkillDraft(draft));
+    }
+    return;
+  }
+
   // Default: discover and display
   if (values.json || !process.stdout.isTTY) {
     console.log(JSON.stringify(report, null, 2));

package/node_modules/@selftune/telemetry-contract/fixtures/complete-push.ts

@@ -1,4 +1,4 @@
-import type { PushPayloadV2 } from "../src/schemas.js";
+import type { PushPayloadV2 } from "../src/types.js";
 
 /**
  * A valid PushPayloadV2 with at least one of every record type.

package/node_modules/@selftune/telemetry-contract/fixtures/evidence-only-push.ts

@@ -1,4 +1,4 @@
-import type { PushPayloadV2 } from "../src/schemas.js";
+import type { PushPayloadV2 } from "../src/types.js";
 
 /**
  * A valid PushPayloadV2 with only evolution_evidence entries and
@@ -7,7 +7,7 @@ import type { PushPayloadV2 } from "../src/schemas.js";
 export const evidenceOnlyPush: PushPayloadV2 = {
   schema_version: "2.0",
   client_version: "0.9.0",
-  push_id: "d4e5f6a7-b8c9-0123-defa-234567890123",
+  push_id: "d4e5f6a7-b8c9-8123-9efa-234567890123",
   normalizer_version: "0.2.1",
   canonical: {
     sessions: [],

package/node_modules/@selftune/telemetry-contract/fixtures/golden.test.ts

@@ -1,7 +1,6 @@
 import { describe, expect, test } from "bun:test";
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
-
 import { CANONICAL_SCHEMA_VERSION } from "../src/types.js";
 import { isCanonicalRecord } from "../src/validators.js";
 

package/node_modules/@selftune/telemetry-contract/fixtures/partial-push-no-sessions.ts

@@ -1,4 +1,4 @@
-import type { PushPayloadV2 } from "../src/schemas.js";
+import type { PushPayloadV2 } from "../src/types.js";
 
 /**
  * A valid PushPayloadV2 with zero sessions but non-empty evolution_evidence.

package/node_modules/@selftune/telemetry-contract/fixtures/partial-push-unresolved-parents.ts

@@ -1,4 +1,4 @@
-import type { PushPayloadV2 } from "../src/schemas.js";
+import type { PushPayloadV2 } from "../src/types.js";
 
 /**
  * A valid PushPayloadV2 with invocations and prompts that reference a
@@ -10,7 +10,7 @@ import type { PushPayloadV2 } from "../src/schemas.js";
 export const partialPushUnresolvedParents: PushPayloadV2 = {
   schema_version: "2.0",
   client_version: "0.9.0",
-  push_id: "c3d4e5f6-a7b8-9012-cdef-123456789012",
+  push_id: "c3d4e5f6-a7b8-8012-8def-123456789012",
   normalizer_version: "0.2.1",
   canonical: {
     sessions: [],

package/node_modules/@selftune/telemetry-contract/package.json

@@ -13,9 +13,9 @@
   "type": "module",
   "exports": {
     ".": "./index.ts",
-    "./schemas": "./src/schemas.ts",
     "./types": "./src/types.ts",
     "./validators": "./src/validators.ts",
+    "./schemas": "./src/schemas.ts",
     "./fixtures": "./fixtures/index.ts"
   },
   "dependencies": {

package/node_modules/@selftune/telemetry-contract/src/index.ts

@@ -1,2 +1,3 @@
+export * from "./schemas.js";
 export * from "./types.js";
 export * from "./validators.js";

package/node_modules/@selftune/telemetry-contract/src/schemas.ts

@@ -1,5 +1,13 @@
-import { z } from "zod";
+/**
+ * Zod validation schemas for all canonical telemetry record types
+ * and the PushPayloadV2 envelope.
+ *
+ * This is the single source of truth -- cloud consumers should import
+ * from @selftune/telemetry-contract/schemas instead of maintaining
+ * their own copies.
+ */
 
+import { z } from "zod";
 import {
   CANONICAL_CAPTURE_MODES,
   CANONICAL_COMPLETION_STATUSES,
@@ -11,6 +19,8 @@ import {
   CANONICAL_SOURCE_SESSION_KINDS,
 } from "./types.js";
 
+// ---------- Shared enum schemas ----------
+
 export const canonicalPlatformSchema = z.enum(CANONICAL_PLATFORMS);
 export const captureModeSchema = z.enum(CANONICAL_CAPTURE_MODES);
 export const sourceSessionKindSchema = z.enum(CANONICAL_SOURCE_SESSION_KINDS);
@@ -19,6 +29,8 @@ export const invocationModeSchema = z.enum(CANONICAL_INVOCATION_MODES);
 export const completionStatusSchema = z.enum(CANONICAL_COMPLETION_STATUSES);
 export const recordKindSchema = z.enum(CANONICAL_RECORD_KINDS);
 
+// ---------- Shared structural schemas ----------
+
 export const rawSourceRefSchema = z.object({
   path: z.string().optional(),
   line: z.number().int().nonnegative().optional(),
@@ -42,6 +54,8 @@ export const canonicalSessionRecordBaseSchema = canonicalRecordBaseSchema.extend
   session_id: z.string().min(1),
 });
 
+// ---------- Canonical record schemas ----------
+
 export const CanonicalSessionRecordSchema = canonicalSessionRecordBaseSchema.extend({
   record_kind: z.literal("session"),
   external_session_id: z.string().optional(),
@@ -126,10 +140,13 @@ export const CanonicalEvolutionEvidenceRecordSchema = z.object({
   evidence_id: z.string().min(1),
   skill_name: z.string().min(1),
   proposal_id: z.string().optional(),
+  timestamp: z.string().datetime().optional(),
+  skill_path: z.string().optional(),
   target: z.string().min(1),
   stage: z.string().min(1),
   rationale: z.string().optional(),
   confidence: z.number().min(0).max(1).optional(),
+  details: z.string().optional(),
   original_text: z.string().optional(),
   proposed_text: z.string().optional(),
   eval_set_json: z.unknown().optional(),
@@ -137,6 +154,39 @@ export const CanonicalEvolutionEvidenceRecordSchema = z.object({
   raw_source_ref: rawSourceRefSchema.optional(),
 });
 
+export const CanonicalGradingResultRecordSchema = z.object({
+  grading_id: z.string().min(1),
+  session_id: z.string().min(1),
+  skill_name: z.string().min(1),
+  transcript_path: z.string().nullable().optional(),
+  graded_at: z.string().min(1),
+  pass_rate: z.number().min(0).max(1).nullable().optional(),
+  mean_score: z.number().min(0).max(1).nullable().optional(),
+  score_std_dev: z.number().nullable().optional(),
+  passed_count: z.number().int().nonnegative().nullable().optional(),
+  failed_count: z.number().int().nonnegative().nullable().optional(),
+  total_count: z.number().int().nonnegative().nullable().optional(),
+  expectations_json: z.string().nullable().optional(),
+  claims_json: z.string().nullable().optional(),
+  eval_feedback_json: z.string().nullable().optional(),
+  failure_feedback_json: z.string().nullable().optional(),
+  execution_metrics_json: z.string().nullable().optional(),
+});
+
+export const CanonicalImprovementSignalRecordSchema = z.object({
+  signal_id: z.string().min(1),
+  timestamp: z.string().min(1),
+  session_id: z.string().min(1),
+  query: z.string().min(1),
+  signal_type: z.string().min(1),
+  mentioned_skill: z.string().nullable().optional(),
+  consumed: z.boolean(),
+  consumed_at: z.string().nullable().optional(),
+  consumed_by_run: z.string().nullable().optional(),
+});
+
+// ---------- Orchestrate run schemas ----------
+
 export const OrchestrateRunSkillActionSchema = z.object({
   skill: z.string().min(1),
   action: z.enum(["evolve", "watch", "skip"]),
@@ -163,12 +213,12 @@ export const PushOrchestrateRunRecordSchema = z.object({
   skill_actions: z.array(OrchestrateRunSkillActionSchema),
 });
 
+// ---------- Push V2 envelope ----------
+
 export const PushPayloadV2Schema = z.object({
   schema_version: z.literal("2.0"),
   client_version: z.string().min(1),
-  // Queue-generated push IDs are typically UUIDs, but the wire contract only
-  // requires a stable non-empty idempotency key.
-  push_id: z.string().min(1),
+  push_id: z.string().uuid(),
   normalizer_version: z.string().min(1),
   canonical: z.object({
     sessions: z.array(CanonicalSessionRecordSchema).min(0),
@@ -178,10 +228,14 @@ export const PushPayloadV2Schema = z.object({
     normalization_runs: z.array(CanonicalNormalizationRunRecordSchema).min(0),
     evolution_evidence: z.array(CanonicalEvolutionEvidenceRecordSchema).optional(),
     orchestrate_runs: z.array(PushOrchestrateRunRecordSchema).optional(),
+    grading_results: z.array(CanonicalGradingResultRecordSchema).optional(),
+    improvement_signals: z.array(CanonicalImprovementSignalRecordSchema).optional(),
   }),
 });
 
-export type PushPayloadV2 = z.infer<typeof PushPayloadV2Schema>;
+// ---------- Inferred types from Zod schemas ----------
+
+export type ZodPushPayloadV2 = z.infer<typeof PushPayloadV2Schema>;
 export type ZodCanonicalSessionRecord = z.infer<typeof CanonicalSessionRecordSchema>;
 export type ZodCanonicalPromptRecord = z.infer<typeof CanonicalPromptRecordSchema>;
 export type ZodCanonicalSkillInvocationRecord = z.infer<
@@ -194,4 +248,8 @@ export type ZodCanonicalNormalizationRunRecord = z.infer<
 export type ZodCanonicalEvolutionEvidenceRecord = z.infer<
   typeof CanonicalEvolutionEvidenceRecordSchema
 >;
+export type ZodCanonicalGradingResultRecord = z.infer<typeof CanonicalGradingResultRecordSchema>;
+export type ZodCanonicalImprovementSignalRecord = z.infer<
+  typeof CanonicalImprovementSignalRecordSchema
+>;
 export type ZodPushOrchestrateRunRecord = z.infer<typeof PushOrchestrateRunRecordSchema>;