@bx-h/meta-flow 0.1.0

package/plugin/skills/meta-flow/references/execution-policy.md

@@ -0,0 +1,35 @@
+# Execution Policy
+
+Execution is concrete-task scoped.
+
+## Planner
+
+The planner writes milestone-level checkpoints with objective, scope, out-of-scope, acceptance checks, expected outputs, risk, and status. It does not create implementation steps.
+
+## Task Decomposer
+
+The task decomposer writes concrete tasks for one milestone. Each task must be independently executable and independently verifiable.
+
+## Executor
+
+The executor:
+
+- handles one concrete task at a time
+- changes only `allowed_files`
+- avoids broad refactors
+- records changed files, commands, evidence, discovered facts, and risk flags
+- marks blocked instead of silently expanding scope
+
+## Result Verifier
+
+The verifier:
+
+- checks one concrete task against `task-spec.json`
+- may run tests, lint, typecheck, scripts, or diff review
+- outputs pass/revise/block
+- gives minimal repair instructions on failure
+- does not modify implementation files
+
+## Repair Limit
+
+Each concrete task has at most 2 repair attempts. After that, mark blocked and route to adjudicator or user.

package/plugin/skills/meta-flow/references/review-rubric.md

@@ -0,0 +1,28 @@
+# Review Rubric
+
+Reviewer output must be a `reviewer-report.json` object with:
+
+- `decision`: `pass`, `revise`, or `block`
+- `confidence`: number from 0 to 1
+- concrete evidence references
+- blocking issues, suggested changes, and missing information
+
+## Product Review
+
+Pass only when the proposal directly addresses the refined goal, respects non-goals, and preserves user value. Revise if scope or value is blurry. Block if it solves the wrong problem.
+
+## Technical Review
+
+Pass only when the implementation route is feasible, simple enough, and compatible with the local architecture. Revise if complexity is avoidable. Block if the route is structurally unsafe or impossible under constraints.
+
+## Risk Review
+
+Pass only when safety, data, permission, destructive action, rollback, and operational risks are identified and controlled. Block high-risk work that lacks mitigation.
+
+## Verification Review
+
+Pass only when every acceptance criterion can be observed, repeated, and evidenced. Revise vague checks. Block when success cannot be verified.
+
+## Duplication Rule
+
+Reviewers may read prior reviewer reports to avoid repeating the same issue. They should cite agreement instead of restating generic feedback.

package/plugin/skills/meta-flow/references/role-contracts.md

@@ -0,0 +1,29 @@
+# Meta-Flow Role Contracts
+
+Each role has a narrow contract. Do not merge roles even when a task looks small.
+
+## Proposal Roles
+
+- `questioner`: turns ambiguity into a small set of high-value questions and a draft goal contract. It does not propose an implementation.
+- `researcher_proposer`: researches and writes `proposal.md`. It does not change the goal contract.
+- `product_reviewer`: checks whether the proposal solves the user's real goal.
+- `technical_reviewer`: checks feasibility, complexity, dependencies, and maintainability.
+- `risk_reviewer`: checks safety, data, permission, destructive, rollback, and operational risks.
+- `verification_reviewer`: checks whether acceptance criteria are observable and repeatable.
+- `adjudicator`: resolves reviewer conflicts and routes the workflow. It does not write code or edit the proposal directly.
+- `proposal_summarizer`: compresses accepted proposal material for user confirmation without adding new claims.
+- `user_confirmation`: a human gate, not an agent.
+
+## Execution Roles
+
+- `planner`: creates milestone-level plan only.
+- `task_decomposer`: decomposes the current milestone into concrete tasks.
+- `executor`: executes exactly one concrete task.
+- `result_verifier`: verifies exactly one concrete task.
+- `direction_evaluator`: checks whether the plan and goal remain valid after a milestone or major new finding.
+- `final_summarizer`: reports completion, evidence, gaps, and residual risk.
+- `user_final_confirmation`: a human gate, not an agent.
+
+## Grain Rule
+
+Milestones are stage checkpoints. Concrete tasks are the executor/verifier unit. Never ask executor or verifier to handle an entire milestone.

package/plugin/templates/adjudication-report.json

@@ -0,0 +1,11 @@
+{
+  "task_id": "__TASK_ID__",
+  "source": "reviewers",
+  "decision": "revise_proposal",
+  "rationale": "string",
+  "resolved_conflicts": [],
+  "deduplicated_issues": [],
+  "instructions_for_next_agent": "string",
+  "next_phase": "PROPOSAL_REWORK",
+  "requires_user_confirmation": false
+}

package/plugin/templates/direction-evaluation.json

