@bx-h/meta-flow 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## 0.1.0
+
+- Initial Codex Plugin and npm installer package.
+- Added meta-flow Skill, role references, agent templates, templates, scripts, docs, and sample task.
+- Added safe install, uninstall, doctor, verify, and print-paths commands.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 huangbaixi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,172 @@
+# Meta Flow Codex
+
+Meta Flow is a Codex-native workflow for turning vague requests into clarified goals, reviewed proposals, adjudicated plans, concrete tasks, verified results, and direction-aware iteration.
+
+## Install
+
+Repo scope:
+
+```bash
+npx @bx-h/meta-flow@latest install --scope repo
+```
+
+User scope:
+
+```bash
+npx @bx-h/meta-flow@latest install --scope user
+```
+
+Global CLI:
+
+```bash
+npm i -g @bx-h/meta-flow
+meta-flow install --scope repo
+```
+
+Pinned version:
+
+```bash
+npx @bx-h/meta-flow@0.1.0 install --scope repo
+```
+
+## Quick Start
+
+1. Install with repo or user scope.
+2. Restart Codex.
+3. In Codex, say:
+
+```text
+Use $meta-flow for this request: "I want to improve our backend observability but I'm not sure where to start."
+```
+
+You can check installation state with:
+
+```bash
+meta-flow doctor --scope repo
+```
+
+## When To Use It
+
+- Vague requests.
+- Multi-stage tasks.
+- High-reliability implementation.
+- Work that needs a proposal before execution.
+- Work that needs task-level verification.
+- Work where execution may reveal facts that require goal adjustment.
+
+## When Not To Use It
+
+- Questions answerable in one response.
+- Tiny code edits.
+- Tasks without definable acceptance criteria.
+- Pure discussion with no observable artifact.
+
+## Workflow
+
+Proposal phase:
+
+```mermaid
+flowchart LR
+  A["INTAKE"] --> B["QUESTIONING"]
+  B --> C["GOAL_CONTRACT_DRAFTED"]
+  C --> D["RESEARCH_AND_PROPOSAL"]
+  D --> E["PROPOSAL_REVIEW"]
+  E --> F["ADJUDICATION"]
+  F -->|revise| G["PROPOSAL_REWORK"]
+  G --> E
+  F -->|accept| H["PROPOSAL_SUMMARY"]
+  H --> I["USER_PROPOSAL_CONFIRMATION"]
+```
+
+Execution phase:
+
+```mermaid
+flowchart LR
+  A["PLANNING"] --> B["USER_PLAN_CONFIRMATION"]
+  B --> C["MILESTONE_SELECTED"]
+  C --> D["TASK_DECOMPOSITION"]
+  D --> E["TASK_EXECUTION"]
+  E --> F["TASK_VERIFICATION"]
+  F -->|repair| G["TASK_REPAIR"]
+  G --> E
+  F -->|pass| H["MILESTONE_COMPLETED"]
+  H --> I["DIRECTION_EVALUATION"]
+  I -->|continue| C
+  I -->|replan| A
+  I -->|adjust goal| J["GOAL_ADJUSTMENT_REQUIRED"]
+  I -->|done| K["FINAL_SUMMARY"]
+  K --> L["USER_FINAL_CONFIRMATION"]
+```
+
+## Roles
+
+- `questioner`: clarifies ambiguity and drafts the goal contract.
+- `researcher-proposer`: researches and writes the proposal.
+- `reviewers`: product, technical, risk, and verification reviewers.
+- `adjudicator`: resolves reviewer/user/direction feedback and routes the workflow.
+- `proposal-summarizer`: writes the user confirmation summary.
+- `planner`: creates milestone checkpoints.
+- `direction-evaluator`: decides whether the goal and plan still hold.
+- `task-decomposer`: creates concrete tasks for a milestone.
+- `executor`: executes exactly one concrete task.
+- `result-verifier`: verifies exactly one concrete task.
+- `final-summarizer`: writes completion evidence, gaps, and residual risk.
+
+## File Write Scope
+
+Repo scope writes under the target repo:
+
+- `<repo>/plugins/meta-flow`
+- `<repo>/.agents/plugins/marketplace.json`
+- `<repo>/.codex/agents/*.toml`
+- `<repo>/.codex/config.toml`
+
+User scope writes under the current user home:
+
+- `~/.codex/plugins/meta-flow`
+- `~/.agents/plugins/marketplace.json`
+- `~/.codex/agents/*.toml`
+- `~/.codex/config.toml`
+
+Task data under `.meta-flow/tasks` is not removed by uninstall.
+
+## Uninstall
+
+```bash
+meta-flow uninstall --scope repo --yes
+meta-flow uninstall --scope user --yes
+```
+
+Run a preview first:
+
+```bash
+meta-flow uninstall --scope repo --dry-run
+```
+
+## Safety
+
+- No `postinstall` script modifies your system.
+- The installer writes files only after explicit `meta-flow install`.
+- No telemetry is collected.
+- User code, config, and task content are not uploaded.
+- Use `--dry-run` before installing.
+- Existing unmanaged files are not overwritten unless `--force` is used.
+- Overwrites support backups.
+- Prefer pinned versions for reproducible installs.
+
+## Codex Marketplace
+
+You can also distribute the plugin through a Codex marketplace entry:
+
+```bash
+codex plugin marketplace add bx-h/meta-flow --ref v0.1.0
+```
+
+The npm installer still matters because it also materializes custom agent TOML files and validation scripts.
+
+## Developer Docs
+
+- [Architecture](docs/architecture.md)
+- [Installation](docs/installation.md)
+- [Publishing](docs/publishing.md)
+- [Security](docs/security.md)

