factoryhub 0.0.0-stage → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (156) hide show
  1. package/LICENSE +202 -0
  2. package/NOTICE +16 -0
  3. package/README.md +195 -2
  4. package/factories/README.md +17 -0
  5. package/factories/client-file-readiness/README.md +3 -0
  6. package/factories/client-file-readiness/agents/analyst/agent.md +10 -0
  7. package/factories/client-file-readiness/agents/reviewer/agent.md +10 -0
  8. package/factories/client-file-readiness/agents/writer/agent.md +11 -0
  9. package/factories/client-file-readiness/factory.yaml +12 -0
  10. package/factories/client-file-readiness/flow.yaml +56 -0
  11. package/factories/competitor-teardown/README.md +3 -0
  12. package/factories/competitor-teardown/agents/analyst/agent.md +10 -0
  13. package/factories/competitor-teardown/agents/researcher/agent.md +11 -0
  14. package/factories/competitor-teardown/agents/reviewer/agent.md +10 -0
  15. package/factories/competitor-teardown/agents/writer/agent.md +11 -0
  16. package/factories/competitor-teardown/factory.yaml +11 -0
  17. package/factories/competitor-teardown/flow.yaml +75 -0
  18. package/factories/homepage-audit/README.md +3 -0
  19. package/factories/homepage-audit/agents/analyst/agent.md +10 -0
  20. package/factories/homepage-audit/agents/researcher/agent.md +11 -0
  21. package/factories/homepage-audit/agents/reviewer/agent.md +10 -0
  22. package/factories/homepage-audit/agents/writer/agent.md +11 -0
  23. package/factories/homepage-audit/factory.yaml +11 -0
  24. package/factories/homepage-audit/flow.yaml +77 -0
  25. package/factories/inbox-triage/README.md +3 -0
  26. package/factories/inbox-triage/agents/analyst/agent.md +10 -0
  27. package/factories/inbox-triage/agents/reviewer/agent.md +10 -0
  28. package/factories/inbox-triage/agents/writer/agent.md +11 -0
  29. package/factories/inbox-triage/factory.yaml +11 -0
  30. package/factories/inbox-triage/flow.yaml +57 -0
  31. package/factories/index.json +587 -0
  32. package/factories/launch-kit/README.md +3 -0
  33. package/factories/launch-kit/agents/reviewer/agent.md +10 -0
  34. package/factories/launch-kit/agents/strategist/agent.md +10 -0
  35. package/factories/launch-kit/agents/writer/agent.md +11 -0
  36. package/factories/launch-kit/factory.yaml +12 -0
  37. package/factories/launch-kit/flow.yaml +75 -0
  38. package/factories/meeting-to-actions/CHANGELOG.md +7 -0
  39. package/factories/meeting-to-actions/README.md +15 -0
  40. package/factories/meeting-to-actions/agents/analyst/agent.md +10 -0
  41. package/factories/meeting-to-actions/agents/reviewer/agent.md +10 -0
  42. package/factories/meeting-to-actions/agents/writer/agent.md +11 -0
  43. package/factories/meeting-to-actions/factory.yaml +11 -0
  44. package/factories/meeting-to-actions/flow.yaml +53 -0
  45. package/factories/meeting-to-actions/mindburn.requirements.yaml +8 -0
  46. package/factories/meeting-to-actions/mindburn.tests.yaml +16 -0
  47. package/factories/newsletter-note/README.md +11 -0
  48. package/factories/newsletter-note/agents/reviewer/agent.md +10 -0
  49. package/factories/newsletter-note/agents/writer/agent.md +11 -0
  50. package/factories/newsletter-note/factory.yaml +12 -0
  51. package/factories/newsletter-note/flow.yaml +45 -0
  52. package/factories/newsletter-note/mindburn.tests.yaml +80 -0
  53. package/factories/outreach-pack/README.md +3 -0
  54. package/factories/outreach-pack/agents/reviewer/agent.md +5 -0
  55. package/factories/outreach-pack/agents/writer/agent.md +5 -0
  56. package/factories/outreach-pack/factory.yaml +9 -0
  57. package/factories/outreach-pack/flow.yaml +42 -0
  58. package/factories/prospect-brief/README.md +3 -0
  59. package/factories/prospect-brief/agents/researcher/agent.md +11 -0
  60. package/factories/prospect-brief/agents/reviewer/agent.md +10 -0
  61. package/factories/prospect-brief/agents/strategist/agent.md +10 -0
  62. package/factories/prospect-brief/agents/writer/agent.md +11 -0
  63. package/factories/prospect-brief/factory.yaml +11 -0
  64. package/factories/prospect-brief/flow.yaml +79 -0
  65. package/factories/release-desk/README.md +13 -0
  66. package/factories/release-desk/agents/editor/agent.md +10 -0
  67. package/factories/release-desk/agents/reviewer/agent.md +10 -0
  68. package/factories/release-desk/factory.yaml +13 -0
  69. package/factories/release-desk/flow.yaml +67 -0
  70. package/factories/release-desk/mindburn.tests.yaml +163 -0
  71. package/factories/short-video-cut/README.md +11 -0
  72. package/factories/short-video-cut/agents/reviewer/agent.md +10 -0
  73. package/factories/short-video-cut/agents/writer/agent.md +11 -0
  74. package/factories/short-video-cut/factory.yaml +13 -0
  75. package/factories/short-video-cut/flow.yaml +46 -0
  76. package/factories/short-video-cut/mindburn.tests.yaml +80 -0
  77. package/factories/video-facts/README.md +11 -0
  78. package/factories/video-facts/agents/analyst/agent.md +10 -0
  79. package/factories/video-facts/agents/reviewer/agent.md +10 -0
  80. package/factories/video-facts/factory.yaml +13 -0
  81. package/factories/video-facts/flow.yaml +39 -0
  82. package/factories/video-facts/mindburn.tests.yaml +34 -0
  83. package/factories/video-to-posts/README.md +35 -0
  84. package/factories/video-to-posts/agents/analyst/agent.md +10 -0
  85. package/factories/video-to-posts/agents/reviewer/agent.md +10 -0
  86. package/factories/video-to-posts/agents/writer/agent.md +11 -0
  87. package/factories/video-to-posts/factory.yaml +12 -0
  88. package/factories/video-to-posts/flow.yaml +62 -0
  89. package/factories/video-to-posts/mindburn.tests.yaml +34 -0
  90. package/factories/week-of-posts/README.md +11 -0
  91. package/factories/week-of-posts/agents/reviewer/agent.md +10 -0
  92. package/factories/week-of-posts/agents/writer/agent.md +11 -0
  93. package/factories/week-of-posts/factory.yaml +12 -0
  94. package/factories/week-of-posts/flow.yaml +46 -0
  95. package/factories/week-of-posts/mindburn.tests.yaml +80 -0
  96. package/package.json +92 -4
  97. package/packages/cli/bin/factoryhub.mjs +8 -0
  98. package/packages/cli/package.json +29 -0
  99. package/packages/cli/src/args.mjs +47 -0
  100. package/packages/cli/src/commands/export.mjs +54 -0
  101. package/packages/cli/src/commands/get.mjs +37 -0
  102. package/packages/cli/src/commands/inspect.mjs +65 -0
  103. package/packages/cli/src/commands/list.mjs +24 -0
  104. package/packages/cli/src/commands/login.mjs +161 -0
  105. package/packages/cli/src/commands/logout.mjs +43 -0
  106. package/packages/cli/src/commands/mcp.mjs +25 -0
  107. package/packages/cli/src/commands/new.mjs +147 -0
  108. package/packages/cli/src/commands/pack.mjs +96 -0
  109. package/packages/cli/src/commands/publish.mjs +62 -0
  110. package/packages/cli/src/commands/pull.mjs +59 -0
  111. package/packages/cli/src/commands/push.mjs +115 -0
  112. package/packages/cli/src/commands/resume.mjs +66 -0
  113. package/packages/cli/src/commands/run.mjs +352 -0
  114. package/packages/cli/src/commands/runs.mjs +52 -0
  115. package/packages/cli/src/commands/search.mjs +30 -0
  116. package/packages/cli/src/commands/validate.mjs +79 -0
  117. package/packages/cli/src/commands/whoami.mjs +34 -0
  118. package/packages/cli/src/hosted.mjs +159 -0
  119. package/packages/cli/src/main.mjs +134 -0
  120. package/packages/cli/src/tool-sources.mjs +272 -0
  121. package/packages/cli/src/util.mjs +58 -0
  122. package/packages/engine/lib/catalog.mjs +50 -0
  123. package/packages/engine/lib/credentials.mjs +121 -0
  124. package/packages/engine/lib/hosted.mjs +119 -0
  125. package/packages/engine/lib/hub.mjs +423 -0
  126. package/packages/engine/lib/nango.mjs +157 -0
  127. package/packages/engine/lib/node.mjs +242 -0
  128. package/packages/engine/lib/providers.mjs +57 -0
  129. package/packages/engine/lib/run.mjs +192 -0
  130. package/packages/engine/lib/skill.mjs +229 -0
  131. package/packages/engine/lib/text.mjs +5 -0
  132. package/packages/engine/package.json +45 -0
  133. package/packages/engine/src/author-tests.mjs +78 -0
  134. package/packages/engine/src/compose.mjs +150 -0
  135. package/packages/engine/src/cost.mjs +41 -0
  136. package/packages/engine/src/diagnostics.mjs +21 -0
  137. package/packages/engine/src/factory-engine.mjs +2109 -0
  138. package/packages/engine/src/flow-sources.mjs +135 -0
  139. package/packages/engine/src/index.mjs +9 -0
  140. package/packages/engine/src/markdown.mjs +97 -0
  141. package/packages/engine/src/mcp-client.mjs +429 -0
  142. package/packages/engine/src/package.mjs +116 -0
  143. package/packages/engine/src/run.mjs +308 -0
  144. package/packages/engine/src/tool-sources.mjs +566 -0
  145. package/packages/mcp/bin/factoryhub-mcp.mjs +6 -0
  146. package/packages/mcp/package.json +36 -0
  147. package/packages/mcp/src/server.mjs +310 -0
  148. package/packages/sdk/package.json +28 -0
  149. package/packages/sdk/src/index.d.ts +163 -0
  150. package/packages/sdk/src/index.mjs +266 -0
  151. package/spec/README.md +42 -0
  152. package/spec/factory-format.md +866 -0
  153. package/spec/schema/factory.schema.json +43 -0
  154. package/spec/schema/factory.yaml.json +815 -0
  155. package/spec/schema/flow.schema.json +191 -0
  156. package/spec/skill-export.md +129 -0
