The factory as files

A factory lives in CodeBook, not in a repository. That is what lets you change it from a screen, and what lets every run be stamped with the exact version of the factory it ran under.

But a factory should not be something you can only see through this app. You can export any factory as plain files, read them, diff them, try the agents in another tool, keep the zip as a snapshot — and upload it back to make the factory match.

Both are in the workflow menu (⋮, top right of a factory) under Factory as files.

What is in the zip

vibeforce/
  factory.yaml               how work moves, and the list of agents
  agents/
    sarah/SKILL.md           one folder per agent: the instructions it runs on
    alex/SKILL.md
    maya/SKILL.md
    harper/SKILL.md
  README.md                  what is here, for whoever opens the zip

• factory.yaml contains the supported workflow definition: stations and their instructions, routes, gate counting rules, the factory's and each station's model policy, contracts, evaluators, workflow managers, policy and budgets, memory, expected tool connections and runtimes, merge and incident settings, and scorers.
• agents/<folder>/SKILL.md is one agent's instructions — the system prompt it works under at every station it staffs. The folder name says which agent.

Evidence-bound memory is omitted with a count and explanation. Restores preserve those live notes. Portable memory keeps its normal scope; a factory file is not a backup of private source or run evidence. See memory revisions.

What is never in it

People (who approves, who is asked), credentials and tokens, cards, and run history. Tool connections and runtimes are named so you know what the factory needs; their secrets are never included.

This is not a complete environment backup. A worker's own model policy, pinned knowledge revisions, tool grants, runtime bindings and the complete dependency history of composed skills are not captured by the current definition. Importing a zip does not reproduce an old runtime or every setting; check current limits.

Gate settings and older files

Gate stations carry gate_settings with rule, min_passes, pass_wording and fail_wording. Rules are all, majority, at least a chosen number, or any passing branch. JSON definitions export as format 3; ZIP bundles remain version 1 and declare definition_format: codebook.factory 3.

Format 1 definitions remain readable, with a warning that gate counting was not recorded. A new installation uses defaults for those gates; a restore preserves current settings on surviving gates and reports incomplete historical coverage. Formats 2 and 3 require explicit counting settings for every gate.

Model policies and older files

Format 3 adds model_policy to the factory and to every station. null means no policy of its own: the scope inherits the wider choice. Otherwise it is the policy as the Models editor saves it — fixed, fallback chain or automatic — naming models the way SSO lists them, never a key. Format 3 requires the key on every scope. A worker's own policy is not part of the file.

Formats 1 and 2 did not record model policies, so their model coverage is unknown. A pinned policy in such a file is refused; a null key is ignored. Restoring one keeps the current policy on factories and stations that survive, new stations inherit, and the result is never reported as an exact restore.

Applying a file to an organization that lacks a model the file names leaves that factory or station without a policy of its own and lists it under missing models in the report. Another model is never substituted.

Where review is required, the gate editor's Send gate change for review creates a normal change request. Editing the draft removes its approval; publication keeps independent live changes when its typed edits still apply. Gate changes affect the workflow and cannot be applied to a share of runs as a canary. Gate and policy pack installation and removal can also be sent through review; settings and the installation receipt change together at publication. See reviewed station packs.

Export

⋮ → Export factory (.zip) downloads the factory as it is now.

Use it to keep a snapshot before a big change, to review a factory in a pull request of your own, to hand a factory to another workspace, or to try an agent somewhere else.

Trying an agent outside CodeBook

Nothing in the zip needs CodeBook to be read.

1. Give a model the agent's SKILL.md as its system prompt.
2. Add the station's instructions from factory.yaml — a station narrows what its agent does there.
3. Give it a card: a title, a description and acceptance criteria.

Update a factory from a file

⋮ → Update factory from a file, then choose a zip.

1. You see the changes first. Nothing is applied until you have read them: which agents get new instructions, which are added, and every change to the factory in a sentence.
2. Apply to this factory updates an unreviewed target within its workspace rules. Where approval is required, Send for review creates a change request and leaves the live factory unchanged.

