coentrify 0.0.2 → 0.1.1

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 (262) hide show
  1. package/LICENSE +18 -0
  2. package/README.md +2 -1
  3. package/bin/coentrify.js +83 -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/0.1.1.md +27 -0
  15. package/src/changelog/overview.md +14 -0
  16. package/src/coentrify-json.md +74 -0
  17. package/src/commands.md +50 -0
  18. package/src/glossary.md +132 -0
  19. package/src/how-it-works.md +51 -0
  20. package/src/onboarding.md +141 -0
  21. package/src/origin.md +19 -0
  22. package/src/philosophy.md +99 -0
  23. package/src/proof.md +596 -0
  24. package/src/readme.md +76 -0
  25. package/src/recommendations.md +107 -0
  26. package/src/standards/ai/match-known-commands-deterministically-classify-the-rest.md +22 -0
  27. package/src/standards/ai/overview.md +6 -0
  28. package/src/standards/ai/prompt-small-models-differently.md +21 -0
  29. package/src/standards/angular/canmatch-wildcard-for-route-access.md +22 -0
  30. package/src/standards/angular/interface-not-abstract-class-for-mock-swap.md +37 -0
  31. package/src/standards/angular/no-any-in-templates.md +25 -0
  32. package/src/standards/angular/no-inline-templates.md +14 -0
  33. package/src/standards/angular/one-component-per-folder-flat.md +12 -0
  34. package/src/standards/angular/one-projected-node-per-control-flow-block.md +19 -0
  35. package/src/standards/angular/overview.md +16 -0
  36. package/src/standards/angular/prefer-content-projection-over-props-angular.md +17 -0
  37. package/src/standards/angular/projected-content-is-never-styled-by-the-host.md +23 -0
  38. package/src/standards/angular/static-attribute-not-literal-binding.md +23 -0
  39. package/src/standards/angular/track-timed-items-by-an-id.md +17 -0
  40. package/src/standards/angular/ui-copy-in-template.md +26 -0
  41. package/src/standards/angular/use-modern-angular-template-apis.md +20 -0
  42. package/src/standards/architecture/adopt-configure-override.md +25 -0
  43. package/src/standards/architecture/app-shield.md +57 -0
  44. package/src/standards/architecture/converge-only-once-proven.md +22 -0
  45. package/src/standards/architecture/folder-concerns.md +28 -0
  46. package/src/standards/architecture/overview.md +11 -0
  47. package/src/standards/architecture/per-application-split-over-shared-branching.md +25 -0
  48. package/src/standards/architecture/separation-before-layer-standards.md +17 -0
  49. package/src/standards/architecture/unique-where-it-counts.md +19 -0
  50. package/src/standards/behavior/a-go-before-work-elsewhere.md +17 -0
  51. package/src/standards/behavior/a-maybe-is-a-trigger-to-investigate.md +20 -0
  52. package/src/standards/behavior/a-name-describes-its-unit.md +19 -0
  53. package/src/standards/behavior/a-quiet-tree-while-a-suite-runs.md +19 -0
  54. package/src/standards/behavior/always-make-no-mistakes.md +45 -0
  55. package/src/standards/behavior/always-verify-before-reporting-done.md +18 -0
  56. package/src/standards/behavior/always-work-from-a-plan.md +29 -0
  57. package/src/standards/behavior/anchor-edits-after-formatting.md +17 -0
  58. package/src/standards/behavior/backward-trace-missing-prerequisites.md +20 -0
  59. package/src/standards/behavior/code-review-compounds-into-patterns-and-sweeps.md +21 -0
  60. package/src/standards/behavior/communication-boundary.md +18 -0
  61. package/src/standards/behavior/dev-tiers.md +25 -0
  62. package/src/standards/behavior/docs-hold-only-what-the-director-decided.md +23 -0
  63. package/src/standards/behavior/dont-filter-data-without-a-spec.md +20 -0
  64. package/src/standards/behavior/dont-introduce-tech-debt.md +25 -0
  65. package/src/standards/behavior/feature-workflow.md +31 -0
  66. package/src/standards/behavior/file-a-change-with-coentrify.md +25 -0
  67. package/src/standards/behavior/flag-every-addition-of-your-own.md +22 -0
  68. package/src/standards/behavior/free-text-replies-no-buttons.md +20 -0
  69. package/src/standards/behavior/general-working-rules.md +37 -0
  70. package/src/standards/behavior/non-destructive-documenting-and-test-automation.md +20 -0
  71. package/src/standards/behavior/normal-dashes.md +15 -0
  72. package/src/standards/behavior/note-issues.md +26 -0
  73. package/src/standards/behavior/overview.md +46 -0
  74. package/src/standards/behavior/own-ports-own-processes.md +37 -0
  75. package/src/standards/behavior/project-lifecycle.md +21 -0
  76. package/src/standards/behavior/propagate-renames-and-convention-changes-everywhere.md +16 -0
  77. package/src/standards/behavior/prose-style.md +24 -0
  78. package/src/standards/behavior/prototype-mode-is-speed-first.md +20 -0
  79. package/src/standards/behavior/regular-layered-gap-analysis.md +20 -0
  80. package/src/standards/behavior/reload-the-standards-after-compacting.md +16 -0
  81. package/src/standards/behavior/review-changes-before-reporting-done.md +17 -0
  82. package/src/standards/behavior/review-every-capture-before-reporting.md +21 -0
  83. package/src/standards/behavior/standards-maintenance.md +65 -0
  84. package/src/standards/behavior/standards-over-skills.md +17 -0
  85. package/src/standards/behavior/sweeps-enumerate-into-tech-debt-first.md +20 -0
  86. package/src/standards/behavior/sync-the-docs-after-every-change.md +20 -0
  87. package/src/standards/behavior/the-quality-of-the-question.md +17 -0
  88. package/src/standards/behavior/things-of-one-kind-are-consistent.md +20 -0
  89. package/src/standards/behavior/understand-the-need.md +69 -0
  90. package/src/standards/behavior/use-us-english-everywhere.md +17 -0
  91. package/src/standards/behavior/verify-apis-against-docs-and-the-installed-artifact.md +17 -0
  92. package/src/standards/behavior/verify-control-before-rename.md +11 -0
  93. package/src/standards/code/code-principles.md +32 -0
  94. package/src/standards/code/escape-hatch-comments.md +20 -0
  95. package/src/standards/code/name-by-concept-not-copy.md +20 -0
  96. package/src/standards/code/no-abbreviated-names.md +20 -0
  97. package/src/standards/code/no-describe-what-comments.md +26 -0
  98. package/src/standards/code/overview.md +10 -0
  99. package/src/standards/code/pre-empt-recurring-code-review-nits.md +31 -0
  100. package/src/standards/commits/commits.md +44 -0
  101. package/src/standards/commits/gate-commits-on-exit-codes.md +22 -0
  102. package/src/standards/commits/main-stays-green-work-stays-clean.md +23 -0
  103. package/src/standards/commits/overview.md +8 -0
  104. package/src/standards/commits/verify-staging-before-committing.md +29 -0
  105. package/src/standards/docs/application-template.md +89 -0
  106. package/src/standards/docs/docs-are-hierarchical-explicit-and-short.md +48 -0
  107. package/src/standards/docs/docs-describe-behavior-not-wiring.md +24 -0
  108. package/src/standards/docs/docs-folder-structure.md +38 -0
  109. package/src/standards/docs/docs-state-knowledge.md +23 -0
  110. package/src/standards/docs/documentation-philosophy.md +62 -0
  111. package/src/standards/docs/feature-spec-template.md +89 -0
  112. package/src/standards/docs/feature-template.md +62 -0
  113. package/src/standards/docs/file-names.md +20 -0
  114. package/src/standards/docs/glossary.md +18 -0
  115. package/src/standards/docs/library-feedback.md +20 -0
  116. package/src/standards/docs/no-faux-headers-in-lists.md +18 -0
  117. package/src/standards/docs/overview.md +20 -0
  118. package/src/standards/docs/ui-vocabulary.md +31 -0
  119. package/src/standards/docs/workspace-levels.md +24 -0
  120. package/src/standards/docs/workspace-suite.md +24 -0
  121. package/src/standards/docs/workspace-template.md +41 -0
  122. package/src/standards/e2e/e2e-assert-before-interacting.md +21 -0
  123. package/src/standards/e2e/e2e-mock-contract.md +20 -0
  124. package/src/standards/e2e/e2e-runs-on-the-development-build.md +18 -0
  125. package/src/standards/e2e/e2e-test-conventions.md +61 -0
  126. package/src/standards/e2e/e2e-tests-must-demonstrate-behavior.md +28 -0
  127. package/src/standards/e2e/one-check-for-many-canvas-clicks.md +17 -0
  128. package/src/standards/e2e/overview.md +14 -0
  129. package/src/standards/e2e/per-feature-overview-test.md +30 -0
  130. package/src/standards/e2e/real-input-for-frame-races.md +25 -0
  131. package/src/standards/e2e/substring-locator-collisions.md +23 -0
  132. package/src/standards/e2e/use-the-e2e-pipeline-for-browser-probing.md +18 -0
  133. package/src/standards/electron/electron-packaging-and-suite.md +22 -0
  134. package/src/standards/electron/electron-shell-shape.md +21 -0
  135. package/src/standards/electron/overview.md +6 -0
  136. package/src/standards/gamedev/2d-visual-design.md +22 -0
  137. package/src/standards/gamedev/budget-exceptions.json +6 -0
  138. package/src/standards/gamedev/captures-and-reels.md +39 -0
  139. package/src/standards/gamedev/devbox.md +21 -0
  140. package/src/standards/gamedev/game-design-laws-experience.md +68 -0
  141. package/src/standards/gamedev/game-design-laws-guidance.md +43 -0
  142. package/src/standards/gamedev/game-design-laws-own-style.md +33 -0
  143. package/src/standards/gamedev/game-design-laws-progress.md +64 -0
  144. package/src/standards/gamedev/game-design-laws-quality.md +30 -0
  145. package/src/standards/gamedev/game-design-laws-story.md +45 -0
  146. package/src/standards/gamedev/game-design-laws-ui.md +52 -0
  147. package/src/standards/gamedev/game-design-laws-world.md +38 -0
  148. package/src/standards/gamedev/game-design-laws.md +114 -0
  149. package/src/standards/gamedev/game-phases-concept.md +29 -0
  150. package/src/standards/gamedev/game-phases-design.md +39 -0
  151. package/src/standards/gamedev/game-phases-development.md +30 -0
  152. package/src/standards/gamedev/game-phases-live.md +19 -0
  153. package/src/standards/gamedev/game-phases.md +52 -0
  154. package/src/standards/gamedev/game-work-workflow.md +47 -0
  155. package/src/standards/gamedev/gamedev-working-cadence.md +52 -0
  156. package/src/standards/gamedev/incremental-pacing.md +22 -0
  157. package/src/standards/gamedev/launch-strategy.md +50 -0
  158. package/src/standards/gamedev/measure-sound-never-guess.md +24 -0
  159. package/src/standards/gamedev/overview.md +29 -0
  160. package/src/standards/gamedev/own-icons.md +19 -0
  161. package/src/standards/gamedev/silent-runs.md +26 -0
  162. package/src/standards/gamedev/sprite-sheet-frames.md +23 -0
  163. package/src/standards/overview.md +43 -0
  164. package/src/standards/records/activity-log.md +33 -0
  165. package/src/standards/records/changelog-per-version.md +43 -0
  166. package/src/standards/records/healing-log.md +23 -0
  167. package/src/standards/records/overview.md +10 -0
  168. package/src/standards/records/playtest-files.md +38 -0
  169. package/src/standards/records/request-log.md +30 -0
  170. package/src/standards/records/user-test-files.md +21 -0
  171. package/src/standards/reporting/change-report.md +43 -0
  172. package/src/standards/reporting/overview.md +6 -0
  173. package/src/standards/reporting/reels-and-video-proof.md +32 -0
  174. package/src/standards/scripts/no-npx-in-scripts.md +20 -0
  175. package/src/standards/scripts/npm-script-naming.md +43 -0
  176. package/src/standards/scripts/overview.md +7 -0
  177. package/src/standards/scripts/thin-wrappers-in-ci-and-hooks.md +25 -0
  178. package/src/standards/security/keep-personal-data-out-of-requests.md +16 -0
  179. package/src/standards/security/keep-secrets-away-from-agents.md +21 -0
  180. package/src/standards/security/never-access-the-keychain.md +16 -0
  181. package/src/standards/security/overview.md +7 -0
  182. package/src/standards/simple-workflow/bugs-template.md +38 -0
  183. package/src/standards/simple-workflow/overview.md +12 -0
  184. package/src/standards/simple-workflow/plan-template.md +50 -0
  185. package/src/standards/simple-workflow/plans-vs-persistent-files.md +31 -0
  186. package/src/standards/simple-workflow/remove-completed-items-from-docs.md +19 -0
  187. package/src/standards/simple-workflow/roadmap-template.md +41 -0
  188. package/src/standards/simple-workflow/technical-debt-template.md +44 -0
  189. package/src/standards/simple-workflow/the-simple-workflow.md +48 -0
  190. package/src/standards/simple-workflow/todo-template.md +31 -0
  191. package/src/standards/tests/a-bugs-test-reproduces-with-real-input.md +18 -0
  192. package/src/standards/tests/bracket-state-changes-with-contrast-assertions.md +37 -0
  193. package/src/standards/tests/gestures-in-tests.md +35 -0
  194. package/src/standards/tests/implementation-agnostic-assertions.md +20 -0
  195. package/src/standards/tests/implementation-agnostic-locators.md +18 -0
  196. package/src/standards/tests/overview.md +13 -0
  197. package/src/standards/tests/realistic-test-data-variance.md +24 -0
  198. package/src/standards/tests/seed-surfaces-every-state-on-page-1.md +17 -0
  199. package/src/standards/tests/test-design.md +47 -0
  200. package/src/standards/tests/test-the-system-behind-a-mock.md +21 -0
  201. package/src/standards/tickets-workflow/agent-roles.md +54 -0
  202. package/src/standards/tickets-workflow/budget-exceptions.json +6 -0
  203. package/src/standards/tickets-workflow/building-a-ticket.md +47 -0
  204. package/src/standards/tickets-workflow/overview.md +15 -0
  205. package/src/standards/tickets-workflow/stabilize-before-adding.md +18 -0
  206. package/src/standards/tickets-workflow/the-builder.md +28 -0
  207. package/src/standards/tickets-workflow/the-conductor.md +44 -0
  208. package/src/standards/tickets-workflow/the-done-part.md +23 -0
  209. package/src/standards/tickets-workflow/ticket-template.md +96 -0
  210. package/src/standards/tickets-workflow/work-item-names.md +30 -0
  211. package/src/standards/tickets-workflow/work-tracking.md +177 -0
  212. package/src/standards/tickets-workflow/work-workflow.md +123 -0
  213. package/src/standards/tickets-workflow/writing-a-ticket.md +50 -0
  214. package/src/standards/tooling/browser-captures-go-to-disk.md +20 -0
  215. package/src/standards/tooling/check-where-a-pane-click-landed.md +19 -0
  216. package/src/standards/tooling/defer-tooling-until-the-cost-shows-up.md +19 -0
  217. package/src/standards/tooling/develop-against-mocks.md +19 -0
  218. package/src/standards/tooling/hygiene-tests-run-on-their-own-runner.md +18 -0
  219. package/src/standards/tooling/lightweight-test-reporting-only.md +16 -0
  220. package/src/standards/tooling/node-versions.md +24 -0
  221. package/src/standards/tooling/overview.md +17 -0
  222. package/src/standards/tooling/parallel-agents.md +45 -0
  223. package/src/standards/tooling/playwright-parallel-runs.md +30 -0
  224. package/src/standards/tooling/playwright-video-recording.md +32 -0
  225. package/src/standards/tooling/read-before-you-truncate.md +19 -0
  226. package/src/standards/tooling/start-playwright-on-a-clean-port.md +22 -0
  227. package/src/standards/tooling/vitepress-wiki.md +38 -0
  228. package/src/standards/typescript/always-add-explicit-types.md +32 -0
  229. package/src/standards/typescript/barrel-imports.md +21 -0
  230. package/src/standards/typescript/no-magic-values.md +52 -0
  231. package/src/standards/typescript/one-artifact-per-file.md +19 -0
  232. package/src/standards/typescript/overview.md +8 -0
  233. package/src/standards/ui/communicate-state.md +21 -0
  234. package/src/standards/ui/never-obscure-information-the-user-needs.md +26 -0
  235. package/src/standards/ui/overview.md +16 -0
  236. package/src/standards/ui/pixel-perfect-design-check.md +22 -0
  237. package/src/standards/ui/ui-component-design.md +34 -0
  238. package/src/standards/ui/ui-components-first.md +25 -0
  239. package/src/standards/ui/ui-layout-via-slot-composition.md +33 -0
  240. package/src/standards/ui/ui-library-is-domain-agnostic.md +20 -0
  241. package/src/standards/ui/ui-refactor-preserve-dont-redesign.md +25 -0
  242. package/src/standards/ui/ui-styleguide.md +30 -0
  243. package/src/standards/ui/ui-variants-by-function-not-by-color.md +23 -0
  244. package/src/standards/ui/validation-errors-fire-on-submit.md +20 -0
  245. package/src/standards/ui/walk-the-users-journey.md +29 -0
  246. package/src/standards/web/always-use-design-tokens-for-colors.md +24 -0
  247. package/src/standards/web/dark-mode-through-tokens.md +19 -0
  248. package/src/standards/web/hidden-attribute-loses-to-display.md +22 -0
  249. package/src/standards/web/overview.md +9 -0
  250. package/src/standards/web/scss-shared-partial-imports.md +16 -0
  251. package/src/standards/web/transitions-only-on-user-toggle.md +19 -0
  252. package/src/standards.md +66 -0
  253. package/src/tools/overview.md +22 -0
  254. package/src/tools/scripts/coentrify-update.py +242 -0
  255. package/src/tools/scripts/unlink-missing-standards.py +138 -0
  256. package/src/tools/specs/changelog-append.md +15 -0
  257. package/src/tools/specs/coentrify-json-check.md +21 -0
  258. package/src/tools/specs/commit-gate.md +32 -0
  259. package/src/tools/specs/healing-append.md +15 -0
  260. package/src/tools/specs/landing.md +29 -0
  261. package/src/tools/specs/refuse-wrap-up-questions.md +22 -0
  262. package/src/tools/specs/reload-core-rules.md +20 -0
