openlanes 3.0.0

data/schemas/plan-state.schema.json

@@ -0,0 +1,101 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/kigster/openlanes/blob/main/schemas/plan-state.schema.json",
+  "title": "OpenLanes plan state",
+  "description": "state.json in a .plans folder: the harness's stages, the agents' signatures, and the messages between agents. Written only through openlanes, never by hand.",
+  "type": "object",
+  "required": ["version", "plan", "stages", "signatures", "messages"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": { "type": "string" },
+    "version": { "type": "integer", "minimum": 1 },
+    "plan": {
+      "type": "object",
+      "required": ["ordinal", "slug"],
+      "additionalProperties": false,
+      "properties": {
+        "ordinal": { "type": ["string", "null"], "pattern": "^\\d{3}\\.\\d{2}$" },
+        "slug": { "type": "string" }
+      }
+    },
+    "state": {
+      "description": "The last state the harness moved the folder to. The folder name is authoritative.",
+      "type": ["string", "null"]
+    },
+    "updated_at": { "type": ["string", "null"], "format": "date-time" },
+    "stages": {
+      "description": "One record per agent per round, written by the harness.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["agent", "round", "status"],
+        "additionalProperties": false,
+        "properties": {
+          "agent": { "$ref": "#/$defs/agent" },
+          "round": { "type": "integer", "minimum": 1 },
+          "status": { "$ref": "#/$defs/status" },
+          "from": { "type": "string" },
+          "to": { "type": "string" },
+          "started_at": { "type": "string", "format": "date-time" },
+          "finished_at": { "type": "string", "format": "date-time" },
+          "adapter": { "enum": ["claude", "codex", "pi"] },
+          "model": { "type": ["string", "null"] },
+          "effort": { "$ref": "#/$defs/effort" },
+          "up": { "type": "integer", "minimum": 0 },
+          "down": { "type": "integer", "minimum": 0 },
+          "seconds": { "type": "number", "minimum": 0 },
+          "note": { "type": "string" },
+          "run": {
+            "description": "The harness process that dispatched it, so a restart can tell a crash from a live run.",
+            "type": "object",
+            "required": ["pid", "host"],
+            "additionalProperties": false,
+            "properties": {
+              "pid": { "type": "integer" },
+              "host": { "type": "string" }
+            }
+          }
+        }
+      }
+    },
+    "signatures": {
+      "description": "Ledger lines, written by agents through `openlanes state sign`.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["at", "agent", "status", "round"],
+        "additionalProperties": false,
+        "properties": {
+          "at": { "type": "string", "format": "date-time" },
+          "agent": { "$ref": "#/$defs/agent" },
+          "status": { "$ref": "#/$defs/status" },
+          "round": { "type": "integer", "minimum": 1 },
+          "note": { "type": "string" },
+          "next": { "$ref": "#/$defs/agent" }
+        }
+      }
+    },
+    "messages": {
+      "description": "What agents on this plan said to each other, through `openlanes mail send`.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["number", "at", "from", "to", "body"],
+        "additionalProperties": false,
+        "properties": {
+          "number": { "type": "integer", "minimum": 1 },
+          "at": { "type": "string", "format": "date-time" },
+          "from": { "$ref": "#/$defs/agent" },
+          "to": { "$ref": "#/$defs/agent" },
+          "body": { "type": "string", "minLength": 1 },
+          "command": { "type": "string", "minLength": 1, "description": "The id of the page's command that sent it (plan 004, W13), so a redelivered command appends nothing twice." }
+        }
+      }
+    }
+  },
+  "$defs": {
+    "agent": { "type": "string", "pattern": "^[\\w-]+$" },
+    "status": { "enum": ["Started", "Completed", "Almost completed", "Interrupted", "Blocked"] },
+    "effort": { "enum": ["low", "medium", "high", "xhigh", "max", null] }
+  }
+}

