You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
fix(cli): retire the agent generator — os g agent now names ADR-0063 and points at skills (#11028)
* fix(cli): retire the `agent` generator, and make the refusal name skills
`os g agent` scaffolded into `src/agents`, a surface ADR-0063 §2 withdrew. The
kernel ships exactly two agents (`ask`, `build`) and the runtime catalog filters
out every other agent record, so the generated file passed `os validate`,
published without complaint, and then never appeared — no error at any step.
That is the silent-strip failure mode, arriving through the scaffolder.
Deleting the roster entry alone would have moved the silence one step earlier
rather than ending it: `Unknown type: agent` plus the surviving roster tells the
author their spelling is not on the list, and the natural next move is to hunt
for the right spelling of something that no longer exists. So `agent` moves to a
`RETIRED_GENERATORS` ledger whose entries owe both halves — the decision that
withdrew the surface, and the surface to author instead. The refusal names
ADR-0063, the two platform agents, the silent strip, and skills
(`src/skills/<name>.skill.ts`, `defineSkill`) as the live extension primitive,
and it exits 1 so a CI script that still calls the command stops.
Advertising sites swept, not fixed by line number: the generator entry and the
`type` argument's roster string in `generate.ts`, `packages/cli/README.md`'s
"Available generate types" line, and three sites in
`content/docs/deployment/cli.mdx` (the `os g agent support` example, the
`agent` / `src/agents/` row of the Available types table, and
`os g agent sales-assistant` in Typical Workflow — the last of which the card
did not name). `content/docs/getting-started/quick-start.mdx`'s project-layout
map advertised `src/agents` as the AI area's authoring directory; it now names
`src/skills`, which is what ADR-0063 says an app author writes.
`scripts/adr-anchors/packages__cli__src__commands__generate.ts.json` pins
ADR-0063 to the file, so the absence of an `agent` generator reads as a decision
rather than an oversight to the next author.
`os g skill` is deliberately NOT in this change — see the follow-up card. The
message says the scaffolder does not exist yet rather than promising it.
Part of #10359
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019bmVFqoQPq63zhKrxdYG1r
* docs(changeset): the `agent` generator is retired — breaking, and loud about it
Declares the removal as breaking (shipped `minor` under the launch-window
convention) and states the consequence a release-notes reader needs: a CI step
that still calls `os g agent` starts exiting 1.
The ADR-0087 disposition is `no-migration-prescription`, and it is a positive
finding rather than a detector miss: a CLI command name is an invocation
surface with no authorable key, no stored row and no schema tombstone, so no
ledger reader has anything to carry — and unlike the metric retirement that
category is usually weighed against, the ledger is not the only notification
channel here, because the command itself now refuses at the point of use.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019bmVFqoQPq63zhKrxdYG1r
---------
Co-authored-by: Claude <noreply@anthropic.com>
fix(cli): **BREAKING** — the `agent` generator is retired, and `os g agent` now says why and points at skills (ADR-0063 §2, #10359)
6
+
7
+
**⛔ If a script, a Makefile or a CI step in your project runs `os g agent`, it
8
+
will now exit 1.** That is the intended outcome and the one way this change can
9
+
interrupt you: the command is gone, deliberately, and the failure is how you
10
+
find out. Everything it used to produce was already being discarded — read on.
11
+
12
+
`minor`, not `major`: during the launch window this stack ships breaking changes
13
+
as `minor` (pre-1.0 semantics under lockstep versioning — see
14
+
`scripts/check-changeset-no-major.mjs`).
15
+
16
+
**What the command actually did.**`os g agent <name>` scaffolded a typed
17
+
`AI.Agent` into `src/agents/`. Per ADR-0063 §2 (which reversed ADR-0040 §3) the
18
+
kernel ships exactly **two** agents — `ask` and `build` — bound by surface and
19
+
never picked from a roster, and the runtime catalog **filters out every
20
+
non-platform agent record**. So the scaffolded file parsed, passed
21
+
`os validate`, published without complaint, and then never appeared anywhere.
22
+
No error at any step. An author who followed the documented example got a file,
23
+
a green validate, a successful publish, and nothing to show for it.
24
+
25
+
**Why the roster entry was not simply deleted.** A deleted type falls through to
26
+
`Unknown type: agent` plus a list of what is left, which tells the author their
27
+
spelling is not on the list and invites them to hunt for the right spelling of
28
+
something that no longer exists — the same silence, one step earlier. `agent` is
29
+
now a **retirement ledger entry** instead, and the refusal carries both halves:
30
+
the decision that withdrew the surface, and the surface to author in its place.
31
+
What you see:
32
+
33
+
```
34
+
✗ `os g agent` was retired — agents are platform-internal (ADR-0063 §2).
35
+
36
+
The kernel ships exactly two agents, `ask` and `build`, bound by surface.
37
+
An agent you author still parses and still publishes — and the runtime
38
+
catalog then filters it out, so it never appears and nothing tells you.
39
+
This command scaffolded exactly that file, so it is retired, not repaired.
40
+
41
+
Author a SKILL instead. Skills (plus tools / MCP) are the third-party
42
+
extension primitive ADR-0063 names — the live surface this one was not.
43
+
44
+
There is no `os g skill` scaffolder yet. Write the file by hand:
45
+
46
+
src/skills/<name>.skill.ts
47
+
import { defineSkill } from '@objectstack/spec/ai';
48
+
49
+
Docs: https://objectstack.ai/docs/ai/agents
50
+
```
51
+
52
+
**There is no command to rewrite the call into.** A skill is a different
53
+
artifact with a different schema, not a renamed agent, and `os g skill` does not
54
+
exist yet — the skill scaffolder is tracked separately, and this message says so
55
+
rather than promising it. Delete the call; author the skill file by hand.
56
+
57
+
The generator roster is now `object`, `view`, `action`, `flow`, `dashboard`,
58
+
`app`. The docs that advertised the retired one — the `os g agent support`
59
+
example, the `agent` / `src/agents/` row of the Available types table, and
60
+
`os g agent sales-assistant` in the Typical Workflow block — are gone from
61
+
`content/docs/deployment/cli.mdx`, which carries the retirement note instead;
62
+
`packages/cli/README.md`'s type roster follows. The quick-start project-layout
63
+
map, which listed `src/agents` as the directory an app author writes AI metadata
64
+
into, now names `src/skills`.
65
+
66
+
<!-- adr-0087: not-required (no-migration-prescription) A CLI COMMAND NAME is an invocation surface, not authorable metadata. There is no authorable key, no `sys_metadata` row and no schema to tombstone here, so there is nothing for `objectstack migrate meta` to rewrite, nothing for `spec-changes.json` to project and no FROM -> TO spelling for the upgrade guide to carry: a skill is a different artifact rather than a renamed agent, and no replacement command exists to rewrite the call into. Nor is the ledger the only notification channel this time, which is the difference from `http-request-errors-total-retired` (where an operator's Grafana panel silently drew a flat zero and the entry was the sole way to say so): the command itself now refuses, exits 1, names ADR-0063 and points at skills at the exact moment and place of use. Same reasoning shape as ADR-0087's D7 addendum, one surface over — there the compiler carries the notice, here the CLI does. -->
0 commit comments