@rt-tools/agent-kit 0.3.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (201) hide show
  1. package/README.md +194 -30
  2. package/assets/agents/business-analyst.md +74 -0
  3. package/assets/agents/project-manager.md +70 -0
  4. package/assets/agents/qa-engineer.md +72 -0
  5. package/assets/agents/skill-curator.md +110 -0
  6. package/assets/agents/spec-critic.md +44 -0
  7. package/assets/agents/spec-writer.md +50 -0
  8. package/assets/checks/board.github.mjs +286 -0
  9. package/assets/checks/check-board.github.mjs +188 -0
  10. package/assets/checks/check-doc-paths.mjs +163 -0
  11. package/assets/checks/check-dupes.mjs +277 -0
  12. package/assets/checks/check-lib-layers.mjs +573 -0
  13. package/assets/checks/check-reuse.mjs +208 -0
  14. package/assets/checks/check-schema-drift.mjs +186 -0
  15. package/assets/checks/check-specs.mjs +1007 -0
  16. package/assets/checks/check-styles.mjs +109 -0
  17. package/assets/checks/rt-kit-checks.config.mjs +134 -0
  18. package/assets/checks/task-new.github.mjs +198 -0
  19. package/assets/commands/skill-curator.md +70 -0
  20. package/assets/defaults/gate-map.sh +100 -0
  21. package/assets/defaults/project.sh +179 -0
  22. package/assets/hooks/browser-device-id.sh +0 -0
  23. package/assets/hooks/browser-guard-device-id.sh +2 -1
  24. package/assets/hooks/browser-guard-no-asking.sh +27 -0
  25. package/assets/hooks/browser-guard-no-listing.sh +2 -1
  26. package/assets/hooks/browser-guard-no-other-drivers.sh +2 -1
  27. package/assets/hooks/browser-guard-require-select.sh +2 -1
  28. package/assets/hooks/commit-msg.sh +1 -1
  29. package/assets/hooks/constitution-index.sh +5 -4
  30. package/assets/hooks/dev-server-guard.sh +8 -6
  31. package/assets/hooks/docs-guard.sh +223 -37
  32. package/assets/hooks/git-guard-delivery.sh +86 -29
  33. package/assets/hooks/git-guard-main.sh +1 -0
  34. package/assets/hooks/git-guard-push-tests.sh +34 -13
  35. package/assets/hooks/glossary-load.sh +23 -0
  36. package/assets/hooks/lint-after-edit.sh +155 -30
  37. package/assets/hooks/qa-dataid-guard.sh +72 -32
  38. package/assets/hooks/reuse-first-guard.sh +105 -34
  39. package/assets/hooks/skill-gate-rearm.sh +1 -0
  40. package/assets/hooks/skill-gate.sh +75 -15
  41. package/assets/hooks/skill-loaded.sh +1 -0
  42. package/assets/hooks/sql-guard.sh +606 -56
  43. package/assets/hooks/task-context-load.sh +100 -0
  44. package/assets/hooks/task-flow-guard.sh +107 -0
  45. package/assets/laws/{access.md → application/access.md} +1 -4
  46. package/assets/laws/{locales.md → application/locales.md} +1 -3
  47. package/assets/laws/application/money.md +41 -0
  48. package/assets/laws/application/ownership.md +32 -0
  49. package/assets/laws/{search-visibility.md → application/search-visibility.md} +1 -1
  50. package/assets/laws/code-structure.md +7 -6
  51. package/assets/laws/delivery.md +53 -3
  52. package/assets/laws/entity-editing.md +49 -55
  53. package/assets/laws/entity-models.md +4 -14
  54. package/assets/laws/frontend-application.md +5 -5
  55. package/assets/laws/lib-imports.md +14 -1
  56. package/assets/laws/lists.md +33 -0
  57. package/assets/laws/navigation.md +40 -0
  58. package/assets/laws/project-documentation.md +17 -8
  59. package/assets/laws/reuse-first.md +26 -21
  60. package/assets/laws/shared-code.md +13 -1
  61. package/assets/laws/verifiability.md +17 -1
  62. package/assets/laws/work-conduct.md +48 -0
  63. package/assets/patterns/admin-lists-screen.md +131 -0
  64. package/assets/patterns/admin-nav-item.md +71 -0
  65. package/assets/patterns/angular-patterns-state.md +29 -22
  66. package/assets/patterns/api-layer-pair.md +40 -30
  67. package/assets/patterns/browser-verification-measure.md +41 -38
  68. package/assets/patterns/browser-verification-stand.md +106 -42
  69. package/assets/patterns/component-structure-new.md +33 -32
  70. package/assets/patterns/dependencies-upgrade.md +65 -0
  71. package/assets/patterns/doc-style-sweep.md +65 -28
  72. package/assets/patterns/doc-style-write.md +36 -33
  73. package/assets/patterns/entity-aside.md +136 -0
  74. package/assets/patterns/entity-models-new.md +124 -0
  75. package/assets/patterns/entity-store.md +91 -0
  76. package/assets/patterns/git-workflow-commit.azure.md +259 -0
  77. package/assets/patterns/git-workflow-commit.github.md +333 -0
  78. package/assets/patterns/git-workflow-commit.gitlab.md +283 -0
  79. package/assets/patterns/git-workflow-merge.md +42 -25
  80. package/assets/patterns/git-workflow-migration.md +61 -31
  81. package/assets/patterns/git-workflow-restart.md +20 -20
  82. package/assets/patterns/lib-layers-move.md +50 -32
  83. package/assets/patterns/lib-layers-new.md +41 -29
  84. package/assets/patterns/ownership-scope-resolve.md +69 -0
  85. package/assets/patterns/permissions-procedure.md +35 -33
  86. package/assets/patterns/platform-access-di.md +39 -25
  87. package/assets/patterns/pricing-quote.md +71 -0
  88. package/assets/patterns/reuse-first-extend.md +22 -22
  89. package/assets/patterns/seo-page.md +52 -40
  90. package/assets/patterns/seo-verify.md +48 -29
  91. package/assets/patterns/shared-code-new.md +37 -31
  92. package/assets/patterns/spec-driven-domain.md +44 -37
  93. package/assets/patterns/spec-driven-rule.md +55 -40
  94. package/assets/patterns/styling-bem-component.md +43 -32
  95. package/assets/patterns/styling-bem-layout.md +30 -24
  96. package/assets/patterns/task-flow-close.md +90 -0
  97. package/assets/patterns/task-flow-resume.md +94 -0
  98. package/assets/patterns/task-flow-start.md +117 -0
  99. package/assets/patterns/testing-e2e.md +53 -51
  100. package/assets/patterns/testing-unit.md +70 -46
  101. package/assets/patterns/translations-key.md +32 -19
  102. package/assets/patterns/ts-procedure.md +24 -25
  103. package/assets/rules/angular-patterns.md +46 -27
  104. package/assets/rules/api-layer.md +46 -28
  105. package/assets/rules/browser-verification.md +66 -48
  106. package/assets/rules/component-structure.md +43 -27
  107. package/assets/rules/dependencies.md +66 -0
  108. package/assets/rules/doc-style.md +81 -39
  109. package/assets/rules/entity-conventions.md +78 -0
  110. package/assets/rules/entity-models.md +70 -0
  111. package/assets/rules/git-workflow.azure.md +116 -0
  112. package/assets/rules/git-workflow.github.md +123 -0
  113. package/assets/rules/git-workflow.gitlab.md +113 -0
  114. package/assets/rules/lib-layers.md +56 -30
  115. package/assets/rules/lists.md +73 -0
  116. package/assets/rules/navigation.md +78 -0
  117. package/assets/rules/ownership-scope.md +63 -0
  118. package/assets/rules/permissions.md +43 -25
  119. package/assets/rules/platform-access.md +57 -29
  120. package/assets/rules/pricing.md +64 -0
  121. package/assets/rules/reuse-first.md +57 -43
  122. package/assets/rules/seo.md +51 -30
  123. package/assets/rules/shared-code.md +51 -26
  124. package/assets/rules/spec-driven.md +96 -50
  125. package/assets/rules/styling-bem.md +54 -39
  126. package/assets/rules/task-flow.md +110 -0
  127. package/assets/rules/testing.md +78 -47
  128. package/assets/rules/translations.md +48 -31
  129. package/assets/rules/typescript-conventions.md +57 -27
  130. package/assets/skills/agent-kit.md +81 -0
  131. package/assets/skills/write-a-skill.md +108 -0
  132. package/assets/templates/gate-map.sh +23 -15
  133. package/assets/templates/implementation.md +14 -8
  134. package/assets/templates/pattern.md +1 -1
  135. package/assets/templates/project.sh +32 -19
  136. package/assets/templates/rule.md +1 -1
  137. package/assets/variants.json +20 -0
  138. package/assets/workflows/feature.js +134 -0
  139. package/assets/workflows/plan.js +150 -0
  140. package/bin/agent-kit.d.ts.map +1 -1
  141. package/bin/agent-kit.js +78 -5
  142. package/bin/agent-kit.js.map +1 -1
  143. package/bin/prompt.d.ts +5 -0
  144. package/bin/prompt.d.ts.map +1 -1
  145. package/bin/prompt.js +19 -7
  146. package/bin/prompt.js.map +1 -1
  147. package/index.d.ts +1 -0
  148. package/index.d.ts.map +1 -1
  149. package/index.js +1 -0
  150. package/index.js.map +1 -1
  151. package/lib/assets.d.ts +8 -3
  152. package/lib/assets.d.ts.map +1 -1
  153. package/lib/assets.js +13 -3
  154. package/lib/assets.js.map +1 -1
  155. package/lib/catalog.d.ts +52 -5
  156. package/lib/catalog.d.ts.map +1 -1
  157. package/lib/catalog.js +104 -16
  158. package/lib/catalog.js.map +1 -1
  159. package/lib/commands.d.ts +22 -1
  160. package/lib/commands.d.ts.map +1 -1
  161. package/lib/commands.js +202 -14
  162. package/lib/commands.js.map +1 -1
  163. package/lib/companion.d.ts +5 -1
  164. package/lib/companion.d.ts.map +1 -1
  165. package/lib/companion.js +29 -2
  166. package/lib/companion.js.map +1 -1
  167. package/lib/config.d.ts +26 -9
  168. package/lib/config.d.ts.map +1 -1
  169. package/lib/config.js +41 -15
  170. package/lib/config.js.map +1 -1
  171. package/lib/freshness.d.ts +14 -0
  172. package/lib/freshness.d.ts.map +1 -0
  173. package/lib/freshness.js +116 -0
  174. package/lib/freshness.js.map +1 -0
  175. package/lib/hooks-map.d.ts +24 -0
  176. package/lib/hooks-map.d.ts.map +1 -0
  177. package/lib/hooks-map.js +72 -0
  178. package/lib/hooks-map.js.map +1 -0
  179. package/lib/integrity.d.ts +36 -0
  180. package/lib/integrity.d.ts.map +1 -0
  181. package/lib/integrity.js +44 -0
  182. package/lib/integrity.js.map +1 -0
  183. package/lib/picker.d.ts +11 -1
  184. package/lib/picker.d.ts.map +1 -1
  185. package/lib/picker.js +44 -6
  186. package/lib/picker.js.map +1 -1
  187. package/lib/sync.d.ts +26 -0
  188. package/lib/sync.d.ts.map +1 -1
  189. package/lib/sync.js +59 -4
  190. package/lib/sync.js.map +1 -1
  191. package/lib/variants.d.ts +44 -0
  192. package/lib/variants.d.ts.map +1 -0
  193. package/lib/variants.js +82 -0
  194. package/lib/variants.js.map +1 -0
  195. package/package.json +1 -1
  196. package/rt-tools-agent-kit-0.4.0.tgz +0 -0
  197. package/assets/laws/admin-lists.md +0 -35
  198. package/assets/laws/admin-navigation.md +0 -38
  199. package/assets/patterns/git-workflow-commit.md +0 -175
  200. package/assets/rules/git-workflow.md +0 -106
  201. package/rt-tools-agent-kit-0.3.0.tgz +0 -0
