Atelier

Atelier

Build the smallest durable surface that keeps the human reviewing while agents work. The surface adapts to the task; the protocol remains stable. `` is the directory containing this file. Consult [CONTEXT.md](CONTEXT.md) only when a capitalized Atelier term is unclear.

Entry gate

Use Atelier when the human and agent must interact during the session or review state must survive the browser or session boundary. Use chat, a markdown checklist, or a static shape probe when one human can finish in one pass without an agent wake loop or durable state.

Complete when: Atelier is selected for a live or durable review, or the lighter artifact has been delivered and this skill exits.

1. Discover the review

1. Inspect the material before designing the surface. Enumerate every Review Unit by stable key,

source anchor, affected target, required human action, and completion effect. One Review Unit is one human intent or judgment even when it changes several slides, files, scenes, or sections. When a Review Unit is a decision, read and satisfy the [Decision Dossier](references/components.md#decision-dossier) contract.

1. Read [references/protocol.md#capability-manifest](references/protocol.md#capability-manifest) and

[references/operation-models.md](references/operation-models.md). Declare every capability dimension independently and record the reason for each value.

1. Read [references/patterns.md#composition-guide](references/patterns.md#composition-guide).

Select one of the five primary composition shapes over one content-and-state model:

• choose the default mode: free exploration or guided action;
• choose only the useful altitudes: map, claims, explanation, evidence, raw source;
• choose only the useful lenses: story, dependency, risk, evidence coverage;
• use the Decision Dossier's dependency neighborhood when decisions have causal edges;
• add another mode, altitude, or lens only when it answers a distinct human question.

1. Ask no question when the material determines the shape. Otherwise ask one to four questions,

starting with: What is the minimum successful outcome of this session? When the human is unavailable, record the best-supported answer as a reversible assumption on the surface, including what would overturn it and a normal action for correcting it.

1. Show a Surface Proposal on the human channel: recommend the capability manifest, primary

composition, context strategy, dependency representation, primary human path, and final-action effect with reasons. Name one materially different alternative only when it changes the human workflow, makes rebuilding expensive, or responds to a rejected surface.

1. For a new or materially uncertain shape, show an ASCII tracer sketch immediately after the

proposal. Use real labels and one representative Review Unit; show location or sequence, decision-specific context, its dependency neighborhood and consequences, current state, actions, Next, and active parallel work when relevant. Keep the sketch to 20 lines or fewer. Treat it as an intent probe rather than a layout specification. Record a skip reason when resuming an accepted surface or reusing an established composition. Use a thin HTML tracer only when density, responsiveness, or interaction behavior remains uncertain.

1. Pause every new or materially changed shape for explicit human approval or revision. While the

shape is pending, continue only discovery work. Record the accepted proposal and tracer, then begin brief finalization, Surface Integrator dispatch, and implementation. Treat silence, continued tool use, and the Coordinator's recommendation as pending. A resumed surface proceeds from its recorded approval and exact accepted shape; a material shape change reopens this gate.

Complete when: every source item maps to a Review Unit or shared context; every decision passes the Decision Dossier completeness test; typed causal dependencies and affected targets are accounted for; every capability value, the primary shape, minimum outcome, assumptions, and completion effect are explicit; and the proposal and tracer have an explicit human approval or a valid prior-approval record.

2. Write the Surface Brief

Build the conflict graph and schedule conflict-free independent sets exactly as defined in [references/operation-models.md](references/operation-models.md#conflict-graph-and-ownership-lanes). Parallel nodes may share a connected graph as long as no active conflict edge joins them. Persist the resulting ownership lanes and integration boundary in the brief.

Keep the human-facing Decision Graph distinct from the execution Conflict Graph. The Decision Graph explains causal judgment relationships; the Conflict Graph schedules safe agent ownership. They may share Review Unit keys while carrying different edges.

Persist a compact brief with this required core:

• outcome: what the human must understand or complete;
• reviewUnits: stable keys, labels, source anchors, a decisionDossier for each decision, typed

causal dependencies, and affectedTargets[];

• decisionGraph: typed edges with a plain-language cause and the upstream constraint,

conflict, unlock, supersession, reopen, or downstream consequence they represent;

• actions: every human action typed with its exact effect;
• sharedContext: synthesized material needed by several units, stated once and referenced from

each affected Decision Dossier;

• surfaceShape: the Surface Proposal, context and dependency strategy, ASCII tracer or skip

reason, primary human path, and the human approval with the exact accepted shape;

• capabilities: the exact manifest from

[references/protocol.md#capability-manifest](references/protocol.md#capability-manifest);

• ownership: conflict-free lanes and the integration boundary;
• constraints: language, safety limits, and final-action effect.

Add stateModel, explanationPacket, and modules only when the task earns them. Use [references/state-model.md](references/state-model.md) as the single source for deciding whether a persisted manifest is required and for validating it.

Complete when: the brief accounts for every discovered unit, context bundle, dependency, and action; every parallel lane has non-overlapping ownership; the shape has explicit approval; the capability manifest is valid; and the Integrator can build a decision-complete surface without the authoring conversation or hidden source reconstruction.

3. Form the control tower

1. Keep one Coordinator on the human channel and event stream. The Coordinator acknowledges work,

maintains task truth, assigns ownership, resolves conflicts, and integrates outcomes; it stays available while workers run.

1. Load the scheduled conflict graph from the brief. Recompute it before dispatch when a new event,

dependency, affected target, or write scope changes ownership.

1. Start or reuse one Surface Integrator using

[agents/atelier-builder.md](agents/atelier-builder.md) with the persisted brief. The Integrator owns the surface files, store, protocol wiring, and rendered evidence. Dispatch only after the shape-approval completion criterion in Discover the review passes.

1. When the brief includes agent-owned source or interpretation work, fill available

capacity with bounded Review Workers using [agents/atelier-review-worker.md](agents/atelier-review-worker.md). Give each worker disjoint stable keys and sources. Route new same-lane feedback to the active worker; create another lane only for independent ownership. Decision-only adjudication creates no execution workers; change events it records may start conflict-free execution lanes.

1. Add a Domain Explainer using [agents/atelier-explainer.md](agents/atelier-explainer.md) when the

human must understand a dense artifact before judging it. Parallel evidence or lens work may feed one synthesized Explanation Packet.

1. Run deterministic builds, renders, hashing, and mechanical checks through scripts or worker

pools. Agents launch and observe those drivers; reasoning agents own interpretation and edits.

Complete when: every active agent-owned unit has exactly one write owner, every conflict edge is serialized, every independent ready agent-owned lane is dispatched up to available capacity, decision-only units name their current human actor, and the Coordinator remains free to receive events.

4. Build and integrate

1. The Surface Integrator reads [references/components.md](references/components.md) and

[references/patterns.md](references/patterns.md), selects only task-earned modules, and implements the shared shell from the brief.

1. Review Workers return packets by stable key as soon as a lane is ready. The Integrator accepts

packets incrementally; independent lanes do not wait at a batch barrier.

1. Keep one canonical content-and-state model. Render every typed action distinctly and follow the

action-verification contract in [references/components.md](references/components.md#action-verification-manifest).

1. Write visible prose per [write-for-humans](../write-for-humans/SKILL.md). Preserve exact

authoritative wording as quoted source material.

1. Persist the brief, store, target registry, drafts, decisions, work state, and event history as

the Surface Record.

Complete when: the surface URL is live; every brief unit is rendered or explicitly pending in an owned lane; browser updates are live; only selected capabilities and modules appear; candidate actions obey readiness; actions persist as declared; and the Integrator returns the URL, store, manifests, changed files, checks, and rendered evidence.

5. Arm and gate

1. Realize the declared agentWake capability exactly as defined in

[references/protocol.md#how-the-poll-wakes-the-agent](references/protocol.md#how-the-poll-wakes-the-agent). Bind one poller to the exact URL only for monitor-stream or exit-to-wake; for manual, render and verify the wake tracer and run no agent poller. Browser live updates remain mandatory in all three cases.

1. The Surface Integrator runs the pre-handback checks defined in

[agents/atelier-builder.md](agents/atelier-builder.md).

1. The Coordinator runs the canonical gate once. Pass --poller-identity for

an automatic wake capability and omit it for manual: /scripts/atelierctl --url gate [--poller-identity ] --evidence-dir .review/preflight [--state-model ].

1. Inspect desktop and narrow evidence for comprehension. The primary Review Unit, current state,

Decision Dossier, next human action, and final effect must be obvious. Apply the Decision Dossier completeness test to the rendered surface.

1. Apply [write-for-humans](../write-for-humans/SKILL.md#independent-review-gate)'s independent

review gate when its context pointer fires, and resolve every blocking finding.

Complete when: the canonical capability gate passes against the current surface, rendered evidence is understandable at both widths, required independent review has no blocking finding, and the declared wake path is proven against the exact URL or the manual tracer is visible and current.

6. Operate the review loop

1. Receive events through the one dispatcher and acknowledge human work immediately.
2. For direct cadence, dispatch a unit as soon as it is actionable. For staged, persist

queued items and wait for the explicit flush boundary, then cluster and dispatch the complete wave. Read [references/feedback.md](references/feedback.md) for feedback placement and [references/protocol.md](references/protocol.md) for event handling.

1. Recompute the conflict graph for each wave. Dispatch independent lanes in parallel and merge

same-owner feedback into the active lane. Keep target state, latest worker update, and derived Next synchronized without hiding task truth inside comments.

1. Let the human continue reviewing while earlier lanes run whenever the selected model permits it.

Completed packets return to their exact targets immediately rather than waiting for the wave.

1. For live-source work, verify each returned unit with the selected screenshot, reload, or local

check. For rendered artifacts, combine parallel source changes through the deterministic draft driver, run one verifier per ready wave, and reserve expensive full gates for explicit sign-off.

1. Close or reopen each unit from its recorded action effect and canonical Revision Set. Final

completion derives from task state and the explicit approved candidate/Revision Set.

Complete when: every received event is acknowledged, owned, and reflected at its target; every finished lane is integrated and verified; unresolved or waiting work remains visible; and the final action settles exactly the intended Review Units.

Invariants

• stable Review Unit keys and complete affected-target sets;
• complete Decision Dossiers for every decision;
• one event dispatcher with parallel ownership lanes;
• one write owner per target or shared file at a time;
• typed actions with explicit, bounded effects and correction routes;
• one canonical capability manifest shared by brief, runtime, and gate;
• mandatory browser live updates with deterministic continuity recovery;
• server-backed truth, draft recovery, canonical Revision Sets, and no silent data loss;
• deterministic mechanics in scripts and judgment in agents;
• modules absent unless selected by the brief;
• candidate actions disabled until capability-specific readiness passes;
• disposable test state isolated from the live surface's root, store, origin, and process;
• accessible controls, responsive layout, dismissal, and focus restoration;
• localhost binding by default, explicit URL/store identity, and a proven automatic poller or

visible manual wake tracer;

• rendered desktop and narrow verification before human involvement.

Resume

For state:durable, read the Surface Record, current files, and in-flight ownership lanes. Run atelierctl resume, verify the exact URL and declared wake capability, then restore unfinished lanes by stable key and apply the browser continuity fallbacks. An ephemeral surface starts a new record instead of claiming cross-session recovery.

Complete when: no durable event, draft, decision, revision, or in-flight ownership assignment is lost across the session boundary.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: tschuehly
• Source: tschuehly/skill-incubator
• License: MIT

Install and usage instructions live in the source repository linked above.