@martinffx/atelier 1.4.0 → 3.0.0

package/dist/atelier.js

@@ -31996,10 +31996,13 @@ var coerce = {
 };
 var NEVER = INVALID;
 // src/constants.ts
-var HARNESS_NAMES = ["claude", "opencode", "codex"];
-var AGENT_NAMES = ["recon", "oracle", "architect"];
+var Harness = ["claude", "opencode", "codex", "cursor"];
+var AGENT_NAMES = ["sentinel", "oracle", "architect"];
+var LEGACY_AGENT_NAME = "recon";
 
 // src/utils/errors.ts
+var harnessChoices = `${Harness.slice(0, -1).join(", ")}, or ${Harness.at(-1)}`;
+
 class AtelierError extends Error {
   code;
   exitCode;
@@ -32013,19 +32016,19 @@ class AtelierError extends Error {
 
 class ConfigNotFoundError extends AtelierError {
   constructor(command) {
-    super(`.atelier/config.json not found. Run \`atelier ${command} --harness <claude|opencode|codex>\` first.`, "CONFIG_NOT_FOUND", 1);
+    super(`.atelier/config.json not found. Run \`atelier ${command} --harness <${Harness.join("|")}>\` first.`, "CONFIG_NOT_FOUND", 1);
   }
 }
 
 class HarnessRequiredError extends AtelierError {
   constructor() {
-    super("`--yes` requires `--harness` (claude, opencode, or codex).", "HARNESS_REQUIRED", 1);
+    super(`\`--yes\` requires \`--harness\` (${harnessChoices}).`, "HARNESS_REQUIRED", 1);
   }
 }
 
 class InvalidHarnessError extends AtelierError {
   constructor(value) {
-    super(`Invalid harness "${value}". Must be claude, opencode, or codex.`, "INVALID_HARNESS", 1);
+    super(`Invalid harness "${value}". Must be ${harnessChoices}.`, "INVALID_HARNESS", 1);
   }
 }
 class FileWriteError extends AtelierError {
@@ -32041,7 +32044,7 @@ class HarnessConfigError extends AtelierError {
 }
 class InvalidConfigError extends AtelierError {
   constructor(cause, { suggestReinit = false } = {}) {
-    const suffix = suggestReinit ? " Run `atelier init --harness <claude|opencode|codex>` to reconfigure." : "";
+    const suffix = suggestReinit ? ` Run \`atelier init --harness <${Harness.join("|")}>\` to reconfigure.` : "";
     super(`Invalid configuration: ${cause}.${suffix}`, "INVALID_CONFIG", 1);
   }
 }
@@ -32131,18 +32134,46 @@ function readConfig(path2 = CONFIG_PATH) {
     });
   }
   try {
-    return ok(validateConfig(parsed));
+    return ok(validateConfig(migrateLegacyAgentName(parsed)));
   } catch (validationErr) {
     const message = validationErr instanceof Error ? validationErr.message : String(validationErr);
     return err({ type: "invalid", message });
   }
 }
