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.
- package/LICENSE +202 -0
- package/NOTICE +16 -0
- package/README.md +189 -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 +356 -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/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/package.json +79 -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 +55 -0
- package/packages/cli/src/commands/get.mjs +38 -0
- package/packages/cli/src/commands/inspect.mjs +66 -0
- package/packages/cli/src/commands/list.mjs +29 -0
- package/packages/cli/src/commands/mcp.mjs +26 -0
- package/packages/cli/src/commands/new.mjs +148 -0
- package/packages/cli/src/commands/pack.mjs +97 -0
- package/packages/cli/src/commands/resume.mjs +67 -0
- package/packages/cli/src/commands/run.mjs +190 -0
- package/packages/cli/src/commands/search.mjs +31 -0
- package/packages/cli/src/commands/validate.mjs +81 -0
- package/packages/cli/src/main.mjs +68 -0
- package/packages/cli/src/util.mjs +21 -0
- package/packages/engine/lib/catalog.mjs +50 -0
- package/packages/engine/lib/hub.mjs +71 -0
- package/packages/engine/lib/node.mjs +114 -0
- package/packages/engine/lib/providers.mjs +52 -0
- package/packages/engine/lib/run.mjs +131 -0
- package/packages/engine/lib/skill.mjs +229 -0
- package/packages/engine/package.json +39 -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 +1762 -0
- package/packages/engine/src/index.mjs +9 -0
- package/packages/engine/src/markdown.mjs +97 -0
- package/packages/engine/src/package.mjs +116 -0
- package/packages/engine/src/run.mjs +232 -0
- package/packages/mcp/bin/factoryhub-mcp.mjs +6 -0
- package/packages/mcp/package.json +36 -0
- package/packages/mcp/src/server.mjs +280 -0
- package/spec/README.md +36 -0
- package/spec/factory-format.md +621 -0
- package/spec/schema/factory.schema.json +43 -0
- package/spec/schema/flow.schema.json +169 -0
- 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
|
+
}
|