@martinffx/atelier 3.0.1 → 3.0.2

package/CHANGELOG.md

@@ -4,6 +4,13 @@
 
 - **breaking:** rename the `recon` agent to `sentinel`. Existing Atelier configuration is migrated automatically and legacy generated files are removed during the next command.
 
+## [3.0.2](https://github.com/martinffx/atelier/compare/v3.0.1...v3.0.2) (2026-08-01)
+
+
+### Bug Fixes
+
+* **opencode:** synchronize user-invocable skill commands ([b373120](https://github.com/martinffx/atelier/commit/b37312040ed80cfdab78139f39c8e5150696b763))
+
 ## [3.0.1](https://github.com/martinffx/atelier/compare/v3.0.0...v3.0.1) (2026-07-31)
 
 

package/README.md

@@ -11,6 +11,10 @@ npx skills add martinffx/atelier
 npx @martinffx/atelier@latest init --harness <claude|opencode|codex|cursor>
 ```
 
+For OpenCode, installing skills first also creates slash commands for every installed skill
+marked `user-invocable: true`. If you initialize first, run `npx @martinffx/atelier@latest update --harness opencode`
+after installing skills.
+
 ## How Atelier works
 
 Atelier uses as much process as each request needs. Bounded work gets a concise plan in the conversation. Substantial work gets a durable spec, an implementation plan, and tracked execution. The developer approves the plan before implementation begins.

package/dist/atelier.js

@@ -25433,7 +25433,7 @@ var {
 } = import__.default;
 
 // src/commands/init.ts
-import { join as join3 } from "path";
+import { join as join4 } from "path";
 import { homedir as homedir3 } from "os";
 
 // node_modules/@inquirer/core/dist/esm/lib/key.js
@@ -32042,6 +32042,12 @@ class HarnessConfigError extends AtelierError {
     super(`Failed to parse ${file}: ${cause}`, "HARNESS_CONFIG_ERROR", 1);
   }
 }
+class SkillDiscoveryError extends AtelierError {
+  constructor(path2, cause) {
+    super(`Failed to read skills from ${path2}: ${cause}`, "SKILL_DISCOVERY_ERROR", 1);
+  }
+}
+
 class InvalidConfigError extends AtelierError {
   constructor(cause, { suggestReinit = false } = {}) {
     const suffix = suggestReinit ? ` Run \`atelier init --harness <${Harness.join("|")}>\` to reconfigure.` : "";
@@ -32183,6 +32189,13 @@ function writeConfig(config, path2 = CONFIG_PATH) {
   writeFileSync2(path2, JSON.stringify(config, null, 2) + `
 `);
 }
+function toSharedConfig(config) {
+  return {
+    version: config.version,
+    skills_source: config.skills_source,
+    skills_path: config.skills_path
+  };
+}
 function getConfiguredHarnesses(config) {
   return Harness.filter((harness) => config[harness] !== undefined);
 }
@@ -32205,7 +32218,7 @@ function getDefaultConfig(harness) {
 
 // src/services/paths.ts
 import { homedir as homedir2 } from "os";
-import { join as join2 } from "path";
+import { isAbsolute, join as join2, resolve } from "path";
 function shortPath(p) {
   const home = homedir2();
   if (p === home || p.startsWith(home + "/")) {
@@ -32216,6 +32229,15 @@ function shortPath(p) {
 function getGlobalOpencodeDir() {
   return join2(homedir2(), ".config", "opencode");
 }
+function resolveSkillsPath(skillsPath) {
+  if (skillsPath === "~") {
+    return homedir2();
+  }
+  if (skillsPath.startsWith("~/")) {
+    return join2(homedir2(), skillsPath.slice(2));
+  }
+  return isAbsolute(skillsPath) ? skillsPath : resolve(skillsPath);
+}
 function resolveBasePath(harness) {
   return harness === "opencode" ? getGlobalOpencodeDir() : homedir2();
 }
@@ -32305,7 +32327,7 @@ async function promptForOpenCodeModels(prompt2, section, models, provider) {
   };
 }
 function formatFileList(files) {
-  return files.map((f) => `  ${f.exists ? "~" : "+"} ${f.path}`).join(`
+  return files.map((f) => `  ${f.action === "delete" ? "-" : f.exists ? "~" : "+"} ${f.path}`).join(`
 `);
 }
 function guardProvider(provider) {
@@ -32315,6 +32337,67 @@ function guardProvider(provider) {
   return provider;
 }
 
+// src/utils/templates.ts
+var import_gray_matter = __toESM(require_gray_matter(), 1);
+import { readFileSync as readFileSync3, existsSync as existsSync2, readdirSync, lstatSync, statSync } from "fs";
+import { join as join3, dirname as dirname2 } from "path";
+import { fileURLToPath } from "url";
+var __dirname2 = dirname2(fileURLToPath(import.meta.url));
+var AGENTS_DIR = existsSync2(join3(__dirname2, "..", "agents")) ? join3(__dirname2, "..", "agents") : join3(__dirname2, "..", "..", "agents");
+var MAX_SKILL_FILE_SIZE = 1024 * 1024;
+function readTemplate(name) {
+  const filePath = join3(AGENTS_DIR, `${name}.md`);
+  const raw = readFileSync3(filePath, "utf-8");
+  const { data, content } = import_gray_matter.default(raw);
+  return {
+    name: data.name,
+    description: data.description,
+    body: content.trim()
+  };
+}
+function readUserInvocableSkills(skillsPath) {
+  let entries;
+  try {
+    entries = readdirSync(skillsPath, { withFileTypes: true });
+  } catch (err2) {
+    if (err2.code === "ENOENT") {
+      return { skills: [], warnings: [] };
+    }
+    throw new SkillDiscoveryError(skillsPath, err2 instanceof Error ? err2.message : String(err2));
+  }
+  const warnings = [];
+  const skills = entries.flatMap((entry) => {
+    const skillDir = join3(skillsPath, entry.name);
+    try {
+      if (!entry.isDirectory() && !(entry.isSymbolicLink() && statSync(skillDir).isDirectory())) {
+        return [];
+      }
+      const skillPath = join3(skillDir, "SKILL.md");
+      if (!existsSync2(skillPath)) {
+        return [];
+      }
+      const stat = lstatSync(skillPath);
+      if (!stat.isFile() || stat.size > MAX_SKILL_FILE_SIZE) {
+        warnings.push(`Skipped ${skillPath}: expected a regular SKILL.md no larger than ${MAX_SKILL_FILE_SIZE} bytes.`);
+        return [];
+      }
+      const { data } = import_gray_matter.default(readFileSync3(skillPath, "utf-8"));
+      if (data["user-invocable"] !== true) {
+        return [];
+      }
+      if (typeof data.name !== "string" || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(data.name) || typeof data.description !== "string") {
+        warnings.push(`Skipped ${skillPath}: invalid user-invocable skill metadata.`);
+        return [];
+      }
+      return [{ name: data.name, description: data.description }];
+    } catch (err2) {
+      warnings.push(`Skipped ${skillDir}: ${err2 instanceof Error ? err2.message : String(err2)}`);
+      return [];
+    }
+  }).sort((a, b) => a.name.localeCompare(b.name));
+  return { skills: [...new Map(skills.map((skill) => [skill.name, skill])).values()], warnings };
+}
+
 // src/commands/init.ts
 async function init(options2) {
   const harnessOption = options2.harness;
@@ -32338,7 +32421,7 @@ async function init(options2) {
     ]);
     harness = answer.harness;
   }
-  const configPath = join3(homedir3(), CONFIG_FILE);
+  const configPath = join4(homedir3(), CONFIG_FILE);
   const configResult = readConfig(configPath);
   if (!configResult.ok) {
     if (configResult.error.type !== "not-found") {
@@ -32357,7 +32440,7 @@ async function init(options2) {
   validateConfig(config);
   const harnessBasePath = resolveBasePath(harness);
   if (!options2.yes) {
-    const files = adapter.fileList(harnessBasePath);
+    const files = adapter.fileList(harnessBasePath, toSharedConfig(config));
     console.log(`
 Files to write:`);
     console.log(formatFileList(files));
@@ -32373,7 +32456,7 @@ Files to write:`);
     }
   }
   adapter.mergeHarnessConfig(section, harnessBasePath);
-  adapter.installAgents(section, harnessBasePath);
+  adapter.installAgents(section, harnessBasePath, toSharedConfig(config));
   writeConfig(config, configPath);
   console.log(`
 Atelier initialized for ${harness}.`);
@@ -32383,10 +32466,13 @@ Next step:`);
     console.log("  opencode auth login --provider openai  # connect your OpenAI account");
   }
   console.log("  npx skills add martinffx/atelier  # install skills");
+  if (harness === "opencode" && readUserInvocableSkills(resolveSkillsPath(config.skills_path)).skills.length === 0) {
+    console.log("  npx @martinffx/atelier@latest update --harness opencode  # create commands after installing skills");
+  }
 }
 
 // src/commands/update.ts
-import { join as join4 } from "path";
+import { join as join5 } from "path";
 import { homedir as homedir4 } from "os";
 
 // src/commands/utils.ts
@@ -32418,7 +32504,7 @@ async function resolveHarness(config, harnessOption, command) {
 
 // src/commands/update.ts
 async function update(options2) {
-  const configPath = join4(homedir4(), CONFIG_FILE);
+  const configPath = join5(homedir4(), CONFIG_FILE);
   const configResult = readConfig(configPath);
   if (!configResult.ok) {
     if (configResult.error.type === "not-found") {
@@ -32435,7 +32521,7 @@ async function update(options2) {
   const adapter = getAdapter(harness);
   const section = await promptForSection(adapter, existingSection);
   const harnessBasePath = resolveBasePath(harness);
-  const files = adapter.fileList(harnessBasePath);
+  const files = adapter.fileList(harnessBasePath, toSharedConfig(config));
   console.log(`
 Files to write:`);
   console.log(formatFileList(files));
@@ -32452,17 +32538,17 @@ Files to write:`);
   config[harness] = section;
   validateConfig(config);
   adapter.mergeHarnessConfig(section, harnessBasePath);
-  adapter.installAgents(section, harnessBasePath);
+  adapter.installAgents(section, harnessBasePath, toSharedConfig(config));
   writeConfig(config, configPath);
   console.log(`Atelier updated for ${harness}.`);
   console.log("Skills are managed separately. Run `npx skills update martinffx/atelier` to update skills.");
 }
 
 // src/commands/remove.ts
-import { join as join5 } from "path";
+import { join as join6 } from "path";
 import { homedir as homedir5 } from "os";
 async function remove(options2) {
-  const configPath = join5(homedir5(), CONFIG_FILE);
+  const configPath = join6(homedir5(), CONFIG_FILE);
   const configResult = readConfig(configPath);
   if (!configResult.ok) {
     if (configResult.error.type === "not-found") {
@@ -32492,27 +32578,9 @@ async function remove(options2) {
 }
 
 // src/adapters/claude.ts
-import { writeFileSync as writeFileSync3, mkdirSync as mkdirSync2, readFileSync as readFileSync4, rmSync as rmSync2, rmdirSync, existsSync as existsSync3, readdirSync } from "fs";
+import { writeFileSync as writeFileSync3, mkdirSync as mkdirSync2, readFileSync as readFileSync4, rmSync as rmSync2, rmdirSync, existsSync as existsSync3, readdirSync as readdirSync2 } from "fs";
 import { join as join7 } from "path";
 
-// src/utils/templates.ts
-var import_gray_matter = __toESM(require_gray_matter(), 1);
-import { readFileSync as readFileSync3, existsSync as existsSync2 } from "fs";
-import { join as join6, dirname as dirname2 } from "path";
-import { fileURLToPath } from "url";
-var __dirname2 = dirname2(fileURLToPath(import.meta.url));
-var AGENTS_DIR = existsSync2(join6(__dirname2, "..", "agents")) ? join6(__dirname2, "..", "agents") : join6(__dirname2, "..", "..", "agents");
-function readTemplate(name) {
-  const filePath = join6(AGENTS_DIR, `${name}.md`);
-  const raw = readFileSync3(filePath, "utf-8");
-  const { data, content } = import_gray_matter.default(raw);
-  return {
-    name: data.name,
-    description: data.description,
-    body: content.trim()
-  };
-}
-
 // src/utils/schemas.ts
 var AgentSchema = exports_external.object({
   template: exports_external.enum(AGENT_NAMES),
@@ -32643,7 +32711,7 @@ function removeDirIfEmpty(dir) {
     return;
   }
   try {
-    if (readdirSync(dir).length === 0) {
+    if (readdirSync2(dir).length === 0) {
       rmdirSync(dir);
     }
   } catch (err2) {
@@ -32692,8 +32760,8 @@ function readExistingSettings(settingsPath) {
 }
 
 // src/adapters/opencode.ts
-import { writeFileSync as writeFileSync4, mkdirSync as mkdirSync3, readFileSync as readFileSync5, existsSync as existsSync4, rmSync as rmSync3, rmdirSync as rmdirSync2, readdirSync as readdirSync2 } from "fs";
-import { join as join8 } from "path";
+import { writeFileSync as writeFileSync4, mkdirSync as mkdirSync3, readFileSync as readFileSync5, existsSync as existsSync4, rmSync as rmSync3, rmdirSync as rmdirSync2, readdirSync as readdirSync3, lstatSync as lstatSync2, realpathSync, statSync as statSync2 } from "fs";
+import { basename, join as join8 } from "path";
 var OPENCODE_PROVIDERS2 = [
   { name: "OpenCode Zen", value: "opencode-zen" },
   { name: "OpenCode Go", value: "opencode-go" },
@@ -32781,6 +32849,7 @@ var DEFAULT_MODELS2 = {
     plan: "openai/gpt-5.6-sol"
   }
 };
+var COMMAND_MARKER = "<!-- Generated by Atelier -->";
 var opencodeAdapter = {
   name: "opencode",
   providerChoices: OPENCODE_PROVIDERS2,
@@ -32817,7 +32886,7 @@ async function promptSection2(prompt2, section) {
   const models = modelsForProvider2(provider);
   return promptForOpenCodeModels(prompt2, openCodeSection, models, provider);
 }
-function installAgents2(section, basePath) {
+function installAgents2(section, basePath, sharedConfig) {
   const config = section;
   const opencodeRoot = getOpencodeRoot(basePath);
   const agentsDir = join8(opencodeRoot, "agent");
@@ -32842,6 +32911,41 @@ temperature: 0.2
     writeFileSync4(agentPath, content);
     console.log(`Created ${shortPath(agentPath)}`);
   }
+  if (sharedConfig) {
+    installCommands(opencodeRoot, sharedConfig);
+  }
+}
+function installCommands(opencodeRoot, sharedConfig) {
+  const discovery = readUserInvocableSkills(resolveSkillsPath(sharedConfig.skills_path));
+  reportSkillWarnings(discovery.warnings);
+  const commandsDir = getCommandsDir(opencodeRoot, discovery.skills.length > 0);
+  if (!commandsDir) {
+    return;
+  }
+  const desiredCommands = new Map(discovery.skills.map((skill) => [skill.name, skill]));
+  for (const path2 of managedCommandPaths(commandsDir)) {
+    if (!desiredCommands.has(basename(path2, ".md"))) {
+      rmSync3(path2, { force: true });
+      console.log(`Removed ${shortPath(path2)}`);
+    }
+  }
+  for (const skill of discovery.skills) {
+    const commandPath = join8(commandsDir, `${skill.name}.md`);
+    if (commandStatus(commandPath) === "custom") {
+      console.log(`Skipped ${shortPath(commandPath)} because it is not managed by Atelier.`);
+      continue;
+    }
+    const content = `---
+description: ${JSON.stringify(skill.description)}
+---
+${COMMAND_MARKER}
+Activate the ${skill.name} skill and follow its instructions precisely.
+
+User request: $ARGUMENTS
+`;
+    writeFileSync4(commandPath, content);
+    console.log(`Created ${shortPath(commandPath)}`);
+  }
 }
 function mergeHarnessConfig2(section, basePath) {
   const config = section;
@@ -32885,7 +32989,7 @@ function mergeHarnessConfig2(section, basePath) {
   }
   console.log(`${isNew ? "Created" : "Updated"} ${shortPath(opencodeJsonPath)}`);
 }
-function fileList2(basePath) {
+function fileList2(basePath, sharedConfig) {
   const files = [
     { path: join8(basePath, "opencode.json"), exists: existsSync4(join8(basePath, "opencode.json")) }
   ];
@@ -32894,6 +32998,27 @@ function fileList2(basePath) {
     const path2 = join8(opencodeRoot, "agent", `${name}.md`);
     files.push({ path: path2, exists: existsSync4(path2) });
   }
+  if (sharedConfig) {
+    const discovery = readUserInvocableSkills(resolveSkillsPath(sharedConfig.skills_path));
+    reportSkillWarnings(discovery.warnings);
+    const commandsDir = getCommandsDir(opencodeRoot, discovery.skills.length > 0);
+    if (!commandsDir) {
+      return files;
+    }
+    const desiredNames = new Set(discovery.skills.map((skill) => skill.name));
+    for (const path2 of managedCommandPaths(commandsDir)) {
+      if (!desiredNames.has(basename(path2, ".md"))) {
+        files.push({ path: path2, exists: true, action: "delete" });
+      }
+    }
+    for (const skill of discovery.skills) {
+      const path2 = join8(opencodeRoot, "command", `${skill.name}.md`);
+      const commandPath = join8(commandsDir, `${skill.name}.md`);
+      if (commandStatus(commandPath) !== "custom") {
+        files.push({ path: path2, exists: existsSync4(commandPath) });
+      }
+    }
+  }
   return files;
 }
 function remove3(section, basePath) {
@@ -32919,7 +33044,7 @@ function removeDirIfEmpty2(dir) {
     return;
   }
   try {
-    if (readdirSync2(dir).length === 0) {
+    if (readdirSync3(dir).length === 0) {
       rmdirSync2(dir);
     }
   } catch (err2) {
@@ -32931,9 +33056,71 @@ function removeLegacyFiles(opencodeRoot) {
   if (existsSync4(pluginPath)) {
     rmSync3(pluginPath, { force: true });
   }
+  const commandsDir = getCommandsDir(opencodeRoot, false);
+  if (!commandsDir) {
+    return;
+  }
+  for (const path2 of managedCommandPaths(commandsDir)) {
+    rmSync3(path2, { force: true });
+  }
+  if (!lstatSync2(join8(opencodeRoot, "command")).isSymbolicLink()) {
+    removeDirIfEmpty2(commandsDir);
+  }
+}
+function reportSkillWarnings(warnings) {
+  for (const warning of warnings) {
+    console.warn(warning);
+  }
+}
+function getCommandsDir(opencodeRoot, create) {
   const commandsDir = join8(opencodeRoot, "command");
-  if (existsSync4(commandsDir)) {
-    rmSync3(commandsDir, { recursive: true, force: true });
+  if (!existsSync4(commandsDir)) {
+    if (!create) {
+      return;
+    }
+    try {
+      mkdirSync3(commandsDir, { recursive: true });
+      return commandsDir;
+    } catch (err2) {
+      throw new FileWriteError(commandsDir, err2 instanceof Error ? err2.message : String(err2));
+    }
+  }
+  try {
+    const stat = lstatSync2(commandsDir);
+    if (stat.isSymbolicLink()) {
+      const target = realpathSync(commandsDir);
+      if (!statSync2(target).isDirectory()) {
+        throw new Error("symbolic link target is not a directory");
+      }
+      return target;
+    }
+    if (!stat.isDirectory()) {
+      throw new Error("path is not a directory");
+    }
+    return commandsDir;
+  } catch (err2) {
+    throw new FileWriteError(commandsDir, err2 instanceof Error ? err2.message : String(err2));
+  }
+}
+function managedCommandPaths(commandsDir) {
+  try {
+    return readdirSync3(commandsDir, { withFileTypes: true }).filter((entry) => entry.isFile() && entry.name.endsWith(".md")).map((entry) => join8(commandsDir, entry.name)).filter((path2) => readFileSync5(path2, "utf-8").includes(COMMAND_MARKER));
+  } catch (err2) {
+    throw new FileWriteError(commandsDir, err2 instanceof Error ? err2.message : String(err2));
+  }
+}
+function commandStatus(path2) {
+  try {
+    const stat = lstatSync2(path2);
+    if (stat.isSymbolicLink() || !stat.isFile()) {
+      throw new Error("command path must be a regular file");
+    }
+    return readFileSync5(path2, "utf-8").includes(COMMAND_MARKER) ? "managed" : "custom";
+  } catch (err2) {
+    if (err2.code === "ENOENT") {
+      return "missing";
+    }
+    throw new FileWriteError(path2, err2 instanceof Error ? err2.message : String(err2));
   }
 }
 function writeOrDeleteOpenCodeJson(basePath, config) {
@@ -32998,7 +33185,7 @@ function deepMerge2(target, source) {
 }
 
 // src/adapters/codex.ts
-import { writeFileSync as writeFileSync5, mkdirSync as mkdirSync4, readFileSync as readFileSync6, existsSync as existsSync5, rmSync as rmSync4, rmdirSync as rmdirSync3, readdirSync as readdirSync3 } from "fs";
+import { writeFileSync as writeFileSync5, mkdirSync as mkdirSync4, readFileSync as readFileSync6, existsSync as existsSync5, rmSync as rmSync4, rmdirSync as rmdirSync3, readdirSync as readdirSync4 } from "fs";
 import { join as join9 } from "path";
 
 // node_modules/smol-toml/dist/date.js
@@ -34216,7 +34403,7 @@ function removeDirIfEmpty3(dir) {
     return;
   }
   try {
-    if (readdirSync3(dir).length === 0) {
+    if (readdirSync4(dir).length === 0) {
       rmdirSync3(dir);
     }
   } catch (err2) {
@@ -34274,7 +34461,7 @@ function removeEmptyCodexDir(codexDir) {
     return;
   }
   try {
-    const entries = readdirSync3(codexDir);
+    const entries = readdirSync4(codexDir);
     if (entries.length === 0) {
       rmSync4(codexDir, { recursive: true, force: true });
     }
@@ -34287,7 +34474,7 @@ function isObject(value) {
 }
 
 // src/adapters/cursor.ts
-import { existsSync as existsSync6, mkdirSync as mkdirSync5, readdirSync as readdirSync4, rmSync as rmSync5, rmdirSync as rmdirSync4, writeFileSync as writeFileSync6 } from "fs";
+import { existsSync as existsSync6, mkdirSync as mkdirSync5, readdirSync as readdirSync5, rmSync as rmSync5, rmdirSync as rmdirSync4, writeFileSync as writeFileSync6 } from "fs";
 import { join as join10 } from "path";
 var CURSOR_MODELS = [
   "composer-2.5",
@@ -34378,7 +34565,7 @@ function remove5(section, basePath) {
       rmSync5(join10(agentsDir, `${agent.name}.md`), { force: true });
     }
     rmSync5(join10(agentsDir, `${LEGACY_AGENT_NAME}.md`), { force: true });
-    if (existsSync6(agentsDir) && readdirSync4(agentsDir).length === 0) {
+    if (existsSync6(agentsDir) && readdirSync5(agentsDir).length === 0) {
       rmdirSync4(agentsDir);
     }
   } catch (err2) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@martinffx/atelier",
-  "version": "3.0.1",
+  "version": "3.0.2",
   "description": "Personal development toolkit - spec-driven development, code quality, deep thinking, and ecosystem patterns",
   "type": "module",
   "bin": {

package/skills/atelier-orchestrator/SKILL.md

@@ -125,9 +125,10 @@ The workflow is not purely linear. Expect backflows:
 - Planning reveals design assumptions are wrong → back to brainstorm
 - Tasks can't be decomposed without more context → back to brainstorm
 
-### Implement → Plan (missing tasks)
-- Implementation reveals missing work → revise the active plan and get approval
-- Spec-backed work is blocked on an unplanned dependency → update plan.json
+### Implement → Plan (material changes)
+- A minor deviation may be recorded inline and reflected in the plan when it does not change
+  approved behavior, scope, architecture, public contracts, or major dependencies.
+- Material missing work or an unplanned dependency → revise the active plan and get approval.
 
 ### Implement → Research (fundamental issue)
 - Inline planning or implementation develops substantial needs → ask the human whether to

package/skills/atelier-setup/SKILL.md

@@ -1,14 +1,15 @@
 ---
 name: atelier-setup
-description: Configure a repository's generic agent guidance for Atelier's development workflow. Use only when the user explicitly invokes atelier-setup; it inspects existing repository instructions and domain-document conventions, previews an idempotent project-guidance update, and writes only after approval. It does not install Atelier, configure a harness, or scaffold empty workflow artifacts.
+description: Configure a repository for Atelier's development workflow. Use only when explicitly invoked; inspect existing guidance, issue-tracker and domain-document conventions, preview the proposed configuration, and write only after approval. It does not install Atelier or initialize external tooling.
 user-invocable: true
+disable-model-invocation: true
 ---
 
 # Atelier Setup
 
-Set up generic repository guidance that Atelier skills need without taking ownership of the
-developer's installation, harness configuration, or project structure. Explore first, present
-the proposed edit exactly, and write only after the developer approves it.
+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
 
@@ -18,6 +19,9 @@ Read the repository before proposing any change:
   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.
 
@@ -33,9 +37,19 @@ Summarize what exists and recommend a domain-document layout:
   contexts. `CONTEXT-MAP.md` belongs at the root and points to each context's `CONTEXT.md` and
   `docs/adr/` directory.
 
-Explain that these documents remain lazy: do not create `CONTEXT.md`, `CONTEXT-MAP.md`, or an ADR
+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.
+2. Otherwise recommend the tracker indicated by existing repository practice, then ask the
+   developer to confirm or describe their tracker.
+3. Accept GitHub, GitLab, local Markdown, another tracker described by the developer, or `none`.
+4. 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.
@@ -43,8 +57,13 @@ Select the instruction file to edit:
 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 the exact `## Agent skills` block that will be
-written. Stop and wait for explicit approval.
+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
 
@@ -58,23 +77,27 @@ Add the following block to the selected instruction file:
 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.
 
-### Domain documentation
+### 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.
 
-Before working in a domain area, read root `CONTEXT-MAP.md` when present and follow it to the
-relevant context documentation. Otherwise, read root `CONTEXT.md` when present. Read relevant
-architectural decisions under `docs/adr/` and any context-specific ADR directories.
+### Domain documentation
 
-If these documents do not exist, proceed silently. Create or update them only when domain
-terminology or an architectural decision has been resolved.
+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` and
-`### Domain documentation` subsections in place rather than appending duplicates. Preserve other
-subsections and all content outside the section, including user edits. Do not create any other
-files or directories.
+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 changed 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.
+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.

package/skills/atelier-setup/references/domain.md

@@ -0,0 +1,22 @@
+# Domain Documentation
+
+## Layout
+
+- **Mode:** [single-context or multi-context]
+- **Context map:** [path or not used]
+- **System ADRs:** [path]
+- **Context ADRs:** [path pattern or not used]
+
+## Before Domain Work
+
+1. Read the context map when configured, then select the relevant context.
+2. Read that context's `CONTEXT.md` when it exists.
+3. Read ADRs relevant to the work.
+4. Proceed silently when these documents do not yet exist.
+
+## Ownership
+
+- `CONTEXT.md` records domain language, distinctions, and business invariants.
+- `CONTEXT-MAP.md` maps bounded contexts to their context documents and ADRs.
+- ADRs record architectural decisions and trade-offs.
+- This file only tells agents how to locate and consume those documents.