vinta-ai-workflows 0.7.0-alpha11 → 0.7.0-alpha12

package/CHANGELOG.md

@@ -7,6 +7,7 @@ the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [0.7.0] — YYYY-MM-DD
 
+<!-- pre-release: 0.7.0-alpha12 on 2026-09-15 -->
 <!-- pre-release: 0.7.0-alpha11 on 2026-09-15 -->
 <!-- pre-release: 0.7.0-alpha10 on 2026-09-15 -->
 <!-- pre-release: 0.7.0-alpha9 on 2026-09-14 -->
@@ -319,8 +320,44 @@ the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   `plan/{plan-id}/lane-{phase-id}` branches, merged `--no-ff` into the single plan
   branch at each wave boundary, so the unit commits survive.
 
+- **`project.prepare_cmd`, for the shared servers a run depends on.** A project
+  whose databases are `delivery: external` and whose services point at one Redis
+  has no long-lived containers of its own — the shape these fields recommend —
+  and that makes some *other* stack a hard dependency of every run. Nothing in
+  the package could bring it up. `setup_cmd` looks like the place and is not: it
+  runs per lane, long after the template database was created on a server that
+  had to be up for `createdb` to work at all.
+
+  It runs in the repository root **before anything else a run does** — before
+  the preflight, before the templates, before the first worktree — and again
+  before every lane recycle, so a server that dies mid-run is restored at the
+  next hand-off rather than failing every phase after it. Failure aborts with
+  the exit code and a bounded stderr tail, and says what the failure means
+  rather than only that a command exited. It must be idempotent, and `--wait`
+  is only as good as the `healthcheck` a service declares: without one, compose
+  returns as soon as the container starts and `createdb` races the server.
+
 ### Fixed
 
+- **`doctor` checks that the shared servers answer.** It verified that binaries
+  existed and disk fitted, and never looked at a `server_url` — so a project
+  whose Postgres lives in another checkout's compose stack passed the preflight
+  with that stack down and died on the first `createdb`, before a worktree
+  existed. Each external database's server and each service URL is now probed
+  with a TCP connect, and a failure names the address that did not answer. A
+  compose-delivered database is deliberately not probed: the lane starts it.
+
+  The order matters as much as the check. `prepare_cmd` runs *before* the
+  preflight, so the check reports the world that hook just made rather than the
+  one in front of it.
+
+- **A service's `create_cmd` runs with the lane's environment.** `reset_cmd`
+  always had it and `create_cmd` did not, so a `create_cmd` that reached for
+  `docker compose` ran against the lane's own compose file with no project name
+  and no override — booting a stack on the project's fixed host ports, which is
+  the collision the override exists to prevent, caused by the step that sets a
+  lane up.
+
 - **`vinta-ai-maestro with` waits for the lock instead of giving up on it.** Its
   usage said it blocked until the resource was granted, and it did — for about
   five minutes, which is where Node's own `fetch` stops waiting for a response.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vinta-ai-workflows",
-  "version": "0.7.0-alpha11",
+  "version": "0.7.0-alpha12",
   "description": "Bootstrap AI tooling (AGENTS.md, skills, sub-agents) across Claude Code, Codex, Cursor, and VS Code + GitHub Copilot.",
   "type": "module",
   "bin": {

package/schemas/workflow.v1.schema.json

@@ -331,6 +331,11 @@
           "additionalProperties": false,
           "description": "How a lane’s compose stack is isolated past `COMPOSE_PROJECT_NAME`."
         },
+        "prepare_cmd": {
+          "description": "Run in the repository root **before anything else a run does** — before the preflight, before the template databases, before the first worktree. Its job is to make the shared servers this project’s lanes connect to reachable: `docker compose up -d --wait db redis` for a stack in the root checkout, `brew services start postgresql` for a host install, nothing at all for a project whose lanes boot their own. `setup_cmd` cannot do this — it runs per lane, long after the template database has been created on a server that had to be up already. MUST be idempotent: it runs again before every lane recycle, which is what restores a server that died mid-run. Note that `--wait` only waits for services that declare a `healthcheck`; without one it returns as soon as the container is started, and `createdb` races the server.",
+          "type": "string",
+          "minLength": 1
+        },
         "setup_cmd": {
           "description": "The project’s own lane-setup command, run inside each freshly provisioned lane with that lane’s environment applied. The escape hatch for whatever a project needs that no field here describes. It MUST be idempotent: it runs again every time the lane is recycled for another phase.",
           "type": "string",