Atelier

Atelier is a starter for research with coding agents. Keep the question, experiment, results, and conclusion linked in one Git repository. Agent work records give people a short summary and the next agent enough context to continue.

This is an early release; the file conventions are still being tested.

Browse the demo.

What gets created

create-atelier is needed only to create a project or resume its creation walkthrough. After that, the project carries its own skills, file contracts, and lint helper under .agents/skills/. Read those files or ask your coding agent to use them. The generator is not a runtime dependency.

Specs define valid files, skills guide the work, and the lint skill checks the record. The optional browser reader displays it. You can run the example without a coding agent.

Try it

Requires Python 3.11+, uv, and Git. Create a project:

uvx create-atelier my-research --no-setup
cd my-research
uv sync
git add .
git commit -m "Initialize research project"
uv run --locked python experiments/exp-001/analyze.py
uv run python -c "import polars as pl; print(pl.read_parquet('experiments/exp-001/summary.parquet'))"

The example estimates a mean from synthetic observations. Inspect experiments/exp-001/summary.parquet for how error changes with sample size. The source revision and inputs are in experiments/exp-001/provenance.json. This demonstrates the workflow; it makes no claim about real-world systems.

For the optional figure, install Node.js 22+ and run npm install && npm run figure inside my-research. Open figures/cache/mean.svg.

Omit --no-setup for a walkthrough that offers dependency installation, optional figure tools, Hugging Face storage, and a first commit and push. Remote repositories default to private; creation and upload require confirmation. Local work needs no remote account. Resume with uvx create-atelier --resume .. See the generated project's README for setup details.

Work inside the generated project

Start with docs/design.md: replace the example question with your hypothesis and tasks. Use your editor or coding agent to change the experiment configuration and analysis in experiments/exp-001/. Commit the inputs, run the experiment, inspect its results, and link the evidence when proposing a conclusion in the design document.

The generated AGENTS.md points to the project skills: task coordination, writing, code review, figures, and lint. For substantial work, keep agents/work/<task>.md current: a TL;DR at the top, followed by an append-only log of inputs, attempts, results, decisions, and next steps. Optional branch refs and commit hashes link the work to its code changes. See work records.

The files remain usable without the generator or a particular frontend. Markdown holds documents; YAML holds configuration and discussions; Parquet holds tables. Each experiment records its inputs and source revision to help another person or agent reproduce it. See the file conventions when adapting the example.

Update an existing project

The generator refuses an existing destination. To adopt newer skills, generate a separate temporary project, compare its .agents/skills/ with yours, and commit the changes you choose. Preserve local conventions and work records. There is no automatic upgrade or requirement to update old projects.

Read and review

The browser reader opens an Atelier stored on Hugging Face. It shows documents, agent work, experiments, and figures without running repository code. The separate frontend package also reads local working trees and builds a static site.

Use the generated atelier-lint skill to check a project:

cd /path/to/research
uv run .agents/skills/atelier-lint/scripts/lint.py . --programmatic

Omit --programmatic to add agent reviews of writing, code design, and figures. The script declares its dependencies for uv. Full review requires an authenticated Codex or Claude Code CLI and sends review content through that CLI to its model provider. These checks inspect the record; they do not establish that a scientific conclusion is true. Lint neither runs the experiment nor applies fixes. See lint coverage and reports.

Develop Atelier

From a source checkout:

uv run python -m unittest discover -s tests
uv build

In src/create_atelier/, cli.py generates projects, setup.py handles the creation walkthrough, and template/ holds copied files. The atelier-lint skill inside that template owns its references/ contracts and scripts/ checks. The independent frontend/ package has its own instructions and tests. Read the shared development plan before claiming work.

Licensed under Apache-2.0. Generated projects include the license and attribution; vendored libraries retain their own licenses.