@bx-h/meta-flow 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.1.2
+
+- Make installed JSON templates pass their matching validation scripts.
+- Add template validation to `verify` and `doctor`.
+- Propagate command return codes through the CLI entrypoint.
+- Tighten `doctor` checks for marketplace, plugin version, support scripts, and CLI-visible failures.
+- Make the release workflow skip npm publish when the tag version already exists.
+
+## 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.2 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.2
 ```
 
 The npm installer still matters because it also materializes custom agent TOML files and validation scripts.

package/bin/meta-flow.js

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
 import { main } from "../src/cli/index.js";
 
-main(process.argv.slice(2)).catch((error) => {
+main(process.argv.slice(2)).then((code) => {
+  process.exitCode = code;
+}).catch((error) => {
   console.error(error?.message || String(error));
   process.exitCode = 1;
 });

package/marketplace/marketplace.json

@@ -6,9 +6,10 @@
   "plugins": [
     {
       "name": "meta-flow",
+      "version": "0.1.2",
       "source": {
         "source": "local",
-        "path": "./plugins/meta-flow"
+        "path": "./plugin"
       },
       "policy": {
         "installation": "AVAILABLE",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bx-h/meta-flow",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "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.2",
   "description": "A Codex workflow for turning vague requests into clarified, reviewed, adjudicated, task-level executed, and verified outcomes.",
   "author": {
     "name": "huangbaixi",

package/plugin/templates/milestone-plan.json

@@ -4,10 +4,16 @@
     {
       "id": "M1",
       "objective": "string",
-      "scope": [],
+      "scope": [
+        "string"
+      ],
       "out_of_scope": [],
-      "acceptance_checks": [],
-      "expected_outputs": [],
+      "acceptance_checks": [
+        "string"
+      ],
+      "expected_outputs": [
+        "string"
+      ],
       "risk": "medium",
       "status": "pending"
     }

package/plugin/templates/task-list.json

@@ -6,11 +6,17 @@
       "id": "T1",
       "objective": "string",
       "inputs": [],
-      "expected_outputs": [],
-      "allowed_files": [],
+      "expected_outputs": [
+        "string"
+      ],
+      "allowed_files": [
+        "path-or-glob"
+      ],
       "forbidden_files": [],
       "allowed_commands": [],
-      "acceptance_checks": [],
+      "acceptance_checks": [
+        "string"
+      ],
       "dependencies": [],
       "risk": "medium",
       "repair_attempts": 0,

package/plugin/templates/task-spec.json

@@ -4,11 +4,17 @@
   "concrete_task_id": "T1",
   "objective": "string",
   "inputs": [],
-  "expected_outputs": [],
-  "allowed_files": [],
+  "expected_outputs": [
+    "string"
+  ],
+  "allowed_files": [
+    "path-or-glob"
+  ],
   "forbidden_files": [],
   "allowed_commands": [],
-  "acceptance_checks": [],
+  "acceptance_checks": [
+    "string"
+  ],
   "dependencies": [],
   "risk": "medium",
   "repair_attempts": 0,

package/src/cli/commands/doctor.js

@@ -6,7 +6,11 @@ import { AGENT_FILES, validateAgentTemplate } from "../lib/agents.js";
 import { inspectCodexConfig } from "../lib/codex_config.js";
 import { pathExists, readJsonOrDefault } from "../lib/fs_safe.js";
 import { createLogger } from "../lib/logger.js";
+import { marketplaceEntry } from "../lib/marketplace.js";
 import { resolveTargets, sampleTaskRoot } from "../lib/paths.js";
+import { validateInstalledSkill } from "../lib/skill.js";
+import { HELP_SCRIPT_FILES, validateSupportFiles } from "../lib/support.js";
+import { META_FLOW_VERSION } from "../lib/version.js";
 
 export function doctorHelp() {
   return `Usage: meta-flow doctor --scope repo|user [--target <path>] [--verbose]`;
@@ -27,10 +31,13 @@ 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));
   results.push(await checkPythonScripts(targets));
+  results.push(await checkInstalledTemplates(targets));
   results.push(await checkSampleTask(targets));
 
   for (const result of results) {
@@ -58,6 +65,9 @@ async function checkPlugin(targets) {
   if (manifest.name !== "meta-flow") {
     return { level: "FAIL", title: "plugin manifest invalid", message: "Expected name=meta-flow." };
   }
+  if (manifest.version !== META_FLOW_VERSION) {
+    return { level: "FAIL", title: "plugin manifest version mismatch", message: `Expected version=${META_FLOW_VERSION}.` };
+  }
   if (!(await pathExists(skillPath))) {
     return { level: "FAIL", title: "SKILL.md missing", message: "Re-run install." };
   }
@@ -68,6 +78,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." };
@@ -79,9 +105,35 @@ async function checkMarketplace(targets) {
   if (!entry) {
     return { level: "FAIL", title: "marketplace entry missing", message: "Run install to add meta-flow entry." };
   }
+  const expected = marketplaceEntry(targets);
+  const errors = [];
+  if (entry.version !== expected.version) {
+    errors.push(`version expected ${expected.version}, got ${entry.version ?? "missing"}`);
+  }
+  if (entry.source?.source !== expected.source.source) {
+    errors.push(`source.source expected ${expected.source.source}`);
+  }
+  if (entry.source?.path !== expected.source.path) {
+    errors.push(`source.path expected ${expected.source.path}, got ${entry.source?.path ?? "missing"}`);
+  }
+  const pluginPath = resolveMarketplacePluginPath(targets, entry);
+  if (!pluginPath || !(await pathExists(path.join(pluginPath, ".codex-plugin", "plugin.json")))) {
+    errors.push("source.path does not point to an installed plugin manifest");
+  }
+  if (errors.length) {
+    return { level: "FAIL", title: "marketplace entry invalid", message: errors.join("; ") };
+  }
   return { level: "PASS", title: "marketplace entry present" };
 }
 
+function resolveMarketplacePluginPath(targets, entry) {
+  const sourcePath = entry?.source?.path;
+  if (!sourcePath || typeof sourcePath !== "string") {
+    return null;
+  }
+  return path.isAbsolute(sourcePath) ? sourcePath : path.resolve(targets.target, sourcePath);
+}
+
 async function checkAgents(targets) {
   const missing = [];
   const invalid = [];
@@ -118,24 +170,47 @@ async function checkConfig(targets) {
 }
 
 async function checkPythonScripts(targets) {
-  const scriptsDir = path.join(targets.pluginTarget, "scripts");
-  const scriptPath = path.join(scriptsDir, "validate_goal_contract.py");
-  if (!(await pathExists(scriptPath))) {
-    return { level: "FAIL", title: "Python scripts missing", message: "Reinstall plugin files." };
-  }
-  const result = spawnSync(resolvePython(), [scriptPath, "--help"], pythonOptions());
-  if (result.status !== 0) {
-    return { level: "FAIL", title: "Python scripts not runnable", message: result.stderr || result.stdout };
+  const scriptsDir = targets.scriptsTarget;
+  const python = resolvePython();
+  for (const fileName of HELP_SCRIPT_FILES) {
+    const scriptPath = path.join(scriptsDir, fileName);
+    if (!(await pathExists(scriptPath))) {
+      return { level: "FAIL", title: "Python scripts missing", message: `Missing ${scriptPath}` };
+    }
+    const result = spawnSync(python, [scriptPath, "--help"], pythonOptions());
+    if (result.status !== 0) {
+      return { level: "FAIL", title: "Python scripts not runnable", message: `${fileName}: ${result.stderr || result.stdout}` };
+    }
   }
   return { level: "PASS", title: "Python scripts runnable" };
 }
 
+async function checkInstalledTemplates(targets) {
+  const python = resolvePython();
+  const scripts = targets.scriptsTarget;
+  const templates = targets.templatesTarget;
+  const runs = [
+    [path.join(scripts, "validate_goal_contract.py"), path.join(templates, "goal-contract.json")],
+    [path.join(scripts, "validate_adjudication.py"), path.join(templates, "adjudication-report.json")],
+    [path.join(scripts, "validate_milestone_plan.py"), path.join(templates, "milestone-plan.json")],
+    [path.join(scripts, "validate_task_list.py"), path.join(templates, "task-list.json")],
+    [path.join(scripts, "validate_task_verification.py"), path.join(templates, "task-verification-report.json")]
+  ];
+  for (const args of runs) {
+    const result = spawnSync(python, args, pythonOptions());
+    if (result.status !== 0) {
+      return { level: "FAIL", title: "installed templates invalid", message: result.stderr || result.stdout };
+    }
+  }
+  return { level: "PASS", title: "installed templates valid" };
+}
+
 async function checkSampleTask(targets) {
   if (!(await pathExists(sampleTaskRoot))) {
     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

@@ -9,6 +9,8 @@ import { runInstall } from "./install.js";
 import { runUninstall } from "./uninstall.js";
 import { validatePlugin } from "../lib/plugin.js";
 import { packageRoot, pluginSource, sampleTaskRoot } from "../lib/paths.js";
+import { HELP_SCRIPT_FILES } from "../lib/support.js";
+import { META_FLOW_VERSION, PACKAGE_NAME } from "../lib/version.js";
 
 export async function runVerify(argv = []) {
   const lintOnly = argv.includes("--lint-only");
@@ -22,6 +24,7 @@ export async function runVerify(argv = []) {
   checks.push(await checkPlugin());
   checks.push(await checkAgents());
   checks.push(await checkPythonHelp());
+  checks.push(await checkTemplates());
   checks.push(await checkSampleTask());
   checks.push(await checkDryRun());
   checks.push(await checkInstallUninstallSimulation());
@@ -32,7 +35,8 @@ export async function runVerify(argv = []) {
 async function checkPackageJson() {
   const packageJson = JSON.parse(await fs.readFile(path.join(packageRoot, "package.json"), "utf8"));
   const errors = [];
-  if (packageJson.name !== "@bx-h/meta-flow") errors.push("unexpected package name");
+  if (packageJson.name !== PACKAGE_NAME) errors.push("unexpected package name");
+  if (packageJson.version !== META_FLOW_VERSION) errors.push(`unexpected package version: ${packageJson.version}`);
   if (packageJson.scripts?.postinstall) errors.push("postinstall must not exist");
   if (packageJson.bin?.["meta-flow"] !== "bin/meta-flow.js") errors.push("bin meta-flow is invalid");
   if (packageJson.type !== "module") errors.push("type must be module");
@@ -65,19 +69,9 @@ async function checkAgents() {
 }
 
 async function checkPythonHelp() {
-  const scripts = [
-    "new_task.py",
-    "validate_goal_contract.py",
-    "aggregate_reviews.py",
-    "validate_adjudication.py",
-    "validate_milestone_plan.py",
-    "validate_task_list.py",
-    "validate_task_verification.py",
-    "status.py"
-  ];
   const python = resolvePython();
   const errors = [];
-  for (const script of scripts) {
+  for (const script of HELP_SCRIPT_FILES) {
     const run = spawnSync(python, [path.join(pluginSource, "scripts", script), "--help"], pythonOptions());
     if (run.status !== 0) {
       errors.push(`${script} --help failed: ${run.stderr || run.stdout}`);
@@ -86,6 +80,27 @@ async function checkPythonHelp() {
   return result("Python script --help", errors);
 }
 
+async function checkTemplates() {
+  const python = resolvePython();
+  const scripts = path.join(pluginSource, "scripts");
+  const templates = path.join(pluginSource, "templates");
+  const runs = [
+    [path.join(scripts, "validate_goal_contract.py"), path.join(templates, "goal-contract.json")],
+    [path.join(scripts, "validate_adjudication.py"), path.join(templates, "adjudication-report.json")],
+    [path.join(scripts, "validate_milestone_plan.py"), path.join(templates, "milestone-plan.json")],
+    [path.join(scripts, "validate_task_list.py"), path.join(templates, "task-list.json")],
+    [path.join(scripts, "validate_task_verification.py"), path.join(templates, "task-verification-report.json")]
+  ];
+  const errors = [];
+  for (const args of runs) {
+    const run = spawnSync(python, args, pythonOptions());
+    if (run.status !== 0) {
+      errors.push(`${path.basename(args[1])} failed: ${run.stderr || run.stdout}`);
+    }
+  }
+  return result("templates validate against scripts", errors);
+}
+
 async function checkSampleTask() {
   const python = resolvePython();
   const tmp = await fs.mkdtemp(path.join(os.tmpdir(), "meta-flow-verify-"));
@@ -135,6 +150,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 +166,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

@@ -1,11 +1,12 @@
 import path from "node:path";
-import { readJsonOrDefault, writeJsonPretty } from "./fs_safe.js";
+import { pathExists, readJsonOrDefault, writeJsonPretty } from "./fs_safe.js";
 import { repoMarketplacePath } from "./paths.js";
+import { META_FLOW_VERSION } from "./version.js";
 
 export function marketplaceEntry(targets) {
   return {
     name: "meta-flow",
-    version: "0.1.0",
+    version: META_FLOW_VERSION,
     source: {
       source: "local",
       path: targets.scope === "repo" ? repoMarketplacePath() : targets.pluginTarget
@@ -58,6 +59,9 @@ export async function updateMarketplace(targets, options = {}) {
 }
 
 export async function uninstallMarketplace(targets, options = {}) {
+  if (!(await pathExists(targets.marketplaceTarget))) {
+    return { updated: false, skipped: true };
+  }
   const current = await readJsonOrDefault(targets.marketplaceTarget, {
     name: "meta-flow-marketplace",
     interface: { displayName: "Meta Flow Marketplace" },
@@ -65,6 +69,7 @@ export async function uninstallMarketplace(targets, options = {}) {
   });
   const next = removeMarketplaceEntry(current);
   await writeJsonPretty(targets.marketplaceTarget, next, options);
+  return { updated: true, skipped: false };
 }
 
 export function describeMarketplace(targets) {

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

@@ -2,6 +2,7 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { backupIfExists, copyDirSafe, pathExists, removeDirSafe } from "./fs_safe.js";
 import { pluginSource } from "./paths.js";
+import { META_FLOW_VERSION } from "./version.js";
 
 async function isMetaFlowPlugin(dir) {
   try {
@@ -47,8 +48,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 !== META_FLOW_VERSION) {
+    errors.push(`plugin manifest version must be ${META_FLOW_VERSION}`);
   }
   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,72 @@
+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 const REQUIRED_SCRIPT_FILES = [
+  "_common.py",
+  "aggregate_reviews.py",
+  "new_task.py",
+  "status.py",
+  "validate_adjudication.py",
+  "validate_goal_contract.py",
+  "validate_milestone_plan.py",
+  "validate_task_list.py",
+  "validate_task_verification.py"
+];
+
+export const HELP_SCRIPT_FILES = REQUIRED_SCRIPT_FILES.filter((fileName) => fileName !== "_common.py");
+
+export const REQUIRED_TEMPLATE_FILES = [
+  "adjudication-report.json",
+  "direction-evaluation.json",
+  "final-report.md",
+  "goal-contract.json",
+  "milestone-plan.json",
+  "proposal-summary.md",
+  "proposal.md",
+  "questioning-report.json",
+  "raw-request.md",
+  "review-aggregate.json",
+  "reviewer-report.json",
+  "state.json",
+  "task-execution-report.json",
+  "task-list.json",
+  "task-spec.json",
+  "task-verification-report.json"
+];
+
+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 errors = [];
+  for (const fileName of REQUIRED_SCRIPT_FILES) {
+    const filePath = path.join(targets.scriptsTarget, fileName);
+    if (!(await pathExists(filePath))) {
+      errors.push(`missing ${filePath}`);
+    }
+  }
+  for (const fileName of REQUIRED_TEMPLATE_FILES) {
+    const filePath = path.join(targets.templatesTarget, fileName);
+    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 };
+}

package/src/cli/lib/version.js

@@ -0,0 +1,2 @@
+export const PACKAGE_NAME = "@bx-h/meta-flow";
+export const META_FLOW_VERSION = "0.1.2";