@howone/agent-cli 0.0.0-stage → 0.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (228) hide show
  1. package/README.md +34 -2
  2. package/bin/index.d.mts +1 -0
  3. package/bin/index.mjs +2450 -0
  4. package/package.json +55 -4
  5. package/skills/howone/01-apps.md +29 -0
  6. package/skills/howone/02-develop.md +107 -0
  7. package/skills/howone/03-workflows.md +71 -0
  8. package/skills/howone/04-functions-and-data.md +41 -0
  9. package/skills/howone/05-capabilities.md +46 -0
  10. package/skills/howone/SKILL.md +52 -0
  11. package/templates/vite/.howone/skills/hallmark/SKILL.md +557 -0
  12. package/templates/vite/.howone/skills/hallmark/references/anti-patterns.md +418 -0
  13. package/templates/vite/.howone/skills/hallmark/references/assets.md +406 -0
  14. package/templates/vite/.howone/skills/hallmark/references/color.md +95 -0
  15. package/templates/vite/.howone/skills/hallmark/references/component-cookbook.md +265 -0
  16. package/templates/vite/.howone/skills/hallmark/references/components/c1-outlined-chip.md +12 -0
  17. package/templates/vite/.howone/skills/hallmark/references/components/c2-inline-form-as-cta.md +16 -0
  18. package/templates/vite/.howone/skills/hallmark/references/components/c3-typographic-link.md +8 -0
  19. package/templates/vite/.howone/skills/hallmark/references/components/c4-sticky-bottom-bar.md +16 -0
  20. package/templates/vite/.howone/skills/hallmark/references/components/f1-bento-grid.md +20 -0
  21. package/templates/vite/.howone/skills/hallmark/references/components/f2-sticky-scroll-stack.md +20 -0
  22. package/templates/vite/.howone/skills/hallmark/references/components/f3-tabular-spec-sheet.md +11 -0
  23. package/templates/vite/.howone/skills/hallmark/references/components/f4-step-sequence.md +11 -0
  24. package/templates/vite/.howone/skills/hallmark/references/components/f5-annotated-screenshot.md +11 -0
  25. package/templates/vite/.howone/skills/hallmark/references/components/f6-product-card-grid.md +41 -0
  26. package/templates/vite/.howone/skills/hallmark/references/components/ft1-mast-headed.md +13 -0
  27. package/templates/vite/.howone/skills/hallmark/references/components/ft2-inline-rule-single-line.md +10 -0
  28. package/templates/vite/.howone/skills/hallmark/references/components/ft3-index-style-category-list.md +12 -0
  29. package/templates/vite/.howone/skills/hallmark/references/components/ft4-dense-typographic.md +10 -0
  30. package/templates/vite/.howone/skills/hallmark/references/components/ft5-statement.md +21 -0
  31. package/templates/vite/.howone/skills/hallmark/references/components/ft6-letter-close.md +19 -0
  32. package/templates/vite/.howone/skills/hallmark/references/components/ft7-newsletter-first.md +27 -0
  33. package/templates/vite/.howone/skills/hallmark/references/components/ft8-marquee-scroll.md +25 -0
  34. package/templates/vite/.howone/skills/hallmark/references/components/h1-marquee.md +15 -0
  35. package/templates/vite/.howone/skills/hallmark/references/components/h2-split-diptych.md +15 -0
  36. package/templates/vite/.howone/skills/hallmark/references/components/h3-quote-led.md +11 -0
  37. package/templates/vite/.howone/skills/hallmark/references/components/h4-stat-led.md +14 -0
  38. package/templates/vite/.howone/skills/hallmark/references/components/h5-letter-hero.md +11 -0
  39. package/templates/vite/.howone/skills/hallmark/references/components/h6-photographic-fold.md +16 -0
  40. package/templates/vite/.howone/skills/hallmark/references/components/h7-demo-video-clipped-by-viewport-edge.md +27 -0
  41. package/templates/vite/.howone/skills/hallmark/references/components/h8-mockup-split-browser-framed.md +23 -0
  42. package/templates/vite/.howone/skills/hallmark/references/components/h9-custom-illustration-centerpiece.md +27 -0
  43. package/templates/vite/.howone/skills/hallmark/references/components/n1-wordmark-2-links.md +12 -0
  44. package/templates/vite/.howone/skills/hallmark/references/components/n10-floating-on-scroll-morph.md +19 -0
  45. package/templates/vite/.howone/skills/hallmark/references/components/n11-mega-menu.md +40 -0
  46. package/templates/vite/.howone/skills/hallmark/references/components/n12-banner-retract.md +34 -0
  47. package/templates/vite/.howone/skills/hallmark/references/components/n13-inline-cmdk-pill.md +39 -0
  48. package/templates/vite/.howone/skills/hallmark/references/components/n1b-saas-three-section.md +35 -0
  49. package/templates/vite/.howone/skills/hallmark/references/components/n2-floating-chip.md +14 -0
  50. package/templates/vite/.howone/skills/hallmark/references/components/n3-side-rail.md +14 -0
  51. package/templates/vite/.howone/skills/hallmark/references/components/n4-hidden-behind-k.md +9 -0
  52. package/templates/vite/.howone/skills/hallmark/references/components/n5-floating-pill.md +28 -0
  53. package/templates/vite/.howone/skills/hallmark/references/components/n6-newspaper-masthead.md +24 -0
  54. package/templates/vite/.howone/skills/hallmark/references/components/n7-brutal-slab.md +22 -0
  55. package/templates/vite/.howone/skills/hallmark/references/components/n8-terminal-command.md +21 -0
  56. package/templates/vite/.howone/skills/hallmark/references/components/n9-edge-aligned-minimal.md +17 -0
  57. package/templates/vite/.howone/skills/hallmark/references/components/s1-left-margin-numbered.md +15 -0
  58. package/templates/vite/.howone/skills/hallmark/references/components/s2-hanging.md +13 -0
  59. package/templates/vite/.howone/skills/hallmark/references/components/s3-sticky-pinned.md +19 -0
  60. package/templates/vite/.howone/skills/hallmark/references/components/s4-inline-no-break.md +11 -0
  61. package/templates/vite/.howone/skills/hallmark/references/components/s5-bottom-anchored.md +13 -0
  62. package/templates/vite/.howone/skills/hallmark/references/components/t1-pull-quote-with-marginalia.md +12 -0
  63. package/templates/vite/.howone/skills/hallmark/references/components/t2-logo-wall-hairline.md +19 -0
  64. package/templates/vite/.howone/skills/hallmark/references/components/t3-single-huge-quote.md +11 -0
  65. package/templates/vite/.howone/skills/hallmark/references/components/t4-numbered-stat-strip.md +14 -0
  66. package/templates/vite/.howone/skills/hallmark/references/contract.md +24 -0
  67. package/templates/vite/.howone/skills/hallmark/references/copy.md +182 -0
  68. package/templates/vite/.howone/skills/hallmark/references/custom-craft.md +626 -0
  69. package/templates/vite/.howone/skills/hallmark/references/custom-theme.md +367 -0
  70. package/templates/vite/.howone/skills/hallmark/references/design-md.md +116 -0
  71. package/templates/vite/.howone/skills/hallmark/references/export-formats.md +328 -0
  72. package/templates/vite/.howone/skills/hallmark/references/floating-nav.md +89 -0
  73. package/templates/vite/.howone/skills/hallmark/references/genres/atmospheric.md +69 -0
  74. package/templates/vite/.howone/skills/hallmark/references/genres/editorial.md +72 -0
  75. package/templates/vite/.howone/skills/hallmark/references/genres/modern-minimal.md +71 -0
  76. package/templates/vite/.howone/skills/hallmark/references/genres/playful.md +70 -0
  77. package/templates/vite/.howone/skills/hallmark/references/hero-enrichment.md +475 -0
  78. package/templates/vite/.howone/skills/hallmark/references/imagery-kit.md +170 -0
  79. package/templates/vite/.howone/skills/hallmark/references/interaction-and-states.md +208 -0
  80. package/templates/vite/.howone/skills/hallmark/references/layout-and-space.md +112 -0
  81. package/templates/vite/.howone/skills/hallmark/references/macrostructures/01-bento-grid.md +35 -0
  82. package/templates/vite/.howone/skills/hallmark/references/macrostructures/02-long-document.md +34 -0
  83. package/templates/vite/.howone/skills/hallmark/references/macrostructures/03-marquee-hero.md +31 -0
  84. package/templates/vite/.howone/skills/hallmark/references/macrostructures/04-stat-led.md +34 -0
  85. package/templates/vite/.howone/skills/hallmark/references/macrostructures/05-workbench.md +32 -0
  86. package/templates/vite/.howone/skills/hallmark/references/macrostructures/06-conversational-faq.md +33 -0
  87. package/templates/vite/.howone/skills/hallmark/references/macrostructures/07-manifesto.md +32 -0
  88. package/templates/vite/.howone/skills/hallmark/references/macrostructures/08-photographic.md +34 -0
  89. package/templates/vite/.howone/skills/hallmark/references/macrostructures/09-quote-led.md +32 -0
  90. package/templates/vite/.howone/skills/hallmark/references/macrostructures/10-specimen.md +32 -0
  91. package/templates/vite/.howone/skills/hallmark/references/macrostructures/11-catalogue.md +23 -0
  92. package/templates/vite/.howone/skills/hallmark/references/macrostructures/12-letter.md +23 -0
  93. package/templates/vite/.howone/skills/hallmark/references/macrostructures/13-index-first.md +23 -0
  94. package/templates/vite/.howone/skills/hallmark/references/macrostructures/14-narrative-workflow.md +23 -0
  95. package/templates/vite/.howone/skills/hallmark/references/macrostructures/15-split-studio.md +23 -0
  96. package/templates/vite/.howone/skills/hallmark/references/macrostructures/16-feature-stack.md +23 -0
  97. package/templates/vite/.howone/skills/hallmark/references/macrostructures/17-type-specimen.md +23 -0
  98. package/templates/vite/.howone/skills/hallmark/references/macrostructures/18-portfolio-grid.md +23 -0
  99. package/templates/vite/.howone/skills/hallmark/references/macrostructures/19-map-diagram.md +23 -0
  100. package/templates/vite/.howone/skills/hallmark/references/macrostructures/20-ecosystem-index.md +23 -0
  101. package/templates/vite/.howone/skills/hallmark/references/macrostructures/21-component-playground.md +23 -0
  102. package/templates/vite/.howone/skills/hallmark/references/macrostructures.md +89 -0
  103. package/templates/vite/.howone/skills/hallmark/references/microinteractions.md +258 -0
  104. package/templates/vite/.howone/skills/hallmark/references/motion.md +109 -0
  105. package/templates/vite/.howone/skills/hallmark/references/preview-examples.md +49 -0
  106. package/templates/vite/.howone/skills/hallmark/references/responsive.md +138 -0
  107. package/templates/vite/.howone/skills/hallmark/references/slop-test.md +192 -0
  108. package/templates/vite/.howone/skills/hallmark/references/structure.md +160 -0
  109. package/templates/vite/.howone/skills/hallmark/references/study.md +509 -0
  110. package/templates/vite/.howone/skills/hallmark/references/themes/carnival.md +301 -0
  111. package/templates/vite/.howone/skills/hallmark/references/themes/cobalt.md +146 -0
  112. package/templates/vite/.howone/skills/hallmark/references/themes/hum.md +403 -0
  113. package/templates/vite/.howone/skills/hallmark/references/themes/lumen.md +478 -0
  114. package/templates/vite/.howone/skills/hallmark/references/typography.md +243 -0
  115. package/templates/vite/.howone/skills/hallmark/references/verbs/audit.md +25 -0
  116. package/templates/vite/.howone/skills/hallmark/references/verbs/redesign.md +269 -0
  117. package/templates/vite/.howone/skills/howone/01-architect/01-app-generation.md +209 -0
  118. package/templates/vite/.howone/skills/howone/01-architect/02-manifest-codegen.md +194 -0
  119. package/templates/vite/.howone/skills/howone/02-entity-schema/01-schema-design.md +523 -0
  120. package/templates/vite/.howone/skills/howone/02-entity-schema/02-schema-operations.md +329 -0
  121. package/templates/vite/.howone/skills/howone/02-entity-schema/03-access-models.md +151 -0
  122. package/templates/vite/.howone/skills/howone/02-entity-schema/04-query-contracts.md +123 -0
  123. package/templates/vite/.howone/skills/howone/02-entity-schema/05-ai-persistence-patterns.md +255 -0
  124. package/templates/vite/.howone/skills/howone/03-ai-capabilities/01-ai-capability-architecture.md +215 -0
  125. package/templates/vite/.howone/skills/howone/03-ai-capabilities/02-workflow-contract-rules.md +427 -0
  126. package/templates/vite/.howone/skills/howone/03-ai-capabilities/03-service-capability-catalog.md +304 -0
  127. package/templates/vite/.howone/skills/howone/03-ai-capabilities/04-workflow-operations.md +164 -0
  128. package/templates/vite/.howone/skills/howone/03-ai-capabilities/05-ai-feature-playbooks.md +275 -0
  129. package/templates/vite/.howone/skills/howone/04-app-sdk/01-client-setup.md +162 -0
  130. package/templates/vite/.howone/skills/howone/04-app-sdk/02-entity-operations.md +163 -0
  131. package/templates/vite/.howone/skills/howone/04-app-sdk/03-auth.md +418 -0
  132. package/templates/vite/.howone/skills/howone/04-app-sdk/04-react-integration.md +138 -0
  133. package/templates/vite/.howone/skills/howone/04-app-sdk/05-file-upload.md +112 -0
  134. package/templates/vite/.howone/skills/howone/04-app-sdk/06-raw-http.md +128 -0
  135. package/templates/vite/.howone/skills/howone/04-app-sdk/07-ai-action-calls.md +210 -0
  136. package/templates/vite/.howone/skills/howone/04-app-sdk/08-ai-manifest-handoff.md +90 -0
  137. package/templates/vite/.howone/skills/howone/04-app-sdk/09-extension-boundaries.md +226 -0
  138. package/templates/vite/.howone/skills/howone/04-app-sdk/10-workflow-execute-sse.md +138 -0
  139. package/templates/vite/.howone/skills/howone/04-app-sdk/11-entity-data-access-patterns.md +310 -0
  140. package/templates/vite/.howone/skills/howone/04-app-sdk/12-query-dsl-and-responses.md +237 -0
  141. package/templates/vite/.howone/skills/howone/04-app-sdk/13-credits.md +31 -0
  142. package/templates/vite/.howone/skills/howone/SKILL.md +256 -0
  143. package/templates/vite/.howone/skills/howone/agents/openai.yaml +4 -0
  144. package/templates/vite/.howone/skills/howone/references/audio-generation.md +30 -0
  145. package/templates/vite/.howone/skills/howone/references/audio-recognition.md +30 -0
  146. package/templates/vite/.howone/skills/howone/references/common-errors.md +27 -0
  147. package/templates/vite/.howone/skills/howone/references/finance.md +28 -0
  148. package/templates/vite/.howone/skills/howone/references/image-editing.md +30 -0
  149. package/templates/vite/.howone/skills/howone/references/image-generation.md +30 -0
  150. package/templates/vite/.howone/skills/howone/references/version-evidence.md +47 -0
  151. package/templates/vite/.howone/skills/howone/references/video-generation.md +35 -0
  152. package/templates/vite/.howone/skills/howone/scripts/verify-project.mjs +151 -0
  153. package/templates/vite/.prettierignore +7 -0
  154. package/templates/vite/.prettierrc +11 -0
  155. package/templates/vite/AGENTS.md +87 -0
  156. package/templates/vite/README.md +21 -0
  157. package/templates/vite/components.json +25 -0
  158. package/templates/vite/eslint.config.js +23 -0
  159. package/templates/vite/index.html +12 -0
  160. package/templates/vite/package.json +58 -0
  161. package/templates/vite/public/vite.svg +1 -0
  162. package/templates/vite/src/App.tsx +17 -0
  163. package/templates/vite/src/assets/react.svg +1 -0
  164. package/templates/vite/src/components/theme-provider.tsx +230 -0
  165. package/templates/vite/src/components/ui/accordion.tsx +79 -0
  166. package/templates/vite/src/components/ui/alert-dialog.tsx +197 -0
  167. package/templates/vite/src/components/ui/alert.tsx +76 -0
  168. package/templates/vite/src/components/ui/aspect-ratio.tsx +11 -0
  169. package/templates/vite/src/components/ui/avatar.tsx +110 -0
  170. package/templates/vite/src/components/ui/badge.tsx +49 -0
  171. package/templates/vite/src/components/ui/breadcrumb.tsx +122 -0
  172. package/templates/vite/src/components/ui/button-group.tsx +83 -0
  173. package/templates/vite/src/components/ui/button.tsx +67 -0
  174. package/templates/vite/src/components/ui/calendar.tsx +222 -0
  175. package/templates/vite/src/components/ui/card.tsx +103 -0
  176. package/templates/vite/src/components/ui/carousel.tsx +240 -0
  177. package/templates/vite/src/components/ui/chart.tsx +373 -0
  178. package/templates/vite/src/components/ui/checkbox.tsx +31 -0
  179. package/templates/vite/src/components/ui/collapsible.tsx +33 -0
  180. package/templates/vite/src/components/ui/combobox.tsx +299 -0
  181. package/templates/vite/src/components/ui/command.tsx +193 -0
  182. package/templates/vite/src/components/ui/context-menu.tsx +261 -0
  183. package/templates/vite/src/components/ui/dialog.tsx +168 -0
  184. package/templates/vite/src/components/ui/direction.tsx +22 -0
  185. package/templates/vite/src/components/ui/drawer.tsx +132 -0
  186. package/templates/vite/src/components/ui/dropdown-menu.tsx +269 -0
  187. package/templates/vite/src/components/ui/empty.tsx +104 -0
  188. package/templates/vite/src/components/ui/field.tsx +238 -0
  189. package/templates/vite/src/components/ui/hover-card.tsx +42 -0
  190. package/templates/vite/src/components/ui/input-group.tsx +154 -0
  191. package/templates/vite/src/components/ui/input-otp.tsx +87 -0
  192. package/templates/vite/src/components/ui/input.tsx +19 -0
  193. package/templates/vite/src/components/ui/item.tsx +196 -0
  194. package/templates/vite/src/components/ui/kbd.tsx +26 -0
  195. package/templates/vite/src/components/ui/label.tsx +22 -0
  196. package/templates/vite/src/components/ui/menubar.tsx +280 -0
  197. package/templates/vite/src/components/ui/native-select.tsx +61 -0
  198. package/templates/vite/src/components/ui/navigation-menu.tsx +164 -0
  199. package/templates/vite/src/components/ui/pagination.tsx +129 -0
  200. package/templates/vite/src/components/ui/popover.tsx +87 -0
  201. package/templates/vite/src/components/ui/progress.tsx +31 -0
  202. package/templates/vite/src/components/ui/radio-group.tsx +42 -0
  203. package/templates/vite/src/components/ui/resizable.tsx +50 -0
  204. package/templates/vite/src/components/ui/scroll-area.tsx +53 -0
  205. package/templates/vite/src/components/ui/select.tsx +192 -0
  206. package/templates/vite/src/components/ui/separator.tsx +26 -0
  207. package/templates/vite/src/components/ui/sheet.tsx +145 -0
  208. package/templates/vite/src/components/ui/sidebar.tsx +700 -0
  209. package/templates/vite/src/components/ui/skeleton.tsx +13 -0
  210. package/templates/vite/src/components/ui/slider.tsx +59 -0
  211. package/templates/vite/src/components/ui/sonner.tsx +47 -0
  212. package/templates/vite/src/components/ui/spinner.tsx +10 -0
  213. package/templates/vite/src/components/ui/switch.tsx +33 -0
  214. package/templates/vite/src/components/ui/table.tsx +114 -0
  215. package/templates/vite/src/components/ui/tabs.tsx +90 -0
  216. package/templates/vite/src/components/ui/textarea.tsx +18 -0
  217. package/templates/vite/src/components/ui/toggle-group.tsx +89 -0
  218. package/templates/vite/src/components/ui/toggle.tsx +45 -0
  219. package/templates/vite/src/components/ui/tooltip.tsx +57 -0
  220. package/templates/vite/src/hooks/use-mobile.ts +19 -0
  221. package/templates/vite/src/index.css +133 -0
  222. package/templates/vite/src/lib/sdk.ts +34 -0
  223. package/templates/vite/src/lib/utils.ts +6 -0
  224. package/templates/vite/src/main.tsx +14 -0
  225. package/templates/vite/tsconfig.app.json +32 -0
  226. package/templates/vite/tsconfig.json +13 -0
  227. package/templates/vite/tsconfig.node.json +26 -0
  228. package/templates/vite/vite.config.ts +14 -0