package/bin/meta-flow.js

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

package/examples/sample-task/adjudication-report.json

@@ -0,0 +1,14 @@
+{
+  "task_id": "sample-health-check",
+  "source": "reviewers",
+  "decision": "accept",
+  "rationale": "All reviewers passed. Suggested changes are compatible and can be carried into implementation constraints.",
+  "resolved_conflicts": [],
+  "deduplicated_issues": [
+    "Keep the endpoint shallow and document that boundary.",
+    "Use existing tests and dependencies."
+  ],
+  "instructions_for_next_agent": "Summarize the accepted proposal for user confirmation, preserving shallow health-check scope and validation expectations.",
+  "next_phase": "PROPOSAL_SUMMARY",
+  "requires_user_confirmation": false
+}

package/examples/sample-task/final-report.md

@@ -0,0 +1,26 @@
+# Final Report
+
+## Completed
+
+- Added a shallow `GET /healthz` endpoint.
+- Added a focused route test.
+- Documented endpoint path, response, and shallow liveness scope.
+
+## Not Completed
+
+- No deep dependency readiness checks were added.
+- No deployment, monitoring, or load balancer configuration was changed.
+
+## Evidence
+
+- `pytest tests/test_health.py` passed in the sample execution report.
+- Documentation review passed.
+- Dependency manifest review passed.
+
+## Risks And Follow-Up
+
+If operations need readiness semantics, create a separate proposal for dependency checks and rollout behavior.
+
+## Acceptance Criteria Result
+
+All acceptance criteria in `goal-contract.json` are satisfied in this sample flow.

package/examples/sample-task/goal-contract.json

@@ -0,0 +1,44 @@
+{
+  "task_id": "sample-health-check",
+  "raw_user_request": "为一个后端项目增加健康检查接口，并确保它有测试和文档。",
+  "refined_goal": "Add a shallow backend health check endpoint with tests and documentation.",
+  "problem_boundary": "Implement one liveness endpoint in the backend service, verify the endpoint response, and document its purpose and response contract.",
+  "non_goals": [
+    "Do not add deep dependency probes for databases, caches, queues, or third-party services.",
+    "Do not change deployment, load balancer, or monitoring configuration.",
+    "Do not refactor unrelated routing code."
+  ],
+  "assumptions": [
+    "The backend already has a route registration pattern.",
+    "GET /healthz is acceptable unless a local convention says otherwise.",
+    "A shallow liveness check is safer for a first implementation."
+  ],
+  "constraints": [
+    "Use existing backend framework and test runner.",
+    "Keep the endpoint side-effect free.",
+    "Do not introduce new runtime dependencies."
+  ],
+  "success_definition": "A caller can request the health endpoint and receive a deterministic success response; tests and documentation describe the behavior.",
+  "acceptance_criteria": [
+    {
+      "id": "AC1",
+      "criterion": "GET /healthz returns HTTP 200 with a JSON body containing status=ok.",
+      "verification_method": "test",
+      "evidence_required": "Passing route test output."
+    },
+    {
+      "id": "AC2",
+      "criterion": "Endpoint behavior and non-goals are documented.",
+      "verification_method": "review",
+      "evidence_required": "Docs diff includes endpoint path, response, and shallow-check limitation."
+    },
+    {
+      "id": "AC3",
+      "criterion": "No new runtime dependency is added.",
+      "verification_method": "review",
+      "evidence_required": "Dependency manifest diff is empty or unchanged."
+    }
+  ],
+  "risk_level": "medium",
+  "requires_user_confirmation": true
+}

