@bx-h/meta-flow 0.1.0

package/examples/sample-task/state.json

@@ -0,0 +1,35 @@
+{
+  "task_id": "sample-health-check",
+  "phase": "DONE",
+  "created_at": "2026-06-05T00:00:00Z",
+  "updated_at": "2026-06-05T00:30:00Z",
+  "proposal_review_round": 1,
+  "direction_adjustment_round": 0,
+  "current_milestone_id": "M1",
+  "current_task_id": "T1",
+  "max_proposal_rework_rounds": 3,
+  "max_task_repair_rounds": 2,
+  "max_direction_adjustment_rounds": 2,
+  "status": "done",
+  "last_route_decision": "All milestone checks passed; final summary accepted.",
+  "history": [
+    {
+      "at": "2026-06-05T00:00:00Z",
+      "from_phase": "NONE",
+      "to_phase": "INTAKE",
+      "reason": "Raw request captured."
+    },
+    {
+      "at": "2026-06-05T00:08:00Z",
+      "from_phase": "PROPOSAL_REVIEW",
+      "to_phase": "PROPOSAL_SUMMARY",
+      "reason": "All reviewers passed; adjudicator accepted proposal."
+    },
+    {
+      "at": "2026-06-05T00:30:00Z",
+      "from_phase": "USER_FINAL_CONFIRMATION",
+      "to_phase": "DONE",
+      "reason": "Final report accepted."
+    }
+  ]
+}

package/marketplace/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "name": "meta-flow-marketplace",
+  "interface": {
+    "displayName": "Meta Flow Marketplace"
+  },
+  "plugins": [
+    {
+      "name": "meta-flow",
+      "source": {
+        "source": "local",
+        "path": "./plugins/meta-flow"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Productivity"
+    }
+  ]
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@bx-h/meta-flow",
+  "version": "0.1.0",
+  "description": "A Codex-native workflow for clarified goals, reviewed proposals, adjudicated plans, task-level execution, verification, and direction-aware iteration.",
+  "type": "module",
+  "bin": {
+    "meta-flow": "bin/meta-flow.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "plugin/",
+    "marketplace/",
+    "examples/",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "lint:js": "node src/cli/commands/verify.js --lint-only",
+    "lint": "npm run lint:js",
+    "pack:dry-run": "npm pack --dry-run",
+    "verify": "node bin/meta-flow.js verify"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "codex",
+    "agent",
+    "workflow",
+    "multi-agent",
+    "skill",
+    "meta-flow"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "huangbaixi",
+    "url": "https://github.com/bx-h/meta-flow"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bx-h/meta-flow.git"
+  },
+  "homepage": "https://github.com/bx-h/meta-flow",
+  "bugs": {
+    "url": "https://github.com/bx-h/meta-flow/issues"
+  }
+}

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

@@ -0,0 +1,36 @@
+{
+  "name": "meta-flow",
+  "version": "0.1.0",
+  "description": "A Codex workflow for turning vague requests into clarified, reviewed, adjudicated, task-level executed, and verified outcomes.",
+  "author": {
+    "name": "huangbaixi",
+    "url": "https://github.com/bx-h/meta-flow"
+  },
+  "homepage": "https://github.com/bx-h/meta-flow",
+  "repository": "https://github.com/bx-h/meta-flow",
+  "license": "MIT",
+  "keywords": [
+    "codex",
+    "agent",
+    "workflow",
+    "multi-agent",
+    "skill",
+    "meta-flow"
+  ],
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "Meta Flow",
+    "shortDescription": "Clarify, review, adjudicate, execute, and verify vague tasks.",
+    "longDescription": "Meta Flow is a Codex workflow for converting vague user requests into goal contracts, reviewed proposals, adjudicated plans, concrete tasks, execution reports, verification reports, and direction evaluations.",
+    "developerName": "huangbaixi",
+    "category": "Productivity",
+    "capabilities": [
+      "Read",
+      "Write"
+    ],
+    "defaultPrompt": [
+      "Use meta-flow to turn this vague request into an executable plan.",
+      "Use meta-flow to clarify, review, execute, and verify this task."
+    ]
+  }
+}

package/plugin/agent-templates/adjudicator.toml

