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,72 @@
1
+ # coentrify.json
2
+
3
+ One file at the root of a project says how the project uses coentrify.
4
+
5
+ - The File - what it holds
6
+ - States - how a project follows a standard
7
+ - Versions - how a change is found
8
+ - The Check - what keeps the file true
9
+
10
+ ## The File
11
+
12
+ The onboarding writes `coentrify.json`, and the director changes it after.
13
+
14
+ ```json
15
+ {
16
+ "source": "https://github.com/coentrify/coentrify",
17
+ "package": "coentrify",
18
+ "version": "0.1.0",
19
+ "folders": { "docs": "docs", "standards": "standards" },
20
+ "workflow": "simple",
21
+ "records": ["changelog", "healing-log"],
22
+ "wiki": "vitepress",
23
+ "healing": "automatic",
24
+ "modules": {
25
+ "behavior": {
26
+ "always-make-no-mistakes": "tracked",
27
+ "understand-the-need": "customized"
28
+ }
29
+ }
30
+ }
31
+ ```
32
+
33
+ - `source` - the repository the standards came from, so a version of coentrify of your own works the same way
34
+ - `package` - the npm package that carries the source, installed as a dev dependency: `coentrify`, or the name a version of your own is published under
35
+ - `version` - the version of coentrify the project is at
36
+ - `folders` - where the docs and the standards live
37
+ - `workflow`, `records`, `wiki` - the choices from the onboarding
38
+ - `workflow` is `simple` or `tickets`
39
+ - `records` lists each record kept by its place under `docs/records/`: `log`, `activity`, `changelog`, `healing-log`, `playtests`, `user-tests`
40
+ - `modules` - every standard taken from coentrify, by module, with its state
41
+ - `healing` - who makes a harness change: `automatic` by default, where a subagent makes it, logs it in the healing log and the report names it for a veto, or `review`, where it is filed for the director
42
+ - `contributor` - left out by default. Set to `true`, the project may file changes at the source.
43
+ - `filing` - for a contributor: `review` by default, where the director looks at an issue before it is filed at the source, or `automatic`, where the subagent files it on its own
44
+ - `libraries` - left out by default. Each library the project contributes to, by name, with its `source` and a `filing` of its own, as above ([Library Feedback](standards/docs/library-feedback.md))
45
+
46
+ A module whose standards come from somewhere else can carry a `source` of its own.
47
+
48
+ ## States
49
+
50
+ - `tracked` - an update replaces the file
51
+ - `customized` - an update reports the changes
52
+
53
+ A tracked standard that is changed by hand becomes customized. So does a standard whose update the director declines. The reason goes in `standards/decisions.md`.
54
+
55
+ A standard the project wrote itself is not listed. It goes in the module it belongs to, beside the standards from coentrify, so the links and the index keep working. A subject coentrify does not cover yet, such as React, gets a module of its own.
56
+
57
+ ## Versions
58
+
59
+ Coentrify has one version, and a project is at one version. The [changelog](changelog/overview.md) names every standard that a version changed.
60
+
61
+ A standard the changelog does not name needs no attention.
62
+
63
+ ## The Check
64
+
65
+ A check built from its spec in the [tools](tools/overview.md) keeps the file true.
66
+
67
+ - A folder the file names has to exist.
68
+ - A standard the file lists has to be on disk.
69
+ - A state is `tracked` or `customized`.
70
+ - `healing` and `filing` are `automatic` or `review`, and `filing` stands only beside `contributor: true`.
71
+
72
+ With `--staged`, as a pre-commit step, the check also refuses a commit that changes a tracked standard by hand. The commit passes once the state is `customized`, or when the commit changes the version, as an update does.
@@ -0,0 +1,48 @@
1
+ # Commands
2
+
3
+ What a director can ask an agent to do with coentrify. A command is matched by intent, so the exact words do not matter.
4
+
5
+ In a fresh project the first prompt is `npx coentrify`, as the [Quick Start](readme.md#quick-start) shows. Once the project is set up, its entry point leads to these commands.
6
+
7
+ - `coentrify` - set the project up with the director in the loop: the agent recommends, and the director chooses
8
+ - `coentrify make no mistakes` - set the project up autonomously: the agent chooses, and the director vetoes afterward
9
+ - `coentrify explain` - say what coentrify is
10
+ - `coentrify update` - bring the project up to date
11
+
12
+ An agent shows the greeting from the [onboarding](onboarding.md) before any command.
13
+
14
+ ## `coentrify`
15
+
16
+ Any request to set the project up. Follow the [onboarding](onboarding.md).
17
+
18
+ ## `coentrify make no mistakes`
19
+
20
+ The onboarding, run autonomously. The agent answers each of the onboarding's questions itself, from its analysis of the project. Every choice the agent made is listed afterward, for the director to veto.
21
+
22
+ The agent starts with this line:
23
+
24
+ ```
25
+ coentrifying. making no mistakes.
26
+ ```
27
+
28
+ ## `coentrify explain`
29
+
30
+ Any question about what coentrify is. Explain from the [readme](readme.md), the [philosophy](philosophy.md) and [how it works](how-it-works.md).
31
+
32
+ ## `coentrify update`
33
+
34
+ Any request to bring the project up to date. The update script from the [tools](tools/overview.md) works out what changed since the project's version, and the agent handles what needs judgment.
35
+
36
+ - Raise coentrify to its latest version, `npm install --save-dev coentrify@latest`.
37
+ - Run the update script from the installed package for the plan, `python3 node_modules/coentrify/src/tools/scripts/coentrify-update.py`, and read the [changelog](changelog/overview.md) from the project's version on. The script fetches the project's version from npm to compare with.
38
+ - A project from before 0.1.0 sets coentrify up again, the way the [onboarding](onboarding.md#an-earlier-coentrify) says for an earlier coentrify.
39
+ - Read `standards/decisions.md` for the reasoning behind the earlier choices.
40
+ - Show the director a changed rule in a tracked standard before it is replaced.
41
+ - A standard whose update the director declines is set to `customized` first, with the reason in the decisions.
42
+ - Run it again with `--apply`, which replaces the tracked standards and their overview lines, and writes the new version.
43
+ - Run the unlink script again, since a replaced standard brings its links back.
44
+ - Rebuild each check or helper whose spec the plan names as changed.
45
+ - Apply each setup change the changelog names since the project's version, the way the onboarding now reads.
46
+ - Report the changes for a customized standard, and a standard renamed, moved or removed at the source.
47
+ - Report new standards worth considering, and surface one that has the same name as one of the project's own.
48
+ - Update the decisions.
@@ -0,0 +1,132 @@
1
+ # Glossary
2
+
3
+ The terms coentrify uses most, each described in plain words.
4
+
5
+ - The People - who does what
6
+ - The System - what a project adopts
7
+ - The Work - how a piece of work is specified, built and accepted
8
+ - Keeping It Right - how differences are found and fixed
9
+
10
+ ## The People
11
+
12
+ ### Director
13
+
14
+ The human in charge of a project. The director decides what is built and in what order, and accepts or rejects the result ([How It Works](how-it-works.md#the-director)).
15
+
16
+ ### Agent
17
+
18
+ An AI model that does the work of a project: it writes the documentation, the tests and the code.
19
+
20
+ ## The System
21
+
22
+ ### Spec-Driven Development
23
+
24
+ A way of working in which what is wanted is written down and specified before it is built, and what is built is checked against what was written ([Spec-Driven Development](readme.md)).
25
+
26
+ ### Standard
27
+
28
+ A written rule, convention or template that a project adopts. Every standard is one file ([Standards](standards.md)).
29
+
30
+ ### Module
31
+
32
+ A folder of standards on one subject, such as Docs or Tests.
33
+
34
+ ### Core Rules
35
+
36
+ The rules every task follows, in every session. An agent loads them at the start of each session ([Overview](standards/overview.md)).
37
+
38
+ ### Check
39
+
40
+ An automated test of a rule: a script, a lint rule or a hook that fails when the rule is broken.
41
+
42
+ ### Harness
43
+
44
+ Everything that guides and limits the work of an agent: the standards, the checks and the tools ([Always Make No Mistakes](standards/behavior/always-make-no-mistakes.md)).
45
+
46
+ ### Coentrify
47
+
48
+ The harness described on these pages. As a verb: to set a project up with it ([Origin](origin.md)).
49
+
50
+ ### Pillar
51
+
52
+ One of the four principles behind the system: Specs & Checks, Layering, Harmony and Shepherding ([Philosophy](philosophy.md)).
53
+
54
+ ### Law
55
+
56
+ A short rule about the product that holds unless there is a very good reason to break it. The design rules of a game are laws ([Game Design Laws](standards/gamedev/game-design-laws.md)).
57
+
58
+ ### Why
59
+
60
+ The section of a standard that says why its rule is needed.
61
+
62
+ ### Part Page
63
+
64
+ A standard that holds one part of a larger standard. Its title starts with the title of the larger standard, followed by a colon.
65
+
66
+ ## The Work
67
+
68
+ ### Use Case
69
+
70
+ The smallest complete flow in a product: one thing a user does, from a start state to a result. A feature consists of several use cases.
71
+
72
+ ### Spec
73
+
74
+ Short for specification: what is wanted, written down, at any level. A feature doc's statements, a feature's use cases and a ticket's criteria are each a spec. The feature spec lists a feature's use cases, each written out as steps, and every use case has an id of its own, renamed everywhere at once when it changes ([Feature Spec Template](standards/docs/feature-spec-template.md)).
75
+
76
+ ### Layer
77
+
78
+ One level of description of a product. From general to specific, the layers are the docs, the specs, the tests and the code.
79
+
80
+ ### Proof
81
+
82
+ Evidence that the director can verify without reading code: a screenshot, a video, a test run or steps to try ([The Done Part](standards/tickets-workflow/the-done-part.md)).
83
+
84
+ ### Go
85
+
86
+ The director's explicit approval to build ready work: by a ticket's or a story's id, or in one word for all that is ready ([Work Workflow](standards/tickets-workflow/work-workflow.md#the-go)). Work in another project, or a session that outlives this one, needs a go of its own ([A Go Before Work Elsewhere](standards/behavior/a-go-before-work-elsewhere.md)).
87
+
88
+ ### Pass
89
+
90
+ One stretch of an agent's work on a request, from taking it up to reporting it. Done in the same pass means done before the report, with no new go needed.
91
+
92
+ ### Maybe
93
+
94
+ An idea the director phrases with uncertainty. An agent investigates it at once and reports the outcome ([A Maybe Is A Trigger To Investigate](standards/behavior/a-maybe-is-a-trigger-to-investigate.md)).
95
+
96
+ ### Veto
97
+
98
+ The director's rejection of a choice that an agent made on its own. An agent lists such choices in its report ([Flag Every Addition Of Your Own](standards/behavior/flag-every-addition-of-your-own.md)). A ticket's Veto section lists those choices.
99
+
100
+ ### Phase
101
+
102
+ The stage of development a project is in, such as prototype or production. The phase determines which work has priority ([Project Lifecycle](standards/behavior/project-lifecycle.md)).
103
+
104
+ ### Phase Gate
105
+
106
+ The test that ends a phase: a leading question together with everything it takes to answer it ([Project Lifecycle](standards/behavior/project-lifecycle.md)).
107
+
108
+ ## Keeping It Right
109
+
110
+ ### Gap
111
+
112
+ A difference between two layers: something that one layer states and the other lacks. A use case without a test is a gap.
113
+
114
+ ### Gap Analysis
115
+
116
+ To compare two layers and find the differences and discrepancies between them, the delta ([Regular Layered Gap Analysis](standards/behavior/regular-layered-gap-analysis.md)).
117
+
118
+ ### Drift
119
+
120
+ A difference that grows over time, because one layer or rule changed and the related one was not updated.
121
+
122
+ ### The Loop
123
+
124
+ The self-healing feedback cycle of the system. A mistake or a gap that is caught gets fixed twice: once in the work, and once in the harness, as a standard or a check. Round after round the system stabilizes, and adapts to its director, its agents and its project ([How It Works](how-it-works.md#the-loop)).
125
+
126
+ ### Sweep
127
+
128
+ To apply one rule to every existing instance in a project: find all instances, list them, then fix them ([Sweeps Enumerate Into Tech-Debt First](standards/behavior/sweeps-enumerate-into-tech-debt-first.md)).
129
+
130
+ ### Focus Level
131
+
132
+ The level of detail a page is written at, such as a workspace, an application or a feature. A page summarizes the levels next to it and leaves their details to their own pages. Also called altitude or level of awareness ([Docs Are Hierarchical, Explicit And Short](standards/docs/docs-are-hierarchical-explicit-and-short.md)).
@@ -0,0 +1,51 @@
1
+ # How It Works
2
+
3
+ How the system turns any input into what you want.
4
+
5
+ ## The Quality Factory
6
+
7
+ Coentrify is a funnel and a quality transformer.
8
+
9
+ - The funnel gathers every input, in any quality and any language.
10
+ - The system turns the input into layers: docs, specs and tests.
11
+ - The work turns the layers into output.
12
+
13
+ Together with the pillars, the funnel and the transformer form a quality factory. What comes out is what you want.
14
+
15
+ ## The Quality Of The Question
16
+
17
+ The quality of an answer depends on the quality of the question.
18
+
19
+ Coentrify is a collection of carefully curated questions and statements. The collection works as a pre-prompt: an agent reads the collection before the prompt, so a simple prompt still gets a quality answer.
20
+
21
+ Inside a coentrified project, a one-word prompt works for the same reason, such as a go: the questions were already asked, in writing.
22
+
23
+ ## The Compass
24
+
25
+ A good system extracts only what the system needs from the director. The vision, the pillars and the laws are the compass. With a direction and a way to steer around obstacles, nobody has to provide the complete route.
26
+
27
+ ## The Loop
28
+
29
+ A gap or a mistake goes back into the funnel as input. The fix becomes a standard or a check, so the factory gets better with every round ([Standards](standards.md)).
30
+
31
+ ## The Work
32
+
33
+ The director decides what gets built. The agent works from the specs, one use case at a time. A test is written first, and fails. The agent builds until the test passes and every check runs clean.
34
+
35
+ The agent settles the easy choices and lists them for the director to veto. The director looks at the proof and decides whether the work is done.
36
+
37
+ ## The Director
38
+
39
+ The director is the human who directs the project. The director has three responsibilities in the work, and three around the work.
40
+
41
+ ### In The Work
42
+
43
+ - Specify - explain, refine and answer questions
44
+ - Plan - choose what comes next and what comes later
45
+ - Accept - check the proof
46
+
47
+ ### Around The Work
48
+
49
+ - Steer - set the vision, and direct how the system heals and personalizes itself
50
+ - Own - answer for the result and for everything that touches the outside world
51
+ - Provide - give the agents access, tools and a budget
@@ -0,0 +1,140 @@
1
+ # Onboarding
2
+
3
+ How an agent sets coentrify up in a project. Every step follows one pattern: a default, a choice, an override.
4
+
5
+ - Greet - show that the prompt worked
6
+ - Analyze - read the project and what is already there
7
+ - Recommend - the defaults for this project
8
+ - Choose - the director accepts, picks or overrides
9
+ - Set Up - put the chosen parts in the project
10
+ - Report - the choices, open to a veto
11
+
12
+ ## Greet
13
+
14
+ Greet the director first, so the director sees that the prompt worked.
15
+
16
+ ```
17
+ ████ ███ █████ █ █ █████ ████ ███ █████ █ █
18
+ █ █ █ █ ██ █ █ █ █ █ █ █ █
19
+ █ █ █ ████ █ █ █ █ ████ █ ████ █
20
+ █ █ █ █ █ ██ █ █ █ █ █ █
21
+ ████ ███ █████ █ █ █ █ █ ███ █ █
22
+ Humans direct. Systems check. Agents work.
23
+ ```
24
+
25
+ ## Analyze
26
+
27
+ Read the project before asking anything.
28
+
29
+ - The stack, such as Angular or Godot, shows which modules are relevant.
30
+ - The docs, the tests and how the work is tracked show where the project stands.
31
+ - The instructions that already exist: project memories, user memories and rule files.
32
+ - An earlier version of coentrify, where the project has one.
33
+
34
+ ### What Is Already There
35
+
36
+ - Nothing of the project's own is overwritten.
37
+ - A conflict between an existing instruction and a standard is surfaced.
38
+ - Every conflict is resolved before the set up.
39
+
40
+ ### An Existing Project
41
+
42
+ An existing project does not get all its specs and tests written first.
43
+
44
+ - New work is specified and tested from the first day.
45
+ - Existing parts are documented when the work touches them.
46
+ - A conflict or a question about the product is surfaced for the stakeholders.
47
+
48
+ ### An Earlier Coentrify
49
+
50
+ Older copies of coentrify are in use, and some have grown into a version of their own. An earlier copy is noted and surfaced to the director.
51
+
52
+ - The current coentrify is adopted in full, and replaces the earlier copy.
53
+ - The project's own additions are analyzed one by one.
54
+ - An addition that still fits goes on top of the current standards.
55
+ - An addition that the update made irrelevant is listed for removal.
56
+
57
+ ## Recommend
58
+
59
+ Every choice has a default, and the default is the recommendation. The [recommendations](recommendations.md) list the defaults and what to weigh for each.
60
+
61
+ - The Always modules in the recommendations are recommended for every project, starting with [Always Make No Mistakes](standards/behavior/always-make-no-mistakes.md).
62
+ - A stack module is recommended when the analysis finds the stack.
63
+ - A specific module, such as the game design laws, is picked by the director.
64
+ - A standard for one kind of project is picked by its title or its Relevant For list.
65
+ - Adoption grows with the phase: an idea takes the Always modules and a workflow, and the stack modules join once it is built.
66
+ - A standard that an adopted standard links to, in a module the project did not pick, is offered as an option.
67
+ - A workflow is strongly recommended, since tracking the work is part of coentrify.
68
+ - Healing is automatic, and for a contributor, filing with coentrify waits for the director.
69
+
70
+ ## Choose
71
+
72
+ The agent shows the recommendations as one short list. The director accepts a default, picks another option, or overrides with something of the project's own.
73
+
74
+ With `coentrify make no mistakes` the agent asks nothing. The agent takes every recommendation, and makes a best guess where there is none. A conflict is settled the same way, and listed in the report.
75
+
76
+ ## Set Up
77
+
78
+ - Install coentrify as a dev dependency, `npm install --save-dev coentrify`, so its source sits in the project, in `node_modules/coentrify/src`. A project without a `package.json` gets one.
79
+ - Copy the chosen standards into the `standards` folder of the project, in the same module folders, so the standards sit beside the code.
80
+ - Remove or change every link to a standard the project did not adopt.
81
+ - Write the index.
82
+ - Point the entry point at the index.
83
+ - Add the session check.
84
+ - Write `coentrify.json`.
85
+ - Write the decisions.
86
+ - Set up the `docs` folder.
87
+ - Create the wiki, where chosen.
88
+ - Switch off the agent's own commit attribution where it has a setting for it ([Commits](standards/commits/commits.md#no-attribution)).
89
+ - Build the checks and hooks the chosen standards ask for, in the project's own stack, from their specs in the [tools](tools/overview.md).
90
+ - Offer a setup script for personal content, where the director uses cloud sessions.
91
+
92
+ ### The Links
93
+
94
+ A link to a standard the project did not adopt points at nothing. The unlink script from the [tools](tools/overview.md) removes every such link and keeps the words, and drops the line of such a standard from its overview.
95
+
96
+ ### The Index
97
+
98
+ `standards/overview.md` lists the adopted modules, and every module has an overview of its own standards, with one line each. An agent reads a module's overview, and then a standard, when the work calls for it.
99
+
100
+ ### Core Rules
101
+
102
+ The index opens with the Core Rules: the rules every task follows, in every session, read before anything else and held to like a check. The list starts with the core rules of coentrify. A project adds standards of its own to the list, and can take one off.
103
+
104
+ ### The Entry Point
105
+
106
+ The entry point is the file an agent reads when a session starts, such as `AGENTS.md` or `CLAUDE.md`. The entry point gets one line that points at the index and at the commands in the installed package, `node_modules/coentrify/src/commands.md`, and holds no standards itself. A project without an entry point gets an `AGENTS.md`.
107
+
108
+ Where the agent can import a file, such as with `@` in `CLAUDE.md`, the entry point imports the index and every standard in the Core Rules, so they load without being asked for, in every agent and subagent.
109
+
110
+ The entry point also says to read the Core Rules again after a compaction. An agent that reads its entry point again after a compaction, its imports included, as Claude Code does, needs nothing more. Elsewhere, where the agent supports hooks, a reload hook does it, built from its spec in the [tools](tools/overview.md).
111
+
112
+ ### The Session Check
113
+
114
+ Every session starts with `coentrify check`. It says when `coentrify.json` is behind the installed coentrify, and what changed in between, and it never blocks.
115
+
116
+ - Where the agent has a session start hook, such as Claude Code, the hook runs the check through the project's npm scripts ([Thin Wrappers In CI And Hooks](standards/scripts/thin-wrappers-in-ci-and-hooks.md)).
117
+ - Elsewhere, the entry point asks for the check at the start of a session.
118
+ - A session that starts without `node_modules`, such as one in a fresh cloud container, runs `npm install` first, and the entry point says so.
119
+
120
+ ### The Coentrify File
121
+
122
+ `coentrify.json` holds the choices, the version and the state of every standard ([coentrify.json](coentrify-json.md)). Where the project has a pre-commit hook, a check built from its spec in the [tools](tools/overview.md) keeps the file true.
123
+
124
+ ### The Decisions
125
+
126
+ `standards/decisions.md` holds the reasoning behind the choices, in free form: why a standard was adopted or customized, and what to revisit later, such as a module to adopt once the project switches stack.
127
+
128
+ ### Personal Content
129
+
130
+ What is personal to the director, such as a role or a tone, stays out of the project. The standards travel with the repository, so a cloud session has all of them. For personal content in a cloud session, a setup script in the director's cloud environment writes a personal instructions file.
131
+
132
+ ### The Wiki
133
+
134
+ The wiki serves the docs and the standards as pages, so the director can read everything in one place. VitePress is recommended, or a similar tool that builds a site from markdown.
135
+
136
+ ## Report
137
+
138
+ Report briefly: the choices that were made, and what was set up. The director stays in control, and can veto or change every choice.
139
+
140
+ A star on GitHub is the only sign that coentrify is in use. Mention it once, and leave it to the director.
package/src/origin.md ADDED
@@ -0,0 +1,19 @@
1
+ # Origin
2
+
3
+ Where the verb comes from, why the verb stayed, and where the three layers come from.
4
+
5
+ ## The Verb
6
+
7
+ Coentrify comes from Coen, the author, and his habit of structuring and organizing everything, seemingly to excess. His brother coined the verb as a lighthearted joke, with judgment for the excess and respect for the results.
8
+
9
+ ## One Word
10
+
11
+ The verb stayed because one word does the job. `coentrify` is easy to type, easy to remember, and unusual enough to be easy to find.
12
+
13
+ ## The Intention
14
+
15
+ The intention is one word that both names the goal and starts the work. Coentrified should mean a well-organized, structured and harmonious codebase.
16
+
17
+ ## Adopt, Configure, Customize
18
+
19
+ The pattern comes from StandardKit, an open source project of standardized tooling with the guardrails built in. StandardKit came in three layers: defaults that just work, configs to choose a flavor, and overrides to customize. Coentrify carries the same three layers from tooling to a whole way of working. StandardKit itself is no longer maintained.
@@ -0,0 +1,99 @@
1
+ # Philosophy
2
+
3
+ The concepts that shape the system.
4
+
5
+ ## The Pillars
6
+
7
+ The four principles the system rests on.
8
+
9
+ - Specs & Checks
10
+ - Layering
11
+ - Harmony
12
+ - Shepherding
13
+
14
+ ## Specs & Checks
15
+
16
+ Specs & Checks is a claim paired with its proof. What is wanted gets documented and specified first. What is built gets shown, and checked against what was written. Done means demonstrated.
17
+
18
+ The writing lives with the work. The docs sit beside the code, and the standards sit beside the project. A wiki shows all of it as one readable whole.
19
+
20
+ - Write before building
21
+ - Every case verified
22
+ - Demos over status reports
23
+ - Knowledge filed where it belongs
24
+
25
+ ## Layering
26
+
27
+ Layering is structure in small, dedicated pieces. Layering starts from single responsibility: one piece, one job. A small piece is easier to check and harder to get wrong, and a small piece gives focus.
28
+
29
+ Every layer rests on the layer below, and is made solid before the next layer goes on top. The same shape repeats at every scale, from a whole project down to a single page.
30
+
31
+ Two layers can be held against each other. A gap between the two shows what is missing.
32
+
33
+ - One purpose per file
34
+ - One step per change
35
+ - Prerequisites before features
36
+ - Layers checked against each other
37
+ - Converge only once proven
38
+
39
+ ## Harmony
40
+
41
+ Harmony is tension held in balance. Two forces pull in opposite directions, and neither wins. A suspension bridge stands because of tension, and so does a project.
42
+
43
+ The tension lives between standards and inside them: brevity pulls at completeness, and strictness pulls at pragmatism. Creative humans pull toward change, and rigid systems pull toward what was written. Agents do the work in between, held by both.
44
+
45
+ Keep both sides of a tension. Fine-tune the balance between them, and weigh how far the tuning goes. Dropping one side breaks the bridge, and averaging the two produces mush.
46
+
47
+ - Conflicts surfaced and settled
48
+ - Deliberate trade-offs
49
+
50
+ ## Shepherding
51
+
52
+ Shepherding is guidance built into the environment. Work takes the shape of its environment, so guardrails in the way of working make the right move the obvious move.
53
+
54
+ The strongest guardrail is an example. An agent repeats what the agent reads, so every page follows the rules the page states. The docs of the system are written by the system's own standards.
55
+
56
+ A rule followed everywhere stops needing attention. The rule becomes a habit, and the habit becomes character.
57
+
58
+ Strictness is a kindness: every removed choice removes a debate, and then a mistake. An agent wants to produce, and a guardrail makes the agent wait until the director knows what is wanted. A fence that lives in one head fades, so every fence is written down.
59
+
60
+ A rule can still be broken. A rule is called a rule because a suggestion was skipped too easily, so breaking the rule stays possible and gets harder. As agents grow, the strictness can fade. The strictness of a rule is a tension too, held in balance like every other.
61
+
62
+ - Lead by example
63
+ - Conventions enforced by tooling
64
+ - Written ways of working
65
+ - Strict defaults
66
+ - One obvious path per task
67
+ - Sweeps that bring old work in line with a new rule
68
+
69
+ ## The Pillars Together
70
+
71
+ The four pillars work through each other.
72
+
73
+ Specs layered on docs can be verified against each other. The difference between the two layers is the tension and the harmony in one.
74
+
75
+ - Layering gives Specs & Checks small pieces to check.
76
+ - Harmony keeps Shepherding kind, because the strictness of a rule is a tension too.
77
+ - Shepherding holds the other three in place.
78
+
79
+ ## The Chair Test
80
+
81
+ A pillar earns its place by removal, the way a chair shows which legs it needs.
82
+
83
+ - Without Specs & Checks there is no shared truth.
84
+ - Without Layering the work arrives big, late and unverifiable.
85
+ - Without Harmony the rules tear each other apart.
86
+ - Without Shepherding the other three need enforcing forever.
87
+
88
+ Four legs, no spares.
89
+
90
+ ## The Benefits
91
+
92
+ - The project has one shared truth, and the checks keep that truth honest.
93
+ - A conflict between two rules is settled once, in the open.
94
+ - A caught mistake strengthens the harness, so the system heals itself and keeps learning.
95
+ - The director is free for judgment, taste and creation.
96
+
97
+ ## Will AI Replace You?
98
+
99
+ The expected answer is no. The better answer is yes: you replace the parts of your own work that bore you. What stays is the part you wanted all along, to direct and to create.