How it works

How one change moves through Artyfact: from a description of the product to code running in production, and back again.

People decide what changes. Agents build it, each in a private fork. Artyfact checks the work against the model and refuses anything stale. Open a phase to see who acts, what they run and what keeps the change safe.

Drawn from Artyfact’s own model.

The site’s build reads the repository’s genome/ with the same loader the platform uses, and draws this diagram from one journey in it. Every id you see is a real node in that model. This page is one too: page.how-it-works.

10 phases, 17 steps, 76 linked model nodes and 10 guardrails, read when the site was built.

From idea to production.

Take a product from a described model through an agreed change, parallel agent work, checks, one review, promotion and deployment, then watch what happens and decide the next change.

Carry a change from idea to production: 10 phases, from J.lifecycle in Artyfact’s model.

PersonYou, or whoever coordinates the work.
AgentThe coding agent you run on your own machine.
PlatformThe Artyfact Worker and its Durable Object.
CIThe artyfact-ci Workflow, building in a container.

Describe the productA person uploads the product's model as an ontology package.Person
What happens
Person
A person uploads the product's model as an ontology package. The platform validates it and shows a preview to review; nothing is saved yet.
Person
A person accepts the reviewed preview by its hash. The package becomes the System's first Genome, the model of what the product should be.
Who acts
Person You, or whoever coordinates the work.
Command or screen
artyfact ontology preview --system <system-id> --file <native-package.json>
artyfact ontology accept <import-id> --system <system-id> --hash <preview-hash>
Screen Overview /s/:systemId/r/:rev/overview
API POST /api/systems/:id/ontology-imports/preview
API POST /api/systems/:id/ontology-imports/:reviewId/accept
Guardrails
An imported package becomes the System's model only when a person accepts the preview they reviewed, identified by its hash.
In the model
Step J.lifecycle/import
Command command.ontology-preview
Endpoint endpoint.ontology-packages-post-ontology-imports-preview
Module module.platform.ontology-packages
Step J.lifecycle/accept-import
Command command.ontology-accept
Screen screen.overview
Endpoint endpoint.ontology-packages-post-ontology-imports-reviewId-accept
Commitment commitment.reviewed-import
Agree the changeA person describes a change in plain words.Person
What happens
Person
A person describes a change in plain words. The platform finds the model nodes it touches and proposes edits, or asks a question back.
Person
A person reviews the proposal from its purpose down to each node and accepts the edits to keep. The accepted change, an Evolution, edits only the model.
Who acts
Person You, or whoever coordinates the work.
Command or screen
artyfact evolution propose --system <system-id> --file <intent.json>
Screen Work /s/:systemId/r/:rev/work
API POST /api/systems/:id/intents
API POST /api/systems/:id/intents/:pid/accept
API POST /api/systems/:id/evolutions/:eid/accept
Guardrails
Accepting a change edits only the Genome; code changes reach the System later, through a plan, its Tasks and a separate promotion.
In the model
Step J.lifecycle/propose
Command command.evolution-propose
Screen screen.work
Endpoint endpoint.intents-create
Journey J.describe-change
Step J.lifecycle/accept-change
Endpoint endpoint.intents-accept
Endpoint endpoint.accept-evolution
Commitment commitment.genome-first
Plan the workArtyfact drafts a plan from the accepted change.PlatformPerson
What happens
Platform
Artyfact drafts a plan from the accepted change. Each Task names the model nodes and paths it may write, what it depends on and its checks. Tasks that write the same nodes go to later waves.
Person
A person saves the plan, pinned to the accepted model version, and lists which Task can be claimed next. A draft saves nothing on its own.
Who acts
Platform The Artyfact Worker and its Durable Object.
Person You, or whoever coordinates the work.
Command or screen
artyfact plan draft --system <system-id> --evolution <evolution-id> [--create]
artyfact plan tasks <plan-id> --system <system-id>
Screen Work /s/:systemId/r/:rev/work
API POST /api/systems/:id/realization-plans/draft
API POST /api/systems/:id/realization-plans
Guardrails
Tasks that write the same model nodes are put in later waves, and a Task cannot be claimed until the Tasks it depends on have a selected candidate.
In the model
Step J.lifecycle/draft-plan
Command command.plan-draft
Endpoint endpoint.plan-draft
Module module.platform.lifecycle
Commitment commitment.waves-avoid-overlap
Step J.lifecycle/save-plan
Command command.plan-tasks
Screen screen.work
Endpoint endpoint.lifecycle-post-realization-plans
The work fans out for each Task, in parallel. Each Task gets its own fork, its own brief and its own agent, so several agents work at once without touching each other’s files.
1. Work in parallelonce per TaskA person claims a Task.PersonAgent
  What happens
  Person
  A person claims a Task. The platform gives it a private fork and a write token for that fork only; the CLI clones it and writes the brief, TASK_PACKET.md and AGENTS.md, cut from the model.
  Agent
  The agent works on the Task in its own fork, with any harness and model, and records checkpoints along the way.
  Agent
  The agent commits, pushes to the fork and submits that exact commit as a candidate, one submitted version of the Task's work.
  Who acts
  Person You, or whoever coordinates the work.
  Agent The coding agent you run on your own machine.
  Command or screen
  artyfact task claim <plan-id> <task-id> --system <system-id> --dir <dir>
  artyfact task checkpoint "<message>"
  artyfact task submit
  API POST /api/systems/:id/realization-plans/:pid/tasks/:tid/claim
  API POST /api/systems/:id/realization-plans/:pid/tasks/:tid/checkpoint
  API POST /api/systems/:id/realization-plans/:pid/tasks/:tid/submit
  Guardrails
  Tokens and secrets are never printed, logged or put on a command line, and are sent only to a platform that identified itself.
  Each Task works in its own fork with a write token for that fork alone, valid for 15 minutes by default and 60 at most; a candidate that changes paths outside its Task's scope is refused.
  Tasks that write the same model nodes are put in later waves, and a Task cannot be claimed until the Tasks it depends on have a selected candidate.
  In the model
  Step J.lifecycle/claim
  Command command.task-claim
  Endpoint endpoint.lifecycle-post-realization-plans-pid-tasks-tid-claim
  Module module.platform.lifecycle
  Module module.platform.packets
  Commitment commitment.credentials-stay-local
  Commitment commitment.task-fork-scope
  Commitment commitment.waves-avoid-overlap
  Step J.lifecycle/work
  Command command.task-checkpoint
  Endpoint endpoint.lifecycle-post-realization-plans-pid-tasks-tid-checkpoint
  Step J.lifecycle/submit
  Command command.task-submit
  Endpoint endpoint.lifecycle-post-realization-plans-pid-tasks-tid-submit
  Module module.platform.hooks
  Journey J.realize
