factoryhub 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (99) hide show
  1. package/LICENSE +202 -0
  2. package/NOTICE +16 -0
  3. package/README.md +189 -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 +356 -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/outreach-pack/README.md +3 -0
  48. package/factories/outreach-pack/agents/reviewer/agent.md +5 -0
  49. package/factories/outreach-pack/agents/writer/agent.md +5 -0
  50. package/factories/outreach-pack/factory.yaml +9 -0
  51. package/factories/outreach-pack/flow.yaml +42 -0
  52. package/factories/prospect-brief/README.md +3 -0
  53. package/factories/prospect-brief/agents/researcher/agent.md +11 -0
  54. package/factories/prospect-brief/agents/reviewer/agent.md +10 -0
  55. package/factories/prospect-brief/agents/strategist/agent.md +10 -0
  56. package/factories/prospect-brief/agents/writer/agent.md +11 -0
  57. package/factories/prospect-brief/factory.yaml +11 -0
  58. package/factories/prospect-brief/flow.yaml +79 -0
  59. package/package.json +79 -4
  60. package/packages/cli/bin/factoryhub.mjs +8 -0
  61. package/packages/cli/package.json +29 -0
  62. package/packages/cli/src/args.mjs +47 -0
  63. package/packages/cli/src/commands/export.mjs +55 -0
  64. package/packages/cli/src/commands/get.mjs +38 -0
  65. package/packages/cli/src/commands/inspect.mjs +66 -0
  66. package/packages/cli/src/commands/list.mjs +29 -0
  67. package/packages/cli/src/commands/mcp.mjs +26 -0
  68. package/packages/cli/src/commands/new.mjs +148 -0
  69. package/packages/cli/src/commands/pack.mjs +97 -0
  70. package/packages/cli/src/commands/resume.mjs +67 -0
  71. package/packages/cli/src/commands/run.mjs +190 -0
  72. package/packages/cli/src/commands/search.mjs +31 -0
  73. package/packages/cli/src/commands/validate.mjs +81 -0
  74. package/packages/cli/src/main.mjs +68 -0
  75. package/packages/cli/src/util.mjs +21 -0
  76. package/packages/engine/lib/catalog.mjs +50 -0
  77. package/packages/engine/lib/hub.mjs +71 -0
  78. package/packages/engine/lib/node.mjs +114 -0
  79. package/packages/engine/lib/providers.mjs +52 -0
  80. package/packages/engine/lib/run.mjs +131 -0
  81. package/packages/engine/lib/skill.mjs +229 -0
  82. package/packages/engine/package.json +39 -0
  83. package/packages/engine/src/author-tests.mjs +78 -0
  84. package/packages/engine/src/compose.mjs +150 -0
  85. package/packages/engine/src/cost.mjs +41 -0
  86. package/packages/engine/src/diagnostics.mjs +21 -0
  87. package/packages/engine/src/factory-engine.mjs +1762 -0
  88. package/packages/engine/src/index.mjs +9 -0
  89. package/packages/engine/src/markdown.mjs +97 -0
  90. package/packages/engine/src/package.mjs +116 -0
  91. package/packages/engine/src/run.mjs +232 -0
  92. package/packages/mcp/bin/factoryhub-mcp.mjs +6 -0
  93. package/packages/mcp/package.json +36 -0
  94. package/packages/mcp/src/server.mjs +280 -0
  95. package/spec/README.md +36 -0
  96. package/spec/factory-format.md +621 -0
  97. package/spec/schema/factory.schema.json +43 -0
  98. package/spec/schema/flow.schema.json +169 -0
  99. package/spec/skill-export.md +126 -0