@@ -2,76 +2,87 @@
2
2
  name: styling-bem-component
3
3
  kind: pattern
4
4
  rule: styling-bem
5
- description: Паттерн правила styling-bem. Брать при правке стилей компонента источника вида — готовый хост, модификаторы, значения только токенами, перебивание умолчаний источника вида. Не брать для раскладки экрана — это паттерн styling-bem-layout.
5
+ description: Паттерн правила styling-bem. Брать при правке стилей компонента кита — готовый :host, модификаторы, токены оформления, язык оформления публичного сайта, обход умолчаний кита. Не брать для раскладки экрана — это паттерн styling-bem-layout.
6
6
  ---
7
7
 
8
8
  # Стили компонента
9
9
 
10
10
  Паттерн правила `styling-bem`. Что при этом должно быть верно — закон
11
- `{{lawsDir}}/frontend-application.md`.
11
+ `docs/constitution/frontend-application.md`.
12
12
 
13
13
  ## Когда брать
14
14
 
15
- - Правится компонент источника вида.
16
- - Правится оформление отдельного компонента.
17
- - Нужно перебить умолчание источника вида в своём компоненте.
15
+ - Правится компонент кита — он живёт в пакете `@rt-tools/ui-kit-v2`, а не в этом дереве.
16
+ - Правится оформление публичного сайта.
17
+ - Нужно перебить умолчание кита в своём компоненте.
18
18
 
