Skip to content
Open
Changes from 1 commit
Commits
Show all changes
30 commits
Select commit Hold shift + click to select a range
0a031eb
spec(FIX-548): `create-fsd-app` — npx-able scaffolding for new FSD pr…
claude Aug 15, 2026
3118cce
spec(FIX-548): re-draft — `create-flow-state`, one template, owns it …
claude Aug 18, 2026
c2579de
spec(FIX-548): make the goal-run count consistent — per template x pe…
claude Aug 18, 2026
dbda62f
spec(FIX-548): pin create-next-app exactly, and make the probe fail w…
claude Aug 18, 2026
ecce07d
spec(FIX-548): canonical route exports, credential stop as its own ca…
claude Aug 18, 2026
c67c063
spec(FIX-548): make the unscoped publish a prerequisite, and correct …
claude Aug 18, 2026
a1c1553
spec(FIX-548): record the one-command finding in §13 as resolved upst…
claude Aug 18, 2026
4c2e396
spec-poc(FIX-548): assert the failure reason and the scaffold facts, …
claude Aug 18, 2026
836a305
spec-poc(FIX-548): make every README claim assertion-backed or delete it
claude Aug 18, 2026
eee403f
spec(FIX-548): close the evidence contract on both sides, and fix a c…
claude Aug 18, 2026
af5fd0d
spec-poc(FIX-548): freeze the probe, after two last checks that could…
claude Aug 18, 2026
c19b834
spec(FIX-548): conform to FIX-1159's wiring contract, and fix two def…
claude Aug 18, 2026
2ecd4fa
spec(FIX-548): settle the import form the POC never tested, and three…
claude Aug 18, 2026
404e82c
spec(FIX-548): make the deliverable, the summary categories and the f…
claude Aug 18, 2026
48d2a52
spec(FIX-548): take the five jobs nobody owned, wire the FIX-1160 edg…
claude Aug 19, 2026
a3fc694
spec(FIX-548): fix three residuals the rewrite created
claude Aug 19, 2026
3480183
spec(FIX-548): derive the dependency set from imports, and fix a guar…
claude Aug 19, 2026
30f6399
spec(FIX-548): name pnpm on the two real CI specs that install
claude Aug 19, 2026
2aebb40
spec(FIX-548): order the deterministic writes ahead of the fallible o…
claude Aug 19, 2026
4a400d0
spec(FIX-548): put the transcript summary in execution order
claude Aug 19, 2026
b0b5754
spec(FIX-548): make a failed AGENTS.md append stop the run, and corre…
claude Aug 19, 2026
dce7a26
spec(FIX-548): add the step that writes the dependencies, block sub-P…
claude Aug 19, 2026
d34dfa9
spec(FIX-548): withdraw the start narrowing and the production refusa…
claude Aug 19, 2026
a2dcb53
spec(FIX-548): propagate the start withdrawal through every count and…
claude Aug 19, 2026
4552da7
spec(FIX-548): repair the Next-specific sentence and record this roun…
claude Aug 19, 2026
64227dd
spec(FIX-548): write the §12 description decision 8 pointed at, and r…
claude Aug 19, 2026
28c2d08
spec(FIX-548): stop promising the withdrawn production refusal in the…
claude Aug 19, 2026
eb38dea
spec(FIX-548): mark the superseded product statement in the evolution…
claude Aug 19, 2026
48cc886
spec(FIX-548): pin zod to v3, replace the single version placeholder …
claude Aug 19, 2026
071e3e9
spec(FIX-548): add the four implementer notes and close the spec
claude Aug 19, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
spec(FIX-548): conform to FIX-1159's wiring contract, and fix two def…
…ects that shipped a broken app

Epic theme 9: the install skill can never reach this template — a brownfield
developer installs the plugin and nothing else, theme 4 forbids reading our
monorepo, and the template ships inside the published scaffolder. So the template
stops being the reference shape the skill points at. FIX-1159 authors a wiring
contract and this template conforms to it: the Next.js mount pair,
fsdev.config.ts's shape with its store profile, and the dependency set.

