factoryhub 0.1.0 → 0.1.1

package/spec/schema/factory.yaml.json

@@ -0,0 +1,815 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://factory.mindburn.org/schemas/factory.yaml.json",
+  "title": "factory.yaml",
+  "description": "A whole factory in one file. Each section is one file of the factory bundle; factoryhub turns it back into the bundle, byte for byte.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "format"
+  ],
+  "patternProperties": {
+    "^x-": {
+      "description": "A note of yours: kept in your text as you wrote it, never a file of the bundle."
+    }
+  },
+  "properties": {
+    "format": {
+      "const": "mindburn.factory.yaml/v1",
+      "description": "The layout of this file. Required."
+    },
+    "factory": {
+      "description": "factory.yaml of the bundle: the name, what the factory produces and when to use it, and the default model.",
+      "anyOf": [
+        {
+          "$ref": "#/definitions/factoryFile"
+        },
+        {
+          "type": "string",
+          "description": "The exact text of factory.yaml, as one JSON string. The writer uses this only for a file a YAML block cannot carry byte for byte."
+        }
+      ]
+    },
+    "flow": {
+      "description": "flow.yaml of the bundle: title, licence, tags, inputs, steps (work, checks, approvals, deliver) and outputs.",
+      "anyOf": [
+        {
+          "$ref": "#/definitions/flowFile"
+        },
+        {
+          "type": "string",
+          "description": "The exact text of flow.yaml, as one JSON string. The writer uses this only for a file a YAML block cannot carry byte for byte."
+        }
+      ]
+    },
+    "agents": {
+      "type": "object",
+      "description": "One entry per agent (agents/<name>/agent.md): its settings, and its standing instructions under instructions: |.",
+      "propertyNames": {
+        "pattern": "^[a-z0-9][a-z0-9_-]{0,40}$"
+      },
+      "additionalProperties": {
+        "anyOf": [
+          {
+            "$ref": "#/definitions/agent"
+          },
+          {
+            "type": "string",
+            "description": "The exact text of agent.md, as one JSON string."
+          },
+          {
+            "type": "null",
+            "description": "Only for foreman: the bundle has no coordinator file."
+          }
+        ]
+      }
+    },
+    "tests": {
+      "description": "mindburn.tests.yaml: the author's examples. Each runs the factory on its inputs and checks the result.",
+      "anyOf": [
+        {
+          "$ref": "#/definitions/testsFile"
+        },
+        {
+          "type": "string",
+          "description": "The exact text of mindburn.tests.yaml, as one JSON string. The writer uses this only for a file a YAML block cannot carry byte for byte."
+        }
+      ]
+    },
+    "requirements": {
+      "description": "mindburn.requirements.yaml: the recommended and minimum model, and an expected cost the author declares.",
+      "anyOf": [
+        {
+          "$ref": "#/definitions/requirementsFile"
+        },
+        {
+          "type": "string",
+          "description": "The exact text of mindburn.requirements.yaml, as one JSON string. The writer uses this only for a file a YAML block cannot carry byte for byte."
+        }
+      ]
+    },
+    "package": {
+      "description": "mindburn.package.yaml, kept as written.",
+      "anyOf": [
+        {
+          "type": "object"
+        },
+        {
+          "type": "string",
+          "description": "The exact text of mindburn.package.yaml, as one JSON string. The writer uses this only for a file a YAML block cannot carry byte for byte."
+        }
+      ]
+    },
+    "samples": {
+      "type": "object",
+      "description": "Sample files under examples/, by their path there.",
+      "additionalProperties": {
+        "anyOf": [
+          {
+            "type": "string",
+            "description": "The file's text: a | block (|- when it has no final line break), or one JSON string."
+          },
+          {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "sha256",
+              "bytes"
+            ],
+            "description": "Keeps this file exactly as it is in the version you started from: a file over 32768 bytes is written this way. Replace it with a | block to change it.",
+            "properties": {
+              "sha256": {
+                "type": "string",
+                "description": "SHA-256 of the file in the version you started from.",
+                "pattern": "^[a-f0-9]{64}$"
+              },
+              "bytes": {
+                "type": "integer",
+                "minimum": 0,
+                "description": "Its length in UTF-8 bytes."
+              }
+            }
+          }
+        ]
+      }
+    },
+    "files": {
+      "type": "object",
+      "description": "Every other file of the bundle by its path: README.md, LICENSE, CHANGELOG.md, skills, prompts, schemas… Files over 32768 bytes may be references.",
+      "additionalProperties": {
+        "anyOf": [
+          {
+            "type": "string",
+            "description": "The file's text: a | block (|- when it has no final line break), or one JSON string."
+          },
+          {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "sha256",
+              "bytes"
+            ],
+            "description": "Keeps this file exactly as it is in the version you started from: a file over 32768 bytes is written this way. Replace it with a | block to change it.",
+            "properties": {
+              "sha256": {
+                "type": "string",
+                "description": "SHA-256 of the file in the version you started from.",
+                "pattern": "^[a-f0-9]{64}$"
+              },
+              "bytes": {
+                "type": "integer",
+                "minimum": 0,
+                "description": "Its length in UTF-8 bytes."
+              }
+            }
+          }
+        ]
+      }
+    }
+  },
+  "definitions": {
+    "factoryFile": {
+      "type": "object",
+      "required": [
+        "schemaVersion",
+        "name",
+        "description"
+      ],
+      "properties": {
+        "schemaVersion": {
+          "const": "v1alpha1",
+          "description": "The version of factory.yaml."
+        },
+        "name": {
+          "type": "string",
+          "description": "The factory's name: lowercase letters, digits and hyphens.",
+          "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+          "maxLength": 64
+        },
+        "description": {
+          "type": "string",
+          "description": "What the factory produces and when to use it. Shown on its card and given to every agent."
+        },
+        "repositories": {
+          "type": "array",
+          "description": "Repositories a harness would check out. This runner reads none."
+        },
+        "agentDefaults": {
+          "type": "object",
+          "description": "Defaults for every agent.",
+          "properties": {
+            "harness": {
+              "type": "object",
+              "properties": {
+                "type": {
+                  "type": "string",
+                  "description": "The harness, such as claude."
+                },
+                "model": {
+                  "type": "string",
+                  "description": "The default model, such as claude-haiku-5-5."
+                }
+              }
+            },
+            "model": {
+              "type": "string",
+              "description": "The default model."
+            }
+          }
+        }
+      }
+    },
+    "flowFile": {
+      "type": "object",
+      "required": [
+        "steps"
+      ],
+      "description": "flow.yaml. A field not listed here is kept exactly as written; this runner reads only the fields it knows.",
+      "properties": {
+        "flow": {
+          "const": "mindburn.flow/v1",
+          "description": "The flow format this runner reads."
+        },
+        "title": {
+          "type": "string",
+          "description": "The title people see.",
+          "maxLength": 200
+        },
+        "author": {
+          "type": "string",
+          "description": "Who wrote it."
+        },
+        "version": {
+          "type": [
+            "string",
+            "number"
+          ],
+          "description": "The author's version, such as \"1.2.0\". Quote it so YAML keeps it as text."
+        },
+        "license": {
+          "type": "string",
+          "description": "Under which licence others may use it: an SPDX identifier such as MIT or Apache-2.0.",
+          "examples": [
+            "MIT",
+            "Apache-2.0",
+            "CC-BY-4.0"
+          ]
+        },
+        "tags": {
+          "anyOf": [
+            {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            {
+              "type": "string"
+            }
+          ],
+          "description": "Words people find it by."
+        },
+        "time": {
+          "type": "string",
+          "description": "How long a run takes, in words, such as \"about 1 minute\"."
+        },
+        "requires": {
+          "type": "array",
+          "items": {
+            "anyOf": [
+              {
+                "const": "scoped-context",
+                "description": "Steps share only the inputs and results their context names."
+              },
+              {
+                "const": "multiple-outputs",
+                "description": "The flow delivers several documents, listed under outputs."
+              },
+              {
+                "const": "blocking-checks",
+                "description": "A check may say on_fail: stop and hold refused work until the owner releases it."
+              },
+              {
+                "const": "tool-sources",
+                "description": "Steps may use tools of the sources this flow declares (RFC 0017, proposed). A runner without it refuses the flow."
+              },
+              {
+                "type": "string",
+                "description": "A feature another runner defines."
+              }
+            ]
+          },
+          "description": "Execution features this flow needs. A runner without one refuses the flow. This runner has scoped-context, multiple-outputs."
+        },
+        "sources": {
+          "type": "object",
+          "description": "RFC 0017 (proposed): the services this flow uses tools from, by source key, at most 8. They mean something only with requires: [tool-sources]; otherwise they are kept and have no effect. Plain data: no command, header, environment variable or credential.",
+          "propertyNames": {
+            "pattern": "^[a-z0-9][a-z0-9_-]{0,40}$"
+          },
+          "maxProperties": 8
+        },
+        "inputs": {
+          "type": "object",
+          "description": "What a person gives the factory, at most 8. The key is the input's name.",
+          "maxProperties": 8,
+          "additionalProperties": {
+            "$ref": "#/definitions/input"
+          }
+        },
+        "steps": {
+          "type": "object",
+          "description": "The steps, at most 24, in order. The key is the step's name.",
+          "minProperties": 1,
+          "maxProperties": 24,
+          "additionalProperties": {
+            "$ref": "#/definitions/step"
+          }
+        },
+        "done": {
+          "type": "array",
+          "items": {
+            "type": [
+              "string",
+              "object"
+            ]
+          },
+          "description": "What a finished result must be: checks call them criteria."
+        },
+        "outputs": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 24,
+          "description": "The documents to deliver, each from a work or deliver step, in order.",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "step",
+              "title"
+            ],
+            "properties": {
+              "step": {
+                "type": "string",
+                "description": "The step whose result this is."
+              },
+              "title": {
+                "type": "string",
+                "description": "The document's title.",
+                "maxLength": 200
+              }
+            }
+          }
+        },
+        "composition": {
+          "type": "object",
+          "description": "Written by factoryhub when it composed this flow from others: the compiler, the intent and the source hashes. Keep it as it is."
+        }
+      },
+      "if": {
+        "required": [
+          "requires"
+        ],
+        "properties": {
+          "requires": {
+            "type": "array",
+            "contains": {
+              "const": "tool-sources"
+            }
+          }
+        }
+      },
+      "then": {
+        "properties": {
+          "sources": {
+            "type": "object",
+            "propertyNames": {
+              "pattern": "^[a-z0-9][a-z0-9_-]{0,40}$"
+            },
+            "maxProperties": 8,
+            "additionalProperties": {
+              "$ref": "#/definitions/source"
+            }
+          }
+        }
+      }
+    },
+    "source": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "title",
+        "mcp",
+        "tools"
+      ],
+      "description": "A service that offers tools. Its tools are named in a step's tools as <source>/<tool>.",
+      "properties": {
+        "title": {
+          "type": "string",
+          "description": "The name a person sees when they connect it.",
+          "minLength": 1,
+          "maxLength": 100
+        },
+        "mcp": {
+          "type": "object",
+          "additionalProperties": false,
+          "minProperties": 1,
+          "description": "How to reach it over MCP: an address, a registry name, or both.",
+          "properties": {
+            "url": {
+              "type": "string",
+              "description": "The server's Streamable HTTP address: https, a host name, no user name, query or fragment.",
+              "format": "uri",
+              "pattern": "^https://"
+            },
+            "registry": {
+              "type": "string",
+              "description": "Its name in the official MCP Registry, such as com.example/tracker."
+            }
+          }
+        },
+        "target": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "label"
+          ],
+          "description": "What a grant to this source is limited to.",
+          "properties": {
+            "label": {
+              "type": "string",
+              "description": "What a person chooses, such as Project.",
+              "minLength": 1,
+              "maxLength": 40
+            },
+            "help": {
+              "type": "string",
+              "description": "How to choose it.",
+              "maxLength": 200
+            }
+          }
+        },
+        "tools": {
+          "type": "object",
+          "minProperties": 1,
+          "maxProperties": 24,
+          "propertyNames": {
+            "pattern": "^[A-Za-z0-9_.-]{1,128}$"
+          },
+          "additionalProperties": {
+            "$ref": "#/definitions/sourceTool"
+          },
+          "description": "The tools this flow may use, by the name the source gives them."
+        }
+      }
+    },
+    "sourceTool": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "effect"
+      ],
+      "properties": {
+        "effect": {
+          "enum": [
+            "read",
+            "write",
+            "external",
+            "irreversible"
+          ],
+          "description": "read changes nothing; write changes something inside the granted system; external sends data out of it; irreversible cannot be undone. Changes wait for a person to approve the exact payload."
+        },
+        "title": {
+          "type": "string",
+          "description": "Plain words for the consent.",
+          "maxLength": 100
+        },
+        "target": {
+          "type": "string",
+          "description": "The argument that carries the target. Only when the source declares target."
+        },
+        "idempotency": {
+          "type": "string",
+          "description": "The argument that carries an idempotency key. Only for a change."
+        }
+      }
+    },
+    "input": {
+      "anyOf": [
+        {
+          "type": "string",
+          "description": "What the person should enter."
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "type": {
+              "enum": [
+                "text",
+                "longtext",
+                "url"
+              ],
+              "description": "text (one line), longtext (pasted text) or url."
+            },
+            "label": {
+              "type": "string",
+              "description": "The label shown on the form."
+            },
+            "help": {
+              "type": "string",
+              "description": "What to enter, with an example."
+            },
+            "optional": {
+              "type": "boolean",
+              "description": "true: the person may leave it empty."
+            },
+            "required": {
+              "type": "boolean",
+              "description": "false: the same as optional: true."
+            },
+            "visibility": {
+              "enum": [
+                "public",
+                "private"
+              ],
+              "description": "public: the value may go to public research steps."
+            }
+          }
+        }
+      ]
+    },
+    "step": {
+      "type": "object",
+      "description": "One step. A field not listed here is kept as written; this runner warns that it does not read it.",
+      "properties": {
+        "title": {
+          "type": "string",
+          "description": "What people see for this step."
+        },
+        "agent": {
+          "type": "string",
+          "description": "The agent who does it: a name under agents. An approve step is the owner's."
+        },
+        "kind": {
+          "enum": [
+            "work",
+            "check",
+            "approve",
+            "deliver"
+          ],
+          "description": "work: does part of the job. check: an agent holds earlier work against criteria and sends it back. approve: the owner decides. deliver: writes the result."
+        },
+        "needs": {
+          "anyOf": [
+            {
+              "type": "string",
+              "description": "One earlier step."
+            },
+            {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "description": "Earlier steps this one waits for. Without needs, a step waits for the one written before it."
+            }
+          ]
+        },
+        "checks": {
+          "type": "string",
+          "description": "check: the earlier step it checks. Default: the work it needs."
+        },
+        "shows": {
+          "type": "string",
+          "description": "approve: the earlier step the owner sees. Default: the work it needs."
+        },
+        "tools": {
+          "type": "array",
+          "items": {
+            "anyOf": [
+              {
+                "enum": [
+                  "web_search",
+                  "web_fetch"
+                ]
+              },
+              {
+                "type": "string",
+                "pattern": "^[a-z0-9][a-z0-9_-]{0,40}/[A-Za-z0-9_.-]{1,128}$",
+                "description": "A tool of a declared source, as <source>/<tool> (RFC 0017)."
+              },
+              {
+                "type": "string",
+                "description": "A tool another harness names; this runner cannot run a step that needs it."
+              }
+            ]
+          },
+          "description": "Tools this step may use. This runner has web_search and web_fetch."
+        },
+        "task": {
+          "type": "string",
+          "description": "What to do, in plain words. A check's task is what passing means."
+        },
+        "rounds": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 5,
+          "description": "check: how often it may send work back. approve: how often the owner may ask for changes (default 3)."
+        },
+        "context": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "Share only these inputs and earlier results with the step.",
+          "properties": {
+            "inputs": {
+              "type": "object",
+              "additionalProperties": {
+                "type": "string"
+              }
+            },
+            "artifacts": {
+              "type": "object",
+              "additionalProperties": {
+                "type": "string"
+              }
+            },
+            "public": {
+              "type": "boolean",
+              "description": "true: public research that may never receive private facts."
+            }
+          }
+        },
+        "criteria": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "check: what the work must meet."
+        },
+        "mcp": {
+          "type": "array",
+          "description": "A tool or connection another harness names. This runner cannot run a step that needs it; the step is kept for a harness that can."
+        },
+        "mcpServers": {
+          "type": "array",
+          "description": "A tool or connection another harness names. This runner cannot run a step that needs it; the step is kept for a harness that can."
+        },
+        "mcp_servers": {
+          "type": "array",
+          "description": "A tool or connection another harness names. This runner cannot run a step that needs it; the step is kept for a harness that can."
+        },
+        "connectors": {
+          "type": "array",
+          "description": "A tool or connection another harness names. This runner cannot run a step that needs it; the step is kept for a harness that can."
+        },
+        "plugins": {
+          "type": "array",
+          "description": "A tool or connection another harness names. This runner cannot run a step that needs it; the step is kept for a harness that can."
+        },
+        "skills": {
+          "type": "array",
+          "description": "A tool or connection another harness names. This runner cannot run a step that needs it; the step is kept for a harness that can."
+        }
+      }
+    },
+    "agent": {
+      "type": "object",
+      "properties": {
+        "description": {
+          "type": "string",
+          "description": "What this agent is for, in one line."
+        },
+        "agentType": {
+          "enum": [
+            "CUSTOM",
+            "REVIEW",
+            "FOREMAN"
+          ],
+          "description": "CUSTOM does work, REVIEW checks it, FOREMAN coordinates (factoryhub writes one from the flow)."
+        },
+        "instructions": {
+          "type": "string",
+          "description": "The agent's role and standing instructions, in prose: instructions: | and the text indented under it."
+        }
+      }
+    },
+    "testsFile": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "version",
+        "cases"
+      ],
+      "properties": {
+        "version": {
+          "const": 1
+        },
+        "cases": {
+          "type": "object",
+          "minProperties": 1,
+          "maxProperties": 8,
+          "propertyNames": {
+            "pattern": "^[a-z][a-z0-9_-]{0,63}$"
+          },
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "inputs",
+              "expect"
+            ],
+            "properties": {
+              "name": {
+                "type": "string",
+                "description": "What this example shows.",
+                "maxLength": 100
+              },
+              "inputs": {
+                "type": "object",
+                "description": "A value for each input."
+              },
+              "expect": {
+                "type": "object",
+                "additionalProperties": false,
+                "minProperties": 1,
+                "properties": {
+                  "contains": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    },
+                    "description": "Text the result must contain."
+                  },
+                  "excludes": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    },
+                    "description": "Text the result must not contain."
+                  },
+                  "min_length": {
+                    "type": "integer",
+                    "minimum": 0,
+                    "maximum": 100000
+                  },
+                  "max_length": {
+                    "type": "integer",
+                    "minimum": 0,
+                    "maximum": 100000
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "requirementsFile": {
+      "type": "object",
+      "properties": {
+        "models": {
+          "type": "object",
+          "properties": {
+            "minimum": {
+              "type": "string",
+              "description": "The least capable model that works."
+            },
+            "recommended": {
+              "type": "string",
+              "description": "The model the author recommends."
+            }
+          }
+        },
+        "expected_cost": {
+          "type": "object",
+          "required": [
+            "currency",
+            "min",
+            "max",
+            "model",
+            "basis"
+          ],
+          "properties": {
+            "currency": {
+              "const": "USD"
+            },
+            "min": {
+              "type": "number"
+            },
+            "max": {
+              "type": "number"
+            },
+            "model": {
+              "type": "string",
+              "description": "The models it was measured with."
+            },
+            "basis": {
+              "type": "string",
+              "description": "How the author arrived at it."
+            }
+          }
+        }
+      }
+    }
+  }
+}