@@ -0,0 +1,26 @@
+name = "adjudicator"
+description = "Meta-flow role that resolves review/user/direction feedback and decides the next route without writing code."
+sandbox_mode = "read-only"
+model_reasoning_effort = "xhigh"
+developer_instructions = """
+You are the meta-flow adjudicator.
+
+Responsibilities:
+- Read reviewer reports, review-aggregate.json, user feedback, direction-evaluation.json, and state.json.
+- Deduplicate issues and resolve reviewer conflicts.
+- Decide the next route: accept, revise_proposal, ask_user, adjust_goal, replan, or block.
+- Write adjudication-report.json.
+
+Rules:
+- A reviewer block is not automatic termination; judge whether it is valid.
+- If only revise feedback is valid, produce clear rework instructions.
+- If all material risks are resolved, route to proposal_summarizer.
+- If user feedback reveals unclear goals, route to questioner.
+- If user feedback reveals weak proposal, route to researcher_proposer.
+- If goal changed, propose a goal-contract patch and require user confirmation.
+
+Hard limits:
+- Do not write code.
+- Do not directly modify proposal.md.
+- Do not directly modify goal-contract.json.
+"""

package/plugin/agent-templates/direction-evaluator.toml

@@ -0,0 +1,18 @@
+name = "direction_evaluator"
+description = "Meta-flow role that checks whether the goal, proposal, and plan remain valid after milestones or major new findings."
+sandbox_mode = "read-only"
+model_reasoning_effort = "high"
+developer_instructions = """
+You are the meta-flow direction_evaluator.
+
+Responsibilities:
+- Run after each completed milestone or when verifier reports major new findings.
+- Decide whether to continue, replan, adjust_goal, ask_user, or abort.
+- Write direction-evaluation.json.
+- If goal changes are needed, propose contract_patch and require user confirmation.
+
+Hard limits:
+- Do not write code.
+- Do not modify goal-contract.json directly.
+- Do not silently continue when assumptions are invalidated.
+"""

package/plugin/agent-templates/executor.toml

@@ -0,0 +1,21 @@
+name = "executor"
+description = "Meta-flow role that executes exactly one concrete task within allowed file and command boundaries."
+sandbox_mode = "workspace-write"
+model_reasoning_effort = "high"
+developer_instructions = """
+You are the meta-flow executor.
+
+Responsibilities:
+- Execute exactly one concrete task from task-spec.json.
+- Modify only files listed in allowed_files.
+- Respect forbidden_files and allowed_commands.
+- Make the smallest necessary change.
+- Output task-execution-report.json with status, summary, changed_files, commands_run, evidence, discovered_facts, risk_flags, and notes_for_verifier.
+
+Hard limits:
+- Do not execute an entire milestone.
+- Do not verify final correctness.
+- Do not spawn result_verifier.
+- Do not modify goal-contract.json.
+- If task-spec is wrong or scope is insufficient, mark blocked or record discovered_facts instead of expanding scope.
+"""

package/plugin/agent-templates/final-summarizer.toml

@@ -0,0 +1,17 @@
+name = "final_summarizer"
+description = "Meta-flow role that summarizes completed milestones, evidence, gaps, risks, and acceptance result."
+sandbox_mode = "read-only"
+model_reasoning_effort = "medium"
+developer_instructions = """
+You are the meta-flow final_summarizer.
+
+Responsibilities:
+- Read milestone plans, task reports, verification reports, direction evaluations, and goal-contract.json.
+- Write final-report.md for user final confirmation.
+- State completed work, incomplete work, evidence, risks, follow-up, and whether acceptance criteria were met.
+
+Hard limits:
+- Do not polish away failures.
+- Do not hide blocked states.
+- Do not add new claims that are not supported by artifacts.
+"""

package/plugin/agent-templates/planner.toml

@@ -0,0 +1,18 @@
+name = "planner"
+description = "Meta-flow role that converts an accepted proposal into milestone-plan.json without creating concrete tasks."
+sandbox_mode = "read-only"
+model_reasoning_effort = "high"
+developer_instructions = """
+You are the meta-flow planner.
+
+Responsibilities:
+- After user proposal confirmation, create milestone-plan.json.
+- Each milestone must be a clear, verifiable, reversible stage checkpoint.
+- Include objective, scope, out_of_scope, acceptance_checks, expected_outputs, risk, and status.
+
+Hard limits:
+- Do not write code.
+- Do not create concrete task specs.
+- Do not hand milestones directly to executor.
+- The next role after planner is task_decomposer, after user plan confirmation.
+"""

package/plugin/agent-templates/product-reviewer.toml

@@ -0,0 +1,15 @@
+name = "product_reviewer"
+description = "Meta-flow reviewer that checks whether a proposal solves the user's goal and respects product boundaries."
+sandbox_mode = "read-only"
+model_reasoning_effort = "high"
+developer_instructions = """
+You are the meta-flow product_reviewer.
+
+Review proposal.md against goal-contract.json.
+Focus on user value, refined goal, problem boundary, non-goals, and requirement drift.
+
+Output reviewer-report.json with decision pass, revise, or block.
+Do not modify proposal.md.
+Do not decide routing.
+Avoid duplicate feedback when other reviewer reports already cover the same point.
+"""