2. Check each candidateonce per TaskArtyfact refuses a candidate that changes files outside its Task, then runs the checks bound to the criteria it affects.PlatformCI
  What happens
  Platform
  Artyfact refuses a candidate that changes files outside its Task, then runs the checks bound to the criteria it affects. Deterministic hooks cover files, diffs, model rules and health; System One judgments cover what needs judgment, including visual criteria judged from screenshots of the preview, never from text alone; an agent's own screenshot can fail a check but not pass it without a platform capture.
  CI
  CI builds the candidate in a container and deploys a preview, then reports the build back to the platform.
  When you run Artyfact on your own Cloudflare account, S1_PROVIDER picks the judge: Cloudflare Clef on Workers AI, TypeSafe’s Jev or OpenRouter. Visual criteria always need Clef. It judges screenshots of the candidate’s CI preview, captured with Cloudflare Browser Run at 1280×800 and 390×844, and up to four the agent attaches with artyfact task submit --screenshot page.png. Agent screenshots are unverified: they can fail a check but never pass it without a platform capture. Clef returns a probability: 0.9 or above passes, 0.1 or below fails with a named concern, and anything between stays unknown. In one local run, Clef scored the desktop and mobile captures of artyfact.ing/model 0.83 against its visual criterion, so the check stayed unknown, not a pass. The hosted demo calls no model: its judgments are simulated and labelled so.
  Who acts
  Platform The Artyfact Worker and its Durable Object.
  CI The artyfact-ci Workflow, building in a container.
  Command or screen
  Screen Evaluations /s/:systemId/r/:rev/evaluations
  CI Workflow ArtyfactCI
  API POST /api/systems/:id/candidates/:cid/evaluate
  API GET /api/systems/:id/evaluations
  API POST /api/systems/:id/builds
  Guardrails
  Only a pass verdict is drawn as success; unknown, stale and waived never are, and unknown blocks promotion.
  Judgments and proposals from a fake provider are labelled as such wherever they are shown.
  In the model
  Step J.lifecycle/check
  Screen screen.evaluations
  Endpoint endpoint.evaluate
  Endpoint endpoint.evaluations
  Module module.platform.hooks
  Commitment commitment.evidence-before-green
  Commitment commitment.labelled-fake
  Step J.lifecycle/preview
  Endpoint endpoint.report-build
  Workflow workflow.artyfact-ci
  Module module.platform.deployments
  Module module.ci.workflow
