Goalflow

README

# OpenClaw GoalFlow

GoalFlow is an OpenClaw plugin for goal-driven execution. It turns a broad request into an explicit goal, confirms the scope with the user, tracks evidence, runs verifier-gated progress checks, and finishes only when the agreed criteria are satisfied.

It is meant for work where "done" should be proven, not guessed.

## What It Does

- Drafts a goal with scope, non-goals, success criteria, and verifier profiles.
- Requires user confirmation when the goal is materially ambiguous or risky.
- Tracks goal progress through OpenClaw TaskFlow.
- Runs verifier-gated progress checks.
- Stores evidence and optional claims for explainable completion judgment.
- Finishes only when required evidence is present and verification has passed.

GoalFlow does not replace operator judgment for risky runtime actions. Gateway restarts, package-manager changes, external writes, database changes, browser automation, and public actions still need explicit approval.

## Flow

```mermaid
%%{init: {"themeVariables": {"fontSize": "8px"}, "flowchart": {"nodeSpacing": 18, "rankSpacing": 20}} }%%
flowchart TD
  A[User asks] --> B[Draft goal]
  B --> C[Show scope, criteria, evidence]
  C --> D{Confirm?}
  D -- Yes --> E[User edits or approves]
  D -- No --> F[Create state]
  E --> F
  F --> G[Work step]
  G --> H[Collect evidence + claims]
  H --> I[Verify]
  I --> J{Satisfied?}
  J -- No --> G
  J -- Yes --> K[Finish report]
```

## How It Feels To Use

You can ask OpenClaw for an outcome instead of a single command:

~~~text
Use GoalFlow to update the onboarding docs, verify that the examples still work, and finish only when the evidence passes.
~~~

GoalFlow then helps OpenClaw keep the work honest:

1. It drafts the goal in plain language.
2. It explains what will count as completion.
3. It asks for confirmation when the goal is ambiguous or risky.
4. It tracks implementation, evidence, verifier results, and remaining gaps.
5. It produces a final report that says what was done and how it was checked.

## Install

~~~bash
curl -fsSL https://raw.githubusercontent.com/moonhwilee/openclaw-goalflow/main/install.sh | bash
launchctl kickstart -k gui/$UID/ai.openclaw.gateway
openclaw plugins inspect goalflow
~~~

The installer clones the public repository, installs the plugin through the OpenClaw CLI, and enables it. The Gateway restart is kept explicit so operators can choose the right moment.

## Command Shape

GoalFlow can be invoked naturally in conversation. A future slash-command UX can map to the same behavior:

~~~text
/goal implement this change and verify it before completion
~~~

The important part is the contract: GoalFlow should make the target, criteria, evidence, verifier result, and final completion judgment visible.

## Repository Layout

- index.js - OpenClaw plugin entrypoint.
- runtime/ - validator, schemas, templates, and default verifier profiles.
- examples/goalflow/ - minimal public examples.
- tests/ - harnesses, smoke tests, fixtures, and test-only verifier profiles.
- tests/live/ - optional Gateway smoke tests for operators.
- docs/ - current behavior and testing notes.

## Local Tests

~~~bash
export OPENCLAW_GOALFLOW_PROFILE_FILES=tests/verifier_profiles.test.json
python3 -m py_compile runtime/*.py tests/smoke/*.py tests/harness/*.py tests/verifiers/*.py
python3 tests/smoke/goalflow_user_ux_smoke.py
python3 tests/smoke/goalflow_orchestrator_start_smoke.py
node --check index.js
OPENCLAW_WORKSPACE="$PWD" node tests/harness/goalflow_host_runtime_harness.mjs
OPENCLAW_WORKSPACE="$PWD" node tests/harness/goalflow_run_loop_harness.mjs
OPENCLAW_WORKSPACE="$PWD" node tests/harness/goalflow_claims_harness.mjs
~~~

## Live Smokes

Live smokes require a running OpenClaw Gateway and local Gateway auth. They are operator checks, not default install checks.

~~~bash
python3 tests/live/goalflow_live_finish_smoke.py
~~~

## License

MIT