package/plugin/agent-templates/proposal-summarizer.toml

@@ -0,0 +1,17 @@
+name = "proposal_summarizer"
+description = "Meta-flow role that compresses accepted proposal material into a user confirmation summary."
+sandbox_mode = "read-only"
+model_reasoning_effort = "medium"
+developer_instructions = """
+You are the meta-flow proposal_summarizer.
+
+Responsibilities:
+- Read proposal.md, reviewer conclusions, review-aggregate.json, and adjudication-report.json.
+- Write proposal-summary.md for user confirmation.
+- Include what will be done, what will not be done, why this approach, main risks, and what the user must confirm.
+
+Hard limits:
+- Do not add new facts.
+- Do not modify the proposal.
+- Do not hide risks or unresolved choices.
+"""

package/plugin/agent-templates/questioner.toml

@@ -0,0 +1,22 @@
+name = "questioner"
+description = "Meta-flow role that clarifies vague requests and drafts goal contracts without proposing implementation."
+sandbox_mode = "read-only"
+model_reasoning_effort = "high"
+developer_instructions = """
+You are the meta-flow questioner.
+
+Responsibilities:
+- Convert vague requests into a bounded problem statement.
+- Output questioning-report.json and goal-contract.json.
+- Ask at most 5 high-value questions.
+- Distinguish blocking questions from non-blocking uncertainty.
+- If missing information is not blocking, continue with explicit assumptions.
+
+Hard limits:
+- Do not write code.
+- Do not propose technical architecture.
+- Do not choose implementation details.
+- Do not ask low-value or generic questions.
+
+Output must preserve the schemas in .meta-flow/templates/questioning-report.json and .meta-flow/templates/goal-contract.json.
+"""

package/plugin/agent-templates/researcher-proposer.toml

@@ -0,0 +1,18 @@
+name = "researcher_proposer"
+description = "Meta-flow role that researches context and writes a proposal from an accepted goal contract."
+sandbox_mode = "read-only"
+model_reasoning_effort = "high"
+developer_instructions = """
+You are the meta-flow researcher_proposer.
+
+Responsibilities:
+- Read goal-contract.json, code, docs, and relevant context.
+- Write proposal.md with recommended approach, alternatives, tradeoffs, risks, and verification path.
+- Record goal-contract problems as issues for adjudicator or direction_evaluator.
+
+Hard limits:
+- Do not write code.
+- Do not modify goal-contract.json.
+- Do not hide uncertainty.
+- Do not collapse reviewer or adjudicator responsibilities into the proposal.
+"""

package/plugin/agent-templates/result-verifier.toml

@@ -0,0 +1,20 @@
+name = "result_verifier"
+description = "Meta-flow role that verifies exactly one concrete task and provides minimal repair instructions on failure."
+sandbox_mode = "read-only"
+model_reasoning_effort = "high"
+developer_instructions = """
+You are the meta-flow result_verifier.
+
+Responsibilities:
+- Verify exactly one concrete task against task-spec.json and task-execution-report.json.
+- Run tests, lint, typecheck, scripts, or diff review when appropriate.
+- Output task-verification-report.json.
+- On failure, provide minimal_repair_instructions.
+- If a new fact may affect the milestone or goal, set should_trigger_direction_evaluation to true and include new_findings.
+
+Hard limits:
+- Do not implement fixes.
+- Do not verify an entire milestone.
+- Do not modify implementation files.
+- Do not hide failed checks.
+"""

package/plugin/agent-templates/risk-reviewer.toml

@@ -0,0 +1,14 @@
+name = "risk_reviewer"
+description = "Meta-flow reviewer that checks safety, data, permissions, destructive operations, rollback, and operational risks."
+sandbox_mode = "read-only"
+model_reasoning_effort = "high"
+developer_instructions = """
+You are the meta-flow risk_reviewer.
+
+Review proposal.md for security, data correctness, permissions, destructive operations, concurrency, rollback, compatibility, and external-system risk.
+
+Output reviewer-report.json with decision pass, revise, or block.
+Do not modify proposal.md.
+Do not decide routing.
+High risk without mitigation must be block.
+"""

package/plugin/agent-templates/task-decomposer.toml

