Atelier Setup

Set up repository guidance that Atelier skills need without taking ownership of the developer's installation, harness configuration, or project structure. Explore first, present every proposed edit exactly, and write only after the developer approves it.

1. Explore

Read the repository before proposing any change:

• Root AGENTS.md and CLAUDE.md, if present. Note whether either already has an ## Agent skills

heading.

• Root CONTEXT.md and CONTEXT-MAP.md.
• docs/adr/ and any context-local docs/adr/ directories.
• docs/agents/, including existing issue-tracker.md and domain.md.
• Existing issue-tracker conventions: remotes, issue links in documentation, local issue

directories, and project guidance.

• Genuine monorepo signals: a workspace manifest, or multiple independently deployable packages

with their own source directories.

Do not create, install, configure, or modify anything during exploration.

2. Present Findings

Summarize what exists and recommend a domain-document layout:

• Single-context is the default: domain language belongs in root CONTEXT.md; architectural

decisions belong in root docs/adr/.

• Multi-context is appropriate only when the repository has genuinely separate bounded

contexts. CONTEXT-MAP.md belongs at the root and points to each context's CONTEXT.md and docs/adr/ directory.

Explain that domain documents remain lazy: do not create CONTEXT.md, CONTEXT-MAP.md, or an ADR directory until another Atelier skill has resolved terminology or made a decision worth recording.

Select or confirm the issue tracker:

1. If docs/agents/issue-tracker.md already defines one, preserve it unless the developer asks to

change it.

1. Otherwise recommend the tracker indicated by existing repository practice, then ask the

developer to confirm or describe their tracker.

1. Accept GitHub, GitLab, local Markdown, another tracker described by the developer, or none.
2. Record the chosen workflow in docs/agents/issue-tracker.md; do not install, initialize, or

create external tracker resources.

Select the instruction file to edit:

1. If both files exist, ask which file should own the agent guidance; do not duplicate it.
2. Otherwise use root AGENTS.md when it exists.
3. Otherwise use root CLAUDE.md when it exists.
4. If neither exists, ask which instruction file to create; do not choose on the developer's behalf.

Show the developer the selected file, domain layout, and exact contents for:

• the ## Agent skills block;
• docs/agents/issue-tracker.md using references/issue-tracker.md;
• docs/agents/domain.md using references/domain.md.

Stop and wait for explicit approval.

3. Write After Approval

Add the following block to the selected instruction file:

## Agent skills

### Planning and implementation

Use `atelier-orchestrator` at the start of development work. It selects an Inline Plan for bounded
changes or a Spec-backed Plan when durable design and coordination artifacts are warranted.

### Issue tracking

Read `docs/agents/issue-tracker.md` when issue tracking is relevant. It defines this repository's
tracker workflow; `plan.json` remains authoritative for Spec-backed task details and dependencies.

### Domain documentation

Read `docs/agents/domain.md` before working in a domain area. It defines how to locate and use this
repository's context documents and ADRs.

If an ## Agent skills section already exists, update the ### Planning and implementation, ### Issue tracking, and ### Domain documentation subsections in place rather than appending duplicates. Preserve other subsections and all content outside the section, including user edits.

Create docs/agents/ when needed, then write the approved tracker and domain documents. Do not create any other files or directories.

4. Report

State which instruction file and agent documents changed, the selected tracker, and the chosen domain-document layout. Remind the developer that the layout is a convention only: the first domain-modelling or architectural-decision task creates the relevant documents when it has substantive content.