package/examples/sample-task/milestone-plan.json

@@ -0,0 +1,31 @@
+{
+  "task_id": "sample-health-check",
+  "milestones": [
+    {
+      "id": "M1",
+      "objective": "Add and verify a shallow health check endpoint.",
+      "scope": [
+        "Route implementation",
+        "Route test",
+        "Endpoint documentation"
+      ],
+      "out_of_scope": [
+        "Dependency readiness checks",
+        "Deployment configuration",
+        "Monitoring dashboards"
+      ],
+      "acceptance_checks": [
+        "Health route test passes.",
+        "Docs describe endpoint path, response, and shallow scope.",
+        "No new runtime dependency is introduced."
+      ],
+      "expected_outputs": [
+        "Endpoint code",
+        "Test coverage",
+        "Documentation update"
+      ],
+      "risk": "medium",
+      "status": "done"
+    }
+  ]
+}

package/examples/sample-task/milestones/M1/direction-evaluation.json

@@ -0,0 +1,16 @@
+{
+  "task_id": "sample-health-check",
+  "milestone_id": "M1",
+  "decision": "continue",
+  "summary": "The milestone satisfied the original goal without invalidating proposal assumptions.",
+  "new_findings": [],
+  "invalidated_assumptions": [],
+  "goal_drift_detected": false,
+  "proposal_patch_needed": false,
+  "contract_patch": {
+    "proposed_changes": [],
+    "reason": "No goal change required.",
+    "requires_user_confirmation": false
+  },
+  "next_phase": "FINAL_SUMMARY"
+}

package/examples/sample-task/milestones/M1/task-list.json

@@ -0,0 +1,41 @@
+{
+  "task_id": "sample-health-check",
+  "milestone_id": "M1",
+  "tasks": [
+    {
+      "id": "T1",
+      "objective": "Implement GET /healthz, add a focused route test, and document shallow liveness behavior.",
+      "inputs": [
+        "goal-contract.json",
+        "proposal.md",
+        "milestone-plan.json"
+      ],
+      "expected_outputs": [
+        "A route handler returning HTTP 200 and status=ok.",
+        "A passing route test.",
+        "Documentation for endpoint path, response, and non-goals."
+      ],
+      "allowed_files": [
+        "src/routes/health.py",
+        "tests/test_health.py",
+        "docs/api.md"
+      ],
+      "forbidden_files": [
+        "deployment/**",
+        "requirements.txt"
+      ],
+      "allowed_commands": [
+        "pytest tests/test_health.py"
+      ],
+      "acceptance_checks": [
+        "pytest tests/test_health.py passes.",
+        "docs/api.md mentions GET /healthz and shallow liveness.",
+        "requirements.txt is unchanged."
+      ],
+      "dependencies": [],
+      "risk": "medium",
+      "repair_attempts": 0,
+      "status": "passed"
+    }
+  ]
+}

package/examples/sample-task/milestones/M1/tasks/T1/execution-report.json

@@ -0,0 +1,25 @@
+{
+  "task_id": "sample-health-check",
+  "milestone_id": "M1",
+  "concrete_task_id": "T1",
+  "status": "done",
+  "summary": "Implemented a shallow health endpoint, added a route test, and documented the endpoint contract.",
+  "changed_files": [
+    "src/routes/health.py",
+    "tests/test_health.py",
+    "docs/api.md"
+  ],
+  "commands_run": [
+    "pytest tests/test_health.py"
+  ],
+  "evidence": [
+    "pytest tests/test_health.py -> passed",
+    "docs/api.md contains GET /healthz documentation",
+    "requirements.txt unchanged"
+  ],
+  "discovered_facts": [
+    "The endpoint is intentionally shallow and does not touch dependencies."
+  ],
+  "risk_flags": [],
+  "notes_for_verifier": "Check route response, docs wording, and dependency manifest."
+}

package/examples/sample-task/milestones/M1/tasks/T1/task-spec.json

