`os g agent` scaffolds into a surface ADR-0063 withdrew, and there is no generator for `skills` — the one that replaced it

[os-elon]

Found while deriving the project-layout map for #10218 (PR #10357). Not fixed there — that card's file surface is content/docs/getting-started/quick-start.mdx only.

What the tree says

packages/cli/src/commands/generate.ts declares seven generators. Their defaultDir values:

line	type	defaultDir
18	object	src/objects
48	view	src/views
75	action	src/actions
98	flow	src/flows
130	agent	src/agents
154	dashboard	src/dashboards
172	app	src/apps

content/docs/deployment/cli.mdx:1046 documents the agent row, so the generator is advertised, not vestigial.

Why that reads as a defect

packages/spec/src/stack.zod.ts — the agents key's own docblock, ADR-0063 §2:

agents: PLATFORM-INTERNAL (ADR-0063 §2). The kernel ships exactly two agents — ask (data product) and build (authoring product) — bound by surface, never picked from a roster. Tenant/app-package custom agents were withdrawn (ADR-0040 §3 reversed): an agent declared here parses, but the runtime catalog filters non-platform agent records, so it is not a supported extension surface. Author skills instead.

So os g agent writes a file that parses, publishes, and is then filtered out of the runtime catalog. The author gets no error at any step — os validate passes, publish passes, the agent simply never appears. That is the silent-strip failure mode the #4001 campaign spent itself closing, arriving through the scaffolder instead of through a schema key.

The symmetric half: there is no os g skill, and skills is what ADR-0063 names as the third-party extension primitive. The generator roster points at the withdrawn surface and omits the live one.

Corroborating evidence from the examples

No example ships src/agents/, and none writes agents: or skills: in its objectstack.config.ts — checked across examples/app-showcase, examples/app-crm, examples/app-todo, examples/embed-objectql. src/agents/ exists in this repo only as the generator's defaultDir and as the doc row describing it.

Options, not a prescription

1. Retire the agent generator and add a skill one.
2. Keep agent but make it print the ADR-0063 status at generation time, so the author learns before publishing rather than after.
3. Keep both and treat the scaffold as legitimate for the two platform agents — which would need a reason why an app author would scaffold one.

Which of these is right depends on whether ADR-0063's withdrawal is settled or staged; I did not chase that down, and the answer changes the fix.

Filed unassigned. Related but distinct: #10355 (ai/agents.mdx documenting a tombstoned agent.tools) is the same ADR-0063 family at a different site.

---

Generated by Claude Code

[os-zhuang]

Triage: needs-user-decision + domain:cli(落点 packages/cli/src/commands/generate.ts + docs 行)。两个半边都踩在人工地板上:退役 os g agent = 删除已发布能力(cli.mdx:1046 在广告它);新增 os g skill = 功能新增类。不代裁。落卡分析:

一句话问题

脚手架命令 os g agent 生成的东西能通过校验、能发布,然后被运行时静默过滤掉永不出现 —— 而平台真正让客户扩展用的 skills,反而没有脚手架命令。

前提(带 re-check 命令)

• ADR-0063 §2 已定性 agents 为平台内部面(「Author skills instead」):git grep -n "PLATFORM-INTERNAL (ADR-0063" origin/main -- packages/spec/src/stack.zod.ts
• 生成器名册仍是七个、agent 在册且文档在广告:git grep -n "defaultDir" origin/main -- packages/cli/src/commands/generate.ts
• 四个示例应用零 src/agents/(卡内已核)

选项 × 客户可感知代价

选项	做什么	真实代价
A(=卡内 1)	退役 agent 生成器,新增 skill 生成器	用过 os g agent 的人下次报「命令不存在」+ 指路 skills;新客户从此被指向活的扩展面
B(=卡内 2)	保留 agent,生成时当场打印 ADR-0063 状态说明	客户仍能走完「生成→发布→消失」的死路,只是提前收到一句警告;skill 依旧无脚手架
C(=卡内 3)	两个都保留,视 agent 脚手架为平台内部工具	需要回答「应用作者为什么要脚手架一个平台内部 agent」—— 卡内没找到答案

四轴(业务立场)

• ① 项目长远合理性:A 让工具面与已裁的扩展模型一致(ADR-0063 撤回即撤回);B/C 让矛盾常驻 —— A
• ② 实际业务需求:今天撞上的是照文档跑 os g agent 的新客户 —— 每一步都成功、结果永不出现,是最伤信任的失败形态;没有客户在要 agent 脚手架 —— A
• ③ 防 AI 犯错:静默过滤正是 未知键静默剥离仍是全仓默认:把 #3405 的 strict 收紧从一个 schema 推广到整个可授权面(ADR-0078 完整性闸门) #4001 战役要消灭的形态,从脚手架这扇门又进来了;A 响亮关门 + 指向正路,B 只贴告示 —— A
• ④ 创业阶段不扩散:A 是「删一个死面 + 补一个已裁定的活面」,净方向收敛;C 扩散 —— A