19
- ## Хост — сам блок
19
+ ## `:host` — сам блок
20
20
 
21
- Хост несёт класс блока, раскладка на хосте, элементы вложены внутрь:
21
+ Хост несёт класс блока, раскладка на `:host`, элементы вложены внутрь:
22
22
 
23
23
  ```scss
24
24
  :host {
25
25
  display: inline-flex;
26
26
 
27
- .<блок > {
27
+ .<префикс > -tag {
28
28
  display: inline-flex;
29
- gap: var(--<токен отступа>);
29
+ gap: var(--<префикс>-space-1);
30
30
  align-items: center;
31
31
 
32
- &--<модификатор > {
33
- border-radius: var(--<токен скругления>);
32
+ &--shape--pill {
33
+ border-radius: var(--<префикс>-radius-full);
34
34
  }
35
35
  }
36
36
  }
37
37
  ```
38
38
 
39
- Модификатор — вложенным селектором или привязкой класса на хосте. У экрана вне источника вида
40
- такого раздела нет: раскладка на хосте — это общий слой приложения, а не файл экрана.
39
+ Отступ — четыре пробела. Модификатор — `&--<имя>` или привязка класса на хосте
40
+ (`[class.<префикс>-component-name--active]="isActive()"`).
41
+
42
+ У экрана вне кита такого раздела нет: `display: flex` с `gap` и `padding` на `:host` — это
43
+ раскладка, и она в общем слое приложения.
41
44
 
42
45
  ## Значения — только токенами
43
46
 
44
47
  ```scss
45
48
  ✗ color: #fff;
46
49
  ✗ box-shadow: 0 1px 2px rgb(0 0 0 / 12%);
47
- ✓ color: var(--<токен цвета поверхности>);
48
- ✓ box-shadow: var(--<токен тени>);
50
+ ✓ color: var(--<префикс>-color-surface);
51
+ ✓ box-shadow: var(--<префикс>-shadow-sm);
49
52
  ```