@@ -0,0 +1,16 @@
+{
+  "task_id": "__TASK_ID__",
+  "milestone_id": "M1",
+  "decision": "continue",
+  "summary": "string",
+  "new_findings": [],
+  "invalidated_assumptions": [],
+  "goal_drift_detected": false,
+  "proposal_patch_needed": false,
+  "contract_patch": {
+    "proposed_changes": [],
+    "reason": "string",
+    "requires_user_confirmation": true
+  },
+  "next_phase": "CONTINUE_NEXT_MILESTONE"
+}

package/plugin/templates/final-report.md

@@ -0,0 +1,11 @@
+# Final Report
+
+## Completed
+
+## Not Completed
+
+## Evidence
+
+## Risks And Follow-Up
+
+## Acceptance Criteria Result

package/plugin/templates/goal-contract.json

@@ -0,0 +1,20 @@
+{
+  "task_id": "__TASK_ID__",
+  "raw_user_request": "string",
+  "refined_goal": "string",
+  "problem_boundary": "string",
+  "non_goals": [],
+  "assumptions": [],
+  "constraints": [],
+  "success_definition": "string",
+  "acceptance_criteria": [
+    {
+      "id": "AC1",
+      "criterion": "string",
+      "verification_method": "manual",
+      "evidence_required": "string"
+    }
+  ],
+  "risk_level": "medium",
+  "requires_user_confirmation": true
+}

package/plugin/templates/milestone-plan.json

@@ -0,0 +1,15 @@
+{
+  "task_id": "__TASK_ID__",
+  "milestones": [
+    {
+      "id": "M1",
+      "objective": "string",
+      "scope": [],
+      "out_of_scope": [],
+      "acceptance_checks": [],
+      "expected_outputs": [],
+      "risk": "medium",
+      "status": "pending"
+    }
+  ]
+}

package/plugin/templates/proposal-summary.md

@@ -0,0 +1,11 @@
+# Proposal Summary
+
+## What Will Be Done
+
+## What Will Not Be Done
+
+## Why This Approach
+
+## Main Risks
+
+## User Confirmation Needed

package/plugin/templates/proposal.md

@@ -0,0 +1,17 @@
+# Proposal
+
+## Goal
+
+Describe the refined goal from `goal-contract.json`.
+
+## Recommended Approach
+
+Explain the primary plan, tradeoffs, risk controls, and validation path.
+
+## Alternatives
+
+List viable alternatives and why they are not preferred.
+
+## Open Issues
+
+Record issues that need adjudication or user confirmation.

package/plugin/templates/questioning-report.json

@@ -0,0 +1,15 @@
+{
+  "task_id": "__TASK_ID__",
+  "raw_user_request": "string",
+  "known_information": [],
+  "missing_information": [],
+  "clarifying_questions": [
+    {
+      "question": "string",
+      "why_it_matters": "string",
+      "blocking": true
+    }
+  ],
+  "assumptions_if_user_does_not_answer": [],
+  "can_continue_without_user_answer": false
+}

package/plugin/templates/raw-request.md

@@ -0,0 +1,3 @@
+# Raw Request
+
+Paste the user's original request here. Preserve ambiguity and wording.

package/plugin/templates/review-aggregate.json

@@ -0,0 +1,14 @@
+{
+  "task_id": "__TASK_ID__",
+  "overall_mechanical_result": "revise",
+  "reviewers": [
+    {
+      "reviewer": "string",
+      "decision": "revise",
+      "confidence": 0.7
+    }
+  ],
+  "all_blocking_issues": [],
+  "all_suggested_changes": [],
+  "all_missing_information": []
+}

package/plugin/templates/reviewer-report.json

@@ -0,0 +1,10 @@
+{
+  "reviewer": "string",
+  "decision": "revise",
+  "confidence": 0.7,
+  "summary": "string",
+  "blocking_issues": [],
+  "suggested_changes": [],
+  "missing_information": [],
+  "evidence_refs": []
+}

package/plugin/templates/state.json

@@ -0,0 +1,23 @@
+{
+  "task_id": "__TASK_ID__",
+  "phase": "INTAKE",
+  "created_at": "__CREATED_AT__",
+  "updated_at": "__UPDATED_AT__",
+  "proposal_review_round": 0,
+  "direction_adjustment_round": 0,
+  "current_milestone_id": null,
+  "current_task_id": null,
+  "max_proposal_rework_rounds": 3,
+  "max_task_repair_rounds": 2,
+  "max_direction_adjustment_rounds": 2,
+  "status": "active",
+  "last_route_decision": "Task initialized.",
+  "history": [
+    {
+      "at": "__CREATED_AT__",
+      "from_phase": "NONE",
+      "to_phase": "INTAKE",
+      "reason": "Raw request captured."
+    }
+  ]
+}

