Relaunch v0.2.0 as @surlymochan/openflow

CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+All notable changes to this project are documented here. Detailed notes live in
+[RELEASE_NOTES.md](RELEASE_NOTES.md).
+
+## [0.2.0] - unreleased (relaunch)
+
+### Added
+- Policy overlay execution mode: `xflow policy validate`, plus policy, notify, storage, plugin and
+  experience-digest atoms.
+- `xflow intake recommend` for adaptive yolo/corps track selection.
+- `xflow profile show|set` for execution profiles.
+- `xflow compare super-assistant`.
+- `docs/assets/demo.gif`, recorded from a real CLI run, and a README rewrite.
+- `CHANGELOG.md`.
+
+### Changed
+- The npm package is now named `@surlymochan/openflow`, because the unscoped `openflow` name is taken. The CLI is still `xflow`.
+- `package.json` adds repository/homepage/bugs/keywords/author, `engines.node >= 22.5` and public `publishConfig`.
+- The `xflow serve` fallback message no longer links to an unpublished repository.
+
+### Fixed
+- `agent_invoke` no longer crashes with an uncaught `EPIPE` when an agent CLI exits before reading its stdin prompt. This fixes an intermittent `heavy-atoms` test failure.
+
+## [0.1.0] - 2026-05-25
+
+### Added
+- First public extraction:
+  - YAML workflows (`yolo`, `corps`) validated against the atom registry.
+  - Red/green TDD proof gates and a test-quality review.
+  - Handoff and AHA state, archive ordering, and the `xflow` CLI.
+- Adapters: `xflow adapter import-file` and `xflow adapter github-issue`.

README.md