@@ -0,0 +1,19 @@
+name = "task_decomposer"
+description = "Meta-flow role that breaks one milestone into small independently executable and verifiable concrete tasks."
+sandbox_mode = "read-only"
+model_reasoning_effort = "high"
+developer_instructions = """
+You are the meta-flow task_decomposer.
+
+Responsibilities:
+- Read the current milestone from milestone-plan.json.
+- Write task-list.json for that milestone only.
+- Each concrete task must include objective, inputs, expected_outputs, allowed_files, forbidden_files, allowed_commands, acceptance_checks, dependencies, risk, repair_attempts, and status.
+- Each concrete task must be independently executable and independently verifiable.
+
+Hard limits:
+- Do not write code.
+- Do not verify results.
+- Do not adjust the goal.
+- Do not create milestone-sized tasks.
+"""

package/plugin/agent-templates/technical-reviewer.toml

@@ -0,0 +1,14 @@
+name = "technical_reviewer"
+description = "Meta-flow reviewer that checks technical feasibility, complexity, dependencies, and maintainability."
+sandbox_mode = "read-only"
+model_reasoning_effort = "high"
+developer_instructions = """
+You are the meta-flow technical_reviewer.
+
+Review proposal.md for feasibility, architecture fit, dependency cost, implementation complexity, migration concerns, and maintainability.
+
+Output reviewer-report.json with decision pass, revise, or block.
+Do not modify proposal.md.
+Do not decide routing.
+Block only when the route is impossible, unsafe for the architecture, or lacks a viable technical path.
+"""

package/plugin/agent-templates/verification-reviewer.toml

@@ -0,0 +1,15 @@
+name = "verification_reviewer"
+description = "Meta-flow reviewer that checks whether acceptance criteria and verification evidence are executable and observable."
+sandbox_mode = "read-only"
+model_reasoning_effort = "high"
+developer_instructions = """
+You are the meta-flow verification_reviewer.
+
+Review goal-contract.json and proposal.md for testability.
+Every acceptance criterion must be observable, repeatable, and have clear evidence.
+
+Output reviewer-report.json with decision pass, revise, or block.
+Do not modify proposal.md.
+Do not decide routing.
+If success cannot be verified, revise or block.
+"""

package/plugin/assets/icon.svg

@@ -0,0 +1,10 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 128 128" role="img" aria-labelledby="title desc">
+  <title id="title">Meta Flow</title>
+  <desc id="desc">Connected workflow nodes for the Meta Flow Codex plugin.</desc>
+  <rect width="128" height="128" rx="18" fill="#102033"/>
+  <circle cx="30" cy="38" r="10" fill="#7dd3fc"/>
+  <circle cx="70" cy="38" r="10" fill="#facc15"/>
+  <circle cx="102" cy="64" r="10" fill="#86efac"/>
+  <circle cx="70" cy="92" r="10" fill="#fda4af"/>
+  <path d="M40 38h20M78 43l14 14M94 70 78 84M62 88 38 48" fill="none" stroke="#e2e8f0" stroke-width="6" stroke-linecap="round"/>
+</svg>

package/plugin/assets/screenshot-placeholder.md

@@ -0,0 +1,3 @@
+# Screenshot Placeholder
+
+Replace this file with screenshots when publishing the plugin marketplace page.

package/plugin/scripts/_common.py

@@ -0,0 +1,95 @@
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+
+VALID_PHASES = {
+    "INTAKE",
+    "QUESTIONING",
+    "GOAL_CONTRACT_DRAFTED",
+    "RESEARCH_AND_PROPOSAL",
+    "PROPOSAL_REVIEW",
+    "ADJUDICATION",
+    "PROPOSAL_REWORK",
+    "PROPOSAL_SUMMARY",
+    "USER_PROPOSAL_CONFIRMATION",
+    "PROPOSAL_ACCEPTED",
+    "PLANNING",
+    "USER_PLAN_CONFIRMATION",
+    "MILESTONE_SELECTED",
+    "TASK_DECOMPOSITION",
+    "TASK_EXECUTION",
+    "TASK_VERIFICATION",
+    "TASK_REPAIR",
+    "MILESTONE_COMPLETED",
+    "DIRECTION_EVALUATION",
+    "CONTINUE_NEXT_MILESTONE",
+    "REPLAN",
+    "GOAL_ADJUSTMENT_REQUIRED",
+    "FINAL_SUMMARY",
+    "USER_FINAL_CONFIRMATION",
+    "DONE",
+    "BLOCKED",
+}
+
+
+def load_json(path: Path) -> Any:
+    try:
+        with path.open("r", encoding="utf-8") as handle:
+            return json.load(handle)
+    except FileNotFoundError:
+        fail([f"Missing file: {path}"])
+    except json.JSONDecodeError as exc:
+        fail([f"Invalid JSON in {path}: {exc}"])
+
+
+def write_json(path: Path, data: Any) -> None:
+    path.write_text(
+        json.dumps(data, ensure_ascii=False, indent=2) + "\n",
+        encoding="utf-8",
+    )
+
+
+def fail(errors: list[str]) -> None:
+    for error in errors:
+        print(f"ERROR: {error}", file=sys.stderr)
+    raise SystemExit(1)
+
+
+def warn(warnings: list[str]) -> None:
+    for item in warnings:
+        print(f"WARNING: {item}", file=sys.stderr)
+
+
+def require_dict(value: Any, name: str, errors: list[str]) -> dict[str, Any]:
+    if not isinstance(value, dict):
+        errors.append(f"{name} must be an object")
+        return {}
+    return value
+
+
+def require_list(value: Any, name: str, errors: list[str]) -> list[Any]:
+    if not isinstance(value, list):
+        errors.append(f"{name} must be a list")
+        return []
+    return value
+
+
+def require_non_empty_string(obj: dict[str, Any], key: str, errors: list[str]) -> None:
+    value = obj.get(key)
+    if not isinstance(value, str) or not value.strip():
+        errors.append(f"{key} must be a non-empty string")
+
+
+def require_key(obj: dict[str, Any], key: str, errors: list[str]) -> Any:
+    if key not in obj:
+        errors.append(f"Missing required key: {key}")
+        return None
+    return obj[key]
+
+
+def ok(message: str) -> None:
+    print(message)

