@martinffx/atelier 1.4.0 → 3.0.0

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## Unreleased
+
+- **breaking:** rename the `recon` agent to `sentinel`. Existing Atelier configuration is migrated automatically and legacy generated files are removed during the next command.
+
+## [3.0.0](https://github.com/martinffx/atelier/compare/v2.0.0...v3.0.0) (2026-07-31)
+
+
+### ⚠ BREAKING CHANGES
+
+* **claude:** consolidate plugins under atelier
+* **skills:** split language skills into companion repositories
+
+### Features
+
+* **claude:** consolidate plugins under atelier ([745f872](https://github.com/martinffx/atelier/commit/745f872193ac841074ddc16f788ded5c92cf9744))
+* **skills:** add atelier setup workflow ([69a7a93](https://github.com/martinffx/atelier/commit/69a7a9350c2f8e7d8a6001143cb4f4233f462117))
+* **skills:** split language skills into companion repositories ([b1fb1f7](https://github.com/martinffx/atelier/commit/b1fb1f7db942283bca5f067848c55e0dcc6c228f))
+
+## [2.0.0](https://github.com/martinffx/atelier/compare/v1.4.0...v2.0.0) (2026-07-27)
+
+
+### ⚠ BREAKING CHANGES
+
+* **agents:** rename recon to sentinel
+
+### Features
+
+* **agents:** rename recon to sentinel ([bf69c50](https://github.com/martinffx/atelier/commit/bf69c50d7f69d0c1f7fc36d1d384914d99def81d))
+* **cursor:** add Cursor harness support ([c0ed4e3](https://github.com/martinffx/atelier/commit/c0ed4e356d3a34a085ca5f11344876bdf59ae618))
+* **cursor:** add subagent adapter foundation ([7b17972](https://github.com/martinffx/atelier/commit/7b1797267b96b502cb8002cdb1a7bac707978a7d))
+* **workflow:** add inline planning mode ([3faefd4](https://github.com/martinffx/atelier/commit/3faefd4d14425c9188ed7a34b42afbdf6eca19ff))
+
+
+### Bug Fixes
+
+* **workflow:** keep inline plans lightweight ([c30bc12](https://github.com/martinffx/atelier/commit/c30bc12543a61e3e645336fe6760fb994e125abd))
+* **workflow:** simplify execution and subagent review ([694e846](https://github.com/martinffx/atelier/commit/694e846af9953f8337734e0dab44e34a0f3a2acc))
+
 ## [1.4.0](https://github.com/martinffx/atelier/compare/v1.3.0...v1.4.0) (2026-07-18)
 
 

package/README.md

@@ -2,277 +2,152 @@
 
 ![Atelier - A collaborative workshop for software development](atelier.jpg)
 
-> 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](https://en.wikipedia.org/wiki/Atelier)
+> A personal development toolkit for AI agents. It covers spec-driven development, code quality, and deep thinking.
 
-A personal development toolkit for AI agents - spec-driven development, code quality, deep thinking, and ecosystem patterns.
-
-Atelier ships as a set of skills installed via `npx skills` plus a small CLI that generates harness-native agent definitions and configuration.
-
-## Quick Start
-
-Install Atelier with a single command. It configures agents and harness-native settings for Claude Code, OpenCode, or Codex:
-
-```bash
-# Initialize atelier for your harness
-npx @martinffx/atelier@latest init --harness <claude|opencode|codex>
-
-# Non-interactive mode (CI/CD)
-npx @martinffx/atelier@latest init --harness <claude|opencode|codex> --yes
-```
-
-That's it. Your project is now configured for spec-driven development.
-
-## What Gets Installed
-
-Atelier sets up two things:
-
-### 1. Skills (28 available)
-
-Specialized knowledge modules that auto-invoke based on context. Install them separately:
+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 skills add martinffx/atelier
+npx @martinffx/atelier@latest init --harness <claude|opencode|codex|cursor>
 ```
 
-### 2. Agent Personas (3 subagents)
-
-Harness-agnostic agent definitions configured with appropriate models:
+## How Atelier works
 
-| Agent | Role | Claude | OpenCode | Codex |
-|-------|------|--------|----------|-------|
-| **Recon** | Fast codebase reconnaissance | haiku | deepseek-v4-flash | gpt-5.6-luna |
-| **Oracle** | Strategic thinking, requirements, analysis | opus | kimi-k2.6 | gpt-5.6-sol |
-| **Architect** | DDD, system design, architecture | opus | deepseek-v4-pro | gpt-5.6-sol |
+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.
 
-Agents are generated into harness-specific locations (`.claude/agents/`, `.opencode/agent/`, `.codex/agents/`) with harness-native model identifiers.
-
-### 3. Task Tracking (optional)
-
-The spec workflow skills support **beads** for dependency-aware task tracking:
-
-```bash
-# 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).
-
-### 4. Configuration
-
-Single source of truth in `.atelier/config.json`:
-
-```json
-{
-  "version": "1.0.0",
-  "skills_source": "martinffx/atelier",
-  "skills_path": "~/.agents/skills",
-  "claude": {
-    "provider": "anthropic",
-    "default_model": "opusplan",
-    "agents": [
-      { "template": "recon", "name": "recon", "model": "haiku" },
-      { "template": "oracle", "name": "oracle", "model": "opus" },
-      { "template": "architect", "name": "architect", "model": "opus" }
-    ]
-  }
-}
-```
-
-## CLI Commands
-
-### `init` (default)
-
-Initialize atelier for a single harness. Each invocation configures one harness; run it multiple times to configure several.
-
-```bash
-npx @martinffx/atelier@latest init --harness <claude|opencode|codex> [options]
+```mermaid
+flowchart TD
+    R[Request] --> O[atelier-orchestrator]
+
+    O -->|Bounded work| IP[spec-plan: Inline Plan]
+    IP --> IA{Developer approval}
+    IA -->|Approved| I[Implement directly]
+    IA -.->|Revise| IP
+    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 --> 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 --> 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
 ```
 
-**Options:**
-- `--harness <type>` - Harness type (`claude`, `opencode`, or `codex`)
-- `--yes` - Non-interactive mode with default models
-
-**Idempotent**: Re-running `init` for the same harness is safe. It regenerates files without deleting anything unless you switch harnesses.
-
-### `update`
+The workflow is deliberately harder to rush than an unstructured agent session. It records decisions when they need to survive the conversation, keeps implementation tied to an approved plan, and requires evidence before calling the work complete.
 
-Refresh agents and harness-native config for one harness without touching skills:
-
-```bash
-npx @martinffx/atelier@latest update --harness <claude|opencode|codex>
-```
+## Grill the idea
 
-### `remove`
+[`oracle-grill-me`](skills/oracle-grill-me/SKILL.md) 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.
 
-Remove all atelier-generated files for one harness:
+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.
 
-```bash
-npx @martinffx/atelier@latest remove --harness <claude|opencode|codex>
+```text
+Grill me on this migration plan
 ```
 
-Skills remain installed. Run `npx skills remove martinffx/atelier` to remove them separately.
-
-## Skills
-
-This repository includes 28 skills that enhance AI agents with specialized knowledge and workflows.
+## Review the code
 
-### Installing Skills
-
-Install skills manually:
-
-```bash
-# Install all skills
-npx skills add martinffx/atelier
+[`code-review`](skills/code-review/SKILL.md) 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.
 
-# 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
+```text
+rq             # Review the diff to main
+rq develop     # Review against another branch
+rs             # Work through the findings
 ```
 
-### 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` → `design.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:*`)
+It reports findings before changing code. You decide which fixes to apply.
 
-Analytical skills that provide patterns, principles, and deep reasoning. These adapt to your specific situation.
+## What you get
 
-- `oracle-debug` — Systematic debugging, root cause before fixes
-- `oracle-grill-me` — Socratic interrogation of plans against domain model
-- `oracle-domain-modelling` — Build and sharpen the project's domain model
+Atelier installs a focused set of skills for the full development loop:
 
-#### Domain Knowledge (`python:*`, `typescript:*`)
+| Area | Capabilities |
+|------|--------------|
+| Spec workflow | Discovery, research, planning, implementation, validation, and finishing |
+| Thinking | Root-cause debugging, decision grilling, and domain modelling |
+| Delivery | Multi-agent review, subagent coordination, commits, handoffs, and pull requests |
 
-Technology-specific patterns and best practices. These are like having a senior engineer for that stack.
+The CLI also configures three specialist agents for Claude Code, OpenCode, Codex, or Cursor:
 
-**TypeScript (8 skills)**
-- `typescript-api-design` — REST conventions, error responses, pagination
-- `typescript-fastify` — Fastify + TypeBox route handlers
-- `typescript-drizzle-orm` — Type-safe SQL schemas and queries
-- `typescript-dynamodb-toolbox` — Single-table design, GSIs
-- `typescript-functional-patterns` — ADTs, branded types, Option/Result
-- `typescript-effect-ts` — Functional effects, error handling, resources
-- `typescript-build-tools` — Bun, Vitest, Biome, Turborepo
-- `typescript-testing` — Mocking, MSW, snapshot testing
+| Agent | Role |
+|-------|------|
+| **Sentinel** | Fast codebase reconnaissance and review triage |
+| **Oracle** | Requirements, trade-offs, and adversarial analysis |
+| **Architect** | Domain modelling, system design, and architecture review |
 
-**Python (8 skills)**
-- `python-architecture` — Functional core/shell, DDD, layered architecture
-- `python-fastapi` — Pydantic validation, dependency injection, OpenAPI
-- `python-sqlalchemy` — ORM patterns, queries, async, upserts
-- `python-temporal` — Workflow orchestration, activities, error handling
-- `python-modern-python` — Type hints, generics, pattern matching
-- `python-monorepo` — uv workspaces, mise task orchestration
-- `python-testing` — Stub-driven TDD, pytest patterns
-- `python-build-tools` — uv, ruff, basedpyright, pytest config
+Run `npx @martinffx/atelier@latest --help` for CLI commands and options. Each skill contains its own operating instructions and loads when its context applies.
 
-#### Utility Skills (`code:*`)
+## Ecosystem
 
-Task-specific tools you invoke when you need them.
+Language-specific guidance lives in companion repositories:
 
-- `code-commit` — Generate and validate conventional commits
-- `code-handoff` — Compact conversation into handoff document
-- `code-pull-request` — Create, comment on, and merge GitHub pull requests or GitLab merge requests
-- `code-review` — Multi-agent code review with specialized reviewers
-- `code-subagents` — Dispatch patterns for parallel implementation
+- [Python skills](https://github.com/martinffx/python-skills)
+- [TypeScript skills](https://github.com/martinffx/typescript-skills)
 
-Skills are auto-invoked based on their description when you work with relevant technologies. No commands needed—just install and AI agents will use them when appropriate.
+## Rationale and inspiration
 
-## How Skills Work
+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](https://www.martinrichards.me/post/building_your_own_agent_harness/) explains the thinking behind it.
 
-Skills are auto-invoked based on context. When you say "create a spec for user auth", the AI matches this to `spec-brainstorm` and loads it automatically.
+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.
 
-### Namespace Philosophy
+Atelier draws on spec-driven development and several projects that informed its approach to agent collaboration:
 
-Skills are organized into four categories based on their role:
+- [Agent OS](https://github.com/buildermethods/agent-os) for discovering project standards and shaping lightweight specs.
+- [OpenSpec](https://github.com/Fission-AI/OpenSpec) for fluid, artifact-guided workflows that support iteration and brownfield development.
+- [GitHub Spec Kit](https://github.com/github/spec-kit) for making specifications central to a structured specify, plan, tasks, and implement workflow.
+- [Superpowers](https://github.com/obra/superpowers) for composable skills, mandatory engineering workflows, TDD, and evidence-based verification.
+- [Matt Pocock's Skills](https://github.com/mattpocock/skills) for small, adaptable skills grounded in practical engineering and developer control.
 
-| Category | Prefix | Type | Invocation | Output | Flexibility |
-|----------|--------|------|------------|--------|-------------|
-| **Workflow** | `spec:` | Process | User/previous skill | Artifact | Follow exactly |
-| **Thinking** | `oracle:` | Analytical | Context-driven | Guidance | Adapt to context |
-| **Domain Knowledge** | `python:`, `typescript:` | Technology | Context-driven | Patterns | Adapt to context |
-| **Utility** | `code:` | Task-specific | User command | Result | Use as needed |
+Some Atelier skills have more direct lineage:
 
-- **Workflow** (`spec:`) — Sequential steps that produce artifacts. Follow them in order.
-- **Thinking** (`oracle:`) — Analytical capabilities that reason about your specific problem.
-- **Domain Knowledge** (`python-*`, `typescript-*`) — Stack-specific patterns and best practices. Like having a senior engineer for that technology.
-- **Utility** (`code:`) — Task-specific tools you invoke directly when needed.
+| Atelier skill | Source skill | Relationship |
+|---------------|--------------|--------------|
+| [`atelier-orchestrator`](skills/atelier-orchestrator/SKILL.md) | Superpowers [`using-superpowers`](https://github.com/obra/superpowers/tree/main/skills/using-superpowers) | Adapted from its mandatory skill-routing discipline. |
+| [`spec-brainstorm`](skills/spec-brainstorm/SKILL.md) | Superpowers [`brainstorming`](https://github.com/obra/superpowers/tree/main/skills/brainstorming) | Adapted from its conversational discovery and section-by-section design approval. |
+| [`spec-plan`](skills/spec-plan/SKILL.md) | Superpowers [`writing-plans`](https://github.com/obra/superpowers/tree/main/skills/writing-plans) | Inspired by its explicit, verifiable implementation plans. |
+| [`spec-implement`](skills/spec-implement/SKILL.md) | Superpowers [`executing-plans`](https://github.com/obra/superpowers/tree/main/skills/executing-plans) and [`test-driven-development`](https://github.com/obra/superpowers/tree/main/skills/test-driven-development) | Inspired by plan-driven execution and test-first feedback loops. |
+| [`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. |
+| [`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-debug`](skills/oracle-debug/SKILL.md) | Superpowers [`systematic-debugging`](https://github.com/obra/superpowers/tree/main/skills/systematic-debugging) and Matt Pocock's [`diagnosing-bugs`](https://github.com/mattpocock/skills/tree/main/skills/engineering/diagnosing-bugs) | Adapted from their root-cause-first debugging workflows. |
 
-### The Spec Workflow
+[`code-commit`](skills/code-commit/SKILL.md) follows the [Conventional Commits](https://www.conventionalcommits.org/) specification.
 
-```mermaid
-graph LR
-    A[spec-brainstorm] -->|design.md| B[spec-plan]
-    B -->|plan.json| C[spec-implement]
-    C --> D[spec-finish]
-    D -.->|invokes| E[code-pull-request]
-    
-    B -.->|design flaw| A
-    C -.->|missing tasks| B
-    C -.->|fundamental issue| A
-    D -.->|bugs found| C
-```
-
-**Standard flow:**
-1. **Research** - Discovery + research + architecture → `design.md`
-2. **Plan** - Break into tasks → `plan.json`
-3. **Implement** - Execute with TDD
-4. **Finish** - Validate, review, and open the PR
-
-**Iteration is normal** - Backflows (dotted lines) are expected when:
-- Planning reveals design flaws → back to research
-- Implementation finds missing tasks → update plan
-- Validation finds bugs → back to implement
-
-### When to Use Which Skill
-
-| User says | Skill invoked |
-|------------|---------------|
-| "Create a spec for X" | spec-brainstorm |
-| "What should we build" | spec-brainstorm |
-| "Write a plan" | spec-plan |
-| "Implement this" | spec-implement |
-| "Review this code" | code-review |
-| "Open a PR" | code-pull-request |
-| "Merge this PR" | code-pull-request |
-| "Read PR comments" | code-pull-request |
-| "Leave a comment on the PR" | code-pull-request |
-| "Debug this" | oracle-debug |
+Atelier adapts these ideas into an opinionated toolkit that works across harnesses. It does not claim to have invented the practices it uses.
 
 ## Development
 
-For local development with Claude Code, use the `--plugin-dir` flag to load skills directly:
+Load the repository directly in Claude Code:
 
 ```bash
 claude --plugin-dir ./atelier
 ```
 
-Restart Claude Code after making changes to reload skills.
-
-To work on the CLI itself:
+Build and test the CLI:
 
 ```bash
-# Build the CLI
 bun run build
-
-# Test locally
-bun ./dist/atelier.js init --yes
+bun test
+bun run typecheck
 ```
 
+Restart your coding harness after changing skills so it reloads their definitions.
+
 ## License
 
 MIT Copyright (c) 2026 Martin Richards

package/agents/architect.md

@@ -9,7 +9,7 @@ You are the **Architect**, a senior technical designer and systems thinker. Your
 
 - Design data models, database schemas, and API contracts
 - Apply architectural patterns (DDD, hexagonal, layered) where appropriate
-- Break down features into dependency-ordered implementation tasks
+- Provide dependency-ordered implementation-task recommendations for Spec-backed Plans
 - Ensure designs align with project standards and constraints
 
 ## Skills
@@ -24,15 +24,15 @@ Before finishing, confirm you have:
 - [ ] Defined properties, types, and validation rules for each model
 - [ ] Specified API endpoints with methods, paths, and request/response contracts
 - [ ] Listed error cases and handling strategy
-- [ ] Broken work into dependency-ordered tasks (entity → repository → service → router)
-- [ ] Written or updated the Technical Design section in `design.md`
-- [ ] Written or updated `plan.json` with the task breakdown
+- [ ] For Spec-backed Plan work, provided dependency-ordered task recommendations (entity → repository → service → router)
+- [ ] For Spec-backed Plan work, written or updated the Technical Design section in `design.md`
 
 ## Boundaries
 
 - DO focus on technical design and architecture
-- DO create dependency-ordered task lists
+- DO provide dependency-ordered task recommendations for Spec-backed Plans
+- DON'T write or update `plan.json` (that's `spec-plan`)
 - DO apply architectural patterns and load relevant skills
 - DON'T write implementation code (that's for `spec-implement`)
 - DON'T conduct discovery interviews (that's `oracle`)
-- DON'T handle file operations or template application (that's `recon`)
+- DON'T handle file operations or template application (that's `sentinel`)

package/agents/oracle.md

@@ -28,7 +28,7 @@ Before finishing, confirm you have:
 - [ ] Documented business rules, validations, and limits
 - [ ] Defined scope—what is included and what is explicitly out of scope
 - [ ] Generated 2–3 alternative approaches with trade-offs if the problem is complex
-- [ ] Written or updated the Requirements section in `design.md`
+- [ ] For Spec-backed Plan work, written or updated the Requirements section in `design.md`
 
 ## Boundaries
 

package/agents/{recon.md → sentinel.md}

@@ -1,9 +1,9 @@
 ---
-name: recon
-description: Fast codebase reconnaissance and exploration, concise summarization of findings, precise location of relevant context, and efficient workspace preparation through targeted file operations and template application
+name: sentinel
+description: Fast codebase reconnaissance and exploration, concise summaries of findings, precise location of relevant context, and efficient workspace preparation through targeted file operations and template application
 ---
 
-You are the **Recon**, a fast reconnaissance agent. Your job is to explore codebases, summarize what you find, highlight relevant context, and point others to exactly where things live. You move quickly, read minimally, and never break existing work.
+You are the **Sentinel**, a fast reconnaissance agent. Your job is to explore codebases, summarize what you find, highlight relevant context, and point others to exactly where things live. You move quickly, read minimally, and never break existing work.
 
 ## Role