Atelier

A personal development toolkit for AI agents. It covers spec-driven development, code quality, and deep thinking.

Atelier gives coding agents a disciplined way to move from an idea to reviewed, verified code without taking control away from the developer.

npx @martinffx/atelier@latest init --harness <claude|opencode|codex>

Install the skills separately:

npx skills add martinffx/atelier

Update installed skills with:

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:

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.

flowchart TD
    R[Request] --> O[atelier-orchestrator]

    O -->|Bounded work| IP[spec-plan: Inline Plan]
    IP --> IA{Developer approval}
    IA -->|Approved| IS[Stop]
    IA -.->|Revise| IP

    IS -->|New implementation request| I[Implement directly]
    I --> V[Validate]
    V -.->|Issues found| I
    IP -.->|Needs brainstorming| B
    I -.->|Needs brainstorming| B

    O -->|Substantial work| B[spec-brainstorm]
    B --> D[design.md]
    D --> BS[Stop]
    BS -->|New planning request| G[oracle-grill-me]
    G --> P[spec-plan]
    G -.->|Refine design| D
    P --> SA{Developer approval}
    SA -->|Approved| J[plan.json]
    SA -.->|Revise plan| P
    SA -.->|Revisit design| B
    J --> PS[Stop]
    PS -->|New implementation request| SI[spec-implement]
    SI --> CR[code-review]
    CR --> F[spec-finish]
    F --> PR[code-pull-request]
    PS -->|Unattended run| SL[spec-loop]
    SL -->|Per-batch review| SL
    SL --> F
    SI -.->|Revise plan| P
    SI -.->|Revisit design| B
    F -.->|Issues found| SI

Loading

The workflow is deliberately harder to rush than an unstructured agent session. spec-brainstorm writes only design.md, and spec-plan writes only its selected plan output. Each skill then stops. The developer starts planning and implementation with separate requests. This records decisions when they need to survive the conversation, keeps implementation tied to an approved plan, and requires evidence before calling the work complete.

Before a plan is presented, spec-plan runs a design review and a critical challenge as parallel subagents and notes what changed. During implementation, spec-implement hands tasks whose design is already settled to a subagent, keeping design-sensitive work in the main thread. The main agent explicitly selects the agent for each step by the kind of work, per atelier-orchestrator.

Grill the idea

oracle-grill-me interviews you one question at a time until the important decisions are explicit. It researches facts from the codebase instead of asking you to supply them, gives a recommended answer for each decision, and leaves the final choice with you.

As the discussion resolves, it maintains the project's domain language and architectural decisions. Use it on a proposal, plan, migration, or design that feels settled a little too quickly.

Grill me on this migration plan

Review the code

code-review runs a review as a debate rather than asking one agent for a general opinion. A read-only scout triages the diff, specialist Critics (always including a simplicity check) raise findings in parallel, an Author defends the change against each one, and Critics concede or maintain with evidence. A Judge rules only on what is still contested. Findings are labelled issue, suggestion, question, nitpick or praise, and as blocking or not; quotes are checked mechanically and the main agent audits what each turn did. See the research notes.

rq             # Review the diff to main
rq develop     # Review against another branch
rs             # Work through the findings

It reports findings before changing code. You decide which fixes to apply.

What you get

Atelier installs a focused set of skills for the full development loop:

Area	Capabilities
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

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	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. 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 (November 2026). Each entry is model / thinking.

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 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, 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 but absent from the researched Zen catalog. 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. 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.

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: 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; a saved opusplan is migrated to opus. 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
• 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
• 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
• 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

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

Language-specific guidance lives in companion repositories:

• Python skills
• TypeScript skills

Rationale and inspiration

Better models alone do not produce better software. Coding agents, like human teams, are shaped by the systems they work within. Good outcomes depend on more than individual ability. They depend on the processes, constraints, shared context, and feedback surrounding the work. If that system does little to encourage quality or catch weak results, agents will simply produce unreliable code faster. Atelier is an attempt to build a better system around the agent, making robust output more repeatable. Building Your Own Agent Harness explains the thinking behind it.

The name is literal. An atelier is a workshop where a principal works with assistants. Here, the developer is the principal, agents are the assistants, the codebase is the workshop, and skills record how the work happens.

Atelier draws on spec-driven development and several projects that informed its approach to agent collaboration:

• Agent OS for discovering project standards and shaping lightweight specs.
• OpenSpec for fluid, artifact-guided workflows that support iteration and brownfield development.
• GitHub Spec Kit for making specifications central to a structured specify, plan, tasks, and implement workflow.
• Superpowers for composable skills, mandatory engineering workflows, TDD, and evidence-based verification.
• Matt Pocock's Skills for small, adaptable skills grounded in practical engineering and developer control.

Some Atelier skills have more direct lineage:

Atelier skill	Source skill	Relationship
atelier-orchestrator	Superpowers using-superpowers	Adapted from its mandatory skill-routing discipline.
spec-brainstorm	Superpowers brainstorming	Adapted from its conversational discovery and section-by-section design approval.
spec-plan	Superpowers writing-plans	Inspired by its explicit, verifiable implementation plans.
spec-implement	Superpowers executing-plans and test-driven-development	Inspired by plan-driven execution and test-first feedback loops.
spec-loop	Superpowers subagent-driven-development	Inspired by its fresh implementer per task, review after each unit, and final whole-branch review. Atelier reviews per batch.
spec-finish	Superpowers finishing-a-development-branch and verification-before-completion	Inspired by its validation and completion workflow.
code-subagents	Superpowers subagent-driven-development and dispatching-parallel-agents	Inspired by fresh subagents, parallel dispatch, and batch review.
code-handoff	Matt Pocock's handoff	Adapted from its context-preserving handoff format.
oracle-grill-me	Matt Pocock's grilling and grill-with-docs	Adapted from its rigorous interview loop and integration with living domain documentation.
oracle-domain-modelling	Matt Pocock's domain-modeling	Adapted from its active domain-modelling discipline, CONTEXT.md, and lightweight ADRs.
oracle-codebase-design	Matt Pocock's 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".
oracle-debug	Superpowers systematic-debugging and Matt Pocock's diagnosing-bugs	Adapted from their root-cause-first debugging workflows.

code-commit follows the Conventional Commits specification.

Atelier adapts these ideas into an opinionated toolkit that works across harnesses. It does not claim to have invented the practices it uses.

Development

Load the repository directly in Claude Code:

claude --plugin-dir ./atelier

Build and test the CLI:

bun run build
bun test
bun run typecheck

Restart your coding harness after changing skills so it reloads their definitions.

License

MIT Copyright (c) 2026 Martin Richards