Team files
Save a team or a group as a file, open it in another Sculptured, and edit it with completion in your editor.
A team file is a whole team in one MADL file: its agents and their Jobs, groups, arrows, workflow and settings. MADL is an open format, so other tools can read the same file. Use it to keep a copy, send a team to a colleague, move it to another Sculptured, or keep it in a Git repository next to the code it works on.
There are three kinds of file:
| File | Holds | Made with | Opened with |
|---|---|---|---|
Team file, .madl.yaml | A whole team | Export team file under Export in the team's Settings | New project → Advanced: import a team file or a past run → Import |
Group file, .group.json | One reusable group | Export on a group in Reusable groups | Import group file in Reusable groups |
Run file, .sculptured-session.jsonl | One past run: the team as it started, then every event | Download run in Results › History | New project → Advanced: import a team file or a past run → Import a past run |
flowchart LR
T["Team on the board"] -- "Export team file" --> F[".madl.yaml"]
F -- "Import" --> T2["New team in any Sculptured"]
G["Group in Reusable groups"] -- "Export" --> GF[".group.json"]
GF -- "Import group file" --> G2["Group, reviewed then saved"]
GF -- "Publish" --> C["Community"]
R["A finished run"] -- "Download run" --> RF[".sculptured-session.jsonl"]
RF -- "Import a past run" --> H["Read-only run in History"]
Export a team
- Open the teamOpen the project.
- Open SettingsOpen its Settings tab and find Export.
- Choose about foldersLeave Include folders (paths on this computer) off to share the file. Folders are paths on one computer, so they rarely make sense anywhere else. Turn it on to keep a backup for the same computer.
- ExportChoose Export team file. The file goes to your downloads as
<team>.madl.yaml.
The same section has View as spec, which shows the team as text without saving a file.
Import a team
- Start a new projectOpen New project.
- Open AdvancedOpen Advanced: import a team file or a past run at the bottom of the page.
- Choose the fileChoose the file, or paste its contents into the box. A MADL file (
.madl.yamlor.madl.json), an older.sculptured-team.jsonfile and an OpenRig YAML file are all accepted. - ImportChoose Import. A new team is created, with a new id made from its name.
- Fix what the board listsSet a folder and fix anything listed under things to fix before you start the team.
What import does with a file:
- Refused only when the file does not hold together: not valid MADL, or broken ids and arrows. The message names the field and the problem, and nothing is created.
- Imported with warnings for anything the board would also flag, such as a Claude agent without a folder. Those only stop the team from starting, so you can fix them on the board.
- Kept: agent, group and arrow ids; Jobs; positions; the workflow; and the team's settings (permissions, own copies, question timeout). A file written by another tool may hold things Sculptured can't use; they are listed under Not imported. See MADL files.
- Not kept: which computer runs the team. You choose that after import.
Importing the same file twice makes two teams. Retrying a request that did not answer does not.
Export and import a group
A group is a reusable part of a team, such as a builder and a reviewer. Groups live in Library → Reusable groups.
- Export: choose Export on the group's card. The file is named
<group>.group.json. - Import: choose Import group file and pick the file. The group opens for review before it is saved. Files over 500 KB are refused.
Group files are cleaned on export and on import, the same way Community cleans a block before publishing. Folders, model choices and the workflow's Input are removed. Every agent is set to Restricted and to start a fresh session. See Community.
Edit a team file by hand
A team file is YAML you can read and edit. Its JSON form (.madl.json) starts with a $schema line naming MADL's JSON Schema, so editors that understand JSON Schema check the file and complete field names as you type; VS Code does this with no setup. For YAML, the YAML extension reads the same schema.
The madl command checks a file before you import it:
cargo install --git https://github.com/Sculptured/Multi-Agent-Descriptor-Language madl-cli
madl validate my-team.madl.yaml
Every field is described in MADL's specification; MADL files lists where each part of a Sculptured team goes.
Keep a team in Git
A team file without folders is the same on every computer, so it fits in a repository:
- Export the team without folders.
- Commit the file, for example as
team/review-loop.madl.yaml. - Review changes to Jobs in pull requests like any other text.
- To use a new version, import it as a new project. Import never overwrites a team you already have.
Share a past run
A run file lets someone see exactly what happened in a run without running anything. It holds the team as it started and every recorded event in order.
- Open the run in History and choose Download run.
- Send the
.sculptured-session.jsonlfile. - The other person imports it with Import a past run. It opens in History, read-only, labelled as imported from a file.