@@ -1,100 +1,152 @@
 # OpenFlow
 
 [![CI](https://github.com/surlymochan/openflow/actions/workflows/ci.yml/badge.svg)](https://github.com/surlymochan/openflow/actions/workflows/ci.yml)
-[![xflow score](https://img.shields.io/badge/xflow%20score-100%2F100-brightgreen)](docs/competitive-benchmark.md)
-[![publish check](https://img.shields.io/badge/publish--check-dry--run%20ready-blue)](docs/public-release.md)
-[![spec delta](https://img.shields.io/badge/spec%20delta-requirements--level-blueviolet)](docs/openspec-migration.md)
+[![npm](https://img.shields.io/npm/v/@surlymochan/openflow?label=npm)](https://www.npmjs.com/package/@surlymochan/openflow)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+![node >= 22.5](https://img.shields.io/badge/node-%E2%89%A522.5-informational)
+
+**Executable delivery workflow for AI coding agents.**
+
+Prompt-based workflows *ask* an agent to write the failing test first, run the suite and keep notes. OpenFlow
+*checks* that it did. Workflows are YAML phases made of small deterministic "atoms". Gates are code: a
+red/green TDD proof, a test-quality review, artifact checks, and archive ordering. The `xflow` CLI runs the
+same workflows from Codex, Claude Code, Cursor, OpenCode, Gemini or a plain terminal.
+
+![OpenFlow demo: a red proof must fail, a green proof must pass, and a faked red proof is rejected](docs/assets/demo.gif)
+
+<sub>Recorded from a real run of the CLI in an empty project. The last two commands show an agent "recording" a
+red proof after the fix, and the gate rejecting it.</sub>
+
+## Why
+
+Agent workflow kits are good at shaping behaviour, but the checks only live in prose. Agents skip the red
+step, write tests that assert nothing, lose context between sessions, and open PRs before verification has
+finished. OpenFlow adds a harder layer underneath:
+
+- **Workflow as data.** `workflows/yolo.yaml` and `workflows/corps.yaml` are validated against an atom registry before they run.
+- **TDD proof checked by code.**
+  - The red proof must fail before implementation and the green proof must pass after it.
+  - `I6c.tdd.quality_review` rejects code changes that have:
+    - no meaningful test changes,
+    - empty assertions,
+    - snapshot-only tests,
+    - mock-heavy tests without real assertions.
+- **Context that survives sessions.**
+  - The `.xflow/GOAL.md` project anchor.
+  - `HANDOFF.md` and `AHA.md`.
+  - Per-change `status.json` and proof files under `specs/changes/<id>/`.
+- **Executable finish.** Verify → archive → commit/push → PR ordering is a tested atom, not a checklist.
 
-Executable delivery workflow for AI coding agents.
-
-OpenFlow is the public extraction of the `openflow` workflow runtime. It turns
-agent work from "follow this prose process" into a local workflow runtime with
-YAML phases, deterministic atoms, TDD proof gates, handoff state, archive
-discipline, and packageable CLI commands.
-
-## Why It Exists
-
-Most agent workflow systems are strong at behavior shaping. OpenFlow adds a
-harder layer:
+## 3 Minute Start
 
-- workflow data that can be validated before it runs
-- red/green TDD proof that is checked by code, not only by prompt discipline
-- `quality-0.json` test-quality review for code/test pairing and common fake-test patterns
-- local handoff and AHA files so context survives across sessions
-- archive and PR ordering that is executable and test-covered
-- clean-project adoption proof in CI plus a reviewable maintainer adoption record
+Requires Node.js ≥ 22.5 (for `node:sqlite`) and Python 3 (atoms are small Python scripts).
 
-## 3 Minute Start
+```bash
+npm install -g @surlymochan/openflow     # installs the `xflow` CLI
+cd your-project
+xflow init --project-root .               # writes .as-xflow/config.json
+xflow goal set "Ship the next verified change" --project-root .
+xflow goal audit --project-root . --json
+xflow doctor --project-root .
+xflow workflow validate yolo --project-root .
+xflow guide                               # the delivery loop in one screen
+```
 
 For a source checkout:
 
 ```bash
 git clone https://github.com/surlymochan/openflow.git
 cd openflow
-npm install
-npm run release:pack
+npm ci && npm test
 node bin/xflow.js quickstart
-node bin/xflow.js guide
 node bin/xflow.js evaluate
-node bin/xflow.js assess
-node bin/xflow.js demo clean
 node bin/xflow.js compare codex-goal
-node bin/xflow.js launch dossier
 node bin/xflow.js launch copy
 ```
 
-To initialize OpenFlow inside a target project after the CLI is linked or
-installed:
+## Run a change
 
 ```bash
-xflow quickstart
-xflow guide
-xflow init --project-root .
-xflow goal set "Ship the next verified change" --project-root .
-xflow goal audit --project-root . --json
-xflow doctor --project-root .
-xflow workflow validate yolo --project-root .
+git checkout -b feat/example-change
+xflow workflow run yolo \
+  --title "Example change" --change-type backend \
+  --tdd-red-command  "npm test -- --grep new-behavior" \
+  --tdd-green-command "npm test"
 ```
 
-Release-owner gates such as `xflow adoption status --json`, `xflow adoption validate --json`,
-`xflow package status --json`, `xflow package preflight --check-registry --check-auth --json`, and
-`xflow package audit --check-registry --json` are intentionally separate from
-the first-run path because they fail until real adoption evidence, npm identity,
-or published registry evidence exists. Use `xflow adoption brief --name <team-or-project> --source <tracker-or-pr> --track yolo`
-to generate the outbound ask, `xflow adoption trial --name <team-or-project> --source <tracker-or-pr> --track yolo`
-to preview the copy-paste external trial, `xflow adoption kit --name <team-or-project> --source <tracker-or-pr> --track yolo`
-to create a shareable packet, then `xflow adoption init --name <team-or-project> --source <tracker-or-pr> --track yolo`
-to create the draft record after real trial evidence exists.
+The lite track runs `tdd-red -> execute -> tdd-green -> verify -> archive` and stops at human or LLM gates. Every
+phase leaves evidence in `specs/changes/<change-id>/`. Add `--dry-run` to print the phases, atoms and gates
+first.
 
-## Run A Change
+You can also run a single gate directly, as in the demo:
 
 ```bash
-git checkout -b codex/example-change
-xflow workflow run yolo --project-root . \
-  --title "Example change" \
-  --change-type backend \
-  --tdd-red-command "npm test -- --grep new-behavior" \
-  --tdd-green-command "npm test"
+xflow atom run I6a.tdd.run --change-id my-change --phase red   --test-command "npm test"
+xflow atom run I6a.tdd.run --change-id my-change --phase green --test-command "npm test"
+xflow atom run I6b.tdd.proof_validate --change-id my-change --phase red
+```
+
+## Evaluate it
+
+```bash
+xflow quickstart        # copy-paste-safe first-run commands
+xflow evaluate          # one-shot brief: quality score, comparisons, blockers, next actions
+xflow assess            # scorecard for goal, yolo, corps and the skill family
+xflow score             # competitive readiness score with evidence per dimension
+xflow demo launch       # goal -> yolo and goal -> corps proof paths
+xflow launch dossier    # one-page narrative backed by the same audit
+xflow launch copy       # claim-safe announcement copy plus forbidden phrases
+xflow release status    # the single next release blocker
 ```
 
-The lite workflow runs `tdd-red -> execute -> tdd-green -> verify -> archive`.
+<details>
+<summary>Release-owner gates (fail until real adoption / npm evidence exists)</summary>
 
-Red proof must fail before implementation. Green proof must pass after implementation. `I6c.tdd.quality_review` then rejects code changes without meaningful changed tests, empty assertions, snapshot-only tests, or mock-heavy tests without real assertions.
+```bash
+xflow adoption trial --name <team-or-project> --source <tracker-or-pr> --track yolo
+xflow adoption status --json
+xflow package preflight --check-registry --check-auth --json
+xflow package audit --check-registry --json
+xflow launch audit --pre-publish --strict --json
+```
 
-## Choose A Track
+</details>
 
-| Track | Use When | Entry |
+## Choose a track
+
+| Track | Use when | Entry |
 | --- | --- | --- |
-| `goal` | You want a simple project direction anchor that later xflow work can read and audit | `xflow:goal`, `xflow goal set`, or `xflow goal audit` |
-| `plan` | You only need a reusable implementation plan | `xflow:plan` |
-| `ralph` | You want Codex to keep implementing, verifying, and repairing until completion evidence is clean | `xflow:ralph` |
-| `yolo` | Backend, docs, infra, small UI, low ceremony | `xflow:yolo` or `xflow workflow run yolo` |
-| `corps` | Product/UI-heavy or multi-agent work | `xflow:corps`, `xflow corps --explain`, or `xflow corps` |
+| `goal` | You want a project-level direction anchor that later work reads and audits | `xflow goal set`, `xflow goal audit` |
+| `plan` | You only need a reusable implementation plan | `xflow:plan` skill |
+| `yolo` | Backend, docs, infra, small UI; low ceremony | `xflow workflow run yolo` |
+| `corps` | Product/UI-heavy or multi-agent work with governed proof | `xflow corps --explain`, then `xflow corps` and `xflow proof --track corps` |
+| `ralph` | Keep implementing, verifying and repairing until the completion evidence is clean | `xflow:ralph` skill |
+
+Not sure which one fits? Run `xflow intake recommend --change-id <id> --title "<title>" --description "<text>"`.
+
+## How it fits together
+
+```
+workflows/*.yaml ──validate──► atoms/registry.json ──► xflow/atoms/*.py   (deterministic steps)
+        │                                                    │
+        ▼                                                    ▼
+  xflow workflow run ──► gates: deterministic | artifact-verify | human | llm
+        │
+        ▼
+  specs/changes/<id>/   status.json · tdd/red-0.json · tdd/green-0.json · quality-0.json · logs/*.ndjson
+```
+
+- `bin/xflow.js`: the CLI. `src/`: workflow loader, runner, policy overlays, scoring.
+- `xflow/`: the portable skill family (`xflow:plan`, `xflow:yolo`, `xflow:corps`, `xflow:ralph`, …) for agent hosts.
+- `schemas/`: JSON schemas for workflows, proofs and policy overlays.
 
-`xflow:plan` is track-neutral. `yolo` and `corps` reuse an existing current plan instead of re-planning.
-`xflow workflow validate corps` is preflight only; heavy-track completion is only accepted after `xflow proof --track corps` writes `corps_proof.json` with `ok=true`. The corps proof now requires the built-in governed corps manifest, hash-linked execution-log witnesses for every phase/atom/gate, and no `stub`/`pencil_stubbed` runtime fallback.
+## Compared with other tools
 
-## What Makes It Different
+OpenFlow aims to complement prompt-level workflow kits and spec tools, not replace them. `xflow compare
+<superpowers|openspec|gstack|spec-kit|codex-goal>` prints a side-by-side with sources.
+
+<details>
+<summary>Full capability table</summary>
 
 | Surface | OpenFlow Position |
 | --- | --- |
@@ -122,8 +174,13 @@ Red proof must fail before implementation. Green proof must pass after implement
 | Competitive proof | `xflow compare codex-goal`, `xflow compare superpowers`, `xflow compare super-assistant`, `xflow compare openspec`, `xflow compare gstack`, `xflow compare spec-kit`, benchmark docs |
 | Adoption proof | Minimal clean project runs in CI, plus public adoption-record templates |
 
+</details>
+
 ## Docs
 
+<details>
+<summary>All guides</summary>
+
 - [Quickstart](docs/quickstart.md)
 - [Install and upgrade](docs/install-upgrade.md)
 - [Tooling matrix](docs/tooling-matrix.md)
@@ -154,16 +211,21 @@ Red proof must fail before implementation. Green proof must pass after implement
 - [Competitive benchmark](docs/competitive-benchmark.md)
 - [2026-05-25 benchmark report](docs/benchmark-openflow-vs-gstack-superpowers-openspec-2026-05-25.md)
 
-## Verify
+</details>
+
+## Development
 
 ```bash
-npm run drift:scan
-npm run verify
-npm run skill:diff
-npm run release:pack
-xflow assess
-xflow launch audit
-xflow score
+npm ci
+npx playwright install chromium   # browser-evidence tests
+npm test                          # 270+ tests
+npm run drift:scan                # docs/skill/workflow drift checks
+npm run pack:check                # what would be published
 ```
 
-Current release gate expectation: all active score dimensions are `strong`, and `xflow score` reports `100/100`.
+Contributions are welcome: open an issue describing the workflow problem first, then a PR with tests. Keep
+claims in docs tied to a command that reproduces them.
+
+## License
+
+[MIT](LICENSE)

RELEASE_NOTES.md

@@ -1,5 +1,39 @@
 # Release Notes
 
+## 0.2.0 - Relaunch (first npm release)
+
+OpenFlow is published to npm as **`@surlymochan/openflow`**. The CLI is still `xflow`. The unscoped
+`openflow` name on npm belongs to an unrelated project.
+
+### Highlights
+
+- **Policy overlays.** `xflow policy validate` checks personal and team policy layered over the built-in
+  workflows. Policy, notify, storage, plugin and experience-digest atoms ship with it.
+- **Adaptive intake.** `xflow intake recommend` reads a demand profile (title, description, repo count) and
+  recommends `yolo` or `corps` plus gate overlays. It writes `workflow_recommendation.json`.
+- **Execution profiles.** `xflow profile show|set` handles personal and team execution modes and provider
+  preferences.
+- **Comparisons.** `xflow compare super-assistant` is new, next to the Superpowers, OpenSpec, gstack,
+  spec-kit and Codex goal comparisons.
+- **New README.** It covers the problem, a demo GIF recorded from a real run, a 3-minute start and
+  single-gate usage (`xflow atom run I6a.tdd.run ...`).
+
+### Packaging
+
+- `package.json` now has `repository`, `homepage`, `bugs`, `keywords`, `author`,
+  `engines.node >= 22.5` (`node:sqlite`) and `publishConfig.access = public`.
+- Install docs and the CLI's copy-paste commands now use `npm install -g @surlymochan/openflow`.
+- `xflow serve` no longer points to an unpublished server repository.
+- Fixed an uncaught `EPIPE` in `agent_invoke` when an agent CLI exits without reading stdin.
+
+### Verified for this release
+
+- `npm test`: 275 passed, 1 skipped, 0 failed (Node 22, Playwright Chromium installed).
+- `npm run drift:scan`: 9/9.
+- `npm publish --dry-run`: `@surlymochan/openflow@0.2.0`, 187 files, about 321 kB.
+- Clean install from the packed tarball into an empty project: `xflow init`, `goal set`, `doctor` and
+  `workflow validate yolo` all pass.
+
 ## 0.1.0 - Public Readiness Candidate
 
 This release turns `openflow` from a local skill/workflow repo into a package-ready workflow runtime for AI coding agents.

bin/xflow.js

@@ -1727,7 +1727,7 @@ const LAUNCH_MISSING_SURFACES = {
     requirement: 'Public npm package ownership confirmed and package published from a green dry run.',
     why_it_matters: 'A launch story is incomplete while users cannot install the advertised package name.',
     acceptable_evidence: [
-      'npm view openflow name version --json returns this package',
+      'npm view @surlymochan/openflow name version --json returns this package',
       'npm publish --access public completed for the intended version',
     ],
   },
@@ -1993,10 +1993,10 @@ function buildLaunchCopyPayload(payload) {
   const packageBlocked = claims.blocked_claims.some((item) => item.id === 'published_package');
   const installCommand = packageBlocked
     ? 'git clone <repo-url> openflow && cd openflow && npm install && node bin/xflow.js quickstart'
-    : 'npm install -g openflow && xflow quickstart';
+    : 'npm install -g @surlymochan/openflow && xflow quickstart';
   const forbiddenPhrases = [];
   if (packageBlocked) {
-    forbiddenPhrases.push('npm install -g openflow works now');
+    forbiddenPhrases.push('npm install -g @surlymochan/openflow works now');
     forbiddenPhrases.push('openflow is publicly installable from npm');
     forbiddenPhrases.push('splash launch complete');
   }
@@ -4798,7 +4798,7 @@ const QUICKSTART = {
     label: 'Published package first run',
     intent: 'Copy-paste-safe commands for an evaluator after openflow is available from npm.',
     commands: [
-      'npm install -g openflow',
+      'npm install -g @surlymochan/openflow',
       'xflow guide',
       'xflow evaluate',
       'xflow assess',
@@ -6532,8 +6532,8 @@ async function handleServe(args) {
     const { default: startServer } = await import('../src/server.js');
     await startServer();
   } else {
-    console.error('HTTP server not yet available. Heavy track requires as-agentos server.');
-    console.error('See: https://github.com/surlymochan/as-agentos');
+    console.error('HTTP control plane is not included in this package yet.');
+    console.error('Use the CLI tracks instead: xflow workflow run yolo, or xflow corps --explain.');
     process.exit(1);
   }
 }

docs/demo-proof.md

@@ -7,7 +7,7 @@ This page defines what an external evaluator should run before trusting xflow cl
 From an empty temporary project:
 
 ```bash
-npm install -g openflow
+npm install -g @surlymochan/openflow
 xflow demo clean
 xflow guide
 xflow assess

docs/install-upgrade.md

@@ -16,7 +16,7 @@ Use source checkout mode when developing xflow itself or when testing workflow c
 ## Global CLI
 
 ```bash
-npm install -g openflow
+npm install -g @surlymochan/openflow
 xflow doctor
 ```