data/skills/openlanes/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: openlanes
+description: The openlanes software factory (`openlanes` CLI) that drives `.plans/` folders through spec → plan → build → review with specialist agents. Use when a project has `.plans/` or `.openlanes.yml`, when the user mentions openlanes, openlanes, plan folders or the factory, or asks how a plan moves between states, or wants to set up a project on openlanes or start the factory. Loads before openlanes-setup, openlanes-spec, openlanes-documents, openlanes-run, openlanes-status and openlanes-sync.
+---
+
+# openlanes: the software factory
+
+`openlanes` (aliases `depot` and `lanes`) turns a few words into a merged pull request. A human writes intent into `spec.md`; specialist agents research, plan, build and review it; `openlanes` moves the plan from state to state until nothing changes. Merge and deploy stay human.
+
+## Which skill does the job
+
+| The user wants to                                            | Load           |
+| ------------------------------------------------------------ | -------------- |
+| set a project up on openlanes, or fix a missing project root (exit 66) | `openlanes-setup` |
+| start a feature or task, pick its lane, add implementation detail | `openlanes-spec`   |
+| write or fix a file in a plan folder: `blocked.md`, `spec.md`, `pull-requests.md` | `openlanes-documents` |
+| start the factory (`openlanes start`) or run the agents until the plans are done; clear a blocked plan | `openlanes-run`    |
+| see where plans stand, a plan's history, an agent's mailbox, the control room | `openlanes-status` |
+| fix folder names, PR titles, or export to Linear             | `openlanes-sync`   |
+
+## Before any command
+
+1. `command -v openlanes` must answer. Otherwise tell the user to install the gem (`gem install openlanes`) and stop. These skills ship inside the gem; after a gem upgrade, `openlanes skills install --overwrite` refreshes them in `~/.agents/skills`.
+1. `openlanes` finds the project root by itself: the nearest ancestor holding `.openlanes.yml` or `.plans/`, else the nearest `.git`. With none of them, project commands exit 66; load `openlanes-setup`. `init`, `docs`, `states`, `agents`, `describe`, `skills`, `eval`, `completion` and `version` need no project and still work.
+1. Bundler errors inside a Ruby project (a Gemfile that is not openlanes's) come from the calling shell's Bundler variables. Re-run in a subshell: `(unset BUNDLE_GEMFILE BUNDLE_BIN_PATH BUNDLER_SETUP BUNDLER_VERSION RUBYOPT RUBYLIB; openlanes …)`.
+1. A flag these skills use being rejected (`-n`, or output saying `Re-run with --commit`) means the `openlanes` on PATH is older than the skills: an rbenv shim or a stale gem shadowing the one that installed them. `which -a openlanes` and `openlanes version` show which; call the right one by its full path and tell the user.
+1. `--help` on any command or subcommand is the source of truth for flags (`openlanes resync dirs --help`). Read it rather than guessing a flag.
+
+## The model in four facts
+
+- **The folder name is the state.** `.plans/003.00-⭐️ → tax-rule-dsl` is plan `003.00`, state Planned, slug `tax-rule-dsl`. There is no database. Folder names hold emoji and spaces, so quote every path. Refer to a plan by its ordinal (`003`, `003.01`) wherever a command accepts one.
+- **Numbers are identity.** `NNN.00` is a new feature; `NNN.MM` with `MM > 0` documents work that already shipped (Retroactive). An ordinal is never renumbered.
+- **Lanes route a plan.** `full`: research, spec, plan, build, review. `plan`: the author's spec stands; plan, build, review. `quick`: one agent (`r2d2-mechanic`) does a short mechanical change, then review. The lane lives in `spec.md` frontmatter.
+- **Blocked means a human decides.** ⭕️ is a technical block (engineer), 🅱️ a product block (product). The questions sit in the plan's `blocked.md`; agents step around the plan until they are answered.
+
+Live references, never copied here so they cannot go stale:
+
+- `openlanes states`: every state, its emoji, and the legal transitions.
+- `openlanes agents list`: which agent handles which state, its model, its lanes.
+- `openlanes docs`: the full conventions document, generated from the state machine.
+
+## Project config: `.openlanes.yml`
+
+At the root, written by `openlanes init`. Keys: `project` (name), `lane` (default lane for new specs), `frontend` (whether the project has a front end; a spec's own `frontend:` wins), `jobs` (plans worked at once), `redis_url` (the Redis behind the control room), and `commands:` (per-command option defaults, e.g. `run: { timeout: 1800 }`). Precedence: CLI flag, then the plan's `spec.md`, then `.openlanes.yml`, then built-in defaults.
+
+## Every write is real
+
+Commands do their work when run. `-n` / `--dry-run` previews and changes nothing. A run pushes branches and opens pull requests, so preview before a broad command whenever the user has not already said to go ahead.

data/skills/openlanes-documents/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: openlanes-documents
+description: "The files inside a openlanes plan folder: what spec.md, plan.md, blocked.md, pull-requests.md and the closing documents are for, the exact formats openlanes parses, and a template for each. Use when writing or fixing a file in a `.plans/NNN.MM-…` folder by hand: blocked.md questions and answers, spec.md frontmatter, a pull-requests.md table, a retroactive spec's provenance line, or a discarded, deferred, deployed or rollback note."
+---
+
+# openlanes-documents: the files in a plan folder
+
+Load the `openlanes` skill first if it is not in context.
+
+A folder's contents justify the state in its name. `openlanes resync dirs` renames a folder whose contents contradict its emoji, so a file written in the wrong shape is a file the tool cannot see, and the folder stays where it was.
+
+## Which state needs which file
+
+Ask the tool, never a copy of its table:
+
+- `openlanes docs` prints every state, the files it requires, and why. `openlanes states` draws the transitions.
+- `openlanes resync dirs -n` after an edit shows what your change now justifies; drop `-n` to rename.
+
+## The files
+
+| File | For | Written by |
+| --- | --- | --- |
+| `spec.md` | what and why; its frontmatter says how to route and judge the work | `openlanes create`, the human, `leah-researcher` (`## Research`), `yoda-writer` |
+| `plan.md` | units, order, the integration check; blank means "waiting for the planner" | `yoda-writer` creates it empty, `palpatine-planner` fills it |
+| `plan-backend.md`, `plan-frontend.md` | each builder's units; a front-end file with no unit heading starts nobody | `palpatine-planner` |
+| `blocked.md` | open questions a human must decide | any agent, or a human |
+| `pull-requests.md` | the pull request table the review states are judged by | `openlanes run` when it opens the PR, `openlanes create --prs`, `openlanes resync prs` |
+| `rewrite.md`, `delayed.md`, `discarded.md`, `deployed.md`, `rollback.md` | why the plan left the main path | the reviewer (`rewrite.md`), otherwise a human |
+| `state.json` | stages, signatures, mailbox | the harness only; read it with `openlanes state show --plan <NNN>` |
+
+Agents also sign a ledger inside the document they own: a `> [!NOTE]` block of `[ agent: … status: Started, round 1 ]` lines. Leave those blocks as they are; the harness reads them to decide who finished.
+
+## Formats openlanes parses
+
+**spec.md frontmatter.** Keys: `lane` (full, plan, quick), `depth` (fast, medium, deep), `frontend` (true or false), `phases` (`<phase>: { adapter, model, effort }`), and `implementation_suggestions`, `implementation_requirements`, `task-completed-when`, `how-to-verify` (each text or a list of text). An unrecognised value is ignored rather than fatal, so a typo silently costs the plan its lane. Choosing the values is `openlanes-spec`'s job. The body opens with the four headings `openlanes create` scaffolds: `## What we are trying to achieve`, `## Why it matters`, `## What already exists`, `## What research needs to settle`.
+
+**blocked.md questions and answers.** A question is a line that starts with `B<n>`, after at most four `#` and an optional `**`: `## B1 — Which rate feed?`. Its answer is a heading `## A1` with the same number. Any other numbering (`1.`, `Q1`, a bullet `- B1`) is invisible: the folder never blocks, and `openlanes unblock` finds nothing to drain. Start no other line with `B` and a digit. An answer counts only when it names who decided (a role will do), carries a date, and picks one option.
+
+Which human a block waits on lives only in the emoji. `resync dirs` files a new `blocked.md` as ⭕️ (engineering); rename the folder's emoji to 🅱️ by hand when product owns the decision, and `resync` keeps it there.
+
+**pull-requests.md.** openlanes reads the first markdown table whose header names a pull request (`Pull Request Number`, `PR`, `#`) and whose rows link to `/pull/<n>`. Columns are found by header words: number, name or title, status. Status words: `Open`, `Draft` or `WIP`, `Merged`, `Closed`. Escape `[`, `]` and `|` inside a title. Prose below the table is ignored.
+
+```markdown
+| Pull Request Number | Pull Request Name | Status |
+| ------------------: | :---------------- | -----: |
+| 41 | [\[018.01\] Verify against filed returns](https://github.com/acme/app/pull/41) | Merged 🟣 |
+```
+
+**Retroactive provenance line.** A plan `NNN.MM` with `MM > 0` documents work that already shipped. Its `spec.md` opens, right after the H1, with a dated note naming the pull requests it describes. `openlanes create --after <NNN> --prs <n,n>` records the PRs and has `yoda-writer` write the spec; the line and how to pick `--after` are in [`references/retroactive-spec.md`](references/retroactive-spec.md).
+
+## Templates
+
+Copy the shape; replace every placeholder:
+
+- [`references/spec-template.md`](references/spec-template.md): `spec.md`, frontmatter and the four headings.
+- [`references/plan-template.md`](references/plan-template.md): `plan.md` and its unit shape.
+- [`references/blocked-template.md`](references/blocked-template.md): `blocked.md` with `B<n>` and `A<n>`.
+- [`references/closing-templates.md`](references/closing-templates.md): `rewrite.md`, `delayed.md`, `discarded.md`, `deployed.md`, `rollback.md`.
+- [`references/retroactive-spec.md`](references/retroactive-spec.md): the provenance line and the anchor.
+
+Done when `openlanes resync dirs -n` names nothing to rename for the folder you edited, or names exactly the state you meant it to reach.

data/skills/openlanes-documents/references/blocked-template.md

@@ -0,0 +1,49 @@
+# blocked.md template
+
+A plan with `blocked.md` naming at least one open question is blocked: ⭕️ Technical Block (an engineer or the CTO decides) or 🅱️ Product Block (a product manager decides). Agents step around it until a human answers and runs `openlanes unblock <NNN>`, which hands the file to `lando-broker`. The broker folds each qualifying answer into `spec.md` (what and why) or `plan.md` (how and in what order), deletes the question with its answer, and deletes the file when nothing is left.
+
+Two heading kinds, and only these: `## B<n>` for a question, `## A<n>` for its answer. openlanes counts the `B` lines; a question numbered any other way blocks nothing.
+
+```markdown
+# Rate Feed Sync — Blocked
+
+**Blocked since:** 2026-10-12
+**Blocking:** U2 cannot start until the source of rates is chosen
+**Decision needed from:** the CTO
+
+## B1 — Do we read rates from the vendor feed or cache them per filing period?
+
+**What we need decided:** one sentence, phrased so that an answer is possible.
+
+**Why it blocks:** what gets built wrong if we guess.
+
+**Options:**
+
+| Option | What it means | Cost or risk |
+| :----- | :------------ | :----------- |
+| A      |               |              |
+| B      |               |              |
+
+**Recommendation:** one option, and why.
+
+**If unanswered by 2026-10-19:** the default we will take.
+
+## What is already decided
+
+Anything settled that the decider need not reopen.
+```
+
+An answer, added under its question when it arrives:
+
+```markdown
+## A1
+
+Decided 2026-10-13 by the CTO: rates are read from the vendor feed, never cached across a filing period.
+```
+
+Notes:
+
+- An answer counts only when it names who decided (a role is enough), carries a date, and picks one option. "Leaning towards B" stays, and so does its question.
+- Answer in pieces if that is how answers arrive; whatever is still open keeps the plan blocked.
+- A new `blocked.md` lands at ⭕️ on the next `openlanes resync dirs`. Rename the folder's emoji to 🅱️ when product owns the decision; nothing else records which human it waits on.
+- `openlanes unblock <NNN> -n` lists the questions openlanes can see. Run it after writing the file.

data/skills/openlanes-documents/references/closing-templates.md

@@ -0,0 +1,59 @@
+# Closing documents
+
+Each of these files is what one off-path state requires (`openlanes docs` lists which). Write the file, then `openlanes resync dirs` moves the folder; rename by hand only if resync names a different state than you meant.
+
+## discarded.md — ❌ Discarded
+
+Dropped for good; terminal. Say why, so nobody re-proposes it blind.
+
+```markdown
+# Rate Feed Sync — Discarded
+
+**Decided:** 2026-10-13 by the head of product
+**Why:** the vendor withdrew the feed; filed returns carry the rates we need.
+**What would change our minds:** a regulator requiring live rates.
+```
+
+## delayed.md — ☢️ Deferred
+
+The work could proceed and we chose not to yet. openlanes refuses the state unless the file names a **trigger** (it looks for the words trigger, revisit, when, until or once).
+
+```markdown
+# Rate Feed Sync — Deferred
+
+**Deferred:** 2026-10-13 by the CTO
+**Why now is wrong:** the ledger refactor in 021 rewrites the tables this touches.
+**Trigger:** revisit once plan 021 is merged.
+```
+
+## rewrite.md — 💩 Scrapped by Review
+
+Written by `hansolo-reviewer` when the work is missing, broken, untested, off-spec, or still failing after two rejections. The plan survives; the pull requests do not. No agent handles 💩: a human reads this and decides whether to re-plan, rewrite the spec, or discard.
+
+```markdown
+# Rate Feed Sync — Rewrite
+
+**Reviewed:** 2026-10-13, PR #41
+**Why it was scrapped:** the sync never writes to the rates table; the spec's verification command fails.
+**What the next attempt must do differently:** …
+```
+
+## deployed.md — 😎 Deployed
+
+```markdown
+# Rate Feed Sync — Deployed
+
+**Release:** v1.8.0
+**Date:** 2026-10-14
+**SHA:** 3f2c9ab
+```
+
+## rollback.md — 😱 Rolled Back
+
+```markdown
+# Rate Feed Sync — Rolled Back
+
+**Rolled back:** 2026-10-15, v1.8.0 → v1.7.3
+**What broke:** the nightly sync locked the rates table for 40 minutes.
+**What has to change before it ships again:** …
+```

data/skills/openlanes-documents/references/plan-template.md

@@ -0,0 +1,61 @@
+# plan.md template
+
+`palpatine-planner` writes `plan.md` from a finished `spec.md`, plus `plan-backend.md` and `plan-frontend.md` holding each builder's units. Write it by hand only when you are taking the planner's place (lane `plan` skips research, not planning).
+
+`plan.md` stays **blank** until it is a plan: any `#`, `##` or `###` heading outside a ledger block tells openlanes the plan is written, and moves the folder from 📋 Ready for Planning to ⭐️ Planned. The whole plan lands as one pull request; more than eight units means the spec is several plans.
+
+```markdown
+# Rate Feed Sync — Plan
+
+**Spec:** `spec.md` in this folder
+**Depends on:** plans that must land first, by number, or nothing
+
+## Units
+
+### U1 — Rates table and model
+
+- **Discipline:** back end
+- **Owns:** db/migrate/*_create_rates.rb, app/models/rate.rb
+- **Must not touch:** app/views/**
+- **Depends on:** nothing
+- **Done when:** spec/models/rate_spec.rb passes
+
+### U2 — Sync command
+
+- **Discipline:** back end
+- **Owns:** lib/acme/rates/sync.rb
+- **Must not touch:** app/models/rate.rb (U1)
+- **Depends on:** U1
+- **Done when:** spec/acme/rates/sync_spec.rb passes
+
+### U3 — Integration check
+
+- **Discipline:** back end
+- **Owns:** spec/integration/rates_sync_spec.rb
+- **Depends on:** U2
+- **Done when:** a real sync, nothing stubbed but the vendor's HTTP, stores rows the model reads back
+
+## Order
+
+U1 → U2 → U3. Units that write the same file are sequential; say which can run in parallel and why.
+
+## Risks
+
+| Risk | What we do about it |
+| :--- | :------------------ |
+|      |                     |
+
+## Task completed when
+
+- copied from spec.md's `task-completed-when`
+
+## How to verify
+
+- copied from spec.md's `how-to-verify`
+```
+
+Notes:
+
+- Every unit appears in exactly one of `plan-backend.md` and `plan-frontend.md`, under its own `##` or `###` heading. `rey-frontend` starts only when `plan-frontend.md` has a unit heading, so a plan with no front end writes one plain line there and no heading.
+- `## Task completed when` and `## How to verify` are appended by the harness when missing; a section you wrote is left alone.
+- A plan stays one level above the code: signatures, routes and response shapes, not method bodies.

data/skills/openlanes-documents/references/retroactive-spec.md

@@ -0,0 +1,43 @@
+# Retroactive specifications: the provenance line
+
+A plan numbered `NNN.MM` with `MM > 0` documents work that already shipped. Its `spec.md` must open by saying so.
+
+A specification's form claims that somebody thought this through before it was built. A `spec.md` dated today and filed as an ordinary plan makes that claim falsely. The number carries the fact (`MM > 0`), but a number is easy to miss and easy to misread as containment; the opening line is what survives being copied, quoted or exported.
+
+## The line
+
+Immediately after the H1, before anything else:
+
+```markdown
+# Verify Against Filed Returns
+
+> [!NOTE]
+> **Written retroactively on 2026-08-17.** This documents work that shipped in
+> #41 and #43, merged between plan 018 and plan 019. It describes what exists;
+> it does not record a decision taken in advance.
+```
+
+Three things, all load-bearing:
+
+1. **The date it was written**, not the date the work shipped.
+1. **The pull requests it describes**, by number: the evidence a reader checks the document against.
+1. **The disclaimer.** "Describes what exists" is the point.
+
+## Choosing the anchor
+
+`openlanes create --after <NNN> --prs <n,n> <words>` takes the next free slot in the gap after plan `NNN`. Choose `NNN` by **when the work merged**, not by what it is about:
+
+```bash
+git log --diff-filter=A --format='%ad %s' -- '.plans/018*' '.plans/019*'
+gh pr view 41 --json mergedAt
+```
+
+If the pull requests merged after 018's folder was created and before 019's, the anchor is 018. The decimal is a slot in time, not a claim about subject matter.
+
+## What happens next
+
+`create --prs` writes `pull-requests.md` (the folder is born 🕰️ Retroactive) and hands the folder to `yoda-writer`, which writes `spec.md` from the diff and an empty `plan.md`. `--no-spec` stops after recording the PRs. From there the plan moves like any other; `openlanes run -n --plan <NNN.MM>` shows who takes it next.
+
+## What does not deserve one
+
+Most unmatched pull requests. The test is whether somebody would need to read it: a capability with behaviour, an interface, or invariants not obvious from the code. "Fix a typo", "remove dead code" and "bump a dependency" belong to no plan; `openlanes docs` names the prefix their titles carry instead.

data/skills/openlanes-documents/references/spec-template.md

@@ -0,0 +1,45 @@
+# spec.md template
+
+`openlanes create <words> --lane <lane> --depth <depth>` writes the title, the frontmatter for the flags it was given, and the four headings; without `--no-draft` it also drafts them from the project's own docs. Fill what it left, keeping the headings in order. Frontmatter keys you do not need can be left out; `lane` defaults to `full`.
+
+```markdown
+---
+lane: full                      # full | plan | quick
+depth: medium                   # fast | medium | deep
+frontend: false                 # omit to inherit .openlanes.yml; true forces the front-end agent, false forbids it
+implementation_suggestions:     # offered to agents, who may take a better route and say why
+  - Reuse the HTTP client already in lib/acme/http.rb
+implementation_requirements:    # met exactly as written, or the agent blocks and asks
+  - Every money column is numeric(19,4)
+task-completed-when:            # copied into plan.md as "## Task completed when"
+  - "`acme rates sync` stores today's rates and prints how many changed"
+how-to-verify:                  # copied into plan.md as "## How to verify"
+  - "bundle exec rspec spec/acme/rates_spec.rb"
+phases:                         # optional, per phase: adapter, model, effort
+  build: { model: opus }
+---
+# Rate Feed Sync
+
+## What we are trying to achieve
+
+The outcome, in a few sentences: what a user or the system can do afterwards.
+
+## Why it matters
+
+Who needs it and what it unblocks. A line from the project's backlog counts.
+
+## What already exists
+
+Specific files, modules and prior plans this builds on, by path.
+
+## What research needs to settle
+
+The open questions. Where nothing is known, say so in one line; research reads the gaps as its assignment.
+```
+
+Notes:
+
+- Quote a list item that holds `: `, ` #`, a backtick, `{`, or starts with `?`; YAML otherwise reads it as something other than text.
+- Leave out "tests and linters pass": openlanes tells every builder and the reviewer that already.
+- `leah-researcher` appends `## Research` (that chapter is what makes the folder 🔎 Researched); `yoda-writer` then rewrites the body into the full specification. Neither needs a heading from you beyond these four.
+- A retroactive plan (`NNN.MM`, `MM > 0`) opens with the provenance line in `retroactive-spec.md` instead of the four headings.

data/skills/openlanes-run/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: openlanes-run
+description: Start the openlanes factory with `openlanes start` (engine plus control room, up until Stop All Local or Ctrl-C, questions answered and plans created on the page), or run openlanes's specialist agents to a fixed point with `openlanes run --until-settled` and clear blocked plans with `openlanes unblock`. Use when the user wants to start, run, resume or finish the agents, build or ship a plan, or unblock a ⭕️ / 🅱️ plan.
+---
+
+# openlanes-run: drive the plans
+
+Load the `openlanes` skill first if it is not in context.
+
+## `openlanes start`: the factory with its control room
+
+`openlanes start` is the way to run the factory for a person. It is `openlanes run` with the control room on, and it does not stop at a fixed point: when a plan blocks, palpatine-planner's questions included, it idles, shows the questions in **Needs You** on the page, takes the answer from there, drains it, and hands the plan back to its agent. It picks up plans created on the page, by `openlanes create` in another terminal, or edited by hand, rescanning `.plans/` every 5 s (`--rescan`).
+
+```bash
+openlanes start              # engine and control room on http://127.0.0.1:11000, browser opened
+openlanes start --no-open    # print the URL only
+```
+
+- It takes `run`'s flags except `-n` and `--no-web`. It needs Redis and refuses without it (exit 69).
+- Every human decision goes through the page: answers, hold, wrap up, stop, models, new plans. **Stop All Local** stops this machine's agents, then its engine and the page; nothing else on the page ends the run. The terminal is output only.
+- It never ends on its own, not even once every plan is finished: the page can create the next one. A project with no plans waits for the first. Stop All Local, Ctrl-C or `kill -TERM` end it, with exit 0; agents get the graceful stop and the page goes down with it.
+- Start it in the background, give the user the URL, and leave the answering to them on the page. Steps 1 to 5 below are the scripted, headless alternative.
+
+`openlanes run` loops in rounds. Each round hands every movable plan to the agent its state and lane call for and renames the folder when the agent finishes. When a builder lands a plan at 🟢 Ready for Review, `openlanes` pushes its branch and opens the pull request, titled `[NNN.MM]`; `hansolo-reviewer` then reviews that pull request. With `--until-settled` it stops at a **fixed point**: a round in which no plan changed state. Without it, a run whose control room came up stays up like `start` and never returns, so a scripted run always passes `--until-settled` (or `--no-web`). Your job is to start it, watch it, and turn what it stops on into questions for the human.
+
+## 1. Scope and preview
+
+Decide the scope from what the user asked: the whole tree, or `--plan 003,005.01`. Then preview, unless the user has already told you to run:
+
+```bash
+openlanes run -n --until-settled --plan <NNN,...>
+```
+
+Each line names a plan, the agent it would get, and the round. Show the user the lines that matter in a few bullets and ask once: "Run these?" One yes covers the whole loop below.
+
+Pick flags from the situation, and read `openlanes run --help` for the rest:
+
+| Situation                                        | Flag                                 |
+| ------------------------------------------------ | ------------------------------------ |
+| limit machine load or API spend                  | `-j <n>`, `--max-tokens <n>`         |
+| the repository has no git                        | `--isolation shared` (serial; see below) |
+| one agent is misbehaving                         | `--skip <agent>`                     |
+| re-drive one agent with extra guidance           | `--agent <name> --prompt "<text>"`   |
+| no browser (CI, a remote shell), or no page at all | `--no-open`; `--no-web` (`openlanes web` can serve it later) |
+| port 11000 taken, or Redis elsewhere              | `--port <n>`, `--redis-url <url>`    |
+
+Keep the defaults (`--isolation worktree`, pushing on) whenever the user wants plans reviewed. `--isolation shared` and `--no-git-push` open no pull request, so every plan stops at 🟢 and the reviewer never starts; `openlanes run` warns when that is the case. Use them only when the user asks to keep work local, and say that review waits for a PR they open (`openlanes resync prs` then records it).
+
+## 2. Run it
+
+```bash
+openlanes run --until-settled --plan <NNN,...>
+```
+
+A run takes minutes to hours: each agent may take up to 15 minutes per round, over several rounds. Start it in the background and wait for it to exit; it prints its progress log path at the start, which is what to read when the user asks how it is going. Avoid polling in a tight loop.
+
+When Redis answers, the run also serves the control room (it still ends at the fixed point, because of `--until-settled`) on `http://127.0.0.1:11000` and opens it in the browser: the user watches the board there and can message, interrupt or stop an agent. Without Redis the run warns once and goes on headless; that is not a failure. To get the page, start `redis-server` (or pass `--redis-url`) before the run; `openlanes-setup` has the details.
+
+A warning about `ANTHROPIC_API_KEY` (or a similar variable) at the start means every agent will authenticate with that key instead of the user's claude.ai login. Stop and ask before running with it; a stale key fails every agent with `401` after minutes each.
+
+## 3. Read where it stopped
+
+When it exits, `openlanes status` shows where each plan stands. Sort them into three groups:
+
+- **Advanced to a human gate**: at ✅ Approved & Merged the reviewer has approved, and merging and deploying are the human's. Report the PR links (`gh pr list`).
+- **Blocked** ⭕️ / 🅱️: go to step 4.
+- **Unmoved without a block**: an agent failed or ran out of rounds. Read the plan's history with `openlanes state show --plan <NNN>` and say which agent stopped and why. Re-run with a fix (`--agent`, `--prompt`, `--timeout`) only after telling the user what you will change.
+
+## 4. Unblock
+
+For each blocked plan:
+
+1. `openlanes unblock <NNN> -n` prints the open questions.
+1. Put them to the human **one at a time**. ⭕️ questions are for an engineer, 🅱️ for product; say which.
+1. Write each answer into the plan's `blocked.md` under `## A<n>`, matching its `## B<n>` (the format is in `openlanes-documents`). An answer counts only when it names who decided (a role is enough), carries today's date, and settles the question. "Leaning towards B" does not count, and the broker will leave it in place.
+
+   ```markdown
+   ## A2
+   Decided 2026-10-12 by the CTO: rates are read from the vendor feed, never cached.
+   ```
+
+1. `openlanes unblock <NNN>` folds the answers into `spec.md` / `plan.md` and renames the folder.
+
+## 5. Loop
+
+Go back to step 2 for the plans that moved. Done when a run ends at a fixed point with every remaining plan at a human gate or blocked on a question the human has chosen not to answer yet. Report:
+
+- [x] plans that reached review or merge, with PR links
+- [ ] plans still blocked, and whose decision each waits on
+- [ ] plans that failed, and the reason

data/skills/openlanes-setup/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: openlanes-setup
+description: "Set a project up on openlanes: check the prerequisites, run `openlanes init`, install the skills, and create the first plan. Use when the user wants to set up a new project on openlanes, bring an existing repository onto it, or when a openlanes command exits 66 with no project root."
+---
+
+# openlanes-setup: put a project on openlanes
+
+Load the `openlanes` skill first if it is not in context. Read `<command> --help` before using a flag here.
+
+## 1. Prerequisites
+
+Check each, then report every gap at once with its fix. Ask before installing anything system-wide.
+
+| Check | Fix when it fails |
+| --- | --- |
+| `command -v openlanes && openlanes version` | `gem install openlanes` |
+| `git rev-parse --show-toplevel` | offer `git init`; without git, `openlanes run` needs `--isolation shared` and opens no pull request |
+| `gh auth status` | `gh auth login`; a "token in GH_TOKEN is invalid" line means `unset GH_TOKEN` and retry |
+| the agents' CLI: `command -v claude`, the default adapter, or `codex` / `pi` when the plans' `spec.md` select them per phase | install the CLI the plans use; `openlanes agents list` shows each agent's adapter |
+| Redis answers at the URL openlanes will use (order below): `url=$(ruby -ryaml -e 'puts((YAML.safe_load_file(".openlanes.yml") rescue {}).to_h["redis_url"])' 2>/dev/null); redis-cli -u "${url:-${REDIS_URL:-redis://localhost:6379/0}}" ping` | start `redis-server`, or point openlanes at another Redis (below) |
+
+Redis carries the control room, its commands and plan claims. `openlanes start` refuses to run without it (exit 69); `openlanes run` still works, headless, and says so. openlanes looks for it in `--redis-url`, then `redis_url:` in `.openlanes.yml`, then `$REDIS_URL`, then `redis://localhost:6379/0`; `openlanes web` checks `$OPENLANES_REDIS_URL` before all of those but the flag.
+
+## 2. `openlanes init`
+
+Run it at the repository root. Infer values from the repository, say them in one line, and wait for a yes:
+
+- `--project`: the product's name, else the directory name.
+- `--lane`: `full` unless the user writes complete specs themselves (`plan`).
+- `--[no-]frontend`: `--frontend` when there is a `web/`, `app/javascript/`, `package.json` with a UI framework, or views; `--no-frontend` for a library or CLI; leave it out when plans differ.
+- `-j`: leave the default unless the user wants to limit load.
+
+> Project **Acme**, lane **full**, **front end** (a `web/` React app), default jobs. OK?
+
+Then `openlanes init -y <flags> -n` to show the file, and the same without `-n` to write `.openlanes.yml` and create `.plans/`. An existing `.openlanes.yml` is kept unless `--overwrite`.
+
+If the repository has a database and a `CLAUDE.md` or `AGENTS.md`, offer one line there naming its PostgreSQL class (`PG-lax`, `PG-strict` or `PG-analytics`), so every agent assumes the same rules.
+
+## 3. Skills
+
+```bash
+openlanes skills install -n                      # what would be installed, kept, replaced
+openlanes skills install                         # into ~/.agents/skills
+openlanes skills install --into ~/.claude/skills # when the user's agent reads another directory
+```
+
+After a gem upgrade, `--overwrite` replaces the copies already there.
+
+## 4. The first plan
+
+Hand off to `openlanes-spec` to create and write the first plan. A new project's first plan is `000.00`. Then:
+
+```bash
+openlanes run -n --plan 000
+```
+
+and offer `openlanes-run` to start the agents.
+
+## Done when
+
+- [ ] `openlanes status` lists the plan.
+- [ ] `openlanes run -n --plan 000` names its first agent.
+- [ ] With Redis up, `openlanes web --demo` opens the control room on a sample run (Ctrl-C to stop).
+- [ ] `openlanes start` is running: the factory and its control room, up until Stop All Local or Ctrl-C. From here the user works on the page (see `openlanes-run`).