coentrify 0.0.1 → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (261) hide show
  1. package/LICENSE +18 -0
  2. package/README.md +5 -4
  3. package/bin/coentrify.js +79 -12
  4. package/package.json +3 -2
  5. package/src/changelog/0.0.1.md +259 -0
  6. package/src/changelog/0.0.2.md +219 -0
  7. package/src/changelog/0.0.3.md +81 -0
  8. package/src/changelog/0.0.4.md +198 -0
  9. package/src/changelog/0.0.5.md +160 -0
  10. package/src/changelog/0.0.6.md +282 -0
  11. package/src/changelog/0.0.7.md +113 -0
  12. package/src/changelog/0.0.8.md +212 -0
  13. package/src/changelog/0.1.0.md +9 -0
  14. package/src/changelog/overview.md +13 -0
  15. package/src/coentrify-json.md +72 -0
  16. package/src/commands.md +48 -0
  17. package/src/glossary.md +132 -0
  18. package/src/how-it-works.md +51 -0
  19. package/src/onboarding.md +140 -0
  20. package/src/origin.md +19 -0
  21. package/src/philosophy.md +99 -0
  22. package/src/proof.md +596 -0
  23. package/src/readme.md +76 -0
  24. package/src/recommendations.md +100 -0
  25. package/src/standards/ai/match-known-commands-deterministically-classify-the-rest.md +22 -0
  26. package/src/standards/ai/overview.md +6 -0
  27. package/src/standards/ai/prompt-small-models-differently.md +21 -0
  28. package/src/standards/angular/canmatch-wildcard-for-route-access.md +22 -0
  29. package/src/standards/angular/interface-not-abstract-class-for-mock-swap.md +37 -0
  30. package/src/standards/angular/no-any-in-templates.md +25 -0
  31. package/src/standards/angular/no-inline-templates.md +14 -0
  32. package/src/standards/angular/one-component-per-folder-flat.md +12 -0
  33. package/src/standards/angular/one-projected-node-per-control-flow-block.md +19 -0
  34. package/src/standards/angular/overview.md +16 -0
  35. package/src/standards/angular/prefer-content-projection-over-props-angular.md +17 -0
  36. package/src/standards/angular/projected-content-is-never-styled-by-the-host.md +23 -0
  37. package/src/standards/angular/static-attribute-not-literal-binding.md +23 -0
  38. package/src/standards/angular/track-timed-items-by-an-id.md +17 -0
  39. package/src/standards/angular/ui-copy-in-template.md +26 -0
  40. package/src/standards/angular/use-modern-angular-template-apis.md +20 -0
  41. package/src/standards/architecture/adopt-configure-override.md +25 -0
  42. package/src/standards/architecture/app-shield.md +57 -0
  43. package/src/standards/architecture/converge-only-once-proven.md +22 -0
  44. package/src/standards/architecture/folder-concerns.md +28 -0
  45. package/src/standards/architecture/overview.md +11 -0
  46. package/src/standards/architecture/per-application-split-over-shared-branching.md +25 -0
  47. package/src/standards/architecture/separation-before-layer-standards.md +17 -0
  48. package/src/standards/architecture/unique-where-it-counts.md +19 -0
  49. package/src/standards/behavior/a-go-before-work-elsewhere.md +17 -0
  50. package/src/standards/behavior/a-maybe-is-a-trigger-to-investigate.md +20 -0
  51. package/src/standards/behavior/a-name-describes-its-unit.md +19 -0
  52. package/src/standards/behavior/a-quiet-tree-while-a-suite-runs.md +19 -0
  53. package/src/standards/behavior/always-make-no-mistakes.md +45 -0
  54. package/src/standards/behavior/always-verify-before-reporting-done.md +18 -0
  55. package/src/standards/behavior/always-work-from-a-plan.md +29 -0
  56. package/src/standards/behavior/anchor-edits-after-formatting.md +17 -0
  57. package/src/standards/behavior/backward-trace-missing-prerequisites.md +20 -0
  58. package/src/standards/behavior/code-review-compounds-into-patterns-and-sweeps.md +21 -0
  59. package/src/standards/behavior/communication-boundary.md +18 -0
  60. package/src/standards/behavior/dev-tiers.md +25 -0
  61. package/src/standards/behavior/docs-hold-only-what-the-director-decided.md +23 -0
  62. package/src/standards/behavior/dont-filter-data-without-a-spec.md +20 -0
  63. package/src/standards/behavior/dont-introduce-tech-debt.md +25 -0
  64. package/src/standards/behavior/feature-workflow.md +31 -0
  65. package/src/standards/behavior/file-a-change-with-coentrify.md +24 -0
  66. package/src/standards/behavior/flag-every-addition-of-your-own.md +22 -0
  67. package/src/standards/behavior/free-text-replies-no-buttons.md +20 -0
  68. package/src/standards/behavior/general-working-rules.md +37 -0
  69. package/src/standards/behavior/non-destructive-documenting-and-test-automation.md +20 -0
  70. package/src/standards/behavior/normal-dashes.md +15 -0
  71. package/src/standards/behavior/note-issues.md +26 -0
  72. package/src/standards/behavior/overview.md +46 -0
  73. package/src/standards/behavior/own-ports-own-processes.md +37 -0
  74. package/src/standards/behavior/project-lifecycle.md +21 -0
  75. package/src/standards/behavior/propagate-renames-and-convention-changes-everywhere.md +16 -0
  76. package/src/standards/behavior/prose-style.md +24 -0
  77. package/src/standards/behavior/prototype-mode-is-speed-first.md +20 -0
  78. package/src/standards/behavior/regular-layered-gap-analysis.md +20 -0
  79. package/src/standards/behavior/reload-the-standards-after-compacting.md +16 -0
  80. package/src/standards/behavior/review-changes-before-reporting-done.md +17 -0
  81. package/src/standards/behavior/review-every-capture-before-reporting.md +21 -0
  82. package/src/standards/behavior/standards-maintenance.md +65 -0
  83. package/src/standards/behavior/standards-over-skills.md +17 -0
  84. package/src/standards/behavior/sweeps-enumerate-into-tech-debt-first.md +20 -0
  85. package/src/standards/behavior/sync-the-docs-after-every-change.md +20 -0
  86. package/src/standards/behavior/the-quality-of-the-question.md +17 -0
  87. package/src/standards/behavior/things-of-one-kind-are-consistent.md +20 -0
  88. package/src/standards/behavior/understand-the-need.md +69 -0
  89. package/src/standards/behavior/use-us-english-everywhere.md +17 -0
  90. package/src/standards/behavior/verify-apis-against-docs-and-the-installed-artifact.md +17 -0
  91. package/src/standards/behavior/verify-control-before-rename.md +11 -0
  92. package/src/standards/code/code-principles.md +32 -0
  93. package/src/standards/code/escape-hatch-comments.md +20 -0
  94. package/src/standards/code/name-by-concept-not-copy.md +20 -0
  95. package/src/standards/code/no-abbreviated-names.md +20 -0
  96. package/src/standards/code/no-describe-what-comments.md +26 -0
  97. package/src/standards/code/overview.md +10 -0
  98. package/src/standards/code/pre-empt-recurring-code-review-nits.md +31 -0
  99. package/src/standards/commits/commits.md +44 -0
  100. package/src/standards/commits/gate-commits-on-exit-codes.md +22 -0
  101. package/src/standards/commits/main-stays-green-work-stays-clean.md +23 -0
  102. package/src/standards/commits/overview.md +8 -0
  103. package/src/standards/commits/verify-staging-before-committing.md +29 -0
  104. package/src/standards/docs/application-template.md +89 -0
  105. package/src/standards/docs/docs-are-hierarchical-explicit-and-short.md +48 -0
  106. package/src/standards/docs/docs-describe-behavior-not-wiring.md +24 -0
  107. package/src/standards/docs/docs-folder-structure.md +38 -0
  108. package/src/standards/docs/docs-state-knowledge.md +23 -0
  109. package/src/standards/docs/documentation-philosophy.md +62 -0
  110. package/src/standards/docs/feature-spec-template.md +89 -0
  111. package/src/standards/docs/feature-template.md +62 -0
  112. package/src/standards/docs/file-names.md +20 -0
  113. package/src/standards/docs/glossary.md +18 -0
  114. package/src/standards/docs/library-feedback.md +20 -0
  115. package/src/standards/docs/no-faux-headers-in-lists.md +18 -0
  116. package/src/standards/docs/overview.md +20 -0
  117. package/src/standards/docs/ui-vocabulary.md +31 -0
  118. package/src/standards/docs/workspace-levels.md +24 -0
  119. package/src/standards/docs/workspace-suite.md +24 -0
  120. package/src/standards/docs/workspace-template.md +41 -0
  121. package/src/standards/e2e/e2e-assert-before-interacting.md +21 -0
  122. package/src/standards/e2e/e2e-mock-contract.md +20 -0
  123. package/src/standards/e2e/e2e-runs-on-the-development-build.md +18 -0
  124. package/src/standards/e2e/e2e-test-conventions.md +61 -0
  125. package/src/standards/e2e/e2e-tests-must-demonstrate-behavior.md +28 -0
  126. package/src/standards/e2e/one-check-for-many-canvas-clicks.md +17 -0
  127. package/src/standards/e2e/overview.md +14 -0
  128. package/src/standards/e2e/per-feature-overview-test.md +30 -0
  129. package/src/standards/e2e/real-input-for-frame-races.md +25 -0
  130. package/src/standards/e2e/substring-locator-collisions.md +23 -0
  131. package/src/standards/e2e/use-the-e2e-pipeline-for-browser-probing.md +18 -0
  132. package/src/standards/electron/electron-packaging-and-suite.md +22 -0
  133. package/src/standards/electron/electron-shell-shape.md +21 -0
  134. package/src/standards/electron/overview.md +6 -0
  135. package/src/standards/gamedev/2d-visual-design.md +22 -0
  136. package/src/standards/gamedev/budget-exceptions.json +6 -0
  137. package/src/standards/gamedev/captures-and-reels.md +39 -0
  138. package/src/standards/gamedev/devbox.md +21 -0
  139. package/src/standards/gamedev/game-design-laws-experience.md +68 -0
  140. package/src/standards/gamedev/game-design-laws-guidance.md +43 -0
  141. package/src/standards/gamedev/game-design-laws-own-style.md +33 -0
  142. package/src/standards/gamedev/game-design-laws-progress.md +54 -0
  143. package/src/standards/gamedev/game-design-laws-quality.md +30 -0
  144. package/src/standards/gamedev/game-design-laws-story.md +45 -0
  145. package/src/standards/gamedev/game-design-laws-ui.md +52 -0
  146. package/src/standards/gamedev/game-design-laws-world.md +38 -0
  147. package/src/standards/gamedev/game-design-laws.md +112 -0
  148. package/src/standards/gamedev/game-phases-concept.md +29 -0
  149. package/src/standards/gamedev/game-phases-design.md +39 -0
  150. package/src/standards/gamedev/game-phases-development.md +30 -0
  151. package/src/standards/gamedev/game-phases-live.md +19 -0
  152. package/src/standards/gamedev/game-phases.md +52 -0
  153. package/src/standards/gamedev/game-work-workflow.md +47 -0
  154. package/src/standards/gamedev/gamedev-working-cadence.md +52 -0
  155. package/src/standards/gamedev/incremental-pacing.md +22 -0
  156. package/src/standards/gamedev/launch-strategy.md +50 -0
  157. package/src/standards/gamedev/measure-sound-never-guess.md +24 -0
  158. package/src/standards/gamedev/overview.md +29 -0
  159. package/src/standards/gamedev/own-icons.md +19 -0
  160. package/src/standards/gamedev/silent-runs.md +26 -0
  161. package/src/standards/gamedev/sprite-sheet-frames.md +23 -0
  162. package/src/standards/overview.md +43 -0
  163. package/src/standards/records/activity-log.md +33 -0
  164. package/src/standards/records/changelog-per-version.md +43 -0
  165. package/src/standards/records/healing-log.md +23 -0
  166. package/src/standards/records/overview.md +10 -0
  167. package/src/standards/records/playtest-files.md +38 -0
  168. package/src/standards/records/request-log.md +30 -0
  169. package/src/standards/records/user-test-files.md +21 -0
  170. package/src/standards/reporting/change-report.md +43 -0
  171. package/src/standards/reporting/overview.md +6 -0
  172. package/src/standards/reporting/reels-and-video-proof.md +32 -0
  173. package/src/standards/scripts/no-npx-in-scripts.md +20 -0
  174. package/src/standards/scripts/npm-script-naming.md +43 -0
  175. package/src/standards/scripts/overview.md +7 -0
  176. package/src/standards/scripts/thin-wrappers-in-ci-and-hooks.md +25 -0
  177. package/src/standards/security/keep-personal-data-out-of-requests.md +16 -0
  178. package/src/standards/security/keep-secrets-away-from-agents.md +21 -0
  179. package/src/standards/security/never-access-the-keychain.md +16 -0
  180. package/src/standards/security/overview.md +7 -0
  181. package/src/standards/simple-workflow/bugs-template.md +38 -0
  182. package/src/standards/simple-workflow/overview.md +12 -0
  183. package/src/standards/simple-workflow/plan-template.md +50 -0
  184. package/src/standards/simple-workflow/plans-vs-persistent-files.md +31 -0
  185. package/src/standards/simple-workflow/remove-completed-items-from-docs.md +19 -0
  186. package/src/standards/simple-workflow/roadmap-template.md +41 -0
  187. package/src/standards/simple-workflow/technical-debt-template.md +44 -0
  188. package/src/standards/simple-workflow/the-simple-workflow.md +48 -0
  189. package/src/standards/simple-workflow/todo-template.md +31 -0
  190. package/src/standards/tests/a-bugs-test-reproduces-with-real-input.md +18 -0
  191. package/src/standards/tests/bracket-state-changes-with-contrast-assertions.md +37 -0
  192. package/src/standards/tests/gestures-in-tests.md +35 -0
  193. package/src/standards/tests/implementation-agnostic-assertions.md +20 -0
  194. package/src/standards/tests/implementation-agnostic-locators.md +18 -0
  195. package/src/standards/tests/overview.md +13 -0
  196. package/src/standards/tests/realistic-test-data-variance.md +24 -0
  197. package/src/standards/tests/seed-surfaces-every-state-on-page-1.md +17 -0
  198. package/src/standards/tests/test-design.md +47 -0
  199. package/src/standards/tests/test-the-system-behind-a-mock.md +21 -0
  200. package/src/standards/tickets-workflow/agent-roles.md +54 -0
  201. package/src/standards/tickets-workflow/budget-exceptions.json +6 -0
  202. package/src/standards/tickets-workflow/building-a-ticket.md +47 -0
  203. package/src/standards/tickets-workflow/overview.md +15 -0
  204. package/src/standards/tickets-workflow/stabilize-before-adding.md +18 -0
  205. package/src/standards/tickets-workflow/the-builder.md +28 -0
  206. package/src/standards/tickets-workflow/the-conductor.md +44 -0
  207. package/src/standards/tickets-workflow/the-done-part.md +23 -0
  208. package/src/standards/tickets-workflow/ticket-template.md +96 -0
  209. package/src/standards/tickets-workflow/work-item-names.md +30 -0
  210. package/src/standards/tickets-workflow/work-tracking.md +177 -0
  211. package/src/standards/tickets-workflow/work-workflow.md +123 -0
  212. package/src/standards/tickets-workflow/writing-a-ticket.md +50 -0
  213. package/src/standards/tooling/browser-captures-go-to-disk.md +20 -0
  214. package/src/standards/tooling/check-where-a-pane-click-landed.md +19 -0
  215. package/src/standards/tooling/defer-tooling-until-the-cost-shows-up.md +19 -0
  216. package/src/standards/tooling/develop-against-mocks.md +19 -0
  217. package/src/standards/tooling/hygiene-tests-run-on-their-own-runner.md +18 -0
  218. package/src/standards/tooling/lightweight-test-reporting-only.md +16 -0
  219. package/src/standards/tooling/node-versions.md +24 -0
  220. package/src/standards/tooling/overview.md +17 -0
  221. package/src/standards/tooling/parallel-agents.md +45 -0
  222. package/src/standards/tooling/playwright-parallel-runs.md +30 -0
  223. package/src/standards/tooling/playwright-video-recording.md +32 -0
  224. package/src/standards/tooling/read-before-you-truncate.md +19 -0
  225. package/src/standards/tooling/start-playwright-on-a-clean-port.md +22 -0
  226. package/src/standards/tooling/vitepress-wiki.md +38 -0
  227. package/src/standards/typescript/always-add-explicit-types.md +32 -0
  228. package/src/standards/typescript/barrel-imports.md +21 -0
  229. package/src/standards/typescript/no-magic-values.md +52 -0
  230. package/src/standards/typescript/one-artifact-per-file.md +19 -0
  231. package/src/standards/typescript/overview.md +8 -0
  232. package/src/standards/ui/communicate-state.md +21 -0
  233. package/src/standards/ui/never-obscure-information-the-user-needs.md +26 -0
  234. package/src/standards/ui/overview.md +16 -0
  235. package/src/standards/ui/pixel-perfect-design-check.md +22 -0
  236. package/src/standards/ui/ui-component-design.md +34 -0
  237. package/src/standards/ui/ui-components-first.md +25 -0
  238. package/src/standards/ui/ui-layout-via-slot-composition.md +33 -0
  239. package/src/standards/ui/ui-library-is-domain-agnostic.md +20 -0
  240. package/src/standards/ui/ui-refactor-preserve-dont-redesign.md +25 -0
  241. package/src/standards/ui/ui-styleguide.md +30 -0
  242. package/src/standards/ui/ui-variants-by-function-not-by-color.md +23 -0
  243. package/src/standards/ui/validation-errors-fire-on-submit.md +20 -0
  244. package/src/standards/ui/walk-the-users-journey.md +29 -0
  245. package/src/standards/web/always-use-design-tokens-for-colors.md +24 -0
  246. package/src/standards/web/dark-mode-through-tokens.md +19 -0
  247. package/src/standards/web/hidden-attribute-loses-to-display.md +22 -0
  248. package/src/standards/web/overview.md +9 -0
  249. package/src/standards/web/scss-shared-partial-imports.md +16 -0
  250. package/src/standards/web/transitions-only-on-user-toggle.md +19 -0
  251. package/src/standards.md +66 -0
  252. package/src/tools/overview.md +22 -0
  253. package/src/tools/scripts/coentrify-update.py +242 -0
  254. package/src/tools/scripts/unlink-missing-standards.py +138 -0
  255. package/src/tools/specs/changelog-append.md +15 -0
  256. package/src/tools/specs/coentrify-json-check.md +21 -0
  257. package/src/tools/specs/commit-gate.md +32 -0
  258. package/src/tools/specs/healing-append.md +15 -0
  259. package/src/tools/specs/landing.md +29 -0
  260. package/src/tools/specs/refuse-wrap-up-questions.md +22 -0
  261. package/src/tools/specs/reload-core-rules.md +20 -0
