@martinffx/atelier 3.0.1 → 3.1.0

package/CHANGELOG.md

@@ -4,6 +4,23 @@
 
 - **breaking:** rename the `recon` agent to `sentinel`. Existing Atelier configuration is migrated automatically and legacy generated files are removed during the next command.
 
+## [3.1.0](https://github.com/martinffx/atelier/compare/v3.0.2...v3.1.0) (2026-08-09)
+
+
+### Features
+
+* **code-review:** persist review decisions ([4b1a349](https://github.com/martinffx/atelier/commit/4b1a34962f2b52f248e4581c663ed139eed4e081))
+* **codex:** configure project execution defaults ([74ef9cc](https://github.com/martinffx/atelier/commit/74ef9cc71c25145ba7591bd58306efc7e734a7c6))
+* **skills:** apply writing guidance to prose ([3fce90d](https://github.com/martinffx/atelier/commit/3fce90da2881788a8d8cdcad63a61849b298d33c))
+* **skills:** enforce simplicity throughout workflows ([fcf852b](https://github.com/martinffx/atelier/commit/fcf852bf68139e66d165761beeec8f74827513eb))
+
+## [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

@@ -7,10 +7,28 @@
 Atelier gives coding agents a disciplined way to move from an idea to reviewed, verified code without taking control away from the developer.
 
 ```bash
-npx skills add martinffx/atelier
 npx @martinffx/atelier@latest init --harness <claude|opencode|codex|cursor>
 ```
 
+Install the skills separately:
+
+```bash
+npx skills add martinffx/atelier
+```
+
+Update installed skills with:
+
+```bash
+npx skills update martinffx/atelier
+```
+
+For OpenCode, installing skills first also creates slash commands for every installed skill
+marked `user-invocable: true`. If you initialized OpenCode before installing the skills, run:
+
+```bash
+npx @martinffx/atelier@latest update --harness opencode
+```
+
 ## 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
@@ -34090,6 +34277,9 @@ var DEFAULT_MODELS3 = {
 var MANAGED_CODEX_KEYS = [
   { key: "model" },
   { key: "model_reasoning_effort" },
+  { key: "plan_mode_reasoning_effort" },
+  { key: "sandbox_mode" },
+  { key: "approval_policy" },
   {
     key: "features",
     nested: { features: ["multi_agent"] }
@@ -34168,6 +34358,9 @@ function mergeHarnessConfig3(section, basePath) {
     ...existing,
     model: config.default_model,
     model_reasoning_effort: "medium",
+    plan_mode_reasoning_effort: "high",
+    sandbox_mode: "danger-full-access",
+    approval_policy: "on-request",
     features: {
       ...isObject(existing.features) ? existing.features : {},
       multi_agent: true
@@ -34216,7 +34409,7 @@ function removeDirIfEmpty3(dir) {
     return;
   }
   try {
-    if (readdirSync3(dir).length === 0) {
+    if (readdirSync4(dir).length === 0) {
       rmdirSync3(dir);
     }
   } catch (err2) {
@@ -34274,7 +34467,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 +34480,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 +34571,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.1.0",
   "description": "Personal development toolkit - spec-driven development, code quality, deep thinking, and ecosystem patterns",
   "type": "module",
   "bin": {

package/skills/atelier-orchestrator/SKILL.md

@@ -33,6 +33,18 @@ The plan may be inline in the conversation or backed by persisted spec artifacts
 the mode before invoking an artifact-producing skill, state the choice with one brief
 reason, and let the human override it.
 
+## Governing Principles
+
+Invoking a skill selects relevant guidance. It does not make every pattern in every loaded
+skill part of the solution. Existing source, explicit requirements, and the smallest correct
+change determine which patterns apply.
+
+Begin with the current design and the minimum behavior-preserving change. Product,
+infrastructure, and architectural expansion require explicit scope. Keep **ponytail** active
+throughout development when it is available or required by the repository. Keep
+**writing-clearly-and-concisely** active whenever writing or editing prose for humans. Before
+returning or persisting that prose, apply **humanizer** in embedded mode.
+
 ## Planning Modes
 
 ### Inline Plan (default)
@@ -125,9 +137,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