What to know:

• Supported definition changes create a factory version. Factory settings → Versions restores that definition. Agent instructions and operational side settings have separate histories and are not restored by this rollback.
• Cards and run history are not touched. A station that holds cards and is no longer in the file is kept, unstaffed, rather than removed.
• An agent belongs to the workspace. New instructions for an agent apply at every factory in the workspace that uses it. What it ran on before is kept as a version of the agent, in its studio.
• A folder for an agent the workspace does not have adds it: installed from the marketplace when marketplace names one, otherwise made as the workspace's own.
• Custom managers and routing candidates travel by name. Workspace-created agents retain their assignments without needing a marketplace slug.
• Names are how a file points at things. A workflow or station is matched to the live one by its name. Rename one in the file and it is, honestly, a new one.
• A setting the file leaves out is left alone. Remove merge, incidents, story_dependencies or scorers from the file and the factory keeps what it has.
• If the factory changed while you were reading the preview, the upload is refused and you look again.
• Only factory.yaml, README.md and agents/<folder>/SKILL.md are read. Anything else in the zip is ignored. The zip can be up to 4 MB.

Create a factory from the zip

In the factory picker or Agent marketplace → Factories, choose Import from a file. The importer accepts the exported zip as well as a supported factory definition file. Inspect the preview, name the destination factory, and install it under the normal factory review rules.

Where another person’s approval is required, a supported definition edit opens a change request in Changes. The author cannot approve it. Keep agent instructions, merge settings, incident routing, story dependencies and scorers unchanged: the current review snapshot cannot preserve changes to those parts, so a file changing them is refused in full. The dialog names each unsupported change.

Agents are shared by the workspace. If any factory environment stage there requires approval, a file cannot change or reactivate an existing workspace agent through a different, unreviewed factory. Unchanged agents and new unrelated agents remain usable in an unreviewed target.

The zip carries agent instructions and scorers along with the factory definition. Missing agents can be installed or created. When the import updates an existing installed agent, the result names it: that agent belongs to the workspace, so the new instructions affect other factories that use it too. Earlier instructions are retained as an agent version.

Factory rollback restores the supported definition. Agent instruction versions are separate, and operational side settings are not restored by factory rollback. A ZIP is not a complete environment backup.

Repositories, credentials, runners and tool connections still need usable bindings in the destination. Use its setup checklist and run a representative task before treating the import as ready.

factory.yaml

format: codebook.factory.bundle     # always this
version: 1                          # the format's version
exported_at: 2026-10-05T17:03:56.674Z
fingerprint: 940250496485b448bf6a1de5d2f156c1e5f61171   # of covered definition values; check historical coverage warnings too
definition_format: codebook.factory 3

agents:
  - folder: alex                    # the folder under agents/. Lowercase letters, digits and dashes.
    name: Alex
    specialty: Senior React Engineer
    marketplace: alex               # its name in the marketplace, or null for an agent of your own
    skill: agents/alex/SKILL.md

