python

Atelier

An atelier is the private workshop or studio where a principal master and a number of assistants, students, and apprentices can work together producing fine art or visual art released under the master's name or supervision.

Wikipedia

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

Quick Start

Install Atelier with a single command. It auto-detects your AI harness (Claude Code or OpenCode), configures agents, and sets up session hooks:

# Initialize atelier in your project
bunx @martinffx/atelier@latest init

# Or install everything including skills
bunx @martinffx/atelier@latest init --all

# Non-interactive mode (CI/CD)
bunx @martinffx/atelier@latest init --yes

That's it. Your project is now configured for spec-driven development.

What Gets Installed

Atelier sets up three things in your project:

1. Skills (34 available)

Specialized knowledge modules that auto-invoke based on context. Install them via the CLI (--all flag) or separately:

npx skills add martinffx/atelier

2. Agent Personas (3 subagents)

Harness-agnostic agent definitions configured with appropriate models:

Agent	Role	Claude	OpenCode
Scout	Fast codebase reconnaissance	haiku	deepseek-v4-flash
Oracle	Strategic thinking, requirements, analysis	opus	kimi-k2.6
Architect	DDD, system design, architecture	opus	deepseek-v4-pro

Agents are generated into .claude/agents/ or .opencode/agents/ with harness-specific model identifiers.

3. Session Hooks

Context injection that runs on every session start, clear, or compact:

• Claude Code: hooks/atelier-session-start outputs project context as JSON
• OpenCode: .opencode/plugins/atelier.js provides config and transform hooks

4. Task Tracking (optional)

The spec workflow skills support beads for dependency-aware task tracking:

# Install beads (optional but recommended)
npm install -g beads

Why beads? It provides bd ready (finds next unblocked task), bd dep add (dependency management), and bd list (progress tracking) that harness-native todos can't match.

Fallback: If beads isn't installed, skills fall back to the harness's native todo system (TodoWrite for Claude Code, built-in todos for OpenCode).

5. Configuration

Single source of truth in .atelier/config.json:

{
  "version": "1.0.0",
  "harness": "claude",
  "skills_source": "martinffx/atelier",
  "agents": [
    { "template": "scout", "model": "haiku" },
    { "template": "oracle", "model": "opus" },
    { "template": "architect", "model": "opus" }
  ]
}

CLI Commands

init (default)

Initialize atelier in the current project.

bunx @martinffx/atelier@latest init [options]

Options:

• --harness <type> - Force harness type (claude or opencode)
• --all - Also install skills via npx skills add
• --yes - Non-interactive mode with default models
• --project - Install skills in project directory (default: global)

Idempotent: Re-running init is safe. It regenerates files without deleting anything unless you switch harnesses.

update

Refresh hooks and agents from the latest templates without touching skills:

bunx @martinffx/atelier@latest update

remove

Remove all atelier-generated files from the project:

bunx @martinffx/atelier@latest remove

Skills remain installed. Run npx skills remove martinffx/atelier to remove them separately.

Skills

This repository includes 34 skills that enhance AI agents with specialized knowledge and workflows.

Installing Skills

If you didn't use --all during init, install skills manually:

# Install all skills
npx skills add martinffx/atelier

# Install specific skills
npx skills add martinffx/atelier --skill typescript-drizzle-orm
npx skills add martinffx/atelier --skill python-fastapi
npx skills add martinffx/atelier --skill spec-brainstorm

Skill Types

Skills fall into four categories based on what they do:

Workflow Skills (spec:*)

Process-oriented skills that guide you through structured development workflows. These produce artifacts and should be followed step-by-step.

• spec-brainstorm → spec.md — Discovery, requirements, architecture
• spec-plan → plan.json — Break spec into implementable tasks
• spec-implement — Execute tasks with TDD
• spec-finish — Validate, review, prepare for PR
• spec-orchestrator — Route to the right skill based on context

Thinking Skills (oracle:*)

Analytical skills that provide patterns, principles, and deep reasoning. These adapt to your specific situation.