@@ -0,0 +1,38 @@
1
+ # Playtest Files
2
+
3
+ Every playtest gets its own file in `docs/records/playtests/`, dated and numbered (`<date>-playtest-<n>.md`), listed newest on top in the wiki. It holds the date and DEV day, the version played with a link to its changelog, the focus, a short summary and the feedback as a flat list, one item per bullet, reworded from the log but never reinterpreted.
4
+
5
+ ## Why
6
+
7
+ A playtest file records what was felt about a build, and the next build is held against it.
8
+
9
+ ## The File
10
+
11
+ - The number gives the director and the playtesters a shared name for a session.
12
+ - The H1 carries the number and the DEV day, the way the log's does: `# Playtest 46 - DEV day 13`, so the wiki's menu shows it. The head repeats the day (`- Day: DEV day 13`), counted as [Changelog Per Version](changelog-per-version.md#the-dev-day) says.
13
+ - A playtest on an untagged build names the version in progress.
14
+ - The summary is two or three lines naming the themes. The items stay in the list.
15
+
16
+ ## What Counts As A Playtest
17
+
18
+ - A session playing the build.
19
+ - A review of the changelog, its captures or its reels instead of the build: even one line of feedback on a reel gets a file.
20
+ - Notes that come in while the director plays a version in progress: the file opens with the first such note of the session and grows with every note after, each in its own commit right after its log entry.
21
+
22
+ ## How To Apply
23
+
24
+ - Write the file right after the log entry, before anything else is done with the feedback. Never afterward on request.
25
+ - Feedback stays feedback: its units go where the project's workflow files new work, such as the intake of [Work Workflow](../tickets-workflow/work-workflow.md), where the director's "feedback for now" or "not for now" means built later in its epic and phase, never held.
26
+
27
+ ## Outside Playtesters
28
+
29
+ - Each outside playtester gets a page listing everything that playtester said by date, so the director sees the whole view at once.
30
+ - The director's own sessions keep the numbered files.
31
+ - An outside playtester's feedback, even relayed by the director, stays on the playtester's page until the director has reviewed it: no ticket or agent brief from it before that review.
32
+ - A workspace doc names every outside playtester for later thanks and indexes the pages.
33
+
34
+ ## Related
35
+
36
+ - [Changelog Per Version](changelog-per-version.md)
37
+ - [Gamedev Working Cadence](../gamedev/gamedev-working-cadence.md)
38
+ - [User Test Files](user-test-files.md)
@@ -0,0 +1,30 @@
1
+ # Request Log
2
+
3
+ Keep a raw, dated log of everything the director says in `docs/records/log/<date>.md`: requests, feedback, questions, asides and go-aheads alike, written before any of it goes where the project's workflow files new work, such as the intake of [Work Workflow](../tickets-workflow/work-workflow.md). Minimal cleanup only: spelling, careful rewording, prose into a flat list. The essence stays. The wiki lists the log newest first as the Request Log.
4
+
5
+ ## Why
6
+
7
+ Every doc and ticket can be checked against the words that produced it.
8
+
9
+ ## The File
10
+
11
+ - The H1 is the date with its DEV day: `2026-09-14 - DEV day 6` ([Changelog Per Version](changelog-per-version.md#the-dev-day)).
12
+ - One `##` per message, titled with its time. The heading is written by the shell itself in the append, `printf '\n## %s\n\n' "$(date +%H:%M)"`, never typed: typed headings run ahead of the clock.
13
+ - The days before the agent are reconstructed from the commit history as entries of their own, so the log starts at the project's first day.
14
+
15
+ ## How To Apply
16
+
17
+ - Log first, in the same turn, then file the work.
18
+ - A message that lands mid-turn is logged the same way, with its own time, before the work goes on.
19
+ - A question the director asks is logged too, since the answer shapes the project.
20
+ - A secret in a message is left out ([Keep Secrets Away From Agents](../security/keep-secrets-away-from-agents.md)).
21
+ - Past entries only get typo fixes.
22
+ - New understanding gets a new entry.
23
+ - The log entry is committed as its own `docs(log)` commit, in the same pass as what was parsed from it. Never left uncommitted waiting for a go.
24
+ - The raw chat transcripts stay where the tool keeps them, on disk and uncommitted. The log is the curated record. Now and then a debt ticket schedules a gap analysis of the raw transcripts against the log and the docs, looking for interpretation errors.
25
+
26
+ ## Related
27
+
28
+ - [Docs Hold Only What The Director Decided](../behavior/docs-hold-only-what-the-director-decided.md)
29
+ - [Activity Log](activity-log.md)
30
+ - [Playtest Files](playtest-files.md)
@@ -0,0 +1,21 @@
1
+ # User Test Files
2
+
3
+ Every session with real users gets its own file in `docs/records/user-tests/`, dated and numbered (`<date>-user-test-<n>.md`), in the shape of a playtest file ([Playtest Files](playtest-files.md)): the date, the version with a link to its changelog, the focus, a short summary and the feedback as a flat list.
4
+
5
+ ## Why
6
+
7
+ A user test records what real users did with a version, and the next version is held against it.
8
+
9
+ ## How To Apply
10
+
11
+ - The head names who took part by role, such as two shop employees and one store manager, never by name.
12
+ - The tasks the users were given come before the feedback, one per bullet.
13
+ - What a user did and what a user said are separate items, since the two often differ.
14
+ - The feedback stays in the file until the director has reviewed it: no ticket and no agent brief from it before that review.
15
+ - The number, the H1 with the DEV day, a version in progress and the summary follow Playtest Files.
16
+
17
+ ## Related
18
+
19
+ - [Playtest Files](playtest-files.md)
20
+ - [Changelog Per Version](changelog-per-version.md)
21
+ - [Request Log](request-log.md)
@@ -0,0 +1,43 @@
1
+ # Change Report
2
+
3
+ When a unit of work is done - a fixed bug, a resolved finding, an improvement, a new or changed feature - write a short report a teammate can read in two minutes and trust. It shows the problem with proof, where it lived, why it happened, what else it touched, and the fix with the same proof. For a feature it shows the old flow, what changed, and the user benefit.
4
+
5
+ ## Why
6
+
7
+ A change report proves a change and shows how far it spread, so the work is reviewed without running it again.
8
+
9
+ ## Section Shape
10
+
11
+ - Headline + one-sentence hook - what was wrong (or what's new) and what changed.
12
+ - TLDR - what / where / fix, three lines, in a callout.
13
+ - The Problem (feature: *Before*) - what the user saw, with a screenshot.
14
+ - Context & Reproduction - conditions, where it appears, steps, expected vs actual.
15
+ - Analysis - root cause in a sentence or two. A bug is smoke, name the fire.
16
+ - The Sweep - grep for siblings of the same pattern. Record what else was affected (screenshots) and what was verified clean. This is what earns trust.
17
+ - The Fix (feature: *After*) - what changed, with before/after images at every location the sweep named.
18
+ - Verification - how it was confirmed: test added, e2e, type check, manual. Never an unconfirmed fix.
19
+ - Impact (feature: *Benefit*, led with) - user-facing effect, plus follow-ups linked out.
20
+ - References - feature/spec/use-case/bug/PR, and related reports.
21
+
22
+ Drop sections that don't apply. Screenshots over prose. Videos only when the point is motion. Name files and slugs by concept ([Name By Concept, Not Copy](../code/name-by-concept-not-copy.md)).
23
+
24
+ ## Deliverable
25
+
26
+ Where a project keeps a changelog per version, that page is the record and this report is not written ([Changelog Per Version](../records/changelog-per-version.md)). Elsewhere the report is a page in the docs wiki, kept so the team can always go back and see what changed: a per-target changelog with a curated newest-first index, entry pages dated and slugged, screenshots stored alongside. A project keeps its own mechanics for this (wiki paths, asset folder, index format) in its docs.
27
+
28
+ ## How To Apply
29
+
30
+ - Reach for this when picking an item off a bugs list, recording a finding, or finishing a feature.
31
+ - Only product changes are entries: what the user of the product sees or does differently. Changes to the wiki, the capture and reel scripts, lint or hooks are not changelog entries. Their commit is the record.
32
+ - Run the enumerate-first sweep before declaring the pattern closed.
33
+ - Capture proof and verify before reporting.
34
+ - Never soften a state in the proof.
35
+
36
+ ## Related
37
+
38
+ - [Sweeps Enumerate Into Tech-Debt First](../behavior/sweeps-enumerate-into-tech-debt-first.md)
39
+ - [Don't Filter Data Without A Spec](../behavior/dont-filter-data-without-a-spec.md)
40
+ - [Never Obscure Information The User Needs](../ui/never-obscure-information-the-user-needs.md)
41
+ - [Always Verify Before Reporting Done](../behavior/always-verify-before-reporting-done.md)
42
+ - [Reels And Video Proof](reels-and-video-proof.md)
43
+ - [Name By Concept, Not Copy](../code/name-by-concept-not-copy.md)
@@ -0,0 +1,6 @@
1
+ # Overview
2
+
3
+ The Reporting standards: reports and proof.
4
+
5
+ - [Change Report](change-report.md) - per-item change report with before and after proof
6
+ - [Reels And Video Proof](reels-and-video-proof.md) - reels come from code, show what they claim, TTS speech unverified until checked
@@ -0,0 +1,32 @@
1
+ # Reels And Video Proof
2
+
3
+ A reel is footage of the product in use or proof that an implementation works, recorded from code on seeded scenarios, never by hand. A still is the cheaper proof. A video earns its place when motion, sound or timing is the point.
4
+
5
+ ## Why
6
+
7
+ A reel is proof that can be watched, and recorded from code it can be made again when a version needs one.
8
+
9
+ ## Rules
10
+
11
+ - A reel shows what it claims. An agent cannot watch it: where it matters, it takes stills of the moments that count, from the run or from frames of the recording, and checks them. If nothing visible changes between them, the reel proves nothing ([E2E Tests Must Demonstrate Behavior](../e2e/e2e-tests-must-demonstrate-behavior.md)).
12
+ - A reel is a product artifact: no sudden resizes, the recording's size matches the viewport (no letterboxing or downscaling), and it ends on a complete state, never mid-transition.
13
+ - Scope matches level. Footage of one feature stays portable, with no framing for one audience. Audience framing belongs only in a reel of the whole product.
14
+ - Copy on screen stays generic, such as "the X", unless the first person is the point.
15
+
16
+ ## Narration And Speech
17
+
18
+ For reels with narration or subtitles, and for any speech a TTS model generates, in a reel or in the product itself:
19
+
20
+ - Words never contradict the screen, and a claim stays true for as long as it is spoken: a step that changes the state it describes splits into a confirm step and an action step.
21
+ - The user is the subject and the simulated world is what they act in: "the user logs in to X", never "as X".
22
+ - Reading-time formulas underestimate TTS, especially outside English. When two lines collide, give them more time.
23
+ - A cheap TTS model says exactly what it reads: spell names and odd words the way they should sound in the input it gets, and keep the display text separate when the two differ.
24
+ - Generated speech is unverified until it is checked. The agent transcribes it with a tool, and brings a clip to the director when only an ear can tell, such as how a name sounds.
25
+ - Unverified speech can still ship, and is reported as unverified.
26
+
27
+ ## Related
28
+
29
+ - [E2E Tests Must Demonstrate Behavior](../e2e/e2e-tests-must-demonstrate-behavior.md)
30
+ - [Per-Feature Overview Test](../e2e/per-feature-overview-test.md)
31
+ - [Captures And Reels](../gamedev/captures-and-reels.md)
32
+ - [Playwright Video Recording](../tooling/playwright-video-recording.md)
@@ -0,0 +1,20 @@
1
+ # No npx In Scripts
2
+
3
+ In `package.json` scripts, husky hooks, and CI workflows, never prefix commands with `npx`. The binary is already a project dependency, so it should be resolved via npm's PATH (an npm script finds it automatically) or via an explicit `npm run <wrapper>` call - never `npx nx ...`, `npx playwright ...`.
4
+
5
+ ## Why
6
+
7
+ A script runs what the lock file declares, online or offline.
8
+
9
+ ## How To Apply
10
+
11
+ - `npx` exists for the case where a tool is not installed locally: it falls back to fetching from the network. In a script it hides that a dependency should be declared, masks a mismatch between `package-lock.json` and what runs, and quietly does the wrong thing in an offline or locked-down CI.
12
+
13
+ ## Exceptions
14
+
15
+ - One-off interactive commands at the terminal can still use `npx`. This rule is about checked-in scripts.
16
+
17
+ ## Related
18
+
19
+ - [npm Script Naming](npm-script-naming.md)
20
+ - [Thin Wrappers In CI And Hooks](thin-wrappers-in-ci-and-hooks.md)
@@ -0,0 +1,43 @@
1
+ # npm Script Naming
2
+
3
+ A script is named by who runs it: a task as `<verb>:<app>:<thing>`, and an automation context's script as `<context>:<thing>`.
4
+
5
+ ## Why
6
+
7
+ A script's name says what it runs and for which context.
8
+
9
+ ## Tasks (Run By Humans Or Shared)
10
+
11
+ Format: `<verb>:<app>:<thing>`. App always comes second, never `<verb>:<thing>:<app>`. Omit `<app>` in single-app projects. Omit `<thing>` when not needed.
12
+
13
+ ### Verbs
14
+
15
+ A verb names the kind of run, such as these:
16
+
17
+ - `start:` - long-running processes (dev server, report viewer).
18
+ - `test:`, `lint:`, `build:`, `e2e:`, `install:` - one-shot runs.
19
+
20
+ ### Examples
21
+
22
+ - `start:admin` - run the admin dev server.
23
+ - `e2e:admin:report` - run the full e2e suite with HTML report and videos.
24
+
25
+ ## Contexts (Run By Automation)
26
+
27
+ Format: `<context>:<thing>`. Each automation context gets its own entry scripts, distinct from the human-run tasks above. The `hooks:` and `ci:` prefixes are examples of the general pattern: one prefix per context.
28
+
29
+ An entry script calls a task, such as `"hooks:pre-commit": "npm run lint"`, so a context and a human run one command that cannot drift. When a context needs a command of its own, that command is a task as well, such as `lint:ci`, and the entry script calls it.
30
+
31
+ - `hooks:pre-commit`, `hooks:pre-push` - called by git hooks.
32
+ - `ci:lint`, `ci:test` - called by CI workflow steps.
33
+
34
+ ## Wrappers
35
+
36
+ For tools that ship as installable binaries (Playwright, MSW, etc.), add a thin wrapper script in `package.json`: `"install:playwright": "playwright install --with-deps chromium"`. Call it via `npm run install:playwright` rather than invoking the binary directly.
37
+
38
+ Don't expose internal env vars or build flags (`DEMO=1`, `CI=true`) in script names. Keep them inside the script.
39
+
40
+ ## Related
41
+
42
+ - [Thin Wrappers In CI And Hooks](thin-wrappers-in-ci-and-hooks.md)
43
+ - [No npx In Scripts](no-npx-in-scripts.md)
@@ -0,0 +1,7 @@
1
+ # Overview
2
+
3
+ The Scripts standards: npm scripts.
4
+
5
+ - [No npx In Scripts](no-npx-in-scripts.md) - no npx in checked-in scripts
6
+ - [npm Script Naming](npm-script-naming.md) - `<verb>:<app>:<thing>`, separate scripts per context
7
+ - [Thin Wrappers In CI And Hooks](thin-wrappers-in-ci-and-hooks.md) - hooks and CI only call npm scripts
@@ -0,0 +1,25 @@
1
+ # Thin Wrappers In CI And Hooks
2
+
3
+ Git hooks and CI workflow steps are thin dispatchers: each is a one-line `npm run <name>` call and nothing else. The real sequence of commands lives in `package.json`.
4
+
5
+ ## Why
6
+
7
+ Every behavior is found in `package.json`, and runs the same from CI, a hook or by hand.
8
+
9
+ ## How To Apply
10
+
11
+ - Git hooks call `hooks:<name>` and CI calls `ci:<name>`, a dedicated script per context ([npm Script Naming](npm-script-naming.md)).
12
+ - Git hook (husky example): `.husky/<name>` holds a single `npm run hooks:<name>` line and nothing else. `hooks:<name>` in `package.json` calls a task (e.g. `"hooks:pre-commit": "npm run lint"`).
13
+ - CI step example:
14
+
15
+ ```yaml
16
+ - run: npm run ci:lint
17
+ ```
18
+
19
+ `ci:<name>` calls a task as well (e.g. `"ci:lint": "npm run lint:affected"`, where `"lint:affected": "nx affected --target=lint --base=origin/main"`).
20
+ - Editing an existing hook or CI step: move any inline commands into a matching npm script first.
21
+ - Wrap even a one-line command, for consistency.
22
+
23
+ ## Related
24
+
25
+ - [npm Script Naming](npm-script-naming.md)
@@ -0,0 +1,16 @@
1
+ # Keep Personal Data Out Of Requests
2
+
3
+ No personal data of the director's goes into a web request an agent makes: a name, an email address or an account id, in the URL, a header, a User-Agent or the body.
4
+
5
+ ## Why
6
+
7
+ The director's personal data stays with the director.
8
+
9
+ ## How To Apply
10
+
11
+ - A service that asks automated clients for contact details gets a generic client name, or the agent asks the director first.
12
+ - A request the director asked for, with their own data, is the director's call and goes as asked.
13
+
14
+ ## Related
15
+
16
+ - [Never Access The Keychain](never-access-the-keychain.md)
@@ -0,0 +1,21 @@
1
+ # Keep Secrets Away From Agents
2
+
3
+ A secret, such as a credential, a token or an API key, is set up so only the running app can read it, as far from the agent as the setup allows.
4
+
5
+ ## Why
6
+
7
+ What an agent reads can end up in a chat, a log or a commit, and a secret that leaks there is out of the director's hands.
8
+
9
+ ## How To Apply
10
+
11
+ - A secret lives in the environment the app runs in, such as the host's or the CI's secret store, never in a file or a message the agent reads.
12
+ - A `.env*` file with secrets is avoided, even where the director points to one. Configuration that is no secret can live in the project.
13
+ - When a task needs a secret, the agent sets up where the app reads it, and the director puts the value there.
14
+ - A secret that reaches the chat anyway is never written to a log, a record or a commit, the request log included.
15
+ - The keychain is never touched ([Never Access The Keychain](never-access-the-keychain.md)).
16
+
17
+ ## Related
18
+
19
+ - [Never Access The Keychain](never-access-the-keychain.md)
20
+ - [Keep Personal Data Out Of Requests](keep-personal-data-out-of-requests.md)
21
+ - [Request Log](../records/request-log.md)
@@ -0,0 +1,16 @@
1
+ # Never Access The Keychain
2
+
3
+ Never access the director's macOS keychain. Do not run `security find-internet-password`, `security find-generic-password`, `security dump-keychain`, or any other `security` / keychain query, and do not script around them. This is a hard boundary.
4
+
5
+ ## Why
6
+
7
+ The keychain is the director's private credential store. Probing it is an intrusion.
8
+
9
+ ## How To Apply
10
+
11
+ - A secret a task needs is set up as [Keep Secrets Away From Agents](keep-secrets-away-from-agents.md) says, never taken from the keychain.
12
+
13
+ ## Related
14
+
15
+ - [Keep Secrets Away From Agents](keep-secrets-away-from-agents.md)
16
+ - [General Working Rules](../behavior/general-working-rules.md)
@@ -0,0 +1,7 @@
1
+ # Overview
2
+
3
+ The Security standards: hard boundaries.
4
+
5
+ - [Keep Personal Data Out Of Requests](keep-personal-data-out-of-requests.md) - no name, email or account id of the director's in a web request
6
+ - [Keep Secrets Away From Agents](keep-secrets-away-from-agents.md) - a secret is set up so only the running app reads it, never in a `.env` file, a chat or a log
7
+ - [Never Access The Keychain](never-access-the-keychain.md) - never query the keychain
@@ -0,0 +1,38 @@
1
+ # Bugs Template
2
+
3
+ `docs/development/bugs.md` uses a fixed shape, and so does `docs/development/<app>/bugs.md` in a workspace with several apps.
4
+
5
+ ## Purpose
6
+
7
+ Catalogs user-facing bugs in the current build. A reader scans bugs.md to know exactly what's broken for real users right now, sorted by impact.
8
+
9
+ ## Why
10
+
11
+ An agent can reproduce the actual bug and fix it.
12
+
13
+ ## Bug Vs Debt
14
+
15
+ - User-facing bug -> bugs.md.
16
+ - Test-tooling limitation, dev-mock gap, internal-only issue -> the debt list ([Technical Debt Template](technical-debt-template.md)).
17
+ - If real users never hit it, it's not a bug.
18
+
19
+ ## Sections
20
+
21
+ - Title: `# Bugs`.
22
+ - Overview list: flat dash list, one bullet per bug, formatted as ``- <description> (`<priority>`)``. Always present, even when there's only one bug. Sorted by priority, highest first.
23
+ - Per bug: `## <title>` subheading, then the bug shape below.
24
+
25
+ ## Bug Shape
26
+
27
+ - Subheading: `## <user-perspective title>`. The title is the user-experienced symptom, not the suspected cause.
28
+ - Priority line right after the title: `Priority: <level>`. Levels: `high`, `medium`, `low` (extend as needed).
29
+ - Description paragraph: what the user experiences when the bug fires. Don't speculate on causes - speculation belongs in PR/commit discussion or investigation notes, not the bug doc.
30
+ - `### Reproduce` subheading: steps that trigger the bug, ending with `Expected:` and `Actual:` lines so the deviation is explicit. Reuse the matching spec use case's structure - the bug entry describes the deviation from the spec, not an alternate spec.
31
+ - `### References` subheading: metadata bullets for navigation (Feature, Use case, E2E status).
32
+
33
+ ## Related
34
+
35
+ - [Workspace Template](../docs/workspace-template.md)
36
+ - [Documentation Philosophy](../docs/documentation-philosophy.md)
37
+ - [Feature Spec Template](../docs/feature-spec-template.md)
38
+ - [No Faux Headers In Lists](../docs/no-faux-headers-in-lists.md)
@@ -0,0 +1,12 @@
1
+ # Overview
2
+
3
+ The Simple Workflow standards: the work tracked in flat lists.
4
+
5
+ - [Bugs Template](bugs-template.md) - user-facing bugs in the current build, sorted by impact, each with the steps to reproduce
6
+ - [Plan Template](plan-template.md) - the plan holds what is in flight now and what comes right after, and a finished item is stripped
7
+ - [Plans Vs Persistent Files](plans-vs-persistent-files.md) - plans shrink to empty, persistent files evolve, never mix the two
8
+ - [Remove Completed Items From Docs](remove-completed-items-from-docs.md) - drop completed list lines, archive tickets, no strikethrough
9
+ - [Roadmap Template](roadmap-template.md) - the roadmap shape (Active, Priorities, Blocked, Waiting For Response, Nice To Have) and item names that show the type of work, the topic and the direction
10
+ - [Technical Debt Template](technical-debt-template.md) - internal debt, sorted by severity, with just enough to start the work
11
+ - [The Simple Workflow](the-simple-workflow.md) - a few flat lists, the director asks what's next, and where a finding goes
12
+ - [Todo Template](todo-template.md) - a flat list of concrete follow-ups, one line each, stripped when done
@@ -0,0 +1,50 @@
1
+ # Plan Template
2
+
3
+ `docs/development/plan.md` is the workspace plan: a thin parent. The detailed, in-flight items live in the per-app plans (`docs/development/<app>/plan.md`). The workspace plan stays short and points down to them. In a project with one app, `docs/development/plan.md` is the plan itself.
4
+
5
+ ## Purpose
6
+
7
+ The short-horizon working doc: what's in flight right now, what's queued for immediately after. Distinct from the roadmap (longer-horizon goals) and the inbox (the unsorted dead drop).
8
+
9
+ ## Workspace Plan (Parent)
10
+
11
+ - Title: `# Plan`.
12
+ - Active focus statement: a one-liner right under the title naming the current focus across the workspace.
13
+ - A flat dash list of pointers to the per-app plans that hold the detail - not the detailed items themselves.
14
+ - Keep it short. It should rarely need editing as app-level work churns.
15
+
16
+ ## App Plan (`docs/development/<app>/plan.md`)
17
+
18
+ - Same shape, scoped to the app: title + active-focus one-liner, then the overview list right under the title.
19
+ - The immediate items live here, in the overview list ([Overview List](#overview-list)). Promote an item to a `##` subsection only when it needs explanation ([No Faux Headers In Lists](../docs/no-faux-headers-in-lists.md)). The subsection is titled the same as its overview entry.
20
+
21
+ ## Overview List
22
+
23
+ - Open the plan, right under its title, with a flat list of every item it tracks, a table of contents that makes the whole plan scannable before any detail.
24
+ - Label the one item in flight `(active)`, at most one active at a time.
25
+ - A done item leaves the plan ([Remove Completed Items From Docs](remove-completed-items-from-docs.md)).
26
+
27
+ ## Describe A Shift
28
+
29
+ - When the focus pivots away from previously-planned work (pausing an in-flight cleanup for a client-priority feature, say), name the shift in the active-focus one-liner: what it moved from, its new state (paused), and why.
30
+ - The next session should see why the active item isn't what the plan used to be about, without digging through git history.
31
+
32
+ ## What Belongs
33
+
34
+ - Items in flight right now or about to be picked up next (in the app plan).
35
+ - The one-line current direction (in both, scoped accordingly).
36
+
37
+ ## What Doesn't Belong
38
+
39
+ - Long-horizon goals - those live in [Roadmap Template](roadmap-template.md).
40
+ - Small unsorted follow-ups - the workspace inbox (the free-form dead drop).
41
+ - Status snapshots ("E2E harness: complete..."). They go stale fast and belong in commit history or release notes.
42
+ - Speculation about future work, restart notes, decision logs.
43
+ - Detailed immediate items in the workspace plan - those belong in the app plan.
44
+
45
+ ## Related
46
+
47
+ - [Workspace Template](../docs/workspace-template.md)
48
+ - [Application Template](../docs/application-template.md)
49
+ - [Roadmap Template](roadmap-template.md)
50
+ - [Documentation Philosophy](../docs/documentation-philosophy.md)
@@ -0,0 +1,31 @@
1
+ # Plans Vs Persistent Files
2
+
3
+ A plan shrinks to empty, a persistent file is never completed, and the two never mix.
4
+
5
+ ## Why
6
+
7
+ Each file stays current, so a reader can trust it.
8
+
9
+ ## Plans
10
+
11
+ Hold what's being done right now: status, ordered tasks, blockers, scope-of-effort. Items get deleted as they're done. The file shrinks toward empty. Examples: `docs/development/plan.md`, the inbox, a plan file outside a project.
12
+
13
+ ## Persistent
14
+
15
+ Hold knowledge, conventions, functionality, and reference. They evolve but never get "completed". Single responsibility per file: one purpose, one shape. Examples: standards, skills, architecture docs.
16
+
17
+ ## How To Apply
18
+
19
+ When writing, ask: is this *how* something works (or should), or *what* we're doing right now?
20
+
21
+ - *How* -> persistent (standard, skill, doc).
22
+ - *What* -> plan.
23
+
24
+ When reviewing a plan, extract any "always X" / "never Y" text to a persistent home and replace with a one-line pointer. Keep the items' status, such as the active one and its blockers, and their order in the plan. When reviewing a persistent file, strip any time-bound status into the relevant plan.
25
+
26
+ ## Related
27
+
28
+ - [Always Work From A Plan](../behavior/always-work-from-a-plan.md)
29
+ - [Plan Template](plan-template.md)
30
+ - [Remove Completed Items From Docs](remove-completed-items-from-docs.md)
31
+ - [Documentation Philosophy](../docs/documentation-philosophy.md)
@@ -0,0 +1,19 @@
1
+ # Remove Completed Items From Docs
2
+
3
+ A list holds only what remains. When an item is completed, its line leaves the list entirely: never `~~text~~`, a "Done" label or a ticked checkbox.
4
+
5
+ ## Why
6
+
7
+ A list holds only open work, so it reads at a glance.
8
+
9
+ ## How To Apply
10
+
11
+ - A completed item leaves the list for the version's changelog, or for the archive.
12
+ - A done ticket is archived, never deleted, so the changelog can link it ([Work Tracking](../tickets-workflow/work-tracking.md)).
13
+ - A plan file outside a project shrinks the same way: each finished step is deleted.
14
+
15
+ ## Related
16
+
17
+ - [Work Tracking](../tickets-workflow/work-tracking.md)
18
+ - [Changelog Per Version](../records/changelog-per-version.md)
19
+ - [Plans Vs Persistent Files](plans-vs-persistent-files.md)
@@ -0,0 +1,41 @@
1
+ # Roadmap Template
2
+
3
+ `docs/development/roadmap.md` uses a fixed shape.
4
+
5
+ ## Purpose
6
+
7
+ Answers "what's next?" at a glance. Active surfaces the current focus. Priorities show what comes after. Blocked vs Waiting For Response splits "we'll unblock ourselves" from "we need someone else". Nice To Have holds what is wanted, for when there is time.
8
+
9
+ ## Sections
10
+
11
+ - Title: `# Roadmap`.
12
+ - `## Active` - the current focus. Usually one item.
13
+ - `## Priorities` - upcoming work, top-down execution order. Top is what we do next once Active completes.
14
+ - `## Blocked` - paused on internal prerequisites (another roadmap item, an e2e harness, a tooling gap). We can unblock ourselves.
15
+ - `## Waiting For Response` - paused on external dependencies (third parties, partners, vendors). We can't unblock ourselves.
16
+ - `## Nice To Have` - decided and wanted, done only when there is time.
17
+
18
+ ## Item Shape
19
+
20
+ - An item is named as [Work Item Names](../tickets-workflow/work-item-names.md) says, in Title Case: `Create An Account`, `Fix Auth Session Redirect`.
21
+ - Flat dash list within each section.
22
+ - One-liner items. No parenthetical bloat, no trailing periods.
23
+ - Blocked / Waiting items: include the blocker inline, e.g. ``X - blocked by Y`` or ``X - waiting for Z``.
24
+ - Reference the feature doc when an item maps to one, e.g. ``[Mobile Responsive](features/responsive.md) - blocked on ...``.
25
+
26
+ ## What Doesn't Belong On The Roadmap
27
+
28
+ - Specific bugs - they live in [Bugs Template](bugs-template.md).
29
+ - Debt entries - they live in the debt list ([Technical Debt Template](technical-debt-template.md)).
30
+ - "Resolve bugs" or "Fix tech debt" as roadmap items - those are continuous activities, not roadmap goals.
31
+ - Generic "Write unit tests" or "Add tests" - if testing is a priority, name it as an initiative (e.g. `Automated Testing`). Specific test backlogs live in the affected feature's spec.
32
+
33
+ ## The Lists Beside It
34
+
35
+ The inbox, the todo and the plan stand beside the roadmap, each with its own job ([The Simple Workflow](the-simple-workflow.md#the-lists)). Before asking the director whether an unbuilt item is still wanted, check which of them holds it.
36
+
37
+ ## Related
38
+
39
+ - [Workspace Template](../docs/workspace-template.md)
40
+ - [Documentation Philosophy](../docs/documentation-philosophy.md)
41
+ - [Bugs Template](bugs-template.md)
@@ -0,0 +1,44 @@
1
+ # Technical Debt Template
2
+
3
+ `docs/development/tech-debt.md` uses a fixed shape.
4
+
5
+ ## Purpose
6
+
7
+ Catalogs internal debt: infrastructure friction, tooling gaps, missing abstractions. Things developers trip over but real users never see. Distinct from user-facing bugs and third-party feedback - see the split below.
8
+
9
+ ## Why
10
+
11
+ An agent can pick up an entry and start the work from it.
12
+
13
+ ## Bug / Debt / Feedback Split
14
+
15
+ - User-facing symptom -> [Bugs Template](bugs-template.md).
16
+ - Third-party library limitation (even with a workaround) -> [Library Feedback](../docs/library-feedback.md).
17
+ - Anything else internal to our code or infrastructure -> the debt list.
18
+
19
+ ## Sections
20
+
21
+ - Title: `# Technical Debt`.
22
+ - Overview list: flat dash list, one bullet per item, formatted as ``- <description>`` or ``- <description> (`<severity>`)`` when severity applies. Always present. Sorted by severity, highest first (blockers at the top). Items without a severity sit below.
23
+ - Per item: `##` subheading with the title, then the body shape.
24
+
25
+ ## Item Shape
26
+
27
+ - Subheading: `## <concise title>`.
28
+ - Optional severity line right after the title: `Severity: <level>`. Use sparingly: `Blocker` for items actively blocking other work. Other levels (`high`, `medium`, `low`) are optional and used when meaningful.
29
+ - Body: *just enough* to start the work. State what's broken and what success looks like. Brief - one short paragraph, often two sentences.
30
+ - Affected use cases or features can be mentioned briefly when they sharpen the impact. Don't enumerate exhaustively. Readers can follow the spec docs.
31
+
32
+ ## What Doesn't Belong
33
+
34
+ - Code-level prescriptions (e.g. "introduce a single SCSS map with names X, Y, Z"). The code is written when the work begins, while a strategy at the entry's focus level may stand in a line.
35
+ - Detailed mechanism (which classes, which methods, which file). Same reason.
36
+ - Bug-style reproduction steps. If something reproduces with concrete user steps, it's a bug.
37
+
38
+ ## Related
39
+
40
+ - [Bugs Template](bugs-template.md)
41
+ - [Library Feedback](../docs/library-feedback.md)
42
+ - [Workspace Template](../docs/workspace-template.md)
43
+ - [Documentation Philosophy](../docs/documentation-philosophy.md)
44
+ - [No Faux Headers In Lists](../docs/no-faux-headers-in-lists.md)
@@ -0,0 +1,48 @@
1
+ # The Simple Workflow
2
+
3
+ The work is tracked in a few flat lists, and the director asks one question: what's next?
4
+
5
+ ## Why
6
+
7
+ Everything has a place to go, with light organization that stays simple.
8
+
9
+ ## The Lists
10
+
11
+ - Inbox - raw and rough ideas: anything goes in, as a flat list of points, and is easily scrapped
12
+ - Todo - what was decided to do soon
13
+ - Roadmap - the concepts decided on, by priority: what will be done, and what is nice to have when there is time
14
+ - Plan - the active file, with what is in flight now
15
+ - Bugs and debt - the other lists the plan pulls from
16
+
17
+ Every list is a file in `docs/development/`: `inbox.md`, `todo.md`, `roadmap.md`, `plan.md`, `bugs.md` and `tech-debt.md`. A workspace with several apps gives each app a folder of its own in it.
18
+
19
+ ## How To Apply
20
+
21
+ - Put anything new in the inbox.
22
+ - When the director rants, extract one bullet per topic or idea.
23
+ - Move an item to the todo when the director decides to do it soon, or to the roadmap for later.
24
+ - An item still to be workshopped stays in the inbox until the director decides on it.
25
+ - Pull items from the todo into the plan.
26
+ - Pull from the bugs and the debt list into the plan as well.
27
+ - Answer "what's next?" with a recommendation from the lists, in the order of [Dev Tiers](../behavior/dev-tiers.md), and the director picks.
28
+ - What counts as a bug or debt of now depends on where the project is in its lifecycle ([Project Lifecycle](../behavior/project-lifecycle.md)).
29
+
30
+ ## Where A Finding Goes
31
+
32
+ A finding in the middle of other work is filed by its kind ([Note Issues](../behavior/note-issues.md)).
33
+
34
+ - Technical (smell, suppression, deprecated pattern, missing test, missing tool or process) -> the debt list ([Technical Debt Template](technical-debt-template.md)).
35
+ - A clear bug, where the build does not do what its feature doc or spec says -> the bugs list ([Bugs Template](bugs-template.md)).
36
+ - A functional doubt, where the intended behavior itself is unclear -> the inbox, as a question for the director, never a bug and never a fix.
37
+ - A functional doc out of date or wrong, where the fix is small -> the fix rides along with the current work and the report names it.
38
+ - A functional doc out of date or wrong, where the gap is larger -> the inbox.
39
+ - A missing prerequisite -> the plan, above the current item ([Backward-Trace Missing Prerequisites](../behavior/backward-trace-missing-prerequisites.md)).
40
+ - A sweep -> one entry in the debt list that lists every instance ([Sweeps Enumerate Into Tech-Debt First](../behavior/sweeps-enumerate-into-tech-debt-first.md)).
41
+
42
+ ## Related
43
+
44
+ - [Todo Template](todo-template.md)
45
+ - [Plan Template](plan-template.md)
46
+ - [Roadmap Template](roadmap-template.md)
47
+ - [Bugs Template](bugs-template.md)
48
+ - [Technical Debt Template](technical-debt-template.md)