@martinffx/atelier 3.6.0 → 3.8.0

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "atelier",
-  "version": "1.2.2",
+  "version": "3.8.0",
   "description": "Personal development toolkit - spec-driven development, code quality, deep thinking, and ecosystem patterns",
   "author": {
     "name": "Martin Richards"
@@ -22,6 +22,8 @@
     "shortDescription": "Personal development toolkit - spec-driven development, code quality, deep thinking, and ecosystem patterns",
     "developerName": "Martin Richards",
     "category": "Developer Tools",
-    "capabilities": ["Read"]
+    "capabilities": [
+      "Read"
+    ]
   }
 }

package/CHANGELOG.md

@@ -4,6 +4,25 @@
 
 - **breaking:** rename the `recon` agent to `sentinel`. Existing Atelier configuration is migrated automatically and legacy generated files are removed during the next command.
 
+## [3.8.0](https://github.com/martinffx/atelier/compare/v3.7.0...v3.8.0) (2026-11-13)
+
+
+### Features
+
+* **claude:** keep opusplan as a selectable session model ([#95](https://github.com/martinffx/atelier/issues/95)) ([052e3c0](https://github.com/martinffx/atelier/commit/052e3c0e4d5c84af71d71abc60bd9e1f48cade35))
+* **config:** use one session model with plan effort and remove cursor ([3177f6f](https://github.com/martinffx/atelier/commit/3177f6f8ff2eba63822aae478d7b8d6c40df413a))
+* **skills:** add code-retro skill for branch retrospectives ([#93](https://github.com/martinffx/atelier/issues/93)) ([193f54f](https://github.com/martinffx/atelier/commit/193f54f97547bd0b424fd6e0c54d23ab78e753c3))
+* **skills:** point setup at subagent delegation and spec-loop resume ([#94](https://github.com/martinffx/atelier/issues/94)) ([0576072](https://github.com/martinffx/atelier/commit/05760722eec57aa66a2f97bb1852e86ef14b0249))
+
+## [3.7.0](https://github.com/martinffx/atelier/compare/v3.6.0...v3.7.0) (2026-11-07)
+
+
+### Features
+
+* **agents:** make keymaker the implementer of settled designs ([6c7fb33](https://github.com/martinffx/atelier/commit/6c7fb33463006d64f68f6bb2d7056347b3eb7bbf))
+* **claude:** set a 190k auto-compact window under opusplan ([a9f1ed1](https://github.com/martinffx/atelier/commit/a9f1ed156f10fbde547dcffe9b31b33409a204f3))
+* **opencode:** refresh model catalogs and add openrouter and google providers ([#90](https://github.com/martinffx/atelier/issues/90)) ([85ed86b](https://github.com/martinffx/atelier/commit/85ed86b5a070f08624c8f4dab2445ebeb8b73db3))
+
 ## [3.6.0](https://github.com/martinffx/atelier/compare/v3.5.0...v3.6.0) (2026-10-25)
 
 

package/README.md

@@ -7,7 +7,7 @@
 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 @martinffx/atelier@latest init --harness <claude|opencode|codex|cursor>
+npx @martinffx/atelier@latest init --harness <claude|opencode|codex>
 ```
 
 Install the skills separately:
@@ -105,47 +105,51 @@ Atelier installs a focused set of skills for the full development loop:
 |------|--------------|
 | Spec workflow | Discovery, research, planning, implementation, validation, and finishing |
 | Thinking | Root-cause debugging, decision grilling, domain modelling, and codebase design |
-| Delivery | Multi-agent review, subagent coordination, commits, handoffs, and pull requests |
+| Delivery | Multi-agent review, subagent coordination, commits, handoffs, pull requests, and branch retros |
 
-The CLI also configures four specialist agents for Claude Code, OpenCode, Codex, or Cursor:
+The CLI also configures four specialist agents for Claude Code, OpenCode, or Codex:
 
 | Agent | Role |
 |-------|------|
 | **Sentinel** | Read-only codebase reconnaissance and review triage |
 | **Oracle** | Requirements, trade-offs, and critical analysis of changes |
 | **Architect** | Domain modelling, system design, and architecture review |
-| **Keymaker** | Fast scaffolding of files and boilerplate from templates and existing patterns |
+| **Keymaker** | Implements settled designs: code, business logic and tests, so the main conversation stays small |
 
-Each subagent launch explicitly selects one of these four by matching the task to its description; the harness default is never used. Keymaker is the only agent with write access in Codex, and it uses Sentinel's model and thinking defaults in every configuration.
+Each subagent launch explicitly selects one of these four by matching the task to its description; the harness default is never used. Keymaker is the only agent with write access in Codex. It runs on each harness's build-tier model (Sonnet on Claude Code), not the cheap Sentinel model.
 
 Run `npx @martinffx/atelier@latest --help` for CLI commands and options. Each skill contains its own operating instructions and loads when its context applies.
 
 ## Models and thinking
 
-New configurations use the following defaults (September 2026). Each entry is **model / thinking**.
+New configurations use the following defaults (November 2026). Each entry is **model / thinking**.
 
-| Configuration | Sentinel | Oracle | Architect | Plan | Build |
-|---|---|---|---|---|---|
-| Claude Code | Haiku 5.5 / default | Opus 5.5 / xhigh | Opus 5.5 / high | Opus 5.5 / high | Sonnet 5 / high |
-| Codex | Luna 6 / low | Astra 6 / high | Astra 6 / xhigh | Sol 6 / xhigh | Sol 6 / high |
-| OpenCode / OpenAI | Luna 6 / low | Astra 6 / high | Astra 6 / xhigh | Astra 6 / xhigh | Sol 6 / high |
-| OpenCode / Bedrock | Haiku 4.5 / default | Fable 5.1 / high | Opus 5.5 / high | Opus 5.5 / high | Sonnet 5 / high |
-| OpenCode / Zen | GLM 5.3 Flash / low | Kimi K3 / high | GLM 5.3 / high | GLM 5.3 / high | DeepSeek V4.1 Flash / high |
-| OpenCode / Go | GLM 5.3 Flash / low | MiMo V2.6 Pro / on | GLM 5.3 / high | GLM 5.3 / high | DeepSeek V4.1 Flash / high |
+| Configuration | Sentinel | Oracle | Architect | Keymaker | Session / Build | Plan |
+|---|---|---|---|---|---|---|
+| Claude Code | Haiku 5.5 / low | Opus 5.5 / xhigh | Opus 5.5 / high | Sonnet 5 / default | Opus 5.5 / medium | Opus 5.5 / medium (one session level) |
+| Codex | Luna 6 / low | Astra 6 / xhigh | Astra 6 / high | Sol 6 / medium | Astra 6 / high | Astra 6 / high |
+| OpenCode / OpenAI | Luna 6 / low | Astra 6 / xhigh | Astra 6 / high | Sol 6 / medium | Astra 6 / high | Astra 6 / high |
+| OpenCode / Bedrock | Haiku 5.5 / low | Fable 5.1 / xhigh | Opus 5.5 / high | Sonnet 5 / default | Opus 5.5 / medium | Opus 5.5 / high |
+| OpenCode / Zen | GLM 5.3 Flash / low | Kimi K3 / high | GLM 5.3 / high | DeepSeek V4.1 Flash / high | Kimi K3 / low | Kimi K3 / high |
+| OpenCode / Go | GLM 5.3 Flash / low | MiMo V2.6 Pro / on | GLM 5.3 / high | DeepSeek V4.1 Flash / high | Kimi K3.1 Pro / low | Kimi K3.1 Pro / high |
+| OpenCode / OpenRouter | GLM 5.3 Flash / low | Kimi K3.1 Pro / high | GLM 5.3 / high | DeepSeek V4.1 Flash (1017) / high | Kimi K3.1 Pro / low | Kimi K3.1 Pro / high |
+| OpenCode / Google | Gemini 3.5 Flash Lite / low | Gemini 4 Argon / high | Gemini 4 Argon / high | Gemini 3.8 Flash / high | Gemini 4 Argon / medium | Gemini 4 Argon / high |
 
-Sentinel favors inexpensive reconnaissance. Oracle needs requirements synthesis and judgment; Architect and Plan need technical depth and completeness. Build balances capability and execution cost. These are starting configurations, informed by [Artificial Analysis](https://artificialanalysis.ai/models), rather than measured winners for Atelier's specific roles. Benchmark effort levels and provider speeds may differ from these defaults.
+Sentinel favors inexpensive reconnaissance. Oracle needs requirements synthesis and judgment; Architect needs technical depth and completeness. Keymaker balances capability and execution cost. The session model drives the main conversation. These are starting configurations, informed by [Artificial Analysis](https://artificialanalysis.ai/models), rather than measured winners for Atelier's specific roles. Benchmark effort levels and provider speeds may differ from these defaults.
 
 Kimi's long-context results motivate its Oracle assignment on Zen. MiMo Pro's general capability and measured value motivate its Go assignment; Pro is available in [Go](https://opencode.ai/docs/go/) but absent from the researched [Zen catalog](https://opencode.ai/docs/zen/). GLM offers a credible engineering baseline; DeepSeek Flash favors execution throughput. Qwen, MiniMax, and other available candidates remain selectable. Qwen's hosted Max endpoint should not be assumed to be an equivalent open-weight model.
 
-Run `atelier update --harness <claude|codex|opencode>` to choose models and thinking settings. Saved models, including custom and older IDs, remain selectable; updates do not replace them with new defaults. Switching OpenCode providers starts from that provider's defaults. Cursor's configuration is unchanged.
+Run `atelier update --harness <claude|codex|opencode>` to choose models and thinking settings. Saved models, including custom and older IDs, remain selectable; updates do not replace them with new defaults. Switching OpenCode providers starts from that provider's defaults. Each slot asks for its model and then its thinking level, and the model picker marks the role's default `(recommended)` without moving off a saved model. When you change a slot's model, the picker preselects that model family's recommended level and marks recommended levels `(recommended)`; every supported level stays selectable.
 
-Thinking is stored as `agents[].thinking`, `build_thinking`, and `plan_thinking` in `~/.atelier/config.json`. Values are model-specific: `default`, `off`, `on`, `low`, `medium`, `high`, `xhigh`, or `max`. The picker offers only verified capabilities. Custom models and catalog models whose controls have not been verified offer `default` only. Missing fields preserve legacy behavior; **Keep existing behavior** preserves that omission when editing. In particular, old Codex configurations retain medium agent/Build effort and high Plan effort. An explicit `default` omits Atelier's native effort override; other harness settings can still apply.
+Build (session) thinking is stored as `build_thinking`, plan thinking as `plan_thinking` (Codex and OpenCode only), and each agent's as `agents[].thinking`, all in `~/.atelier/config.json`. Values are model-specific: `default`, `off`, `on`, `low`, `medium`, `high`, `xhigh`, or `max`. The picker offers only verified capabilities. Custom models and catalog models whose controls have not been verified offer `default` only. Missing fields preserve legacy behavior; **Keep existing behavior** preserves that omission when editing. In particular, old Codex configurations retain medium agent/Build effort. An explicit `default` omits Atelier's native effort override; other harness settings can still apply. Old plan settings from earlier versions are migrated or cleaned up automatically.
 
-- **Claude Code:** `opusplan` switches Opus/Sonnet by mode. Other session models share one thinking setting across modes. Atelier writes canonical `modelSettings.<model>.effortLevel` entries and subagent `effort`. Session `max` cannot be persisted, though supported subagents can use it. Use Claude Code **2.1.280 or later** for Opus 5.5 and the current aliases. Atelier also sets `disableClaudeAiConnectors: true`, `syncClaudeAiSkills: false` and `syncClaudeAiPlugins: false` in `~/.claude/settings.json`, so nothing from claude.ai is synced into Claude Code; `atelier remove` clears them unless you changed them. It also disables the Claude Code built-ins that clash with Atelier skills (`disableBundledSkills`, `enableArtifact: false`, `disableWorkflows`, deny rules for `Artifact`, `ArtifactComments`, `ArtifactData`, `Workflow` and `DesignSync`, and `skillOverrides` turning off the `/security-review` and `/ultrareview` commands). Interactive `init` also offers a checklist of optional built-ins to disable, none selected by default: `cron` (`/loop` and the Cron tools), `chrome` (the claude-in-chrome MCP server) and `remote-trigger` (`RemoteTrigger`). `atelier remove` and unticking an option undo these the same way. [Claude configuration](https://code.claude.com/docs/en/model-config)
-- **Codex:** Plan and Build share the selected session model, with separate reasoning settings. Oracle and Architect use independent Astra configurations. `off` maps to native `none`, available on Sol/Luna but not Astra. [Codex configuration](https://developers.openai.com/codex/config-reference/)
-- **OpenCode:** all five assignments are independent. Use **1.18.30 or later** for GPT-6 integration. Atelier sends explicit provider options rather than relying on automatically discovered reasoning variants: `reasoningEffort` for OpenAI-compatible routes, `effort` for Anthropic, and `reasoningConfig` for Bedrock. GLM 5.3 supports low/high/max; it does not support medium. Bedrock defaults use US inference profiles with `us-east-1`. [OpenCode agents](https://opencode.ai/docs/agents/)
+- **Claude Code:** there is one session effort and no separate plan setting, because Claude Code sets effort per model or per session and has no plan mode effort. The session model defaults to `opus`; `opusplan` can be selected as the session model (not for subagents): it plans on Opus and builds on Sonnet, and the one session effort is written for both. Atelier writes canonical `modelSettings.<model>.effortLevel` entries for the session model and subagent `effort`. Session `max` cannot be persisted, though supported subagents can use it. Atelier no longer writes `autoCompactWindow`; `atelier update` and `atelier remove` clear a `190000` value it wrote earlier, and any value other than exactly `190000` is kept. Use Claude Code **2.1.280 or later** for Opus 5.5 and the current aliases. Atelier also sets `disableClaudeAiConnectors: true`, `syncClaudeAiSkills: false` and `syncClaudeAiPlugins: false` in `~/.claude/settings.json`, so nothing from claude.ai is synced into Claude Code; `atelier remove` clears them unless you changed them. It also disables the Claude Code built-ins that clash with Atelier skills (`disableBundledSkills`, `enableArtifact: false`, `disableWorkflows`, deny rules for `Artifact`, `ArtifactComments`, `ArtifactData`, `Workflow` and `DesignSync`, and `skillOverrides` turning off the `/security-review` and `/ultrareview` commands). Interactive `init` also offers a checklist of optional built-ins to disable, none selected by default: `cron` (`/loop` and the Cron tools), `chrome` (the claude-in-chrome MCP server) and `remote-trigger` (`RemoteTrigger`). `atelier remove` and unticking an option undo these the same way. [Claude configuration](https://code.claude.com/docs/en/model-config)
+- **Codex:** the session model defaults to `gpt-6-astra`; Build uses `model_reasoning_effort` and Plan uses its own effort on the same model. There is no separate plan model. Plan effort is `plan_thinking`, written to `plan_mode_reasoning_effort` in `.codex/config.toml`; `default` removes the key, and an unset value leaves any existing key alone. Oracle and Architect use independent Astra configurations. `off` maps to native `none`, available on Sol/Luna but not Astra. [Codex configuration](https://developers.openai.com/codex/config-reference/)
+- **OpenCode:** the session model is `default_model` (migrated from `build_model`), defaulting to Kimi K3.1 Pro on opencode-go and openrouter, kimi-k3 on opencode-zen, claude-opus-5-5 on amazon-bedrock, gpt-6-astra on openai and gemini-4-argon on google. Atelier writes the session model to the top-level `model` (replacing any value already there, so every agent without its own model shares it) and to `agent.build` (which also carries the session thinking). Plan uses the same model with its own effort in `agent.plan` (`mode: primary`); an existing `agent.plan` without `mode: primary` belongs to you and is left untouched. `atelier remove` clears both entries and clears `model` only while it still matches. All five assignments are independent. Use **1.18.30 or later** for GPT-6 integration. Atelier sends explicit provider options rather than relying on automatically discovered reasoning variants: `reasoningEffort` for OpenAI-compatible routes, `effort` for Anthropic, and `reasoningConfig` for Bedrock, `reasoning.effort` for OpenRouter and `thinkingConfig.thinkingLevel` for Google. GLM 5.3 supports low/high/max; it does not support medium. Bedrock defaults use US inference profiles with `us-east-1`. Go's Muse Spark 1.3 Contributor only works if the workspace allows paid endpoints that train on request data. OpenRouter session warming is opt-in and off by default: when enabled, Atelier writes `providers.openrouter.settings.cache.warming: true`, so OpenCode sends keep-alive requests every 4 minutes for up to 30 minutes to keep an idle session cache warm. It only applies to root sessions (subagents are not warmed), whether it saves money depends on the model and host, and it requires OpenCode 2.2.6 or later. Turning it off, switching provider or `atelier remove` clears the key only if it is exactly `true`; a custom object value is left alone. [OpenCode agents](https://opencode.ai/docs/agents/)
 - **MiMo:** `on`/`off` maps to `thinking.type: enabled`/`disabled`. There are no graded effort tiers. OpenCode agent files omit the old fixed temperature override so provider defaults apply. [MiMo API](https://mimo.mi.com/docs/en-US/api/chat/openai-api)
 
+**Upgrading:** the config migration is one-way. After `atelier update` (or any command that rewrites the config) saves a migrated `~/.atelier/config.json`, an older CLI cannot read it, because its schema requires `build_model` and `plan_model` for OpenCode. To roll back, install the older version, then either hand-edit `~/.atelier/config.json` (restore `build_model` and `plan_model` in the `opencode` section) or delete the file and run `init` again.
+
 Atelier does not upgrade installed harness CLIs. Request-option serialization was checked against OpenCode's provider SDK versions with intercepted requests; this verifies parameter encoding, not upstream availability, quota, or role quality.
 
 ## Ecosystem
@@ -181,6 +185,7 @@ Some Atelier skills have more direct lineage:
 | [`spec-finish`](skills/spec-finish/SKILL.md) | Superpowers [`finishing-a-development-branch`](https://github.com/obra/superpowers/tree/main/skills/finishing-a-development-branch) and [`verification-before-completion`](https://github.com/obra/superpowers/tree/main/skills/verification-before-completion) | Inspired by its validation and completion workflow. |
 | [`code-subagents`](skills/code-subagents/SKILL.md) | Superpowers [`subagent-driven-development`](https://github.com/obra/superpowers/tree/main/skills/subagent-driven-development) and [`dispatching-parallel-agents`](https://github.com/obra/superpowers/tree/main/skills/dispatching-parallel-agents) | Inspired by fresh subagents, parallel dispatch, and batch review. |
 | [`code-handoff`](skills/code-handoff/SKILL.md) | Matt Pocock's [`handoff`](https://github.com/mattpocock/skills/tree/main/skills/productivity/handoff) | Adapted from its context-preserving handoff format. |
+| [`code-retro`](skills/code-retro/SKILL.md) | Matt Pocock's [`retro`](https://github.com/mattpocock/skills/tree/main/skills/engineering/retro) | Adapted from its session-evidence, ranked-candidates, write-nothing approach. Extended to a whole branch, centred on Corrections and Nudges. Its session extractor needs Python 3.9+. |
 | [`oracle-grill-me`](skills/oracle-grill-me/SKILL.md) | Matt Pocock's [`grilling`](https://github.com/mattpocock/skills/tree/main/skills/productivity/grilling) and [`grill-with-docs`](https://github.com/mattpocock/skills/tree/main/skills/engineering/grill-with-docs) | Adapted from its rigorous interview loop and integration with living domain documentation. |
 | [`oracle-domain-modelling`](skills/oracle-domain-modelling/SKILL.md) | Matt Pocock's [`domain-modeling`](https://github.com/mattpocock/skills/tree/main/skills/engineering/domain-modeling) | Adapted from its active domain-modelling discipline, `CONTEXT.md`, and lightweight ADRs. |
 | [`oracle-codebase-design`](skills/oracle-codebase-design/SKILL.md) | Matt Pocock's [`codebase-design`](https://github.com/mattpocock/skills/tree/main/skills/engineering/codebase-design) and John Ousterhout's *A Philosophy of Software Design* | Adapted from its deep-module vocabulary, deletion test, and design-it-twice. Extended with Ousterhout's principles and red flags, plus Alexis King's "parse, don't validate", Yaron Minsky's "make illegal states unrepresentable", and Gary Bernhardt's "functional core, imperative shell". |

package/agents/keymaker.md

@@ -1,36 +1,44 @@
 ---
 name: keymaker
-description: Fast scaffolder. Use proactively to create files, directories and boilerplate from templates or existing project patterns, or to make simple pattern-following edits; reports exactly what changed. Does not design, review or implement business logic.
+description: Implementer. MUST BE USED for every code change once the design or plan is settled, including new files, features, business logic, refactors, test writing, bug fixes with a known cause, and multi-file edits. Delegate implementation to Keymaker instead of editing in the main conversation, so the main conversation's context stays small. Give it the design excerpt, owned files and validation command. It writes tests first, implements, runs validation and reports files changed and test results. It makes no design decisions; it stops and asks.
 ---
 
-You are the **Keymaker**, a fast scaffolding agent. Your job is to create the files and directories others need, by copying existing project patterns or applying templates exactly. You work quickly, follow the pattern you are given, and never improvise design.
+You are the **Keymaker**, the implementer. The design is settled and someone has handed you one task to build. You write the code and tests, run the validation, and report back, so the main conversation never has to carry the implementation.
+
+Delegating to you is the default path for writing code. The main conversation edits directly only for trivial one-line changes and stateful debugging.
 
 ## Role
 
-- Create files and directory structures from templates or existing project patterns
-- Apply variable substitutions consistently across everything you create
-- Make simple, mechanical, pattern-following edits (renames, boilerplate, wiring)
-- Report exactly what was created or changed
+- Implement one task from the design excerpt you are given: files, business logic, wiring, and tests
+- Follow existing project patterns and conventions rather than inventing new ones
+- Write the test first when behaviour changes (stub → test → fix), then make it pass
+- Run the task's validation command and fix what fails, within the files you own
+- Report exactly what changed, and what the validation showed
 
 ## Skills
 
-Before beginning work, scan your environment for relevant skills and load any that apply to the task at hand. Use them to follow the project's conventions for structure and naming.
+Before beginning work, scan your environment for relevant skills and load any that apply to the task at hand. Use them to follow the project's conventions for structure, naming and testing.
+
+## Inputs
+
+You should be given: the task and its requirements, the design excerpt it implements, the files you own, and the validation command. If any of these is missing or ambiguous, stop and ask. Do not guess your way around a gap in the design.
 
 ## Checklist
 
 Before finishing, confirm you have:
 
-- [ ] Verified each target file does not already exist before creating it
-- [ ] Created parent directories as needed
-- [ ] Applied all relevant variable substitutions when using templates
-- [ ] Matched the pattern you were pointed at (naming, structure, imports)
-- [ ] Reported every file created or modified
+- [ ] Stayed inside the files you were told you own
+- [ ] Matched the pattern you were pointed at (naming, structure, imports, test style)
+- [ ] Written or updated tests for any changed behaviour
+- [ ] Run the validation command and read its output
+- [ ] Reported every file created or modified, plus the validation result (pass or the failing output)
 
 ## Boundaries
 
-- DO create files and directories as requested
-- DO follow the pattern you are given rather than inventing one
+- DO implement the task, including business logic, within your owned files
+- DO write and update tests
+- DO stop and ask when the design is unclear, contradicts the code, or a change would reach outside your owned files
 - DON'T make design or architectural decisions (that's `architect`)
-- DON'T implement business logic or review code
-- DON'T conduct requirements discovery (that's `oracle`)
-- NEVER overwrite existing files unless explicitly told to
+- DON'T conduct requirements discovery or challenge scope (that's `oracle`)
+- DON'T review code beyond checking your own work
+- NEVER overwrite files outside your owned list, and never silently work around a failing test by weakening it