@flumecode/runner 0.23.1 → 0.25.0-preview.39

package/dist/mcp-stdio.js

@@ -66,6 +66,9 @@ var requirementSchema = z.object({
   )
 });
 var planInputSchema = {
+  dependsOn: z.array(z.number().int().positive()).optional().describe(
+    "1-based positions of EARLIER plans in this same submission that must be merged or closed before this one. Use ONLY when the work must be strictly serial; omit for independent plans."
+  ),
   title: z.string().min(1).max(120).describe(
     "A concise, descriptive name for THIS plan. Must be distinct from the request title and from any sibling plans on the same request. Keep it under 120 characters."
   ),
@@ -187,6 +190,20 @@ function renderPlan(plan) {
   lines.push(PLAN_MARKER);
   return lines.join("\n");
 }
+function validateDependsOnReferences(arr, ctx) {
+  for (let i = 0; i < arr.length; i++) {
+    const deps = arr[i]?.dependsOn ?? [];
+    for (const dep of deps) {
+      if (dep > i || dep < 1) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: [i, "dependsOn"],
+          message: "dependsOn must reference an earlier plan (1-based) in this submission."
+        });
+      }
+    }
+  }
+}
 var submitPlanInputSchema = {
   plans: z.array(requireAtLeastTwoCriteria(requireRootCauseForFix(z.object(planInputSchema)))).min(1).refine(
     (arr) => {
@@ -194,7 +211,7 @@ var submitPlanInputSchema = {
       return new Set(titles).size === titles.length;
     },
     { message: "Each plan must have a distinct non-empty title" }
-  )
+  ).superRefine(validateDependsOnReferences)
 };
 var submitPlanSchema = z.object(submitPlanInputSchema);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flumecode/runner",