+function migrateLegacyAgentName(config) {
+  if (typeof config !== "object" || config === null) {
+    return config;
+  }
+  const migrated = { ...config };
+  for (const harness of Harness) {
+    const section = migrated[harness];
+    if (typeof section !== "object" || section === null || !Array.isArray(section.agents)) {
+      continue;
+    }
+    const agents = section.agents;
+    migrated[harness] = {
+      ...section,
+      agents: agents.map((agent) => {
+        if (typeof agent !== "object" || agent === null) {
+          return agent;
+        }
+        const entry = agent;
+        return {
+          ...entry,
+          template: entry.template === LEGACY_AGENT_NAME ? "sentinel" : entry.template,
+          name: entry.name === LEGACY_AGENT_NAME ? "sentinel" : entry.name
+        };
+      })
+    };
+  }
+  return migrated;
+}
 function isOldFlatConfig(config) {
   if (typeof config !== "object" || config === null) {
     return false;
   }
   const record = config;
-  return typeof record.harness === "string" && record.claude == null && record.codex == null && record.opencode == null;
+  return typeof record.harness === "string" && Harness.every((harness) => record[harness] == null);
 }
 function writeConfig(config, path2 = CONFIG_PATH) {
   const dir = dirname(path2);
@@ -32153,7 +32184,7 @@ function writeConfig(config, path2 = CONFIG_PATH) {
 `);
 }
 function getConfiguredHarnesses(config) {
-  return HARNESS_NAMES.filter((harness) => config[harness] !== undefined);
+  return Harness.filter((harness) => config[harness] !== undefined);
 }
 function removeConfigDir(path2 = CONFIG_PATH) {
   const dir = dirname(path2);
@@ -32292,7 +32323,7 @@ async function init(options2) {
   }
   let harness;
   if (harnessOption) {
-    if (!HARNESS_NAMES.includes(harnessOption)) {
+    if (!Harness.includes(harnessOption)) {
       throw new InvalidHarnessError(harnessOption);
     }
     harness = harnessOption;
@@ -32302,7 +32333,7 @@ async function init(options2) {
         type: "list",
         name: "harness",
         message: "Which harness are you using?",
-        choices: HARNESS_NAMES
+        choices: Harness
       }
     ]);
     harness = answer.harness;
@@ -32348,7 +32379,7 @@ Files to write:`);
 Atelier initialized for ${harness}.`);
   console.log(`
 Next step:`);
-  if (harness === "opencode" && section.provider === "openai") {
+  if (harness === "opencode" && "provider" in section && section.provider === "openai") {
     console.log("  opencode auth login --provider openai  # connect your OpenAI account");
   }
   console.log("  npx skills add martinffx/atelier  # install skills");
@@ -32361,7 +32392,7 @@ import { homedir as homedir4 } from "os";
 // src/commands/utils.ts
 async function resolveHarness(config, harnessOption, command) {
   if (harnessOption) {
-    if (!HARNESS_NAMES.includes(harnessOption)) {
+    if (!Harness.includes(harnessOption)) {
       throw new InvalidHarnessError(harnessOption);
     }
     const configured2 = getConfiguredHarnesses(config);
@@ -32493,6 +32524,9 @@ var SimpleConfigSchema = exports_external.object({
   default_model: exports_external.string().min(1),
   agents: exports_external.array(AgentSchema).min(1)
 });
+var CursorConfigSchema = exports_external.object({
+  agents: exports_external.array(AgentSchema).min(1)
+}).strict();
 var OPENCODE_PROVIDERS = ["opencode-zen", "opencode-go", "amazon-bedrock", "openai"];
 var OpenCodeConfigSchema = exports_external.object({
   provider: exports_external.enum(OPENCODE_PROVIDERS),
@@ -32505,7 +32539,7 @@ var OpenCodeConfigSchema = exports_external.object({
 var ANTHROPIC_MODELS = ["haiku", "sonnet", "opus", "opusplan"];
 var DEFAULT_MODELS = {
   default_model: "opusplan",
-  recon: "haiku",
+  sentinel: "haiku",
   oracle: "opus",
   architect: "opus"
 };
@@ -32545,6 +32579,7 @@ function installAgents(section, basePath) {
   } catch (err2) {
     throw new FileWriteError(agentsDir, err2 instanceof Error ? err2.message : String(err2));
   }
+  rmSync2(join7(agentsDir, `${LEGACY_AGENT_NAME}.md`), { force: true });
   for (const agent of config.agents) {
     const template = readTemplate(agent.template);
     const frontmatter = `---
@@ -32599,6 +32634,7 @@ function remove2(section, basePath) {
       rmSync2(file, { force: true });
     }
   }
+  rmSync2(join7(agentsDir, `${LEGACY_AGENT_NAME}.md`), { force: true });
   removeDirIfEmpty(agentsDir);
   removeAtelierSettings(claudeDir);
 }
