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.
- package/LICENSE +202 -0
- package/NOTICE +16 -0
- package/README.md +195 -2
- package/factories/README.md +17 -0
- package/factories/client-file-readiness/README.md +3 -0
- package/factories/client-file-readiness/agents/analyst/agent.md +10 -0
- package/factories/client-file-readiness/agents/reviewer/agent.md +10 -0
- package/factories/client-file-readiness/agents/writer/agent.md +11 -0
- package/factories/client-file-readiness/factory.yaml +12 -0
- package/factories/client-file-readiness/flow.yaml +56 -0
- package/factories/competitor-teardown/README.md +3 -0
- package/factories/competitor-teardown/agents/analyst/agent.md +10 -0
- package/factories/competitor-teardown/agents/researcher/agent.md +11 -0
- package/factories/competitor-teardown/agents/reviewer/agent.md +10 -0
- package/factories/competitor-teardown/agents/writer/agent.md +11 -0
- package/factories/competitor-teardown/factory.yaml +11 -0
- package/factories/competitor-teardown/flow.yaml +75 -0
- package/factories/homepage-audit/README.md +3 -0
- package/factories/homepage-audit/agents/analyst/agent.md +10 -0
- package/factories/homepage-audit/agents/researcher/agent.md +11 -0
- package/factories/homepage-audit/agents/reviewer/agent.md +10 -0
- package/factories/homepage-audit/agents/writer/agent.md +11 -0
- package/factories/homepage-audit/factory.yaml +11 -0
- package/factories/homepage-audit/flow.yaml +77 -0
- package/factories/inbox-triage/README.md +3 -0
- package/factories/inbox-triage/agents/analyst/agent.md +10 -0
- package/factories/inbox-triage/agents/reviewer/agent.md +10 -0
- package/factories/inbox-triage/agents/writer/agent.md +11 -0
- package/factories/inbox-triage/factory.yaml +11 -0
- package/factories/inbox-triage/flow.yaml +57 -0
- package/factories/index.json +587 -0
- package/factories/launch-kit/README.md +3 -0
- package/factories/launch-kit/agents/reviewer/agent.md +10 -0
- package/factories/launch-kit/agents/strategist/agent.md +10 -0
- package/factories/launch-kit/agents/writer/agent.md +11 -0
- package/factories/launch-kit/factory.yaml +12 -0
- package/factories/launch-kit/flow.yaml +75 -0
- package/factories/meeting-to-actions/CHANGELOG.md +7 -0
- package/factories/meeting-to-actions/README.md +15 -0
- package/factories/meeting-to-actions/agents/analyst/agent.md +10 -0
- package/factories/meeting-to-actions/agents/reviewer/agent.md +10 -0
- package/factories/meeting-to-actions/agents/writer/agent.md +11 -0
- package/factories/meeting-to-actions/factory.yaml +11 -0
- package/factories/meeting-to-actions/flow.yaml +53 -0
- package/factories/meeting-to-actions/mindburn.requirements.yaml +8 -0
- package/factories/meeting-to-actions/mindburn.tests.yaml +16 -0
- package/factories/newsletter-note/README.md +11 -0
- package/factories/newsletter-note/agents/reviewer/agent.md +10 -0
- package/factories/newsletter-note/agents/writer/agent.md +11 -0
- package/factories/newsletter-note/factory.yaml +12 -0
- package/factories/newsletter-note/flow.yaml +45 -0
- package/factories/newsletter-note/mindburn.tests.yaml +80 -0
- package/factories/outreach-pack/README.md +3 -0
- package/factories/outreach-pack/agents/reviewer/agent.md +5 -0
- package/factories/outreach-pack/agents/writer/agent.md +5 -0
- package/factories/outreach-pack/factory.yaml +9 -0
- package/factories/outreach-pack/flow.yaml +42 -0
- package/factories/prospect-brief/README.md +3 -0
- package/factories/prospect-brief/agents/researcher/agent.md +11 -0
- package/factories/prospect-brief/agents/reviewer/agent.md +10 -0
- package/factories/prospect-brief/agents/strategist/agent.md +10 -0
- package/factories/prospect-brief/agents/writer/agent.md +11 -0
- package/factories/prospect-brief/factory.yaml +11 -0
- package/factories/prospect-brief/flow.yaml +79 -0
- package/factories/release-desk/README.md +13 -0
- package/factories/release-desk/agents/editor/agent.md +10 -0
- package/factories/release-desk/agents/reviewer/agent.md +10 -0
- package/factories/release-desk/factory.yaml +13 -0
- package/factories/release-desk/flow.yaml +67 -0
- package/factories/release-desk/mindburn.tests.yaml +163 -0
- package/factories/short-video-cut/README.md +11 -0
- package/factories/short-video-cut/agents/reviewer/agent.md +10 -0
- package/factories/short-video-cut/agents/writer/agent.md +11 -0
- package/factories/short-video-cut/factory.yaml +13 -0
- package/factories/short-video-cut/flow.yaml +46 -0
- package/factories/short-video-cut/mindburn.tests.yaml +80 -0
- package/factories/video-facts/README.md +11 -0
- package/factories/video-facts/agents/analyst/agent.md +10 -0
- package/factories/video-facts/agents/reviewer/agent.md +10 -0
- package/factories/video-facts/factory.yaml +13 -0
- package/factories/video-facts/flow.yaml +39 -0
- package/factories/video-facts/mindburn.tests.yaml +34 -0
- package/factories/video-to-posts/README.md +35 -0
- package/factories/video-to-posts/agents/analyst/agent.md +10 -0
- package/factories/video-to-posts/agents/reviewer/agent.md +10 -0
- package/factories/video-to-posts/agents/writer/agent.md +11 -0
- package/factories/video-to-posts/factory.yaml +12 -0
- package/factories/video-to-posts/flow.yaml +62 -0
- package/factories/video-to-posts/mindburn.tests.yaml +34 -0
- package/factories/week-of-posts/README.md +11 -0
- package/factories/week-of-posts/agents/reviewer/agent.md +10 -0
- package/factories/week-of-posts/agents/writer/agent.md +11 -0
- package/factories/week-of-posts/factory.yaml +12 -0
- package/factories/week-of-posts/flow.yaml +46 -0
- package/factories/week-of-posts/mindburn.tests.yaml +80 -0
- package/package.json +92 -4
- package/packages/cli/bin/factoryhub.mjs +8 -0
- package/packages/cli/package.json +29 -0
- package/packages/cli/src/args.mjs +47 -0
- package/packages/cli/src/commands/export.mjs +54 -0
- package/packages/cli/src/commands/get.mjs +37 -0
- package/packages/cli/src/commands/inspect.mjs +65 -0
- package/packages/cli/src/commands/list.mjs +24 -0
- package/packages/cli/src/commands/login.mjs +161 -0
- package/packages/cli/src/commands/logout.mjs +43 -0
- package/packages/cli/src/commands/mcp.mjs +25 -0
- package/packages/cli/src/commands/new.mjs +147 -0
- package/packages/cli/src/commands/pack.mjs +96 -0
- package/packages/cli/src/commands/publish.mjs +62 -0
- package/packages/cli/src/commands/pull.mjs +59 -0
- package/packages/cli/src/commands/push.mjs +115 -0
- package/packages/cli/src/commands/resume.mjs +66 -0
- package/packages/cli/src/commands/run.mjs +352 -0
- package/packages/cli/src/commands/runs.mjs +52 -0
- package/packages/cli/src/commands/search.mjs +30 -0
- package/packages/cli/src/commands/validate.mjs +79 -0
- package/packages/cli/src/commands/whoami.mjs +34 -0
- package/packages/cli/src/hosted.mjs +159 -0
- package/packages/cli/src/main.mjs +134 -0
- package/packages/cli/src/tool-sources.mjs +272 -0
- package/packages/cli/src/util.mjs +58 -0
- package/packages/engine/lib/catalog.mjs +50 -0
- package/packages/engine/lib/credentials.mjs +121 -0
- package/packages/engine/lib/hosted.mjs +119 -0
- package/packages/engine/lib/hub.mjs +423 -0
- package/packages/engine/lib/nango.mjs +157 -0
- package/packages/engine/lib/node.mjs +242 -0
- package/packages/engine/lib/providers.mjs +57 -0
- package/packages/engine/lib/run.mjs +192 -0
- package/packages/engine/lib/skill.mjs +229 -0
- package/packages/engine/lib/text.mjs +5 -0
- package/packages/engine/package.json +45 -0
- package/packages/engine/src/author-tests.mjs +78 -0
- package/packages/engine/src/compose.mjs +150 -0
- package/packages/engine/src/cost.mjs +41 -0
- package/packages/engine/src/diagnostics.mjs +21 -0
- package/packages/engine/src/factory-engine.mjs +2109 -0
- package/packages/engine/src/flow-sources.mjs +135 -0
- package/packages/engine/src/index.mjs +9 -0
- package/packages/engine/src/markdown.mjs +97 -0
- package/packages/engine/src/mcp-client.mjs +429 -0
- package/packages/engine/src/package.mjs +116 -0
- package/packages/engine/src/run.mjs +308 -0
- package/packages/engine/src/tool-sources.mjs +566 -0
- package/packages/mcp/bin/factoryhub-mcp.mjs +6 -0
- package/packages/mcp/package.json +36 -0
- package/packages/mcp/src/server.mjs +310 -0
- package/packages/sdk/package.json +28 -0
- package/packages/sdk/src/index.d.ts +163 -0
- package/packages/sdk/src/index.mjs +266 -0
- package/spec/README.md +42 -0
- package/spec/factory-format.md +866 -0
- package/spec/schema/factory.schema.json +43 -0
- package/spec/schema/factory.yaml.json +815 -0
- package/spec/schema/flow.schema.json +191 -0
- 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.
|