Recorded as a CONSTRAINT, not a deliverable. Same six files, no new package,
artifact or dependency, still the set's only deterministic writer. What moved is
authorship of three shapes it was already writing. §2's drift tripwire is
re-aimed (both sides cite the contract, rather than the skill citing the
template), decision 3's justification shifts from "instructions can point at it"
to "conformance can be checked against it", and the FIX-1159 edge is firmer than
recorded: it was the library seam plus the printed next-steps block, neither of
which touched this template's own files.

Node floor. The CLI loads fsdev.config.ts through a native import(), and native
type stripping arrives in 22.18 — load-config.ts names it in its runtime-floor
note and in the remediation it prints. On 22.0–22.17 the scaffold SUCCEEDED and
every printed fsdev command then failed to load the config: the headline outcome
breaking silently on a range we advertise. Step 1 now refuses before creating
anything.

The reasoning is narrower than it looked, and is stated rather than the number
alone: the POC settled the shape GIVEN a TypeScript config and never tested the
.mjs escape the loader documents. What rules that escape out is a JS config
losing type checking on the most error-prone file in the template, FIX-1159
decision 4, and theme 9 making the config's shape a contract — not the POC.

The Created summary moves to the wrapper. §5 had init print it while §7's seam
hands init no file list, so an implementer had to widen the seam or print a list
init cannot verify. The wrapper wrote the files and knows them; this keeps the
seam at decision 3's width and is what lets the epic's report-versus-diff check
for this issue pass at all.

§10 gains two behaviours: the Created summary compared against the actual diff in
both directions, and the sub-22.18 refusal leaving the directory untouched.

probe.sh is untouched — it stays frozen; this round is prose only.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m
  • Loading branch information
claude committed Aug 18, 2026
commit c19b834b7ffed2fbf40ca8f60767700a71b51b36
119 changes: 106 additions & 13 deletions spec/FIX-548.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,8 +43,11 @@ section, the dependency install, and the block of next steps that gets printed.
this spec's previous draft, which had init generate the config and the host wiring while this
package supplied only demo content. That boundary existed to stop two deterministic writers
duplicating scaffolding logic; after the split there is one, so the line moved. What replaces it
is a **drift** tripwire: the template is the reference shape, checked in as real files, and the
install skill's instructions point at it rather than restating its contents.
is a **drift** tripwire, and epic theme 9 has since re-aimed it. The template is no longer the
reference shape the install skill points at — that skill ships in a plugin and can never reach a
template published inside this scaffolder. Instead **both conform to a wiring contract FIX-1159
authors**, and the tripwire watches for either one restating the wiring instead of citing it.
This package still writes the shape; it no longer defines it.

**Philosophy** — tenet 2 (composition over features): the command's value is the ordering of
three things that already exist. Tenet 3 (earn every addition): §6 is mostly about keeping the
Expand Down Expand Up @@ -90,9 +93,10 @@ file list short and refusing surface — including a `--template` flag with one
twice.**
*Rejected:* the previous draft's split, where init generated `fsdev.config.*` and the Next
route pair and this package supplied only the demo flow and the page.
*Locks in:* the template is a directory a person can read, diff, and point instructions at,
which is what epic theme 1's drift tripwire needs — a shape assembled at runtime from
`create-next-app` output plus init's generator is not readable anywhere. It also means init's
*Locks in:* the template is a directory a person can read and diff, which is what checking it
against **FIX-1159's wiring contract** requires (epic theme 9) — a shape assembled at runtime
from `create-next-app` output plus init's generator is readable nowhere, so nothing could be
held to the contract at all. It also means init's
Next-host branch is no longer on this path (§12 raises that with FIX-1159 rather than
deciding it). The cost is that a config generator now exists in two places and can drift;
the epic accepted exactly that trade when it replaced "no two writers" with "watch for
Expand All @@ -117,6 +121,28 @@ file list short and refusing surface — including a `--template` flag with one
not run, and we add one key. Dependencies and the lockfile still belong entirely to the
package manager. Stated out loud because a reviewer should see the exception, not find it.

