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 

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]
    SI -.->|Revise plan| P
    SI -.->|Revisit design| B
    F -.->|Issues found| SI

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.

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 multi-agent review rather than asking one agent for a general opinion. Sentinel triages the diff, specialist reviewers examine likely failure modes in parallel, Architect checks design boundaries, and a final challenge pass removes weak or unsupported findings.

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:

The CLI also configures three specialist agents for Claude Code, OpenCode, Codex, or Cursor:

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.

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, 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 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.

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.

• Claude Code: opusplan switches Opus/Sonnet by mode. Other session models share one thinking setting across modes. Atelier writes canonical modelSettings..effortLevel entries and subagent effort; Haiku has no graded effort control. 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. Claude configuration
• 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
• 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
• 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

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:

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 © 2026 Martin Richards