@@ -0,0 +1,37 @@
+{
+  "task_id": "sample-health-check",
+  "milestone_id": "M1",
+  "concrete_task_id": "T1",
+  "objective": "Implement GET /healthz, add a focused route test, and document shallow liveness behavior.",
+  "inputs": [
+    "goal-contract.json",
+    "proposal.md",
+    "milestones/M1/task-list.json"
+  ],
+  "expected_outputs": [
+    "A route handler returning HTTP 200 and status=ok.",
+    "A passing route test.",
+    "Documentation for endpoint path, response, and non-goals."
+  ],
+  "allowed_files": [
+    "src/routes/health.py",
+    "tests/test_health.py",
+    "docs/api.md"
+  ],
+  "forbidden_files": [
+    "deployment/**",
+    "requirements.txt"
+  ],
+  "allowed_commands": [
+    "pytest tests/test_health.py"
+  ],
+  "acceptance_checks": [
+    "pytest tests/test_health.py passes.",
+    "docs/api.md mentions GET /healthz and shallow liveness.",
+    "requirements.txt is unchanged."
+  ],
+  "dependencies": [],
+  "risk": "medium",
+  "repair_attempts": 0,
+  "status": "passed"
+}

package/examples/sample-task/milestones/M1/tasks/T1/verification-report.json

@@ -0,0 +1,23 @@
+{
+  "task_id": "sample-health-check",
+  "milestone_id": "M1",
+  "concrete_task_id": "T1",
+  "decision": "pass",
+  "checks_run": [
+    "pytest tests/test_health.py",
+    "documentation review",
+    "dependency diff review"
+  ],
+  "passed_checks": [
+    "Route test passed.",
+    "Documentation states GET /healthz response and shallow liveness scope.",
+    "No dependency manifest change."
+  ],
+  "failed_checks": [],
+  "evidence_refs": [
+    "execution-report.json#evidence"
+  ],
+  "minimal_repair_instructions": "",
+  "new_findings": [],
+  "should_trigger_direction_evaluation": false
+}

package/examples/sample-task/proposal-summary.md

@@ -0,0 +1,21 @@
+# Proposal Summary
+
+## What Will Be Done
+
+Add `GET /healthz` as a shallow backend liveness endpoint, with a route test and documentation.
+
+## What Will Not Be Done
+
+No database, cache, queue, or external service readiness checks. No deployment or monitoring configuration changes.
+
+## Why This Approach
+
+A shallow liveness endpoint is deterministic, low-risk, and enough to satisfy the initial user request.
+
+## Main Risks
+
+The repo may already prefer a different health endpoint path. Documentation must prevent operators from assuming this is a deep readiness check.
+
+## User Confirmation Needed
+
+Confirm that a shallow `GET /healthz` endpoint is the intended first version.

package/examples/sample-task/proposal.md

@@ -0,0 +1,29 @@
+# Proposal
+
+## Goal
+
+Add a shallow backend liveness endpoint with tests and documentation.
+
+## Recommended Approach
+
+Implement `GET /healthz` using the existing route registration pattern. The endpoint returns HTTP 200 and a JSON body such as `{"status":"ok"}`. Add a focused route test and document that this is a shallow liveness check, not a dependency readiness check.
+
+This keeps behavior deterministic and avoids coupling deploy health to external systems.
+
+## Alternatives
+
+- Deep readiness endpoint: useful later, but higher risk because dependency outages may affect rollout behavior.
+- Framework middleware/plugin: unnecessary unless the repo already standardizes on one.
+- Reuse an existing status endpoint: possible, but only if it already has the same semantics.
+
+## Risks
+
+- Existing route conventions may prefer `/health` over `/healthz`.
+- Tests may need framework-specific fixtures.
+- Operators may expect dependency checks; documentation must state the shallow scope.
+
+## Verification
+
+- Run the backend route test.
+- Review docs for endpoint path, response shape, and non-goals.
+- Confirm dependency files are unchanged.

package/examples/sample-task/questioning-report.json