*Consequence — the generated app needs **Node 22.18+**, and step 1 refuses below it.* The CLI
loads a TypeScript config through a native `import()`, and native type stripping arrives in
**22.18** — `packages/cli/src/load-config.ts` says so in its runtime-floor note and in the
remediation text it prints. Below that the scaffold would finish, print its next steps, and
then **every printed `fsdev` command would fail to load `fsdev.config.ts`**: the epic's
headline outcome breaking silently, on a Node range we advertise as supported. So the check
belongs in step 1's validation, refusing **before any directory is created**, with the floor
and the message init uses — not late, as a config-load error, after a project exists.

*What actually forces this, stated precisely, because the POC does not.* The POC settled the
config's shape **given that it is TypeScript**; it never tested a `.mjs` config, and the
loader documents `.mjs`/`.js` as a universal escape that would work across all of 22.x. That
escape is rejected on other grounds: a JavaScript config in an otherwise TypeScript template
drops type checking on the most error-prone file in it, contradicts FIX-1159 decision 4
(TypeScript for the CLI half), and — after epic theme 9 — `fsdev.config.ts`'s shape belongs to
a contract FIX-1159 authors, not to something this template may reformat to widen a Node
range. 22.18 is old enough by now that requiring it costs approximately nobody.

*Not the package's `engines`.* This floor is what the **generated app** needs, checked against
the Node actually running the command. The scaffolder's own `engines` stays at the repo-wide
`>=22`; §9 records why narrowing that is a separate mistake.
Comment on lines +246 to +248

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Persist the runtime floor in the generated app

When a project is scaffolded on Node 22.18+ and later cloned or deployed on Node 22.0–22.17, the one-time scaffolder check no longer runs, the FSD packages' >=22 engines still admit that runtime, and the printed CLI commands fail to import fsdev.config.ts. The current revision addresses the earlier runtime-floor issue only during creation; keep the scaffolder's own engine range unchanged, but add node >=22.18 to the generated app's manifest so its stated requirement travels with the project.

Useful? React with 👍 / 👎.


5. **The demo flow reaches whichever provider the developer has a key for, through an intent —
it never hard-codes one provider's model.** The config declares
`models: { default: <the chosen provider's model>, intents: { chat: [anthropic, openai,
Expand Down Expand Up @@ -287,9 +313,21 @@ $ npm create flow-state my-app
AGENTS.md tells your coding assistant how to write FSD flows.
```

Everything from `Created` down is **init's output, printed by init** (epic theme 5). The three
lines above it are this package's. Two details in the block are load-bearing rather than
cosmetic: `npm exec` needs the `--` separator or npm consumes `--input` as its own configuration
**Who prints what.** The `Created` block is **this package's**, along with the three lines above
it. Everything from `Wrote` down is **init's output, printed by init** (epic theme 5) — that is
where the byte-identical-to-a-standalone-run guarantee applies, and the next-steps block is the
part theme 5 actually binds.

*This corrects an earlier draft that put `Created` on init's side of the line.* It could not
hold: §7's step-4 table hands init broad declarations that config, flows and wiring exist and
**never a file list**, so init cannot name six files it did not author and was not told about.
The two ways out were widening the seam — giving back the narrowness decision 3 bought — or
printing a summary nobody can know is correct. Neither is needed, because the wrapper wrote those
files and knows exactly what they are. It also matters more than a formatting nit: the epic's
goal check for this issue **compares the run's report against the actual diff**, so a summary
that cannot name what was written is a check that cannot pass.

Two details in the block are load-bearing rather than cosmetic: `npm exec` needs the `--` separator or npm consumes `--input` as its own configuration
and the command fails, and the two-process caveat is real because both printed servers open the
same development store. §10 asserts the first by running it.

Expand Down Expand Up @@ -396,6 +434,11 @@ are exhaustive, which is what keeps the citation and the evidence one-to-one.
| the package manager | one manager, one lockfile |
| **returned:** the next-steps block | printed once, by init, byte-identical to a standalone init run (epic theme 5) |

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Brittle contract: "byte-identical" next-steps (also §10) couples create-fsd-app CI to init wording. Any init copy tweak breaks wrapper tests though behaviour is fine. Consider asserting same commands/URLs in order (normalized whitespace) or owning the snapshot in init's test suite only.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Reconcile ownership of the generated-file summary

