factoryhub 0.0.0-stage → 0.1.0

package/spec/schema/flow.schema.json

@@ -0,0 +1,169 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/Mindburn-Labs/factoryhub/blob/main/spec/schema/flow.schema.json",
+  "title": "flow.yaml",
+  "description": "A factory's executable workflow, format v1alpha1 (mindburn.flow/v1). Describes the document after YAML parsing. Rules across steps and files (references, cycles, agent files) are in spec/factory-format.md, section 6.",
+  "type": "object",
+  "required": ["steps"],
+  "properties": {
+    "flow": { "description": "The flow format.", "const": "mindburn.flow/v1" },
+    "requires": {
+      "description": "Execution features the flow depends on.",
+      "type": "array",
+      "items": { "enum": ["scoped-context", "multiple-outputs"] }
+    },
+    "title": { "type": "string" },
+    "author": { "type": "string" },
+    "version": { "description": "The factory's version. Quote it, for example \"1.0.0\".", "type": "string" },
+    "license": { "description": "An SPDX license identifier is recommended.", "type": "string" },
+    "tags": { "type": "array", "items": { "type": "string" } },
+    "time": { "description": "How long a run takes, in words.", "type": "string" },
+    "inputs": {
+      "description": "What a person fills in before a run. At most eight.",
+      "type": ["object", "null"],
+      "maxProperties": 8,
+      "propertyNames": { "$ref": "#/$defs/name" },
+      "additionalProperties": { "$ref": "#/$defs/input" }
+    },
+    "steps": {
+      "description": "The steps, in the order they are written. At most 24.",
+      "type": "object",
+      "minProperties": 1,
+      "maxProperties": 24,
+      "propertyNames": { "$ref": "#/$defs/name" },
+      "additionalProperties": { "$ref": "#/$defs/step" }
+    },
+    "done": {
+      "description": "Checkable statements about the deliverable.",
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "outputs": {
+      "description": "Exact results to deliver, in order. Needs requires: [multiple-outputs].",
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 24,
+      "items": {
+        "type": "object",
+        "required": ["step", "title"],
+        "additionalProperties": false,
+        "properties": {
+          "step": { "$ref": "#/$defs/name" },
+          "title": { "type": "string", "pattern": "\\S", "maxLength": 200 }
+        }
+      }
+    },
+    "composition": {
+      "description": "Provenance of a composed factory.",
+      "type": "object",
+      "required": ["compiler", "intent", "sources", "unmetCapabilities"],
+      "additionalProperties": false,
+      "properties": {
+        "compiler": { "const": "mindburn.compose/v1" },
+        "intent": { "type": "string" },
+        "sources": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["id", "name", "version", "sha256"],
+            "properties": {
+              "id": { "type": "string" },
+              "name": { "type": "string" },
+              "version": { "type": "string" },
+              "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }
+            }
+          }
+        },
+        "unmetCapabilities": { "type": "array", "items": { "type": "string" } }
+      }
+    }
+  },
+  "$defs": {
+    "name": {
+      "description": "An input or step name, written normalized: lowercase letters and digits joined by single underscores.",
+      "type": "string",
+      "pattern": "^[a-z0-9]+(?:_[a-z0-9]+)*$",
+      "maxLength": 64
+    },
+    "agent": {
+      "description": "An agent folder name under agents/: lowercase letters and digits joined by single hyphens.",
+      "type": "string",
+      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+      "maxLength": 41
+    },
+    "input": {
+      "type": "object",
+      "properties": {
+        "type": { "enum": ["text", "longtext", "url"] },
+        "label": { "type": "string" },
+        "help": { "type": "string" },
+        "optional": { "type": "boolean" },
+        "required": { "type": "boolean" },
+        "visibility": { "enum": ["public", "private"] }
+      }
+    },
+    "toolList": {
+      "oneOf": [
+        { "type": "string" },
+        { "type": "array", "items": { "type": "string" } }
+      ]
+    },
+    "step": {
+      "type": "object",
+      "properties": {
+        "title": { "type": "string" },
+        "kind": { "enum": ["work", "check", "approve", "deliver"] },
+        "agent": { "$ref": "#/$defs/agent" },
+        "task": { "type": "string" },
+        "needs": {
+          "oneOf": [
+            { "$ref": "#/$defs/name" },
+            { "type": "array", "items": { "$ref": "#/$defs/name" } },
+            { "type": "null" }
+          ]
+        },
+        "checks": { "$ref": "#/$defs/name" },
+        "shows": { "$ref": "#/$defs/name" },
+        "rounds": { "type": "integer", "minimum": 0, "maximum": 5 },
+        "tools": { "$ref": "#/$defs/toolList" },
+        "mcp": {}, "mcpServers": {}, "mcp_servers": {}, "connectors": {}, "plugins": {}, "skills": {},
+        "context": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "inputs": { "$ref": "#/$defs/bindings" },
+            "artifacts": { "$ref": "#/$defs/bindings" },
+            "public": { "type": "boolean" }
+          }
+        },
+        "criteria": {
+          "type": "array",
+          "items": { "type": "string", "pattern": "\\S" }
+        }
+      },
+      "allOf": [
+        {
+          "if": { "not": { "properties": { "kind": { "const": "approve" } }, "required": ["kind"] } },
+          "then": { "required": ["agent"] }
+        },
+        {
+          "if": { "anyOf": [{ "not": { "required": ["kind"] } }, { "properties": { "kind": { "enum": ["work", "deliver"] } } }] },
+          "then": { "required": ["task"], "properties": { "task": { "type": "string", "pattern": "\\S" } } }
+        },
+        {
+          "if": { "required": ["checks"] },
+          "then": { "required": ["kind"], "properties": { "kind": { "const": "check" } } }
+        },
+        {
+          "if": { "required": ["shows"] },
+          "then": { "properties": { "kind": { "const": "approve" } }, "required": ["kind"] }
+        }
+      ]
+    },
+    "bindings": {
+      "type": "object",
+      "propertyNames": { "pattern": "^[a-z][a-z0-9_]{0,63}$" },
+      "additionalProperties": { "$ref": "#/$defs/name" }
+    }
+  }
+}