50
53
 
51
- Составное значение берётся готовым токеном целиком, а не собирается из частей. Переменные
52
- препроцессора для значений оформления не используются вовсе: они разрешаются на сборке и темой
53
- не переключаются.
54
+ Составное значение берётся готовым токеном целиком, а не собирается из частей. SCSS-переменные
55
+ (`$primaryColor`) для значений оформления не используются вовсе.
56
+
57
+ ## Язык оформления публичного сайта
58
+
59
+ Тропический премиум, фото-first:
60
+
61
+ - светлая тёплая палитра — песок, терракота, пальмовая зелень, только через `--<префикс>-color-*`;
62
+ - акцентная антиква в заголовках (`--<префикс>-font-serif`), гуманистический гротеск в тексте
63
+ (`--<префикс>-font-sans`);
64
+ - большие полноэкранные фото, щедрые отступы, сдержанные анимации;
65
+ - тёмные оверлеи поверх фото — переменными с прозрачностью.
54
66
 
55
- ## Перебить умолчание источника вида
67
+ ## Перебить умолчание кита
56
68
 
57
- Стили компонента без инкапсуляции весят столько же, сколько умолчания источника вида: у обоих
58
- селекторов по одному классу, и исход решает порядок подключения. Переопределение пишется
59
- потомком блока так вес растёт на единицу, и порядок перестаёт что-либо решать:
69
+ Стили компонента с `ViewEncapsulation.None` весят столько же, сколько умолчания кита: у
70
+ `.<префикс>-block__item` и у `.<префикс>-kit-item` по одному классу, и исход решает порядок подключения.
71
+ Переопределение пишется потомком блока:
60
72
 
61
73
  ```scss
62
74
  & &__item {
63
- color: var(--<токен приглушённого текста>);
75
+ color: var(--<префикс>-color-text-muted);
64
76
  }
65
77
  ```
66
78
 
67
79
  ## Частые промахи
68
80
 
69
- - **Комментарий-выключатель линтера стилей:** селекторы объединяются вложенностью, а не
70
- отключением правила.
71
- - **Приоритетное объявление:** запрещено, и оформление, заданное на месте, перебить им всё
72
- равно не выйдет.
73
- - **Новые объявления при переносе стилей:** переносится существующее, новое появляется, только
74
- когда задача фича.
75
- - **Замечание линтера, лежавшее в файле раньше, оставлено:** правятся все, и новые, и старые.
76
- - **Своё наследование гарнитуры в компоненте:** оно включено глобально, и местное объявление
77
- только расходится с ним.
81
+ - Комментарий-выключатель stylelint: селекторы объединяются вложенностью, а не отключением
82
+ правила.
83
+ - `!important`: запрещён, и инлайновый `width: 100%` на боксе панели перебить им нельзя.
84
+ - Новые объявления при переносе стилей: переносится существующее, новое появляется только
85
+ тогда, когда задача фича.
86
+ - Замечание линтера, лежавшее в файле раньше, оставлено: правятся все, и новые, и старые.
87
+ - Свой `font-family: inherit` в компоненте: наследование включено глобально в `styles.scss`
88
+ обоих приложений.
@@ -2,13 +2,13 @@
2
2
  name: styling-bem-layout
3
3
  kind: pattern
4
4
  rule: styling-bem
5
- description: Паттерн правила styling-bem. Брать при сборке экрана раздела, формы, панели или окна — блоки общего слоя, разметка директивами блока и элемента, свой элемент в чужом поддереве, признак того, что правка идёт не туда. Не брать для стилей компонента источника вида — это паттерн styling-bem-component.
5
+ description: Паттерн правила styling-bem. Брать при сборке экрана раздела, формы, панели или окна — готовые блоки общего слоя, разметка через rtBlock и rtElem, свой элемент в чужом поддереве, признак того, что правка идёт не туда. Не брать для стилей компонента кита — это паттерн styling-bem-component.
6
6
  ---
7
7
 
8
8
  # Экран на общем слое раскладки
9
9
 
10
10
  Паттерн правила `styling-bem`. Что при этом должно быть верно — закон
11
- `{{lawsDir}}/frontend-application.md`.
11
+ `docs/constitution/frontend-application.md`.
12
12
 
13
13
  ## Когда брать
14
14
 
@@ -17,51 +17,57 @@ description: Паттерн правила styling-bem. Брать при сбо
17
17
 
18
18
  ## Файл стилей экрана по умолчанию пустой
19
19
 
20
- Раскладка объявлена один раз в общем слое приложения, а экран её только применяет. Блоков этого
21
- слоя немного, и каждый отвечает за свой род экрана: экран раздела с заголовком и прокруткой,
22
- форма с разделами и строками полей, содержимое панели правки, содержимое модального окна.
20
+ Раскладка объявлена один раз в общем слое приложения (`apps/<app>/src/styles/`), а экран её
21
+ только применяет. Блоков в админке четыре, у сайта один:
23
22
 