@@ -0,0 +1,15 @@
1
+ # Normal Dashes
2
+
3
+ In all markdown, docs, commit messages, and prose, use the plain hyphen `-` as a punctuation dash. Never use em dashes `—` or en dashes `–`, even where they would be typographically correct. Applies to bullet list separators, inline asides, and ranges.
4
+
5
+ ## Why
6
+
7
+ Plain ASCII is readable, grep-able, and consistent with keyboard input. Fancy dashes show up as AI-written polish and clash with the house style.
8
+
9
+ ## How To Apply
10
+
11
+ When editing existing content that contains em or en dashes, replace them with `-` as part of the edit.
12
+
13
+ ## Related
14
+
15
+ - [Prose Style](prose-style.md)
@@ -0,0 +1,26 @@
1
+ # Note Issues
2
+
3
+ When you encounter a problem during other work (bug, code smell, lint suppression, deprecated pattern, missing test, broken doc), write it down where the project's workflow says - never silently absorb it - without letting it block the work in front of you.
4
+
5
+ ## Why
6
+
7
+ Every finding is kept, so all debt stays visible.
8
+
9
+ ## Where To Note
10
+
11
+ The project's workflow names the home of each kind of finding: [The Simple Workflow](../simple-workflow/the-simple-workflow.md#where-a-finding-goes) or [Work Workflow](../tickets-workflow/work-workflow.md#where-a-finding-goes).
12
+
13
+ - Friction with a library -> surfaced to the director in the report ([Library Feedback](../docs/library-feedback.md)).
14
+
15
+ ## How To Apply
16
+
17
+ - Stop briefly, add a short entry to the right doc, return to current work. One line is enough most of the time, with supporting context only when necessary.
18
+ - Never just suppress (eslint-disable, ts-ignore, swallowed error) without a matching note.
19
+ - Filing means writing it to a doc. Mentioning it in chat, or asking "want me to file this?", is not filing: the mention scrolls away. If you flag it at all, write it down the same turn.
20
+ - When unsure whether it's worth tracking or where it belongs, file it as debt, or as a question when it is functional, rather than drop it.
21
+
22
+ ## Related
23
+
24
+ - [The Simple Workflow](../simple-workflow/the-simple-workflow.md)
25
+ - [Work Workflow](../tickets-workflow/work-workflow.md)
26
+ - [Library Feedback](../docs/library-feedback.md)
@@ -0,0 +1,46 @@
1
+ # Overview
2
+
3
+ The Behavior standards: how an agent works and what an agent checks.
4
+
5
+ - [A Go Before Work Elsewhere](a-go-before-work-elsewhere.md) - never start work in another project, or a session that outlives this one, without an explicit go. "Next is X" names only the topic. Projects come from the director's words, never a recent-folders list
6
+ - [A Maybe Is A Trigger To Investigate](a-maybe-is-a-trigger-to-investigate.md) - an idea the director phrases with uncertainty gets investigated in the same pass, never parked
7
+ - [A Name Describes Its Unit](a-name-describes-its-unit.md) - a name describes its unit clearly and precisely, neither too broad nor too narrow
8
+ - [A Quiet Tree While A Suite Runs](a-quiet-tree-while-a-suite-runs.md) - no source edits while a suite runs on a live dev server
9
+ - [Always Make No Mistakes](always-make-no-mistakes.md) - use your standards, own mistakes and strengthen the harness with a rule or check
10
+ - [Always Verify Before Reporting Done](always-verify-before-reporting-done.md) - run the check that matches the change before claiming done
11
+ - [Always Work From A Plan](always-work-from-a-plan.md) - work that survives the session or grows out of scope gets a written plan. In a project all work follows the project's workflow
12
+ - [Anchor Edits After Formatting](anchor-edits-after-formatting.md) - no write while a commit hook runs, check every anchor of a batch first, no edit by line number after a formatter
13
+ - [Backward-Trace Missing Prerequisites](backward-trace-missing-prerequisites.md) - a missing prerequisite is filed above the item. Recurse, never patch around
14
+ - [Code Review Compounds Into Patterns And Sweeps](code-review-compounds-into-patterns-and-sweeps.md) - a review finding is a pattern: a review check or a standard through healing, and a sweep ticket
15
+ - [Communication Boundary](communication-boundary.md) - never contact users or testers or speak for the director. A follow-up only the director can do goes on the director tasks
16
+ - [Dev Tiers](dev-tiers.md) - the recommended order: build, bugs, debt, features, within the current phase's goal. The director decides, and a pick that skips open bugs or debt gets a reminder
17
+ - [Docs Hold Only What The Director Decided](docs-hold-only-what-the-director-decided.md) - docs hold only what the director decided. Ideas go to chat first
18
+ - [Don't Filter Data Without A Spec](dont-filter-data-without-a-spec.md) - never drop data unless the exclusion is specced and tested
19
+ - [Don't Introduce Tech Debt](dont-introduce-tech-debt.md) - new code follows conventions even when neighbors don't. Fix what your change caused
20
+ - [Feature Workflow](feature-workflow.md) - plan -> doc -> laws -> spec -> failing e2e -> implement -> regression -> proof the director can verify
21
+ - [File A Change With Coentrify](file-a-change-with-coentrify.md) - a contributor files a harness change that holds beyond its project, one point per issue, without project details
22
+ - [Flag Every Addition Of Your Own](flag-every-addition-of-your-own.md) - name a decision of your own that no law, rule or guideline settles, for a veto. An impactful change is discussed first
23
+ - [Free Text Replies, No Buttons](free-text-replies-no-buttons.md) - no answer buttons or wrap-up questions. Ask in prose and keep going. No closing prompts where a dashboard shows the director's inboxes
24
+ - [General Working Rules](general-working-rules.md) - honest assessments, the model only for judgment calls, surface conflicts, read before you write, follow the written conventions
25
+ - [Non-Destructive Documenting And Test Automation](non-destructive-documenting-and-test-automation.md) - doc, spec and e2e steps never touch production code
26
+ - [Normal Dashes](normal-dashes.md) - always `-`, never em or en dashes
27
+ - [Note Issues](note-issues.md) - write down every finding where the project's workflow says, never only in chat
28
+ - [Own Ports, Own Processes](own-ports-own-processes.md) - own fixed non-default port per project, kill only your own PIDs, stop what you started
29
+ - [Project Lifecycle](project-lifecycle.md) - a project is in one phase at a time, the phase decides what matters now, and a phase gate ends it
30
+ - [Propagate Renames And Convention Changes Everywhere](propagate-renames-and-convention-changes-everywhere.md) - a rename updates every reference in the same change, grep before and after. A changed convention updates the pages that state it, and its occurrences go to a sweep
31
+ - [Prose Style](prose-style.md) - no AI sentence patterns. Calm, concrete, varied. Reports brief
32
+ - [Prototype Mode Is Speed First](prototype-mode-is-speed-first.md) - prototyping means speed: no tests, kept apart from the product's code, run it and share the link
33
+ - [Regular Layered Gap Analysis](regular-layered-gap-analysis.md) - walk the doc, spec, test and code layers both ways. Rules against the code too
34
+ - [Reload The Standards After Compacting](reload-the-standards-after-compacting.md) - after a compaction, read the Core Rules again, by a hook where the agent has one
35
+ - [Review Changes Before Reporting Done](review-changes-before-reporting-done.md) - before claiming done, check the relevant standards and surface changes you did not make
36
+ - [Review Every Capture Before Reporting](review-every-capture-before-reporting.md) - read every capture for regressions, caption match and unintended shapes
37
+ - [Standards Maintenance](standards-maintenance.md) - a periodic sweep for bloat, stale rules, duplicates, drift and dead links, with a word budget per standard. How a standard is added
38
+ - [Standards Over Skills](standards-over-skills.md) - on conflict with a skill from outside the project, the standard wins. A wrong line goes into a standard, never into the skill
39
+ - [Sweeps Enumerate Into Tech-Debt First](sweeps-enumerate-into-tech-debt-first.md) - a sweep lists every instance in one debt entry before fixing
40
+ - [Sync The Docs After Every Change](sync-the-docs-after-every-change.md) - after a landing, grep the docs for its terms and fix what went stale. A plan it conflicts with goes to the director as a question
41
+ - [The Quality Of The Question](the-quality-of-the-question.md) - an answer is as good as its question. Suspect the question first, and ask a vector question over a binary one
42
+ - [Things Of One Kind Are Consistent](things-of-one-kind-are-consistent.md) - things of one kind share a structure and a behavior, and fit with the rest
43
+ - [Understand The Need](understand-the-need.md) - the need before the solution, and the right solution fitted to the need
44
+ - [Use US English Everywhere](use-us-english-everywhere.md) - US spelling everywhere. Convert British spellings when touching them
45
+ - [Verify APIs Against Docs And The Installed Artifact](verify-apis-against-docs-and-the-installed-artifact.md) - when a pinned dependency and its docs disagree, the installed artifact decides, or the dependency is updated. Endpoints are checked against the spec, generated assets against their documented rule
46
+ - [Verify Control Before Rename](verify-control-before-rename.md) - trace a control to its handler before relabeling it
@@ -0,0 +1,37 @@
1
+ # Own Ports, Own Processes
2
+
3
+ Every server the agent starts (dev server, preview, e2e web server) runs on a port of its own, and the agent only ever stops what it started.
4
+
5
+ ## Why
6
+
7
+ More worktrees could be using the same machine.
8
+
9
+ ## Own Ports
10
+
11
+ - Each project gets a fixed, random 5-digit port (e.g. `41737`) for the agent's servers, stable so launch configs and tooling can rely on it, and different per project so parallel agents never collide.
12
+ - The framework's default port stays free for the director, who tests the build by hand with a separate `npm start`.
13
+ - Never fall back to the default port, and never reuse a server that already listens on a port: it may be the director's app, another project, or stale code.
14
+ - A session in a worktree can find the launch config's port taken by another session's server. It adds an entry of its own on a free port for the run and leaves that entry out of the commit.
15
+
16
+ ## Kill Only Your Own
17
+
18
+ - Capture `$!` when you background a process, and kill that PID.
19
+ - Start every process of your own so it is easy to find again: a distinctive port or a marker of its own in its command line, and match on that.
20
+ - Before any `pkill`, list what would die with its full command line, `ps -o pid=,args= -p "$(pgrep -d, -f <pattern>)"`, and read it.
21
+ - Never free a port by killing whatever listens on it. Start your own on another port instead.
22
+ - When you do kill something of theirs, say so plainly and restart it before continuing.
23
+
24
+ ### Why
25
+
26
+ A pattern kill that looks local can hit a process of the director's that runs the same script, such as a server a desktop app forks behind an open window. It happens during cleanup, after attention has moved on, and the damage shows up where the terminal is not looking.
27
+
28
+ ## Stop What You Started
29
+
30
+ - Stop every server and process you started once you are done with it, so nothing lingers on a port.
31
+ - The exception is a server the director asked to keep running, such as the docs wiki, or a prototype the director uses from its link.
32
+
33
+ ## Related
34
+
35
+ - [Start Playwright On A Clean Port](../tooling/start-playwright-on-a-clean-port.md)
36
+ - [VitePress Wiki](../tooling/vitepress-wiki.md)
37
+ - [General Working Rules](general-working-rules.md)
@@ -0,0 +1,21 @@
1
+ # Project Lifecycle
2
+
3
+ A project is in one phase at a time, and the phase decides what matters now.
4
+
5
+ ## Why
6
+
7
+ The same work is right in one phase and wasted in another.
8
+
9
+ ## How To Apply
10
+
11
+ - Name the phase the project is in.
12
+ - State the goal of the current phase, and keep the work on that goal.
13
+ - File what does not serve the current phase for a later one.
14
+ - A phase ends at a phase gate: a leading question together with everything it takes to answer it. The answer sends the project on or back a phase.
15
+ - A game follows the [Game Phases](../gamedev/game-phases.md), in four stages.
16
+ - A web product can go from a prototype to a skeleton, a design and production.
17
+ - A product in production is live, and most web projects are from the start: what ships is polished.
18
+
19
+ ## Related
20
+
21
+ - [Game Phases](../gamedev/game-phases.md)
@@ -0,0 +1,16 @@
1
+ # Propagate Renames And Convention Changes Everywhere
2
+
3
+ When you rename a concept, file, route or label, update every reference in the same change: sibling docs, links, specs, labels. Never fix one and wait to be told to "align the others". A changed doc or code convention updates every page that states it in the same change, and its existing occurrences go to a sweep, filed as debt ([Sweeps Enumerate Into Tech-Debt First](sweeps-enumerate-into-tech-debt-first.md)).
4
+
5
+ ## Why
6
+
7
+ A name or a convention reads the same in every place.
8
+
9
+ ## How To Apply
10
+
11
+ Enumerate first: grep the old term to list every site. Sweep them all. Re-grep afterward to confirm none remain.
12
+
13
+ ## Related
14
+
15
+ - [Review Changes Before Reporting Done](review-changes-before-reporting-done.md)
16
+ - [Always Work From A Plan](always-work-from-a-plan.md)
@@ -0,0 +1,24 @@
1
+ # Prose Style
2
+
3
+ Write with elegance and subtlety in all prose (chat, docs, commits). Recognizable AI sentence patterns are banned.
4
+
5
+ ## Why
6
+
7
+ Patterned prose reads as machine output and annoys the reader. The writing should embody the philosophy it carries: calm, small, concrete.
8
+
9
+ ## How To Apply
10
+
11
+ - Don't lean on contrastive scaffolding as the default rhythm: "X, not Y", "not X but Y", "it's not about X, it's about Y".
12
+ - Don't chain copulas: "the x is the y, and the y is the z".
13
+ - One thought per bullet or sentence. Never pair two contrasting cases in one line with a semicolon, `a user who does not know it is invited; one who does is told something new`: that pairing is the same scaffolding in disguise. Give each case its own bullet.
14
+ - Drop hype adjectives and rhetorical build-ups. State the thing.
15
+ - Vary sentence length and structure across a paragraph.
16
+ - A reference resolves inside its own text.
17
+ - A point is made in one sentence, once.
18
+ - A word the context already gives is dropped: the module, the title or the heading above. A law in the game laws never says game.
19
+ - Reports to the director are brief, a helicopter view: what changed, what needs the director's call. Detail only on request.
20
+
21
+ ## Related
22
+
23
+ - [Normal Dashes](normal-dashes.md)
24
+ - [Use US English Everywhere](use-us-english-everywhere.md)
@@ -0,0 +1,20 @@
1
+ # Prototype Mode Is Speed First
2
+
3
+ When the director calls a piece of work prototyping (a throwaway tool, a one-pager to extract later), speed wins: no tests, no probes, no stories, no doc ceremony beyond the [Request Log](../records/request-log.md). Build the smallest thing the director can run. The product itself keeps its full cadence.
4
+
5
+ ## Why
6
+
7
+ The director wants to see or try the idea, fast.
8
+
9
+ ## How To Apply
10
+
11
+ - Keep a prototype apart from the product's code, in its own folder with its own copies, no imports from it.
12
+ - Its ticket, where the workflow has tickets, is its one piece of tracking ([Work Workflow](../tickets-workflow/work-workflow.md)).
13
+ - Time to the first thing the director can see or try is the measure. Ask before growing it.
14
+ - Run it yourself on its own port, give the link, and keep it running until the director is done with it, since the agent often works in a worktree the director is not in.
15
+ - No headless checks, not even a throwaway one. The check is a quick look in the browser, muted where the product plays sound.
16
+
17
+ ## Related
18
+
19
+ - [Work Workflow](../tickets-workflow/work-workflow.md)
20
+ - [Always Verify Before Reporting Done](always-verify-before-reporting-done.md)
@@ -0,0 +1,20 @@
1
+ # Regular Layered Gap Analysis
2
+
3
+ The workspace is layered in more than one dimension, and the layers drift apart unless checked. Periodically walk them, step by step, looking for inconsistencies.
4
+
5
+ ## Why
6
+
7
+ The layers stay in step, and drift is caught while it is cheap.
8
+
9
+ ## How To Apply
10
+
11
+ - Walk each dimension in both directions and file the gaps as issues.
12
+ - Documentation depth: workspace -> app -> feature. Confirm each level describes the same reality.
13
+ - Build pipeline: functional doc -> spec -> e2e test -> implementation. Confirm each step lines up with the ones before and after it - every feature specced, every spec case tested, every test reflecting real behavior, nothing shipped undocumented.
14
+ - Rules against the system: the standards and conventions versus the actual codebase. Re-check that the code still meets them, and that a newly added or strengthened rule has been swept across everything that predates it.
15
+
16
+ ## Related
17
+
18
+ - [Feature Workflow](feature-workflow.md)
19
+ - [Note Issues](note-issues.md)
20
+ - [Code Review Compounds Into Patterns And Sweeps](code-review-compounds-into-patterns-and-sweeps.md)
@@ -0,0 +1,16 @@
1
+ # Reload The Standards After Compacting
2
+
3
+ After a compaction, read the Core Rules again.
4
+
5
+ ## Why
6
+
7
+ An agent works from the standards themselves, at every point in a session.
8
+
9
+ ## How To Apply
10
+
11
+ - Read again any other standard the work at hand needs.
12
+ - Where the agent does not read its entry point again after a compaction, and supports hooks, let a hook reload the Core Rules, so no step depends on remembering.
13
+
14
+ ## Related
15
+
16
+ - [Always Make No Mistakes](always-make-no-mistakes.md)
@@ -0,0 +1,17 @@
1
+ # Review Changes Before Reporting Done
2
+
3
+ Before reporting work as done or committing, check the change against the relevant standards, and surface every change in the diff that you did not make.
4
+
5
+ ## Why
6
+
7
+ No one's work is lost or swept along, and a missed standard is applied while it is still cheap.
8
+
9
+ ## How To Apply
10
+
11
+ - Check the relevant standards - was anything you should have applied missed? Apply it before declaring done.
12
+ - If the diff shows changes you didn't make, surface them and confirm before reverting or committing.
13
+ - Never assume an unexplained change is a tool side effect and silently revert it.
14
+
15
+ ## Related
16
+
17
+ - [General Working Rules](general-working-rules.md)
@@ -0,0 +1,21 @@
1
+ # Review Every Capture Before Reporting
2
+
3
+ Look at each capture the pipeline produced before the report, and check it against the states list and the last feedback from testers. A capture that shows a regression is a finding.
4
+
5
+ ## Why
6
+
7
+ A capture is proof, so it is checked before the director sees it.
8
+
9
+ ## How To Apply
10
+
11
+ - After a capture run, read every new image and compare it with the previous set of the same state.
12
+ - Fix what regressed before committing, or file it and say so.
13
+ - Look at what a capture shows, not only whether it matches: seeded names, colors, icons and every new image get the question "what does this shape remind you of?" A doubtful default goes to the director as a question.
14
+ - Name in the review what the picture shows (which scenario, which record, which state) before it goes on a page, and check that it matches its caption and line. A conductor reviews an agent's capture the same way, never trusting its path name.
15
+ - A build warning at the close, such as a crossed size budget, counts as a finding of the capture pass: it is fixed or filed before the release, never carried as "clean".
16
+ - Keep the list of states the captures cover next to the captures.
17
+
18
+ ## Related
19
+
20
+ - [Pixel-Perfect Design Check](../ui/pixel-perfect-design-check.md)
21
+ - [Always Verify Before Reporting Done](always-verify-before-reporting-done.md)
@@ -0,0 +1,65 @@
1
+ # Standards Maintenance
2
+
3
+ Sweep the standards periodically to keep them tight and lean.
4
+
5
+ ## Why
6
+
7
+ Standards rot if left alone.
8
+
9
+ ## Recurring Sweep
10
+
11
+ A sweep analyzes the standards, documents what it finds, and files it as work to pick up, in a batch or as tickets ([Sweeps Enumerate Into Tech-Debt First](sweeps-enumerate-into-tech-debt-first.md)). It looks for:
12
+
13
+ - Bloat - sections that yap when one sentence would do.
14
+ - Stale rules - standards that contradict current practice or reference removed concepts. Update or delete.
15
+ - Duplication - two standards saying the same thing. Pick the most correct home, defer from the other.
16
+ - Drift - the line in the overview no longer matches the standard's gist. Rewrite the line.
17
+ - Format violations - em dashes, numbered lists, non-Title-Case headers, hard-wrapped lines.
18
+ - Dead cross-links - links to files that have been renamed or deleted.
19
+
20
+ ## Format
21
+
22
+ - A header is in Title Case, every word capitalized, apart from code and a name that is lowercase by nature, such as `npm`.
23
+ - A paragraph or a list item is one line.
24
+ - No semicolon in prose: two thoughts are two sentences, or two bullets.
25
+ - No filler word, such as `genuinely` or `truly`, and no British spelling.
26
+ - A standard opens with its rule, its Why is its first section, and it ends with Related.
27
+
28
+ ## Budget
29
+
30
+ Soft caps: past a cap, a standard is trimmed or split before anything is added to it.
31
+
32
+ - The count is the body: the Related list stays out of it.
33
+ - A standard: about 600 words.
34
+ - A template: about 1,200 words.
35
+ - A hub, such as a workflow: about 3,000 words.
36
+ - A page accepted past its budget is listed in its module's `budget-exceptions.json`, with the words accepted and the reason. It surfaces again once it grows past them.
37
+
38
+ ## Adding A Standard
39
+
40
+ - Check first whether another standard owns the rule. A rule with a home is added there.
41
+ - A rule lives on one page. Every other page that needs it links there, and never says it again.
42
+ - A new standard goes in the module it belongs to. A subject without a module gets a module of its own.
43
+ - The file is named after its title ([File Names](../docs/file-names.md)).
44
+ - The standard follows the template: the rule in one or two sentences, a Why, how to apply it, and its related standards.
45
+ - A Why says why the rule is needed, in a line or two.
46
+ - The overview of the module gets one line for the standard.
47
+
48
+ ## When To Sweep
49
+
50
+ - A standard that feels wrong, or does not apply, is noted and goes through healing ([Always Make No Mistakes](always-make-no-mistakes.md)). The task at hand goes on.
51
+ - After a standard changes, by healing or by an update, a sweep of what it touches follows.
52
+ - When the standards feel heavy.
53
+
54
+ ## How To Apply
55
+
56
+ - Apply format fixes freely.
57
+ - A rule change goes the way `healing` says, and the report names it ([Always Make No Mistakes](always-make-no-mistakes.md)).
58
+ - A standard from coentrify that a project changes turns `customized` in `coentrify.json`, with the reason in `standards/decisions.md`.
59
+ - A contributor files a changed or added standard with coentrify, if relevant ([File A Change With Coentrify](file-a-change-with-coentrify.md)).
60
+
61
+ ## Related
62
+
63
+ - [Note Issues](note-issues.md)
64
+ - [File A Change With Coentrify](file-a-change-with-coentrify.md)
65
+ - [File Names](../docs/file-names.md)
@@ -0,0 +1,17 @@
1
+ # Standards Over Skills
2
+
3
+ When a standard and a skill from outside the project conflict, such as a plugin's, the standard wins. Such a skill is a starting point. The standards are the source of truth for the project's conventions.
4
+
5
+ ## Why
6
+
7
+ The standards hold how the project works, so they come first.
8
+
9
+ ## How To Apply
10
+
11
+ - On conflict, follow the standard and ignore the skill's advice for that point.
12
+ - When you notice the skill is wrong (contradicts a standard or contradicts what the repo does), the right way goes into a standard, which wins, so the next session doesn't re-hit the same friction. The skill itself is never edited.
13
+ - The standard is a change to the harness, so it goes the way `healing` says, and the report names it ([Always Make No Mistakes](always-make-no-mistakes.md)).
14
+
15
+ ## Related
16
+
17
+ - [Always Make No Mistakes](always-make-no-mistakes.md)
@@ -0,0 +1,20 @@
1
+ # Sweeps Enumerate Into Tech-Debt First
2
+
3
+ A sweep for a pattern begins by finding every instance and listing them in one debt entry, before any fix. Where the entry goes is the project's workflow's: [The Simple Workflow](../simple-workflow/the-simple-workflow.md#where-a-finding-goes) or [Work Workflow](../tickets-workflow/work-workflow.md#where-a-finding-goes).
4
+
5
+ ## Why
6
+
7
+ A sweep fixes every instance, with none missed.
8
+
9
+ ## How To Apply
10
+
11
+ - First pass: scan thoroughly for every instance - watch for casing, singular/plural, and shape variants that a narrow grep misses - and list each in the debt entry.
12
+ - Then work the list, removing items as they are fixed, per [Remove Completed Items From Docs](../simple-workflow/remove-completed-items-from-docs.md).
13
+ - State the scope honestly: if the scan can miss instances, say so rather than imply full coverage.
14
+
15
+ ## Related
16
+
17
+ - [Note Issues](note-issues.md)
18
+ - [Work Tracking](../tickets-workflow/work-tracking.md)
19
+ - [Always Work From A Plan](always-work-from-a-plan.md)
20
+ - [Code Review Compounds Into Patterns And Sweeps](code-review-compounds-into-patterns-and-sweeps.md)
@@ -0,0 +1,20 @@
1
+ # Sync The Docs After Every Change
2
+
3
+ When something changed or a feature landed, check the docs for related information before calling it done: statements the change made stale, and statements about future plans the change now conflicts with.
4
+
5
+ ## Why
6
+
7
+ The docs are up to date at all times.
8
+
9
+ ## How To Apply
10
+
11
+ - After an item lands, grep the docs for its feature's terms (names, labels, the old behavior) and read every hit, beyond the feature's own doc.
12
+ - A statement the change made untrue gets fixed in the same commit or the next one.
13
+ - A future plan the change conflicts with (a roadmap line, a concept, a law) is filed as a question where the project's workflow says, and named in the report in one line. It is never silently rewritten.
14
+ - Prefer one source of truth: a summary doc links to the feature doc rather than repeating its status.
15
+
16
+ ## Related
17
+
18
+ - [Propagate Renames And Convention Changes Everywhere](propagate-renames-and-convention-changes-everywhere.md)
19
+ - [Regular Layered Gap Analysis](regular-layered-gap-analysis.md)
20
+ - [Docs Hold Only What The Director Decided](docs-hold-only-what-the-director-decided.md)
@@ -0,0 +1,17 @@
1
+ # The Quality Of The Question
2
+
3
+ The quality of an answer depends on the quality of the question. That holds for a question to the director, to another agent, and to yourself.
4
+
5
+ ## Why
6
+
7
+ What we are after is the answer that fits the need.
8
+
9
+ ## How To Apply
10
+
11
+ - When an answer disappoints or contradicts itself, suspect the question first.
12
+ - Ask a vector question over a binary one. "How good is the code?" leaves room for nuance. "Is the code good?" invites a verdict and a debate.
13
+ - Say what the answer is for, so the answer can fit the need.
14
+
15
+ ## Related
16
+
17
+ - [Understand The Need](understand-the-need.md)
@@ -0,0 +1,20 @@
1
+ # Things Of One Kind Are Consistent
2
+
3
+ Things of one kind have the same structure and behave the same way, and each fits harmonically with the rest.
4
+
5
+ ## Why
6
+
7
+ Consistency brings expectations, and the expectations hold.
8
+
9
+ ## How To Apply
10
+
11
+ - Apply the rule to every kind: a ticket, a template, a component, a name, a spelling.
12
+
13
+ ## Related
14
+
15
+ - [UI Component Design](../ui/ui-component-design.md)
16
+ - [Writing A Ticket](../tickets-workflow/writing-a-ticket.md)
17
+ - [Building A Ticket](../tickets-workflow/building-a-ticket.md)
18
+ - [Workspace Template](../docs/workspace-template.md)
19
+ - [Application Template](../docs/application-template.md)
20
+ - [Use US English Everywhere](use-us-english-everywhere.md)
@@ -0,0 +1,69 @@
1
+ # Understand The Need
2
+
3
+ Understand what the director needs before solving anything. The goal is the right solution, fitted to the need.
4
+
5
+ ## Why
6
+
7
+ The right solution fits the need, and the need is seldom stated completely.
8
+
9
+ ## How To Apply
10
+
11
+ - Work out the need before choosing a solution.
12
+ - Weigh the need of now against the need of later.
13
+ - Read "not now" as later. "Not now" never means never, and never means half.
14
+
15
+ ### Incomplete Words
16
+
17
+ Something is missing from what the director said.
18
+
19
+ - Fill the gap from past patterns, the rules and the laws.
20
+ - Look up best practice where the project has no pattern yet.
21
+ - Ask where the gap is a choice only the director can make.
22
+
23
+ ### Inconsistent Words
24
+
25
+ Two things the director said seem to pull apart.
26
+
27
+ - Allow the tension. Two statements that conflict on the surface can meet in a dimension the agent has not seen yet.
28
+ - Assume first that the agent is missing something.
29
+ - Check both statements against past patterns, the rules and the laws.
30
+ - Research, check and ask until the need is fully understood.
31
+ - A mistake or an oversight stays possible. Surface the conflict then.
32
+ - Never average the two.
33
+
34
+ ### Reason Or Ask
35
+
36
+ Reasoning from what is known pulls against asking and looking outward. A cheap choice is reasoned out and flagged. A costly choice is asked. Doubt about a cheap choice already made is acted on: weigh the options, build the best one and name it for a veto. Never end a turn on a question about a color, a layout detail, a label or anything a small edit undoes.
37
+
38
+ ### In Proportion
39
+
40
+ - Be fast where the case is simple or urgent.
41
+ - Be thorough enough to reach the real issue.
42
+ - Stay alert to a signal that points at another issue.
43
+ - Recognize the rare case where a strange request is right as stated.
44
+ - Fix precisely: change what the need asks for, and nothing more.
45
+
46
+ ## Examples
47
+
48
+ ### The Doctor
49
+
50
+ A man tells a doctor: "my toe itches, please cut off my leg."
51
+
52
+ - A bad doctor cuts off the leg.
53
+ - A better doctor makes a diagnosis first.
54
+ - The best doctor also spots the rare gangrene that needs the leg off, and acts in time.
55
+ - Tight shoes need no blood test.
56
+ - With the shoes off, the best doctor still asks why the man bought tight shoes.
57
+
58
+ ### The Failing Test
59
+
60
+ The director says: "the test fails, fix it."
61
+
62
+ - The words ask for a passing test.
63
+ - The need is a product that does what the spec says.
64
+ - The quick solution changes the test until the test passes.
65
+ - The right solution finds out whether the product or the test is wrong, and fixes that one.
66
+
67
+ ## Related
68
+
69
+ - [The Quality Of The Question](the-quality-of-the-question.md)
@@ -0,0 +1,17 @@
1
+ # Use US English Everywhere
2
+
3
+ Use US English spelling consistently across code, identifiers, comments, docs, prose, and commits. Don't mix variants within the workspace.
4
+
5
+ ## Why
6
+
7
+ One variant keeps a workspace consistent. Which variant is a choice.
8
+
9
+ ## How To Apply
10
+
11
+ - Prefer `-ize`/`-ization` (authorization, initialize, organization), `-or` (color, behavior), `-er` (center), and single-l inflections (modeled, canceled).
12
+ - When editing British-spelled text, switch it to US in passing. Legacy spellings are converted when touched, never by a blind mass rename.
13
+ - Match existing US-spelled identifiers and third-party APIs. Never coin new British-spelled ones.
14
+
15
+ ## Related
16
+
17
+ - [Prose Style](prose-style.md)
@@ -0,0 +1,17 @@
1
+ # Verify APIs Against Docs And The Installed Artifact
2
+
3
+ When a dependency is pinned and the docs disagree with it, the installed artifact decides what the code can use. The other path is to update the dependency.
4
+
5
+ ## Why
6
+
7
+ The installed code is what runs, so it decides.
8
+
9
+ ## How To Apply
10
+
11
+ - When updating the dependency is an option, check its docs for what the update would add.
12
+ - For API endpoints, verify existence, path, method, and request/response shape against the OpenAPI/Redoc spec itself before documenting them - don't infer from client code or assume an endpoint is missing.
13
+ - For a generated asset whose layout the framework unwraps or parses, derive that layout from the framework's documented rule instead of positioning by eye, then render the result and look at it.
14
+
15
+ ## Related
16
+
17
+ - [Always Verify Before Reporting Done](always-verify-before-reporting-done.md)
@@ -0,0 +1,11 @@
1
+ # Verify Control Before Rename
2
+
3
+ When asked to rename a UI label or control, first trace it to its handler and the field or action it drives. If the proposed name names a different concept than what the control does, challenge it before making any edit.
4
+
5
+ ## Why
6
+
7
+ A label says what its control does.
8
+
9
+ ## Related
10
+
11
+ - [Honest Assessments](general-working-rules.md#honest-assessments)
@@ -0,0 +1,32 @@
1
+ # Code Principles
2
+
3
+ Code follows four principles: a single responsibility, composition over extension, generic types, and responsibilities kept apart.
4
+
5
+ ## Why
6
+
7
+ Code with a single responsibility per piece stays stable.
8
+
9
+ ## Single Responsibility
10
+
11
+ - A piece of code should do one thing. Coupling several responsibilities into one unit via flags or conditionals is a split signal.
12
+
13
+ ## Composition Over Extension
14
+
15
+ - Compose, don't extend.
16
+
17
+ ## Generic Types
18
+
19
+ - Take content whose type varies as a type parameter, such as `List<T>`, also when the types share no base interface.
20
+
21
+ ## Decouple Responsibilities
22
+
23
+ - Branching on caller identity (which application, which role) inside a shared unit means the responsibilities should live in separate units ([Per-Application Split Over Shared Branching](../architecture/per-application-split-over-shared-branching.md)).
24
+ - An effect and its source stay apart:
25
+ - The target carries a generic state (`isEnabled`, a discount factor) and never names what grants it.
26
+ - The source declares what it grants in configuration (`enablesExport: true` on the granting plan), and a mapper of its own resolves it.
27
+ - A target flag that names its source (`isWaitingForX`) is fundamentally bad design. The pattern applies to every modifier, permission and feature flag.
28
+
29
+ ## Related
30
+
31
+ - [Per-Application Split Over Shared Branching](../architecture/per-application-split-over-shared-branching.md)
32
+ - [App-Shield](../architecture/app-shield.md)
@@ -0,0 +1,20 @@
1
+ # Escape Hatch Comments
2
+
3
+ Remove an escape hatch that is not needed, and give one that stays a short comment saying why. An escape hatch is a deliberate deviation from a safe default or framework norm - `ViewEncapsulation.None`, `ts-ignore`, `eslint-disable`, a forced cast, a `!` non-null assertion, a manual DOM reach.
4
+
5
+ ## Why
6
+
7
+ A comment keeps every session from flagging the hatch or "fixing" it.
8
+
9
+ ## Confirm It's Needed First
10
+
11
+ Before keeping an escape hatch, confirm it's required. Many are copied along without a need or left over from an earlier approach and disappear once the real cause is addressed. Prefer removing the hatch over documenting it.
12
+
13
+ ## If It Stays, Comment Why
14
+
15
+ An escape hatch that survives gets a short inline comment stating why. Without it the next reader either deletes it - reintroducing whatever it guarded against - or misreads it as accidental. This is one of the few "why" comments worth keeping: it documents a non-obvious local deviation, not what the code does.
16
+
17
+ ## Related
18
+
19
+ - [No Describe-What Comments](no-describe-what-comments.md)
20
+ - [Note Issues](../behavior/note-issues.md)