Table of Contents

πŸ‡«πŸ‡· Version franΓ§aise

Forge a team from a need

You do not want to build an agent team β€” you want to solve a concrete problem. The Atelier (orkeon forge) is the guided path between the two: you describe the problem in plain words, an assistant turns it into a team, the team is tried in a sandbox on your own example, and the result is judged against the acceptance criteria you stated β€” not against a vague "is it good?".

Brief ──▢ Blueprint ──▢ Render ──▢ Validate ──▢ Test ──▢ Diagnose ──▢ Verdict
              β–²                        β”‚          β”‚                      β”‚
              └────── refine ◀─────────┴──── (validation errors) ──────── (not conforming)
                                                  β”‚                      β–Ό
                                                  └─────────────▢ Ready ──▢ Promote
                                                   (adopt without trying)

Prerequisites

A configured LLM. If you have not done it yet:

orkeon init          # the 5-choice wizard (ollama, openai, custom…)
orkeon doctor        # sanity-check the installation

The forge refuses to open the interview without a model (FORGE-LLM-UNAVAILABLE) β€” it would only echo your words back.

The cycle, end to end

orkeon forge "summarize my supplier's new offers every morning"
  1. The interview. The assistant asks only what your need leaves unsaid β€” what comes in, what comes out and in which shape β€” one short question at a time, and never how often the work runs (scheduling is settled at promotion). A need that already says it all goes through with no question at all; "I don't know" is always a valid answer. It captures a structured brief: goal, inputs, expected output, constraints, acceptance criteria (what "done, correctly" means, in your words), and a sample input for the try.
  2. The folders. Between the brief and the plan, the forge proposes the team's folders: the ones your need names β€” Β« …PDFs in /inpdf, the Markdown in /outmd Β» gives /inpdf read and /outmd written β€” or, when it names none, /workspace to read (only when something comes in) and /output to write. The terminal takes the proposal as it is and prints it; a client that drives the forge can show it as a step where you rename a folder, bind it to a real one or keep it inside the team, then confirm. From then on that list is the team's folders: the plan delivers into them, the try mounts them, the promoted team carries them. A folder bound to a real one outside your working directory is read by a try that a forge resume runs β€” the way a client that confirms the folders does it, in a --dry run first: the process that tries a team can only read the directories it started with, so a run about to try the team in the same process refuses that folder at the confirmation (a recoverable FORGE-FOLDERS-INVALID) and says how. When a folder is kept inside the team, the forge then waits for you to drop its files in β€” Enter in the terminal, folders.filled on the event channel; --auto does not wait β€” and reads what each one holds into the brief, so the plan is made for those files. When the folder is an inbox whose contents change from run to run, say so in your need (Β« whatever documents are dropped in /documents Β»): the assistant marks the folder (examples), the files you drop are then examples of what will come, and the plan names none of them.
  3. The proposal. From the brief, the assistant plans a team: who does what, in which order, with which tools β€” drawn from the real tool catalogue only; it cannot invent one. The plan is rendered as ordinary crew files and validated mechanically (unknown tools, unassigned tasks, dependency cycles, and a task or agent that names a file under a deliverable folder without depending on the task that writes it β€” an existing file under an output folder counts as written; see orkeon forge). Validation errors go back to the assistant for repair β€” twice, then they surface to you. A text deliverable that one of the agents able to run its task cannot write (no writing tool of its own or granted by the task) is rendered source: final_message (the framework saves the agent's final answer there); a binary one (.docx, .xlsx…) needs its format's writer tool, or the plan fails validation.
  4. The try. The crew runs in a sandbox, in-process, on your sample input, with the confirmed folders mounted and nothing else of yours: each output folder lands in the session's own directory (folders/<name>, snapshotted into runs/<n>/folders/<name> after each run), an input folder reads the real folder you bound behind it β€” else --read, else the workspace for /workspace, else the session's folders/<name>, which moves into the team at adoption β€” and /forge holds the session's working files; shell_command/code_interpreter and the eleven drive_* tools are removed from the catalogue outright (a try has no drive to read). The confinement is the session directory. A try runs without memory, whatever the plan's memory: says: it stores nothing and recalls nothing, so the promoted team never recalls a trial's output as one of its earlier runs β€” its memory starts with its first real run. A task that ends without writing its declared file is flagged deliverableMissing on its task.completed, and the try's run.finished counts it in missingDeliverables. A task whose agent ended on its iteration cap carries endedOnIterationCap on its task.completed, and run.finished counts it in cappedTasks.
  5. The verdict. A judge grades the output against your acceptance criteria, one by one, and states findings and concrete suggestions. A missed must criterion blocks regardless of the score. If no judge can run, the verdict says so (judge: deterministic) β€” it never invents a βœ”.
  6. Your call. Interactive mode arbitrates every verdict, conforming ones included: accept (a conforming crew becomes ready; accepting a non-conforming one is your judgement on sight), re-run the trial as-is (retry β€” zero compose tokens, one budget iteration), refine (the diagnosis is fed back into the plan, verbatim), hand back an edited plan (edit), or stop. --auto arbitrates alone, within the budget.

Adoption itself is not a one-way door: forge resume of a promoted session reopens it at the arbitration (the stored verdict is re-announced), and a second forge promote to the same destination β€” or to that folder moved or renamed since β€” updates the folder in place β€” generated files regenerated, your own files preserved. Any other non-empty destination stays refused, a copy of the folder included. And the session is not a prerequisite either: forge reopen <team-folder> finds the session the folder is linked to by the id its forge.json carries, or rebuilds one from the folder's own crew/ (and that forge.json) when the original is gone β€” or when the folder is a copy, which then gets a session of its own β€” landing at the --dry pause: an imported, orphaned or duplicated team can be amended, tried and re-adopted onto the same folder, not only relaunched.

Everything is bounded: 3 iterations by default (--max-iterations), optional token and wall-time ceilings (--max-tokens, --max-seconds). An exhausted budget stops the cycle cleanly; resuming may raise it β€” consumption always carries over.

The session on disk

Each cycle lives under .orkeon/forge/<slug>/ in your working directory:

.orkeon/forge/supplier-watch/
β”œβ”€β”€ session.json          id, state, status, budget β€” the resume point
β”œβ”€β”€ brief.json            what you asked, criteria included
β”œβ”€β”€ folders.json          the folders you confirmed, with the real folder behind each
β”œβ”€β”€ folders/<name>/       a folder kept inside the team until adoption; each try's outputs
β”œβ”€β”€ blueprint.json        the team plan (single source of both renders)
β”œβ”€β”€ repair.json           the validation errors a repair must address, while one is pending
β”œβ”€β”€ crew/                 the rendered crew β€” what actually runs
β”œβ”€β”€ runs/<n>/             each try: output, metrics, verdict, deliverables (folders/<name>/)
β”œβ”€β”€ transcript.jsonl      the conversation
└── history.jsonl         every state transition
orkeon forge list                      # what is in progress, what is ready
orkeon forge resume supplier-watch     # pick up exactly where it stopped
orkeon forge "..." --dry               # generate and validate only β€” never execute
orkeon forge resume supplier-watch --edit --dry   # amend the plan at the pause, re-render, pause again
orkeon forge resume supplier-watch --adopt        # keep the team as generated, without a trial

At the --dry pause you can amend the plan before ever trying it: resume --edit reads the amended blueprint from the channel, validates it in full, re-renders deterministically β€” zero LLM tokens, same iteration β€” and with --dry pauses again at the same boundary.

The same pause takes a second answer: resume --adopt keeps the team as generated and goes straight to Ready β€” offline, no run directory, zero tokens. What it skips is the evidence a trial produces, never a check: the crew is rendered and validated at that pause, and promotion never consumed a trial artefact β€” FORGE.md simply says « no verdict was recordedΒ Β».

Two formats, one generation

The assistant never writes YAML or TypeScript β€” it produces one schema-validated plan, and a deterministic renderer derives the files. --format yaml (default) renders the per-entity YAML layout; --format script renders an editable crew.ork.ts β€” the scripted equivalent of the same crew, a starting point for your own edits, not conditional logic. The script path needs esbuild; without it, a new session falls back to YAML and says so (FORGE-ESBUILD-MISSING).

Both renders converge on the same validator, and the try loads the crew from the rendered files β€” what was written is what runs.

Adopt it

orkeon forge promote supplier-watch --to ~/solutions/supplier-watch \
    --name "Supplier watch" --schedule daily@07:30

--name is the team's name: it titles the card, the record and the session. Once the folder is written, the session follows the team β€” its folder under .orkeon/forge/ takes the destination folder's name (-2 when another session already has it), so forge list shows it under the team it made.

The promoted folder is ordinary β€” nothing about it is proprietary to the forge:

  • crew/ β€” the team, as tried;
  • one folder per confirmed folder (inpdf/, outmd/; /workspace reads input/) β€” created at promotion, holding whatever the session kept for it, so the first launch has somewhere to read and write;
  • run.sh / run.cmd β€” launch scripts that cd into the folder, carry the mounts binding those folders (--mount "$DIR/outmd":/outmd:rw) and have your sample inputs pre-filled (adapt them to the real run);
  • FORGE.md β€” the crew's identity card: goal, acceptance criteria, verdict, generation date and version β€” what a colleague reads when picking up the folder;
  • forge.json β€” the card's machine-readable twin: the session's id, slug, title, format, promotion instant and the brief β€” the id links the folder back to its session wherever the folder goes, and the rest is what forge reopen reads to rebuild a faithful session once the original is gone (nothing secret in it);
  • schedule/ (with --schedule) β€” a Windows task XML, a systemd timer, a cron line, all named after the team folder (orkeon-supplier-watch.timer). The promotion installs none of them: orkeon forge schedule ~/solutions/supplier-watch registers the one your system uses, and notes what it registered in schedule/installed.json (--check says where it stands, orkeon forge unschedule removes it). Orkeon has no scheduler of its own β€” the operating system runs the team β€” so it promises no supervision it cannot give.

Run it with its own launcher β€” ~/solutions/supplier-watch/run.sh. A bare orkeon run ~/solutions/supplier-watch/crew also launches it: the promoted config.yaml names the folders the team uses (mounts: [/inpdf, /outmd]), so a settings entry declaring /outmd is used as it stands, and with none the run is refused in one line (the crew requires '/outmd' … pass --mount <folder>:/outmd:rw) instead of writing nowhere.

Other options

Option Applies to What it does
--read <dir> a new session, forge resume The folder the trial reads behind the first input folder no real folder was bound to (/workspace by default), in place of the working directory β€” point a trial at the documents the team is meant to read; the sessions stay under the working directory.
--reference <id> a new session Composes the team from a use case of the catalogue (orkeon usecases list): its crew's structure is the assistant's model, and the session, forge.json and FORGE.md record it.
--lang <code> a new session, forge resume The language the assistant converses in and names the team in (fr, en, es, de, zh; English by default) β€” until you write in another language or ask for one.
--settings <path> a new session, forge resume The settings file, with the same semantics as orkeon run --settings.
--with-settings forge promote Copies the resolved settings file into the promoted folder. Off by default: a settings file usually holds API keys and the folder is made to be shared β€” without the copy, the launch scripts reference the file in place.
--events jsonl every verb The versioned event protocol on stdout, the answers on stdin β€” how an external client drives the forge.
--pack <dir> a new session, forge resume A folder whose files override the embedded assistant pack.

orkeon forge rename <team-folder> --name "<new name>" renames a promoted team β€” every title, the folder itself, the linked session's folder and an installed schedule β€” all of it or nothing.

Honest limits

  • The quality of the proposal tracks the model you configured; the brief's criteria and the mechanical validation are the guardrails, not a substitute.
  • The sandbox restricts by removing tools from the catalogue, not by hoping the model abstains; network tools reach the plan only if your brief asked for them.
  • Mail is tried, never sent: the twelve mailbox tools are offered, and every try runs them on a fictitious trial mailbox; the sends, drafts and changes it would have made are shown under the verdict and nothing reaches a real mailbox (Forged crews).
  • One session, one problem: the Atelier generates and validates a team β€” it is not a visual crew editor.