@wildo-ai/framework-knowledge 1.1.1 → 1.1.3

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 (223) hide show
  1. package/dist/esm/framework-knowledge.definitions.d.ts +1 -1
  2. package/dist/esm/framework-knowledge.definitions.d.ts.map +1 -1
  3. package/dist/esm/framework-knowledge.definitions.js +271 -8
  4. package/dist/esm/framework-knowledge.definitions.js.map +1 -1
  5. package/dist/esm/framework-knowledge.loader.d.ts +19 -0
  6. package/dist/esm/framework-knowledge.loader.d.ts.map +1 -1
  7. package/dist/esm/framework-knowledge.loader.js +32 -0
  8. package/dist/esm/framework-knowledge.loader.js.map +1 -1
  9. package/dist/esm/framework-knowledge.schemas.d.ts +13 -2
  10. package/dist/esm/framework-knowledge.schemas.d.ts.map +1 -1
  11. package/dist/esm/framework-knowledge.schemas.js.map +1 -1
  12. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.d.ts +45 -0
  13. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.d.ts.map +1 -0
  14. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.js +55 -0
  15. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.js.map +1 -0
  16. package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.d.ts +6 -7
  17. package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.d.ts.map +1 -1
  18. package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.js +6 -6
  19. package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.js.map +1 -1
  20. package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.d.ts +0 -4
  21. package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.d.ts.map +1 -1
  22. package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.js +0 -2
  23. package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.js.map +1 -1
  24. package/dist/esm/playbooks/bottom_up.build-scale/playbook.definition.d.ts +0 -4
  25. package/dist/esm/playbooks/bottom_up.build-scale/playbook.definition.d.ts.map +1 -1
  26. package/dist/esm/playbooks/bottom_up.build-scale/playbook.definition.js +0 -2
  27. package/dist/esm/playbooks/bottom_up.build-scale/playbook.definition.js.map +1 -1
  28. package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.d.ts +3 -9
  29. package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.d.ts.map +1 -1
  30. package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.js +1 -3
  31. package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.js.map +1 -1
  32. package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.d.ts +10 -6
  33. package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.d.ts.map +1 -1
  34. package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.js +25 -4
  35. package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.js.map +1 -1
  36. package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.d.ts +1 -5
  37. package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.d.ts.map +1 -1
  38. package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.js +1 -3
  39. package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.js.map +1 -1
  40. package/dist/esm/playbooks/refinement.compliance-document-candidate/playbook.definition.d.ts +4 -2
  41. package/dist/esm/playbooks/refinement.compliance-document-candidate/playbook.definition.d.ts.map +1 -1
  42. package/dist/esm/playbooks/refinement.compliance-document-candidate/playbook.definition.js +4 -2
  43. package/dist/esm/playbooks/refinement.compliance-document-candidate/playbook.definition.js.map +1 -1
  44. package/dist/esm/playbooks/refinement.document-facts/playbook.definition.d.ts +1 -2
  45. package/dist/esm/playbooks/refinement.document-facts/playbook.definition.d.ts.map +1 -1
  46. package/dist/esm/playbooks/refinement.document-facts/playbook.definition.js +13 -14
  47. package/dist/esm/playbooks/refinement.document-facts/playbook.definition.js.map +1 -1
  48. package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.d.ts +3 -5
  49. package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.d.ts.map +1 -1
  50. package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.js +3 -4
  51. package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.js.map +1 -1
  52. package/dist/esm/playbooks/top_down.business-model/playbook.definition.d.ts +2 -8
  53. package/dist/esm/playbooks/top_down.business-model/playbook.definition.d.ts.map +1 -1
  54. package/dist/esm/playbooks/top_down.business-model/playbook.definition.js +0 -2
  55. package/dist/esm/playbooks/top_down.business-model/playbook.definition.js.map +1 -1
  56. package/dist/esm/playbooks/top_down.capability-map/playbook.definition.d.ts +2 -8
  57. package/dist/esm/playbooks/top_down.capability-map/playbook.definition.d.ts.map +1 -1
  58. package/dist/esm/playbooks/top_down.capability-map/playbook.definition.js +0 -2
  59. package/dist/esm/playbooks/top_down.capability-map/playbook.definition.js.map +1 -1
  60. package/dist/esm/playbooks/top_down.compliance-analysis/playbook.definition.d.ts +52 -0
  61. package/dist/esm/playbooks/top_down.compliance-analysis/playbook.definition.d.ts.map +1 -0
  62. package/dist/esm/playbooks/top_down.compliance-analysis/playbook.definition.js +127 -0
  63. package/dist/esm/playbooks/top_down.compliance-analysis/playbook.definition.js.map +1 -0
  64. package/dist/esm/playbooks/top_down.compliance-conception/playbook.definition.d.ts +75 -0
  65. package/dist/esm/playbooks/top_down.compliance-conception/playbook.definition.d.ts.map +1 -0
  66. package/dist/esm/playbooks/top_down.compliance-conception/playbook.definition.js +91 -0
  67. package/dist/esm/playbooks/top_down.compliance-conception/playbook.definition.js.map +1 -0
  68. package/dist/esm/playbooks/top_down.compliance-evidence-adequacy/playbook.definition.d.ts +29 -0
  69. package/dist/esm/playbooks/top_down.compliance-evidence-adequacy/playbook.definition.d.ts.map +1 -0
  70. package/dist/esm/playbooks/top_down.compliance-evidence-adequacy/playbook.definition.js +28 -0
  71. package/dist/esm/playbooks/top_down.compliance-evidence-adequacy/playbook.definition.js.map +1 -0
  72. package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.d.ts +9 -45
  73. package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.d.ts.map +1 -1
  74. package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.js +4 -54
  75. package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.js.map +1 -1
  76. package/dist/esm/playbooks/top_down.compliance-research/playbook.definition.d.ts +30 -0
  77. package/dist/esm/playbooks/top_down.compliance-research/playbook.definition.d.ts.map +1 -0
  78. package/dist/esm/playbooks/top_down.compliance-research/playbook.definition.js +25 -0
  79. package/dist/esm/playbooks/top_down.compliance-research/playbook.definition.js.map +1 -0
  80. package/dist/esm/playbooks/top_down.market-analysis/playbook.definition.d.ts +2 -9
  81. package/dist/esm/playbooks/top_down.market-analysis/playbook.definition.d.ts.map +1 -1
  82. package/dist/esm/playbooks/top_down.market-analysis/playbook.definition.js +9 -5
  83. package/dist/esm/playbooks/top_down.market-analysis/playbook.definition.js.map +1 -1
  84. package/dist/esm/playbooks/top_down.market-evidence-adequacy/playbook.definition.d.ts +0 -1
  85. package/dist/esm/playbooks/top_down.market-evidence-adequacy/playbook.definition.d.ts.map +1 -1
  86. package/dist/esm/playbooks/top_down.market-evidence-adequacy/playbook.definition.js +0 -1
  87. package/dist/esm/playbooks/top_down.market-evidence-adequacy/playbook.definition.js.map +1 -1
  88. package/dist/esm/playbooks/top_down.market-research/playbook.definition.d.ts +0 -1
  89. package/dist/esm/playbooks/top_down.market-research/playbook.definition.d.ts.map +1 -1
  90. package/dist/esm/playbooks/top_down.market-research/playbook.definition.js +0 -1
  91. package/dist/esm/playbooks/top_down.market-research/playbook.definition.js.map +1 -1
  92. package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.d.ts +0 -9
  93. package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.d.ts.map +1 -1
  94. package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.js +0 -2
  95. package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.js.map +1 -1
  96. package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.d.ts +2 -8
  97. package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.d.ts.map +1 -1
  98. package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.js +0 -2
  99. package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.js.map +1 -1
  100. package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.d.ts +2 -8
  101. package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.d.ts.map +1 -1
  102. package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.js +0 -2
  103. package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.js.map +1 -1
  104. package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.d.ts +2 -8
  105. package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.d.ts.map +1 -1
  106. package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.js +5 -4
  107. package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.js.map +1 -1
  108. package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.d.ts +0 -4
  109. package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.d.ts.map +1 -1
  110. package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.js +0 -2
  111. package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.js.map +1 -1
  112. package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.d.ts +4 -6
  113. package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.d.ts.map +1 -1
  114. package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.js +25 -5
  115. package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.js.map +1 -1
  116. package/dist/knowledge/manifest.json +6 -7
  117. package/dist/knowledge/playbooks/bottom_up.build-decompose/method.md +7 -47
  118. package/dist/knowledge/playbooks/bottom_up.build-decompose/playbook.json +6 -13
  119. package/dist/knowledge/playbooks/bottom_up.build-dispatch/method.md +1 -82
  120. package/dist/knowledge/playbooks/bottom_up.build-dispatch/playbook.json +11 -6
  121. package/dist/knowledge/playbooks/bottom_up.build-scale/playbook.json +10 -5
  122. package/dist/knowledge/playbooks/bottom_up.domain-plan/playbook.json +3 -4
  123. package/dist/knowledge/playbooks/bottom_up.foundation/playbook.json +3 -4
  124. package/dist/knowledge/playbooks/refinement.compliance-document-candidate/method.md +15 -735
  125. package/dist/knowledge/playbooks/refinement.compliance-document-candidate/playbook.json +11 -7
  126. package/dist/knowledge/playbooks/refinement.document-facts/method.md +16 -123
  127. package/dist/knowledge/playbooks/refinement.document-facts/playbook.json +15 -8
  128. package/dist/knowledge/playbooks/top_down.brand-identity/playbook.json +10 -4
  129. package/dist/knowledge/playbooks/top_down.business-model/playbook.json +10 -4
  130. package/dist/knowledge/playbooks/top_down.capability-map/method.md +2 -2
  131. package/dist/knowledge/playbooks/top_down.capability-map/playbook.json +12 -5
  132. package/dist/knowledge/playbooks/top_down.compliance-posture/playbook.json +10 -4
  133. package/dist/knowledge/playbooks/{top_down.market-snapshot-produce → top_down.market-analysis}/evaluation-protocol.json +1 -1
  134. package/dist/knowledge/playbooks/{top_down.market-snapshot-produce → top_down.market-analysis}/evaluation-treatment.json +1 -1
  135. package/dist/knowledge/playbooks/top_down.market-analysis/method.md +165 -51
  136. package/dist/knowledge/playbooks/top_down.market-analysis/playbook.json +39 -21
  137. package/dist/knowledge/playbooks/top_down.phase-gate/playbook.json +2 -6
  138. package/dist/knowledge/playbooks/top_down.requirements-definition/playbook.json +10 -4
  139. package/dist/knowledge/playbooks/top_down.scope-roadmap/method.md +1 -1
  140. package/dist/knowledge/playbooks/top_down.scope-roadmap/playbook.json +11 -5
  141. package/dist/knowledge/playbooks/top_down.value-proposition/method.md +2 -2
  142. package/dist/knowledge/playbooks/top_down.value-proposition/playbook.json +11 -5
  143. package/dist/knowledge/playbooks/top_down.vision-elicitation/playbook.json +10 -4
  144. package/dist/knowledge/references/build-plan.task-graph.config.md +1 -45
  145. package/dist/knowledge/references/example.config.app-shell.full.md +4 -0
  146. package/dist/knowledge/references/example.provider.backend-module-shape.md +0 -7
  147. package/dist/knowledge/references/example.resource.add-resource.module-factory-map.md +1 -0
  148. package/dist/knowledge/references/platform.config.saas.md +0 -50
  149. package/dist/knowledge/references/saas.external-data.admin-endpoints.md +48 -0
  150. package/dist/knowledge/references/saas.frontend.app-level-component.configuration.md +10 -6
  151. package/dist/knowledge/references/saas.frontend.app-level-component.vocabulary.md +1 -0
  152. package/dist/knowledge/references/saas.frontend.resource-operation-frontend-config.md +0 -109
  153. package/dist/knowledge/references/saas.models.data-mode-read-list.md +0 -137
  154. package/dist/knowledge/references/saas.models.http-api-binding.md +29 -3
  155. package/dist/knowledge/references/saas.models.resource-config.builder-parameters.md +2 -4
  156. package/dist/knowledge/references/saas.models.resource-config.resource-configuration.md +0 -2
  157. package/dist/knowledge/references/saas.models.resource-config.resources-registry.md +0 -14
  158. package/dist/knowledge/references/saas.specifications.application-document-fact-specification.contract.md +1 -1
  159. package/dist/knowledge/references/saas.specifications.companion-exports.contract.md +0 -36
  160. package/dist/knowledge/references/zod.decorators.chainable-runtime.md +0 -26
  161. package/dist/knowledge/references/zod.decorators.decorator-vocabulary.md +0 -45
  162. package/dist/knowledge/references/zod.decorators.display-edit-modes.md +1 -1
  163. package/dist/knowledge/references/zod.decorators.per-primitive-ui.md +1 -1
  164. package/dist/knowledge/references/zod.decorators.schema-metadata.md +0 -1
  165. package/dist/knowledge/registries/assurance-authority-bases.json +1 -1
  166. package/dist/knowledge/registries/framework-topics.json +11 -48
  167. package/dist/knowledge/registries/playbooks.json +11 -74
  168. package/dist/knowledge/registries/source-tags.json +538 -622
  169. package/dist/knowledge/skills/INDEX.md +0 -1
  170. package/dist/knowledge/skills/compliance-document-authoring/SKILL.md +2 -16
  171. package/dist/knowledge/skills/compliance-document-authoring/references/document-composition-governance.md +8 -26
  172. package/dist/knowledge/skills/compliance-document-authoring/references/document-composition-privacy-notice.md +74 -252
  173. package/dist/knowledge/skills/compliance-document-authoring/references/document-composition-service-terms.md +8 -26
  174. package/dist/knowledge/skills/compliance-document-authoring/references/framework-application-document-fact-specification-contract.md +21 -36
  175. package/dist/knowledge/skills/compliance-document-authoring/references/framework-assurance-document-blueprint-contract.md +19 -49
  176. package/dist/knowledge/skills/config-app-shell/SKILL.md +8 -6
  177. package/dist/knowledge/skills/config-app-shell/references/framework-app-shell-api.md +11 -6
  178. package/dist/knowledge/skills/config-saas/references/framework-wildo-saas-config-api.md +0 -50
  179. package/dist/knowledge/skills/configure-billing/references/example-backend-provider-module-shape.md +0 -7
  180. package/dist/knowledge/skills/market-companion-prompt-enrichment/SKILL.md +0 -36
  181. package/dist/knowledge/skills/market-companion-prompt-enrichment/references/framework-companion-behavior-api.md +0 -36
  182. package/dist/knowledge/skills/module-companion-exports/references/companion-exports-by-package.md +0 -36
  183. package/dist/knowledge/skills/resource-add-field/references/framework-field-cross-layer-api.md +0 -109
  184. package/dist/knowledge/skills/resource-add-resource/SKILL.md +1 -2
  185. package/dist/knowledge/skills/resource-add-resource/references/framework-new-resource-core-config-api.md +2 -4
  186. package/dist/knowledge/skills/resource-config-wiring/SKILL.md +0 -2
  187. package/dist/knowledge/skills/resource-config-wiring/references/framework-saas-models-resource-config-api.md +2 -157
  188. package/dist/knowledge/skills/resource-custom-view/references/custom-view-contracts.md +0 -109
  189. package/dist/knowledge/skills/resource-external-data/SKILL.md +2 -0
  190. package/dist/knowledge/skills/resource-external-data/references/framework-http-api-binding-api.md +29 -3
  191. package/dist/knowledge/skills/resource-external-data/references/framework-pipeline-admin-endpoints-api.md +70 -0
  192. package/dist/knowledge/skills/resource-schema-authoring/SKILL.md +0 -1
  193. package/dist/knowledge/skills/resource-schema-authoring/references/decorator-layer-map.md +0 -17
  194. package/dist/knowledge/skills/resource-schema-authoring/references/framework-decorator-vocabulary-api.md +0 -46
  195. package/dist/knowledge/skills/resource-schema-authoring/references/framework-zod-lifecycle-and-chainable-api.md +0 -26
  196. package/dist/knowledge/skills/resource-ui-behavior/references/framework-display-edit-modes-api.md +1 -1
  197. package/dist/knowledge/skills/resource-ui-behavior/references/framework-frontend-resource-ui-contracts-api.md +0 -109
  198. package/dist/knowledge/skills/resource-ui-behavior/references/framework-per-primitive-ui-api.md +1 -1
  199. package/dist/knowledge/skills/spec-companion-exports/references/framework-companion-exports-contract-api.md +0 -36
  200. package/dist/knowledge/topic-index.json +128 -285
  201. package/dist/tsconfig.build.tsbuildinfo +1 -1
  202. package/dist/tsconfig.tsbuildinfo +1 -1
  203. package/package.json +4 -4
  204. package/dist/esm/.builder.pid +0 -9
  205. package/dist/knowledge/playbooks/bottom_up.placement-plan/method.md +0 -185
  206. package/dist/knowledge/playbooks/bottom_up.placement-plan/playbook.json +0 -66
  207. package/dist/knowledge/playbooks/top_down.market-evidence-adequacy/method.md +0 -56
  208. package/dist/knowledge/playbooks/top_down.market-evidence-adequacy/playbook.json +0 -40
  209. package/dist/knowledge/playbooks/top_down.market-research/method.md +0 -68
  210. package/dist/knowledge/playbooks/top_down.market-research/playbook.json +0 -42
  211. package/dist/knowledge/playbooks/top_down.market-snapshot-produce/method.md +0 -239
  212. package/dist/knowledge/playbooks/top_down.market-snapshot-produce/playbook.json +0 -69
  213. package/dist/knowledge/references/placement-plan.config.md +0 -330
  214. package/dist/knowledge/references/saas.frontend.settings-hub.engine-destinations.md +0 -58
  215. package/dist/knowledge/references/saas.frontend.settings-hub.placement.md +0 -118
  216. package/dist/knowledge/references/zod.decorators.data-categories.md +0 -197
  217. package/dist/knowledge/rules/resource-schema-awareness.md +0 -77
  218. package/dist/knowledge/skills/resource-config-wiring/references/framework-personal-data-declaration-api.md +0 -622
  219. package/dist/knowledge/skills/resource-schema-authoring/references/framework-personal-data-category-api.md +0 -245
  220. package/dist/knowledge/skills/settings-placement-authoring/SKILL.md +0 -134
  221. package/dist/knowledge/skills/settings-placement-authoring/references/framework-settings-destinations-catalog.md +0 -65
  222. package/dist/knowledge/skills/settings-placement-authoring/references/framework-settings-placement-api.md +0 -127
  223. /package/dist/knowledge/playbooks/{top_down.market-snapshot-produce → top_down.market-analysis}/structured-artifact-action.json +0 -0