package/plugin/templates/task-execution-report.json

@@ -0,0 +1,13 @@
+{
+  "task_id": "__TASK_ID__",
+  "milestone_id": "M1",
+  "concrete_task_id": "T1",
+  "status": "done",
+  "summary": "string",
+  "changed_files": [],
+  "commands_run": [],
+  "evidence": [],
+  "discovered_facts": [],
+  "risk_flags": [],
+  "notes_for_verifier": "string"
+}

package/plugin/templates/task-list.json

@@ -0,0 +1,20 @@
+{
+  "task_id": "__TASK_ID__",
+  "milestone_id": "M1",
+  "tasks": [
+    {
+      "id": "T1",
+      "objective": "string",
+      "inputs": [],
+      "expected_outputs": [],
+      "allowed_files": [],
+      "forbidden_files": [],
+      "allowed_commands": [],
+      "acceptance_checks": [],
+      "dependencies": [],
+      "risk": "medium",
+      "repair_attempts": 0,
+      "status": "pending"
+    }
+  ]
+}

package/plugin/templates/task-spec.json

@@ -0,0 +1,16 @@
+{
+  "task_id": "__TASK_ID__",
+  "milestone_id": "M1",
+  "concrete_task_id": "T1",
+  "objective": "string",
+  "inputs": [],
+  "expected_outputs": [],
+  "allowed_files": [],
+  "forbidden_files": [],
+  "allowed_commands": [],
+  "acceptance_checks": [],
+  "dependencies": [],
+  "risk": "medium",
+  "repair_attempts": 0,
+  "status": "pending"
+}

package/plugin/templates/task-verification-report.json

@@ -0,0 +1,13 @@
+{
+  "task_id": "__TASK_ID__",
+  "milestone_id": "M1",
+  "concrete_task_id": "T1",
+  "decision": "pass",
+  "checks_run": [],
+  "passed_checks": [],
+  "failed_checks": [],
+  "evidence_refs": [],
+  "minimal_repair_instructions": "",
+  "new_findings": [],
+  "should_trigger_direction_evaluation": false
+}

package/src/cli/commands/doctor.js