package/spec/skill-export.md

@@ -0,0 +1,126 @@
+# Exporting a factory as an Agent Skill
+
+Status: alpha, version 1. This mapping turns a factory into an
+[Agent Skills](https://agentskills.io/specification) folder, so any agent that
+loads skills can find the factory, collect its inputs, follow its steps and
+stop where a person decides. `factoryhub export --as skill`, the MCP tool
+`export_skill` and `exportSkill()` in
+[`packages/engine/lib/skill.mjs`](../packages/engine/lib/skill.mjs) implement
+it. Another implementation, such as the factoryhub site, MUST produce the
+same bytes for the same canonical bundle and id: the expected `SKILL.md` of
+every house factory is in [`skill-export/`](skill-export), and
+[`test/skill-export.test.mjs`](test/skill-export.test.mjs) checks it.
+
+## Layout
+
+```text
+<id>/
+  SKILL.md        frontmatter and instructions written from the flow
+  factory/...     the canonical bundle, byte for byte
+```
+
+`<id>` is the factory's id: its `name`, or the id the factoryhub catalogue
+gives it. It MUST be lowercase letters, digits and single hyphens, at most 64
+characters, as both formats require.
+
+`factory/` holds the **canonical bundle** (spec section 9): the factory's own
+files, unchanged, plus `agents/foreman/agent.md` written from the flow when
+the author wrote none. Nothing else is added or changed.
+
+## Frontmatter
+
+```yaml
+---
+name: "<id>"
+description: "<description>"
+license: "<license>"
+metadata:
+  factoryhub-id: "<id>"
+  factoryhub-version: "<version>"
+  factoryhub-source: "https://factory.mindburn.org/f/<id>"
+  factoryhub-sha256: "<bundle sha256>"
+  factoryhub-author: "<author>"
+---
+```
+
+| Field | Value |
+|---|---|
+| `name` | the id |
+| `description` | the factory's description with every run of whitespace turned into one space. If it does not contain "use when" (in any case), append ` Use when the person wants to run the “<title>” factory.` If the result is longer than 1,024 characters, the factory description is cut at a word boundary to fit and ends with `…` before the appended sentence |
+| `license` | the `license` in `flow.yaml`. Left out when the flow declares none |
+| `metadata.factoryhub-id` | the id |
+| `metadata.factoryhub-version` | the `version` in `flow.yaml` |
+| `metadata.factoryhub-source` | `https://factory.mindburn.org/f/<id>`, or the same path on another factoryhub address |
+| `metadata.factoryhub-sha256` | the SHA-256 of the canonical bundle, as hex: the factory's identity |
+| `metadata.factoryhub-author` | the `author` in `flow.yaml`. Left out when the flow declares none |
+
+Every value is written as a JSON string, which YAML reads as a double-quoted
+scalar, so an id such as `no` or `2024` stays text in every YAML reader. The fields appear in
+the order above, one per line; the `metadata` keys are indented by two
+spaces. `metadata` is a map from strings to strings, as the Agent Skills
+specification requires, and holds nothing but these keys.
+
+## Body
+
+After the frontmatter, a blank line, then these parts in order:
+
+1. `# <title>`, the description, and a line naming the factory id and its
+   version, saying that `factory/` holds its files unchanged, "plus a foreman
+   written from the flow" when the canonical bundle's
+   `agents/foreman/agent.md` is the one the engine writes from the flow
+   (`isGeneratedForeman`) or "with nothing added" otherwise, and giving the
+   source address. The sentence depends on the canonical bundle alone, so a
+   source with or without the generated foreman exports to the same bytes.
+2. `## What it produces`: the deliverable (the declared outputs in order, or
+   the final step and its agent), then the `done` statements as a list.
+3. `## Inputs to collect`: how many are required, then one line per input:
+   name, type, required or optional, help; then the input limits and "Never
+   invent a missing input".
+4. `## Steps`: the order rule, the parallel rule when two steps need the same
+   earlier steps, then every step in file order, numbered:
+   - work and deliver: title, kind, the agent with its description, what it
+     needs, its tools, then its task;
+   - check: title, the reviewer agent, what it needs, the step it checks, the
+     criteria as a quotation, and what happens when it fails, by `rounds`;
+   - approve: title, "Who: the person", what it needs, then
+     `Stop and ask the person to approve the result of "<subject title>".`,
+     "Show it to them in full", its task, and what approve, change (by
+     `rounds`) and reject do, ending "Never decide for them".
+5. `## Run it with the factoryhub CLI`: how to run the bundle in `factory/`
+   with the CLI and the person's own key or a local model.
+6. `## Follow it by hand`: read the foreman, take on each agent's role, stop
+   and ask the person to approve at every decision, deliver the final result
+   unchanged; and that following by hand does not reproduce the runner's
+   enforced checks or receipt.
+
+Every decision step appears exactly once as `Stop and ask the person to
+approve the result of`. The exact wording of every sentence is the one
+`exportSkill()` writes; the golden files are the reference.
+
+## Checks
+
+`checkSkill()` checks an exported folder, and the tests run it on every house
+factory:
+
+- `SKILL.md` has YAML frontmatter with only the Agent Skills fields (`name`,
+  `description`, `license`, `compatibility`, `metadata`, `allowed-tools`);
+- `name` follows the naming rule and matches the folder name;
+- `description` is 1 to 1,024 characters and says when to use the skill;
+- every `metadata` value is a string, and the `factoryhub-*` keys hold the
+  id, version, source address and SHA-256;
+- the body has the five sections;
+- the folder holds only `SKILL.md` and `factory/`, `factory/` is a valid
+  factory, and its hash equals `metadata.factoryhub-sha256`;
+- the body asks the person to approve exactly as many times as the flow has
+  decision steps.
+
+CI also runs the Agent Skills reference validator (`skills-ref`) on the
+exports of every house factory.
+
+## Using an export
+
+Copy the folder into a skills directory: `~/.claude/skills/` for Claude Code,
+`~/.agents/skills/` or `<workspace>/skills/` for OpenClaw,
+`~/.hermes/skills/` for Hermes Agent. See
+[`docs/integrations.md`](../docs/integrations.md) for which of these were
+exercised.