Skip to content

docs: restore the concrete type list in the scaffold AGENTS.md #1634

Description

@vivek7405

Problem

#1632 ("state each agent rule once and point to it") cut the scaffold AGENTS.md "Type everything (all templates)" section from a concrete list to a pointer: "Derive the type at every boundary from its source ... the rule is step 8 of the skill's Default Workflow". The section that #1199 added to teach app agents full-stack type safety is now two sentences.

The concrete forms still exist, but not in what an agent reads first: SKILL.md Default Workflow step 8 keeps $inferSelect, a named interface input, ActionResult<T> and PageProps / LayoutProps / RouteHandlerContext; references/typescript.md holds the full ladder (including prop<Student>(Object) at ~L113 and npx webjsdev types at ~L214). Missing from both always-read files: the generated route union (npx webjsdev types), and prop<T>() only survives in the full-stack playbook step 6.

Typing is the one rule webjs check and tsc cannot enforce (both spellings are valid TypeScript), so it is the rule an agent is most likely to skip if the concrete form is not in front of it. This is a judgment from reading the diff and two small builds made after #1632 (both typed well), not a measured regression.

Design / approach

Restore a SHORT concrete list under "Type everything" in the scaffold AGENTS.md, not the old ~2.2k-character prose. Roughly 1k characters (about 250 tokens, against the ~1,560 tokens #1632 saved):

  • A database row: typeof table.$inferSelect / $inferInsert, carried into a shipping component with import type.
  • An action's input: a named interface; its result: ActionResult<T>.
  • Routing files: PageProps<'/x/[id]'>, LayoutProps, RouteHandlerContext; npx webjsdev types for the typed Route union.
  • A reactive property: prop<T>(Object) / prop<T[]>(Array).
  • One line on the unknown exception (an unvetted payload narrowed on the next line; a parameter of your own helper forwarding into an html hole) stays in SKILL.md step 8, do not duplicate it.

Keep the "state each rule once" intent of #1632: the list is a quick-reference of forms, and the rule itself stays canonical in SKILL.md step 8.

Implementation notes (for the implementing agent)

  • Where to edit: packages/cli/templates/AGENTS.md, the ## Type everything (all templates) section (~L35-45). The full-stack and API playbooks are partials (packages/cli/templates/partials/agents-playbook-fullstack.md, agents-playbook-api.md) spliced in by packages/cli/lib/create.js (~L792); the "Type everything" section is NOT in the partials, it is in AGENTS.md itself, so one edit covers every template.
  • Landmines: docs: state each agent rule once and point to it #1632 (7d4f627) is the commit being partly walked back, and its goal (every agent reads these docs on every run, so each duplicated rule is paid for every time) still holds; keep the addition under ~1.2k characters. The pre-docs: state each agent rule once and point to it #1632 text is in git show 7d4f627e^:packages/cli/templates/AGENTS.md if you want wording. docs: teach app agents full-stack type safety instead of unknown / any #1199 introduced the original section.
  • Invariants: no em-dashes or space-surrounded hyphen pauses in docs (see .agents/rules/workflow.md Git rules wording); the skill (.agents/skills/webjs/SKILL.md) remains the canonical statement of the rule, AGENTS.md only lists forms.
  • Tests + docs surfaces: grep found no test asserting the section's text, but run the scaffold validation tests (test/scaffolds/scaffold-template-validation.test.js, test/scaffolds/scaffold-integration.test.js) after the edit. Per webjs-doc-sync, check whether the website docs repeat the scaffold AGENTS.md section (website/app/docs/) and whether any other scaffold surface (webjs-scaffold-sync map) copies it.

Acceptance criteria

  • The generated AGENTS.md for the full-stack and api templates names $inferSelect, ActionResult<T>, PageProps / LayoutProps, prop<T>() and npx webjsdev types in the "Type everything" section.
  • The addition is ~1k characters or less and does not restate the unknown rule already in SKILL.md step 8.
  • A fresh webjs create scaffold generates the section and passes its own ci.
  • Scaffold tests pass; no other surface left stating a different version of the list.

Activity

  1. self-assigned this
    on Oct 8, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

documentationImprovements or additions to documentation

Type

No type

Projects

  • Status
    Done

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions