@bx-h/meta-flow 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.1.1
+
+- Install `meta-flow` into `.agents/skills/meta-flow` so `$meta-flow` can be discovered directly.
+- Install support scripts and templates into `.meta-flow/scripts` and `.meta-flow/templates`.
+- Update `doctor` to check the discoverable Skill and runtime support files, not only the plugin bundle.
+- Keep `.meta-flow/tasks` during uninstall while removing managed support files.
+
 ## 0.1.0
 
 - Initial Codex Plugin and npm installer package.

package/README.md

@@ -26,7 +26,7 @@ meta-flow install --scope repo
 Pinned version:
 
 ```bash
-npx @bx-h/meta-flow@0.1.0 install --scope repo
+npx @bx-h/meta-flow@0.1.1 install --scope repo
 ```
 
 ## Quick Start
@@ -117,6 +117,9 @@ flowchart LR
 Repo scope writes under the target repo:
 
 - `<repo>/plugins/meta-flow`
+- `<repo>/.agents/skills/meta-flow`
+- `<repo>/.meta-flow/scripts`
+- `<repo>/.meta-flow/templates`
 - `<repo>/.agents/plugins/marketplace.json`
 - `<repo>/.codex/agents/*.toml`
 - `<repo>/.codex/config.toml`
@@ -124,6 +127,9 @@ Repo scope writes under the target repo:
 User scope writes under the current user home:
 
 - `~/.codex/plugins/meta-flow`
+- `~/.agents/skills/meta-flow`
+- `~/.meta-flow/scripts`
+- `~/.meta-flow/templates`
 - `~/.agents/plugins/marketplace.json`
 - `~/.codex/agents/*.toml`
 - `~/.codex/config.toml`