The work joins again once every Task has a candidate. One candidate per Task goes forward to a single review.
Combine and reviewA person picks one candidate for each Task, with its checks and any overlap with other Tasks in view.PersonPlatform
What happens
Person
A person picks one candidate for each Task, with its checks and any overlap with other Tasks in view.
Platform
Artyfact combines the selected results in one integration fork, runs the checks again on the combined commit and opens one review.
Who acts
Person You, or whoever coordinates the work.
Platform The Artyfact Worker and its Durable Object.
Command or screen
artyfact task select <plan-id> <task-id> --system <system-id> --candidate <candidate-id>
artyfact plan integrate <plan-id> --system <system-id>
Screen Review /s/:systemId/r/:rev/review
API POST /api/systems/:id/realization-plans/:pid/tasks/:tid/select
API POST /api/systems/:id/realization-plans/:pid/integrate
API GET /api/systems/:id/realization-plans/:pid/review
Guardrails
Only a pass verdict is drawn as success; unknown, stale and waived never are, and unknown blocks promotion.
Nothing is integrated until every Task has a selected candidate; the selected results are combined and checked again as one reviewed result.
In the model
Step J.lifecycle/select
Command command.task-select
Screen screen.review
Endpoint endpoint.lifecycle-post-realization-plans-pid-tasks-tid-select
Module module.platform.lifecycle
Step J.lifecycle/integrate
Command command.plan-integrate
Endpoint endpoint.lifecycle-post-realization-plans-pid-integrate
Endpoint endpoint.lifecycle-get-realization-plans-pid-review
Commitment commitment.evidence-before-green
Commitment commitment.one-review
PromoteA person promotes the reviewed result with the expected head, a rationale and the exact candidate ids.Person
What happens
Person
A person promotes the reviewed result with the expected head, a rationale and the exact candidate ids. The System's current state moves only if nothing changed since the review.
Who acts
Person You, or whoever coordinates the work.
Command or screen
artyfact plan promote <plan-id> --system <system-id> --file <promotion.json>
Screen Review /s/:systemId/r/:rev/review
API POST /api/systems/:id/realization-plans/:pid/promote
Guardrails
Promotion is a compare-and-swap on the System head: a candidate built on an old head is refused with 409 stale-base.
Only a pass verdict is drawn as success; unknown, stale and waived never are, and unknown blocks promotion.
In the model
Step J.lifecycle/promote
Command command.plan-promote
Screen screen.review
Endpoint endpoint.lifecycle-post-realization-plans-pid-promote
Module module.platform.lifecycle
Module module.platform.promotion
Journey J.promote
Commitment commitment.cas-promotion
Commitment commitment.evidence-before-green
DeployCI builds the promoted commit in a container and deploys it to production, recording the deployment against the System commit it runs.CI
What happens
CI
CI builds the promoted commit in a container and deploys it to production, recording the deployment against the System commit it runs.
Who acts
CI The artyfact-ci Workflow, building in a container.
Command or screen
Screen Deployments /s/:systemId/r/:rev/phenome
CI Workflow ArtyfactCI
API POST /api/systems/:id/deployments
Guardrails
Runtime events are accepted only with a credential such as a deployment's ingest token; each is validated and linked to the deployment and commit that sent it, and a deployment alone is not counted as an outcome.
In the model
Step J.lifecycle/deploy
Screen screen.phenome
Endpoint endpoint.create-deployment
Workflow workflow.artyfact-ci
Module module.platform.deployments
Module module.ci.workflow
Commitment commitment.attributed-events
ObserveArtyfact receives the events the running app reports, validates each one and links it to the deployment and commit that sent it.Platform
What happens
Platform
Artyfact receives the events the running app reports, validates each one and links it to the deployment and commit that sent it.
Who acts
Platform The Artyfact Worker and its Durable Object.
Command or screen
Screen Deployments /s/:systemId/r/:rev/phenome
API POST /api/systems/:id/deployments/:did/ingest-token
API POST /api/systems/:id/phenome/events
Guardrails
Runtime events are accepted only with a credential such as a deployment's ingest token; each is validated and linked to the deployment and commit that sent it, and a deployment alone is not counted as an outcome.
In the model
Step J.lifecycle/observe
Screen screen.phenome
Endpoint endpoint.ingest-token
Endpoint endpoint.ingest-events
Module module.platform.deployments
Module module.platform.phenome
Commitment commitment.attributed-events
ReviseA person reads what happened against the claims the product makes and describes the next change, so the model and the product move together.Person
What happens
Person
A person reads what happened against the claims the product makes and describes the next change, so the model and the product move together.
Who acts
Person You, or whoever coordinates the work.
Command or screen
Screen Theory /s/:systemId/r/:rev/theory
Guardrails
A person decides here. Nothing changes until they act.
In the model
Step J.lifecycle/revise
Screen screen.theory

Then around again, for the next change: 2. Agree the change

Try it with your own agent.

The agent guide walks through each command on this page. The theory explains why the model comes first.

Bring your agent Read the theory