@@ -1,239 +0,0 @@
1
- # Market Analysis — Produce Method (v1 scaffold)
2
-
3
- ### Target Application Framing
4
-
5
- This knowledge is for configuring behavior in the target application.
6
- Wildo is the framework surface being used, not the product being built.
7
-
8
- Read and apply these patterns from the application-developer point of view:
9
-
10
- - how the application should configure the relevant app-level file
11
- - how the application should use framework-provided factories, enums, and helpers
12
- - how the application should avoid mixing frontend, backend, and infrastructure concerns
13
-
14
-
15
- > **This is a v1 scaffold methodology.** It is a working first cut meant to
16
- > be iterated. The authoring order, research posture, and the "produce vs.
17
- > refine" rules below are deliberately explicit so they can be tuned against
18
- > real runs — treat them as a starting rubric, not a frozen contract. The
19
- > *analytical depth* of the market work (research rigor, competitive
20
- > teardown, quantified FIT/Kano scoring) is intentionally shallow here and is
21
- > deepened in a later phase; do not perfect it in this playbook.
22
-
23
- ## What this playbook does
24
-
25
- You are the **market analyst**. Your one job is to produce — or refine an
26
- existing — **MarketSnapshot** for this product: the single artifact that
27
- declares *who the product is for*, *what they are trying to get done*, and
28
- *how the product is positioned* to them. You reason top-down from the
29
- product idea (there is no code yet in this phase); you do not model the
30
- domain, author resources, or write features — later playbooks consume your
31
- snapshot to do that.
32
-
33
- ## The shape you return is FLAT, not nested
34
-
35
- Read this before the slice list below, because the slices read like a hierarchy and the object is
36
- not one.
37
-
38
- A MarketSnapshot is **~16 sibling top-level collections** — `category`, `icps`, `personas`, `jobs`,
39
- `pains`, `gains`, `tonesOfVoice`, `benefits`, `positionings`, `channels`, `alternatives`,
40
- `triggers`, `buyingJourneys`, `proofs`, `objections`, `messageTemplates` — and entities point at
41
- each other with flat **ref strings** (`jobRef`, `painRef`, `gainRef`, `personaRef`, `alternativeRef`,
42
- …). An ICP does not CONTAIN its jobs; it names them:
43
-
44
- ```
45
- jobs: [ { ref: 'job-close-the-week', statement: '…' } ] // the job itself, top level
46
- icps: [ { ref: 'icp-small-team',
47
- jobs: [ { jobRef: 'job-close-the-week', importance: … } ] } ] // the ICP's REFERENCE to it
48
- ```
49
-
50
- ⚠ **Measured on this playbook, 2026-08-29.** A first attempt returned 41,098 characters that were
51
- rejected wholesale: it had nested `personas`, `benefits`, `positionings`, `channels`, `alternatives`,
52
- `triggers`, `proofs` and `objections` INSIDE `icps[0]`, left every top-level collection empty, and
53
- wrote whole job objects where `{ jobRef, importance }` belongs. The retry recovered it, but a full
54
- generation was spent discovering the shape. The slice ordering below is a THINKING order — what to
55
- work out first — never the structure of the answer.
56
-
57
- A MarketSnapshot is assembled from these slices, each owned by a dedicated
58
- `market_*` app-knowledge skill (see References). You author them in
59
- dependency order because later slices reference earlier refs:
60
-
61
- 1. **Category** — the one market category the product competes in, plus the
62
- rejected adjacent categories. (`market-category`)
63
- 2. **ICPs** — the Ideal Customer Profiles: the firmographic / demographic
64
- segments the product is sold to. (`market-icp`)
65
- 3. **Personas** — the human roles inside each ICP, including buying-group
66
- members. Every ICP needs at least one persona. (`market-persona`)
67
- 4. **Jobs / Pains / Gains** — the Strategyzer customer-profile triplet for
68
- the personas: what they are trying to do, what blocks them, what a win
69
- looks like. (`market-jobs-pains-gains`)
70
- 5. **Tones of voice** — the named brand voices the product speaks in.
71
- (`market-tone-of-voice`)
72
- 6. **Benefits** — the outcome claims the product delivers, weighted against
73
- the pains/gains they relieve/create. (`market-add-feature-benefit`)
74
- 7. **Positionings** — the per-ICP marketing-truth promise. Author one per
75
- ICP that the product actually targets. (`market-positioning-authoring`)
76
- 8. **Reach surfaces** — the go-to-market context: channels, competing
77
- alternatives, buying triggers + per-ICP buying journeys, proofs, and the
78
- objections proofs answer. (`market-channels`, `market-alternatives`,
79
- `market-triggers-and-journey`, `market-proof-and-objection`)
80
- 9. **Message templates** — reusable prompt templates that render from the
81
- snapshot above. Author last; they reference the earlier slices.
82
- (`market-message-templates-authoring`)
83
-
84
- Author only the slices the product's stage warrants — a first pass may stop
85
- after positionings and leave the phase-3/4 reach surfaces empty (they
86
- default to `[]`). A snapshot with a category, at least one ICP, its
87
- personas, the jobs/pains/gains triplet, and at least one positioning is a
88
- legitimate v1; the reach surfaces and message templates are additive.
89
-
90
- ## Where the snapshot lives
91
-
92
- The MarketSnapshot for this journey is placed under
93
- `specifications/src/market/index.ts`. That is the artifact this
94
- playbook owns and the rest of the top-down phase reads. When the product's
95
- definition later stabilises, the snapshot is what seeds the durable market
96
- specification under `./specifications/` — but at this phase it is a journey
97
- artifact, not yet app source.
98
-
99
- ## Produce vs. refine — read state first
100
-
101
- This playbook is **idempotent** on the journey's market artifact. Before
102
- authoring anything:
103
-
104
- 1. Read the current journey state and scope through the `journey-status`
105
- skill (it owns the read; do not re-derive it here) — that tells you which
106
- scope the snapshot must be complete *for*.
107
- 2. Check whether a MarketSnapshot already exists by reading the artifact at the
108
- `market-snapshot` family's landing path, `specifications/src/market/index.ts`.
109
- The path belongs to the FAMILY, not to this playbook — every playbook that
110
- writes a market snapshot writes that same file. Its presence or absence
111
- selects the mode below.
112
-
113
- - **No snapshot yet** — produce a fresh one, authoring the slices in the
114
- order above.
115
- - **A snapshot exists** — *refine* it: read every slice, keep what still
116
- holds, and only add/correct the slices the current steering notes or new
117
- research call for. Never silently discard authored refs — a downstream
118
- positioning or benefit may depend on an ICP or persona ref, and dropping
119
- it orphans them (the validator will catch this, but honest refinement
120
- should not create the orphan in the first place).
121
-
122
- ## Provenance — record where a claim came from
123
-
124
- You are given the evidence a sibling research step gathered, with the URLs it read.
125
- Where an entity's content rests on one of those sources, RECORD that URL on the entity
126
- — in the schema's own provenance fields, which exist for exactly this:
127
-
128
- | field | for |
129
- |---|---|
130
- | `pains[].evidence[]`, `gains[].evidence[]`, `benefits[].evidence` | what a source shows about the pain, gain or claim |
131
- | `proofs[].evidenceUrl`, `proofs[].attribution.url` | the page a proof points at |
132
- | `alternatives[].notes[]`, `category.notes[]`, `icps[].notes[]` | where the framing came from |
133
-
134
- ⚠ An earlier revision of this section told you to use `authoredMetadata.notes` instead.
135
- That was wrong, and the correction is recorded rather than quietly applied because the
136
- run that exposed it did better than the instruction: handed the evidence, the model
137
- put 10 URLs into the typed `evidence`/`evidenceUrl` fields above and none into the
138
- generic metadata block it had been pointed at. Typed provenance is machine-readable
139
- and the generic block is prose; prefer the specific field every time one exists.
140
-
141
- This is not bookkeeping. Measured on this playbook's first composite run
142
- (2026-08-29): the snapshot it produced carried **zero** source URLs and was, on that
143
- dimension, indistinguishable from the single-call version it replaced — the judge
144
- called the older one's evidence "self-referential statements such as 'The vision
145
- specifies…'". A sourced claim and an invented one must not look the same in what you
146
- land, because nobody downstream can tell them apart afterwards.
147
-
148
- So:
149
-
150
- - An entity grounded in a fetched page carries its URL in `authoredMetadata.notes`.
151
- - An entity you INFERRED carries that word, and `confidence` set honestly — `LOW` for
152
- a hypothesis, not `HIGH` because it reads well.
153
- - An entity the evidence did not cover is still authorable, and says so.
154
-
155
- Omit `authoredMetadata` only where the content is so self-evident that provenance
156
- would be noise. A competitor's price is never that.
157
-
158
- ## Research posture (scaffold depth)
159
-
160
- Ground each slice in evidence, not invention. At this scaffold depth the
161
- research is whatever the executing agent can gather about the product's
162
- category, competitors, and buyers; capture the *shape* faithfully (real
163
- category, real competing alternatives, plausible ICPs and personas) rather
164
- than aspirational fiction. Where you are inferring rather than citing, say so
165
- in the slice's authored prose so a later, deeper research pass can tighten
166
- it. Do **not** build a research pipeline or block on external tooling here —
167
- richer web-research capability is a later-phase concern; this playbook
168
- consumes whatever the agent already knows plus the creator's steering.
169
-
170
- ## Quality gate
171
-
172
- Your emitted snapshot is checked by the deterministic `market-snapshot-valid`
173
- gate (`validateMarketSnapshot`) before anything downstream consumes it. It
174
- enforces the cross-slice invariants — orphan refs (a positioning naming a
175
- missing ICP, a benefit naming a missing pain/gain), an ICP with no persona,
176
- influence cycles, duplicate edges, proofs without support, message-template
177
- placeholder mismatches, and more. Duplicate or malformed refs and
178
- `ERROR`-severity issues are hard failures; the snapshot does not advance
179
- until they clear. `WARN`-severity issues (e.g. stale-authored, a missing
180
- positioning for a targeted ICP) do not block but should be resolved. Read
181
- `market-snapshot-validation` for the full issue catalogue and emit a clean
182
- snapshot the first time.
183
-
184
- ## Scaffold-depth boundary (deferred to a later depth phase)
185
-
186
- Keep this playbook at scaffold depth. The following are explicitly **out of
187
- scope here** and are deepened in the methodology-depth phase, not now:
188
-
189
- - **Deep competitive teardown** — the reach surfaces capture *that* an
190
- alternative exists and *why* a buyer might pick it; a quantified,
191
- feature-by-feature competitor matrix is later-phase work.
192
- - **Quantified FIT / Kano scoring** — `market-scoring-interpretation` reads
193
- the deterministic FIT scorer; at scaffold depth you consume it to sanity-
194
- check benefit weighting, not to drive a precise prioritization model. The
195
- prioritization seam stays pluggable (see the capability-map playbook).
196
- - **Opportunity / TAM sizing and evidence depth** — jobs/pains/gains are
197
- authored as framing, not as a sized, sourced market model.
198
-
199
- If you find yourself perfecting any of the above, stop and leave the slice at
200
- scaffold depth — depth is a dedicated later pass done once, holistically.
201
-
202
- ## What you emit
203
-
204
- A single MarketSnapshot at `specifications/src/market/index.ts`,
205
- assembled from the slices above via their `market_*` skills, passing the
206
- `market-snapshot-valid` gate. The creator reviews the result (approval posture
207
- `approve_result`) before it is accepted as the journey's market intent.
208
-
209
- ## References
210
-
211
- - `.claude/skills/journey-status/SKILL.md` — read the current journey state
212
- and scope before authoring.
213
- - `.claude/skills/market-authoring-overview/SKILL.md` — the orchestrator for
214
- the whole market slice; read it first to see how the slices fit together.
215
- - `.claude/skills/market-category/SKILL.md` — author the singular market
216
- category.
217
- - `.claude/skills/market-icp/SKILL.md` — author the Ideal Customer Profiles.
218
- - `.claude/skills/market-persona/SKILL.md` — author the personas per ICP.
219
- - `.claude/skills/market-jobs-pains-gains/SKILL.md` — author the Strategyzer
220
- jobs/pains/gains triplet.
221
- - `.claude/skills/market-tone-of-voice/SKILL.md` — author the named brand
222
- voices.
223
- - `.claude/skills/market-add-feature-benefit/SKILL.md` — author the benefit
224
- claims and their pain/gain weighting.
225
- - `.claude/skills/market-positioning-authoring/SKILL.md` — author the per-ICP
226
- positioning promise.
227
- - `.claude/skills/market-channels/SKILL.md` — author the reach channels.
228
- - `.claude/skills/market-alternatives/SKILL.md` — author the competing
229
- alternatives.
230
- - `.claude/skills/market-triggers-and-journey/SKILL.md` — author buying
231
- triggers and per-ICP buying journeys.
232
- - `.claude/skills/market-proof-and-objection/SKILL.md` — author proofs and
233
- the objections they answer.
234
- - `.claude/skills/market-message-templates-authoring/SKILL.md` — author the
235
- reusable message templates (last).
236
- - `.claude/skills/market-scoring-interpretation/SKILL.md` — interpret the
237
- deterministic FIT scorer to sanity-check benefit weighting.
238
- - `.claude/skills/market-snapshot-validation/SKILL.md` — the full validation
239
- issue catalogue the quality gate enforces.
@@ -1,69 +0,0 @@
1
- {
2
- "ref": "top_down.market-snapshot-produce",
3
- "version": "0.1.0",
4
- "phase": "top_down",
5
- "intent": "Derive a validated market snapshot from the vision and from the EVIDENCE a sibling research step gathered — the artifact-producing child of the `top_down.market-analysis` composite. The provider proposes the market graph; the trusted runtime stamps entity refs/version and keeps provenance, authority and accepted-family mutation outside model output. Its intent used to claim derivation from \"sealed research evidence\" while nothing supplied any; it now runs only once an adequacy gate has read the evidence and returned ADEQUATE.",
6
- "functionalTopics": [],
7
- "preconditions": [
8
- {
9
- "kind": "phase_is",
10
- "phase": "top_down"
11
- },
12
- {
13
- "kind": "artifact_valid",
14
- "selector": {
15
- "family": "vision-brief"
16
- }
17
- },
18
- {
19
- "kind": "step_available",
20
- "ref": "evidence-adequacy",
21
- "requires": {
22
- "path": "verdict",
23
- "equals": "adequate"
24
- }
25
- }
26
- ],
27
- "inputs": [
28
- {
29
- "family": "vision-brief"
30
- }
31
- ],
32
- "outputs": [
33
- {
34
- "family": "market-snapshot",
35
- "schemaRef": "saas-specifications:MarketSnapshot",
36
- "description": "The assembled market category, ICP, persona, jobs/pains/gains, benefit, positioning and reach graph validated by validateMarketSnapshot."
37
- }
38
- ],
39
- "stepOutputs": [],
40
- "method": {
41
- "guidance": "# Market Analysis — Produce Method (v1 scaffold)\n\n### Target Application Framing\n\nThis knowledge is for configuring behavior in the target application.\nWildo is the framework surface being used, not the product being built.\n\nRead and apply these patterns from the application-developer point of view:\n\n- how the application should configure the relevant app-level file\n- how the application should use framework-provided factories, enums, and helpers\n- how the application should avoid mixing frontend, backend, and infrastructure concerns\n\n\n> **This is a v1 scaffold methodology.** It is a working first cut meant to\n> be iterated. The authoring order, research posture, and the \"produce vs.\n> refine\" rules below are deliberately explicit so they can be tuned against\n> real runs — treat them as a starting rubric, not a frozen contract. The\n> *analytical depth* of the market work (research rigor, competitive\n> teardown, quantified FIT/Kano scoring) is intentionally shallow here and is\n> deepened in a later phase; do not perfect it in this playbook.\n\n## What this playbook does\n\nYou are the **market analyst**. Your one job is to produce — or refine an\nexisting — **MarketSnapshot** for this product: the single artifact that\ndeclares *who the product is for*, *what they are trying to get done*, and\n*how the product is positioned* to them. You reason top-down from the\nproduct idea (there is no code yet in this phase); you do not model the\ndomain, author resources, or write features — later playbooks consume your\nsnapshot to do that.\n\n## The shape you return is FLAT, not nested\n\nRead this before the slice list below, because the slices read like a hierarchy and the object is\nnot one.\n\nA MarketSnapshot is **~16 sibling top-level collections** — `category`, `icps`, `personas`, `jobs`,\n`pains`, `gains`, `tonesOfVoice`, `benefits`, `positionings`, `channels`, `alternatives`,\n`triggers`, `buyingJourneys`, `proofs`, `objections`, `messageTemplates` — and entities point at\neach other with flat **ref strings** (`jobRef`, `painRef`, `gainRef`, `personaRef`, `alternativeRef`,\n…). An ICP does not CONTAIN its jobs; it names them:\n\n```\njobs: [ { ref: 'job-close-the-week', statement: '…' } ] // the job itself, top level\nicps: [ { ref: 'icp-small-team',\n jobs: [ { jobRef: 'job-close-the-week', importance: … } ] } ] // the ICP's REFERENCE to it\n```\n\n⚠ **Measured on this playbook, 2026-08-29.** A first attempt returned 41,098 characters that were\nrejected wholesale: it had nested `personas`, `benefits`, `positionings`, `channels`, `alternatives`,\n`triggers`, `proofs` and `objections` INSIDE `icps[0]`, left every top-level collection empty, and\nwrote whole job objects where `{ jobRef, importance }` belongs. The retry recovered it, but a full\ngeneration was spent discovering the shape. The slice ordering below is a THINKING order — what to\nwork out first — never the structure of the answer.\n\nA MarketSnapshot is assembled from these slices, each owned by a dedicated\n`market_*` app-knowledge skill (see References). You author them in\ndependency order because later slices reference earlier refs:\n\n1. **Category** — the one market category the product competes in, plus the\n rejected adjacent categories. (`market-category`)\n2. **ICPs** — the Ideal Customer Profiles: the firmographic / demographic\n segments the product is sold to. (`market-icp`)\n3. **Personas** — the human roles inside each ICP, including buying-group\n members. Every ICP needs at least one persona. (`market-persona`)\n4. **Jobs / Pains / Gains** — the Strategyzer customer-profile triplet for\n the personas: what they are trying to do, what blocks them, what a win\n looks like. (`market-jobs-pains-gains`)\n5. **Tones of voice** — the named brand voices the product speaks in.\n (`market-tone-of-voice`)\n6. **Benefits** — the outcome claims the product delivers, weighted against\n the pains/gains they relieve/create. (`market-add-feature-benefit`)\n7. **Positionings** — the per-ICP marketing-truth promise. Author one per\n ICP that the product actually targets. (`market-positioning-authoring`)\n8. **Reach surfaces** — the go-to-market context: channels, competing\n alternatives, buying triggers + per-ICP buying journeys, proofs, and the\n objections proofs answer. (`market-channels`, `market-alternatives`,\n `market-triggers-and-journey`, `market-proof-and-objection`)\n9. **Message templates** — reusable prompt templates that render from the\n snapshot above. Author last; they reference the earlier slices.\n (`market-message-templates-authoring`)\n\nAuthor only the slices the product's stage warrants — a first pass may stop\nafter positionings and leave the phase-3/4 reach surfaces empty (they\ndefault to `[]`). A snapshot with a category, at least one ICP, its\npersonas, the jobs/pains/gains triplet, and at least one positioning is a\nlegitimate v1; the reach surfaces and message templates are additive.\n\n## Where the snapshot lives\n\nThe MarketSnapshot for this journey is placed under\n`specifications/src/market/index.ts`. That is the artifact this\nplaybook owns and the rest of the top-down phase reads. When the product's\ndefinition later stabilises, the snapshot is what seeds the durable market\nspecification under `./specifications/` — but at this phase it is a journey\nartifact, not yet app source.\n\n## Produce vs. refine — read state first\n\nThis playbook is **idempotent** on the journey's market artifact. Before\nauthoring anything:\n\n1. Read the current journey state and scope through the `journey-status`\n skill (it owns the read; do not re-derive it here) — that tells you which\n scope the snapshot must be complete *for*.\n2. Check whether a MarketSnapshot already exists by reading the artifact at the\n `market-snapshot` family's landing path, `specifications/src/market/index.ts`.\n The path belongs to the FAMILY, not to this playbook — every playbook that\n writes a market snapshot writes that same file. Its presence or absence\n selects the mode below.\n\n- **No snapshot yet** — produce a fresh one, authoring the slices in the\n order above.\n- **A snapshot exists** — *refine* it: read every slice, keep what still\n holds, and only add/correct the slices the current steering notes or new\n research call for. Never silently discard authored refs — a downstream\n positioning or benefit may depend on an ICP or persona ref, and dropping\n it orphans them (the validator will catch this, but honest refinement\n should not create the orphan in the first place).\n\n## Provenance — record where a claim came from\n\nYou are given the evidence a sibling research step gathered, with the URLs it read.\nWhere an entity's content rests on one of those sources, RECORD that URL on the entity\n— in the schema's own provenance fields, which exist for exactly this:\n\n| field | for |\n|---|---|\n| `pains[].evidence[]`, `gains[].evidence[]`, `benefits[].evidence` | what a source shows about the pain, gain or claim |\n| `proofs[].evidenceUrl`, `proofs[].attribution.url` | the page a proof points at |\n| `alternatives[].notes[]`, `category.notes[]`, `icps[].notes[]` | where the framing came from |\n\n⚠ An earlier revision of this section told you to use `authoredMetadata.notes` instead.\nThat was wrong, and the correction is recorded rather than quietly applied because the\nrun that exposed it did better than the instruction: handed the evidence, the model\nput 10 URLs into the typed `evidence`/`evidenceUrl` fields above and none into the\ngeneric metadata block it had been pointed at. Typed provenance is machine-readable\nand the generic block is prose; prefer the specific field every time one exists.\n\nThis is not bookkeeping. Measured on this playbook's first composite run\n(2026-08-29): the snapshot it produced carried **zero** source URLs and was, on that\ndimension, indistinguishable from the single-call version it replaced — the judge\ncalled the older one's evidence \"self-referential statements such as 'The vision\nspecifies…'\". A sourced claim and an invented one must not look the same in what you\nland, because nobody downstream can tell them apart afterwards.\n\nSo:\n\n- An entity grounded in a fetched page carries its URL in `authoredMetadata.notes`.\n- An entity you INFERRED carries that word, and `confidence` set honestly — `LOW` for\n a hypothesis, not `HIGH` because it reads well.\n- An entity the evidence did not cover is still authorable, and says so.\n\nOmit `authoredMetadata` only where the content is so self-evident that provenance\nwould be noise. A competitor's price is never that.\n\n## Research posture (scaffold depth)\n\nGround each slice in evidence, not invention. At this scaffold depth the\nresearch is whatever the executing agent can gather about the product's\ncategory, competitors, and buyers; capture the *shape* faithfully (real\ncategory, real competing alternatives, plausible ICPs and personas) rather\nthan aspirational fiction. Where you are inferring rather than citing, say so\nin the slice's authored prose so a later, deeper research pass can tighten\nit. Do **not** build a research pipeline or block on external tooling here —\nricher web-research capability is a later-phase concern; this playbook\nconsumes whatever the agent already knows plus the creator's steering.\n\n## Quality gate\n\nYour emitted snapshot is checked by the deterministic `market-snapshot-valid`\ngate (`validateMarketSnapshot`) before anything downstream consumes it. It\nenforces the cross-slice invariants — orphan refs (a positioning naming a\nmissing ICP, a benefit naming a missing pain/gain), an ICP with no persona,\ninfluence cycles, duplicate edges, proofs without support, message-template\nplaceholder mismatches, and more. Duplicate or malformed refs and\n`ERROR`-severity issues are hard failures; the snapshot does not advance\nuntil they clear. `WARN`-severity issues (e.g. stale-authored, a missing\npositioning for a targeted ICP) do not block but should be resolved. Read\n`market-snapshot-validation` for the full issue catalogue and emit a clean\nsnapshot the first time.\n\n## Scaffold-depth boundary (deferred to a later depth phase)\n\nKeep this playbook at scaffold depth. The following are explicitly **out of\nscope here** and are deepened in the methodology-depth phase, not now:\n\n- **Deep competitive teardown** — the reach surfaces capture *that* an\n alternative exists and *why* a buyer might pick it; a quantified,\n feature-by-feature competitor matrix is later-phase work.\n- **Quantified FIT / Kano scoring** — `market-scoring-interpretation` reads\n the deterministic FIT scorer; at scaffold depth you consume it to sanity-\n check benefit weighting, not to drive a precise prioritization model. The\n prioritization seam stays pluggable (see the capability-map playbook).\n- **Opportunity / TAM sizing and evidence depth** — jobs/pains/gains are\n authored as framing, not as a sized, sourced market model.\n\nIf you find yourself perfecting any of the above, stop and leave the slice at\nscaffold depth — depth is a dedicated later pass done once, holistically.\n\n## What you emit\n\nA single MarketSnapshot at `specifications/src/market/index.ts`,\nassembled from the slices above via their `market_*` skills, passing the\n`market-snapshot-valid` gate. The creator reviews the result (approval posture\n`approve_result`) before it is accepted as the journey's market intent.\n\n## References\n\n- `.claude/skills/journey-status/SKILL.md` — read the current journey state\n and scope before authoring.\n- `.claude/skills/market-authoring-overview/SKILL.md` — the orchestrator for\n the whole market slice; read it first to see how the slices fit together.\n- `.claude/skills/market-category/SKILL.md` — author the singular market\n category.\n- `.claude/skills/market-icp/SKILL.md` — author the Ideal Customer Profiles.\n- `.claude/skills/market-persona/SKILL.md` — author the personas per ICP.\n- `.claude/skills/market-jobs-pains-gains/SKILL.md` — author the Strategyzer\n jobs/pains/gains triplet.\n- `.claude/skills/market-tone-of-voice/SKILL.md` — author the named brand\n voices.\n- `.claude/skills/market-add-feature-benefit/SKILL.md` — author the benefit\n claims and their pain/gain weighting.\n- `.claude/skills/market-positioning-authoring/SKILL.md` — author the per-ICP\n positioning promise.\n- `.claude/skills/market-channels/SKILL.md` — author the reach channels.\n- `.claude/skills/market-alternatives/SKILL.md` — author the competing\n alternatives.\n- `.claude/skills/market-triggers-and-journey/SKILL.md` — author buying\n triggers and per-ICP buying journeys.\n- `.claude/skills/market-proof-and-objection/SKILL.md` — author proofs and\n the objections they answer.\n- `.claude/skills/market-message-templates-authoring/SKILL.md` — author the\n reusable message templates (last).\n- `.claude/skills/market-scoring-interpretation/SKILL.md` — interpret the\n deterministic FIT scorer to sanity-check benefit weighting.\n- `.claude/skills/market-snapshot-validation/SKILL.md` — the full validation\n issue catalogue the quality gate enforces.\n",
42
- "skillRefs": [
43
- "journey-status",
44
- "market-authoring-overview",
45
- "market-category",
46
- "market-icp",
47
- "market-persona",
48
- "market-jobs-pains-gains",
49
- "market-tone-of-voice",
50
- "market-add-feature-benefit",
51
- "market-positioning-authoring",
52
- "market-channels",
53
- "market-alternatives",
54
- "market-triggers-and-journey",
55
- "market-proof-and-objection",
56
- "market-message-templates-authoring",
57
- "market-scoring-interpretation",
58
- "market-snapshot-validation"
59
- ],
60
- "contextSources": [],
61
- "suspendsForClarification": false
62
- },
63
- "executor": "companion_agent",
64
- "approval": "approve_result",
65
- "budget": {
66
- "maxRuns": 3
67
- },
68
- "onFailure": "keep_and_flag"
69
- }
@@ -1,330 +0,0 @@
1
- # placement-plan.config
2
-
3
- ## Import Origins
4
-
5
- - `@wildo-ai/saas-specifications`
6
-
7
- ## Source Excerpts
8
-
9
- ### Origin Package: `@wildo-ai/saas-specifications`
10
-
11
- ```typescript
12
- *
13
- * Versioning for the placement-plan payload format itself. `V1` — initial
14
- * shape (declared groups + one decision per subject). The shape grows
15
- * additively across versions; `version` is the explicit marker for consumers
16
- * that branch on era.
17
- */
18
- export enum PlacementPlanVersion {
19
- V1 = 'v1',
20
- }
21
-
22
- /** Stable prefix every placement decision ref carries; the trusted runtime stamps it, a provider supplies only the slug. */
23
- export const PLACEMENT_DECISION_REF_PREFIX = 'placement-';
24
-
25
- /**
26
- * WHICH shell surface a subject is placed on — a closed vocabulary, because
27
- * each member names a different authoring file with a different vocabulary,
28
- * and the dispatching coding agent derives which skill and which file from it.
29
- *
30
- * Deliberately NOT merged into one "navigation surface" bucket: a settings
31
- * placement names a rail CATEGORY, a sidebar placement names a sidebar
32
- * SECTION, and the two are different concepts that happen to both be groups.
33
- */
34
- export enum PlacementSurface {
35
- /** The settings hub rail (`frontend/src/config/settings-hub.config.ts`). Grouped by category. */
36
- SETTINGS_HUB = 'SETTINGS_HUB',
37
- /** The application sidebar (`appShellConfig[SIDEBAR].contentSections`). Grouped by section. */
38
- SIDEBAR = 'SIDEBAR',
39
- /** The user dropdown's settings entries. Flat — no groups. */
40
- USER_MENU = 'USER_MENU',
41
- /** The command palette (Cmd+K). Flat — its `category` is a search facet, not a placement group. */
42
- COMMAND_MENU = 'COMMAND_MENU',
43
- }
44
-
45
- /** The surfaces whose placements MUST name a declared group. The other members are flat by construction. */
46
- export const GROUPED_PLACEMENT_SURFACES: readonly PlacementSurface[] = [
47
- PlacementSurface.SETTINGS_HUB,
48
- PlacementSurface.SIDEBAR,
49
- ];
50
-
51
- /** WHAT is being placed. */
52
- export enum PlacementSubjectKind {
53
- /**
54
- * An engine-owned settings destination, named by its
55
- * `SettingsDestination.ref` (the engine catalog's id). The catalog itself
56
- * lives in the frontend package; `_core` deliberately does not import it, so
57
- * ref EXISTENCE is checked by the caller that holds the catalog — see
58
- * `validatePlacementPlan`'s `knownSubjectRefs`.
59
- */
60
- ENGINE_SETTINGS_DESTINATION = 'ENGINE_SETTINGS_DESTINATION',
61
- /** A resource operation surface the application owns (its LIST, its READ, a custom verb). */
62
- RESOURCE_OPERATION = 'RESOURCE_OPERATION',
63
- /** An application-scoped view (composite, chart, execution, full-custom). */
64
- APP_VIEW = 'APP_VIEW',
65
- }
66
-
67
- const SlugSchema = z.string().regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/);
68
- const NonEmptyStringSchema = z.string().trim().min(1);
69
-
70
- export const PlacementSubjectSchema = z.discriminatedUnion('kind', [
71
- z.strictObject({
72
- kind: z.literal(PlacementSubjectKind.ENGINE_SETTINGS_DESTINATION),
73
- destinationRef: SlugSchema,
74
- }),
75
- z.strictObject({
76
- kind: z.literal(PlacementSubjectKind.RESOURCE_OPERATION),
77
- moduleRef: SlugSchema,
78
- resourceRef: SlugSchema,
79
- /** The operation this placement surfaces (`list`, `read`, a custom verb ref). */
80
- operation: NonEmptyStringSchema,
81
- }),
82
- z.strictObject({
83
- kind: z.literal(PlacementSubjectKind.APP_VIEW),
84
- viewRef: SlugSchema,
85
- }),
86
- ]);
87
- export type PlacementSubject = z.infer<typeof PlacementSubjectSchema>;
88
-
89
- /**
90
- * A container the plan decides should exist on a grouped surface — a settings
91
- * rail category, or a sidebar section.
92
- *
93
- * `purpose` is prose, and it is load-bearing rather than decorative: it is what
94
- * grounds the generated `settings_hub.categories.<ref>.label` /
95
- * `sidebar_sections.<ref>.title` labels in authored intent instead of letting a
96
- * model invent filler from the ref alone. The plan does NOT author the label
97
- * string — that is the labelling pipeline's job.
98
- */
99
- export const PlacementGroupSchema = z.strictObject({
100
- groupRef: SlugSchema,
101
- /** Which grouped surface this group belongs to. */
102
- surface: z.enum(PlacementSurface),
103
- /** Why this group exists / what it gathers, from a product perspective. */
104
- purpose: NonEmptyStringSchema,
105
- /** Sort order among groups on its surface (lower = higher). */
106
- order: z.number().int().min(0),
107
- });
108
- export type PlacementGroup = z.infer<typeof PlacementGroupSchema>;
109
-
110
- /**
111
- * WHERE a placed subject sits. Discriminated on surface because the address
112
- * vocabularies genuinely differ: the grouped surfaces name a group, the flat
113
- * ones do not have one to name.
114
- */
115
- export const PlacementAddressSchema = z.discriminatedUnion('surface', [
116
- z.strictObject({
117
- surface: z.literal(PlacementSurface.SETTINGS_HUB),
118
- /** The `PlacementGroup.groupRef` of the settings rail category. */
119
- groupRef: SlugSchema,
120
- order: z.number().int().min(0),
121
- }),
122
- z.strictObject({
123
- surface: z.literal(PlacementSurface.SIDEBAR),
124
- /** The `PlacementGroup.groupRef` of the sidebar section. */
125
- groupRef: SlugSchema,
126
- order: z.number().int().min(0),
127
- }),
128
- z.strictObject({
129
- surface: z.literal(PlacementSurface.USER_MENU),
130
- order: z.number().int().min(0),
131
- }),
132
- z.strictObject({
133
- surface: z.literal(PlacementSurface.COMMAND_MENU),
134
- order: z.number().int().min(0),
135
- }),
136
- ]);
137
- export type PlacementAddress = z.infer<typeof PlacementAddressSchema>;
138
-
139
- /**
140
- * Whether a considered subject was placed or deliberately left unplaced.
141
- *
142
- * `DECLINED` is a first-class outcome, not an absence. A subject that is simply
143
- * missing from the plan is a COVERAGE GAP (the decision was never taken); a
144
- * subject recorded as `DECLINED` is a decision, with a reason a reader can
145
- * disagree with. Collapsing the two would make "we thought about it and said no"
146
- * indistinguishable from "nobody looked".
147
- */
148
- export enum PlacementDisposition {
149
- PLACED = 'PLACED',
150
- DECLINED = 'DECLINED',
151
- }
152
-
153
- /**
154
- * WHOSE judgement a decision currently represents.
155
- *
156
- * The placement plan is produced by an expert-panel deliberation, and every decision carries a
157
- * `rationale` written by that panel. Nothing stopped a later edit — a re-run, or a human changing
158
- * the landed file — from leaving that rationale in place while changing what it explains, so the
159
- * artifact went on asserting panel reasoning for a decision the panel never took.
160
- *
161
- * This is the field that makes the difference legible. It is REQUIRED and has NO DEFAULT, which is
162
- * the whole point: a defaulted `DELIBERATED` would mean silence claims the panel, and silence is
163
- * exactly what a hand-edit produces.
164
- *
165
- * ⚠️ TRUSTED, like `decisionRef`. `PlacementDecisionGenerationSchema` cannot express it, so a
166
- * provider cannot declare its own output a human revision; `parsePlacementPlanGeneration` stamps
167
- * `DELIBERATED` because a panel run is by definition the panel's judgement.
168
- *
169
- * ⚠️ This is not an audit trail and must not grow into one. Git already records WHO changed a
170
- * decision, WHEN, and with what commit message, mergeably and across branches
171
- * (`.claude/rules/one-source-of-truth.md`). What git cannot tell a reader who is looking at the
172
- * FILE — the config, in an editor, asking "why is Billing under Account?" — is that this particular
173
- * line is no longer what the panel decided. That is the one fact this carries.
174
- */
175
- export enum PlacementDecisionOrigin {
176
- /** The expert panel decided it, and nobody has changed it since. */
177
- DELIBERATED = 'DELIBERATED',
178
- /** A human changed it after the panel decided otherwise. {@link PlacementSupersededDecisionSchema} says what the panel had said. */
179
- REVISED = 'REVISED',
180
- }
181
-
182
- /**
183
- * What a revision replaced — the panel's own reasoning, kept beside the human's.
184
- *
185
- * Only the RATIONALE, deliberately. The decision schema's own note already says the reasoning is
186
- * "the artifact's most perishable and most valuable part", and it is the half a reader cannot
187
- * reconstruct: the prior address is visible in `git diff`, the prior argument is not, because a
188
- * diff shows the words that changed and never the case they were making.
189
- *
190
- * Keeping more — the old address, a timestamp, an author — would grow a shadow decision beside the
191
- * real one, and every one of those is something git already holds, in a form that merges.
192
- */
193
- export const PlacementSupersededDecisionSchema = z.strictObject({
194
- /** The rationale the panel gave for the decision this one replaced. */
195
- rationale: NonEmptyStringSchema,
196
- });
197
- export type PlacementSupersededDecision = z.infer<typeof PlacementSupersededDecisionSchema>;
198
-
199
- /**
200
- * One placement decision.
201
- *
202
- * `rationale` is REQUIRED on both arms. It is what lets a creator ask "why is
203
- * Billing under Organization?" and get an answer without re-running the panel
204
- * that decided it — the plan is produced by an expert-panel deliberation, so
205
- * the reasoning is the artifact's most perishable and most valuable part.
206
- *
207
- * A subject may legitimately be placed on SEVERAL surfaces (billing sits in the
208
- * settings rail AND answers to the command palette), so one decision per
209
- * (subject, surface) — never one per subject.
210
- */
211
- export const PlacementDecisionSchema = z.discriminatedUnion('disposition', [
212
- z.strictObject({
213
- /** `placement-<slug>`, stamped by the trusted runtime. */
214
- decisionRef: z.string().regex(new RegExp(`^${PLACEMENT_DECISION_REF_PREFIX}[a-z0-9]+(?:-[a-z0-9]+)*$`)),
215
- disposition: z.literal(PlacementDisposition.PLACED),
216
- /** Whose judgement this is. Required, never defaulted — see {@link PlacementDecisionOrigin}. */
217
- origin: z.enum(PlacementDecisionOrigin),
218
- subject: PlacementSubjectSchema,
219
- address: PlacementAddressSchema,
220
- /** Why this subject belongs at this address. One or two sentences, product-level. */
221
- rationale: NonEmptyStringSchema,
222
- /** Required exactly when `origin` is REVISED — enforced below, on the decision itself. */
223
- supersedes: PlacementSupersededDecisionSchema.optional(),
224
- }),
225
- z.strictObject({
226
- decisionRef: z.string().regex(new RegExp(`^${PLACEMENT_DECISION_REF_PREFIX}[a-z0-9]+(?:-[a-z0-9]+)*$`)),
227
- disposition: z.literal(PlacementDisposition.DECLINED),
228
- origin: z.enum(PlacementDecisionOrigin),
229
- subject: PlacementSubjectSchema,
230
- /** Why this subject is deliberately NOT surfaced anywhere. */
231
- rationale: NonEmptyStringSchema,
232
- supersedes: PlacementSupersededDecisionSchema.optional(),
233
- }),
234
- ]).superRefine((decision, context) => {
235
- /*
236
- * The pairing, enforced on the DECISION rather than on the plan.
237
- *
238
- * `PlacementDecisionSchema` is exported and parsed on its own, so a check that lived only in the
239
- * plan's `superRefine` would hold for a whole plan and not for a decision — one of the two call
240
- * sites of an invariant, which is the shape `.claude/rules/invariant-call-site-enumeration.md`
241
- * exists for. Here it cannot be bypassed by parsing at a different granularity.
242
- *
243
- * Both directions, and the second matters as much as the first. A REVISED decision with no
244
- * `supersedes` is the defect this whole field was added for, wearing the new vocabulary: it says
245
- * "a human changed this" and still cannot say what was changed. A DELIBERATED decision that
246
- * CARRIES a `supersedes` is a plan claiming the panel overruled itself — no run produces that, so
247
- * it can only come from an edit that changed one half and forgot the other.
248
- */
249
- if (decision.origin === PlacementDecisionOrigin.REVISED && decision.supersedes === undefined) {
250
- context.addIssue({
251
- code: 'custom',
252
- message: `placement decision "${decision.decisionRef}" is REVISED but records no superseded rationale — a revision must say what the panel had decided, or the artifact loses the argument it replaced`,
253
- path: ['supersedes'],
254
- });
255
- }
256
- if (decision.origin === PlacementDecisionOrigin.DELIBERATED && decision.supersedes !== undefined) {
257
- context.addIssue({
258
- code: 'custom',
259
- message: `placement decision "${decision.decisionRef}" is DELIBERATED and records a superseded rationale — a panel decision supersedes nothing; set origin to REVISED, or drop the supersedes block`,
260
- path: ['supersedes'],
261
- });
262
- }
263
- });
264
- export type PlacementDecision = z.infer<typeof PlacementDecisionSchema>;
265
-
266
- /**
267
- * THE placement payload — a **single aggregate per application**: which shell
268
- * surface every destination, resource operation and app view sits on, and why.
269
- *
270
- * **Artifact-family id: `placement-plan`.** This schema is the shape of the
271
- * journey artifact selected by `MetaWorkflow_ArtifactSelector.family ===
272
- * 'placement-plan'` (the `family` vocabulary stays an open string owned by the
273
- * selector surface; this note is the single place tying the SHAPE to the NAME).
274
- * Produced by the `bottom_up.placement-plan` playbook — an expert-panel
275
- * deliberation, not a creator elicitation — and consumed by `build-decompose`,
276
- * which turns it into the coding tasks that author the real config files.
277
- *
278
- * Invariants enforced HERE: unique decision refs; at least one decision; every
279
- * placement on a grouped surface names a group declared in this plan, of the
280
- * SAME surface; no two groups share a ref on one surface. Coherence beyond
281
- * structure — duplicate placements, empty groups, order collisions, coverage
282
- * against the engine catalog — is `validatePlacementPlan`'s job.
283
- */
284
- export const PlacementPlanSchema = z.object({
285
- version: z.enum(PlacementPlanVersion).default(PlacementPlanVersion.V1),
286
- /**
287
- * The groups the plan decides should exist. May be empty only when no
288
- * grouped-surface placement is made — enforced below rather than by a
289
- * `min(1)`, because a plan that places nothing but command-menu entries is
290
- * legitimate and needs no group.
291
- */
292
- groups: z.array(PlacementGroupSchema).default([]),
293
- /**
294
- * At least one decision, at the SCHEMA. A plan that decided nothing is a
295
- * refusal ("there was nothing to place"), never an artifact — and an empty
296
- * artifact that LANDS overwrites a real one, which is exactly how a completed
297
- * 3-task build plan was destroyed by a vacuous one on 2026-08-24.
298
- */
299
- decisions: z.array(PlacementDecisionSchema).min(1),
300
- }).superRefine((plan, context) => {
301
- const groupKeys = new Set<string>();
302
- plan.groups.forEach((group, index) => {
303
- const key = `${group.surface}::${group.groupRef}`;
304
- if (groupKeys.has(key)) {
305
- context.addIssue({ code: 'custom', message: `duplicate placement group "${group.groupRef}" on surface ${group.surface}`, path: ['groups', index, 'groupRef'] });
306
- }
307
- groupKeys.add(key);
308
- });
309
-
310
- const decisionRefs = new Set<string>();
311
- plan.decisions.forEach((decision, index) => {
312
- if (decisionRefs.has(decision.decisionRef)) {
313
- context.addIssue({ code: 'custom', message: `duplicate placement decision ref "${decision.decisionRef}"`, path: ['decisions', index, 'decisionRef'] });
314
- }
315
- decisionRefs.add(decision.decisionRef);
316
-
317
- if (decision.disposition !== PlacementDisposition.PLACED) return;
318
- const address = decision.address;
319
- if (!('groupRef' in address)) return;
320
- if (!groupKeys.has(`${address.surface}::${address.groupRef}`)) {
321
- context.addIssue({
322
- code: 'custom',
323
- message: `placement "${decision.decisionRef}" names group "${address.groupRef}", which this plan does not declare for surface ${address.surface}`,
324
- path: ['decisions', index, 'address', 'groupRef'],
325
- });
326
- }
327
- });
328
- });
329
- export type PlacementPlan = z.infer<typeof PlacementPlanSchema>;
330
- ```