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,96 @@
1
+ # Ticket Template
2
+
3
+ A ticket is one file, the single source of truth for one piece of work. This standard holds its shape. How to fill it is in [Writing A Ticket](writing-a-ticket.md), and the tracking around it in [Work Tracking](work-tracking.md).
4
+
5
+ ## Why
6
+
7
+ Every agent reads a ticket in one shape, and code checks it the same way each time.
8
+
9
+ ## The Template
10
+
11
+ Its filename is the slug of its name ([Work Item Names](work-item-names.md)). It holds two routes, kept apart: the work's, from the current situation (A) to the acceptance criteria (B) with the solution between them, and the user's, the entry points where the user meets the change. Each section answers one question.
12
+
13
+ | Question | Section | Answered well when |
14
+ | --- | --- | --- |
15
+ | What is it? | the summary, under the title, no heading | what should change, in one or two plain sentences a human reads cold ([Writing A Ticket](writing-a-ticket.md)) |
16
+ | Why do we want it? | Why | a bullet per reason, what it gives the user. A law it serves is named |
17
+ | What do we need to know? | Context | the terms a new reader lacks and the relevant facts that do not change, a line each, the feature docs linked |
18
+ | How and when does the user get there? | Entry Points | a bullet per way and moment the user arrives, from every state the user can arrive in. What happens there only when it is a relevant trigger |
19
+ | How is it now? | Current Situation (A) | a bullet per fact the work changes, checked against the product, its feature doc and its history. A bug's reproduce steps, Expected and Actual |
20
+ | How is it when it is done? | Acceptance Criteria (B) | a bullet per check the director can verify by using the product ([Acceptance Criteria](writing-a-ticket.md#acceptance-criteria)) |
21
+ | How do we get there? | Solution | the strategy at the ticket's focus level, a short task per bullet, worked out before the build, never the criteria again, never code or tests |
22
+ | What will the user read? | Content, under Solution | every text that ends up in the product, exactly as it will read |
23
+ | How must it look? | Visual Quality | the ticket's own visual points. The generic ones sit in the project's visual checklist, which the Definition of Done points to |
24
+ | What did an agent decide? | Veto | a decision per bullet, each checked in refinement for what it implies |
25
+ | Can we split it, or leave something out? | Left Out | each part split off into a ticket of its own, or left out with its reason |
26
+ | What could go wrong? | Risks | each risk with its mitigation, decided in refinement: a step inside the ticket when it is small and relevant, a design risk mitigated by design say, otherwise the ticket that closes the gap. A mitigation never grows the ticket's work ([Building A Ticket](building-a-ticket.md#a-ticket-lands-right)) |
27
+ | What does it wait on? | Depends On | the tickets of its own story it waits on |
28
+ | Where did it come from? | Source | the log entries it came from, linked from the root: `/records/log/2026-10-25#_12-57` |
29
+
30
+ ## Sections Per Type
31
+
32
+ Every section of a type's set stands in every ticket of that type, `` `-` `` when empty: a section left out primes the next ticket to leave it out where it matters.
33
+
34
+ | Section | Feature | Bug | Debt | Heal | Docs | Spike | Epic |
35
+ | --- | --- | --- | --- | --- | --- | --- | --- |
36
+ | summary | yes | yes | yes | yes | yes | yes | - |
37
+ | Goal | - | - | - | - | - | - | yes |
38
+ | Source | yes | yes | yes | yes | yes | yes | yes |
39
+ | Why, Context, Current Situation, Acceptance Criteria, Solution | yes | yes | yes | yes | yes | yes | - |
40
+ | Entry Points | yes | yes | - | - | yes | - | - |
41
+ | Content | yes | yes | - | - | - | - | - |
42
+ | Visual Quality | yes | yes | - | - | - | - | - |
43
+ | Veto, Left Out, Risks, Depends On | yes | yes | yes | yes | yes | yes | - |
44
+ | Done: Proof and Veto | yes | yes | yes | yes | yes | yes | - |
45
+
46
+ `## Question` and `## To Refine` stand only while one is open, so their presence keeps a ticket on the refine list.
47
+
48
+ ```
49
+ ---
50
+ id: BUG-31
51
+ epic: <epic-slug>
52
+ story: <story-slug> (when it belongs to one)
53
+ rework: FEAT-214 (the landed ticket it redoes, from the director's findings)
54
+ phase: <phase-slug> (epics only)
55
+ area: <area-slug> (epics only, when it has one)
56
+ priority: high (every ticket but an epic: high, medium, low; the director's call, medium when missing)
57
+ workshop: true (while it needs a workshop or waits on one)
58
+ last: true (a ticket that closes its phase, a phase gate spike say)
59
+ long: true (a ticket kept past about 300 words before Done)
60
+ long-done: true (a Done part kept past about 100 words)
61
+ go: 2026-10-23#_14-05 (the log entry of the director's go, written by the conductor)
62
+ agent: builder-1 (its builder's name as a slug, docs-agent-1 or scout-1 say, written by the conductor)
63
+ feedback: 2026-10-23#_15-10 (while the director's feedback on it is worked in)
64
+ ---
65
+
66
+ # Fix Auth Session Redirect
67
+
68
+ What should change, in one or two plain sentences.
69
+
70
+ ## Goal (epics only, in place of the summary)
71
+ ## Why
72
+ ## Context
73
+ ## Entry Points
74
+ ## Current Situation
75
+ ## Acceptance Criteria
76
+ ## Solution
77
+ ### Content
78
+ ## Visual Quality
79
+ ## Veto
80
+ ## Left Out
81
+ ## Risks
82
+ ## Depends On
83
+ ## Question (only while one is open)
84
+ ## To Refine (only while something is still to spec)
85
+ ## Source
86
+ ## Done (written when it lands)
87
+ ### Proof
88
+ ### Veto
89
+ ```
90
+
91
+ ## Related
92
+
93
+ - [Writing A Ticket](writing-a-ticket.md)
94
+ - [Work Tracking](work-tracking.md)
95
+ - [Work Item Names](work-item-names.md)
96
+ - [Building A Ticket](building-a-ticket.md)
@@ -0,0 +1,30 @@
1
+ # Work Item Names
2
+
3
+ Every name for a piece of work - a ticket's title, a line on the plan or the roadmap, an epic - makes three things clear at a glance: the type of work, the topic, and the direction of the issue or outcome. That is the focus level a top-level list needs. Names are in Title Case.
4
+
5
+ ## Why
6
+
7
+ A list of work reads at a glance.
8
+
9
+ ## Per Type Of Work
10
+
11
+ - A feature reads as a goal from the user's side: `Create An Account`. It names the topic and hints at the outcome.
12
+ - A change to how something behaves names the behavior once it is done, subject first: `Welcome Screen Only Shows Once`. Its name is never the agent's action, such as `Drop The Welcome Screen's Repeats`.
13
+ - An addition leads with its verb: `Add Contact Search`.
14
+ - A fix leads with `Fix`: `Fix Auth Session Redirect` says it is a bug, names the topic and hints at what goes wrong.
15
+ - A spike leads with `Investigate`: `Investigate Multi-Role Editing`, for finding out how something is before a solution is picked.
16
+ - A phase names a step on the product's road: `Pre-Alpha`, `Alpha`, `Beta`.
17
+ - An epic names the common denominator of its tickets: `Save And Load`, `User Onboarding`, `Settings Menu`.
18
+ - A small task is named the way the director said it: `Make The Button Blue`.
19
+
20
+ ## How To Apply
21
+
22
+ - One name everywhere: the ticket's title, its filename slug and every list line linking it carry the same name.
23
+ - A rename updates the file, its slug and every link in the same change.
24
+ - One line, no trailing period, no parenthetical bloat. Detail belongs in the ticket.
25
+
26
+ ## Related
27
+
28
+ - [Work Tracking](work-tracking.md)
29
+ - [A Name Describes Its Unit](../behavior/a-name-describes-its-unit.md)
30
+ - [Name By Concept, Not Copy](../code/name-by-concept-not-copy.md)
@@ -0,0 +1,177 @@
1
+ # Work Tracking
2
+
3
+ A project tracks its work in its own docs, next to the code: a ticket per piece of work, stories and epics grouping tickets, phases grouping epics, lists generated from the tickets, and an archive of what is done. Tickets are data. The lists are views of them.
4
+
5
+ ## Why
6
+
7
+ Tracked next to the code, the work stays up to date with it.
8
+
9
+ ## The Folder
10
+
11
+ ```
12
+ docs/development/
13
+ roadmap.md (by hand)
14
+ plan.md (list generated)
15
+ refine.md (list generated, the director's inbox)
16
+ planning.md (list generated, the director's inbox)
17
+ accept.md (list generated, the director's inbox)
18
+ processing.md (list generated)
19
+ phases/<slug>.md
20
+ areas/<slug>.md
21
+ epics/<id>-<slug>.md
22
+ stories/<id>-<slug>.md
23
+ features/<id>-<slug>.md
24
+ bugs/<id>-<slug>.md
25
+ debt/<id>-<slug>.md
26
+ healing/<id>-<slug>.md
27
+ docs/<id>-<slug>.md
28
+ spikes/<id>-<slug>.md
29
+ archive/<type>/<id>-<slug>.md
30
+ ```
31
+
32
+ ## Types
33
+
34
+ A ticket's type is its folder, and the archive keeps the same folders. No front matter field repeats it.
35
+
36
+ - Feature, in `features`, prefix `FEAT`: what the user gains.
37
+ - Bug, in `bugs`, prefix `BUG`: what goes wrong for the user. User-facing only: what a real user never hits is debt. It describes the symptom as the user meets it, never a guess at the cause, and links its feature doc and spec case.
38
+ - Debt, in `debt`, prefix `DEBT`: the workspace's own code and tooling, its test gaps and its structure. It holds what is broken, what success looks like, and its Solution: the strategy at the ticket's focus level, worked out before the build so the easy way out is ruled out. It never names the classes and files.
39
+ - Heal, in `healing`, prefix `HEAL`: a change to the harness that healing makes, to a standard, a check or a tool ([Always Make No Mistakes](../behavior/always-make-no-mistakes.md)). It has a debt ticket's sections, and lands archived like one. With `healing` automatic, its go comes with it, and the healing subagent builds it at once, off the plan.
40
+ - Docs, in `docs`, prefix `DOCS`: the work on the docs and the work tracking. The wiki's own tooling is code, so Debt.
41
+ - Spike, in `spikes`, prefix `SPIKE`: finding out how something is now, worked by the scout ([Agent Roles](agent-roles.md)).
42
+ - Epic, in `epics`, prefix `EPIC`: a ticket that groups others under one outcome. Its file holds its `phase` field, a `## Goal` section of one short line and a Source, no summary and no acceptance criteria since its tickets hold their own. Which tickets belong to it lives only in each ticket's `epic` field, and the wiki lists them.
43
+
44
+ A ticket's type never changes. Work that turns out to be of another type is a new ticket with an id of its own, and the old ticket is dropped: at once when the director never saw or refined it, otherwise with the director's yes. A new type applies to tickets filed from then on. An existing ticket keeps its type. A product layer may add types of its own, a game's in [Game Work Workflow](../gamedev/game-work-workflow.md).
45
+
46
+ ## Ids
47
+
48
+ Every ticket, every story and every epic carries an id of its own, kept for life, so the director gives a go or a verdict by the id alone.
49
+
50
+ - The id stands in the front matter, `id: FEAT-214`, and the wiki shows it right below the title. The file's name leads with it in lowercase, `feat-214-upload-retries.md`, so a glob finds a ticket by its id.
51
+ - Its prefix says the type. The number counts per prefix, so FEAT-1 and BUG-1 both stand. A new ticket takes one past the highest of its prefix, the archive's included.
52
+ - An id never changes: archiving keeps it, and a list's position never stands for it.
53
+ - Every list line starts with its ticket's id, and the director names a ticket by its id: `FEAT-214 go`, `FEAT-214 accepted`.
54
+ - A ticket's links never depend on where a file lives, so archiving is a `git mv` and nothing else: a ticket is linked through its id, `[DEBT-81](/tickets/DEBT-81)`, which the wiki resolves wherever the file is, and any other page from the wiki's root, `/records/log/2026-10-25#_12-57`.
55
+ - A hygiene check fails two pages sharing an id, a prefix that does not match the page's folder, a file name that does not lead with its id, a link to a ticket by its file path, and a relative link in a ticket.
56
+
57
+ ## The Ticket
58
+
59
+ A ticket is one file in its type's folder. Its sections and front matter are in [Ticket Template](ticket-template.md), how it is written and its criteria in [Writing A Ticket](writing-a-ticket.md), and its Done part in [The Done Part](the-done-part.md).
60
+
61
+ ## Phases
62
+
63
+ A phase is a step on the product's road, one layer above the epic: one goal and the phase gate that closes it, so the work in it serves that goal and nothing else.
64
+
65
+ ```
66
+ # <Phase Name>
67
+
68
+ Goal: the one outcome this phase delivers.
69
+
70
+ Gate: the leading question of the phase gate that ends this phase.
71
+
72
+ ## Done When
73
+
74
+ - One observable condition per bullet.
75
+
76
+ ## Not In It
77
+
78
+ - What waits for a later phase.
79
+ ```
80
+
81
+ - A phase's gate ([Project Lifecycle](../behavior/project-lifecycle.md)) is written as its leading question, with Done When listing what answers it.
82
+ - A hygiene check fails a phase page without its `Gate:` line.
83
+ - Which epics belong to a phase lives only in each epic's `phase` field. The wiki lists them on the phase's page.
84
+ - Anything that does not serve the current phase's goal is filed and waits for its phase, never refined or built early. Bugs and debt too: one that does not hurt the goal waits ([Dev Tiers](../behavior/dev-tiers.md)).
85
+ - A ticket's phase and priority are the director's call. An agent files a finding in the phase where it hurts the goal, a later one unless it hurts the current goal now, and leaves the priority out.
86
+ - A game's phases, in their four stages, are in [Game Phases](../gamedev/game-phases.md).
87
+
88
+ ## Areas
89
+
90
+ An area is a category of the product (the checkout, the UI), one layer above the epic like a phase, which is a step of the road. An area is a page, an epic's `area` field names it, and the wiki lists an area's epics on its page the way it lists a phase's.
91
+
92
+ ## Stories
93
+
94
+ A story is one layer between the epic and the ticket: the unit the director refines, gives a go and accepts, and the unit one builder builds ([Agent Roles](agent-roles.md#the-builder)). The ticket stays the unit of building, small and refined part by part.
95
+
96
+ - A story of product work is a stretch of the product the director uses from start to end.
97
+ - A story of debt or docs is a group of tickets of one epic that share an area and the load of their checks.
98
+ - A debt story gets a go and no verdict: it ends when its last ticket lands. A docs story gets the director's verdict, like a feature, since the director decides what the docs say.
99
+ - A debt story is cut in refinement to be light or heavy, never mixed. A light one needs no browser suite. When each starts is in [Agent Roles](agent-roles.md#how-many).
100
+ - A ticket names its story in its `story` field. A ticket outside any story is the exception, refined, planned and accepted by itself. Loose tickets of one epic are grouped into a story, so they show as one line and get one go and one agent.
101
+ - A story is a page in `stories` with an id of its own, `STORY-8`, and its epic in its `epic` field: what to use and how to start it.
102
+ - The wiki lists a story's tickets on its page from their `story` field, in three lists: to refine, ready and done. A rework ticket carries a rework mark there.
103
+ - A story's done list runs newest first, and each line ends with the date and time its ticket was done, read from its landing commit: `` `2026-12-31` `11:23` ``.
104
+ - The director gives a story's go and verdict by its id: `STORY-8 go`, `STORY-8 accepted`.
105
+ - A story is sized to fit one builder's context. One that does not fit is split in refinement.
106
+ - A ticket waits only inside its story: its Depends On names tickets of its own story, the builder's order. Two tickets outside a story that depend on each other go into a story together.
107
+ - A story can be blocked on a story, the level the go is given at. Its page names the stories it waits on under Depends On, only where the order matters.
108
+ - A block is avoided first: the order is made irrelevant, each story started by itself from a skeleton or a seeded scenario, or the shared piece is extracted into a small story of its own that unblocks both.
109
+ - A blocked story is refined and given its go like any other. It gets no builder until its blocker is accepted, or merged where a debt story gets no verdict.
110
+ - The director's findings on a story become new tickets in it, each tagged with the landed ticket it redoes in its `rework` field, so rework is counted and its causes are found. A landed ticket is never reopened.
111
+
112
+ ## The Lists
113
+
114
+ Every list but the roadmap is a view the wiki generates from the tickets, the way a data loader reads each ticket's folder, front matter and parts at build time, and so are its lists of tickets per folder and per epic. The repository holds the list pages, each with its title and hand-kept sections, and never a generated list, which would go stale. The dev server regenerates a list the moment a file changes. Nobody moves a line by hand: a ticket's place follows from facts written once.
115
+
116
+ The unit of a list is the story. Each story of the current phase stands on exactly one list: the first whose condition it meets, in this order. A ticket outside a story stands on one the same way, as a story of one ticket. Refine is the fallback, so nothing falls through. A story's own tickets show on its page. A later phase's story stands on none. Its epic and phase are its home. An epic stands on none either. The roadmap is its home.
117
+
118
+ - `processing.md` - every story with a ticket that carries a `feedback` field, which keeps it off the director's inboxes until the conductor clears the field.
119
+ - `accept.md` - every story with open tickets, each with a Done part, in landing order read from git. Debt never waits there, since it lands archived.
120
+ - `plan.md` - every story whose tickets not yet landed are all ready, have a `go` and have an agent, one line per story in a section per agent by its tickets' `agent` field, the section's heading read back from the slug, in the roadmap's order of epics. The plan lists stories, never their tickets, which stand on the story's page in the story's order. A story stays on the plan as long as its builder works it, a wait on an answer or on a ticket it filed included. The plan holds only what is active: its generated sections.
121
+ - `planning.md` - every story whose tickets not yet landed are all ready, as one item, in three groups: the stories with a go that wait for an agent, the stories that wait on a go, and `## Blocked`, the stories that wait on a story, each naming its blocker inline (`STORY-12 - blocked by STORY-9`).
122
+ - `refine.md` - every other story of the current phase ([The Refine List](#the-refine-list)). What a ticket still misses is read in the ticket. A builder's question on a ticket in flight lists that ticket here as well, until it is answered.
123
+ - `roadmap.md` - kept by hand, since its order is a decision: every epic, functional and technical alike, a section per phase in the phases' order, each linking its phase page and listing its epics in execution order, then `## Blocked` and `## Waiting For Response` for epics paused on an internal or an external dependency, each naming its blocker inline (`X - blocked by Y`).
124
+ - Every ticket sits in an epic, a new one in its phase where none fits, so it reaches the lists once its phase is current.
125
+ - No backlog and no nice to have list: decided work not yet scheduled waits in its epic and phase.
126
+ - A list line is one line: the ticket's id and a link, never a description, a status or history. The one exception is the landing stamp on a story's done list.
127
+ - A list page holds its title, its list and its hand-kept sections, never a text on how the list works: the rules stand in the standards, once.
128
+ - A hygiene check fails a current-phase ticket whose story stands on no list, or that stands on none by itself, and prose on a list page that explains its list.
129
+ - A hygiene check fails a ticket whose Depends On names a ticket outside its story, and a story whose Depends On names anything but a story.
130
+ - A hygiene check fails more than three tickets of one epic outside a story on the planning page.
131
+ - The plan's logic lives in one module that the wiki's loader and a command-line script share, so an agent reads the plan without the wiki.
132
+ - An agent finds tickets with `ls` and a grep on the front matter, never by reading a whole folder.
133
+ - Continuous activities ("Resolve bugs", "Add tests") are never items. A testing push is an epic with a name of its own.
134
+ - Before asking the director whether an unbuilt item is still wanted, check for its ticket in its epic.
135
+
136
+ ## The Refine List
137
+
138
+ - Per ticket, the generated list checks what code can of the Definition of Ready: every section of its type's set present, a criterion at least, a Source, no `## Question`, no `## To Refine`, and no workshop mark.
139
+ - A ticket's readiness never looks at another ticket.
140
+ - A ticket written before a template change passes on the sections of its own time.
141
+ - A ticket an agent judges not ready for any other reason gets a `## To Refine` section naming what is still to spec, so the list catches it too.
142
+ - A ticket's phase is its epic's. A ticket outside an epic is never on the list.
143
+ - A story being built or reworked stands first.
144
+ - The rest runs in the roadmap's order of epics, under each epic its stories, linked, with their tickets not yet ready, then its tickets outside a story.
145
+ - A story leaves once every ticket of it is ready.
146
+ - The list ends with a `## Last In Phase` section: every ticket marked `last` until each unmarked ticket of its phase is archived.
147
+ - A blocked story's tickets are read again once its blocker is accepted, since what the blocker settled can change them.
148
+
149
+ ## The Open Questions
150
+
151
+ A question lives in the ticket that has the unclarity, under `## Question`: the one thing to decide in a plain sentence, then short options, each answerable without opening another doc and one of them recommended with its reasons, then where it came from. The refine list shows every current ticket with a question. A question is never asked only in chat.
152
+
153
+ - Weigh a question before asking it: when one option is the status quo and the other has no gain the director would feel, keep the status quo and ask nothing.
154
+ - Tell the moment the way the user meets it, never by a doc's or an agent's name for it.
155
+ - A question listing several items explains each one: what it is as the user meets it, where it stands today, and what each answer changes.
156
+ - Options that are sounds, clips or pictures put the sample beside each one.
157
+ - Every claim in a question is checked, and says how it was checked. The ticket's Source entries are read first, so a question the log already answers is never asked.
158
+ - An answer is logged, moved into the docs or tickets it decides, and the question dropped.
159
+ - A question that blocks a builder, or whose answer changes other tickets, names them and goes to the director at once, through the conductor. It never waits for a refinement.
160
+ - While a builder is blocked, the conductor can start another builder on ready work.
161
+
162
+ ## The Archive
163
+
164
+ - A ticket is archived at the director's verdict on it or on its story, a debt or heal ticket at its landing: a `git mv` to `archive/<type>/`, which is the verdict's whole bookkeeping, since every list follows by itself.
165
+ - A version's changelog lists the tickets that landed in it, generated ([Changelog Per Version](../records/changelog-per-version.md)).
166
+ - A story page is archived with its last ticket, at its verdict, or a debt story's at its last landing, to `archive/stories/`.
167
+ - A dropped ticket is archived at once, and a workshop's ticket once its outcome is ready tickets, so no id is used twice. An epic is archived with its last ticket.
168
+ - Archived tickets are never edited again. More work on the same topic, a rework included, is a new ticket.
169
+
170
+ ## Related
171
+
172
+ - [Work Workflow](work-workflow.md)
173
+ - [Work Item Names](work-item-names.md)
174
+ - [Commits](../commits/commits.md)
175
+ - [Don't Introduce Tech Debt](../behavior/dont-introduce-tech-debt.md)
176
+ - [Plans Vs Persistent Files](../simple-workflow/plans-vs-persistent-files.md)
177
+ - [Docs State Knowledge](../docs/docs-state-knowledge.md)
@@ -0,0 +1,123 @@
1
+ # Work Workflow
2
+
3
+ Every piece of work takes one path: the director's words are logged, turned into tickets and refined until ready, given a go, built from the plan, checked against the Definition of Done, accepted and archived. The director's time goes to the creative side, steering, deciding and testing the product. Everything between the director's words and a landed, provable change is the agents' job. Refinement should feel like play: its chores are automated step by step, by code where code can decide and by an agent's judgment where it cannot.
4
+
5
+ This policy is strict on purpose. It starts as a best guess and tightens itself: see Tightening at the end. The ticket's shape is in [Ticket Template](ticket-template.md), its tracking in [Work Tracking](work-tracking.md), the agents' roles in [Agent Roles](agent-roles.md), the main session's in [The Conductor](the-conductor.md), and what changes for a game in [Game Work Workflow](../gamedev/game-work-workflow.md).
6
+
7
+ ## Why
8
+
9
+ The director is free for judgment, taste and creation.
10
+
11
+ ## Intake
12
+
13
+ Every message from the director runs through these steps before any work on it starts.
14
+
15
+ - Log it first ([Request Log](../records/request-log.md)).
16
+ - Split it into units: one unit is one thing to do, to decide or to remember. Each unit of work goes straight into a ticket, which links its log entry under Source. Nothing sits between the log and the tickets.
17
+ - Classify every unit in the same pass ([Classifying A Unit](#classifying-a-unit)).
18
+ - Turn each unit of work into a ticket that meets the Definition of Ready. A unit that needs no explanation becomes a short ticket, its empty sections `` `-` ``. The ticket holds the director's words parsed, never extended ([Docs Hold Only What The Director Decided](../behavior/docs-hold-only-what-the-director-decided.md)). A unit that cannot be made ready yet becomes a ticket all the same, with its question.
19
+ - A new epic gets its phase ([Work Tracking](work-tracking.md#phases)). Work that does not serve the current phase's goal is filed for its own phase.
20
+ - Schedule it where the director named. Without a name: a bug or debt that hurts the current phase's goal goes into an epic of the current phase, and any other waits in its epic in a later phase ([Dev Tiers](../behavior/dev-tiers.md)). Something new while a version stabilizes goes into its epic ([Stabilize Before Adding](stabilize-before-adding.md)). "For later", "after the release" and "feedback for now" land in their epic and phase, built later and never parked. Anything else lands in its epic and phase, a new epic in its phase where none fits, and the report says so.
21
+ - Report: a line per ticket created, its id, its context and a title of a few words ([The Conductor](the-conductor.md#what-it-says)). The agent's own decisions stand in the ticket's Veto section.
22
+
23
+ ### Classifying A Unit
24
+
25
+ - A feature, a bug, a piece of debt, a piece of docs work, a spike or an epic is work.
26
+ - An undecided idea becomes a ticket in its epic, its open point under Question, unless it is a maybe to investigate now ([A Maybe Is A Trigger To Investigate](../behavior/a-maybe-is-a-trigger-to-investigate.md)). A later phase's idea gets its ticket with the director's words and little more, refined once its phase comes.
27
+ - A question for the director goes into the ticket it is about, under Question, which puts the ticket on the refine list.
28
+ - An answer to an open question goes where [Work Tracking](work-tracking.md#the-open-questions) says.
29
+ - Feedback from someone outside the project waits for the director's review before it becomes work.
30
+ - An instruction about how to work goes to the project's docs, or into the project's standards once the director says it holds everywhere.
31
+
32
+ ## Where A Finding Goes
33
+
34
+ A finding in the middle of other work is filed by its kind ([Note Issues](../behavior/note-issues.md)). Every ticket follows [Work Tracking](work-tracking.md).
35
+
36
+ - Technical (smell, suppression, deprecated pattern, missing test, missing tool or process) -> a debt ticket.
37
+ - A clear bug, where the build does not do what its feature doc or spec says -> a bug ticket.
38
+ - A functional doubt, where the intended behavior itself is unclear -> a question in the ticket it is about, which the refine list shows ([Work Tracking](work-tracking.md#the-open-questions)), never a bug ticket and never a fix.
39
+ - A functional doc out of date or wrong (feature doc, spec) -> a small fix rides on the current ticket's go as a Veto line. A larger gap is a docs ticket.
40
+ - A missing prerequisite -> a ticket of its own, named in the current ticket's Depends On, so the builder takes it first once it has its go ([Backward-Trace Missing Prerequisites](../behavior/backward-trace-missing-prerequisites.md)).
41
+ - A sweep -> one debt ticket that lists every instance, or an epic when the sweep is too big for one item ([Sweeps Enumerate Into Tech-Debt First](../behavior/sweeps-enumerate-into-tech-debt-first.md)).
42
+ - A ticket filed this way lands in the phase where it hurts the goal, a later one unless it hurts the current goal now ([Dev Tiers](../behavior/dev-tiers.md)), and stays unscheduled until the director plans it. The report names it.
43
+
44
+ ## The Go
45
+
46
+ Everything needs the director's go before it is built: a feature, a bug, docs work, a spike, debt, a rework, and the main session's own small change.
47
+
48
+ - The go is given at a planning, by id, by a story's id for every ticket in it, or in one word for all that is ready, and the conductor writes its log entry into each ticket's `go` field. A story with its go waits on the planning page until the conductor assigns its builder, which puts it on the plan.
49
+ - An answer to a question on a ticket in flight is its builder's go on. An answer in refinement makes the ticket ready, and its go comes at the planning.
50
+ - An ask is never the go: the ticket written from it goes on the planning page, and only a go and an agent put it on the plan.
51
+ - Once a ticket has its go, it is built and lands without asking again.
52
+ - Automatic healing files a heal ticket that carries its go, and the report names it for a veto ([Work Tracking](work-tracking.md#types)).
53
+ - A violation found mid-change is fixed or noted as [Don't Introduce Tech Debt](../behavior/dont-introduce-tech-debt.md) says, and a noted one becomes a debt ticket.
54
+ - The one exception sits at the end of the path: a debt ticket needs no acceptance.
55
+
56
+ ## Definition Of Ready
57
+
58
+ A ticket is ready to be scheduled and built when every one of these holds. The work goes into getting the ticket right up front: a well-described ticket lands once, a vague one comes back for rounds of tweaks.
59
+
60
+ - Its name follows [Work Item Names](work-item-names.md).
61
+ - Every section of its type's set is answered, `` `-` `` for an empty one ([Ticket Template](ticket-template.md#sections-per-type)).
62
+ - What the work is and why is clear from the ticket alone, without the chat.
63
+ - Its acceptance criteria are written, each one observable ([Writing A Ticket](writing-a-ticket.md#acceptance-criteria)).
64
+ - Its premise was checked against the feature doc and the log: a bug that contradicts a fact the feature doc states is a question for the director, and between two dated words the newest wins.
65
+ - Nothing is left for an agent to make up: no number, name or look the director has not decided or seen under Veto.
66
+ - Every question that decides what gets built is answered.
67
+ - It is the smallest piece that gives an actual feature. Anything larger becomes a story of smaller tickets.
68
+ - It belongs to the current phase.
69
+ - The tickets it waits on are named, each of its own story ([Work Tracking](work-tracking.md#stories)).
70
+
71
+ ## Building
72
+
73
+ A ticket with its go is built from the plan and checked against the Definition of Done. Both are in [Building A Ticket](building-a-ticket.md), the builder's page.
74
+
75
+ ## Refinement
76
+
77
+ A refinement makes the current phase's tickets ready, one story from the refine list at a time, its tickets' questions together. Only the current phase is refined: the director's attention goes to what this phase needs, and a later phase refined now is refined again once things change.
78
+
79
+ - The refine list carries links alone, and the chat points to it without repeating what a ticket holds. The director works from the ticket, its questions shaped as [Work Tracking](work-tracking.md#the-open-questions) says.
80
+ - A scheme, a mechanic or an idea grown big enough to discuss gets a ticket of its own, so a ticket never carries several at once.
81
+ - Answers go where [Work Tracking](work-tracking.md#the-open-questions) says, and a ticket that passes leaves the refine list by itself.
82
+ - Unblock as much as possible: a question goes into a ticket only when its choice is costly to undo or the director's words leave it open. A point whose recommended answer follows from the docs and is cheap to change is decided by the agent and written under Veto, so the ticket stays ready.
83
+ - Every Veto line is checked for what it implies: a decision that grows the work or reaches into another feature becomes a question, or a ticket of its own.
84
+ - Whatever has to be found out about how things are now is a spike for the scout, so refinement itself stays fast.
85
+ - A risk's mitigation is decided in refinement, with the director. It is never left for the builder.
86
+
87
+ ## Grooming, Planning And Acceptance
88
+
89
+ The director steers, decides and accepts. The agents groom.
90
+
91
+ - Grooming runs in the background, without the director's focus: agents write the tickets in the template, check them by code and by judgment, and turn what only the director can decide into one question each.
92
+ - The checks come in two layers. Code checks the structure: every section of the type's set present, the id and its prefix, the phase current, the dependencies inside the ticket's own story. An agent checks the rest: the current situation against the product, the entry points from every state the user can arrive in, the criteria functional, single and matching the goal, the ticket against its feature doc, each fact said once, vague words, whether it can be split.
93
+ - A ticket held back from the planning page carries its reason in itself, under To Refine or as a workshop mark, so the readiness check keeps it on the refine list.
94
+ - A bug that does not reproduce at first is traced, never handed back as a question: every route to the reported state is tried, each seeded scenario, a fresh start after other stored data in the same session, the state a service keeps across a fresh start, and every build the director uses, since builds can write their state at different moments. Only what no run can find goes to the director.
95
+ - The planning page lists every story whose tickets are all ready ([Work Tracking](work-tracking.md#the-lists)), links alone, each after its id. The director reads the tickets.
96
+ - A planning is a final check: go or no go. A little question can still be settled there. Anything structural or undecided belongs to refinement first.
97
+ - The template keeps changing, so a ticket is checked against the latest template the moment it goes on the planning page, never in a sweep. A ticket written before a change keeps its shape until it comes up.
98
+ - Once its builder meets the Definition of Done, a ticket is done on its story's branch with its Done part. The story lands on main once every ticket in it is done, in one merge, and reaches the accept list. A ticket outside a story lands on its own. The director accepts a story, never a ticket of one: on main, by using it through from its page with the Done parts beside it, and never checks out a branch. The story's builder and branch are kept until the verdict.
99
+ - A debt ticket never waits on the accept list: the workspace's own code and tooling cannot be checked by using the product, so a verdict adds a step and no check. Work that changes what the user sees or hears is a feature or a bug by its nature, and is filed as one ([Work Tracking](work-tracking.md#types)).
100
+ - An accepted story ends its builder, and its branch goes as [Parallel Agents](../tooling/parallel-agents.md#cleanup) says. The archive follows [Work Tracking](work-tracking.md#the-archive). The director writes findings in the chat as they come, and the conductor sorts them into new tickets in the story, each with `priority: high` and a `rework` field. Once done with findings, the director gives the story's go, which starts the rework. The story returns to the accept list once it lands, and the cycle repeats until the story is accepted. A landed ticket is never reopened.
101
+ - Work that comes back a second time gets an investigation into why its refinement missed: a spike, or a change to the standards when the cause is the workflow.
102
+ - The director's work comes down to three inboxes: the refine, the planning and the accept lists. Their order runs right to left, finishing before starting: accept what landed, then plan enough work to keep the builders working, and only then refine and brainstorm. A session to braindump or prototype has a normal priority.
103
+
104
+ ## Spikes, Workshops And Experiments
105
+
106
+ Sometimes the right first step is to find out or to try something. That is fine, and it is always named as such before it starts.
107
+
108
+ - A spike finds out how something is now: its criteria are the questions it must answer, the scout works it, and its findings stand in its Done part. A ticket it informs states the facts it needs and links the spike under Source. A ticket that turns out to need finding out first gets a spike of its own under Depends On. It never changes type.
109
+ - A workshop is refinement: it is held with the director from the refine list, never from the plan, and its outcome is ready tickets, after which it is archived. Whatever needs the director's picks is a workshop and stays on the refine list.
110
+ - A proof of concept or an experiment goes on the plan like any ticket, its criteria the learnings it must bring, and stays apart from the product's code ([Prototype Mode Is Speed First](../behavior/prototype-mode-is-speed-first.md)).
111
+ - Each ends with its findings turned into tickets and refined like any other.
112
+ - Unnamed, work follows the full path.
113
+
114
+ ## Tightening
115
+
116
+ This policy is a starting point. Every deviation that happens anyway is a gap in it, never a one-off: fix the work, then heal the harness the way `healing` says ([Always Make No Mistakes](../behavior/always-make-no-mistakes.md)). A rule that only adds friction and catches nothing is loosened, with the director's yes. A Veto line that keeps coming back is a pattern and becomes a rule, so the Veto empties over time. The aim is to automate every step that needs no human, once it runs right by hand.
117
+
118
+ ## Related
119
+
120
+ - [Work Tracking](work-tracking.md)
121
+ - [Agent Roles](agent-roles.md)
122
+ - [Building A Ticket](building-a-ticket.md)
123
+ - [Always Make No Mistakes](../behavior/always-make-no-mistakes.md)
@@ -0,0 +1,50 @@
1
+ # Writing A Ticket
2
+
3
+ How a ticket's sections are filled. The sections themselves are in [Ticket Template](ticket-template.md).
4
+
5
+ ## Why
6
+
7
+ A builder can build from the ticket alone.
8
+
9
+ ## Style
10
+
11
+ - Say each fact once: it stands in the one section that owns it, and no other section restates it. The criteria own what must be true, the Solution owns the how, the Done part shows what was achieved.
12
+ - One line per bullet. A point with parts gets a subsection of its own. Nested bullets are allowed but strongly discouraged.
13
+ - The summary says what should change, with should, since a ticket is a change. The end state in the present tense belongs to the criteria. It keeps its articles and reads cold to a human, never like an agent's footnote.
14
+ - Elsewhere articles and filler words go. A concept goes by its name in words, never by a session's or a doc's shorthand.
15
+ - An empty section is the dash in backticks, `` `-` ``, since a bare dash renders as an empty bullet.
16
+ - The summary, Why, Current Situation, Acceptance Criteria and Source always hold a real answer.
17
+ - History stays behind the Source link.
18
+ - Every check runs on every ticket. An answer is never skipped because the tickets before it had the same one.
19
+ - Past about 300 words before Done a ticket counts as long, headings and the dash of an empty section not counted, and the agent grooming it ([Agent Roles](agent-roles.md)) trims it unless the length is necessary. A ticket kept long carries `long: true`, which a hygiene check requires. A long ticket never loses an important point, and never splits for its length alone.
20
+ - A small ticket is always better ([Definition Of Ready](work-workflow.md#definition-of-ready)): it is easy to place, waits on less, is fast to build and easy to accept.
21
+ - The Current Situation is written first. A ticket asking for something built already shows it there and never reaches the plan.
22
+ - Left Out holds decisions only. Something built already or decided elsewhere is refined away. An unsure split is a Question.
23
+ - The ticket is functional. Tests, specs, docs and code are the Definition of Done and the builder's.
24
+ - A ticket describes the work. The product is described in its feature docs, which a feature ticket updates. A feature doc links the ticket of a part not built yet beside its `(Not Yet Implemented)` mark. A hygiene check flags a mark whose ticket is archived, the cue to update the doc.
25
+
26
+ ## Acceptance Criteria
27
+
28
+ What must be observably true, from the user's side, for the work to count as done.
29
+
30
+ - One check per bullet, never compound: "glows while, and stops once" is two criteria.
31
+ - A spec line: the moment, then what you see, "when you open the settings, the volume shows its last value".
32
+ - A criterion states the rule for every case it covers, never one case alone.
33
+ - No test kind, spec id or doc in a criterion.
34
+ - No vague word ("properly", "where needed", "nice") without a measure.
35
+ - A criterion that needs a measurement names one that settles in a single run. A measure not yet proven gets a spike first.
36
+ - At least one criterion shows the change against today.
37
+ - Every fact in the Current Situation has its criterion.
38
+ - A bug: the reproduce steps now give the Expected.
39
+ - Debt: the state that shows the debt is gone.
40
+ - A spike: the questions it must answer, one per bullet.
41
+
42
+ ## The Done Part
43
+
44
+ Its own page is [The Done Part](the-done-part.md).
45
+
46
+ ## Related
47
+
48
+ - [Work Tracking](work-tracking.md)
49
+ - [Things Of One Kind Are Consistent](../behavior/things-of-one-kind-are-consistent.md)
50
+ - [Don't Introduce Tech Debt](../behavior/dont-introduce-tech-debt.md)
@@ -0,0 +1,20 @@
1
+ # Browser Captures Go To Disk
2
+
3
+ A capture taken in the browser pane (a canvas `toDataURL`, a base64 image) is written to disk by a script from the tool's saved result, never transcribed by the agent into a command.
4
+
5
+ ## Why
6
+
7
+ A capture is proof, so it reaches the disk byte for byte.
8
+
9
+ ## How To Apply
10
+
11
+ - Return the base64 padded past the inline limit (a long run of spaces), so the result lands in a file. Extract it with a regex on the base64 alphabet and decode with node.
12
+ - Pixel art captures at native size, then nearest-neighbor upscaled with ffmpeg (`scale=W:H:flags=neighbor`), flattened onto the app's ground color when the canvas is transparent.
13
+ - Review every capture with the image reader before it lands on a page ([Review Every Capture Before Reporting](../behavior/review-every-capture-before-reporting.md)).
14
+ - When the project has a Playwright suite, the capture scripts there are the way ([Use The E2E Pipeline For Browser Probing](../e2e/use-the-e2e-pipeline-for-browser-probing.md)).
15
+ - A base64 string transcribed by hand comes out as a corrupted PNG, or as a made-up stand-in. The browser tools save a large result to a file, and a script decodes it from there without the bytes entering the context.
16
+
17
+ ## Related
18
+
19
+ - [Captures And Reels](../gamedev/captures-and-reels.md)
20
+ - [Always Make No Mistakes](../behavior/always-make-no-mistakes.md)
@@ -0,0 +1,19 @@
1
+ # Check Where A Pane Click Landed
2
+
3
+ A click in the browser pane that does nothing is first a question of where it landed, then a question about the app. Log the pointer's position on the page, or click the control through its reference or a script, before calling the control unresponsive.
4
+
5
+ ## Why
6
+
7
+ Time goes only into bugs that are real.
8
+
9
+ ## How To Apply
10
+
11
+ - Put a capture listener on pointerdown and click, logging clientX and clientY and the target, before trusting a coordinate click.
12
+ - After an emulated viewport, set it again or go back to the pane's own size and take a fresh screenshot before clicking by coordinates.
13
+ - A real bug hunt in the app belongs in a Playwright probe anyway.
14
+ - When the pane drops its viewport emulation, the screenshot's frame no longer matches the page, and a coordinate click lands off the control while the app works fine.
15
+
16
+ ## Related
17
+
18
+ - [Use The E2E Pipeline For Browser Probing](../e2e/use-the-e2e-pipeline-for-browser-probing.md)
19
+ - [Browser Captures Go To Disk](browser-captures-go-to-disk.md)
@@ -0,0 +1,19 @@
1
+ # Defer Tooling Until The Cost Shows Up
2
+
3
+ Don't add heavyweight tooling (reporting dashboards, contract testing, visual regression, accessibility automation, monitoring SaaS) preemptively. Wait until the cost of not having it becomes concrete, then add it.
4
+
5
+ ## Why
6
+
7
+ The project carries only the weight it needs.
8
+
9
+ ## How To Apply
10
+
11
+ - Don't pre-commit to heavyweight tooling as "phase 2" or "we'll add it later" - that signals it's coming, which it isn't until the cost is concrete.
12
+ - When evaluating a tool, name the specific cost that justifies it. "Drift is happening and the mock layer no longer reflects production" beats "we should probably add contract testing".
13
+ - Maturity bumps the threshold. As a workspace climbs the [Workspace Levels](../docs/workspace-levels.md), lighter alternatives start to visibly fail. That is the signal heavy tools have earned their keep, never a calendar milestone.
14
+ - Tooling carries weight: setup, a learning curve, an integration surface, CI minutes and maintenance.
15
+
16
+ ## Related
17
+
18
+ - [Workspace Levels](../docs/workspace-levels.md)
19
+ - [Lightweight Test Reporting Only](lightweight-test-reporting-only.md)
@@ -0,0 +1,19 @@
1
+ # Develop Against Mocks
2
+
3
+ Daily development runs against mocks: auth, user identity, app context, API responses. A real backend stays out of it, and is proved as [Test The System Behind A Mock](../tests/test-the-system-behind-a-mock.md) says.
4
+
5
+ ## Why
6
+
7
+ Mocks make testing automated and repeatable, and development smoother.
8
+
9
+ ## How To Apply
10
+
11
+ - A configurable mock layer covers every external system: identity provider, user/claims, app context, backend API, third parties.
12
+ - Enabling and disabling mocks is a single toggle. Mock state is the default in local configurations.
13
+ - Mocks are committed code, encapsulated outside the code they stub ([Non-Destructive Documenting And Test Automation](../behavior/non-destructive-documenting-and-test-automation.md)). The thing being mocked stays untouched.
14
+ - New mockable behavior extends the existing mock layer. Never fork a one-off bypass or inline a dev-mode conditional.
15
+ - A temporary hack inside a guard, service, or interceptor is the wrong tool. Promote it to the mock layer or note it ([Note Issues](../behavior/note-issues.md)).
16
+
17
+ ## Related
18
+
19
+ - [Test The System Behind A Mock](../tests/test-the-system-behind-a-mock.md)
@@ -0,0 +1,18 @@
1
+ # Hygiene Tests Run On Their Own Runner
2
+
3
+ Source hygiene checks (import boundaries, banned legacy APIs, dead components, TODO trails) are plain vitest specs that read the source tree with node's file system, kept in their own top-level folder with their own vitest config in the node environment and their own npm script. They never go through the framework's unit-test builder, which bundles specs for a browser-like environment where node modules are not available.
4
+
5
+ ## Why
6
+
7
+ A separate, tiny config runs in milliseconds and stays independent of the app build.
8
+
9
+ ## How To Apply
10
+
11
+ - Put the checks in `hygiene/` with a `vitest.hygiene.config.ts`, script `test:hygiene`, and add it to the pre-push chain.
12
+ - Resolve relative imports against the file's directory before judging a layer crossing. A subfolder named like a layer (`ui/core`) otherwise triggers false positives.
13
+ - Each rule sweeps the whole tree and reports offenders as a list, so a failure names every file to fix.
14
+
15
+ ## Related
16
+
17
+ - [Always Verify Before Reporting Done](../behavior/always-verify-before-reporting-done.md)
18
+ - [Code Review Compounds Into Patterns And Sweeps](../behavior/code-review-compounds-into-patterns-and-sweeps.md)
@@ -0,0 +1,16 @@
1
+ # Lightweight Test Reporting Only
2
+
3
+ Test reporting should show whether the suite is green right now, nothing more. Skip tools that add severity matrices, epic/feature grouping, history graphs, or flaky-test detection.
4
+
5
+ ## Why
6
+
7
+ What matters is a fast, reliable signal: did it pass, did it fail, and where.
8
+
9
+ ## How To Apply
10
+
11
+ - Pick the reporter that maximizes speed, consistent output, and reliable signal - usually the test runner's own.
12
+ - Add small custom reporters only when they answer a concrete question, like click count per flow.
13
+
14
+ ## Related
15
+
16
+ - [Defer Tooling Until The Cost Shows Up](defer-tooling-until-the-cost-shows-up.md)