@@ -0,0 +1,31 @@
+{
+  "task_id": "sample-health-check",
+  "raw_user_request": "为一个后端项目增加健康检查接口，并确保它有测试和文档。",
+  "known_information": [
+    "The user wants a backend health check endpoint.",
+    "Tests and documentation are required outputs."
+  ],
+  "missing_information": [
+    "Backend framework is not specified.",
+    "Exact endpoint path is not specified.",
+    "Health check depth is not specified."
+  ],
+  "clarifying_questions": [
+    {
+      "question": "Should the endpoint be shallow liveness only, or include dependency checks?",
+      "why_it_matters": "Dependency checks can turn transient database or cache issues into deployment failures.",
+      "blocking": false
+    },
+    {
+      "question": "Is there an existing route convention for health endpoints?",
+      "why_it_matters": "Following local route naming prevents compatibility drift.",
+      "blocking": false
+    }
+  ],
+  "assumptions_if_user_does_not_answer": [
+    "Use GET /healthz as a shallow liveness endpoint.",
+    "Return HTTP 200 with a small JSON body.",
+    "Do not add database, cache, or third-party dependency probes in this first pass."
+  ],
+  "can_continue_without_user_answer": true
+}

package/examples/sample-task/raw-request.md

@@ -0,0 +1 @@
+为一个后端项目增加健康检查接口，并确保它有测试和文档。

package/examples/sample-task/review-aggregate.json

@@ -0,0 +1,34 @@
+{
+  "task_id": "sample-health-check",
+  "overall_mechanical_result": "pass",
+  "reviewers": [
+    {
+      "reviewer": "product_reviewer",
+      "decision": "pass",
+      "confidence": 0.86
+    },
+    {
+      "reviewer": "risk_reviewer",
+      "decision": "pass",
+      "confidence": 0.8
+    },
+    {
+      "reviewer": "technical_reviewer",
+      "decision": "pass",
+      "confidence": 0.82
+    },
+    {
+      "reviewer": "verification_reviewer",
+      "decision": "pass",
+      "confidence": 0.88
+    }
+  ],
+  "all_blocking_issues": [],
+  "all_suggested_changes": [
+    "Make the shallow versus deep health check boundary explicit in documentation.",
+    "Do not include database/cache checks without a separate readiness design.",
+    "Use existing route test utilities rather than adding a new testing dependency.",
+    "Record the exact test command in task-execution-report.json."
+  ],
+  "all_missing_information": []
+}

package/examples/sample-task/reviews/product-reviewer.json

@@ -0,0 +1,16 @@
+{
+  "task_id": "sample-health-check",
+  "reviewer": "product_reviewer",
+  "decision": "pass",
+  "confidence": 0.86,
+  "summary": "The proposal addresses the user's request and keeps the initial scope clear.",
+  "blocking_issues": [],
+  "suggested_changes": [
+    "Make the shallow versus deep health check boundary explicit in documentation."
+  ],
+  "missing_information": [],
+  "evidence_refs": [
+    "goal-contract.json#refined_goal",
+    "proposal.md#Recommended Approach"
+  ]
+}

package/examples/sample-task/reviews/risk-reviewer.json

@@ -0,0 +1,16 @@
+{
+  "task_id": "sample-health-check",
+  "reviewer": "risk_reviewer",
+  "decision": "pass",
+  "confidence": 0.8,
+  "summary": "The shallow endpoint avoids coupling health to dependencies and has low operational risk.",
+  "blocking_issues": [],
+  "suggested_changes": [
+    "Do not include database/cache checks without a separate readiness design."
+  ],
+  "missing_information": [],
+  "evidence_refs": [
+    "goal-contract.json#non_goals",
+    "proposal.md#Risks"
+  ]
+}

package/examples/sample-task/reviews/technical-reviewer.json

@@ -0,0 +1,16 @@
+{
+  "task_id": "sample-health-check",
+  "reviewer": "technical_reviewer",
+  "decision": "pass",
+  "confidence": 0.82,
+  "summary": "The implementation path is small and should fit existing backend route patterns.",
+  "blocking_issues": [],
+  "suggested_changes": [
+    "Use existing route test utilities rather than adding a new testing dependency."
+  ],
+  "missing_information": [],
+  "evidence_refs": [
+    "goal-contract.json#constraints",
+    "proposal.md#Alternatives"
+  ]
+}

package/examples/sample-task/reviews/verification-reviewer.json

@@ -0,0 +1,15 @@
+{
+  "task_id": "sample-health-check",
+  "reviewer": "verification_reviewer",
+  "decision": "pass",
+  "confidence": 0.88,
+  "summary": "The acceptance criteria are observable through route tests and documentation review.",
+  "blocking_issues": [],
+  "suggested_changes": [
+    "Record the exact test command in task-execution-report.json."
+  ],
+  "missing_information": [],
+  "evidence_refs": [
+    "goal-contract.json#acceptance_criteria"
+  ]
+}