On every successful scaffold, the transcript requires init to print a Created summary containing all six template files, including app/page.tsx, but this closed handoff gives init only broad declarations that config, flows, and wiring exist and returns only the next-steps block. Since init neither authors nor receives the template file list, the implementation must either violate the stated seam or omit/misreport that summary; assign the template summary to the wrapper or explicitly pass the report data through init.

Useful? React with 👍 / 👎.


**Not** crossing the seam: the list of template files. This package prints its own `Created`
summary (§5) because it is the only side that knows what it wrote — init receives declarations,
not filenames. Keeping it out is what holds the seam at the width decision 3 chose, and it is
what lets the run's report be compared against the actual diff (§10).

**Ordering, and why it is not incidental.** The template is written *before* init runs, so init
sees a fully declared shape and authors nothing that competes. `create-next-app` must skip its
install, or the project installs twice and the second run rewrites the lockfile the first wrote.
Expand Down Expand Up @@ -439,7 +482,7 @@ package generates a project; it changes no framework behaviour.
|---|---|
| Target directory exists and is not empty | Refuse, naming the path. |
| Project name is not a valid npm package name | Refuse, saying which rule failed, and offer the sanitized form. |
| Node runtime below the floor the generated project needs | Refuse, with the same floor and the same message init uses. Do **not** narrow the package's `engines` below the repo-wide `>=22` — FIX-1159 §9 records why. |
| Node runtime below the floor the generated project needs | Refuse in step 1, before anything is created, with the same floor and the same message init uses. The floor is **22.18** — native type stripping, without which every printed `fsdev` command fails to load `fsdev.config.ts` (decision 4). Do **not** narrow the package's `engines` below the repo-wide `>=22` — that is the scaffolder's own runtime, a different question; FIX-1159 §9 records why. |

**The credential stop — after the scaffold exists, before the key is written.** Its own
category, because it is neither of the other two and putting it in either produced a
Expand Down Expand Up @@ -533,6 +576,14 @@ init, in a temporary directory, with no network and no install, **except the thr
a missing pin, since `@16` silently re-resolves. The symptoms otherwise are "the first hour is
slower", "it behaved differently on my machine", and a version nobody tested
- **the printed next-steps block is byte-identical to a standalone init run** (epic theme 5)
- **the `Created` summary names exactly the files the run wrote** — compare the reported list
against the actual diff of the generated directory, in both directions, so a file written but
not reported fails as loudly as one reported but not written. The epic's proof for this issue

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Scope the summary comparison to template files

Fresh evidence beyond the earlier summary-ownership comment is this new bidirectional diff requirement: the six-file Created block can never equal the actual generated-directory diff because the wrapper also changes package.json, while create-next-app and init add their own scaffold, credential, instruction, dependency, and lock files. This makes the required CI behavior fail on every successful run; compare only the materialized template paths, or define the baseline and include every wrapper-authored change in the report.

Useful? React with 👍 / 👎.

requires that comparison; it also pins the seam, since a summary that drifts from the diff is
the first sign the file list has crossed into init
- **the scaffold refuses on Node below 22.18, before creating anything** — assert the exit, the
message naming the floor, and an untouched target directory. Without it the failure moves to
every printed `fsdev` command, after a project exists (decision 4)
- **every printed command runs** — execute the strings the block emitted, in the generated
project, and assert the process starts. This is where npm's `--` separator is caught
- every refusal in §9's first block, each asserting nothing was created
Expand Down Expand Up @@ -570,10 +621,27 @@ subprocesses stubbed.

**Dependencies.**

- **FIX-1159 blocks implementation, not specification.** This package cannot be built until
init's library seam exists, and cannot merge before init merges. §7's step-4 table is the
required interface; it is **smaller than the previous draft's**, because decision 3 moved the
config and the mount here.
- **FIX-1159 blocks implementation, and now constrains part of this specification.** This package
cannot be built until init's library seam exists, and cannot merge before init merges. §7's
step-4 table is the required interface; it is **smaller than the previous draft's**, because
decision 3 moved the config and the mount here.