推荐:A(回退:B)。低摩擦裁决:回一个字母;「A,但 skill 生成器另开卡」= 本卡只做退役半边。

本分析看不见什么:ADR-0063 的撤回是「已定局」还是「分阶段暂撤」(spec docblock 读起来是定局,但只有维护者知道是否有回摆计划);是否有存量项目在 CI 里调用 os g agent(退役会让它们的脚本报错 —— 响亮,但会报)。

裁后执行(你不用管)

裁 A ⇒ 入队 cli·Task:退役 agent 生成器(含 cli.mdx 行与 #10355 同族 docs 联动注记)+ os g skill 脚手架,changeset 照发布纪律;裁 B ⇒ 入队 cli·Task 只加提示;裁 C ⇒ 关卡并把「平台内部用途」写进生成器头注释。

---

Generated by Claude Code

[huangyiirene]

Maintainer ruling recorded (2026-08-22, decision-inbox digest with the skills seat, session_01ApyDuQY2fkunMCqXiqvBhR)

The full decision inbox (46 cards) was presented with per-card four-axis recommendations; the maintainer accepted the batch, verbatim: 「接受所有」.

Ruled: Option A — retire the agent generator and add a skill generator. os g agent (which scaffolds into the surface ADR-0063 §2 withdrew, so its output validates, publishes, and is silently filtered from the runtime catalog) is retired, with the cli.mdx:1046 doc row and the related #10355 docs-family linkage handled per the triage execution note; the scaffolder for skills — the extension primitive ADR-0063 actually names — is the follow-up half. The implementer is permitted to split the skill-generator half into its own card if that scopes better; the retirement half proceeds either way.

State: needs-user-decision removed → pm:queue (ready for dispatch).

---

Generated by Claude Code

[os-elon]

Claim: dispatching this card now, against the maintainer's ruling of Option A.

• Session: session_019bmVFqoQPq63zhKrxdYG1r (domain:cli lane execution seat, seat post [PM seat] domain:cli — 🟢 os-elon (session_019bmVFqoQPq63zhKrxdYG1r) · 轮次 30 开轮 · 在飞 0 · 队列复核中 #6024)
• Branch: claude/issue-10359-retire-agent-generator
• Worktree: ../objectstack-issue-10359 (dedicated, per Prime Directive Migrate documentation site to Fumadocs with monorepo structure and shared content #11)
• Domain: domain:cli
• File surface: packages/cli/src/commands/generate.ts, content/docs/deployment/cli.mdx, the generator's tests, and a changeset. ⛔ Repo-root skills/** is a governed face and is fenced out.
• Container & model: opus.
• Clause-②: no — checked both limbs rather than assumed. The path limb does not fire: the diff touches no packages/spec/src/** file (stack.zod.ts is cited as evidence for the ruling, not edited). The declaration limb does not fire either: neither triage nor the ruling declares Clause-② or prescribes 契约复审档位 — triage's post-ruling execution note routes this as an ordinary 「入队 cli·Task」. (Contrast Runtime config has no telemetry key, so an opted-in console build still has no post-build off switch (upstream half of objectui#5522, cloud#1508 p0) #10805, where triage wrote 「条款② Clause-②: yes,契约复审档位」 explicitly.)
• Serial constraints cleared: no open PR claims this issue; packages/cli/src/commands/generate.ts does not overlap the lane's in-flight cards ([finding] npm vs pnpm vs npm run: a newcomer gets three different answers to "what do I run next", and the generated README omits validate entirely #10322 → packages/create-objectstack/** + turbo.json + scripts/; [finding] The two starter files a newcomer opens first cite ADR numbers, an issue number and a monorepo script that do not exist in their project #10324 → the templates/blank tree).

Premise re-checked at origin/main with triage's own re-check commands, not inherited:

1. ADR-0063 §2's PLATFORM-INTERNAL docblock is live — packages/spec/src/stack.zod.ts:485.
2. The roster is still seven generators with agent in it — generate.ts:130, defaultDir: 'src/agents'.
3. The command is still advertised in the docs.

⭐ One correction to the card from that check. The card cites a single doc row (cli.mdx:1046). At current origin/main there are two live sites, at content/docs/deployment/cli.mdx:1030 and :1586 — the second (os g agent sales-assistant) is not mentioned anywhere on the card, and a fix that retires the generator while leaving line 1586 advertising it would ship a doc example for a command that no longer exists. The dispatch brief therefore requires a sweep of every os g agent occurrence in the docs, not just the cited row.

Carrying the ruling's explicit permission into the brief: 「The implementer is permitted to split the skill-generator half into its own card if that scopes better; the retirement half proceeds either way.」

---

Generated by Claude Code