factory:
  name: Vibeforce
  model_policy: null                # null = inherit the organization default; or { mode: fixed | fallback | auto, ... }
  policy:                           # null means no limit
    max_tokens_per_card: null
    max_tokens_per_day: null
    max_runs_per_card: null
    max_concurrent_runs: null
    allow_repository_write: 1       # 1 on, 0 off
    pull_requests_need_approval: 0
    allow_tool_connections: 1
    allow_external_runtimes: 1
    allow_handoffs: 1
    risk_routing: 0
    risk_approval_from: null        # low | medium | high | critical
  memory: []                        # [{ title, body }] notes every agent of the factory is given
  integrations: []                  # [{ catalog_key, label }] tool connections it expects — named, never their secrets
  workflows:
    - position: 0
      name: Software delivery
      memory: []
      supervisor:                   # the workflow's manager
        enabled: 1
        agent_slug: harper
        agent_name: Harper
        max_interventions: 3
        instructions: ""
      stations:
        - position: 2               # stations refer to each other by position
          title: Development
          color: "#6366f1"
          outcome: null             # done | dropped on a station where finished work rests
          model_policy:             # null = inherit the factory's policy
            mode: fallback
            models: [model-a, model-b]  # names as your organization's SSO lists them
          worker_type: ai           # ai | approval | human | external | gate | crew | factory
          agent: { slug: alex, name: Alex, specialty: Senior React Engineer }
          runtime: null             # { kind, label } for an outside runtime
          instructions: Build the story. Open a draft pull request.
          on_create: 0              # start when a card is created here
          on_move: 1                # start when a card arrives here
          max_retries: 3
          allow_repository_write: 1
          allow_mcp: 0
          pass: 3                   # the station a card goes to on pass, by position — or null
          fail: null
          blocked: null
          gate: null
          autonomy: null            # observe | suggest | approve | low_risk | full
          sla_minutes: null
          routing_mode: fixed
          routing_objective: quality    # quality | cost | speed | balanced
          routing_max_tokens: null
          routing_by_category: 0
          candidates: []            # [{ agent_slug, agent_name, runtime_kind, runtime_label, role, category }]
          branches: []              # positions of stations every card also opens in parallel
          risk_branches: []         # [{ station, risk_level }]
          routes: []                # [{ kind, label, mode, target_workflow, target_station, return_station, risk_level }]
          contract: []              # [{ direction: requires | produces, requirement_kind, artifact_kind, field_key, label }]
          evaluator_rule: all       # all | majority | any
          evaluators: []            # [{ kind: agent | checks | rules | human_sample, label, agent_slug, agent_name, criteria, required, sample_percent }]
          crew: null
          intake: null

merge:                              # who merges finished work
  who: codebook                     # codebook | person
  person_from_risk: 71              # a person merges from this risk score up; empty = CodeBook merges whatever passes
  protected_paths: ["migrations/**", "src/auth/**"]
  required_commands: [test]         # runner commands that must pass before a merge
  deploy_verify_commands: [smoke]   # runner commands that verify a deploy

incidents:                          # what a production incident does; empty = it opens no card
  open_cards_at: { workflow: Software delivery, station: Development }
  from_severity: high               # critical | high | medium | low
  investigate_first: true
  active: true

story_dependencies:
  mode: off                         # off | enforce
  author_station: null              # { workflow, station }
  intake_station: null

scorers:
  - name: Redundant tests
    preset: redundant_tests         # which ready-made scorer it is, or null for one of your own
    question: Did this run add tests that duplicate coverage that already existed, or several tests that check the same thing?
    best: Every added test covers something not covered before.
    worst: Most added tests repeat existing coverage.
    applies_to: { workflow: Software delivery, station: Development }   # or null for every station
    sample_percent: 20
    pass_score: 4
    observe_after: 20
    active: true

Rules the file must follow

Part	Rule
format, version	codebook.factory.bundle and 1.
agents[].folder	Lowercase letters, digits and dashes, up to 60 characters; unique in the file.
agents/<folder>/SKILL.md	Must exist and not be empty for every agent listed, up to 100,000 characters. A folder that is not listed is refused.
factory	Checked by the same rules as a blueprint: up to 12 workflows and 40 stations each; pass, fail, blocked and gate must be positions of stations in the same workflow.
merge.who	codebook or person. person_from_risk is 1 to 100, or empty.
incidents.open_cards_at	A station of this factory, as { workflow, station }.
scorers[]	A name and a question; scorers are matched by name.

A file that breaks a rule is refused with a sentence saying which, and nothing is changed.

How this differs from defining a factory in a repository

Some tools define the factory as files in a repository and treat those files as the source of truth. CodeBook does not: the factory you see is the factory that runs, changed by people with the right to change it, versioned on every change. Files are a way in and out — a snapshot you can read, test and bring back — not a second place the factory lives.