@@ -0,0 +1,171 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { parseOptions, helpRequested } from "../lib/args.js";
+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 { resolveTargets, sampleTaskRoot } from "../lib/paths.js";
+
+export function doctorHelp() {
+  return `Usage: meta-flow doctor --scope repo|user [--target <path>] [--verbose]`;
+}
+
+export async function runDoctor(argv = []) {
+  if (helpRequested(argv)) {
+    console.log(doctorHelp());
+    return 0;
+  }
+  const { options } = parseOptions(argv, {
+    scope: "string",
+    target: "string"
+  });
+  const targets = resolveTargets({ scope: options.scope || "repo", target: options.target });
+  const logger = createLogger({ verbose: options.verbose });
+  const results = [];
+
+  results.push(checkCodexCli());
+  results.push(await checkPlugin(targets));
+  results.push(await checkMarketplace(targets));
+  results.push(await checkAgents(targets));
+  results.push(await checkConfig(targets));
+  results.push(await checkPythonScripts(targets));
+  results.push(await checkSampleTask(targets));
+
+  for (const result of results) {
+    logger[result.level.toLowerCase()](`${result.title}${result.message ? ` - ${result.message}` : ""}`);
+  }
+  const hasFail = results.some((result) => result.level === "FAIL");
+  return hasFail ? 1 : 0;
+}
+
+function checkCodexCli() {
+  const found = spawnSync("codex", ["--version"], { encoding: "utf8" });
+  if (found.status === 0) {
+    return { level: "PASS", title: "Codex CLI found" };
+  }
+  return { level: "WARN", title: "Codex CLI not found", message: "Install Codex CLI or use the Codex desktop app plugin loader." };
+}
+
+async function checkPlugin(targets) {
+  const manifestPath = path.join(targets.pluginTarget, ".codex-plugin", "plugin.json");
+  const skillPath = path.join(targets.pluginTarget, "skills", "meta-flow", "SKILL.md");
+  if (!(await pathExists(manifestPath))) {
+    return { level: "FAIL", title: "plugin manifest missing", message: `Run meta-flow install --scope ${targets.scope}` };
+  }
+  const manifest = JSON.parse(await fs.readFile(manifestPath, "utf8"));
+  if (manifest.name !== "meta-flow") {
+    return { level: "FAIL", title: "plugin manifest invalid", message: "Expected name=meta-flow." };
+  }
+  if (!(await pathExists(skillPath))) {
+    return { level: "FAIL", title: "SKILL.md missing", message: "Re-run install." };
+  }
+  const skill = await fs.readFile(skillPath, "utf8");
+  if (!/^---\n[\s\S]*?name:\s*meta-flow[\s\S]*?---/m.test(skill)) {
+    return { level: "FAIL", title: "SKILL.md frontmatter invalid", message: "Reinstall plugin files." };
+  }
+  return { level: "PASS", title: "plugin and skill present" };
+}
+
+async function checkMarketplace(targets) {
+  if (!(await pathExists(targets.marketplaceTarget))) {
+    return { level: "FAIL", title: "marketplace missing", message: "Run install to create marketplace.json." };
+  }
+  const marketplace = await readJsonOrDefault(targets.marketplaceTarget, {});
+  const entry = Array.isArray(marketplace.plugins)
+    ? marketplace.plugins.find((plugin) => plugin?.name === "meta-flow")
+    : null;
+  if (!entry) {
+    return { level: "FAIL", title: "marketplace entry missing", message: "Run install to add meta-flow entry." };
+  }
+  return { level: "PASS", title: "marketplace entry present" };
+}
+
+async function checkAgents(targets) {
+  const missing = [];
+  const invalid = [];
+  for (const fileName of AGENT_FILES) {
+    const filePath = path.join(targets.agentsTarget, fileName);
+    if (!(await pathExists(filePath))) {
+      missing.push(fileName);
+      continue;
+    }
+    const result = await validateAgentTemplate(filePath);
+    if (result.missing.length) {
+      invalid.push(`${fileName}:${result.missing.join(",")}`);
+    }
+  }
+  if (missing.length || invalid.length) {
+    return {
+      level: "FAIL",
+      title: "custom agents incomplete",
+      message: `missing=[${missing.join(", ")}] invalid=[${invalid.join(", ")}]`
+    };
+  }
+  return { level: "PASS", title: "custom agents present" };
+}
+
+async function checkConfig(targets) {
+  const config = await inspectCodexConfig(targets.codexConfigTarget);
+  if (!config.exists) {
+    return { level: "FAIL", title: "Codex config missing", message: "Run install to create .codex/config.toml." };
+  }
+  if (!config.hasAgents || !config.hasMaxThreads || !config.hasMaxDepth) {
+    return { level: "WARN", title: "Codex agents config incomplete", message: "Run install --force to patch existing settings if desired." };
+  }
+  return { level: "PASS", title: "Codex agents config present" };
+}
+
+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 };
+  }
+  return { level: "PASS", title: "Python scripts runnable" };
+}
+
+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 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")],
+    [path.join(scripts, "validate_milestone_plan.py"), path.join(sampleTaskRoot, "milestone-plan.json")],
+    [path.join(scripts, "validate_task_list.py"), path.join(sampleTaskRoot, "milestones", "M1", "task-list.json")],
+    [
+      path.join(scripts, "validate_task_verification.py"),
+      path.join(sampleTaskRoot, "milestones", "M1", "tasks", "T1", "verification-report.json")
+    ]
+  ];
+  for (const args of runs) {
+    const result = spawnSync(python, args, pythonOptions());
+    if (result.status !== 0) {
+      return { level: "FAIL", title: "sample task validation failed", message: result.stderr || result.stdout };
+    }
+  }
+  return { level: "PASS", title: "sample task validation passed" };
+}
+
+function resolvePython() {
+  const python3 = spawnSync("python3", ["--version"], pythonOptions());
+  return python3.status === 0 ? "python3" : "python";
+}
+
+function pythonOptions() {
+  return {
+    encoding: "utf8",
+    env: {
+      ...process.env,
+      PYTHONDONTWRITEBYTECODE: "1"
+    }
+  };
+}

package/src/cli/commands/install.js