@@ -32717,28 +32753,28 @@ var PROVIDER_MODELS = {
 };
 var DEFAULT_MODELS2 = {
   "opencode-zen": {
-    recon: "opencode/minimax-m2.7",
+    sentinel: "opencode/minimax-m2.7",
     oracle: "opencode/kimi-k2.6",
     architect: "opencode/deepseek-v4-pro",
     build: "opencode/deepseek-v4-flash",
     plan: "opencode/deepseek-v4-pro"
   },
   "opencode-go": {
-    recon: "opencode-go/minimax-m2.7",
+    sentinel: "opencode-go/minimax-m2.7",
     oracle: "opencode-go/kimi-k2.6",
     architect: "opencode-go/deepseek-v4-pro",
     build: "opencode-go/deepseek-v4-flash",
     plan: "opencode-go/deepseek-v4-pro"
   },
   "amazon-bedrock": {
-    recon: "amazon-bedrock/anthropic-claude-haiku-4-5",
+    sentinel: "amazon-bedrock/anthropic-claude-haiku-4-5",
     oracle: "amazon-bedrock/anthropic-claude-opus-4-7",
     architect: "amazon-bedrock/anthropic-claude-opus-4-7",
     build: "amazon-bedrock/anthropic-claude-sonnet-4-5",
     plan: "amazon-bedrock/anthropic-claude-haiku-4-5"
   },
   openai: {
-    recon: "openai/gpt-5.6-luna",
+    sentinel: "openai/gpt-5.6-luna",
     oracle: "openai/gpt-5.6-sol",
     architect: "openai/gpt-5.6-sol",
     build: "openai/gpt-5.6-terra",
@@ -32790,6 +32826,7 @@ function installAgents2(section, basePath) {
   } catch (err2) {
     throw new FileWriteError(agentsDir, err2 instanceof Error ? err2.message : String(err2));
   }
+  rmSync3(join8(agentsDir, `${LEGACY_AGENT_NAME}.md`), { force: true });
   for (const agent of config.agents) {
     const template = readTemplate(agent.template);
     const frontmatter = `---
@@ -32816,13 +32853,13 @@ function mergeHarnessConfig2(section, basePath) {
   } catch (err2) {
     throw new FileWriteError(basePath, err2 instanceof Error ? err2.message : String(err2));
   }
-  const recon = config.agents.find((a) => a.name === "recon");
+  const sentinel = config.agents.find((a) => a.name === "sentinel");
   const architect = config.agents.find((a) => a.name === "architect");
   const atelierFields = {
     agent: {
       build: {
         mode: "primary",
-        model: config.build_model || recon?.model || DEFAULT_MODELS2[config.provider].build
+        model: config.build_model || sentinel?.model || DEFAULT_MODELS2[config.provider].build
       },
       plan: {
         mode: "primary",
@@ -32874,6 +32911,7 @@ function removeAgentFiles(opencodeRoot, config) {
       rmSync3(file, { force: true });
     }
   }
+  rmSync3(join8(agentsDir, `${LEGACY_AGENT_NAME}.md`), { force: true });
   removeDirIfEmpty2(agentsDir);
 }
 function removeDirIfEmpty2(dir) {
@@ -34045,7 +34083,7 @@ var OPENAI_MODELS = [
 ];
 var DEFAULT_MODELS3 = {
   default_model: "gpt-5.6-terra",
-  recon: "gpt-5.6-luna",
+  sentinel: "gpt-5.6-luna",
   oracle: "gpt-5.6-sol",
   architect: "gpt-5.6-sol"
 };
@@ -34098,6 +34136,7 @@ function installAgents3(section, basePath) {
   } catch (err2) {
     throw new FileWriteError(agentsDir, err2 instanceof Error ? err2.message : String(err2));
   }
+  rmSync4(join9(agentsDir, `${LEGACY_AGENT_NAME}.toml`), { force: true });
   for (const agent of config.agents) {
     const template = readTemplate(agent.template);
     const content = {
@@ -34167,6 +34206,7 @@ function remove4(section, basePath) {
       rmSync4(file, { force: true });
     }
   }
+  rmSync4(join9(agentsDir, `${LEGACY_AGENT_NAME}.toml`), { force: true });
   removeDirIfEmpty3(agentsDir);
   cleanCodexConfig(codexDir);
   removeEmptyCodexDir(codexDir);
@@ -34246,22 +34286,123 @@ function isObject(value) {
   return typeof value === "object" && value !== null && !Array.isArray(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 { join as join10 } from "path";
+var CURSOR_MODELS = [
+  "composer-2.5",
+  "cursor-grok-4.5-high",
+  "gpt-5.6-luna-medium",
+  "gpt-5.6-terra-medium",
+  "gpt-5.6-sol-medium",
+  "claude-opus-4-8-high",
+  "claude-sonnet-5-high",
+  "kimi-k2.7-code",
+  "glm-5.2-high"
+];
+var DEFAULT_MODELS4 = {
+  sentinel: "composer-2.5",
+  oracle: "claude-opus-4-8-high",
+  architect: "gpt-5.6-sol-medium"
+};
+var cursorAdapter = {
+  name: "cursor",
+  configSchema: CursorConfigSchema,
+  defaultSection: defaultSection4,
+  modelsForProvider: modelsForProvider4,
+  promptSection: promptSection4,
+  installAgents: installAgents4,
+  mergeHarnessConfig: mergeHarnessConfig4,
+  fileList: fileList4,
+  remove: remove5
+};
+function defaultSection4() {
+  return {
+    agents: AGENT_NAMES.map((name) => ({ template: name, name, model: DEFAULT_MODELS4[name] }))
+  };
+}
+function modelsForProvider4(_provider) {
+  return CURSOR_MODELS;
+}
+async function promptSection4(prompt2, section) {
+  const config = section;
+  const answers = await prompt2.prompt(AGENT_NAMES.map((name) => ({
+    type: "list",
+    name,
+    message: `Select model for ${name}`,
+    choices: CURSOR_MODELS,
+    default: config.agents.find((agent) => agent.name === name)?.model ?? DEFAULT_MODELS4[name]
+  })));
+  return {
+    agents: AGENT_NAMES.map((name) => ({
+      template: name,
+      name,
+      model: answers[name] ?? DEFAULT_MODELS4[name]
+    }))
+  };
+}
+function installAgents4(section, basePath) {
+  const config = section;
+  const agentsDir = join10(basePath, ".cursor", "agents");
+  try {
+    mkdirSync5(agentsDir, { recursive: true });
+  } catch (err2) {
+    throw new FileWriteError(agentsDir, err2 instanceof Error ? err2.message : String(err2));
+  }
+  rmSync5(join10(agentsDir, `${LEGACY_AGENT_NAME}.md`), { force: true });
+  for (const agent of config.agents) {
+    const template = readTemplate(agent.template);
+    const content = `---
+name: ${agent.name}
+description: ${template.description}
+model: ${agent.model}
+---
+${template.body}`;
+    const agentPath = join10(agentsDir, `${agent.name}.md`);
+    writeFileSync6(agentPath, content);
+    console.log(`Created ${shortPath(agentPath)}`);
+  }
+}
+function mergeHarnessConfig4(_section, _basePath) {}
+function fileList4(basePath) {
+  return AGENT_NAMES.map((name) => {
+    const path2 = join10(basePath, ".cursor", "agents", `${name}.md`);
+    return { path: path2, exists: existsSync6(path2) };
+  });
+}
+function remove5(section, basePath) {
+  const config = section;
+  const agentsDir = join10(basePath, ".cursor", "agents");
+  try {
+    for (const agent of config.agents) {
+      rmSync5(join10(agentsDir, `${agent.name}.md`), { force: true });
+    }
+    rmSync5(join10(agentsDir, `${LEGACY_AGENT_NAME}.md`), { force: true });
+    if (existsSync6(agentsDir) && readdirSync4(agentsDir).length === 0) {
+      rmdirSync4(agentsDir);
+    }
+  } catch (err2) {
+    throw new FileWriteError(agentsDir, err2 instanceof Error ? err2.message : String(err2));
+  }
+}
+
 // src/adapters/index.ts
 registerAdapter(claudeAdapter);
 registerAdapter(opencodeAdapter);
 registerAdapter(codexAdapter);
+registerAdapter(cursorAdapter);
 
 // src/atelier.ts
-var harnessChoices = HARNESS_NAMES.join(", ");
+var harnessChoices2 = Harness.join(", ");
 var program2 = new Command;
-program2.name("atelier").description("Atelier CLI - configure Claude Code, OpenCode, and Codex for spec-driven development").version("0.1.0");
-program2.command("init", { isDefault: true }).description("Initialize atelier globally").option(`--harness <type>`, `Harness type (${harnessChoices})`).option("--yes", "Non-interactive mode with defaults").action((options2) => {
+program2.name("atelier").description("Atelier CLI - configure Claude Code, OpenCode, Codex, and Cursor for spec-driven development").version("0.1.0");
+program2.command("init", { isDefault: true }).description("Initialize atelier globally").option(`--harness <type>`, `Harness type (${harnessChoices2})`).option("--yes", "Non-interactive mode with defaults").action((options2) => {
   init(options2).catch(handleError);
 });
-program2.command("update").description("Update atelier agents").option(`--harness <type>`, `Harness type (${harnessChoices})`).action((options2) => {
+program2.command("update").description("Update atelier agents").option(`--harness <type>`, `Harness type (${harnessChoices2})`).action((options2) => {
   update(options2).catch(handleError);
 });
-program2.command("remove").description("Remove a configured harness from atelier").option(`--harness <type>`, `Harness type (${harnessChoices})`).action((options2) => {
+program2.command("remove").description("Remove a configured harness from atelier").option(`--harness <type>`, `Harness type (${harnessChoices2})`).action((options2) => {
   remove(options2).catch(handleError);
 });
 program2.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@martinffx/atelier",
-  "version": "1.4.0",
+  "version": "3.0.0",
   "description": "Personal development toolkit - spec-driven development, code quality, deep thinking, and ecosystem patterns",
   "type": "module",
   "bin": {
@@ -12,6 +12,7 @@
     "claude-code",
     "opencode",
     "codex",
+    "cursor",
     "ai-agents",
     "spec-driven-development"
   ],

package/skills/atelier-orchestrator/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: atelier-orchestrator
+description: >
+  Skill routing and workflow orchestration. Selects Inline Plan or Spec-backed Plan, routes
+   to the correct workflow skill, and manages transitions between phases. Use when starting
+  any conversation or task to determine which planning mode and skill apply.
+user-invocable: false
+---
+
+<EXTREMELY-IMPORTANT>
+If you think there is even a 1% chance a skill might apply to what you are doing, you ABSOLUTELY
+MUST invoke the skill.
+
+IF A SKILL APPLIES TO YOUR TASK, YOU DO NOT HAVE A CHOICE. YOU MUST USE IT.
+
+This is not negotiable. This is not optional. You cannot rationalize your way out of this.
+</EXTREMELY-IMPORTANT>
+
+# Planning Workflow
+
+You have skills. You MUST use them. Not "should." Not "when convenient." MUST.
+
+Invoke relevant skills BEFORE any response or action. Even a 1% chance a skill might apply
+means you invoke it. If an invoked skill turns out to be wrong for the situation, you don't
+need to follow it. But you must check.
+
+## The One Rule
+
+**When an implementation choice exists, never write code until the human has reviewed and
+approved a written plan.** Exact mechanical changes may use the exception below.
+
+The plan may be inline in the conversation or backed by persisted spec artifacts. Select
+the mode before invoking an artifact-producing skill, state the choice with one brief
+reason, and let the human override it.
+
+## Planning Modes
+
+### Inline Plan (default)
+
+Use for bounded, well-understood work, including ordinary features, bug fixes, refactors,
+configuration changes, and multi-file changes. Route to **spec-plan** with Inline mode
+explicitly selected. It presents a concise plan in conversation, creates no planning artifacts
+or tracker entries, and stops for approval. After approval, implement the plan directly; do
+not invoke `spec-implement`, `spec-finish`, or `code-subagents`.
+
+Direct Inline implementation must:
+
+- Avoid main/master unless the human explicitly permits it
+- Stay within the approved scope and files
+- Run every validation item in the approved plan
+- Review the final diff for unintended changes
+- Do not commit, push, or open a PR without explicit human instruction
+
+When in doubt, choose Inline Plan. File count and estimated duration alone do not make work
+spec-worthy.
+
+### Spec-backed Plan
+
+Use when at least one concrete signal exists:
+
+- The human explicitly requests a spec or durable planning artifacts
+- Requirements or boundaries need discovery before planning
+- The work materially changes architecture, public contracts, data models, or cross-system behavior
+- Multiple dependent subsystems need decomposition and dependency tracking
+- The plan must survive the conversation for handoff, audit, or multi-person coordination
+
+Route through **spec-brainstorm**. This mode produces:
+
+```
+design.md    ← spec-brainstorm (requirements + research + architecture)
+plan.json    ← spec-plan (tasks, dependencies)
+```
+
+Do not infer substantial work from size alone. If no concrete signal applies, use Inline Plan.
+
+## Skill Routing
+
+```
+atelier-orchestrator → Select and announce planning mode
+spec-brainstorm   → Spec-backed discovery + design → design.md
+spec-plan         → Inline Plan or Spec-backed Plan → approval
+spec-implement    → Execute approved Spec-backed Plans; track tasks
+spec-finish       → Post-implementation validation for Spec-backed Plans
+code-subagents    → Parallel dispatch for Spec-backed Plan tasks
+```
+
+### Ordinary bounded work
+
+```
+spec-plan (Inline mode) → approval → implement directly
+```
+
+### Substantial work or explicit spec request
+
+```
+spec-brainstorm → spec-plan (Spec-backed Plan) → approval → spec-implement → spec-finish
+```
+
+### Truly mechanical change
+
+A typo or exact single-line replacement may skip planning when there is no implementation
+choice to review. If any choice exists, use an Inline Plan.
+
+## Hard Transitions
+
+| After completing... | Next step |
+|---------------------|-----------|
+| spec-brainstorm | spec-plan in Spec-backed mode |
+| approved Inline Plan | implement the approved plan directly |
+| approved Spec-backed Plan | spec-implement in Spec-backed mode |
+| spec-implement | spec-finish |
+
+Do not begin implementation without an approved written plan. Spec-backed work must not
+jump from research to implementation.
+
+## Iteration Patterns
+
+The workflow is not purely linear. Expect backflows:
+
+### Research → Research (discovery loop)
+- Brainstorm reveals new requirements → loop back to discovery phase
+- Human adds new scope mid-brainstorm → continue discovery
+
+### Plan → Research (design flaw)
+- 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 → Research (fundamental issue)
+- Inline planning or implementation develops substantial needs → ask the human whether to
+  switch to a Spec-backed Plan
+- Implementation reveals spec-backed design is fundamentally wrong → back to brainstorm
+
+### Finish → Implement (bugs found)
+- Validation finds bugs → back to implement
+- Tests failing → back to implement
+
+### When to escalate
+If you loop 2+ times on the same issue, stop and ask the human:
+
+> "We've looped on [issue] twice. Should we reconsider the approach?"
+
+## Red Flags — You Are Rationalizing
+
+| What you're thinking | Why it's wrong |
+|----------------------|----------------|
+| "This is too simple for a persisted spec" | Use an Inline Plan instead |
+| "I already know how to do this" | Knowing how ≠ having the human's approval for how |
+| "The human seems impatient" | Wasting time on wrong code is worse than planning |
+| "I'll just do a quick prototype" | Prototypes become production. Plan it. |
+| "I need to explore the code first" | Gather enough context for an Inline Plan; use brainstorm only when discovery is substantial |
+| "Let me just fix this one thing" | One thing becomes three. Plan it. |
+| "I can plan in my head" | Plans in your head can't be reviewed or annotated |
+| "This is just a refactor" | Refactors still need at least an Inline Plan |
+| "I'll write the plan after" | Post-hoc plans are fiction. Plan before. |
+| "I need more context first" | Skills tell you HOW to gather context. Check first. |
+| "The spec workflow is overkill" | It may be. Default to an Inline Plan unless substantial-work signals exist. |
+| "I know what that skill says" | Skills evolve. Read current version. Invoke it. |
+| "This feels productive" | Undisciplined action wastes time. Skills prevent this. |
+
+## Skill Types
+
+**Process skills** (spec-brainstorm, spec-plan, spec-implement, spec-finish): Follow exactly.
+Don't adapt away discipline.
+
+**Knowledge skills** (oracle-grill-me, oracle-domain-modelling): Adapt principles to
+context. These inform decisions within the workflow.
+
+**Discipline skills** (oracle-debug): Strict methodology that must be followed
+exactly — no adaptation that bypasses root-cause investigation.
+
+Process skills come first. Knowledge skills get invoked by process skills when needed.
+
+## User Instructions
+
+"Add X" or "Fix Y" doesn't mean skip workflows. Instructions say WHAT, not HOW.
+The skills define HOW.

package/skills/atelier-setup/SKILL.md

@@ -0,0 +1,80 @@
+---
+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.
+user-invocable: 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.
+
+## 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.
+- 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 these 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 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 the exact `## Agent skills` block that will be
+written. Stop and wait for explicit approval.
+
+## 3. Write After Approval
+
+Add the following block to the selected instruction file:
+
+```markdown
+## 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.
+
+### Domain documentation
+
+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.
+
+If these documents do not exist, proceed silently. Create or update them only when domain
+terminology or an architectural decision has been resolved.
+```
+
+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.
+
+## 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.

package/skills/code-review/SKILL.md

@@ -34,7 +34,7 @@ Use these concrete harness subagent types. If an exact match is unavailable, use
 
 | `subagent_type` | Purpose |
 |-----------------|---------|
-| `recon` | Triage only: changed-file analysis, context retrieval, reviewer selection |
+| `sentinel` | Triage only: changed-file analysis, context retrieval, reviewer selection |
 | `oracle` | Parallel reviewer personas, evidence-based critique, failure-mode analysis, challenge validation |
 | `architect` | Architecture, design-boundary, data-model, and API-contract review |
 
@@ -67,7 +67,7 @@ Follows [code-subagents](../code-subagents/SKILL.md) patterns:
 
 | Agent | Used In Step |
 |-------|--------------|
-| `recon` | Triage only (context retrieval, file analysis) |
+| `sentinel` | Triage only (context retrieval, file analysis) |
 | `oracle` | Reviewers and challenge validation |
 | `architect` | Architect (architecture review) |