-  "version": "0.23.1",
+  "version": "0.25.0-preview.39",
   "type": "module",
   "description": "FlumeCode local runner — claims jobs and drives your local Claude Code against a real checkout.",
   "bin": {

package/skills-plugin/rules/coding-guideline.md

@@ -47,3 +47,4 @@ description: >-
 ## Documentation
 
 - When behavior or conventions change, update the matching project docs (`CLAUDE.md` or rule files) in the same PR.
+- FlumeCode plugin recipes (`.flumecode/plugins/*.json`) record how to install, build, run, or preview the app. If your change invalidates one — you altered the install/build/run/dev-server command, how the port or env is supplied, where the app lives (`appDir`), or which files count as the relevant change — update the matching recipe in the same PR so it doesn't go stale. They are not regenerated automatically; a stale recipe silently breaks the capability (e.g. the UI Preview pass) until someone re-installs.

package/skills-plugin/skills/preview-ui/SKILL.md

@@ -1,127 +1,86 @@
 ---
 name: preview-ui
 description: >-
-  Author an ephemeral fake-data showcase page for changed UI components so the
-  runner can screenshot them in a headless browser. Use after a UI-touching
-  implementation, when the runner provides a tmpRoute directory. Writes the
-  showcase files there and records the URL path in a sentinel file. Never
-  commits, pushes, or modifies application code outside the tmpRoute directory.
+  Author an ephemeral showcase that renders the recently-changed UI with realistic
+  fake data, so the runner can screenshot it in a headless browser. Use after a
+  UI-touching implementation, when the runner provides a preview recipe (from the
+  repo's ui-preview plugin manifest) and a sentinel-file path. Follows the recipe to
+  mount a temporary showcase — including registering a temporary route for
+  server-rendered stacks — and records the showcase URL in the sentinel file. The
+  showcase is ephemeral: the runner reverts the working tree afterward, so it never
+  reaches the pull request.
 ---
 
 # preview-ui
 
-You author a **temporary showcase page** that imports the recently-changed UI
-components and fills them with realistic fake data, so the runner can start the
-repo's dev server and take headless screenshots.
+You author a **temporary showcase** that renders the recently-changed UI filled with
+realistic fake data, so the runner can start the app and take headless screenshots.
 
-You write only inside the `<tmpRoute>` directory the runner hands you. You never
-modify production code, commit, or push.
+The showcase is **ephemeral**. The runner runs this pass _after_ the implementation is
+already committed, and **reverts the working tree** (tracked and untracked changes) once
+it has captured the screenshots. So you may edit whatever the recipe requires — including
+registering a temporary route in tracked files — and **nothing you write reaches the pull
+request**. Never commit or push.
 
 ## What you receive
 
 The runner injects these into your prompt:
 
-- **`<tmpRoute>`** — an absolute path to an empty temp directory inside the repo
-  (already git-excluded). Write your showcase files here.
-- **Committed UI files** — the list of files changed by the implementation, so
-  you know which components to showcase.
-
-## Step 1 — Detect the framework
-
-Read the repo's `package.json` (and `package.json` files in workspaces, if any)
-to determine the framework:
-
-| Framework     | Key `dependencies` / `devDependencies`  |
-| ------------- | --------------------------------------- |
-| Next.js       | `next`                                  |
-| Vite + React  | `vite` + `react`                        |
-| Vite + Vue    | `vite` + `vue`                          |
-| Vite + Svelte | `vite` + `svelte` (no SvelteKit)        |
-| SvelteKit     | `@sveltejs/kit`                         |
-| Nuxt          | `nuxt`                                  |
-| Astro         | `astro`                                 |
-| CRA           | `react-scripts`                         |
-| Remix         | `@remix-run/react` or `@remix-run/node` |
-
-If the framework is not recognisable or the file list contains no importable
-components, write a single plain `<tmpRoute>/index.html` file with a message
-like "No supported framework detected" and write `/__flumecode_preview` to
-`<tmpRoute>/.showcase-path`. Then stop — do not create a route file.
-
-## Step 2 — Determine the entry path
-
-Choose a URL path unlikely to collide with real routes: `/__flumecode_preview`.
-Write that string (exactly, no trailing newline) to `<tmpRoute>/.showcase-path`.
-
-## Step 3 — Author the showcase entry file
-
-Create a single route/page file at the correct location under `<tmpRoute>` for
-the detected framework:
-
-| Framework              | File to create                                        |
-| ---------------------- | ----------------------------------------------------- |
-| Next.js (App Router)   | `<tmpRoute>/page.tsx` (if the project uses `app/`)    |
-| Next.js (Pages Router) | `<tmpRoute>/index.tsx` (if the project uses `pages/`) |
-| Vite + React           | `<tmpRoute>/App.tsx` (or `.jsx`)                      |
-| Vite + Vue             | `<tmpRoute>/App.vue`                                  |
-| Vite + Svelte          | `<tmpRoute>/App.svelte`                               |
-| SvelteKit              | `<tmpRoute>/+page.svelte`                             |
-| Nuxt                   | `<tmpRoute>/index.vue`                                |
-| Astro                  | `<tmpRoute>/index.astro`                              |
-| CRA                    | `<tmpRoute>/index.tsx`                                |
-| Remix                  | `<tmpRoute>/route.tsx`                                |
-
-**Next.js App Router note:** The runner mounts the showcase at
-`app/__flumecode_preview/page.tsx` by symlinking or copying `<tmpRoute>` to
-`app/__flumecode_preview/`. You only need to produce `<tmpRoute>/page.tsx` — the
-runner handles the mount.
+- **The preview recipe** — from the repo's `.flumecode/plugins/ui-preview.json` manifest
+  (written when a repo member initialized the UI Preview plugin). It tells you the app
+  directory, the showcase strategy for this stack, and step-by-step instructions for
+  where to put the showcase and which URL path it serves at. **Follow it** — it is the
+  source of truth for how previews work in this repo. Do not re-detect the framework.
+- **A sentinel file path** — an absolute path. Write the showcase's URL path there.
+- **Changed UI files** — the list of files the implementation changed, so you know what
+  to showcase.
+
+## Step 1 — Record the URL path first
+
+Decide the showcase URL path the recipe specifies (e.g. `/__flumecode_preview`). Write
+that string **exactly** (no trailing newline) to the sentinel file the runner gave you,
+**before** authoring anything else — the runner reads it even if a later step fails.
+
+## Step 2 — Author the showcase by following the recipe
+
+Do exactly what the recipe's instructions say for this repo's stack. The shape differs by
+stack, but the intent is always the same: a single page/route that renders the changed UI
+with hard-coded fake data, reachable at the URL path from Step 1.
+
+- **Drop-in file stacks** (e.g. a Next.js/Vite/Svelte route file): create the showcase
+  entry file at the location the recipe names, importing the changed components by their
+  real relative paths and filling every prop with realistic fake data.
+- **Server-rendered stacks** (e.g. Django, Rails): also register a **temporary route** so
+  the page is reachable — add the URL/route mapping the recipe describes (e.g. a Django
+  `urls.py` entry pointing at a throwaway view + template, a Rails route + controller
+  action + view). Editing these tracked files is expected and safe; the runner reverts
+  them after capture.
 
 ### Content rules
 
-- Import the changed components using their real relative paths (calculate the
-  path from `<tmpRoute>` to the component's source location).
-- Fill every prop with **realistic fake data** — use hardcoded literals, not
-  calls to external APIs or databases.
-- If a component requires a provider (React context, Vuex store, Pinia, etc.),
-  wrap it with a minimal in-file stub provider — do not import the real app
-  store or data layer.
-- If a component calls a route handler or fetch endpoint, stub the relevant
-  function or hook at the top of the file with a mock that returns realistic
-  hard-coded data. Do NOT import MSW or any test library; keep stubs as plain
-  module-level overrides.
-- Export the showcase page as the default export (except Astro/SvelteKit, which
-  don't require a default export).
-- Keep the file short: one `export default` function that renders all changed
-  components in a flex column, with a small amount of padding.
-
-### What NOT to do
-
-- Do not call `fetch`, `axios`, `prisma`, `supabase`, or any I/O in the
-  showcase.
-- Do not import from test utilities, MSW, Storybook, or Cypress.
-- Do not add new npm dependencies.
-- Do not edit any file outside `<tmpRoute>`.
-- Do not commit or push.
-
-## Step 4 — Verify your output
-
-Before finishing, confirm:
-
-1. `<tmpRoute>/.showcase-path` exists and contains the URL path string.
-2. The showcase entry file exists at the expected path under `<tmpRoute>`.
-3. The file imports only modules that already exist in the repo (no invented
-   paths).
-
-If you cannot produce a valid showcase (e.g. the components have complex
-dependencies you cannot stub), write only `<tmpRoute>/.showcase-path` with the
-URL string and leave the entry file absent — the runner will detect the missing
-file and skip the screenshot step gracefully.
+- Fill every prop / template variable with **realistic fake data** — hard-coded literals,
+  never live calls to a database, API, or external service.
+- If a component needs a provider/context/store, wrap it with a minimal in-file stub — do
+  not import the real app store or data layer.
+- If a component or view calls a fetch/route/query, stub it locally with a mock returning
+  realistic hard-coded data. Do NOT pull in MSW, Storybook, Cypress, or any test library.
+- Do not add new dependencies — the manifest already declares everything previews need.
+- Keep it short: render all the changed UI in one simple page with a little padding.
+
+## Step 3 — Verify before finishing
+
+1. The sentinel file contains the showcase URL path.
+2. The showcase entry (and any temporary route registration the stack needs) exists and
+   references only modules/paths that already exist in the repo — no invented imports.
+
+If you cannot produce a valid showcase (e.g. the changed UI has dependencies you cannot
+reasonably stub), leave only the sentinel file with the URL path and stop — the runner
+detects the missing showcase and reports the preview as needing manual setup rather than
+crashing.
 
 ## Always
 
-- Write the URL path to `<tmpRoute>/.showcase-path` first, before any other
-  file — the runner reads it even if something else fails.
-- These files are ephemeral and git-excluded. They will be deleted by the runner
-  after screenshots are taken. Never commit or push them.
-- Your final reply should be one short sentence confirming what you created (e.g.
-  "Wrote `<tmpRoute>/page.tsx` showcasing `Button` and `Card` with fake data.").
+- Write the URL path to the sentinel file **first**, before anything else.
+- The showcase is ephemeral and reverted by the runner. **Never commit or push.**
+- Final reply: one short sentence naming what you created and its URL path (e.g.
+  "Showcased `Button` and `Card` at `/__flumecode_preview` via a temporary route.").

package/skills-plugin/skills/request-to-plan/SKILL.md

@@ -89,6 +89,7 @@ Field-by-field guidance:
   - **`description`** — an array of bullet points that help the reviewer understand the upcoming `pseudoCode` and decide whether the plan and design are correct. Each item is a distinct, self-contained point about what is changing and why — not a single paragraph, and not a line-by-line restatement of the pseudo code. Use concrete file references (`path/to/file.ts`) and name the functions/symbols involved. Apply inline-code formatting to all identifiers.
   - **`pseudoCode`** — an array of `{ file, pseudoCode }` entries. Provide an entry for every file the step touches **except** documentation files (SKILL.md, README.md, wiki pages, etc.). `pseudoCode` is optional in the schema but expected for all non-documentation files. Each entry names the file path and contains pseudo code that precisely describes the changes to make in that file.
 
+- **`dependsOn`** — optional. A list of 1-based positions of EARLIER plans in the same `plans[]` call that must be merged or closed before this one can start. Use ONLY when the plans must be worked strictly serially (e.g. a shared refactor that must merge before dependent features can be built on top of it). Omit for independent plans — most plans are independent.
 - **`risks`** — anything that could change the approach or surface a problem.
 - **`outOfScope`** — what you are deliberately not doing.
 
@@ -110,6 +111,12 @@ own independently-acceptable "Accept as plan" draft. After a plan is accepted th
 keep commenting to refine it; treat a later turn as a fresh **Plan** phase and call
 `submit_plan` again with a `plans[]` array containing the revised fields.
 
+When plans must be worked in a strict order (e.g. plan 1 is a shared refactor that plan 2
+builds on), express this with `dependsOn`: plan 2 sets `dependsOn: [1]`. Accepting the plans
+auto-creates the blocking links between their coding sessions — the order of acceptance does
+not matter. Do **not** use `dependsOn` for plans that can safely run in parallel; rely on
+array order only for documentation, not for enforcement.
+
 Before adding an entry to `plans[]`, apply this right-sizing checklist — if a plan fails any criterion, split it into separate entries:
 
 - **Single, clear outcome** — one bug fixed, one feature increment, one refactor. If the `title` needs "and", consider splitting.

package/skills-plugin/skills/setup-preview/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: setup-preview
+description: >-
+  Set up the FlumeCode UI Preview plugin for a repository. Analyse the app, then
+  record how to install it, run its dev server, and mount a temporary showcase page
+  into a machine-readable manifest at .flumecode/plugins/ui-preview.json plus a
+  human-readable wiki page — and install any packages future previews need. Use when a
+  request asks to install/re-initialize the UI Preview plugin. Works for any stack
+  (Node, Django, Rails, …): everything
+  stack-specific is captured as data in the manifest, so later previews need no
+  per-stack code. If previews can't be fully automated, record the manual steps.
+---
+
+# setup-preview
+
+You set up the **UI Preview plugin** for this repository: a one-time (re-runnable)
+analysis that records _how to run and preview this app_ so that every later coding
+session can screenshot its UI automatically — for **any** stack, with no per-stack code.
+
+You produce two artifacts and commit them (the runner opens the PR):
+
+1. **`.flumecode/plugins/ui-preview.json`** — the machine-readable recipe the per-session
+   preview pass executes. Its existence is what marks the plugin "initialized".
+2. **A wiki record** — a human-readable `.flumecode/wiki/components/ui-preview.md` page,
+   linked from the wiki nav map, documenting the detected stack and how previews work,
+   with a sync marker.
+
+You may also install/scaffold packages the previews genuinely need (these persist in the
+PR). Do **not** otherwise modify application code.
+
+## Step 1 — Understand the app
+
+Read the FlumeCode wiki first if it exists (`.flumecode/wiki/README.md`), then confirm
+against the code. Determine:
+
+- **The app directory** — the repo root, or a subdirectory / workspace member that holds
+  the previewable front-end (e.g. `apps/web`).
+- **The stack** — framework + language (Next.js, Vite, SvelteKit, Django, Rails, …).
+- **Install** — the command(s) that make the app runnable (`pnpm install`,
+  `pip install -r requirements.txt`, `bundle install`, …).
+- **Dev server** — the command that serves the app on a port, and how the port is passed.
+- **Hermetic boot** — any env vars needed so the dev server starts without real
+  infrastructure (e.g. a throwaway SQLite `DATABASE_URL`, a dummy secret). Previews must
+  not depend on production services.
+- **Showcase mounting** — how to add a _temporary_ page that renders arbitrary components
+  with fake data, reachable at a URL. For drop-in-file frameworks that's a route file; for
+  server-rendered stacks (Django, Rails) it's a temporary route + view + template.
+
+## Step 2 — Write `.flumecode/plugins/ui-preview.json`
+
+Write the manifest with these fields (the runner fills sane defaults for omitted optionals,
+but be explicit):
+
+| Field         | Type              | Meaning                                                                                                                               |
+| ------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `version`     | number            | Manifest version. Use `1`.                                                                                                            |
+| `appDir`      | string            | App dir relative to repo root (`.` for root).                                                                                         |
+| `install`     | string[]          | Commands run (in order) before the dev server. Keep idempotent.                                                                       |
+| `devServer`   | string            | Dev-server command. Use the token `{PORT}` where the port goes.                                                                       |
+| `readyPath`   | string            | Path polled for HTTP readiness once up (usually `/`).                                                                                 |
+| `env`         | object (optional) | Extra env for the dev server (hermetic boot).                                                                                         |
+| `uiGlobs`     | string[]          | Globs that count as a UI change (gates whether a session previews).                                                                   |
+| `showcase`    | object            | `{ "kind": "...", "instructions": "..." }` — the recipe the `preview-ui` skill follows each session to author the ephemeral showcase. |
+| `manualSteps` | string (optional) | Set ONLY when you cannot fully automate previews — markdown telling a human what to do. Omit/empty otherwise.                         |
+
+The `showcase.instructions` is the most important field: write **clear, stack-specific,
+step-by-step** instructions a future agent can follow blindly — where to create the
+showcase file(s), which route to register, the exact URL path to serve at, and how to
+import/stub the changed UI. Choose an unlikely URL path such as `/__flumecode_preview`.
+
+### Examples
+
+**Next.js (App Router) in a monorepo member:**
+
+```json
+{
+  "version": 1,
+  "appDir": "apps/web",
+  "install": ["pnpm install"],
+  "devServer": "pnpm next dev -p {PORT}",
+  "readyPath": "/",
+  "uiGlobs": ["apps/web/**/*.tsx", "apps/web/**/*.css"],
+  "showcase": {
+    "kind": "next-app-route",
+    "instructions": "Create apps/web/app/__flumecode_preview/page.tsx as a client component. Import the changed components by relative path, render them in a column with fake props, and stub any data hooks inline. Serve at /__flumecode_preview."
+  }
+}
+```
+
+**Django:**
+
+```json
+{
+  "version": 1,
+  "appDir": ".",
+  "install": ["pip install -r requirements.txt"],
+  "devServer": "python manage.py runserver 127.0.0.1:{PORT}",
+  "readyPath": "/",
+  "env": { "DJANGO_SETTINGS_MODULE": "myproject.settings", "DATABASE_URL": "sqlite:///preview.db" },
+  "uiGlobs": ["**/templates/**/*.html", "**/static/**/*.css"],
+  "showcase": {
+    "kind": "django-urlconf",
+    "instructions": "Add a temporary view that renders the changed template(s) with a hard-coded context, register it at path '__flumecode_preview/' in the project urls.py, and ensure ALLOWED_HOSTS permits localhost. Serve at /__flumecode_preview/."
+  }
+}
+```
+
+**Ruby on Rails:**
+
+```json
+{
+  "version": 1,
+  "appDir": ".",
+  "install": ["bundle install"],
+  "devServer": "bin/rails server -p {PORT} -b 127.0.0.1",
+  "readyPath": "/",
+  "env": { "RAILS_ENV": "development" },
+  "uiGlobs": ["app/views/**/*.erb", "app/assets/**/*.css"],
+  "showcase": {
+    "kind": "rails-route",
+    "instructions": "Add a temporary controller action that assigns hard-coded instance variables and renders the changed view(s), wire it to get '/__flumecode_preview' in config/routes.rb. Serve at /__flumecode_preview."
+  }
+}
+```
+
+## Step 3 — Write the wiki record
+
+Create or update `.flumecode/wiki/components/ui-preview.md` (and add a row for it in the
+wiki nav map in `README.md`). It documents — for humans — the detected stack, the
+install/run/preview commands, and any manual steps. Begin it with a sync marker so a future
+re-init knows what it last synced to:
+
+```
+<!-- preview-plugin-synced-to: <current HEAD SHA> -->
+```
+
+Get the SHA with `git rev-parse HEAD`. Keep the page short and accurate; point at the
+manifest rather than duplicating it.
+
+## Step 4 — Install / scaffold what previews need
+
+If the app needs a package or config to be previewable (e.g. a dev dependency, a sample
+env file, a static-build config), add it now — these changes persist in the PR so future
+previews don't re-do them. Do not add anything the app doesn't actually need.
+
+## Step 5 — Best-effort self-verify
+
+If you can, verify the recipe end-to-end without real infrastructure: run `install`, start
+the `devServer` on a free port with `env`, author a trivial showcase per your own
+`showcase.instructions`, and confirm the page renders. Then **revert any throwaway showcase
+edits** — only the manifest, wiki record, and genuinely-needed packaging should remain.
+
+## When you cannot fully automate
+
+If the app cannot boot for previews without external services (a real database, third-party
+auth, secrets you don't have), do not guess. Set `devServer` to `""` (or still record your
+best attempt) and fill `manualSteps` with concise markdown telling a human exactly what to
+provide. Still write the wiki record. The per-session pass will then report previews as
+needing setup, surfacing your steps, instead of failing opaquely.
+
+## Always
+
+- Only create/edit files under `.flumecode/` plus the minimal packaging the previews need.
+  Never change application logic.
+- Do not commit or push — the runner does. Reply with a one- or two-line summary: the
+  detected stack, the commands you recorded, and any manual steps left for a human.