#1137 Establish personal rulebooks for code layout and TypeScript preferences - #1144
Merged
Conversation
A new rulebook states where code lives and what it is called: source grouped by role rather than left flat, `__tests__/` beside the code it covers, test helpers in a `test-utils/` directory resolved to the nearest common ancestor of the tests that import them, fixture data kept apart from fixture builders, file naming, and declaration order. It deploys as `consult-williamthorsen-code-layout-preferences`. The rulebook records which of its conventions carry no tooling default and therefore bind only through a project's own coverage and lint configuration.
A new rulebook states TypeScript language mechanics, the shape of a module's public surface, and documentation form: named exports only, barrels confined to a package's published entry points, import specifiers naming the file that exists on disk, banned type assertions, function declarations over expressions, type placement, and doc tags. It deploys as `consult-williamthorsen-typescript-preferences`. Doc tags are settled in one direction: `@param` and `@returns` are omitted, with a single exception for symbols a package publishes, where consumers read emitted declarations rather than source. The rulebook notes that compiling with `removeComments` strips those declarations, so the exception reaches nobody until that setting changes.
Library-adoption guidance now sits alongside the other software-engineering principles, and the mocking and describe-argument rules alongside the other testing conventions.
The `code-patterns` and `typescript-conventions` skills are removed. Their rules are carried by the `consult-williamthorsen-code-layout-preferences` and `consult-williamthorsen-typescript-preferences` rulebooks, and by `software-engineering` and `testing-conventions`. A `codeassembly.yaml` naming either removed skill must name a replacement instead.
The project guidance no longer directs agents to a skill that has been removed. The rulebook that replaced it states its own trigger in its description, which is how every other consult-prefixed rulebook is reached.
The TypeScript preferences rulebook now says which linter can enforce its barrel rule and which cannot, so a reader knows the rule holds by convention alone under ESLint.
The TypeScript preferences rulebook now names the three `@typescript-eslint` rules that bind its type-safety section and says the compiler enforces none of it, so a reader adopting the rulebook in a project with no linting knows the section carries no signal there.
…oder The orchestrated coder receives the software-engineering skill, which holds the library-adoption rules it consulted before those rules moved out of a skill it no longer injects. Reviewer and planner agents already received them.
The TypeScript preferences rulebook no longer presents `@typescript-eslint` as the source of its type-safety rules, so a reader on Biome, oxlint, or any other linter is not told the section binds through a package they do not use. The ESLint rule names stay as one worked mapping rather than the definition.
The TypeScript preferences rulebook no longer says which linter catches violations of its barrel and type-safety rules. Both rules bind by being followed, so compliance never depended on knowing whether a violation would be flagged. The import-specifier and doc-tag notes remain. Each names a precondition that decides whether following the rule works at all: honest `.ts` specifiers need a build that rewrites extensions, and a doc tag written under the public-entry-point exception reaches nobody when declarations are compiled without comments.
Both rulebooks state their rules without the ecosystem background and design narration that surrounded them. Where a justification makes a rule bind harder it survives as a clause of six to ten words, and where it only explained how the rule was arrived at it is gone.
The type-safety section states each rule once, with one worked example in place of paired banned and required blocks. Three rules that appeared twice under different headings now appear once.
…t wire The rulebook no longer tells a reader that no directory name carries a tooling default, a claim its own fixtures rule contradicted by placing fixture data where exemptions were said to already apply. Both passages now describe the exemption as one the project configures.
The worked example in the TypeScript preferences rulebook reads its file as text, so an agent copying it gets code that typechecks. Reading without an encoding yields a `Buffer`, which `JSON.parse` rejects.
williamthorsen
added
breaking
Dependency auditProduction dependency audit passed. |
williamthorsen
removed
the
breaking
williamthorsen
marked this pull request as ready for review
August 1, 2026 00:58
williamthorsen
added a commit
that referenced
this pull request
Aug 4, 2026
…e-v0.2.2 codeassembly-v0.4.0 factory-v0.2.2 codeassembly-mcp-v0.2.2 codeassembly-v0.4.0 - #1153 feat: Make codeassembly and kb CLI tools publishable (#1164) - #1091 fix: Anchor a project-deployed link where its target deploys (#1159) - #1156 refactor: Rename packages to publishable names (#1157) - #1152 tooling: Run every test in the default gate, classified by what it reaches (#1155) - #1110 tooling: Migrate Vitest to nmr's centralized model (#1154) - refactor: Refine typescript-preferences - #1150 fix: State doc-description form and make comment mood opt-in (#1151) - deps: Upgrade first-party linting deps to latest version - #1137 feat: Establish personal rulebooks for code layout and TypeScript preferences (#1144) - #1126 feat: Check a package's own guidance content before it ships (#1138) - refactor: Fix lint - tooling: Remove redundant lint rules - #1133 fix: Reject an anchor link that names no heading (#1135) - #1122 feat: Capture lede decisions as an accumulating corpus (#1132) - #1125 feat: Honor invocation tokens in rulebook bodies (#1129) - #1107 feat: Render rulebook links and path tokens per harness (#1124) - #1115 feat: Sync guidance at build and install so an upgrade cannot leave it stale (#1123) - #1114 feat: Adopt a dependency's guidance by naming the package (#1121) - #1088 feat: Deliver project ambient rulebooks per harness (#1113) - #1087 refactor: Rename the authoring rulebook and mark its enforced rules (#1092) - #1095 tooling: Move compilation out of the install lifecycle into a bootstrap step (#1102) - #1094 refactor: Remove the ambient ripgrep dependency from the test suite (#1097) - deps: Upgrade all deps to latest version - tooling: Upgrade all deps to latest version & modernize configs - refactor: Fix lint - #1077 feat: Show the proposed edit above post-review menu options (#1078) - #1068 feat: Deliver ambient rulebooks mechanically, retiring GLOBAL.md (#1075) - #1069 feat: Add a no-second-person rule to the lede-voice doctrine (#1070) - #1050 feat: Add a redundancy rule to the lede-voice doctrine (#1058) - #1035 internal: Add lifecycle workspace with the canonical envelope, vocabulary & lane fold (#1049) - #1006 internal: Extend lifecycle-event instrumentation to five high-traffic skills (#1034) - #1028 feat: Rule out absence-of-removed-code tests (#1032) - #114 feat: Let reviewers emit gated insights into review artifacts (#1031) - #1027 internal: Retire input.received and redundant skill.progress emits (#1030) - #1026 fix: Name the side effects an approval ask authorizes (#1029) - #1022 fix: Normalize action and question label identifiers across asks blocks (#1025) factory-v0.2.2 - #1156 refactor: Rename packages to publishable names (#1157) - deps: Upgrade all deps to latest version - #1152 tooling: Run every test in the default gate, classified by what it reaches (#1155) - #1110 tooling: Migrate Vitest to nmr's centralized model (#1154) - tooling: Remove redundant lint rules - deps: Upgrade deps to latest version - deps: Upgrade all deps to latest version - deps: Upgrade all deps to latest version - tooling: Upgrade all deps to latest version & modernize configs - refactor: Fix lint - deps: Upgrade all deps to latest version kb-v0.3.0 - #1153 feat: Make codeassembly and kb CLI tools publishable (#1164) - #1156 refactor: Rename packages to publishable names (#1157) - #1152 tooling: Run every test in the default gate, classified by what it reaches (#1155) - #1110 tooling: Migrate Vitest to nmr's centralized model (#1154) - tooling: Remove redundant lint rules - #1095 tooling: Move compilation out of the install lifecycle into a bootstrap step (#1102) - tooling: Upgrade all deps to latest version & modernize configs - refactor: Fix lint codeassembly-lifecycle-v0.2.0 - #1153 feat: Make codeassembly and kb CLI tools publishable (#1164) - #1156 refactor: Rename packages to publishable names (#1157) - #1152 tooling: Run every test in the default gate, classified by what it reaches (#1155) - #1110 tooling: Migrate Vitest to nmr's centralized model (#1154) - tooling: Remove redundant lint rules - #1095 tooling: Move compilation out of the install lifecycle into a bootstrap step (#1102) - tooling: Upgrade all deps to latest version & modernize configs - #1038 feat: Add the read-only git adapter for worktree and base-branch ground truth (#1059) - #1051 feat: Bound fold memory and rescan cost with a retention window (#1057) - #1035 internal: Add lifecycle workspace with the canonical envelope, vocabulary & lane fold (#1049) codeassembly-mcp-v0.2.2 - deps: Upgrade all deps to latest version - #1156 refactor: Rename packages to publishable names (#1157) - #1152 tooling: Run every test in the default gate, classified by what it reaches (#1155) - #1110 tooling: Migrate Vitest to nmr's centralized model (#1154) - #1095 tooling: Move compilation out of the install lifecycle into a bootstrap step (#1102) - tooling: Upgrade all deps to latest version & modernize configs - refactor: Fix lint codeassembly-run-core-v0.2.2 - #1156 refactor: Rename packages to publishable names (#1157) - #1152 tooling: Run every test in the default gate, classified by what it reaches (#1155) - #1110 tooling: Migrate Vitest to nmr's centralized model (#1154) - #1095 tooling: Move compilation out of the install lifecycle into a bootstrap step (#1102) - tooling: Upgrade all deps to latest version & modernize configs - refactor: Fix lint
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds two rulebooks describing code-layout and TypeScript conventions for agent-authored code, covering such topics as naming conventions, placement of test helpers and fixture data, use of JSDoc params, and preference for named exports. The
code-patternsandtypescript-conventionsskills have been removed, and their content has been absorbed into the new rulebooks.Why
Code-layout and TypeScript conventions had no single owner, so several went unwritten entirely while the ones that were written had begun to contradict each other: doc tags were ruled out categorically in
shared/AGENTS.mdand permitted conditionally incode-patterns, and both shipped. Both retired skills were also misfiled — normative content carrying noun names, where the content specification asks that such content reach agents as a verb-ledconsult-rulebook.Details
🎉 Features
williamthorsen-code-layout-preferencescovers source taxonomy,__tests__/placement, a three-tier resolution order for where test helpers live, fixture placement, file naming, declaration order, and section separators. Several of these had no written home before: fixture data is separated from fixture builders so the two follow different placement rules,__tests__/is one per directory rather than rolled up per package, and a file takes the name of its main export.williamthorsen-typescript-preferencescovers named exports, the barrel boundary, honest.tsimport specifiers, type mechanics, function declarations, type co-location, and doc-tag form.delivery: skill, so each is invoked by name rather than loaded ambiently, and each description names the condition that should provoke a consult..tsspecifiers requireallowImportingTsExtensionsand a build that rewrites extensions, and a doc tag written under the entry-point exception reaches nobody where declarations compile withremoveComments.🪦 Removed
code-patternsandtypescript-conventionsare deleted. Every rule they carried has exactly one new home; a declaration or subagentskills:entry naming either must be repointed.♻️ Refactoring
software-engineering; test organization and mocking principles move totesting-conventions.orchestrated-codergainssoftware-engineering, keeping library-adoption guidance in reach of the agent that implements.common-mistakesdeclares both rulebooks as dependencies and routes code organization and language mechanics to them.🤖 Agentic support
.agents/PROJECT.mddrops the always-invoke directive for the retired skill. Aconsult-rulebook carries its trigger in its own description, so a project-scoped directive would duplicate it and would not travel to other projects regardless.Known gaps
Rulebook content cannot reach a subagent: a
skills:entry must resolve to a real skill artifact, and ambient delivery lands in the harness-home guidance file, which subagents do not read.orchestrated-coderandcode-simplification-reviewertherefore lose the section-separator, region-fold, doc-tag, and identifier-naming rules thatcode-patternsused to inject. Tracked on #1142 alongside the other mechanism obstacles blocking the wider migration.Closes #1137