@@ -0,0 +1,427 @@
1
+ # Workflow Contract Rules
2
+
3
+ Use this reference when designing `capability.description`, `inputSchema`, `outputSchema`, and
4
+ `outputEntityName` for HowOne AI workflows.
5
+
6
+ These rules come from `docs/ai-worlfow-guide-schema.md`. Violating them can make the workflow
7
+ service reject the request or produce a workflow the runtime cannot execute reliably.
8
+
9
+ ## Contract Shape
10
+
11
+ ```json
12
+ {
13
+ "name": "summarizeDocument",
14
+ "description": "Reads an uploaded document and produces a concise summary highlighting the key points.",
15
+ "inputSchema": {
16
+ "type": "object",
17
+ "properties": {
18
+ "document_url": {
19
+ "type": "string",
20
+ "format": "uri",
21
+ "description": "Supabase Storage URL of the uploaded document."
22
+ },
23
+ "summary_length": {
24
+ "type": "string",
25
+ "description": "Desired summary length, e.g. short, medium, long, or a specific sentence count."
26
+ }
27
+ },
28
+ "required": ["document_url"]
29
+ },
30
+ "outputSchema": {
31
+ "type": "object",
32
+ "properties": {
33
+ "summary": {
34
+ "type": "string",
35
+ "description": "The generated summary in the same language as the source document."
36
+ }
37
+ },
38
+ "required": ["summary"]
39
+ },
40
+ "outputEntityName": "DocumentSummary"
41
+ }
42
+ ```
43
+
44
+ ## Loose JSON Schema
45
+
46
+ The workflow engine is agentic. Overly strict schemas reduce reliability.
47
+
48
+ Do:
49
+
50
+ - require only essential inputs;
51
+ - make non-essential options optional;
52
+ - use strings with good descriptions for open-ended user choices;
53
+ - use nested objects only when the product truly needs structured output;
54
+ - use `format: "uri"` for URLs.
55
+
56
+ Avoid:
57
+
58
+ - `minLength`, `maxLength`, `pattern` unless technically required;
59
+ - enum for open-ended values like tone, style, audience, mood;
60
+ - many required knobs that normal users do not understand;
61
+ - provider/model/tool names in schema fields.
62
+
63
+ Good:
64
+
65
+ ```json
66
+ {
67
+ "tone": {
68
+ "type": "string",
69
+ "description": "Desired writing tone, e.g. formal, casual, humorous, empathetic, professional."
70
+ }
71
+ }
72
+ ```
73
+
74
+ Bad:
75
+
76
+ ```json
77
+ {
78
+ "tone": {
79
+ "type": "string",
80
+ "enum": ["formal", "casual", "humorous"],
81
+ "minLength": 3,
82
+ "maxLength": 20
83
+ }
84
+ }
85
+ ```
86
+
87
+ Use enum only for closed domains such as `"daily" | "minute"` or known output modes.
88
+
89
+ ## URLs Only For Files
90
+
91
+ All file exchange uses cloud storage URLs.
92
+
93
+ Correct inputs:
94
+
95
+ ```json
96
+ {
97
+ "source_image_url": {
98
+ "type": "string",
99
+ "format": "uri",
100
+ "description": "Public URL of the source image to edit."
101
+ }
102
+ }
103
+ ```
104
+
105
+ Correct outputs:
106
+
107
+ ```json
108
+ {
109
+ "edited_image_url": {
110
+ "type": "string",
111
+ "format": "uri",
112
+ "description": "Public URL of the edited image."
113
+ }
114
+ }
115
+ ```
116
+
117
+ Forbidden:
118
+
119
+ - raw `File` / `Blob`;
120
+ - base64 content;
121
+ - `contentEncoding`;
122
+ - inline PDF/image/audio bytes;
123
+ - browser upload logic in workflow.
124
+
125
+ The app uploads first, then passes the resulting URL to the workflow. File upload helpers belong to
126
+ the SDK track.
127
+
128
+ ## Output Minimalism
129
+
130
+ Every output field costs model attention. Only include what the product will render or persist.
131
+
132
+ Usually forbidden unless explicitly requested:
133
+
134
+ - `processing_time`, `timestamp`, `created_at`;
135
+ - `model_used`, `provider`, `version`;
136
+ - `file_size`, `mime_type`, `resolution`, `frame_rate`;
137
+ - `confidence_score`, `bounding_boxes`, `coordinates`;
138
+ - style/color/tone metadata when user only asked for an asset.
139
+
140
+ Examples:
141
+
142
+ | User asks | Good output | Avoid |
143
+ |---|---|---|
144
+ | Summarize a PDF | `summary` | `summary`, `word_count`, `reading_time` |
145
+ | Generate image | `generated_image_url` | `generated_image_url`, `model_used`, `color_palette` |
146
+ | OCR image | `extracted_text` | `extracted_text`, `confidence_score`, `bounding_boxes` |
147
+ | Generate video | `video_url` | `video_url`, `duration_seconds`, `frame_rate` |
148
+
149
+ If the app needs history metadata, put it in the entity schema, not workflow output.
150
+
151
+ ## Input / Output Names Must Not Overlap
152
+
153
+ Input and output property names share a routing namespace. Do not reuse names.
154
+
155
+ | Scenario | Bad | Good |
156
+ |---|---|---|
157
+ | Translation | input `text`, output `text` | input `source_text`, output `translated_text` |
158
+ | Summary | input `content`, output `content` | input `source_content`, output `summary` |
159
+ | Image edit | input `image_url`, output `image_url` | input `source_image_url`, output `edited_image_url` |
160
+ | Audio transcript | input `audio_url`, output `audio_url` | input `source_audio_url`, output `transcript_text` |
161
+
162
+ ## Description Says What, Not How
163
+
164
+ `capability.description` describes the user-visible outcome.
165
+
166
+ Good:
167
+
168
+ ```json
169
+ "description": "Searches the web for recent news on a topic and produces a structured briefing with source links."
170
+ ```
171
+
172
+ Bad:
173
+
174
+ ```json
175
+ "description": "First calls search_web, then summarizes articles with an LLM, then saves the result."
176
+ ```
177
+
178
+ Do not mention:
179
+
180
+ - internal tool names;
181
+ - step sequences;
182
+ - model/provider names;
183
+ - database writes;
184
+ - storage implementation details except URL inputs/outputs.
185
+
186
+ ## Output Language Must Be Explicit
187
+
188
+ Every text output field description must say what language to use.
189
+
190
+ Patterns:
191
+
192
+ ```json
193
+ "summary": {
194
+ "type": "string",
195
+ "description": "Summary in the same language as the source document."
196
+ }
197
+ ```
198
+
199
+ ```json
200
+ "translated_text": {
201
+ "type": "string",
202
+ "description": "Translated text in the target language specified by 'target_language'."
203
+ }
204
+ ```
205
+
206
+ ```json
207
+ "briefing": {
208
+ "type": "string",
209
+ "description": "Briefing written in the language specified by 'language'."
210
+ }
211
+ ```
212
+
213
+ Do not write vague descriptions like `"The translated text."`
214
+
215
+ ## No CRUD In Workflow
216
+
217
+ Workflow belongs to intelligent processing. App persistence belongs to entities.
218
+
219
+ Forbidden in capability descriptions and schemas:
220
+
221
+ - "save to database";
222
+ - "create user record";
223
+ - "update task status";
224
+ - "delete previous result";
225
+ - "read current user's records";
226
+ - "assign owner".
227
+
228
+ Instead:
229
+
230
+ 1. workflow returns output fields;
231
+ 2. app code persists through the entity runtime after SDK handoff;
232
+ 3. durable fields map to the entity contract.
233
+
234
+ ## External Data Assumptions
235
+
236
+ Do not require user-provided datasets unless the user said they have them.
237
+
238
+ | User asks | Bad input | Better input |
239
+ |---|---|---|
240
+ | Stock analysis app | `stock_data_csv_url` | `trading_symbol`, `start_date`, `end_date` |
241
+ | Latest news app | `article_urls` | `topic`, `language` |
242
+ | Academic research | `paper_pdf_urls` | `query`, optional `year_range` |
243
+ | Product comparison | `product_dataset_url` | `product_names` or `search_topic` |
244
+
245
+ The workflow should use available retrieval/search capabilities when data is external.
246
+
247
+ ## Raw JSON Requirement
248
+
249
+ Schemas must be raw JSON objects:
250
+
251
+ - start with `{` and end with `}`;
252
+ - ASCII double quotes;
253
+ - no trailing commas;
254
+ - no `undefined`, `NaN`, comments, or single quotes;
255
+ - not a string containing escaped JSON.
256
+
257
+ Good:
258
+
259
+ ```json
260
+ { "type": "object", "properties": {} }
261
+ ```
262
+
263
+ Bad:
264
+
265
+ ```json
266
+ "{ \"type\": \"object\" }"
267
+ ```
268
+
269
+ ## Schema Pattern Templates
270
+
271
+ ### Text generation
272
+
273
+ ```json
274
+ {
275
+ "inputSchema": {
276
+ "type": "object",
277
+ "properties": {
278
+ "topic": {
279
+ "type": "string",
280
+ "description": "Topic to write about."
281
+ },
282
+ "audience": {
283
+ "type": "string",
284
+ "description": "Intended audience, e.g. executives, children, developers, or general readers."
285
+ },
286
+ "language": {
287
+ "type": "string",
288
+ "description": "Output language, e.g. English or Chinese."
289
+ }
290
+ },
291
+ "required": ["topic"]
292
+ },
293
+ "outputSchema": {
294
+ "type": "object",
295
+ "properties": {
296
+ "generated_text": {
297
+ "type": "string",
298
+ "description": "Generated text in the language specified by 'language', or English if not specified."
299
+ }
300
+ },
301
+ "required": ["generated_text"]
302
+ }
303
+ }
304
+ ```
305
+
306
+ ### Image generation
307
+
308
+ ```json
309
+ {
310
+ "inputSchema": {
311
+ "type": "object",
312
+ "properties": {
313
+ "image_description": {
314
+ "type": "string",
315
+ "description": "Detailed description of the image to generate, including subject, style, mood, and composition."
316
+ },
317
+ "style_preference": {
318
+ "type": "string",
319
+ "description": "Optional style preference such as watercolor, pixel art, photorealistic, anime, or flat design."
320
+ }
321
+ },
322
+ "required": ["image_description"]
323
+ },
324
+ "outputSchema": {
325
+ "type": "object",
326
+ "properties": {
327
+ "generated_image_url": {
328
+ "type": "string",
329
+ "format": "uri",
330
+ "description": "Public URL of the generated image."
331
+ }
332
+ },
333
+ "required": ["generated_image_url"]
334
+ }
335
+ }
336
+ ```
337
+
338
+ ### Image editing
339
+
340
+ ```json
341
+ {
342
+ "inputSchema": {
343
+ "type": "object",
344
+ "properties": {
345
+ "source_image_url": {
346
+ "type": "string",
347
+ "format": "uri",
348
+ "description": "Public URL of the image to edit."
349
+ },
350
+ "edit_instruction": {
351
+ "type": "string",
352
+ "description": "Natural language instruction describing the desired edit."
353
+ }
354
+ },
355
+ "required": ["source_image_url", "edit_instruction"]
356
+ },
357
+ "outputSchema": {
358
+ "type": "object",
359
+ "properties": {
360
+ "edited_image_url": {
361
+ "type": "string",
362
+ "format": "uri",
363
+ "description": "Public URL of the edited image."
364
+ }
365
+ },
366
+ "required": ["edited_image_url"]
367
+ }
368
+ }
369
+ ```
370
+
371
+ ### Research briefing
372
+
373
+ ```json
374
+ {
375
+ "inputSchema": {
376
+ "type": "object",
377
+ "properties": {
378
+ "topic": {
379
+ "type": "string",
380
+ "description": "Research topic or question."
381
+ },
382
+ "language": {
383
+ "type": "string",
384
+ "description": "Language for the output briefing."
385
+ }
386
+ },
387
+ "required": ["topic"]
388
+ },
389
+ "outputSchema": {
390
+ "type": "object",
391
+ "properties": {
392
+ "briefing": {
393
+ "type": "object",
394
+ "description": "Structured briefing written in the language specified by 'language'.",
395
+ "properties": {
396
+ "summary": { "type": "string" },
397
+ "sources": {
398
+ "type": "array",
399
+ "items": {
400
+ "type": "object",
401
+ "properties": {
402
+ "title": { "type": "string" },
403
+ "url": { "type": "string", "format": "uri" },
404
+ "key_point": { "type": "string" }
405
+ }
406
+ }
407
+ }
408
+ },
409
+ "required": ["summary", "sources"]
410
+ }
411
+ },
412
+ "required": ["briefing"]
413
+ }
414
+ }
415
+ ```
416
+
417
+ ## Contract Checklist
418
+
419
+ - Required inputs are essential only.
420
+ - File inputs/outputs are URL strings.
421
+ - Output contains only the requested product result.
422
+ - Input/output property names do not overlap.
423
+ - Text output descriptions specify language.
424
+ - Description says what, not how.
425
+ - No CRUD/auth/upload/payment/app-state requirements.
426
+ - Feature fits an available capability.
427
+ - Schema is raw valid JSON.