@hassangameryt/freeflow 0.8.0 → 0.9.0

package/skills/write-skill/scripts/lib/skill-author.mjs

@@ -605,6 +605,7 @@ async function analyzeSkill(directory, packageDirectory) {
   });
 
   return {
+    readable: true,
     skillDirectory,
     packageRoot,
     frontmatter: document.frontmatter,
@@ -619,17 +620,210 @@ function emptyResources() {
   return { localReferences: [], packageDependencies: [], scripts: [], unlinkedFiles: [] };
 }
 
-export async function validateSkill({ directory, packageRoot }) {
+// Link cycles among the Markdown files a skill reaches: its own references and the package files they link to,
+// followed transitively inside the package root. A link to any SKILL.md is a route or a pointer back to an owner,
+// not an edge: routing between skills may be cyclic by design. A cycle is reported as a fact for the author, not as
+// a validation error.
+async function linkCycles(skillDirectory, packageRoot) {
+  const graph = new Map();
+  const queue = [path.join(skillDirectory, "SKILL.md")];
+  while (queue.length) {
+    const source = queue.shift();
+    if (graph.has(source)) continue;
+    let contents;
+    try {
+      contents = await readFile(source, "utf8");
+    } catch {
+      graph.set(source, []);
+      continue;
+    }
+    const targets = new Set();
+    for (const link of markdownLinks(contents)) {
+      const target = path.resolve(path.dirname(source), link);
+      if (target === source || path.basename(target) === "SKILL.md" || path.extname(target).toLowerCase() !== ".md")
+        continue;
+      if (!isContained(packageRoot, target)) continue;
+      try {
+        await access(target, fsConstants.R_OK);
+      } catch {
+        continue;
+      }
+      targets.add(target);
+      queue.push(target);
+    }
+    graph.set(source, [...targets]);
+  }
+
+  let counter = 0;
+  const stack = [];
+  const onStack = new Set();
+  const order = new Map();
+  const low = new Map();
+  const cycles = [];
+  const visit = (node) => {
+    order.set(node, counter);
+    low.set(node, counter);
+    counter += 1;
+    stack.push(node);
+    onStack.add(node);
+    for (const next of graph.get(node) ?? []) {
+      if (!order.has(next)) {
+        visit(next);
+        low.set(node, Math.min(low.get(node), low.get(next)));
+      } else if (onStack.has(next)) {
+        low.set(node, Math.min(low.get(node), order.get(next)));
+      }
+    }
+    if (low.get(node) !== order.get(node)) return;
+    const component = [];
+    let member;
+    do {
+      member = stack.pop();
+      onStack.delete(member);
+      component.push(member);
+    } while (member !== node);
+    if (component.length > 1 && component.some((file) => isContained(skillDirectory, file))) {
+      cycles.push(component.map((file) => relativePath(skillDirectory, file)).sort());
+    }
+  };
+  for (const node of graph.keys()) if (!order.has(node)) visit(node);
+  return cycles.sort((left, right) => left[0].localeCompare(right[0]));
+}
+
+function tableCells(line) {
+  return line
+    .trim()
+    .replace(/^\|/, "")
+    .replace(/\|$/, "")
+    .split("|")
+    .map((cell) => cell.trim());
+}
+
+// Routing-map parity: the map's row for this skill names the same sibling routes and direct resources as the links
+// in its SKILL.md. A route is a link to another skill's SKILL.md; the row names it by directory name in backticks or
+// by a link. Every other direct link is a resource, named in the row by a link.
+async function checkRoutingMap({ skillDirectory, body, routingMap }) {
+  const mapFile = path.resolve(routingMap);
+  const mapPath = relativePath(skillDirectory, mapFile);
+  const findings = [];
+  let contents;
+  try {
+    contents = await readFile(mapFile, "utf8");
+  } catch {
+    return [errorFinding("routing-map-unreadable", mapPath, `Routing map is not a readable file: ${routingMap}`)];
+  }
+
+  const skillFile = path.join(skillDirectory, "SKILL.md");
+  const resolveFrom = (directory, link) => path.resolve(directory, link);
+  const rows = [];
+  let fence = null;
+  for (const line of contents.split(/\r?\n/)) {
+    if (fence) {
+      if (closesFence(line, fence)) fence = null;
+      continue;
+    }
+    fence = openingFence(line);
+    if (fence || !/^\s*\|.*\|\s*$/.test(line)) continue;
+    const [first, ...rest] = tableCells(line);
+    if (markdownLinks(first).some((link) => resolveFrom(path.dirname(mapFile), link) === skillFile))
+      rows.push(rest.join(" | "));
+  }
+  if (rows.length !== 1) {
+    const code = rows.length ? "routing-map-duplicate-row" : "routing-map-missing-row";
+    const message = rows.length
+      ? "Routing map has more than one row for this skill"
+      : "Routing map has no row for this skill";
+    return [errorFinding(code, mapPath, message)];
+  }
+
+  const isRoute = (target) => path.basename(target) === "SKILL.md" && path.dirname(target) !== skillDirectory;
+  const routeName = (target) => path.basename(path.dirname(target));
+  const expectedRoutes = new Set();
+  const expectedResources = new Set();
+  for (const link of markdownLinks(body)) {
+    const target = resolveFrom(skillDirectory, link);
+    if (isRoute(target)) expectedRoutes.add(routeName(target));
+    else if (target !== skillFile) expectedResources.add(target);
+  }
+
+  const siblings = new Set();
+  for (const entry of await readdir(path.dirname(skillDirectory), { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    try {
+      await access(path.join(path.dirname(skillDirectory), entry.name, "SKILL.md"), fsConstants.R_OK);
+      siblings.add(entry.name);
+    } catch {
+      // Not a skill directory.
+    }
+  }
+  const row = rows[0];
+  const documentedRoutes = new Set();
+  const documentedResources = new Set();
+  for (const link of markdownLinks(row)) {
+    const target = resolveFrom(path.dirname(mapFile), link);
+    if (isRoute(target)) documentedRoutes.add(routeName(target));
+    else if (target !== skillFile) documentedResources.add(target);
+  }
+  for (const match of maskInlineLinks(row).matchAll(/`([a-z0-9]+(?:-[a-z0-9]+)*)`/g)) {
+    if (expectedRoutes.has(match[1]) || siblings.has(match[1])) documentedRoutes.add(match[1]);
+  }
+
+  const display = (target) => relativePath(skillDirectory, target);
+  for (const name of [...expectedRoutes].filter((name) => !documentedRoutes.has(name)).sort()) {
+    findings.push(
+      errorFinding("routing-map-missing-route", mapPath, `Routing map row does not name the linked skill: ${name}`),
+    );
+  }
+  for (const name of [...documentedRoutes].filter((name) => !expectedRoutes.has(name)).sort()) {
+    findings.push(
+      errorFinding("routing-map-extra-route", mapPath, `Routing map row names a skill SKILL.md does not link: ${name}`),
+    );
+  }
+  for (const target of [...expectedResources]
+    .filter((target) => !documentedResources.has(target))
+    .map(display)
+    .sort()) {
+    findings.push(
+      errorFinding("routing-map-missing-resource", mapPath, `Routing map row does not link the resource: ${target}`),
+    );
+  }
+  for (const target of [...documentedResources]
+    .filter((target) => !expectedResources.has(target))
+    .map(display)
+    .sort()) {
+    findings.push(
+      errorFinding(
+        "routing-map-extra-resource",
+        mapPath,
+        `Routing map row links a resource SKILL.md does not link: ${target}`,
+      ),
+    );
+  }
+  return findings;
+}
+
+function maskInlineLinks(text) {
+  return text.replace(/\[[^\]]*\]\([^)]*\)/g, " ");
+}
+
+export async function validateSkill({ directory, packageRoot, routingMap }) {
   const analysis = await analyzeSkill(directory, packageRoot);
+  const findings = [...analysis.findings];
+  let cycles = [];
+  if (analysis.readable) {
+    cycles = await linkCycles(analysis.skillDirectory, analysis.packageRoot);
+    if (routingMap) findings.push(...(await checkRoutingMap({ ...analysis, routingMap })));
+  }
   return {
     command: "validate",
-    status: analysis.findings.some((finding) => finding.severity === "error") ? "invalid" : "valid",
+    status: findings.some((finding) => finding.severity === "error") ? "invalid" : "valid",
     skillDirectory: analysis.skillDirectory,
     packageRoot: analysis.packageRoot,
     frontmatter: analysis.frontmatter,
     heading: analysis.heading,
     resources: analysis.resources,
-    findings: analysis.findings,
+    cycles,
+    findings,
   };
 }
 

package/skills/write-skill/scripts/skill-author.mjs

@@ -1,13 +1,14 @@
 #!/usr/bin/env node
 
+import { compareGuidance, compareMarkdown } from "./lib/compare.mjs";
 import { DEFAULT_THRESHOLD, findSimilarFiles } from "./lib/similarity.mjs";
 import { initSkill, inspectSkill, SkillAuthorError, validateSkill } from "./lib/skill-author.mjs";
 
-const commands = new Set(["init", "validate", "inspect", "similarity"]);
+const commands = new Set(["init", "validate", "inspect", "similarity", "compare"]);
 
 function printUsage() {
   process.stdout.write(
-    `Usage: skill-author <init|validate|inspect|similarity> [options]\n\nCommands:\n  init <directory> --name <name> --description <text>\n      init creates a minimal SKILL.md and refuses to overwrite one\n  validate <directory> [--package-root <directory>]\n      validate checks structure and recursive resource containment\n  inspect <directory> [--package-root <directory>]\n      inspect reports factual inventory plus validation findings\n  similarity <directory> [--threshold <0-1>]\n      similarity reports near-duplicate Markdown files by shared word sequences (default ${DEFAULT_THRESHOLD})\n\nOutput:\n  Commands emit JSON. Invalid structure still emits JSON and exits nonzero.\n  Command errors emit structured error JSON.\n  Package root defaults to the nearest package.json ancestor, then the skill parent.\n\nFrontmatter:\n  Validation supports flat plain-string or JSON-compatible double-quoted scalars.\n  Double-quote values when punctuation, numbers, booleans, or null-like text could be ambiguous.\n`,
+    `Usage: skill-author <init|validate|inspect|similarity> [options]\n       skill-author compare [<base-ref> [<new-ref>] | --base <folder> [<folder>]] [options]\n\nCommands:\n  init <directory> --name <name> --description <text>\n      init creates a minimal SKILL.md and refuses to overwrite one\n  validate <directory> [--package-root <directory>] [--routing-map <file>]\n      validate checks structure and recursive resource containment, reports link cycles among\n      the Markdown files the skill reaches, and with --routing-map checks the skill's row\n  inspect <directory> [--package-root <directory>]\n      inspect reports factual inventory plus validation findings\n  similarity <directory> [--threshold <0-1>]\n      similarity reports near-duplicate Markdown files by shared word sequences (default ${DEFAULT_THRESHOLD})\n  compare [<base-ref> [<new-ref>]] [--paths <path>...] [--deleted-only] [--all-units] [--verdicts <file>] [--markdown]\n      compare reports what changed model-facing Markdown at <base-ref> (default: the merge-base with\n      the default branch) no longer says at <new-ref> (default: the working tree, uncommitted edits\n      included), and exits nonzero while a rule-like unmatched unit (a rule, a numbered step, or a\n      reason: because, so that, otherwise, why) has no verdict; --all-units, for a substantial\n      revision (a merge, split, move or rewrite), needs a verdict for every unmatched unit\n  compare --base <folder> [<folder>] [options]\n      compare against a copy of the text kept outside Git (default: the current folder)\n\nOutput:\n  Commands emit JSON. Invalid structure still emits JSON and exits nonzero.\n  compare --markdown prints a readable report instead.\n  Command errors emit structured error JSON.\n  Package root defaults to the nearest package.json ancestor, then the skill parent.\n\nFrontmatter:\n  Validation supports flat plain-string or JSON-compatible double-quoted scalars.\n  Double-quote values when punctuation, numbers, booleans, or null-like text could be ambiguous.\n`,
   );
 }
 
@@ -15,7 +16,8 @@ function fail(code, message, exitCode = 2) {
   throw new SkillAuthorError(code, message, exitCode);
 }
 
-function parseOptions(args, allowedOptions) {
+// Options take one value, except flags (no value) and lists (every following argument up to the next option).
+function parseOptions(args, allowedOptions, { flags = new Set(), lists = new Set() } = {}) {
   const positionals = [];
   const options = {};
 
@@ -26,12 +28,23 @@ function parseOptions(args, allowedOptions) {
       continue;
     }
 
-    if (!allowedOptions.has(argument)) {
+    if (!allowedOptions.has(argument) && !flags.has(argument) && !lists.has(argument)) {
       fail("unknown-option", `Unknown option: ${argument}`);
     }
     if (Object.hasOwn(options, argument)) {
       fail("duplicate-option", `Option may be supplied once: ${argument}`);
     }
+    if (flags.has(argument)) {
+      options[argument] = true;
+      continue;
+    }
+    if (lists.has(argument)) {
+      const values = [];
+      while (index + 1 < args.length && !args[index + 1].startsWith("--")) values.push(args[(index += 1)]);
+      if (values.length === 0) fail("missing-option-value", `Option requires a value: ${argument}`);
+      options[argument] = values;
+      continue;
+    }
 
     const value = args[index + 1];
     if (value === undefined || value.startsWith("--")) {
@@ -61,12 +74,15 @@ async function run(command, args) {
   }
 
   if (command === "validate" || command === "inspect") {
-    const { positionals, options } = parseOptions(args, new Set(["--package-root"]));
+    const allowed = command === "validate" ? ["--package-root", "--routing-map"] : ["--package-root"];
+    const { positionals, options } = parseOptions(args, new Set(allowed));
     if (positionals.length !== 1) {
       fail("invalid-arguments", `${command} requires exactly one skill directory`);
     }
     const input = { directory: positionals[0], packageRoot: options["--package-root"] };
-    return command === "validate" ? validateSkill(input) : inspectSkill(input);
+    return command === "validate"
+      ? validateSkill({ ...input, routingMap: options["--routing-map"] })
+      : inspectSkill(input);
   }
 
   if (command === "similarity") {
@@ -84,6 +100,33 @@ async function run(command, args) {
     return findSimilarFiles({ directory: positionals[0], threshold });
   }
 
+  if (command === "compare") {
+    const { positionals, options } = parseOptions(args, new Set(["--base", "--verdicts"]), {
+      flags: new Set(["--deleted-only", "--markdown", "--all-units"]),
+      lists: new Set(["--paths"]),
+    });
+    const folder = options["--base"] ?? null;
+    if (positionals.length > (folder === null ? 2 : 1)) {
+      fail(
+        "invalid-arguments",
+        folder === null
+          ? "compare takes at most a base ref and a new ref"
+          : "compare --base takes at most one folder to compare",
+      );
+    }
+    const result = await compareGuidance({
+      base: folder === null ? (positionals[0] ?? null) : null,
+      next: folder === null ? (positionals[1] ?? null) : null,
+      baseFolder: folder,
+      directory: folder === null ? null : (positionals[0] ?? null),
+      paths: options["--paths"] ?? null,
+      deletedOnly: options["--deleted-only"] === true,
+      verdicts: options["--verdicts"] ?? null,
+      allUnits: options["--all-units"] === true,
+    });
+    return options["--markdown"] ? { ...result, markdown: true } : result;
+  }
+
   fail("unknown-command", `Unknown command: ${command}`);
 }
 
@@ -99,8 +142,8 @@ async function main() {
   }
 
   const result = await run(command, args);
-  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
-  if (result.status === "invalid") process.exitCode = 1;
+  process.stdout.write(result.markdown ? compareMarkdown(result) : `${JSON.stringify(result, null, 2)}\n`);
+  if (result.status === "invalid" || result.status === "unresolved") process.exitCode = 1;
 }
 
 try {

package/capabilities/cognitive-routing/references/both-mode.md

@@ -1,36 +0,0 @@
-# Both Mode
-
-Judgment for placing work when Runtime State shows `Delegation: both`. The core skill's Rules still apply, including the limit on Coordinator's own environment work.
-
-Both mode is the middle ground between quality and cost. Executor does consequential work, including code; Helper does support; Coordinator plans, writes contracts, assesses, and talks to the user. Every assignment names its worker with `worker: "helper"` or `worker: "executor"`.
-
-## Choose The Worker Per Assignment
-
-Goal: each assignment goes to the cheapest worker that can do it without losing quality.
-
-Default: Executor for results whose behavior or failure needs engineering ownership; Helper for gathering, checks, setup, record maintenance, and small settled changes.
-
-| Situation | Worker |
-| --- | --- |
-| Find the callers, contracts, and conventions the next change will touch. | Helper |
-| Implement the change and its tests. | Executor |
-| A one-line authorization change with security consequences. | Executor: small, but consequential. |
-| A read-only audit that decides whether the design holds. | Executor: no writes, but substantive judgment. |
-| Rerun the validation suite and the formatter after Executor's change. | Helper |
-| Update several record entries after an accepted result. | Helper, or folded into an assignment already going out. |
-
-The failure to prevent is misplacement: a consequential change given to Helper because it is short, or Executor spent on pure gathering. Decide by the responsibility and its consequences, not by size or by whether the work writes.
-
-These are available routes, not phases. A unit may use only Helper, go straight to Executor, or keep one coherent result with Executor through its checks and corrections.
-
-## Reuse What The Other Worker Found
-
-Goal: no worker rediscovers what the other already established.
-
-Helper and Executor share ordinary history. A typical route: Helper gathers; Executor's contract points at what Helper found instead of asking it to explore; Coordinator receives what it needs through projection. After implementation, Helper can run follow-up checks with Executor's context already present. Recheck a fact only when its freshness matters or its source is no longer available.
-
-Executor forms the execution forecast for production work; Coordinator supplies the governing decisions.
-
-## Mind The Model Configuration
-
-The user may run Coordinator and Executor on the same model at different effort. On routes that keep the provider cache across effort changes (currently GPT-6 on an OpenAI API key or OpenAI Codex), handoffs to Executor then reuse the cache and cost less. Elsewhere, including OpenAI's Sign in with ChatGPT, each effort keeps its own cache, so the first handoff at each effort rereads the whole context and later ones reread what was added since that effort last ran. With different models, every switch rereads the whole context. Either way the configuration is the user's choice; do not change it.

package/capabilities/cognitive-routing/references/executor-mode.md

@@ -1,48 +0,0 @@
-# Executor Mode
-
-Judgment for placing work when Runtime State shows `Delegation: executor`. The core skill's Rules still apply, including the limit on Coordinator's own environment work.
-
-Executor mode is the main cost saver. A cheaper Executor does the environment work: investigation, preparation, artifacts, implementation, checks, and record maintenance. Coordinator plans, writes contracts, assesses, and talks to the user, and executes nothing itself except under ACT_BOUNDED. The saving comes from two places: projection keeps Executor's working trail out of Coordinator's context, and precise contracts keep Executor from searching.
-
-## Make The Contract Do The Heavy Thinking
-
-Goal: Executor's first attempt is right often enough that the saving outweighs the corrections.
-
-Coordinator's judgment reaches the work only through the contract, so the contract carries the decision. Frame the problem so the cheaper model finds it straightforward: the representation to use, the invariant to preserve, the wrong approach that looks right, and the check that tells them apart. For consequential design choices, write that content with the Implementation Decisions method in [Design for Depth](../../../skills/design-for-depth/SKILL.md).
-
-```text
-Weak:   Add caching to the config loader.
-Strong: Cache the parsed config per file path and invalidate when the file's
-        modification time changes. Two loads of an unchanged file parse once;
-        an edit between loads must be seen. A process-lifetime cache looks
-        right and passes a single-load test but serves stale config, so check
-        with an edit between two loads.
-```
-
-A cheaper model applies an escape clause literally, so write requirements as outcomes for named things ("each caller listed below still gets X"), never "unless…" or "as today", and say where the change belongs.
-
-Default: give structure where Executor has shown difficulty or the property is easy to get subtly wrong, and freedom where the mechanics are ordinary. Signals the balance is off:
-
-- Executor returns work that misses an unstated decision: the contract left it implicit.
-- The contract is longer than the change and reads like a patch: Coordinator has done the work at premium price, and Executor only transcribes it.
-- The same misunderstanding recurs: change how you represent the problem, not how forcefully you state it.
-
-## Gather, Then Produce
-
-Goal: Coordinator's contracts rest on evidence without Coordinator doing the reading.
-
-Coordinator may first commission evidence or a proposal, interpret what comes back, and then commission production. Executor gathers; projection carries the selected evidence to Coordinator; the next contract uses it to narrow Executor's search. Do not add a gathering pass when Executor already has an adequate basis, and do not pre-solve every detail before any evidence exists.
-
-Executor forms the execution forecast for production work. Coordinator supplies the governing decisions it rests on.
-
-## Ask For Evidence That Decides
-
-Goal: Coordinator can assess from what projection delivers, without asking for the whole trail.
-
-Request evidence by the claim it must support: the decisive test output, the changed interface, the contradicting observation. Requesting everything moves Executor's trail into Coordinator's context and cancels the saving; requesting too little forces a recovery round. When a return lacks evidence that exists, recover it rather than re-running the work.
-
-## What Coordinator Does Not Do Here
-
-Coordinator writes an artifact itself only when the user explicitly assigns it (see the core skill). Record maintenance goes to Executor, folded into an assignment already going out rather than sent as a handoff of its own. Recovery after context loss is the exception the core skill names: Coordinator reads the Working Record and the artifacts that define the task directly.
-
-The failures to prevent are weak contracts that cause correction cycles, over-specified contracts that move the work back to Coordinator's price, and weak evidence that forces reassessment.

package/capabilities/cognitive-routing/references/helper-mode.md

@@ -1,47 +0,0 @@
-# Helper Mode
-
-Judgment for placing work when Runtime State shows `Delegation: helper`. The core skill's Rules still apply.
-
-Helper mode is for the best output quality. Coordinator implements; Helper takes everything that does not need Coordinator-level reasoning. There is no Executor to invoke or simulate.
-
-## Delegate By Default
-
-Goal: Coordinator's premium compute goes to the work that needs it, and nothing else.
-
-Default: delegate a step unless it needs Coordinator-level reasoning. Keep that category narrow:
-
-- governing decisions and design;
-- substantive implementation, meaning changes whose behavior or failure needs engineering ownership;
-- the conversation with the user.
-
-Helper takes the rest: gathering sources and skills, investigating bounded questions, preparing authorized setup, running existing checks and validations, separate record maintenance, and straightforward settled changes that are local, reversible, and easy to check. Helper can reason, compare evidence, spot contradictions, and choose local mechanics; it is not limited to copying facts.
-
-The failure to prevent is under-delegation: classifying every step as Coordinator-level, so Coordinator does all the gathering, checking, and bookkeeping itself and the mode saves nothing.
-
-## Do Not Split What Belongs Together
-
-Goal: handoffs save more than they cost.
-
-Keep a tightly coupled edit, check, and interpret loop with Coordinator. Moving each check to Helper adds a contract, a ramp-up, and a return, and forces Helper to rebuild the context Coordinator already holds.
-
-Hand off results that stand on their own:
-
-| Situation | Placement |
-| --- | --- |
-| Before implementing, the sources, callers, and conventions for the planned change need gathering. | Helper gathers; Coordinator implements from the result. |
-| Mid-implementation, Coordinator wants to know which acceptance requirements the candidate meets, which lack a check, and which test edits changed coverage. | Helper runs a read-only cross-check against the Slice's acceptance requirements and returns without patching. |
-| After a feature lands, several record entries, a validation run, and a formatting pass are due. | Helper, as one assignment. |
-| Coordinator just ran a failing test and knows the fix. | Coordinator fixes and reruns; no handoff. |
-| One line of the Working Record needs updating in the middle of Coordinator's own work. | Coordinator updates it; a handoff would cost more than the edit. |
-
-If Helper reaches substantive work outside its assignment, it returns findings and partial state, and Coordinator takes the next decision.
-
-## Route Preparation
-
-Helper gathers; Coordinator implements. Gathered evidence must reach Coordinator: with projection on, Helper selects it at return; with projection off, Coordinator sees Helper's work in ordinary history. Coordinator forms the execution forecast itself.
-
-## Coordinator's Own Production
-
-Coordinator's direct implementation passes through no handoff, and handoffs are part of how routing keeps long work on course. Rely on Execute Work's forecast and on Workflow's check before each continuation: does the next change meet a requirement, repair a demonstrated defect, or only add an optional guarantee? Do not invent assignments for your own work to recreate that boundary, and use no ACT_BOUNDED; direct production is what this mode is for.
-
-Coordinator may update the Working Record directly as part of its own work. When closing a Slice, fold the writeback into Helper work already going out, or do it directly when it is one small update.

package/plugin.json

@@ -1,33 +0,0 @@
-{
-  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
-  "name": "freeflow",
-  "version": "0.8.0",
-  "description": "Feedback-based control system for coding agents.",
-  "author": {
-    "name": "Hassan Mohiddin"
-  },
-  "homepage": "https://github.com/hassan-mohiddin/freeflow",
-  "repository": "https://github.com/hassan-mohiddin/freeflow",
-  "license": "MIT",
-  "keywords": [
-    "workflow",
-    "skills",
-    "agents",
-    "feedback-loop",
-    "task-memory",
-    "planning",
-    "verification",
-    "review",
-    "agent-plugins",
-    "gemini",
-    "copilot",
-    "vscode",
-    "cursor",
-    "kiro",
-    "opencode",
-    "hermes"
-  ],
-  "extensions": {
-    "com.github.copilot": {}
-  }
-}

package/skills/action-selection/SKILL.md

@@ -1,92 +0,0 @@
----
-name: "action-selection"
-description: "Use when choosing or bounding an environment interaction, especially when the needed context, target, observer, or scope is uncertain, output may be broad, or recent actions have not advanced the current question."
----
-
-# Action Selection
-
-Choose environment interactions that advance the current question or result, observe what they actually change, and return the changed evidence to the current owner.
-
-An environment interaction is a bounded tool-mediated observation or effect. A current activity can need many of them; a tool call is not a task phase, a Slice, or a reason to change ownership.
-
-The **Rules** below are binding; if one cannot be met, stop and say why. Everything else is **judgment**: follow its stated goal, and adapt when a different choice serves that goal better.
-
-## Rules
-
-- Action Selection serves the current owner. It never changes the outcome, work agreement, execution method, scope, Slice, Checkpoint, or route, accepts no result, and an available tool grants no authority. Return changed authority, scope, ownership, direction, evidence boundary, or stop conditions to [Workflow](../workflow/SKILL.md).
-- Never present a simulated, predicted, sampled, or truncated result as a complete observation. State truncation and sampling explicitly; a partial result does not show that omitted matches are irrelevant or that a search was exhaustive.
-- Never report an interaction's success as proof of a wider claim. A successful read is not understanding, a successful write is not correctness, and a passing tool result is not the claim it was meant to support; return the evidence for interpretation.
-- Do not emit candidate tables, scores, or speculative tool-call sequences unless a user-owned choice is exposed.
-
-## Know What The Step Must Establish
-
-Goal: every interaction answers a question the owner actually has.
-
-Before touching the environment, identify what the interaction must answer or produce, and reuse evidence already available and current enough for that purpose. The need may be understanding the outcome or symptom, establishing a mechanism or dependency, applying an understood change, observing whether a claim holds, or reconstructing missing continuation state. Use these to focus the action, not to print phase labels or restart planning.
-
-Aim for the minimum sufficient context or effect for the next decision; minimum means sufficient, not merely short. Do not collect information because it may be useful later, and do not mistake a source or reference existing for its contents being available.
-
-## Run Settled Steps; Select Uncertain Ones
-
-Goal: spend judgment where the next step is genuinely open, and none on steps that are already decided.
-
-When the target, purpose, scope, and observing boundary are supported and the action is covered and directly checkable, act directly: read a known function or range, apply a selected edit, run a chosen focused check, inspect its diff.
-
-When the owner's route or [Execute Work](../execute-work/SKILL.md)'s forecast already fixes a sequence, run the sequence without reconsidering each call. Issue independent reads together, apply coupled edits before their shared check, and run that check once. Select again only when a result contradicts the forecast, is unexpected, or opens a new question.
-
-Select deliberately when the target, observer, or scope is uncertain, the likely output is broad, the action is destructive, expensive, or hard to recover, or recent work has stalled:
-
-1. Identify the fact or effect the owner needs.
-2. Check whether existing evidence already supplies it.
-3. Consider only a few materially different ways to obtain it.
-4. Reject unchanged rereads, equivalent searches, eliminated approaches, and information with no current use.
-5. Prefer the most direct action that distinguishes the plausible answers.
-6. Among equally useful actions, prefer proportionate output, side effects, context residue, and recovery cost.
-7. Execute it, then choose what follows from the actual result.
-
-Keep this comparison internal. A command being easy to run does not make its target or hypothesis well chosen. A good observation can change the owner's belief or next action whether it supports or contradicts the leading explanation; an exact mutation can advance a settled result without testing a hypothesis.
-
-## Bound The Tool And Its Output
-
-Goal: get the needed evidence at the lowest total cost, counting what the output costs after it arrives.
-
-Everything an interaction returns stays in context and is paid for again on every later turn until compaction, so one broad read can cost more than several focused ones. Each separate call also costs a model turn, so batching independent calls saves turns. Weigh both.
-
-Use the simplest operation that can establish the required relationship:
-
-- known file, symbol, artifact, or range -> focused read or operation;
-- ownership, caller, or dependency question -> structured relationship query where available;
-- literal or generated reference -> bounded content search;
-- behavioral claim -> the owner's selected test, observer, or reproduction;
-- understood effect -> narrow direct mutation;
-- unknown location -> bounded discovery, then narrow from its result.
-
-Choose scope before running: directory, source kind, pattern, range, test target, time window, result count, fields, affected state, or recovery scope. Exclude unrelated history, generated output, and dependencies unless the question needs them. When volume is uncertain, run a location or count query before requesting all matching bodies, and prefer bounded output with an accessible full result.
-
-Recover saved output instead of rerunning its command, and use a script when a settled loop over many results (filter, parse, compare, aggregate) would otherwise take many model turns. A script runs known steps; return to ordinary calls when a result needs a new decision.
-
-Use host-supplied usage when available; do not invent token counts or treat the provider maximum as a promise that the work will fit. The owner chooses the work horizon: return an unexpectedly large context need to it instead of reading the whole dependency tree or silently shrinking acceptance.
-
-## Observe Before Continuing
-
-Goal: know what changed before deciding what comes next.
-
-After an interaction, establish what actually ran or was returned, what changed in evidence, hypotheses, implementation, or task state, whether the intended question was answered or effect produced, and what uncertainty, partial effect, or contradiction remains. New content is not automatically useful evidence.
-
-When a read settles the question, stop that investigation. An invalidated implementation premise needs reassessment before dependent effects; ordinary local continuation can proceed.
-
-## Notice A Stall Early
-
-Goal: stop spending interactions that no longer change anything.
-
-If an interaction did not advance the question, do not repeat it with synonyms, nearby files, a wider equivalent search, or another tool with the same evidence relationship. Change the question or the kind of observer, or report the missing evidence.
-
-The common stalls are rerunning a check against unchanged state, rereading an unchanged source without a new question, widening a search without narrowing the hypothesis, and alternating edits, failures, and reversions without a supported cause. When two or more recent interactions have not changed understanding, advanced the covered effect, or supported a new branch, read [Trajectory Stalls](references/trajectory-stalls.md) before another interaction.
-
-For unexplained repeated failure, use [Diagnose Failure](../diagnose-failure/SKILL.md).
-
-## Return
-
-Return the observation and material state change to the same owner. Stop when the immediate need is satisfied, the active contract requires return, no useful covered interaction remains, or another activity must settle the next choice. Reuse adequate evidence instead of generating new calls to justify completion.
-
-The goal is fewer low-value interactions while preserving sufficient evidence and the agreed outcome, not fewer calls at any cost.