**The edge is firmer than this spec previously recorded it.** It used to be the library seam
plus the shared next-steps block — both about what crosses the seam at runtime and what gets
printed, neither about this template's own files. Epic theme 9 adds the **wiring contract**,
which does constrain them. Specification can still proceed in parallel, but not as far as
before: the shapes below are conformance targets, not local calls.
- **This template conforms to FIX-1159's wiring contract (epic theme 9).** The contract is the
part both entry paths share, and it covers exactly three things: **the Next.js mount pair**
(`app/api/flows/route.ts` + `app/api/flows/[...path]/route.ts`), **`fsdev.config.ts`'s shape**
including its required store profile, and **the dependency set**. This package writes them;
FIX-1159 specifies them. Everything else in §7 — the demo flow, the chat page, the
agent-instructions section, the manifest edit — is this issue's own and is outside the
contract. Recorded so an implementer conforms rather than inventing the mount shape a second
time; the check is theme 8's parity requirement, that this template and the brownfield Next
path deliver the same mounted-route shape. **No new artifact, package or dependency comes with
this**: the contract travels as skill content on the path skill content already takes
(FIX-1159 authors → FIX-1160 packages → the plugin ships).
- **Publishing the unscoped `create-flow-state` is a hard prerequisite** (decision 1). Not a
naming preference: without it the headline command resolves to nothing, and there is no
in-scope workaround, because a scoped publish cannot serve `npm create flow-state`. What is
Expand Down Expand Up @@ -794,6 +862,31 @@ Spec-PR feedback recorded rather than folded. These are inputs, not instructions
PR that never merges, so any later finding is answered by narrowing a README claim to what the
frozen script proves. The reasoning is on the POC README rather than just the rule: a probe
that keeps earning rounds is one asserting more than its job requires.
- **Epic theme 9 lands as a constraint, not a deliverable.** The install skill can never reach
this template — a brownfield developer installs the plugin and nothing else — so the template
stopped being the reference shape the skill points at. **FIX-1159 now authors a wiring
contract and this template conforms to it**, covering the Next.js mount pair,
`fsdev.config.ts`'s shape with its store profile, and the dependency set. Nothing is added or
removed: the same six files, no new package, artifact or dependency, and this package remains
the set's only deterministic writer. What moved is authorship of three shapes it was already
writing — it is the contract's consumer, not its source. §2's drift tripwire is re-aimed (both
sides now cite the contract instead of the skill citing the template), decision 3's
justification shifts from "instructions can point at it" to "conformance can be checked
against it", and the FIX-1159 edge is recorded as firmer: it used to be the library seam and
the printed next-steps block, neither of which touched this template's own files.
- **Two defects that would have shipped a broken app.** The generated project needs **Node
22.18+** — the native type-stripping floor `packages/cli/src/load-config.ts` names twice —
because the CLI loads `fsdev.config.ts` through a native `import()`. Below it the scaffold
*succeeded* and every printed `fsdev` command then failed, which is the headline outcome
breaking silently on a range we advertise. Step 1 now refuses before creating anything. The
reasoning is recorded rather than just the number, and it is narrower than it first looked:
the POC settled the shape *given a TypeScript config* and never tested the `.mjs` escape the
loader documents, so what rules that escape out is a JS config losing type checking on the
most error-prone file, FIX-1159 decision 4, and theme 9 making the config's shape a contract —
not the POC. Separately, §5 had **init** print the `Created` summary while §7's seam hands it
no file list, so an implementer had to widen the seam or print a list init cannot verify. The
summary moves to the wrapper, which wrote the files; that keeps the seam at decision 3's width
and is what lets the epic's report-versus-diff check pass at all.
- **§12 overstated the npm mechanism, and it is corrected.** The spec said `npm create <name>`
*and* a bare `fsdev` on the path both need unscoped names. Only the first is true. A command
name comes from the package's `bin` key, so `@flow-state-dev/cli` — already declaring
Expand Down
Loading