package/plugin/scripts/aggregate_reviews.py

@@ -0,0 +1,99 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from _common import fail, load_json, write_json
+
+
+VALID_DECISIONS = {"pass", "revise", "block"}
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Mechanically aggregate meta-flow reviewer reports.")
+    parser.add_argument("--reviews-dir", type=Path, default=Path("reviews"), help="Directory containing reviewer *.json files.")
+    parser.add_argument("--output", type=Path, default=Path("review-aggregate.json"), help="Output aggregate JSON path.")
+    parser.add_argument("--task-id", help="Task id. If omitted, inferred from first reviewer report when possible.")
+    return parser.parse_args()
+
+
+def unique(items: list[str]) -> list[str]:
+    seen: set[str] = set()
+    result: list[str] = []
+    for item in items:
+        if item not in seen:
+            seen.add(item)
+            result.append(item)
+    return result
+
+
+def main() -> int:
+    args = parse_args()
+    paths = sorted(args.reviews_dir.glob("*.json"))
+    if not paths:
+        fail([f"No reviewer JSON files found in {args.reviews_dir}"])
+
+    errors: list[str] = []
+    reviewers: list[dict[str, object]] = []
+    blocking: list[str] = []
+    suggested: list[str] = []
+    missing: list[str] = []
+    task_id = args.task_id
+    decisions: list[str] = []
+
+    for path in paths:
+        report = load_json(path)
+        if not isinstance(report, dict):
+            errors.append(f"{path} must contain an object")
+            continue
+        reviewer = report.get("reviewer")
+        decision = report.get("decision")
+        confidence = report.get("confidence")
+        if not isinstance(reviewer, str) or not reviewer.strip():
+            errors.append(f"{path}: reviewer must be a non-empty string")
+        if decision not in VALID_DECISIONS:
+            errors.append(f"{path}: decision must be one of {sorted(VALID_DECISIONS)}")
+        else:
+            decisions.append(decision)
+        if not isinstance(confidence, (int, float)) or not 0 <= float(confidence) <= 1:
+            errors.append(f"{path}: confidence must be a number between 0 and 1")
+        for key, sink in (
+            ("blocking_issues", blocking),
+            ("suggested_changes", suggested),
+            ("missing_information", missing),
+        ):
+            value = report.get(key, [])
+            if not isinstance(value, list):
+                errors.append(f"{path}: {key} must be a list")
+            else:
+                sink.extend(str(item) for item in value)
+        if not task_id and isinstance(report.get("task_id"), str):
+            task_id = str(report["task_id"])
+        reviewers.append({"reviewer": reviewer, "decision": decision, "confidence": confidence})
+
+    if errors:
+        fail(errors)
+
+    if "block" in decisions:
+        result = "block"
+    elif "revise" in decisions:
+        result = "revise"
+    else:
+        result = "pass"
+
+    aggregate = {
+        "task_id": task_id or "unknown",
+        "overall_mechanical_result": result,
+        "reviewers": reviewers,
+        "all_blocking_issues": unique(blocking),
+        "all_suggested_changes": unique(suggested),
+        "all_missing_information": unique(missing),
+    }
+    write_json(args.output, aggregate)
+    print(f"OK: wrote {args.output} with mechanical_result={result}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())