atelier

name	atelier
description	Create and operate a durable, task-shaped HTML surface when a human needs to understand, inspect, edit, annotate, compare, decide, approve, or triage generated material with an agent. Use for visual review loops, decision sessions, media review, structured editors, reports, plans, batches, and other work that is clearer in an interactive surface than chat.

Atelier

Build the smallest surface that makes the human's real task clear. The protocol is reusable; the visible interface is not a template. Use the canonical terms in CONTEXT.md.

<skill-dir> is the directory containing this file.

Coordinator workflow

1. Identify the human task before choosing UI:
   • the primary review unit, such as a thread, fact, scene, finding, option, or document;
   • what the human must understand and the actions they must take;
   • the lightest useful feedback anchors;
   • what the final action triggers.
2. Define the task state before choosing navigation. Read references/state-model.md. When a Review Unit can change actor, receive feedback, be revised, block work, be decided, or reopen, create a task-specific state model with events, guards, effects, terminal/reopen behavior, and a human-attention projection. Persist it and run node <skill-dir>/scripts/validate-state-model.mjs <model.json>. Comments are conversation attached to transitions; they are never the sole source of task state.
3. Choose the smallest agent topology that the task earns. Read references/agent-topology.md. Always retain one Coordinator and normally one Surface Builder. Add a Domain Explainer only when the human must understand a dense or unfamiliar artifact, and an Evidence Specialist only for a substantial bounded source task. Do not spawn agents for visible modules.
4. When interpretation is delegated, give one Domain Explainer agents/atelier-explainer.md a compact Interpretation Brief. It returns an Explanation Packet with stable design anchors, explanations, and human-authority questions. Validate its semantics before sending the packet onward. Keep this collaborator off the direct human channel.
5. Choose a composition and only the modules the task earns. Read references/components.md, then references/patterns.md. Read references/feedback.md when feedback is needed and references/protocol.md when operating or extending the protocol. Do not add navigation, a worklist, revisions, comments, queues, activity, notifications, filters, or diagrams merely because the seed supports them.
6. Write a compact Surface Brief with:
   • outcome: what the human must understand or complete;
   • reviewUnits: stable task keys, labels, and source anchors;
   • actions: task actions and their exact effects;
   • stateModel: stateful entities, current states, transitions, attention priority, and the persisted model path, or an explicit static justification;
   • agentTopology: selected collaborators and the bounded reason for each;
   • explanationPacket: target-anchored explanations and questions when one exists;
   • modules: selected modules and why each is useful;
   • evidence: paths, media, or facts;
   • language and task constraints. Cards and Sections are optional presentation choices, not required brief fields.
7. Spawn one Surface Builder with agents/atelier-builder.md and the brief. Do not prescribe layout or pass the full conversation. Reuse that builder for presentation changes. The builder owns representation; the Domain Explainer owns delegated interpretation; the Coordinator owns intent, conflicts, and event interpretation. Send each collaborator only compact deltas anchored by stable task keys.
8. Receive the URL, store name, persisted brief, state-model path and validation result, selected-module manifest, target/revision manifest where applicable, changed files, and rendered evidence. Operate the ready surface with <skill-dir>/scripts/atelierctl --url <url>. Never edit its store directly.
9. Bind the wake path to the exact surface URL. Run <skill-dir>/scripts/wake-plan.sh claude|codex|manual <poller-path> <url> and follow its output. A copied poller without an explicit URL is invalid.
10. Run the module-aware gate before involving the human: <skill-dir>/scripts/atelierctl --url <url> gate --poller-identity <unique-poller-path> --evidence-dir .review/preflight. Add --state-model <model-path> for every stateful surface so the same gate verifies the persisted model. Inspect the desktop and narrow evidence for comprehension, not just layout. Confirm that the primary review unit, next action, and final effect are obvious. Replace any module that adds more orientation cost than value.

For stateful tasks, confirm that target state is visible without opening comments, the latest meaningful agent update is summarized at its target, and one derived Next action lands on the highest-priority human-actionable control. An overview may supplement this guidance but cannot be the only way to discover work.

For explained designs, review the design itself rather than a detached grill. Place each question at its stable design target. Prefer an inline question or expandable disclosure; use a focused layer when comparison or deeper inspection benefits from staying over the design. Never convert the Explanation Packet into a second questionnaire page.

Feedback loop

• On sent, acknowledge, start, and complete the comment with atelierctl comment ....
• When comment handling changes whose turn it is, transition the task target too. Show agent acknowledgement, work, and implementation state at the target; keep the full thread layered.
• Treat flush and its preceding sent events as one staged feedback wave.
• On decision, treat custom as authoritative and choiceIndex as route provenance.
• On explain-request, post a decision-relevant explanation with atelierctl explain.
• On comment-rejected, use the required follow-up, rework, and return the comment to implemented.
• On command, use action and data as the task-specific action contract.
• Use proposal reopen when a human asks to reconsider a recorded decision; do not rewrite the store.

Invariants

Keep these strict even when the interface shape changes:

• stable task keys for durable feedback and actions;
• a validated task state model for multi-state work, with one durable current state per modeled entity and no hidden task truth confined to comments or notifications;
• server-backed truth with draft recovery and no silent data loss;
• explicit, bounded action effects and no accidental outward publication;
• accessible controls, responsive layout, dismissal, and focus restoration;
• localhost binding by default and an explicit URL/store/poller identity per live surface;
• rendered desktop and narrow verification.

Everything else is compositional. The seed in assets/seed.html is a module-capable reference client, not a required application shell.

Continuity

Persist the brief, store, target registry, and event log as the Surface Record. After a session boundary, a replacement builder reads that record and resumes. Run atelierctl resume, verify the exact URL and one uniquely named poller, then continue.