pi-loopflows 0.1.2 → 0.1.3

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.1.3 - 2026-06-22
+
+- Add clear semantic versioning policy and release checklist.
+- Include `VERSIONING.md` in the published package.
+- Add concise versioning guidance to README.
+
 ## 0.1.2 - 2026-06-22
 
 - Tighten README positioning around loopflows as LEGO-like subagent workflows.

package/README.md

@@ -278,6 +278,16 @@ worker → reviewer → worker → reviewer
 
 If you need a feedback loop, a quality gate, a max iteration limit, or saved evidence, use a loopflow.
 
+## Versioning
+
+`pi-loopflows` uses semantic versioning: `MAJOR.MINOR.PATCH`.
+
+- PATCH for docs, bug fixes, prompt polish, validation improvements, and internal refactors with no user-facing behavior change.
+- MINOR for new backward-compatible features, bundled loopflows, commands, options, fields, or adapter backends.
+- MAJOR for breaking changes to loopflow JSON shape, template variables, gate semantics, commands, artifact paths, or adapter behavior.
+
+See [`VERSIONING.md`](VERSIONING.md) for the release checklist.
+
 ## Status
 
 `pi-loopflows` is early, but designed as a real product surface rather than a one-off script. The core model is intentionally small:

package/VERSIONING.md

@@ -0,0 +1,70 @@
+# Versioning
+
+`pi-loopflows` uses semantic versioning: `MAJOR.MINOR.PATCH`.
+
+## PATCH: `0.1.x`
+
+Use a patch release for safe, backward-compatible changes:
+
+- README, docs, examples, wording, metadata;
+- bug fixes that do not change workflow file shape;
+- bundled loopflow prompt improvements that keep the same behavior contract;
+- validation/typecheck/test improvements;
+- internal refactors with no user-facing API changes.
+
+Example: `0.1.2 -> 0.1.3`.
+
+## MINOR: `0.x.0`
+
+Use a minor release for new backward-compatible capability:
+
+- new bundled loopflows;
+- new loopflow fields that old files do not need;
+- new commands/tools/options;
+- new adapter backend support;
+- expanded artifact output that does not break existing consumers;
+- new gate/status helpers that existing loopflows can ignore.
+
+Example: `0.1.3 -> 0.2.0`.
+
+## MAJOR: `x.0.0`
+
+Use a major release for breaking changes:
+
+- changing or removing existing loopflow JSON fields;
+- changing template variable semantics;
+- changing gate status behavior in a way existing loopflows may interpret differently;
+- removing commands, tools, bundled loopflows, or adapter behavior;
+- changing artifact paths or output shape in a way scripts may depend on.
+
+Example: `1.4.2 -> 2.0.0`.
+
+## Release checklist
+
+1. Update `package.json` with `npm version <patch|minor|major> --no-git-tag-version`.
+2. Update `CHANGELOG.md` under the new version.
+3. Run:
+
+   ```bash
+   npm run validate
+   npm run typecheck
+   npm run pack:check
+   ```
+
+4. Commit with a clear release-prep message.
+5. Tag the version: `git tag vX.Y.Z`.
+6. Push `main` and the tag.
+7. Publish to npm:
+
+   ```bash
+   npm publish --access public
+   ```
+
+8. Create a GitHub release for the tag.
+9. Install the published package and validate it:
+
+   ```bash
+   pi remove npm:pi-loopflows || true
+   pi install npm:pi-loopflows@X.Y.Z
+   node ~/.pi/agent/npm/node_modules/pi-loopflows/scripts/validate.mjs
+   ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-loopflows",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Deterministic loop workflows for Pi subagents: steps, gates, feedback loops, and artifacts.",
   "license": "MIT",
   "author": "Nikita Nosov <20nik.nosov21@gmail.com>",
@@ -28,6 +28,7 @@
     "skills",
     "scripts",
     "README.md",
+    "VERSIONING.md",
     "LICENSE",
     "CHANGELOG.md"
   ],