@@ -0,0 +1,120 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { parseOptions, helpRequested } from "../lib/args.js";
+import { installAgents } from "../lib/agents.js";
+import { patchCodexConfig } from "../lib/codex_config.js";
+import { backupIfExists } from "../lib/fs_safe.js";
+import { createLogger } from "../lib/logger.js";
+import { updateMarketplace } from "../lib/marketplace.js";
+import { installPlugin } from "../lib/plugin.js";
+import { resolveTargets } from "../lib/paths.js";
+
+export function installHelp() {
+  return `Usage: meta-flow install --scope repo|user [options]
+
+Options:
+  --target <path>   Target repo path for repo scope. Defaults to cwd.
+  --force           Overwrite conflicts after backing them up.
+  --dry-run         Print planned actions without writing files.
+  --yes             Skip confirmation prompts.
+  --no-agents       Do not install custom agent TOML files.
+  --no-plugin       Do not install the Codex plugin files.
+  --backup          Backup existing managed files before update.
+  --verbose         Print detailed actions.`;
+}
+
+export async function runInstall(argv = []) {
+  if (helpRequested(argv)) {
+    console.log(installHelp());
+    return 0;
+  }
+  const { options } = parseOptions(argv, {
+    scope: "string",
+    target: "string"
+  });
+  const scope = options.scope || "repo";
+  const targets = resolveTargets({ scope, target: options.target });
+  const logger = createLogger({ verbose: options.verbose });
+  const dryRun = Boolean(options.dryRun);
+  const force = Boolean(options.force);
+  const backup = Boolean(options.backup);
+  const installPluginEnabled = options.plugin !== false;
+  const installAgentsEnabled = options.agents !== false;
+
+  printInstallPlan(targets, {
+    installPluginEnabled,
+    installAgentsEnabled,
+    dryRun
+  });
+
+  if (backup && !dryRun) {
+    await fs.mkdir(path.dirname(targets.marketplaceTarget), { recursive: true });
+  }
+
+  if (installPluginEnabled) {
+    if (backup) {
+      await backupIfExists(targets.pluginTarget, { dryRun, logger });
+    }
+    const result = await installPlugin(targets, { dryRun, force, logger });
+    if (result.conflict) {
+      logger.warn(`plugin target exists and is not a meta-flow plugin: ${result.conflict}. Re-run with --force to overwrite.`);
+    }
+  }
+
+  await updateMarketplace(targets, { dryRun, logger });
+
+  if (installAgentsEnabled) {
+    if (backup) {
+      await backupExistingAgents(targets, { dryRun, logger });
+    }
+    const result = await installAgents(targets, { dryRun, force, logger });
+    for (const conflict of result.conflicts) {
+      logger.warn(`agent file exists without meta-flow marker; not overwritten: ${conflict}`);
+    }
+  }
+
+  const configResult = await patchCodexConfig(targets.codexConfigTarget, {
+    dryRun,
+    force,
+    backup,
+    logger
+  });
+  for (const warning of configResult.warnings) {
+    logger.warn(warning);
+  }
+
+  console.log("\nNext:");
+  console.log("1. Restart Codex.");
+  console.log(`2. Run: meta-flow doctor --scope ${scope}${scope === "repo" ? ` --target ${targets.target}` : ""}`);
+  console.log("3. In Codex, mention: $meta-flow");
+  return 0;
+}
+
+function printInstallPlan(targets, options) {
+  console.log("Meta Flow install plan:");
+  console.log(`- scope: ${targets.scope}`);
+  console.log(`- target: ${targets.target}`);
+  console.log(`- plugin: ${targets.pluginTarget}`);
+  console.log(`- marketplace: ${targets.marketplaceTarget}`);
+  console.log(`- agents: ${targets.agentsTarget}`);
+  console.log(`- config: ${targets.codexConfigTarget}`);
+  console.log("\nActions:");
+  if (options.installPluginEnabled) {
+    console.log("- copy plugin");
+  }
+  if (options.installAgentsEnabled) {
+    console.log("- install 14 agent templates");
+  }
+  console.log("- update marketplace");
+  console.log("- ensure Codex agent config");
+  if (options.dryRun) {
+    console.log("- dry-run only; no files will be written");
+  }
+}
+
+async function backupExistingAgents(targets, options) {
+  const { AGENT_FILES } = await import("../lib/agents.js");
+  for (const fileName of AGENT_FILES) {
+    await backupIfExists(path.join(targets.agentsTarget, fileName), options);
+  }
+}

package/src/cli/commands/print_paths.js

@@ -0,0 +1,20 @@
+import { parseOptions, helpRequested } from "../lib/args.js";
+import { resolveTargets } from "../lib/paths.js";
+
+export function printPathsHelp() {
+  return `Usage: meta-flow print-paths --scope repo|user [--target <path>]`;
+}
+
+export async function runPrintPaths(argv = []) {
+  if (helpRequested(argv)) {
+    console.log(printPathsHelp());
+    return 0;
+  }
+  const { options } = parseOptions(argv, {
+    scope: "string",
+    target: "string"
+  });
+  const targets = resolveTargets({ scope: options.scope || "repo", target: options.target });
+  console.log(JSON.stringify(targets, null, 2));
+  return 0;
+}