@@ -0,0 +1,866 @@
1
+ # The factory format, v1alpha1
2
+
3
+ Status: alpha. This document describes the format as the reference engine in
4
+ [`packages/engine`](../packages/engine) reads and runs it at this commit,
5
+ except the pack v0 additions that
6
+ [section 12](#pack-v0-additions-not-yet-in-the-reference-engine) lists and
7
+ the single-file form of [section 13](#13-the-single-file-form): the format
8
+ defines them, and the reference engine does not implement them yet.
9
+ Changes go through the [RFC process](rfcs/README.md). The key words MUST,
10
+ MUST NOT, SHOULD and MAY are used as in RFC 2119.
11
+
12
+ A **factory** is a small organisation of AI agents written as plain text
13
+ files: who does what, in what order, what gets checked, and where a person
14
+ decides. People read the files, any editor changes them, and a runner
15
+ executes them.
16
+
17
+ Contents:
18
+
19
+ 1. [Files](#1-files)
20
+ 2. [YAML](#2-yaml)
21
+ 3. [factory.yaml](#3-factoryyaml)
22
+ 4. [Agents](#4-agents)
23
+ 5. [flow.yaml](#5-flowyaml)
24
+ 6. [Validity and runnability](#6-validity-and-runnability)
25
+ 7. [How a run works](#7-how-a-run-works)
26
+ 8. [Receipts](#8-receipts)
27
+ 9. [Identity and the transfer bundle](#9-identity-and-the-transfer-bundle)
28
+ 10. [Companion files](#10-companion-files)
29
+ 11. [What the format leaves out](#11-what-the-format-leaves-out)
30
+ 12. [JSON Schemas and conformance](#12-json-schemas-and-conformance)
31
+ 13. [The single-file form](#13-the-single-file-form)
32
+
33
+ ## 1. Files
34
+
35
+ ```text
36
+ factory.yaml name, description, default harness
37
+ flow.yaml inputs, steps, who does each, what each needs
38
+ agents/<name>/agent.md one file per agent: its role and standing instructions
39
+ ```
40
+
41
+ These three are the core. A factory MAY carry companion files. The same files
42
+ can also be written as one YAML file ([section 13](#13-the-single-file-form)). Only paths of
43
+ these forms are part of a factory; a runner MUST ignore every other path:
44
+
45
+ | Path | What it is |
46
+ |---|---|
47
+ | `factory.yaml`, `flow.yaml` | the core |
48
+ | `agents/<name>/agent.md` | an agent |
49
+ | `README`, `LICENSE`, `LICENCE`, `NOTICE`, `CHANGELOG` (optionally `.md` or `.txt`) | documentation |
50
+ | `mindburn.tests.yaml`, `mindburn.requirements.yaml` | companions, see [section 10](#10-companion-files) |
51
+ | `mindburn.package.yaml`, `mindburn.company.yaml`, `mindburn.lock.yaml`, `layout.json` | preserved companions; the reference runner does not read them |
52
+ | `automations/<name>/automation.md`, `scorers/<name>/scorer.md` | preserved definitions |
53
+ | `runners/<name>.yaml`, `routers/<name>.yaml`, `webhooks/<name>.yaml` | preserved definitions |
54
+ | `benchmarks/<name>/suite.yaml`, `benchmarks/<name>/tasks/<name>.yaml` | preserved definitions |
55
+ | `skills/<name>.yaml`, `skills/<name>/…/*.md`, and the same under `agents/<name>/` | skills |
56
+ | `self-improvement/agent.md` | preserved definition |
57
+ | `profiles/`, `flows/`, `schemas/`, `prompts/`, `assets/`, `examples/`, `checks/`, `fixtures/`, `capabilities/`, `policies/`, `adapters/`, `ui/` | data files ending `.yaml`, `.yml`, `.json`, `.md`, `.txt`, `.csv` or `.svg`, up to seven folders deep |
58
+
59
+ `<name>` is a lowercase letter or digit followed by up to 40 lowercase
60
+ letters, digits, `_` or `-`. A path MUST NOT be absolute, contain `.` or `..`
61
+ segments, backslashes or control characters, and MUST NOT be a symbolic
62
+ link. The exact expression is `ALLOWED_PATH` in
63
+ [`factory-engine.mjs`](../packages/engine/src/factory-engine.mjs).
64
+
65
+ Admitting a file grants it nothing. Preserved definitions and skills travel
66
+ with the factory; the reference runner does not execute them, and an active
67
+ agent's skill makes the factory not runnable here ([section 6](#6-validity-and-runnability)).
68
+
69
+ Text files are UTF-8. Line endings are normalized to `\n`.
70
+
71
+ ## 2. YAML
72
+
73
+ Factory files use a subset of YAML 1.2:
74
+
75
+ - One document per file. A leading `---` is allowed; a second document is an error.
76
+ - Block mappings, block lists, inline lists `[a, b]` and inline maps `{a: 1}`.
77
+ - Plain, `"double"` and `'single'` quoted scalars. `true`, `false`, `null`,
78
+ `~` and numbers such as `3` or `1.5` are read as those types.
79
+ - Block text under `|` (kept as written) and `>` (folded), each optionally
80
+ with `-` (no final line break) or `+`.
81
+ - Comments starting with `#` at the start of a line or after whitespace.
82
+ - A tab counts as two spaces of indentation.
83
+
84
+ Duplicate keys, anchors (`&`), aliases (`*`) and tags (`!`) are errors.
85
+
86
+ Quote a text value that contains `: ` or starts with a character YAML treats
87
+ specially. A list item such as `- Owner: named` is read as a map, not as
88
+ text. The engine reads `- Every action: has an owner` (a space before the
89
+ colon) as text, while standard YAML parsers read it as a map: quote it.
90
+
91
+ ## 3. factory.yaml
92
+
93
+ The factory's name, purpose and default model recommendation. It follows the
94
+ published factory schema at `schemaVersion: v1alpha1`.
95
+
96
+ ```yaml
97
+ schemaVersion: v1alpha1
98
+ name: launch-kit
99
+ description: |
100
+ Turns a product description into a launch kit with positioning, a landing
101
+ page draft, a launch email and posts. Use when you have something to launch.
102
+ repositories: []
103
+ agentDefaults:
104
+ harness:
105
+ type: claude
106
+ model: sonnet
107
+ ```
108
+
109
+ | Field | Required | Meaning |
110
+ |---|---|---|
111
+ | `schemaVersion` | yes | `v1alpha1` |
112
+ | `name` | yes | the factory's id: lowercase letters, digits and single hyphens, at most 64 characters, not starting or ending with a hyphen |
113
+ | `description` | yes | what the factory produces and when to use it. Single line breaks are read as spaces; a blank line starts a new paragraph |
114
+ | `repositories` | no | repositories a runtime must check out. Non-empty makes the factory not runnable here |
115
+ | `agentDefaults.harness.type`, `agentDefaults.harness.model` | no | the author's recommended harness and model. A recommendation, not a requirement |
116
+
117
+ Other fields are kept and have no effect, except the **execution
118
+ requirements** below. When present with a non-empty value, at the top level
119
+ or under `agentDefaults`, each one makes the factory valid but not runnable
120
+ by the reference runner, because the runner cannot apply it:
121
+
122
+ `tools`, `mcp`, `mcpServers`, `mcp_servers`, `connectors`, `plugins`,
123
+ `skills`, `secrets`, `networkPolicy`, `extends`, `params`, `runner`,
124
+ `environmentId`, `workerHost`, `credentialStrategy`, `required_repos`,
125
+ `spawnableBy`, `repositories`, `cloudProviders`, `providers`,
126
+ `integrations`, and `harness.auth`.
127
+
128
+ `networkPolicy` and `spawnableBy` count even when empty: an empty network
129
+ policy or spawning allowlist is still a restriction. The same fields in the
130
+ frontmatter of an agent that a step uses count too.
131
+
132
+ ## 4. Agents
133
+
134
+ `agents/<name>/agent.md` holds one agent. The frontmatter says what the agent
135
+ is for; the body is its role, in prose. A role is not a task: the same agent
136
+ MAY do several steps, and each step's task is in `flow.yaml`.
137
+
138
+ ```markdown
139
+ ---
140
+ description: Chooses the angle: what to say, to whom, and why it should work.
141
+ agentType: CUSTOM
142
+ ---
143
+
144
+ You are the strategist. From the facts in hand you choose the angle...
145
+ ```
146
+
147
+ | Field | Meaning |
148
+ |---|---|
149
+ | `description` | one line on what the agent is responsible for |
150
+ | `agentType` | `CUSTOM` (default), `REVIEW` for an agent that only checks, `FOREMAN` for the coordinator. Read case-insensitively |
151
+
152
+ The frontmatter, when present, MUST be closed by a second `---` line and MUST
153
+ be valid YAML in the subset above. A factory has at most 40 agents.
154
+
155
+ A step names its agent by the folder name. Steps refer to agents in
156
+ lowercase letters, digits and hyphens, so an agent folder that steps use
157
+ SHOULD be named that way (at most 41 characters).
158
+
159
+ ### The foreman
160
+
161
+ `agents/foreman/agent.md` explains the whole workflow in prose, for a harness
162
+ that has no flow runner. When a factory has no foreman, the engine writes one
163
+ from the flow (`foremanText`). A generated foreman is recognised by its
164
+ `description: Coordinates the <name> factory from its flow.` line together
165
+ with the sentence `The exact, executable version of these steps is
166
+ flow.yaml.`; the engine rewrites it when the flow changes. A foreman an author
167
+ wrote is kept byte for byte, with a warning that it may no longer match the
168
+ flow.
169
+
170
+ Following the foreman's prose does not reproduce a runner's enforced checks,
171
+ approvals or receipts.
172
+
173
+ ## 5. flow.yaml
174
+
175
+ The executable workflow. It states dependencies, checks and approval points
176
+ explicitly; a diagram of the factory is derived from it.
177
+
178
+ ```yaml
179
+ flow: mindburn.flow/v1
180
+ title: Launch kit
181
+ version: "1.0.0"
182
+ license: MIT
183
+ tags: [marketing, launch]
184
+ time: about 4 minutes
185
+ inputs:
186
+ product:
187
+ type: longtext
188
+ help: What you are launching, what it does and the price.
189
+ site:
190
+ type: url
191
+ optional: true
192
+ help: Your current website, to match the voice.
193
+ steps:
194
+ positioning:
195
+ title: Find the positioning
196
+ agent: strategist
197
+ kind: work
198
+ tools: [web_fetch]
199
+ task: |
200
+ Write the positioning: the audience, the promise in one sentence...
201
+ approve_positioning:
202
+ title: Agree the positioning
203
+ kind: approve
204
+ needs: [positioning]
205
+ shows: positioning
206
+ task: Everything else is written from this. Approve it or correct it.
207
+ landing_page:
208
+ title: Write the landing page
209
+ agent: writer
210
+ needs: [approve_positioning]
211
+ task: ...
212
+ messages:
213
+ title: Write the emails and posts
214
+ agent: writer
215
+ needs: [approve_positioning]
216
+ task: ...
217
+ kit:
218
+ title: Package the kit
219
+ agent: writer
220
+ kind: deliver
221
+ needs: [landing_page, messages]
222
+ task: ...
223
+ check_kit:
224
+ title: Check the final kit
225
+ agent: reviewer
226
+ kind: check
227
+ needs: [kit]
228
+ checks: kit
229
+ task: Every factual claim in the kit appears in the inputs or the approved positioning.
230
+ done:
231
+ - No claim appears that the inputs do not support.
232
+ ```
233
+
234
+ ### 5.1 Top-level fields
235
+
236
+ | Field | Meaning |
237
+ |---|---|
238
+ | `flow` | `mindburn.flow/v1`. Another value is read with a warning |
239
+ | `requires` | execution features the flow depends on: `scoped-context`, `multiple-outputs`, `blocking-checks` ([5.3](#blocking-checks)). A runner MUST refuse a flow that requires a feature it does not know |
240
+ | `title` | the human title. Default: the name, with hyphens as spaces |
241
+ | `author`, `license`, `time` | text: who wrote it, its license (an SPDX identifier is recommended), how long a run takes |
242
+ | `version` | the factory's version, as text. Quote it: `"1.0.0"`. Default `1.0.0` |
243
+ | `tags` | a list of lowercase words |
244
+ | `inputs` | what a person fills in before a run ([5.2](#52-inputs)) |
245
+ | `steps` | the work, in order ([5.3](#53-steps)). Required, at least one |
246
+ | `done` | checkable statements about the deliverable ([5.6](#56-done)) |
247
+ | `outputs` | exact results to deliver ([5.8](#58-outputs)) |
248
+ | `composition` | provenance of a composed factory ([5.9](#59-composition)) |
249
+
250
+ Other top-level fields are kept and have no effect.
251
+
252
+ ### 5.2 Inputs
253
+
254
+ A map from input name to its definition. At most eight.
255
+
256
+ | Type | Holds | Accepts up to |
257
+ |---|---|---|
258
+ | `text` (default) | a short answer | 2,000 characters |
259
+ | `longtext` | pasted material | 40,000 characters |
260
+ | `url` | a website | 2,000 characters |
261
+
262
+ | Field | Meaning |
263
+ |---|---|
264
+ | `type` | `text`, `longtext` or `url` |
265
+ | `label` | the label shown for it. Default: the name, with underscores as spaces |
266
+ | `help` | what to put there, with an example |
267
+ | `optional: true` | a run can go without it (`required: false` means the same) |
268
+ | `visibility` | `private` (default) or `public`, for [scoped context](#57-scoped-context) |
269
+
270
+ - Names are normalized: lowercased, every run of other characters becomes `_`,
271
+ at most 64 characters. Write them normalized, such as `launch_offer`. Two
272
+ names that normalize to the same name are an error.
273
+ - All inputs together accept up to 80,000 characters. Lengths are counted in
274
+ UTF-16 code units.
275
+ - Text is preserved in full. A `url` input is normalized: a bare domain gets
276
+ `https://`, and only http(s) addresses with a dot in the host are accepted.
277
+ - Unknown names, non-text values, missing required inputs and oversized
278
+ inputs are rejected before any model is called. Nothing is cut.
279
+ - `inputSchema(factory)` in the engine returns the inputs as a JSON Schema.
280
+
281
+ ### 5.3 Steps
282
+
283
+ A map from step name to step. At most 24. Step names are normalized like
284
+ input names; write them normalized, such as `check_kit`.
285
+
286
+ | Field | Meaning |
287
+ |---|---|
288
+ | `title` | the human title. Default: the name, with underscores as spaces |
289
+ | `kind` | `work` (default), `check`, `approve` or `deliver` |
290
+ | `agent` | the agent that does the step: `agents/<agent>/agent.md` MUST exist. Required except for `approve` |
291
+ | `task` | what to do, in plain language. Required for `work` and `deliver` |
292
+ | `needs` | the steps whose results this step uses: a list, or one name. Left out, a step needs the step written above it |
293
+ | `checks` | for a `check`: the work or deliver step it reviews |
294
+ | `shows` | for an `approve`: the work or deliver step it shows the person |
295
+ | `rounds` | how often a check or person may send the work back: 0 to 5. Default 1 for a check, 3 for an approval |
296
+ | `on_fail` | for a `check` only: `flag` (default) or `stop`, what happens when the work still fails after its redos ([blocking checks](#blocking-checks)) |
297
+ | `tools` | tools the step may use ([5.5](#55-tools)) |
298
+ | `context` | scoped context ([5.7](#57-scoped-context)) |
299
+ | `criteria` | a list of statements this step's result is held to, in place of `done` |
300
+
301
+ | Kind | What happens |
302
+ |---|---|
303
+ | `work` | The agent does one job and hands its result on. |
304
+ | `check` | A reviewer judges the result named in `checks` against the criteria in `task`. If it fails, that work goes back to be redone with the reasons, and everything built on it runs again. After the allowed redos the run continues and the receipt says the check failed (`flagged`); with `on_fail: stop` the work is held for the owner instead ([blocking checks](#blocking-checks)). A reviewer that returns malformed output gets one format-repair attempt; if that also fails, the result is `unreviewed`, never passed. |
305
+ | `approve` | The run stops and shows the person the result named in `shows`. They approve; say what to change, and that work is redone; or reject, which ends the run with no result. Nothing else counts as a decision, and no runner makes one for them. |
306
+ | `deliver` | The agent writes the final deliverable. |
307
+
308
+ When a `check` has no `checks`, or an `approve` has no `shows`, the subject
309
+ is the first step in its `needs` that is earlier work or deliver, otherwise
310
+ the last earlier work or deliver step. The subject MUST be work or deliver
311
+ that the step depends on, directly or through other steps.
312
+
313
+ #### Blocking checks
314
+
315
+ Requires `requires: [blocking-checks]`. A `check` that says `on_fail: stop`
316
+ does not let refused work through:
317
+
318
+ - When the work still fails after its redos (`flagged`), or the reviewer gives
319
+ no valid verdict (`unreviewed`), the run **holds** it for the owner
320
+ ([section 7](#7-how-a-run-works)). Nothing built on it runs and nothing is
321
+ delivered; steps that do not depend on it finish first. The owner releases
322
+ the work as it is (`release`) or discards it and ends the run (`discard`).
323
+ - A blocking check gates its subject: every step that needs the subject, other
324
+ than another check of it, waits until the check passes or the owner releases
325
+ the work, whether it needs the check or only the subject. A flow in which the
326
+ blocking check itself needs such a step is invalid, as it would wait for
327
+ itself.
328
+ - `on_fail` is allowed only on a `check`, with the value `stop` or `flag`.
329
+ Without it, or with `flag`, the check behaves as described above.
330
+ - A flow with an `on_fail: stop` check MUST declare
331
+ `requires: [blocking-checks]`, so a runner without blocking checks refuses
332
+ the flow ([5.1](#51-top-level-fields)) instead of delivering work its
333
+ checker refused.
334
+
335
+ An agent following the factory without a runner, such as an exported skill,
336
+ gets this text for the check in place of the "carry on" text, word for word:
337
+
338
+ - with `rounds` 1 or more: `If it fails, send it back to be redone <once|up to N times> with the reasons, and redo every step that used it. If it still fails, stop and ask the person; do not deliver. Nothing that uses "<subject title>" starts until this check passes or the person lets the work through.`
339
+ - with `rounds: 0`: `If it fails, do not redo it. Stop and ask the person; do not deliver. Nothing that uses "<subject title>" starts until this check passes or the person lets the work through.`
340
+
341
+ Fields that other harnesses use for tools and connections (`mcp`,
342
+ `mcpServers`, `mcp_servers`, `connectors`, `plugins`, `skills`) are read as
343
+ tools this step needs ([5.5](#55-tools)). Any other unknown field is kept, has
344
+ no effect, and produces a warning.
345
+
346
+ ### 5.4 Order, parallel work and joins
347
+
348
+ Every step whose `needs` are finished can start. Steps that become ready
349
+ together run at the same time: in the example, the landing page and the
350
+ messages are written in parallel once the positioning is approved. A step
351
+ that needs several steps waits for all of them. The steps MUST NOT depend on
352
+ each other in a circle.
353
+
354
+ The **deliverable** is the result of the last `deliver` step in the file, or
355
+ of the last `work` step when there is no `deliver` step, unless the flow
356
+ declares [outputs](#58-outputs).
357
+
358
+ ### 5.5 Tools
359
+
360
+ The reference runner has two tools: `web_search` finds pages and `web_fetch`
361
+ reads one. Leave `tools` out when a step needs neither. Agents read public
362
+ http(s) pages only: never local, private-network or literal-IP addresses, or
363
+ ports other than 80 and 443; each redirect is checked again. `web_search`
364
+ needs a provider with server-side search (Anthropic); elsewhere the step
365
+ runs without it and the receipt records that limitation.
366
+
367
+ A step MAY name a tool the runner does not have, such as one a harness
368
+ provides. The factory stays valid and readable, and the runner refuses to run
369
+ it: without the tool it would be a different factory.
370
+
371
+ ### 5.6 Done
372
+
373
+ A list of checkable statements about the deliverable. The agent of every
374
+ `deliver` step is told them, and a check on the final deliverable is held to
375
+ them. A receipt marks a final deliverable with no matching review as
376
+ `not_checked`.
377
+
378
+ ### 5.7 Scoped context
379
+
380
+ Requires `requires: [scoped-context]`. Without `context`, a step sees every
381
+ input and the results of every step it depends on. With it, only the named
382
+ bindings enter its prompt:
383
+
384
+ ```yaml
385
+ context:
386
+ inputs:
387
+ product: product_facts # alias: input name
388
+ artifacts:
389
+ research: market_brief # alias: step name
390
+ public: true
391
+ ```
392
+
393
+ - `context` has only `inputs`, `artifacts` and `public` (a boolean).
394
+ - Aliases are lowercase letters, digits and `_`, starting with a letter, at
395
+ most 64 characters, unique across `inputs` and `artifacts`. References are
396
+ normalized names.
397
+ - An input reference MUST name an input. An artifact reference MUST name
398
+ earlier work or deliver that the step depends on.
399
+ - Dependencies still control ordering and revision. A reviewer also receives
400
+ its exact subject.
401
+ - Inputs are private unless `visibility: public`. A step with `public: true`
402
+ MUST NOT receive private inputs or private evidence, including a
403
+ reviewer's feedback; privacy is propagated through every review and
404
+ revision route. This controls model context, not storage or sharing.
405
+
406
+ ### 5.8 Outputs
407
+
408
+ Requires `requires: [multiple-outputs]`. A list of 1 to 24 exact results:
409
+
410
+ ```yaml
411
+ outputs:
412
+ - step: market_brief
413
+ title: Market research
414
+ - step: launch_kit
415
+ title: Launch materials
416
+ ```
417
+
418
+ Each entry has only `step` (a work or deliver step, once each) and `title`
419
+ (1 to 200 characters). The deliverable joins the texts in this order, each
420
+ under its title, without a model rewrite. The receipt records each output's
421
+ hash and review status.
422
+
423
+ ### 5.9 Composition
424
+
425
+ A composed factory records where it came from:
426
+
427
+ ```yaml
428
+ composition:
429
+ compiler: mindburn.compose/v1
430
+ intent: The person's original request.
431
+ sources:
432
+ - { id: research, name: market-research, title: Market research, version: "1.0.0", sha256: <64 hex> }
433
+ unmetCapabilities: []
434
+ ```
435
+
436
+ All four fields are required and nothing else is allowed. Each source has
437
+ `id`, `name`, `version` and `sha256`, and MAY have `title`, the member
438
+ factory's title, at most 120 characters. `composeFactories` in
439
+ [`compose.mjs`](../packages/engine/src/compose.mjs) produces these factories
440
+ from members pinned by hash; the result is an ordinary factory and needs no
441
+ registry to run. A source hash establishes identity, not trust, and a
442
+ `composition` block is text anyone can write: a runner names the members of a
443
+ run in its receipt only for a composition it compiled itself
444
+ ([section 8](#8-receipts)).
445
+
446
+ Each member's steps run under the member's id (member `posts`, step `write`
447
+ runs as `posts_write`). A compiler:
448
+
449
+ - refuses member ids where one begins with another followed by `_`, so every
450
+ step belongs to exactly one member;
451
+ - keeps a member check's `on_fail`, and adds `blocking-checks` to `requires`
452
+ when any member check says `on_fail: stop`;
453
+ - MAY take `maxCalls`, a positive whole number, and then refuses a
454
+ composition whose worst-case run needs more model calls (`worstCaseCalls`).
455
+ It returns `worstCaseCalls` with the result. The worst case counts the
456
+ calls one run can make: a work or deliver step with tools may take every
457
+ model turn (8 in the reference runner), one without tools makes one call; a
458
+ check makes two, its verdict and one format repair; an approval makes none.
459
+ Each check or approval may send its subject back as often as its `rounds`
460
+ allow, and each time the subject, the sender and every step built on the
461
+ subject that does not wait for the sender run again.
462
+
463
+ A member MAY carry `rounds: { <step>: <n> }`, with the member's own step
464
+ names. It lowers the revision rounds of its own check or approve steps in the
465
+ composed flow, so a composition fits `maxCalls` without changing the member.
466
+ The compiler refuses something other than a map, a step that is not one of
467
+ the member's checks or approvals, and a fraction, a negative number or more
468
+ rounds than the step has. The member's pin is unchanged.
469
+
470
+ A member's `mindburn.tests.yaml` tests that member alone, so the compiler
471
+ leaves it out of the composed factory. The member's pin stays the bundle hash
472
+ of all its files, the tests file included. Any other file the compiler cannot
473
+ compile is refused.
474
+
475
+ ### 5.10 Limits
476
+
477
+ - At most 8 inputs, 24 steps and 40 agents.
478
+ - Inputs: see [5.2](#52-inputs).
479
+ - One YAML document per file; duplicate keys are rejected.
480
+
481
+ ## 6. Validity and runnability
482
+
483
+ A factory is **valid** when the engine reports no errors. Beyond the shape the
484
+ [JSON Schemas](#12-json-schemas-and-conformance) describe, validity requires:
485
+
486
+ 1. `factory.yaml` exists and parses; every YAML file and agent frontmatter parses.
487
+ 2. Input names and step names are non-empty after normalization and unique.
488
+ 3. Every `needs` entry names a step, and steps do not depend on each other in a circle.
489
+ 4. Every step other than `approve` names an agent, and `agents/<agent>/agent.md` exists.
490
+ 5. Every `check` and `approve` has earlier work or deliver to check or show,
491
+ and an explicit `checks` or `shows` names one it depends on.
492
+ 6. The flow has at least one `work` or `deliver` step.
493
+ 7. Context bindings and outputs refer to what [5.7](#57-scoped-context) and
494
+ [5.8](#58-outputs) allow, and public steps receive no private data.
495
+ 8. At most 40 agents.
496
+
497
+ A valid factory is **runnable** by the reference runner when it has a flow
498
+ with steps, every tool its steps ask for is `web_search` or `web_fetch`, and
499
+ it declares no execution requirement from [section 3](#3-factoryyaml), no
500
+ factory-level skill, and no skill for an agent a step uses. A valid factory that is not runnable can still
501
+ be read, shared and taken to a runtime that supports what it needs.
502
+
503
+ A factory with only `factory.yaml` and agents is valid. It has no steps to
504
+ run; an agent can follow its foreman.
505
+
506
+ `factoryhub validate` and `node run.mjs --validate` report exactly this.
507
+
508
+ ## 7. How a run works
509
+
510
+ 1. The inputs are checked ([5.2](#52-inputs)). A factory that asks for a tool
511
+ or requirement the runner lacks is not started.
512
+ 2. Every step whose `needs` are finished starts; up to four run at once.
513
+ 3. Each agent sees the accepted inputs, the results of the steps it depends
514
+ on (or only its [scoped context](#57-scoped-context)), its own role and its
515
+ task, with house rules: use only those and pages actually read, never
516
+ invent facts, say plainly when something could not be found. A reviewer
517
+ also sees the subject step's task, the full subject text and the earlier
518
+ evidence. A request over the runner's 160,000-character context bound stops
519
+ the run instead of cutting evidence.
520
+ 4. Checks send weak work back ([5.3](#53-steps)). Sending back marks that
521
+ step and everything built on it to run again.
522
+ 5. At an approval the run waits, for as long as it takes. A decision is
523
+ `approve`, `revise` (with a note) or `reject`. It names the SHA-256 of the
524
+ exact text the person was shown (`seen`) and the approval's id, which
525
+ differs for every occurrence, so a delayed decision cannot land on text that
526
+ changed since or on a later review of the same text. With no decision the
527
+ runner returns the run still waiting.
528
+ 6. A [blocking check](#blocking-checks) that holds work makes the run wait the
529
+ same way, once nothing else can run, with
530
+ `approval: { kind: "blocked", step, title, artifact, artifact_sha256, ask, issues, note, choices: ["release", "discard"], id, revisionsLeft: 0 }`.
531
+ The only answers are `release` and `discard`, with `seen` and the
532
+ approval's id as above; `approve`, `revise` and `reject` are refused at a
533
+ hold, and `release` and `discard` at an approval. `release` lets the run go
534
+ on and the receipt flags the release. `discard` ends the run as `stopped`
535
+ with nothing delivered. A release answers one attempt of its check: when the
536
+ work is redone and the check runs again, the new verdict stands. A runner
537
+ never delivers a run whose blocking check refused work the owner did not
538
+ release; such a run fails instead. An agent app acting for the owner is
539
+ shown the hold's `artifact_sha256` and `issues`, never the held text, and
540
+ cannot release or discard it.
541
+ 7. A provider answer that is truncated, incomplete, or asks for a tool the
542
+ step was not offered stops the run with a reason. Failed page reads, missing
543
+ search and partial pages are recorded as limitations when usable work
544
+ continues.
545
+ 8. The reference runner's budgets: 60 model calls and 20 page reads per run, 4
546
+ searches and 8 model turns per step, 14,000 characters of text per page,
547
+ read from at most 1,500,000 bytes of a text, HTML, XML or JSON page.
548
+ 9. A finished run ends with the deliverable and a [receipt](#8-receipts). A
549
+ run that was rejected at a decision has no deliverable and no receipt. A
550
+ run whose owner discarded held work has no deliverable and a receipt whose
551
+ `outcome` says so.
552
+
553
+ A repeated run follows the same declared workflow; model outputs can differ.
554
+
555
+ ## 8. Receipts
556
+
557
+ A completed run produces a receipt (`kind: factory-run-receipt`, `v: 2`):
558
+
559
+ | Field | Meaning |
560
+ |---|---|
561
+ | `run`, `issuer` | the run id; `self` for a local run |
562
+ | `factory` | name, version and the bundle hash ([section 9](#9-identity-and-the-transfer-bundle)) |
563
+ | `inputs_sha256` | hash of the canonical JSON of the accepted inputs |
564
+ | `runner` | mode, provider and model |
565
+ | `started`, `finished` | ISO 8601 times |
566
+ | `steps` | every step attempt: status, tools used and targets, verdicts, limitations, decisions with `seen_sha256`, `approval_id` and `decided_by`, a check's `on_fail`, `output_sha256`; for reviews, the target hash, reviewer provider and model, input and evidence hashes and the request hash |
567
+ | `flags` | what the person should know: failed checks, unreviewed results, limitations, released holds |
568
+ | `outputs` | with declared outputs: each output's hash and review |
569
+ | `members` | for a composition the runner compiled itself: one entry per member (below) |
570
+ | `outcome` | for a run whose owner discarded held work: `{ status: "blocked", by: "owner", step, target, decision: "discard", at, decided_by }` |
571
+ | `deliverable_review` | `passed`, `limited` (a passing review with missing evidence), `flagged`, `unreviewed` or `not_checked`, for the delivered bytes; `flagged` whenever a release of held work is in effect, whatever a later check says; `not_delivered`, with `sha256: null` and no checks, when the owner discarded held work |
572
+ | `deliverable_sha256`, `usage` | hash of the deliverable, `null` when nothing was delivered; model calls and tokens. Each entry of `usage.metering.calls` names the `step` it was made for |
573
+
574
+ **Decisions.** Every decision record (an approval, and the owner's answer to
575
+ a hold) carries `decided_by: { account, surface }`. `account` is a stable,
576
+ salted hash of the deciding account, never its id, or `null` when no account
577
+ stands behind the decision (a run key). `surface` is how the decision arrived:
578
+ `web`, `mcp`, `a2a`, `email` or `api`. It is a label taken from the request,
579
+ not proof of the channel; who had authority is `account`. No handle or name is
580
+ signed: a reader looks up who an account is while it exists.
581
+
582
+ **Holds.** The owner's answer to a [blocking check](#blocking-checks) is a
583
+ step of `kind: hold`: `{ status: released | discarded, decision, target, seen_sha256, approval_id, decided_by }`,
584
+ kept apart from the check record it answers, which keeps its `flagged` or
585
+ `unreviewed` status.
586
+
587
+ **Members.** A runner adds `members` only for a composition it compiled
588
+ itself, from the sources it hashed, and never from a bundle's own
589
+ `composition` block, which anyone can write. Each entry, in compile order:
590
+ `{ id, name, title, version, source_sha256, status, steps, send_backs, released, usage }`.
591
+ `title` is at most 120 characters; `steps` are the member's namespaced step
592
+ ids; `send_backs` counts its check records that read `sent_back`; `released`
593
+ is true when the owner released work one of its blocking checks refused and
594
+ that check has not run again since; `usage` has the shape of a run's `usage`,
595
+ holding the calls made for its steps. A receipt's `status` is `done`,
596
+ `blocked` (held work, discarded or left held when the run ended), `failed`,
597
+ `stopped` or `skipped`; a runner's live view MAY also show `pending`,
598
+ `running` and `waiting`. Receipts keep counters, not prices.
599
+
600
+ A discarded run's receipt verifies no result: check only its signature.
601
+
602
+ A runner MAY sign a receipt: `signature: { key_id, sig }`, an Ed25519
603
+ signature (base64url) over the canonical JSON of the receipt without its
604
+ `signature` field. `verifyReceipt(receipt, keys, deliverable)` checks the
605
+ signature against published keys and the deliverable against its hash. A
606
+ local receipt is unsigned and self-attested. No review or signature
607
+ guarantees factual accuracy; Ed25519 is not post-quantum.
608
+
609
+ ## 9. Identity and the transfer bundle
610
+
611
+ **Canonical JSON** sorts object keys at every level and has no whitespace.
612
+
613
+ A factory's **hash** is the SHA-256 of the canonical JSON of its files, as a
614
+ map from path to text with `\n` line endings (`bundleHash`). Its identity is
615
+ the hash of the **canonical bundle**: the source files plus the generated
616
+ foreman when the author wrote none (`withForeman`). An edit is a new version
617
+ with a new hash.
618
+
619
+ The **transfer bundle** (`mindburn.factory.bundle/v1`) carries a factory as
620
+ one JSON document:
621
+
622
+ ```json
623
+ {
624
+ "format": "mindburn.factory.bundle/v1",
625
+ "status": "existing-source",
626
+ "source": { "project": "launch-kit", "factory_path": "factory.yaml" },
627
+ "files": [
628
+ { "path": "factory.yaml", "content": "...", "sha256": "<64 hex>", "bytes": 312 }
629
+ ],
630
+ "warnings": [],
631
+ "review_required": true,
632
+ "meta": { "file_count": 7 }
633
+ }
634
+ ```
635
+
636
+ - `status` is `existing-source` or `inferred-draft` (a factory reconstructed
637
+ from a project that had no `factory.yaml`).
638
+ - When `sha256` or `bytes` is present, a reader MUST reject a file that does
639
+ not match it.
640
+ - At most 60 files and 400,000 UTF-8 bytes. Paths outside
641
+ [section 1](#1-files) are listed in `left_out` and not read; unsafe paths
642
+ are errors.
643
+
644
+ ## 10. Companion files
645
+
646
+ ### mindburn.tests.yaml
647
+
648
+ Declarative examples of a run and checks on its deliverable. No code,
649
+ regular expressions or model judge.
650
+
651
+ ```yaml
652
+ version: 1
653
+ cases:
654
+ keeps_owner:
655
+ name: Keeps the owner and action
656
+ inputs:
657
+ notes: Dana sends the invoice.
658
+ expect:
659
+ contains: [Dana, invoice]
660
+ excludes: [invented]
661
+ min_length: 15
662
+ max_length: 2000
663
+ ```
664
+
665
+ - 1 to 8 cases. Case names are a lowercase letter followed by up to 63
666
+ lowercase letters, digits, `_` or `-`. `name` is at most 100 characters.
667
+ - `inputs` MUST pass the factory's input checks.
668
+ - `contains` and `excludes`: 1 to 50 phrases of up to 500 characters,
669
+ compared ignoring case and differences in whitespace (NFKC). `min_length`
670
+ and `max_length`: integers from 0 to 100,000, counted in Unicode characters.
671
+ At least one check per case.
672
+ - Test inputs ship with the factory: use invented or public data.
673
+
674
+ `node run.mjs --test` runs every case with your provider and writes
675
+ `author-test-results.json`. Passing checks are a regression signal on these
676
+ examples, not a general effectiveness benchmark.
677
+
678
+ ### mindburn.requirements.yaml
679
+
680
+ The author's declarations about models and cost:
681
+
682
+ ```yaml
683
+ models:
684
+ recommended: claude-haiku-5-5
685
+ minimum: claude-haiku-5-5
686
+ expected_cost:
687
+ currency: USD
688
+ min: 0.008
689
+ max: 0.02
690
+ model: claude-haiku-5-5
691
+ basis: How the estimate was made.
692
+ ```
693
+
694
+ These are declarations, not verified compatibility or a spending cap.
695
+ `packageManifest` reports them with `provenance: author-declared`.
696
+
697
+ ## 11. What the format leaves out
698
+
699
+ - There are no variables, expressions or code.
700
+ - Loops exist only as "send this work back".
701
+ - Agents work with text and the public web. They do not send email, write to
702
+ your systems or act on your behalf: the deliverable is a document, a draft
703
+ or a plan that a person uses.
704
+
705
+ ## 12. JSON Schemas and conformance
706
+
707
+ [`schema/factory.schema.json`](schema/factory.schema.json) and
708
+ [`schema/flow.schema.json`](schema/flow.schema.json) (JSON Schema 2020-12)
709
+ describe the shape of `factory.yaml` and `flow.yaml` after YAML parsing.
710
+ [`test/schema.test.mjs`](test/schema.test.mjs) checks them against the
711
+ engine on the fixtures in [`fixtures/`](fixtures):
712
+
713
+ - `valid/`: the schemas and the engine both accept them. Every house factory
714
+ is also checked.
715
+ - `invalid/`: the schemas and the engine both reject them.
716
+ - `semantic/`: the schemas accept them and the engine rejects them, by a rule
717
+ of [section 6](#6-validity-and-runnability) that a per-file schema cannot
718
+ express, such as a missing agent file or a circle of steps.
719
+ - `unimplemented/`: the schemas accept them and the engine refuses them,
720
+ because they require an execution feature it does not implement yet
721
+ (`blocking-checks`). A runner MUST refuse such a flow
722
+ ([5.1](#51-top-level-fields)); the test checks that this is the only reason.
723
+ - `lenient/`: the engine accepts them and the schemas reject them. The engine
724
+ converts or ignores values the format does not define. The fixtures cover:
725
+ an uppercase `kind`; an unknown input `type` (read as `text`); a number
726
+ where text belongs (a numeric `name` or `version`); a comma-separated
727
+ `tags` string; any non-empty `schemaVersion`, and any `flow` value (with a
728
+ warning); `rounds` outside 0 to 5 (clamped); an uppercase `agent` (read in
729
+ lowercase); `checks` on a `work` step (ignored); a `done` item that YAML
730
+ reads as a map (joined into text); an input given as plain text (read as
731
+ its help); step names that are not written normalized; `on_fail: stop`
732
+ without `requires: [blocking-checks]` (the engine at this commit ignores
733
+ `on_fail` with a warning; it will reject this once it implements blocking
734
+ checks). The engine also
735
+ accepts, without fixtures here, non-boolean `required` and `optional`,
736
+ non-integer `rounds` (the default is used), and scalars where
737
+ `repositories`, `agentDefaults`, `author` or `tags` items belong. Authors
738
+ SHOULD NOT rely on any of these; a future version may reject them.
739
+
740
+ [`schema/factory.yaml.json`](schema/factory.yaml.json) (JSON Schema draft-07)
741
+ describes the single-file form of [section 13](#13-the-single-file-form); its
742
+ fixtures and test are listed there.
743
+
744
+ A conforming factory validates against both schemas and passes the rules of
745
+ [section 6](#6-validity-and-runnability). The engine is the reference: where
746
+ this document and the engine disagree, that is a bug in one of them, and an
747
+ issue is welcome.
748
+
749
+ ### Pack v0 additions not yet in the reference engine
750
+
751
+ The format defines these, and the engine and CLI at this commit do not
752
+ implement them yet:
753
+
754
+ - [blocking checks](#blocking-checks): `on_fail`, `requires: [blocking-checks]`,
755
+ the gate on the subject, holds and their answers (section 7, item 6), and the
756
+ export text. The engine refuses a flow that requires `blocking-checks`, as
757
+ 5.1 requires, and ignores `on_fail` elsewhere with a warning;
758
+ - in [5.9](#59-composition): recording `title`, the nested member-id refusal,
759
+ carrying `on_fail`, `maxCalls`, `worstCaseCalls`, a member's `rounds` and
760
+ leaving out a member's tests file;
761
+ - in [section 8](#8-receipts): `members`, `outcome`, `decided_by`, `on_fail`,
762
+ `kind: hold`, `deliverable_review.status: not_delivered`, the `flagged`
763
+ status for a release in effect, and `usage.metering.calls[].step`.
764
+
765
+ The schemas already describe the new fields: `on_fail` (only on a `check`,
766
+ `stop` or `flag`), `blocking-checks` in `requires` (required by any
767
+ `on_fail: stop` check), and `title` (at most 120 characters) in a composition
768
+ source.
769
+
770
+ [RFC 0020](rfcs/0020-pack-v0.md) is where these additions are discussed and
771
+ decided. It also proposes who paid for a run and for each call (`funding`,
772
+ `payer`), which this document does not define until the RFC settles them.
773
+
774
+ ## 13. The single-file form
775
+
776
+ Proposed in [RFC 0023](rfcs/0023-single-file-factory.md), a draft, which
777
+ gives the full rules. The reference engine and CLI at this commit do not read
778
+ this form yet: `factoryhub validate` and `factoryhub run` read factory folders
779
+ and bundle `.json` files, and `factoryhub push` refuses a single file.
780
+
781
+ A whole factory MAY be written as one YAML file, `factory.yaml`, with
782
+ `format: mindburn.factory.yaml/v1` on a line of its own. Each top-level
783
+ section is one file of the bundle, and its text is that file's exact bytes:
784
+
785
+ ```yaml
786
+ # yaml-language-server: $schema=https://raw.githubusercontent.com/Mindburn-Labs/factoryhub/main/spec/schema/factory.yaml.json
787
+ format: mindburn.factory.yaml/v1
788
+
789
+ factory:
790
+ schemaVersion: v1alpha1
791
+ name: one-step-summary
792
+ description: Writes a three-sentence summary of the text you give it.
793
+
794
+ flow:
795
+ flow: mindburn.flow/v1
796
+ inputs:
797
+ text:
798
+ type: longtext
799
+ help: The text to summarise.
800
+ steps:
801
+ summary:
802
+ agent: writer
803
+ task: Summarise the text in three sentences.
804
+
805
+ agents:
806
+ writer:
807
+ description: Writes plain summaries.
808
+ instructions: |
809
+ You write short, plain summaries. You add nothing the text does not say.
810
+ ```
811
+
812
+ | Section | Bundle file |
813
+ |---|---|
814
+ | `format` | none; required, `mindburn.factory.yaml/v1` |
815
+ | `factory`, `flow` | `factory.yaml`, `flow.yaml` |
816
+ | `agents` | `agents/<name>/agent.md`, one entry per agent: its settings, then `instructions: \|` |
817
+ | `tests`, `requirements`, `package` | `mindburn.tests.yaml`, `mindburn.requirements.yaml`, `mindburn.package.yaml` |
818
+ | `samples` | `examples/<path>`, one entry per file |
819
+ | `files` | every other file, by its path |
820
+
821
+ - **Sections are files.** The lines of a YAML section, less two spaces of
822
+ indent, are its file, plus one final line break; comments and formatting
823
+ inside a section are the file's own bytes. An agent entry is its
824
+ frontmatter settings, then its body under `instructions: |` (or `|-` for no
825
+ final line break). A file a block cannot carry byte for byte is one JSON
826
+ string, its exact text, on its key's line.
827
+ - **The coordinator.** A writer leaves out `agents/foreman/agent.md` while it
828
+ is exactly what the engine writes from the flow (`withForeman`), and a
829
+ reader writes it again. An authored or stale foreman is kept as written;
830
+ `foreman: ~` says the bundle has none.
831
+ - **Presentation.** Comments and blank lines between sections, section order,
832
+ comments on a section's own line and top-level `x-` keys are no file's
833
+ content. They never change the bundle or its hash.
834
+ - **Unknown keys.** Any other unknown top-level key is an error at its line,
835
+ never dropped. Inside a section every key is kept byte for byte, whether a
836
+ runner reads it or not; `requires` gates features exactly as in
837
+ [5.1](#51-top-level-fields).
838
+ - **Identity.** A single file is a view of its bundle. Its hash is the
839
+ [bundle hash](#9-identity-and-the-transfer-bundle) of the bundle it expands
840
+ to; no byte outside the files counts. Writing a bundle as one file and
841
+ reading it back MUST give the same bundle.
842
+ - **Size.** A file in `samples` or `files` over 32 KiB (32,768 UTF-8 bytes)
843
+ MAY be written as a reference, `{ sha256: "<64 hex>", bytes: <n> }`: the
844
+ same file of the version the text came from. A reader resolves it only
845
+ against that version, and an editor shows it read-only. The bundle the file
846
+ expands to keeps the limits of [section 9](#9-identity-and-the-transfer-bundle).
847
+ - **Versions.** `format` versions the layout; `schemaVersion` and `flow` keep
848
+ versioning their files. A reader MUST refuse a `format` it does not know.
849
+ A file with a line `format: mindburn.factory.yaml/v1` at column 1 is a
850
+ single file, not a bundle's `factory.yaml`.
851
+
852
+ [`schema/factory.yaml.json`](schema/factory.yaml.json) (draft-07) gives
853
+ editors completion, hover text and errors. It is open wherever a file is and
854
+ does not decide validity, which the reader and
855
+ [section 6](#6-validity-and-runnability) do. Its `$id`,
856
+ `https://factory.mindburn.org/schemas/factory.yaml.json`, is its stable
857
+ address on the factoryhub site, which generates the same document. That site
858
+ is in private preview, so point editors at this repository's copy, as the
859
+ example's first line does ([editor setup](../docs/editor-setup.md)).
860
+
861
+ [`fixtures/single-file/`](fixtures/single-file) holds `valid/` (the schema
862
+ accepts them and each is a valid factory; two are house factories, equal to
863
+ their folders byte for byte), `invalid/` (the schema rejects each at the place
864
+ it names) and `reader/` (the schema accepts them, and the rules above reject
865
+ them). [`test/single-file.test.mjs`](test/single-file.test.mjs) checks them,
866
+ and checks the reference engine against them once it reads this form.