24
- Блок вешается на хост, элементы получают классы от директивы блока в корне шаблона:
23
+ | Блок | Что раскладывает |
24
+ | --------------------- | --------------------------------------------------------------- |
25
+ | `<префикс>-page` | экран раздела: заголовок, тулбар, прокрутка, таблица, пагинация |
26
+ | `<префикс>-form` | форма с разделами-карточками и строками полей |
27
+ | `<префикс>-panel` | содержимое панели правки |
28
+ | `<префикс>-window` | содержимое модального окна |
29
+ | `<префикс>-site-page` | колонка содержимого сайта: заголовок раздела и вводный абзац |
25
30
 
26
- ```
27
- host: { class: '<блок экрана>' },
31
+ Блок вешается на хост, элементы получают классы от `rtBlock` в корне шаблона:
32
+
33
+ ```typescript
34
+ host: { class: '<префикс>-page' },
28
35
  ```
29
36
 
30
37
  ```html
31
- <ng-container rtBlock="<блок экрана>">
38
+ <ng-container rtBlock="<префикс>-page">
32
39
  <header rtElem="header">
33
40
  <div rtElem="header-main">
34
- <h1 rtElem="title">{{ '<ключ заголовка>' | <перевод> }}</h1>
41
+ <h1 rtElem="title">{{ 'bookingsTitle' | transloco }}</h1>
42
+ <p rtElem="hint">{{ 'bookingsHint' | transloco }}</p>
35
43
  </div>
36
44
  </header>
37
45
  </ng-container>
38
46
  ```
39
47
 
40
- Директива блока на контейнере без своего узла класса не ставит — узел это комментарий. Второго
41
- носителя класса блока не нужно, и своей обёртки тоже.
48
+ `rtBlock` на `<ng-container>` класса не ставит — узел это комментарий. Второго носителя класса
49
+ блока не нужно, и своей обёртки `<section>` тоже.
42
50
 
43
51
  ## Свой элемент в чужом поддереве
44
52
 
45
53
  Пара директив на одном элементе; класс блока при этом не ставится, только класс элемента:
46
54
 
47
55
  ```html