@@ -159,7 +165,7 @@ meta-flow uninstall --scope repo --dry-run
 You can also distribute the plugin through a Codex marketplace entry:
 
 ```bash
-codex plugin marketplace add bx-h/meta-flow --ref v0.1.0
+codex plugin marketplace add bx-h/meta-flow --ref v0.1.1
 ```
 
 The npm installer still matters because it also materializes custom agent TOML files and validation scripts.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bx-h/meta-flow",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "A Codex-native workflow for clarified goals, reviewed proposals, adjudicated plans, task-level execution, verification, and direction-aware iteration.",
   "type": "module",
   "bin": {

package/plugin/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "meta-flow",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "A Codex workflow for turning vague requests into clarified, reviewed, adjudicated, task-level executed, and verified outcomes.",
   "author": {
     "name": "huangbaixi",

package/src/cli/commands/doctor.js

@@ -7,6 +7,8 @@ import { inspectCodexConfig } from "../lib/codex_config.js";
 import { pathExists, readJsonOrDefault } from "../lib/fs_safe.js";
 import { createLogger } from "../lib/logger.js";
 import { resolveTargets, sampleTaskRoot } from "../lib/paths.js";
+import { validateInstalledSkill } from "../lib/skill.js";
+import { validateSupportFiles } from "../lib/support.js";
 
 export function doctorHelp() {
   return `Usage: meta-flow doctor --scope repo|user [--target <path>] [--verbose]`;
@@ -27,6 +29,8 @@ export async function runDoctor(argv = []) {
 
   results.push(checkCodexCli());
   results.push(await checkPlugin(targets));
+  results.push(await checkDiscoverableSkill(targets));
+  results.push(await checkSupportFiles(targets));
   results.push(await checkMarketplace(targets));
   results.push(await checkAgents(targets));
   results.push(await checkConfig(targets));
@@ -68,6 +72,22 @@ async function checkPlugin(targets) {
   return { level: "PASS", title: "plugin and skill present" };
 }
 
+async function checkDiscoverableSkill(targets) {
+  const result = await validateInstalledSkill(targets);
+  if (result.errors.length) {
+    return { level: "FAIL", title: "discoverable skill incomplete", message: result.errors.join("; ") };
+  }
+  return { level: "PASS", title: "discoverable skill present" };
+}
+
+async function checkSupportFiles(targets) {
+  const result = await validateSupportFiles(targets);
+  if (result.errors.length) {
+    return { level: "FAIL", title: "support scripts/templates incomplete", message: result.errors.join("; ") };
+  }
+  return { level: "PASS", title: "support scripts/templates present" };
+}
+
 async function checkMarketplace(targets) {
   if (!(await pathExists(targets.marketplaceTarget))) {
     return { level: "FAIL", title: "marketplace missing", message: "Run install to create marketplace.json." };
@@ -118,7 +138,7 @@ async function checkConfig(targets) {
 }
 
 async function checkPythonScripts(targets) {
-  const scriptsDir = path.join(targets.pluginTarget, "scripts");
+  const scriptsDir = targets.scriptsTarget;
   const scriptPath = path.join(scriptsDir, "validate_goal_contract.py");
   if (!(await pathExists(scriptPath))) {
     return { level: "FAIL", title: "Python scripts missing", message: "Reinstall plugin files." };
@@ -135,7 +155,7 @@ async function checkSampleTask(targets) {
     return { level: "WARN", title: "sample task unavailable", message: "Package examples are not present." };
   }
   const python = resolvePython();
-  const scripts = path.join(targets.pluginTarget, "scripts");
+  const scripts = targets.scriptsTarget;
   const runs = [
     [path.join(scripts, "validate_goal_contract.py"), path.join(sampleTaskRoot, "goal-contract.json")],
     [path.join(scripts, "validate_adjudication.py"), path.join(sampleTaskRoot, "adjudication-report.json")],

package/src/cli/commands/install.js

@@ -8,6 +8,8 @@ import { createLogger } from "../lib/logger.js";
 import { updateMarketplace } from "../lib/marketplace.js";
 import { installPlugin } from "../lib/plugin.js";
 import { resolveTargets } from "../lib/paths.js";
+import { installSkill } from "../lib/skill.js";
+import { installSupportFiles } from "../lib/support.js";
 
 export function installHelp() {
   return `Usage: meta-flow install --scope repo|user [options]
@@ -61,6 +63,18 @@ export async function runInstall(argv = []) {
     }
   }
 
+  const skillResult = await installSkill(targets, { dryRun, force, backup, logger });
+  if (skillResult.conflict) {
+    logger.warn(`skill target exists and is not managed by meta-flow: ${skillResult.conflict}. Re-run with --force to overwrite.`);
+  }
+
+  const supportResult = await installSupportFiles(targets, { dryRun, force, backup, logger });
+  for (const [name, result] of Object.entries(supportResult)) {
+    if (result.conflict) {
+      logger.warn(`${name} target exists and is not managed by meta-flow: ${result.conflict}. Re-run with --force to overwrite.`);
+    }
+  }
+
   await updateMarketplace(targets, { dryRun, logger });
 
   if (installAgentsEnabled) {
@@ -95,6 +109,8 @@ function printInstallPlan(targets, options) {
   console.log(`- scope: ${targets.scope}`);
   console.log(`- target: ${targets.target}`);
   console.log(`- plugin: ${targets.pluginTarget}`);
+  console.log(`- skill: ${targets.skillTarget}`);
+  console.log(`- support: ${targets.supportTarget}`);
   console.log(`- marketplace: ${targets.marketplaceTarget}`);
   console.log(`- agents: ${targets.agentsTarget}`);
   console.log(`- config: ${targets.codexConfigTarget}`);
@@ -105,6 +121,8 @@ function printInstallPlan(targets, options) {
   if (options.installAgentsEnabled) {
     console.log("- install 14 agent templates");
   }
+  console.log("- install discoverable skill");
+  console.log("- install support scripts and templates");
   console.log("- update marketplace");
   console.log("- ensure Codex agent config");
   if (options.dryRun) {

package/src/cli/commands/uninstall.js

@@ -4,6 +4,8 @@ import { createLogger } from "../lib/logger.js";
 import { uninstallMarketplace } from "../lib/marketplace.js";
 import { uninstallPlugin } from "../lib/plugin.js";
 import { resolveTargets } from "../lib/paths.js";
+import { uninstallSkill } from "../lib/skill.js";
+import { uninstallSupportFiles } from "../lib/support.js";
 
 export function uninstallHelp() {
   return `Usage: meta-flow uninstall --scope repo|user [options]
@@ -34,6 +36,8 @@ export async function runUninstall(argv = []) {
   console.log(`- scope: ${targets.scope}`);
   console.log(`- target: ${targets.target}`);
   console.log(`- remove plugin: ${targets.pluginTarget}`);
+  console.log(`- remove skill: ${targets.skillTarget}`);
+  console.log(`- remove support scripts/templates: ${targets.supportTarget}`);
   console.log(`- update marketplace: ${targets.marketplaceTarget}`);
   console.log(`- remove marked agents: ${targets.agentsTarget}`);
   console.log(`- keep tasks: ${targets.tasksTarget}`);
@@ -46,6 +50,16 @@ export async function runUninstall(argv = []) {
   if (pluginResult.skipped) {
     logger.warn(`plugin target is not a confirmed meta-flow plugin; skipped: ${targets.pluginTarget}`);
   }
+  const skillResult = await uninstallSkill(targets, { dryRun, logger });
+  if (skillResult.skipped) {
+    logger.warn(`skill target has no meta-flow marker; skipped: ${targets.skillTarget}`);
+  }
+  const supportResult = await uninstallSupportFiles(targets, { dryRun, logger });
+  for (const [name, result] of Object.entries(supportResult)) {
+    if (result.skipped) {
+      logger.warn(`${name} target has no meta-flow marker; skipped.`);
+    }
+  }
   await uninstallMarketplace(targets, { dryRun, logger });
   const agentResult = await uninstallAgents(targets, { dryRun, logger });
   for (const skipped of agentResult.skipped) {

package/src/cli/commands/verify.js

@@ -135,6 +135,15 @@ async function checkInstallUninstallSimulation() {
   const marketplace = JSON.parse(await fs.readFile(path.join(tmp, ".agents", "plugins", "marketplace.json"), "utf8"));
   const entries = marketplace.plugins.filter((plugin) => plugin.name === "meta-flow");
   if (entries.length !== 1) errors.push(`marketplace has ${entries.length} meta-flow entries`);
+  if (!(await exists(path.join(tmp, ".agents", "skills", "meta-flow", "SKILL.md")))) {
+    errors.push("discoverable skill was not installed");
+  }
+  if (!(await exists(path.join(tmp, ".meta-flow", "scripts", "new_task.py")))) {
+    errors.push("support scripts were not installed");
+  }
+  if (!(await exists(path.join(tmp, ".meta-flow", "templates", "state.json")))) {
+    errors.push("support templates were not installed");
+  }
   const doctorCode = await runDoctor(["--scope", "repo", "--target", tmp]);
   if (doctorCode !== 0) errors.push("doctor returned non-zero after install");
   const uninstallCode = await runUninstall(["--scope", "repo", "--target", tmp, "--yes"]);
@@ -142,6 +151,15 @@ async function checkInstallUninstallSimulation() {
   return result("repo install/doctor/uninstall simulation", errors);
 }
 
+async function exists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 async function collectJsFiles(dir) {
   const entries = await fs.readdir(dir, { withFileTypes: true });
   const files = [];

package/src/cli/lib/managed_dirs.js

@@ -0,0 +1,55 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { backupIfExists, copyDirSafe, pathExists, removeDirSafe } from "./fs_safe.js";
+
+export const MANAGED_MARKER = ".meta-flow-managed.json";
+
+export async function hasManagedMarker(dir) {
+  try {
+    const marker = JSON.parse(await fs.readFile(path.join(dir, MANAGED_MARKER), "utf8"));
+    return marker.installedBy === "meta-flow";
+  } catch {
+    return false;
+  }
+}
+
+export async function installManagedDir(source, target, options = {}) {
+  const { dryRun = false, force = false, backup = false, logger } = options;
+  if (await pathExists(target)) {
+    if (!(await hasManagedMarker(target)) && !force) {
+      return { installed: false, conflict: target };
+    }
+    if (force || backup) {
+      await backupIfExists(target, { dryRun, logger });
+    }
+  }
+
+  await copyDirSafe(source, target, { dryRun, logger });
+  await writeManagedMarker(target, { dryRun, logger });
+  return { installed: true, conflict: null };
+}
+
+export async function uninstallManagedDir(parent, target, options = {}) {
+  if (!(await pathExists(target))) {
+    return { removed: false, skipped: false };
+  }
+  if (!(await hasManagedMarker(target))) {
+    return { removed: false, skipped: true };
+  }
+  await removeDirSafe(parent, target, options);
+  return { removed: true, skipped: false };
+}
+
+async function writeManagedMarker(target, { dryRun = false, logger } = {}) {
+  const markerPath = path.join(target, MANAGED_MARKER);
+  const content = {
+    installedBy: "meta-flow",
+    source: "https://github.com/bx-h/meta-flow"
+  };
+  if (dryRun) {
+    logger?.info(`DRY-RUN write ${markerPath}`);
+    return;
+  }
+  await fs.mkdir(target, { recursive: true });
+  await fs.writeFile(markerPath, `${JSON.stringify(content, null, 2)}\n`, "utf8");
+}

package/src/cli/lib/marketplace.js

@@ -5,7 +5,7 @@ import { repoMarketplacePath } from "./paths.js";
 export function marketplaceEntry(targets) {
   return {
     name: "meta-flow",
-    version: "0.1.0",
+    version: "0.1.1",
     source: {
       source: "local",
       path: targets.scope === "repo" ? repoMarketplacePath() : targets.pluginTarget

package/src/cli/lib/paths.js

@@ -6,6 +6,9 @@ const thisFile = fileURLToPath(import.meta.url);
 export const packageRoot = path.resolve(path.dirname(thisFile), "../../..");
 export const pluginSource = path.join(packageRoot, "plugin");
 export const agentTemplatesSource = path.join(pluginSource, "agent-templates");
+export const skillSource = path.join(pluginSource, "skills", "meta-flow");
+export const scriptsSource = path.join(pluginSource, "scripts");
+export const templatesSource = path.join(pluginSource, "templates");
 export const marketplaceSource = path.join(packageRoot, "marketplace", "marketplace.json");
 export const examplesRoot = path.join(packageRoot, "examples");
 export const sampleTaskRoot = path.join(examplesRoot, "sample-task");
@@ -25,9 +28,13 @@ export function resolveTargets({ scope = "repo", target } = {}) {
     pluginTarget: scope === "user"
       ? path.join(base, ".codex", "plugins", "meta-flow")
       : path.join(base, "plugins", "meta-flow"),
+    skillTarget: path.join(base, ".agents", "skills", "meta-flow"),
     marketplaceTarget: path.join(base, ".agents", "plugins", "marketplace.json"),
     agentsTarget: path.join(base, ".codex", "agents"),
     codexConfigTarget: path.join(base, ".codex", "config.toml"),
+    supportTarget: path.join(base, ".meta-flow"),
+    scriptsTarget: path.join(base, ".meta-flow", "scripts"),
+    templatesTarget: path.join(base, ".meta-flow", "templates"),
     tasksTarget: path.join(base, ".meta-flow", "tasks")
   };
 }

package/src/cli/lib/plugin.js

@@ -47,8 +47,8 @@ export async function validatePlugin(root = pluginSource) {
   if (manifest.name !== "meta-flow") {
     errors.push("plugin manifest name must be meta-flow");
   }
-  if (manifest.version !== "0.1.0") {
-    errors.push("plugin manifest version must be 0.1.0");
+  if (manifest.version !== "0.1.1") {
+    errors.push("plugin manifest version must be 0.1.1");
   }
   if (!/^---\n[\s\S]*?name:\s*meta-flow[\s\S]*?---/m.test(skill)) {
     errors.push("SKILL.md frontmatter must contain name: meta-flow");

package/src/cli/lib/skill.js

@@ -0,0 +1,52 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { hasManagedMarker, installManagedDir, uninstallManagedDir } from "./managed_dirs.js";
+import { pathExists } from "./fs_safe.js";
+import { skillSource } from "./paths.js";
+
+export async function installSkill(targets, options = {}) {
+  const result = await installManagedDir(skillSource, targets.skillTarget, options);
+  if (result.conflict || options.dryRun) {
+    return result;
+  }
+
+  const skillPath = path.join(targets.skillTarget, "SKILL.md");
+  const text = await fs.readFile(skillPath, "utf8");
+  await fs.writeFile(skillPath, materializeSkillText(text, targets), "utf8");
+  return result;
+}
+
+export async function uninstallSkill(targets, options = {}) {
+  return uninstallManagedDir(path.dirname(targets.skillTarget), targets.skillTarget, options);
+}
+
+export async function validateInstalledSkill(targets) {
+  const skillPath = path.join(targets.skillTarget, "SKILL.md");
+  const errors = [];
+  if (!(await pathExists(skillPath))) {
+    errors.push("discoverable SKILL.md missing");
+    return { skillPath, errors };
+  }
+  if (!(await hasManagedMarker(targets.skillTarget))) {
+    errors.push("discoverable skill is not managed by meta-flow installer");
+  }
+  const skill = await fs.readFile(skillPath, "utf8");
+  if (!/^---\n[\s\S]*?name:\s*meta-flow[\s\S]*?---/m.test(skill)) {
+    errors.push("discoverable SKILL.md frontmatter invalid");
+  }
+  if (!skill.includes(`${supportRootForSkill(targets)}/scripts/new_task.py`)) {
+    errors.push("discoverable SKILL.md points at the wrong support script path");
+  }
+  return { skillPath, errors };
+}
+
+function materializeSkillText(text, targets) {
+  const supportRoot = supportRootForSkill(targets);
+  return text
+    .replaceAll("python3 .meta-flow/scripts/", `python3 ${supportRoot}/scripts/`)
+    .replaceAll(".meta-flow/templates/", `${supportRoot}/templates/`);
+}
+
+function supportRootForSkill(targets) {
+  return targets.scope === "user" ? "~/.meta-flow" : ".meta-flow";
+}

package/src/cli/lib/support.js

@@ -0,0 +1,38 @@
+import path from "node:path";
+import { hasManagedMarker, installManagedDir, uninstallManagedDir } from "./managed_dirs.js";
+import { pathExists } from "./fs_safe.js";
+import { scriptsSource, templatesSource } from "./paths.js";
+
+export async function installSupportFiles(targets, options = {}) {
+  const scripts = await installManagedDir(scriptsSource, targets.scriptsTarget, options);
+  const templates = await installManagedDir(templatesSource, targets.templatesTarget, options);
+  return { scripts, templates };
+}
+
+export async function uninstallSupportFiles(targets, options = {}) {
+  const scripts = await uninstallManagedDir(targets.supportTarget, targets.scriptsTarget, options);
+  const templates = await uninstallManagedDir(targets.supportTarget, targets.templatesTarget, options);
+  return { scripts, templates };
+}
+
+export async function validateSupportFiles(targets) {
+  const required = [
+    path.join(targets.scriptsTarget, "new_task.py"),
+    path.join(targets.scriptsTarget, "validate_goal_contract.py"),
+    path.join(targets.templatesTarget, "state.json"),
+    path.join(targets.templatesTarget, "goal-contract.json")
+  ];
+  const errors = [];
+  for (const filePath of required) {
+    if (!(await pathExists(filePath))) {
+      errors.push(`missing ${filePath}`);
+    }
+  }
+  if (!(await hasManagedMarker(targets.scriptsTarget))) {
+    errors.push("scripts directory is not managed by meta-flow installer");
+  }
+  if (!(await hasManagedMarker(targets.templatesTarget))) {
+    errors.push("templates directory is not managed by meta-flow installer");
+  }
+  return { errors };
+}