@@ -0,0 +1,621 @@
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
+ Changes go through the [RFC process](rfcs/README.md). The key words MUST,
6
+ MUST NOT, SHOULD and MAY are used as in RFC 2119.
7
+
8
+ A **factory** is a small organisation of AI agents written as plain text
9
+ files: who does what, in what order, what gets checked, and where a person
10
+ decides. People read the files, any editor changes them, and a runner
11
+ executes them.
12
+
13
+ Contents:
14
+
15
+ 1. [Files](#1-files)
16
+ 2. [YAML](#2-yaml)
17
+ 3. [factory.yaml](#3-factoryyaml)
18
+ 4. [Agents](#4-agents)
19
+ 5. [flow.yaml](#5-flowyaml)
20
+ 6. [Validity and runnability](#6-validity-and-runnability)
21
+ 7. [How a run works](#7-how-a-run-works)
22
+ 8. [Receipts](#8-receipts)
23
+ 9. [Identity and the transfer bundle](#9-identity-and-the-transfer-bundle)
24
+ 10. [Companion files](#10-companion-files)
25
+ 11. [What the format leaves out](#11-what-the-format-leaves-out)
26
+ 12. [JSON Schemas and conformance](#12-json-schemas-and-conformance)
27
+
28
+ ## 1. Files
29
+
30
+ ```text
31
+ factory.yaml name, description, default harness
32
+ flow.yaml inputs, steps, who does each, what each needs
33
+ agents/<name>/agent.md one file per agent: its role and standing instructions
34
+ ```
35
+
36
+ These three are the core. A factory MAY carry companion files. Only paths of
37
+ these forms are part of a factory; a runner MUST ignore every other path:
38
+
39
+ | Path | What it is |
40
+ |---|---|
41
+ | `factory.yaml`, `flow.yaml` | the core |
42
+ | `agents/<name>/agent.md` | an agent |
43
+ | `README`, `LICENSE`, `LICENCE`, `NOTICE`, `CHANGELOG` (optionally `.md` or `.txt`) | documentation |
44
+ | `mindburn.tests.yaml`, `mindburn.requirements.yaml` | companions, see [section 10](#10-companion-files) |
45
+ | `mindburn.package.yaml`, `mindburn.company.yaml`, `mindburn.lock.yaml`, `layout.json` | preserved companions; the reference runner does not read them |
46
+ | `automations/<name>/automation.md`, `scorers/<name>/scorer.md` | preserved definitions |
47
+ | `runners/<name>.yaml`, `routers/<name>.yaml`, `webhooks/<name>.yaml` | preserved definitions |
48
+ | `benchmarks/<name>/suite.yaml`, `benchmarks/<name>/tasks/<name>.yaml` | preserved definitions |
49
+ | `skills/<name>.yaml`, `skills/<name>/…/*.md`, and the same under `agents/<name>/` | skills |
50
+ | `self-improvement/agent.md` | preserved definition |
51
+ | `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 |
52
+
53
+ `<name>` is a lowercase letter or digit followed by up to 40 lowercase
54
+ letters, digits, `_` or `-`. A path MUST NOT be absolute, contain `.` or `..`
55
+ segments, backslashes or control characters, and MUST NOT be a symbolic
56
+ link. The exact expression is `ALLOWED_PATH` in
57
+ [`factory-engine.mjs`](../packages/engine/src/factory-engine.mjs).
58
+
59
+ Admitting a file grants it nothing. Preserved definitions and skills travel
60
+ with the factory; the reference runner does not execute them, and an active
61
+ agent's skill makes the factory not runnable here ([section 6](#6-validity-and-runnability)).
62
+
63
+ Text files are UTF-8. Line endings are normalized to `\n`.
64
+
65
+ ## 2. YAML
66
+
67
+ Factory files use a subset of YAML 1.2:
68
+
69
+ - One document per file. A leading `---` is allowed; a second document is an error.
70
+ - Block mappings, block lists, inline lists `[a, b]` and inline maps `{a: 1}`.
71
+ - Plain, `"double"` and `'single'` quoted scalars. `true`, `false`, `null`,
72
+ `~` and numbers such as `3` or `1.5` are read as those types.
73
+ - Block text under `|` (kept as written) and `>` (folded), each optionally
74
+ with `-` (no final line break) or `+`.
75
+ - Comments starting with `#` at the start of a line or after whitespace.
76
+ - A tab counts as two spaces of indentation.
77
+
78
+ Duplicate keys, anchors (`&`), aliases (`*`) and tags (`!`) are errors.
79
+
80
+ Quote a text value that contains `: ` or starts with a character YAML treats
81
+ specially. A list item such as `- Owner: named` is read as a map, not as
82
+ text. The engine reads `- Every action: has an owner` (a space before the
83
+ colon) as text, while standard YAML parsers read it as a map: quote it.
84
+
85
+ ## 3. factory.yaml
86
+
87
+ The factory's name, purpose and default model recommendation. It follows the
88
+ published factory schema at `schemaVersion: v1alpha1`.
89
+
90
+ ```yaml
91
+ schemaVersion: v1alpha1
92
+ name: launch-kit
93
+ description: |
94
+ Turns a product description into a launch kit with positioning, a landing
95
+ page draft, a launch email and posts. Use when you have something to launch.
96
+ repositories: []
97
+ agentDefaults:
98
+ harness:
99
+ type: claude
100
+ model: sonnet
101
+ ```
102
+
103
+ | Field | Required | Meaning |
104
+ |---|---|---|
105
+ | `schemaVersion` | yes | `v1alpha1` |
106
+ | `name` | yes | the factory's id: lowercase letters, digits and single hyphens, at most 64 characters, not starting or ending with a hyphen |
107
+ | `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 |
108
+ | `repositories` | no | repositories a runtime must check out. Non-empty makes the factory not runnable here |
109
+ | `agentDefaults.harness.type`, `agentDefaults.harness.model` | no | the author's recommended harness and model. A recommendation, not a requirement |
110
+
111
+ Other fields are kept and have no effect, except the **execution
112
+ requirements** below. When present with a non-empty value, at the top level
113
+ or under `agentDefaults`, each one makes the factory valid but not runnable
114
+ by the reference runner, because the runner cannot apply it:
115
+
116
+ `tools`, `mcp`, `mcpServers`, `mcp_servers`, `connectors`, `plugins`,
117
+ `skills`, `secrets`, `networkPolicy`, `extends`, `params`, `runner`,
118
+ `environmentId`, `workerHost`, `credentialStrategy`, `required_repos`,
119
+ `spawnableBy`, `repositories`, `cloudProviders`, `providers`,
120
+ `integrations`, and `harness.auth`.
121
+
122
+ `networkPolicy` and `spawnableBy` count even when empty: an empty network
123
+ policy or spawning allowlist is still a restriction. The same fields in the
124
+ frontmatter of an agent that a step uses count too.
125
+
126
+ ## 4. Agents
127
+
128
+ `agents/<name>/agent.md` holds one agent. The frontmatter says what the agent
129
+ is for; the body is its role, in prose. A role is not a task: the same agent
130
+ MAY do several steps, and each step's task is in `flow.yaml`.
131
+
132
+ ```markdown
133
+ ---
134
+ description: Chooses the angle: what to say, to whom, and why it should work.
135
+ agentType: CUSTOM
136
+ ---
137
+
138
+ You are the strategist. From the facts in hand you choose the angle...
139
+ ```
140
+
141
+ | Field | Meaning |
142
+ |---|---|
143
+ | `description` | one line on what the agent is responsible for |
144
+ | `agentType` | `CUSTOM` (default), `REVIEW` for an agent that only checks, `FOREMAN` for the coordinator. Read case-insensitively |
145
+
146
+ The frontmatter, when present, MUST be closed by a second `---` line and MUST
147
+ be valid YAML in the subset above. A factory has at most 40 agents.
148
+
149
+ A step names its agent by the folder name. Steps refer to agents in
150
+ lowercase letters, digits and hyphens, so an agent folder that steps use
151
+ SHOULD be named that way (at most 41 characters).
152
+
153
+ ### The foreman
154
+
155
+ `agents/foreman/agent.md` explains the whole workflow in prose, for a harness
156
+ that has no flow runner. When a factory has no foreman, the engine writes one
157
+ from the flow (`foremanText`). A generated foreman is recognised by its
158
+ `description: Coordinates the <name> factory from its flow.` line together
159
+ with the sentence `The exact, executable version of these steps is
160
+ flow.yaml.`; the engine rewrites it when the flow changes. A foreman an author
161
+ wrote is kept byte for byte, with a warning that it may no longer match the
162
+ flow.
163
+
164
+ Following the foreman's prose does not reproduce a runner's enforced checks,
165
+ approvals or receipts.
166
+
167
+ ## 5. flow.yaml
168
+
169
+ The executable workflow. It states dependencies, checks and approval points
170
+ explicitly; a diagram of the factory is derived from it.
171
+
172
+ ```yaml
173
+ flow: mindburn.flow/v1
174
+ title: Launch kit
175
+ version: "1.0.0"
176
+ license: MIT
177
+ tags: [marketing, launch]
178
+ time: about 4 minutes
179
+ inputs:
180
+ product:
181
+ type: longtext
182
+ help: What you are launching, what it does and the price.
183
+ site:
184
+ type: url
185
+ optional: true
186
+ help: Your current website, to match the voice.
187
+ steps:
188
+ positioning:
189
+ title: Find the positioning
190
+ agent: strategist
191
+ kind: work
192
+ tools: [web_fetch]
193
+ task: |
194
+ Write the positioning: the audience, the promise in one sentence...
195
+ approve_positioning:
196
+ title: Agree the positioning
197
+ kind: approve
198
+ needs: [positioning]
199
+ shows: positioning
200
+ task: Everything else is written from this. Approve it or correct it.
201
+ landing_page:
202
+ title: Write the landing page
203
+ agent: writer
204
+ needs: [approve_positioning]
205
+ task: ...
206
+ messages:
207
+ title: Write the emails and posts
208
+ agent: writer
209
+ needs: [approve_positioning]
210
+ task: ...
211
+ kit:
212
+ title: Package the kit
213
+ agent: writer
214
+ kind: deliver
215
+ needs: [landing_page, messages]
216
+ task: ...
217
+ check_kit:
218
+ title: Check the final kit
219
+ agent: reviewer
220
+ kind: check
221
+ needs: [kit]
222
+ checks: kit
223
+ task: Every factual claim in the kit appears in the inputs or the approved positioning.
224
+ done:
225
+ - No claim appears that the inputs do not support.
226
+ ```
227
+
228
+ ### 5.1 Top-level fields
229
+
230
+ | Field | Meaning |
231
+ |---|---|
232
+ | `flow` | `mindburn.flow/v1`. Another value is read with a warning |
233
+ | `requires` | execution features the flow depends on: `scoped-context`, `multiple-outputs`. A runner MUST refuse a flow that requires a feature it does not know |
234
+ | `title` | the human title. Default: the name, with hyphens as spaces |
235
+ | `author`, `license`, `time` | text: who wrote it, its license (an SPDX identifier is recommended), how long a run takes |
236
+ | `version` | the factory's version, as text. Quote it: `"1.0.0"`. Default `1.0.0` |
237
+ | `tags` | a list of lowercase words |
238
+ | `inputs` | what a person fills in before a run ([5.2](#52-inputs)) |
239
+ | `steps` | the work, in order ([5.3](#53-steps)). Required, at least one |
240
+ | `done` | checkable statements about the deliverable ([5.6](#56-done)) |
241
+ | `outputs` | exact results to deliver ([5.8](#58-outputs)) |
242
+ | `composition` | provenance of a composed factory ([5.9](#59-composition)) |
243
+
244
+ Other top-level fields are kept and have no effect.
245
+
246
+ ### 5.2 Inputs
247
+
248
+ A map from input name to its definition. At most eight.
249
+
250
+ | Type | Holds | Accepts up to |
251
+ |---|---|---|
252
+ | `text` (default) | a short answer | 2,000 characters |
253
+ | `longtext` | pasted material | 40,000 characters |
254
+ | `url` | a website | 2,000 characters |
255
+
256
+ | Field | Meaning |
257
+ |---|---|
258
+ | `type` | `text`, `longtext` or `url` |
259
+ | `label` | the label shown for it. Default: the name, with underscores as spaces |
260
+ | `help` | what to put there, with an example |
261
+ | `optional: true` | a run can go without it (`required: false` means the same) |
262
+ | `visibility` | `private` (default) or `public`, for [scoped context](#57-scoped-context) |
263
+
264
+ - Names are normalized: lowercased, every run of other characters becomes `_`,
265
+ at most 64 characters. Write them normalized, such as `launch_offer`. Two
266
+ names that normalize to the same name are an error.
267
+ - All inputs together accept up to 80,000 characters. Lengths are counted in
268
+ UTF-16 code units.
269
+ - Text is preserved in full. A `url` input is normalized: a bare domain gets
270
+ `https://`, and only http(s) addresses with a dot in the host are accepted.
271
+ - Unknown names, non-text values, missing required inputs and oversized
272
+ inputs are rejected before any model is called. Nothing is cut.
273
+ - `inputSchema(factory)` in the engine returns the inputs as a JSON Schema.
274
+
275
+ ### 5.3 Steps
276
+
277
+ A map from step name to step. At most 24. Step names are normalized like
278
+ input names; write them normalized, such as `check_kit`.
279
+
280
+ | Field | Meaning |
281
+ |---|---|
282
+ | `title` | the human title. Default: the name, with underscores as spaces |
283
+ | `kind` | `work` (default), `check`, `approve` or `deliver` |
284
+ | `agent` | the agent that does the step: `agents/<agent>/agent.md` MUST exist. Required except for `approve` |
285
+ | `task` | what to do, in plain language. Required for `work` and `deliver` |
286
+ | `needs` | the steps whose results this step uses: a list, or one name. Left out, a step needs the step written above it |
287
+ | `checks` | for a `check`: the work or deliver step it reviews |
288
+ | `shows` | for an `approve`: the work or deliver step it shows the person |
289
+ | `rounds` | how often a check or person may send the work back: 0 to 5. Default 1 for a check, 3 for an approval |
290
+ | `tools` | tools the step may use ([5.5](#55-tools)) |
291
+ | `context` | scoped context ([5.7](#57-scoped-context)) |
292
+ | `criteria` | a list of statements this step's result is held to, in place of `done` |
293
+
294
+ | Kind | What happens |
295
+ |---|---|
296
+ | `work` | The agent does one job and hands its result on. |
297
+ | `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`). A reviewer that returns malformed output gets one format-repair attempt; if that also fails, the result is `unreviewed`, never passed. |
298
+ | `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. |
299
+ | `deliver` | The agent writes the final deliverable. |
300
+
301
+ When a `check` has no `checks`, or an `approve` has no `shows`, the subject
302
+ is the first step in its `needs` that is earlier work or deliver, otherwise
303
+ the last earlier work or deliver step. The subject MUST be work or deliver
304
+ that the step depends on, directly or through other steps.
305
+
306
+ Fields that other harnesses use for tools and connections (`mcp`,
307
+ `mcpServers`, `mcp_servers`, `connectors`, `plugins`, `skills`) are read as
308
+ tools this step needs ([5.5](#55-tools)). Any other unknown field is kept, has
309
+ no effect, and produces a warning.
310
+
311
+ ### 5.4 Order, parallel work and joins
312
+
313
+ Every step whose `needs` are finished can start. Steps that become ready
314
+ together run at the same time: in the example, the landing page and the
315
+ messages are written in parallel once the positioning is approved. A step
316
+ that needs several steps waits for all of them. The steps MUST NOT depend on
317
+ each other in a circle.
318
+
319
+ The **deliverable** is the result of the last `deliver` step in the file, or
320
+ of the last `work` step when there is no `deliver` step, unless the flow
321
+ declares [outputs](#58-outputs).
322
+
323
+ ### 5.5 Tools
324
+
325
+ The reference runner has two tools: `web_search` finds pages and `web_fetch`
326
+ reads one. Leave `tools` out when a step needs neither. Agents read public
327
+ http(s) pages only: never local, private-network or literal-IP addresses, or
328
+ ports other than 80 and 443; each redirect is checked again. `web_search`
329
+ needs a provider with server-side search (Anthropic); elsewhere the step
330
+ runs without it and the receipt records that limitation.
331
+
332
+ A step MAY name a tool the runner does not have, such as one a harness
333
+ provides. The factory stays valid and readable, and the runner refuses to run
334
+ it: without the tool it would be a different factory.
335
+
336
+ ### 5.6 Done
337
+
338
+ A list of checkable statements about the deliverable. The agent of every
339
+ `deliver` step is told them, and a check on the final deliverable is held to
340
+ them. A receipt marks a final deliverable with no matching review as
341
+ `not_checked`.
342
+
343
+ ### 5.7 Scoped context
344
+
345
+ Requires `requires: [scoped-context]`. Without `context`, a step sees every
346
+ input and the results of every step it depends on. With it, only the named
347
+ bindings enter its prompt:
348
+
349
+ ```yaml
350
+ context:
351
+ inputs:
352
+ product: product_facts # alias: input name
353
+ artifacts:
354
+ research: market_brief # alias: step name
355
+ public: true
356
+ ```
357
+
358
+ - `context` has only `inputs`, `artifacts` and `public` (a boolean).
359
+ - Aliases are lowercase letters, digits and `_`, starting with a letter, at
360
+ most 64 characters, unique across `inputs` and `artifacts`. References are
361
+ normalized names.
362
+ - An input reference MUST name an input. An artifact reference MUST name
363
+ earlier work or deliver that the step depends on.
364
+ - Dependencies still control ordering and revision. A reviewer also receives
365
+ its exact subject.
366
+ - Inputs are private unless `visibility: public`. A step with `public: true`
367
+ MUST NOT receive private inputs or private evidence, including a
368
+ reviewer's feedback; privacy is propagated through every review and
369
+ revision route. This controls model context, not storage or sharing.
370
+
371
+ ### 5.8 Outputs
372
+
373
+ Requires `requires: [multiple-outputs]`. A list of 1 to 24 exact results:
374
+
375
+ ```yaml
376
+ outputs:
377
+ - step: market_brief
378
+ title: Market research
379
+ - step: launch_kit
380
+ title: Launch materials
381
+ ```
382
+
383
+ Each entry has only `step` (a work or deliver step, once each) and `title`
384
+ (1 to 200 characters). The deliverable joins the texts in this order, each
385
+ under its title, without a model rewrite. The receipt records each output's
386
+ hash and review status.
387
+
388
+ ### 5.9 Composition
389
+
390
+ A composed factory records where it came from:
391
+
392
+ ```yaml
393
+ composition:
394
+ compiler: mindburn.compose/v1
395
+ intent: The person's original request.
396
+ sources:
397
+ - { id: research, name: market-research, version: "1.0.0", sha256: <64 hex> }
398
+ unmetCapabilities: []
399
+ ```
400
+
401
+ All four fields are required and nothing else is allowed. `composeFactories`
402
+ in [`compose.mjs`](../packages/engine/src/compose.mjs) produces these
403
+ factories from members pinned by hash; the result is an ordinary factory and
404
+ needs no registry to run. A source hash establishes identity, not trust.
405
+
406
+ ### 5.10 Limits
407
+
408
+ - At most 8 inputs, 24 steps and 40 agents.
409
+ - Inputs: see [5.2](#52-inputs).
410
+ - One YAML document per file; duplicate keys are rejected.
411
+
412
+ ## 6. Validity and runnability
413
+
414
+ A factory is **valid** when the engine reports no errors. Beyond the shape the
415
+ [JSON Schemas](#12-json-schemas-and-conformance) describe, validity requires:
416
+
417
+ 1. `factory.yaml` exists and parses; every YAML file and agent frontmatter parses.
418
+ 2. Input names and step names are non-empty after normalization and unique.
419
+ 3. Every `needs` entry names a step, and steps do not depend on each other in a circle.
420
+ 4. Every step other than `approve` names an agent, and `agents/<agent>/agent.md` exists.
421
+ 5. Every `check` and `approve` has earlier work or deliver to check or show,
422
+ and an explicit `checks` or `shows` names one it depends on.
423
+ 6. The flow has at least one `work` or `deliver` step.
424
+ 7. Context bindings and outputs refer to what [5.7](#57-scoped-context) and
425
+ [5.8](#58-outputs) allow, and public steps receive no private data.
426
+ 8. At most 40 agents.
427
+
428
+ A valid factory is **runnable** by the reference runner when it has a flow
429
+ with steps, every tool its steps ask for is `web_search` or `web_fetch`, and
430
+ it declares no execution requirement from [section 3](#3-factoryyaml), no
431
+ factory-level skill, and no skill for an agent a step uses. A valid factory that is not runnable can still
432
+ be read, shared and taken to a runtime that supports what it needs.
433
+
434
+ A factory with only `factory.yaml` and agents is valid. It has no steps to
435
+ run; an agent can follow its foreman.
436
+
437
+ `factoryhub validate` and `node run.mjs --validate` report exactly this.
438
+
439
+ ## 7. How a run works
440
+
441
+ 1. The inputs are checked ([5.2](#52-inputs)). A factory that asks for a tool
442
+ or requirement the runner lacks is not started.
443
+ 2. Every step whose `needs` are finished starts; up to four run at once.
444
+ 3. Each agent sees the accepted inputs, the results of the steps it depends
445
+ on (or only its [scoped context](#57-scoped-context)), its own role and its
446
+ task, with house rules: use only those and pages actually read, never
447
+ invent facts, say plainly when something could not be found. A reviewer
448
+ also sees the subject step's task, the full subject text and the earlier
449
+ evidence. A request over the runner's 160,000-character context bound stops
450
+ the run instead of cutting evidence.
451
+ 4. Checks send weak work back ([5.3](#53-steps)). Sending back marks that
452
+ step and everything built on it to run again.
453
+ 5. At an approval the run waits, for as long as it takes. A decision is
454
+ `approve`, `revise` (with a note) or `reject`. It names the SHA-256 of the
455
+ exact text the person was shown (`seen`) and the approval's id, which
456
+ differs for every occurrence, so a delayed decision cannot land on text that
457
+ changed since or on a later review of the same text. With no decision the
458
+ runner returns the run still waiting.
459
+ 6. A provider answer that is truncated, incomplete, or asks for a tool the
460
+ step was not offered stops the run with a reason. Failed page reads, missing
461
+ search and partial pages are recorded as limitations when usable work
462
+ continues.
463
+ 7. The reference runner's budgets: 60 model calls and 20 page reads per run, 4
464
+ searches and 8 model turns per step, 14,000 characters of text per page.
465
+ 8. A finished run ends with the deliverable and a [receipt](#8-receipts). A
466
+ run that was rejected at a decision has no deliverable and no receipt.
467
+
468
+ A repeated run follows the same declared workflow; model outputs can differ.
469
+
470
+ ## 8. Receipts
471
+
472
+ A completed run produces a receipt (`kind: factory-run-receipt`, `v: 2`):
473
+
474
+ | Field | Meaning |
475
+ |---|---|
476
+ | `run`, `issuer` | the run id; `self` for a local run |
477
+ | `factory` | name, version and the bundle hash ([section 9](#9-identity-and-the-transfer-bundle)) |
478
+ | `inputs_sha256` | hash of the canonical JSON of the accepted inputs |
479
+ | `runner` | mode, provider and model |
480
+ | `started`, `finished` | ISO 8601 times |
481
+ | `steps` | every step attempt: status, tools used and targets, verdicts, limitations, decisions with `seen_sha256` and `approval_id`, `output_sha256`; for reviews, the target hash, reviewer provider and model, input and evidence hashes and the request hash |
482
+ | `flags` | what the person should know: failed checks, unreviewed results, limitations |
483
+ | `outputs` | with declared outputs: each output's hash and review |
484
+ | `deliverable_review` | `passed`, `limited` (a passing review with missing evidence), `flagged`, `unreviewed` or `not_checked`, for the delivered bytes |
485
+ | `deliverable_sha256`, `usage` | hash of the deliverable; model calls and tokens |
486
+
487
+ A runner MAY sign a receipt: `signature: { key_id, sig }`, an Ed25519
488
+ signature (base64url) over the canonical JSON of the receipt without its
489
+ `signature` field. `verifyReceipt(receipt, keys, deliverable)` checks the
490
+ signature against published keys and the deliverable against its hash. A
491
+ local receipt is unsigned and self-attested. No review or signature
492
+ guarantees factual accuracy; Ed25519 is not post-quantum.
493
+
494
+ ## 9. Identity and the transfer bundle
495
+
496
+ **Canonical JSON** sorts object keys at every level and has no whitespace.
497
+
498
+ A factory's **hash** is the SHA-256 of the canonical JSON of its files, as a
499
+ map from path to text with `\n` line endings (`bundleHash`). Its identity is
500
+ the hash of the **canonical bundle**: the source files plus the generated
501
+ foreman when the author wrote none (`withForeman`). An edit is a new version
502
+ with a new hash.
503
+
504
+ The **transfer bundle** (`mindburn.factory.bundle/v1`) carries a factory as
505
+ one JSON document:
506
+
507
+ ```json
508
+ {
509
+ "format": "mindburn.factory.bundle/v1",
510
+ "status": "existing-source",
511
+ "source": { "project": "launch-kit", "factory_path": "factory.yaml" },
512
+ "files": [
513
+ { "path": "factory.yaml", "content": "...", "sha256": "<64 hex>", "bytes": 312 }
514
+ ],
515
+ "warnings": [],
516
+ "review_required": true,
517
+ "meta": { "file_count": 7 }
518
+ }
519
+ ```
520
+
521
+ - `status` is `existing-source` or `inferred-draft` (a factory reconstructed
522
+ from a project that had no `factory.yaml`).
523
+ - When `sha256` or `bytes` is present, a reader MUST reject a file that does
524
+ not match it.
525
+ - At most 60 files and 400,000 UTF-8 bytes. Paths outside
526
+ [section 1](#1-files) are listed in `left_out` and not read; unsafe paths
527
+ are errors.
528
+
529
+ ## 10. Companion files
530
+
531
+ ### mindburn.tests.yaml
532
+
533
+ Declarative examples of a run and checks on its deliverable. No code,
534
+ regular expressions or model judge.
535
+
536
+ ```yaml
537
+ version: 1
538
+ cases:
539
+ keeps_owner:
540
+ name: Keeps the owner and action
541
+ inputs:
542
+ notes: Dana sends the invoice.
543
+ expect:
544
+ contains: [Dana, invoice]
545
+ excludes: [invented]
546
+ min_length: 15
547
+ max_length: 2000
548
+ ```
549
+
550
+ - 1 to 8 cases. Case names are a lowercase letter followed by up to 63
551
+ lowercase letters, digits, `_` or `-`. `name` is at most 100 characters.
552
+ - `inputs` MUST pass the factory's input checks.
553
+ - `contains` and `excludes`: 1 to 50 phrases of up to 500 characters,
554
+ compared ignoring case and differences in whitespace (NFKC). `min_length`
555
+ and `max_length`: integers from 0 to 100,000, counted in Unicode characters.
556
+ At least one check per case.
557
+ - Test inputs ship with the factory: use invented or public data.
558
+
559
+ `node run.mjs --test` runs every case with your provider and writes
560
+ `author-test-results.json`. Passing checks are a regression signal on these
561
+ examples, not a general effectiveness benchmark.
562
+
563
+ ### mindburn.requirements.yaml
564
+
565
+ The author's declarations about models and cost:
566
+
567
+ ```yaml
568
+ models:
569
+ recommended: claude-haiku-5-5
570
+ minimum: claude-haiku-5-5
571
+ expected_cost:
572
+ currency: USD
573
+ min: 0.008
574
+ max: 0.02
575
+ model: claude-haiku-5-5
576
+ basis: How the estimate was made.
577
+ ```
578
+
579
+ These are declarations, not verified compatibility or a spending cap.
580
+ `packageManifest` reports them with `provenance: author-declared`.
581
+
582
+ ## 11. What the format leaves out
583
+
584
+ - There are no variables, expressions or code.
585
+ - Loops exist only as "send this work back".
586
+ - Agents work with text and the public web. They do not send email, write to
587
+ your systems or act on your behalf: the deliverable is a document, a draft
588
+ or a plan that a person uses.
589
+
590
+ ## 12. JSON Schemas and conformance
591
+
592
+ [`schema/factory.schema.json`](schema/factory.schema.json) and
593
+ [`schema/flow.schema.json`](schema/flow.schema.json) (JSON Schema 2020-12)
594
+ describe the shape of `factory.yaml` and `flow.yaml` after YAML parsing.
595
+ [`test/schema.test.mjs`](test/schema.test.mjs) checks them against the
596
+ engine on the fixtures in [`fixtures/`](fixtures):
597
+
598
+ - `valid/`: the schemas and the engine both accept them. Every house factory
599
+ is also checked.
600
+ - `invalid/`: the schemas and the engine both reject them.
601
+ - `semantic/`: the schemas accept them and the engine rejects them, by a rule
602
+ of [section 6](#6-validity-and-runnability) that a per-file schema cannot
603
+ express, such as a missing agent file or a circle of steps.
604
+ - `lenient/`: the engine accepts them and the schemas reject them. The engine
605
+ converts or ignores values the format does not define. The fixtures cover:
606
+ an uppercase `kind`; an unknown input `type` (read as `text`); a number
607
+ where text belongs (a numeric `name` or `version`); a comma-separated
608
+ `tags` string; any non-empty `schemaVersion`, and any `flow` value (with a
609
+ warning); `rounds` outside 0 to 5 (clamped); an uppercase `agent` (read in
610
+ lowercase); `checks` on a `work` step (ignored); a `done` item that YAML
611
+ reads as a map (joined into text); an input given as plain text (read as
612
+ its help); step names that are not written normalized. The engine also
613
+ accepts, without fixtures here, non-boolean `required` and `optional`,
614
+ non-integer `rounds` (the default is used), and scalars where
615
+ `repositories`, `agentDefaults`, `author` or `tags` items belong. Authors
616
+ SHOULD NOT rely on any of these; a future version may reject them.
617
+
618
+ A conforming factory validates against both schemas and passes the rules of
619
+ [section 6](#6-validity-and-runnability). The engine is the reference: where
620
+ this document and the engine disagree, that is a bug in one of them, and an
621
+ issue is welcome.
@@ -0,0 +1,43 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "https://github.com/Mindburn-Labs/factoryhub/blob/main/spec/schema/factory.schema.json",
4
+ "title": "factory.yaml",
5
+ "description": "A factory's name, purpose and default model recommendation, format v1alpha1. Describes the document after YAML parsing. See spec/factory-format.md, section 3.",
6
+ "type": "object",
7
+ "required": ["schemaVersion", "name", "description"],
8
+ "properties": {
9
+ "schemaVersion": {
10
+ "description": "The published factory schema version.",
11
+ "const": "v1alpha1"
12
+ },
13
+ "name": {
14
+ "description": "The factory's id: lowercase letters, digits and single hyphens, not starting or ending with a hyphen.",
15
+ "type": "string",
16
+ "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
17
+ "maxLength": 64
18
+ },
19
+ "description": {
20
+ "description": "What the factory produces and when to use it.",
21
+ "type": "string",
22
+ "pattern": "\\S"
23
+ },
24
+ "repositories": {
25
+ "description": "Repositories a runtime must check out. Non-empty makes the factory not runnable by the reference runner.",
26
+ "type": "array"
27
+ },
28
+ "agentDefaults": {
29
+ "description": "Defaults for every agent.",
30
+ "type": "object",
31
+ "properties": {
32
+ "harness": {
33
+ "description": "The author's recommended harness and model. A recommendation, not a requirement.",
34
+ "type": "object",
35
+ "properties": {
36
+ "type": { "type": "string" },
37
+ "model": { "type": "string" }
38
+ }
39
+ }
40
+ }
41
+ }
42
+ }
43
+ }