48
- <div rtBlock="<свой блок>" rtElem="confirm"></div>
56
+ <div rtBlock="<префикс>-bookings-page" rtElem="confirm"></div>
49
57
  ```
50
58
 
51
- Класс получается составной, а потомки внутри считаются от того же блока.
59
+ Класс получается `<префикс>-bookings-page__confirm`, а потомки внутри считаются от того же блока.
52
60
 
53
61
  ## Своё в файле экрана
54
62
 
55
- Остаётся только то, что принадлежит одному этому экрану и в общий слой не просится, — сетка
56
- календаря, карта на странице записи, лента переписки. Рядом пишется, почему это не общее.
63
+ Остаётся только то, что принадлежит одному этому экрану и в общий слой не просится — сетка
64
+ календаря, карта на странице объекта, лента переписки. Рядом пишется, почему это не общее.
57
65
 
58
66
  ## Частые промахи
59
67
 
60
- - **Раскладка на хосте в файле экрана.** Одинаковые с виду экраны от неё расходятся: заголовок
61
- страницы, объявленный в каждом экране заново, живёт тремя разными кеглями.
62
- - **Директива элемента без предка, объявившего блок:** отрисовка падает во время работы, сборка
63
- и линтер молчат.
64
- - **Класс, у которого правило сняли, а директива в шаблоне осталась:** ловит проверка «класс
65
- без правила».
66
- - **Элемент чужого блока в чужом поддереве:** имя блока приходит от предка, и подмешать его
67
- нечем.
68
+ - `display: flex` с `gap` и `padding` на `:host` в файле экрана это раскладка. Одинаковые с
69
+ виду экраны от неё расходятся: заголовок страницы объявлялся в одиннадцати компонентах тремя
70
+ разными кеглями.
71
+ - `rtElem` без предка с `rtBlock`: отрисовка падает в рантайме, сборка и линт молчат.
72
+ - Класс, у которого правило сняли, а `rtElem` в шаблоне остался: ловит `npm run check:styles`.
73
+ - Элемент чужого блока в чужом поддереве: имя блока приходит инъекцией, и подмешать его нечем.
@@ -0,0 +1,90 @@
1
+ ---
2
+ name: task-flow-close
3
+ kind: pattern
4
+ rule: task-flow
5
+ description: Паттерн правила task-flow. Брать при закрытии работы — вливание договорённости в спек домена последним коммитом отчёта, разбор папки задачи, переезд в архив, сверка очереди работ. Не брать для хода работы — это паттерн task-flow-resume.
6
+ ---
7
+
8
+ # Закрытие работы
9
+
10
+ Паттерн правила `task-flow`. Что при этом должно быть верно — закон
11
+ `docs/constitution/work-conduct.md`.
12
+
13
+ ## Когда брать
14
+
15
+ - Этапы замысла закрыты, проверки зелёные, отчёт готовится к публикации.
16
+ - `npm run check:specs` перечислил договорённость в разделе «Пора вливать».
17
+
18
+ ## 1. Договорённость вливается в спек домена
19
+
20
+ Последним коммитом отчёта, до слияния. Код к этому моменту написан, поэтому привязки
21
+ `файл:символ` известны — правило въезжает в спек домена сразу проверяемым.
22
+
23
+ ```bash
24
+ npm run check:specs # раздел «Пора вливать» называет готовые директории
25
+ ```
26
+
27
+ Порядок переезда:
28
+
29
+ - правила из `proposed/<фича>/spec.md` дописываются в `spec.md` домена, в его разделы;
30
+ - сценарии переезжают в `scenarios.md` домена **с прежними номерами**: на них ссылаются
31
+ заголовки тестов, и пересчёт рвёт сверку;
32
+ - привязки из `proposed/<фича>/implementation.md` дописываются в `implementation.md` домена
33
+ и проставляются на код, который теперь есть;
34
+ - законы, объявленные фичей в шапке, дописываются в шапку спека домена;
35
+ - директория `proposed/<фича>/` удаляется, строка о фиче снимается из раздела «Что
36
+ предложено, но ещё не выкачено» в `docs/specs/README.md`;
37
+ - домена ещё не было — `proposed/` заменяется полноценным спеком, и домен получает строку в
38
+ таблице `docs/specs/README.md`.
39
+
40
+ Работа шла несколькими задачами — вливание идёт в последней из них. Какая последняя, видно в
41
+ `docs/plans/<линия>.md`; закрытая линия уезжает в `docs/archive/` или удаляется.
42
+
43
+ ```bash
44
+ npm run check:specs # после вливания: привязки на месте, сценарии не потерялись
45
+ ```
46
+
47
+ ## 2. Папка задачи разбирается
48
+
49
+ Целиком в архив не переносится: `docs/archive/` — место для записей о состоявшемся, которые
50
+ кто-то читает, а не свалка ходов работы.
51
+
52
+ | Файл | Куда |
53
+ | ------------- | ------------------------------------------------------------------------------------------------------------------ |
54
+ | `grill.md` | в `docs/archive/` — ответы владельца невосстановимы, и это единственная запись о том, почему задача поставлена так |
55
+ | `progress.md` | в `docs/archive/`, если в нём есть решения по ходу с причинами; иначе удаляется |
56
+ | `plan.md` | удаляется — после выкатки на его вопрос отвечает код, а на «как работает» отвечает спек домена |
57
+
58
+ Уезжающее складывается одним файлом с говорящим именем, а не папкой из трёх:
59
+
60
+ ```bash
61
+ cat docs/tasks/<КЛЮЧ>-<номер>-<slug>/grill.md > docs/archive/<ЧТО_РЕШАЛИ>.md
62
+ rm -r docs/tasks/<КЛЮЧ>-<номер>-<slug>
63
+ ```
64
+
65
+ Разбор идёт в том же отчёте, что и работа: папка, оставленная до мержа, попадает в главную
66
+ ветку и читается там как текущая.
67
+
68
+ ## 3. Сверка
69
+
70
+ ```bash
71
+ npm run check:board # папка закрытой задачи среди текущих, брошенные черновики
72
+ npm run check:specs # договорённость влита, привязки на месте
73
+ npm run check:docs # пути, названные в текстах, существуют
74
+ ```
75
+
76
+ ## Ловушки
77
+
78
+ - **Папку разбирают до мержа — после него о ней уже никто не вспомнит.** Сверка очереди
79
+ считает задачу закрытой по мержу: до него папка среди текущих законна, а после за неё никто
80
+ не отвечает — работа ушла в следующую задачу, и находка приходит в чужой заход. Дважды
81
+ подряд папка закрытой задачи так и уехала в главную ветку. Разбирают её тем же PR, что и
82
+ работу, а не отдельным заходом «потом».
83
+ - **Вливание после мержа не делается.** В главной ветке тогда лежит раздел «предложено, но не
84
+ выкачено» с тем, что работает месяц, — беззвучная ложь, тем убедительнее, чем старше.
85
+ - **Номера сценариев при вливании не пересчитываются.** Идентификатор — ключ связи с тестами;
86
+ сдвиг рвёт сверку у соседей, которых правка не касалась.
87
+ - **Правило без привязки в спек домена не въезжает.** Кода, который его исполняет, нет —
88
+ значит это намерение, и место ему в открытых вопросах домена, а не в правилах.
89
+ - **Архив не обновляется после выкатки.** Уехавшее туда описывает день переезда, и правится
90
+ оно только вместе с признанием, что описывало неверно.
@@ -0,0 +1,94 @@
1
+ ---
2
+ name: task-flow-resume
3
+ kind: pattern
4
+ rule: task-flow
5
+ description: Паттерн правила task-flow. Брать при возвращении к незаконченной работе новым заходом — что уже пришло в контекст, чего не спрашивать у владельца, как править «Где стоим», как записывать решение по ходу и пересмотр этапа. Не брать для начала работы — это паттерн task-flow-start.
6
+ ---
7
+
8
+ # Возвращение к незаконченной работе
9
+
10
+ Паттерн правила `task-flow`. Что при этом должно быть верно — закон
11
+ `docs/constitution/work-conduct.md`.
12
+
13
+ ## Когда брать
14
+
15
+ - Сессия начата на ветке `<КЛЮЧ>-*`, работа в ней уже шла.
16
+ - Работа прерывается — надо оставить её так, чтобы следующий заход поднял без владельца.
17
+
18
+ ## Что уже пришло в контекст
19
+
20
+ Хук `task-context-load.sh` на запуске сессии отдал замысел и ход работы целиком, а разбор
21
+ просьбы — путём. Перечитывать их файлами не нужно; `grill.md` читается, когда в ходе работы
22
+ всплыло решение, причина которого неясна.
23
+
24
+ Пришло предупреждение «РАБОТА БЕЗ ПАПКИ ЗАДАЧИ» — работа шла мимо: папка собирается с
25
+ образца, а `progress.md` заполняется по тому, что видно в дереве и в истории ветки, а не по
26
+ расспросам владельца.
27
+
28
+ ## Чего не делать
29
+
30
+ - **Не спрашивать владельца о том, что записано.** Ради этого всё и заведено.
31
+ - **Не начинать заново то, что отмечено сделанным.** Отметка стоит в ходе работы; сомнение в
32
+ ней проверяется деревом — сборкой, тестами, чтением файла, — а не вопросом.
33
+ - **Не править замысел.** С ним сверяют результат; пересмотр идёт записью в ходе работы.
34
+
35
+ ## Первое действие захода
36
+
37
+ Сверить «Где стоим» с деревом. Запись описывает день, когда её сделали:
38
+
39
+ ```bash
40
+ git status --short
41
+ git log --oneline origin/main..HEAD
42
+ ```
43
+
44
+ Разошлось — «Где стоим» правится сразу, до работы: следующий заход поверит записи, а не
45
+ дереву.
46
+
47
+ ## Как ведётся ход работы
48
+
49
+ Раздел «Где стоим» **перезаписывается**, а не дописывается — это первое, что читает следующий
50
+ заход, и единственное, что переживает обрезку по объёму:
51
+
52
+ ```markdown
53
+ ## Где стоим
54
+
55
+ - **Этап:** 3 из 6 — гард и хук запуска
56
+ - **Сделано:** закон заведён, папка задачи и образец написаны
57
+ - **Следующий шаг:** сценарии обоих хуков, затем подключение в настройках
58
+ - **Незакоммиченное:** всё, ветка пока без коммитов
59
+ - **Ждём владельца:** нет
60
+ ```
61
+
62
+ Решение, принятое по ходу, — вместе с причиной и с тем, что было альтернативой:
63
+
64
+ ```markdown
65
+ - **2026-08-07. Гард судит по путям правки, а не по замыслу задачи.** Оценку «меняет ли
66
+ поведение» назначал бы тот, кому она мешает. Альтернатива — строка в замысле — отвергнута.
67
+ ```
68
+
69
+ Пересмотр этапа — туда же, а не правкой замысла:
70
+
71
+ ```markdown
72
+ - **2026-08-07. Этап 4 заменён: роли заводятся обе, а не одна.** Владелец решил при разборе;
73
+ прежний этап в замысле оставлен видимым.
74
+ ```
75
+
76
+ Запись захода отмечает сделанное и то, чем это подтверждено:
77
+
78
+ ```markdown
79
+ ### 2026-08-07
80
+
81
+ - 28 сценариев в наборе, `bash .claude/hooks/tests/run.sh` — все наборы зелёные.
82
+ - Доэтапное, не этой работы: сверка очереди перечисляет шесть закрытых задач вне борды.
83
+ ```
84
+
85
+ ## Ловушки
86
+
87
+ - **Заход, кончившийся ничем, тоже записывается.** Иначе следующий пойдёт той же дорогой:
88
+ «пробовали так — не вышло, потому что» стоит одной строки и экономит целый заход.
89
+ - **Незакоммиченное называется явно.** Работа живёт в дереве неделями; строка «что лежит
90
+ несохранённым и почему» — единственное, по чему это видно, пока отчёта нет.
91
+ - **Подтверждение — вывод команды или замер, а не пересказ.** «Проверил, работает» через
92
+ заход неотличимо от «казалось, что работает».
93
+ - **Доэтапное отделяется от своего.** Красное, найденное по дороге и не этой работой
94
+ сделанное, помечается таковым сразу: иначе следующий заход примет его за свою поломку.
@@ -0,0 +1,117 @@
1
+ ---
2
+ name: task-flow-start
3
+ kind: pattern
4
+ rule: task-flow
5
+ description: Паттерн правила task-flow. Брать в начале работы от владельца — готовый порядок: разведка до первого вопроса, шесть обязательных вопросов, договорённость о продукте, конвейер ролей, заведение задачи и ветки, сборка папки задачи. Не брать для возвращения к незаконченной работе — это паттерн task-flow-resume.
6
+ ---
7
+
8
+ # Начало работы
9
+
10
+ Паттерн правила `task-flow`. Что при этом должно быть верно — закон
11
+ `docs/constitution/work-conduct.md`.
12
+
13
+ ## Когда брать
14
+
15
+ - Владелец просит что-то сделать, и работы больше, чем на одну реплику.
16
+ - Замеченный по ходу дефект становится задачей.
17
+
18
+ ## Порядок
19
+
20
+ ### 1. Разведка — до первого вопроса
21
+
22
+ Вопрос, ответ на который лежит в коде, владельцу не задаётся: он обесценивает и остальные.
23
+
24
+ ```
25
+ Agent(subagent_type: "Explore", prompt: "<тема просьбы>: что по ней уже есть в дереве —
26
+ какие спеки описывают, какие законы и правила задевает, какие либы затронуты,
27
+ есть ли готовый образец рядом. Верни находки, а не пересказ файлов.")
28
+ ```
29
+
30
+ Находки складываются в раздел «Что уже есть в дереве» разбора.
31
+
32
+ ### 2. Разбор с владельцем
33
+
34
+ Ведёт главный агент: субагент до владельца не достучится. Команда — `/grill-me`, один вопрос
35
+ за раз, к каждому — свой рекомендуемый ответ с доводом.
36
+
37
+ Шесть вопросов задаются всегда, даже когда задача кажется понятной:
38
+
39
+ | Вопрос | Зачем |
40
+ | -------------------------------------------- | -------------------------------------------------------- |
41
+ | Меняет ли задача поведение приложения | от этого зависит договорённость о продукте |
42
+ | Требует ли правки закона или правила | закон без ведома владельца не правится |
43
+ | Одна задача или несколько | делится то, что откатывается порознь, и делится ДО ветки |
44
+ | Что в задачу не входит | не названная вслух граница не существует |
45
+ | Чем будет видно, что задача закрыта | «работает» признаком не является |
46
+ | Есть ли образец, с которого снимается подход | разведка найдёт похожее, а не то |
47
+
48
+ Спрашивается прозой. Меню вариантов годится, только когда постановка уже подтверждена и
49
+ остался выбор значения из закрытого набора; выбор слова, имени и термина — никогда.
50
+
51
+ Ответы пишутся в `docs/tasks/_draft-<slug>/grill.md` — папка ещё черновик, номера нет.
52
+
53
+ ```bash
54
+ mkdir -p docs/tasks/_draft-<slug>
55
+ cp docs/tasks/_template/grill.md docs/tasks/_draft-<slug>/grill.md
56
+ ```
57
+
58
+ ### 3. Конвейер после разбора
59
+
60
+ Вопросов больше не будет — дальше роли:
61
+
62
+ ```
63
+ Workflow(name: "plan", args: "docs/tasks/_draft-<slug>")
64
+ ```
65
+
66
+ Нужность → договорённость о продукте (`spec-writer`) → её состязательный разбор
67
+ (`spec-critic`) → замысел и разбивка (`project-manager`). Пробелы, которые роли не смогли
68
+ закрыть, возвращаются владельцу — их относит главный агент.
69
+
70
+ ### 4. Задача, ветка, папка
71
+
72
+ ```bash
73
+ npm run task:new -- --title '<Что не так>' --slug <slug> --label documentation --label area:tooling < тело.md
74
+ git checkout -b <КЛЮЧ>-<номер>-<slug>
75
+ npm run task:move -- <номер> in-progress
76
+ ```
77
+
78
+ `task:new` переименовывает `_draft-<slug>` в `<КЛЮЧ>-<номер>-<slug>` и проставляет шапку замысла.
79
+ Ветка заводится вторым вызовом: составную «завести и сразу коммитить» гард главной ветки
80
+ отклоняет целиком.
81
+
82
+ Остальные два файла — с образца:
83
+
84
+ ```bash
85
+ cp docs/tasks/_template/plan.md docs/tasks/<КЛЮЧ>-<номер>-<slug>/plan.md
86
+ cp docs/tasks/_template/progress.md docs/tasks/<КЛЮЧ>-<номер>-<slug>/progress.md
87
+ ```
88
+
89
+ ### 5. Шапка замысла
90
+
91
+ Её читает гард:
92
+
93
+ ```markdown
94
+ **Задача:** <КЛЮЧ>-282 · **Ветка:** <КЛЮЧ>-282-task-flow
95
+ **Драфт:** `docs/specs/bookings/proposed/aside-header/`
96
+ **Поведение:** меняется
97
+ ```
98
+
99
+ Работа, не задевающая `apps/**` и `libs/**`, договорённости не требует:
100
+
101
+ ```markdown
102
+ **Поведение:** не меняется — переезд слоя, снаружи не видно. Подтверждено владельцем.
103
+ ```
104
+
105
+ Пустая причина не принимается.
106
+
107
+ ## Ловушки
108
+
109
+ - **Номер не бывает первым.** До конца разбора неизвестно даже, сколько задач из него выйдет:
110
+ заведённая заранее задача после разбивки закрывается и остаётся мусором в очереди работ.
111
+ - **Разбор пишется на диск сразу, а не копится в переписке.** Сессия обрывается, и разбор,
112
+ прожитый в разговоре, восстанавливается только пересказом владельца.
113
+ - **Из одного разбора вышло несколько задач — общее уезжает в `docs/plans/<линия>.md`.**
114
+ Папка задачи умирает с мержем, а порядок задач и зависимости между ними должны его
115
+ пережить.
116
+ - **Задача заводится командой, а не четырьмя вызовами подряд.** Борда к репозиторию не
117
+ привязана, и задача попадает на неё только явным добавлением.