@martinffx/atelier 1.3.0 → 2.0.0

package/.codex-plugin/plugin.json

@@ -0,0 +1,27 @@
+{
+  "name": "atelier",
+  "version": "1.2.2",
+  "description": "Personal development toolkit - spec-driven development, code quality, deep thinking, and ecosystem patterns",
+  "author": {
+    "name": "Martin Richards"
+  },
+  "homepage": "https://github.com/martinffx/atelier",
+  "repository": "https://github.com/martinffx/atelier",
+  "license": "MIT",
+  "keywords": [
+    "spec-driven-development",
+    "code-quality",
+    "deep-thinking",
+    "typescript",
+    "python",
+    "codex"
+  ],
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "Atelier",
+    "shortDescription": "Personal development toolkit - spec-driven development, code quality, deep thinking, and ecosystem patterns",
+    "developerName": "Martin Richards",
+    "category": "Developer Tools",
+    "capabilities": ["Read"]
+  }
+}

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.
+
+## [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)
+
+
+### Features
+
+* **code-commit:** improve commit workflow ([a5e8973](https://github.com/martinffx/atelier/commit/a5e89735ec8623ea24effec326010136cb546735))
+* **codex:** add Codex harness support and refactor for multi-harness CLI ([#38](https://github.com/martinffx/atelier/issues/38)) ([ce381d2](https://github.com/martinffx/atelier/commit/ce381d25c8b91734bf84288e1c9522e1a914a5b9))
+* **opencode:** add OpenAI provider support ([3f956bd](https://github.com/martinffx/atelier/commit/3f956bd0fb371a00147d2a92c5503d0c853215e2))
+
+
+### Bug Fixes
+
+* **code-handoff:** write handoffs to project directory ([abd6ec9](https://github.com/martinffx/atelier/commit/abd6ec90cbe614cedff3b0a2059ca9c6743d35ba))
+
 ## [1.3.0](https://github.com/martinffx/atelier/compare/v1.2.2...v1.3.0) (2026-07-17)
 
 

package/README.md

@@ -6,129 +6,158 @@
 >
 > [Wikipedia](https://en.wikipedia.org/wiki/Atelier)
 
-A personal development toolkit for AI agents - spec-driven development, code quality, deep thinking, and ecosystem patterns.
+A personal development toolkit for AI agents. It covers spec-driven development, code quality, deep thinking, and ecosystem patterns.
 
-## Quick Start
+Atelier includes skills installed with `npx skills` and a small CLI for generating agent definitions and configuration for supported harnesses.
 
-Install Atelier with a single command. It auto-detects your AI harness (Claude Code or OpenCode), configures agents, and sets up session hooks:
+## Quick start
 
-```bash
-# Initialize atelier in your project
-bunx @martinffx/atelier@latest init
+Install Atelier, then choose the harness you use. The CLI configures agents and harness-native settings for Claude Code, OpenCode, Codex, and Cursor.
 
-# Or install everything including skills
-bunx @martinffx/atelier@latest init --all
+```bash
+# Initialize atelier for your harness
+npx @martinffx/atelier@latest init --harness <claude|opencode|codex|cursor>
 
 # Non-interactive mode (CI/CD)
-bunx @martinffx/atelier@latest init --yes
+npx @martinffx/atelier@latest init --harness <claude|opencode|codex|cursor> --yes
 ```
 
-That's it. Your project is now configured for spec-driven development.
+Your project is ready to use the spec workflow.
+
+## 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](https://www.martinrichards.me/post/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](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.
+
+Some Atelier skills have more direct lineage:
+
+| Atelier skill | Source skill | Relationship |
+|---------------|--------------|--------------|
+| [`spec-orchestrator`](skills/spec-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. |
+
+Elsewhere, [`typescript-functional-patterns`](skills/typescript-functional-patterns/SKILL.md) draws on Rastrian's [Why Reliability Demands Functional Programming, ADTs, Safety and Critical Infrastructure](https://blog.rastrian.dev/post/why-reliability-demands-functional-programming-adts-safety-and-critical-infrastructure), and [`code-commit`](skills/code-commit/SKILL.md) follows the [Conventional Commits](https://www.conventionalcommits.org/) specification.
 
-## What Gets Installed
+Atelier adapts these ideas into an opinionated toolkit that works across harnesses. It does not claim to have invented the practices it uses.
 
-Atelier sets up three things in your project:
+## What gets installed
 
-### 1. Skills (28 available)
+Atelier sets up the following:
 
-Specialized knowledge modules that auto-invoke based on context. Install them via the CLI (`--all` flag) or separately:
+### 1. Skills (29 available)
+
+Skills are specialized knowledge modules that load when their context applies. Install them separately:
 
 ```bash
 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 |
+### 2. Agent personas (3 subagents)
 
-Agents are generated into `.claude/agents/` or `.opencode/agents/` with harness-specific model identifiers.
+Agent definitions are generated for each supported harness with appropriate models:
 
-### 3. Session Hooks
+| Agent | Role | Claude | OpenCode | Codex | Cursor |
+|-------|------|--------|----------|-------|--------|
+| **Sentinel** | Fast codebase reconnaissance | haiku | deepseek-v4-flash | gpt-5.6-luna | composer-2.5 |
+| **Oracle** | Strategic thinking, requirements, analysis | opus | kimi-k2.6 | gpt-5.6-sol | claude-opus-4-8-high |
+| **Architect** | DDD, system design, architecture | opus | deepseek-v4-pro | gpt-5.6-sol | gpt-5.6-sol-medium |
 
-Context injection that runs on every session start, clear, or compact:
+The CLI writes agents to harness-specific locations: `.claude/agents/`, `.opencode/agent/`, `.codex/agents/`, or `~/.cursor/agents/`. It uses each harness's model identifiers. Cursor's primary model and `~/.cursor/cli-config.json` remain user-managed. Atelier only creates its three global subagents.
 
-- **Claude Code**: `hooks/atelier-session-start` outputs project context as JSON
-- **OpenCode**: `.opencode/plugins/atelier.js` provides config and transform hooks
+The agent personas carry a light *Matrix* theme. Sentinel takes after the Sentinels: it moves quickly through the codebase, locating what matters and reporting back. Oracle clarifies human needs and choices under uncertainty. Architect turns those requirements into structured technical designs.
 
-### 4. Task Tracking (optional)
+### 3. Task tracking (optional)
 
-The spec workflow skills support **beads** for dependency-aware task tracking:
+The spec workflow can use **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.
+Beads provides `bd ready` to find unblocked tasks, `bd dep add` to manage dependencies, and `bd list` to show progress. Harness-native todo systems do not provide the same dependency support.
 
-**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).
+If beads is unavailable, skills use the harness's native todo system: TodoWrite for Claude Code or built-in todos for OpenCode.
 
-### 5. Configuration
+### 4. Configuration
 
 Single source of truth in `.atelier/config.json`:
 
 ```json
 {
   "version": "1.0.0",
-  "harness": "claude",
   "skills_source": "martinffx/atelier",
-  "agents": [
-    { "template": "scout", "model": "haiku" },
-    { "template": "oracle", "model": "opus" },
-    { "template": "architect", "model": "opus" }
-  ]
+  "skills_path": "~/.agents/skills",
+  "claude": {
+    "provider": "anthropic",
+    "default_model": "opusplan",
+    "agents": [
+      { "template": "sentinel", "name": "sentinel", "model": "haiku" },
+      { "template": "oracle", "name": "oracle", "model": "opus" },
+      { "template": "architect", "name": "architect", "model": "opus" }
+    ]
+  }
 }
 ```
 
-## CLI Commands
+## CLI commands
 
 ### `init` (default)
 
-Initialize atelier in the current project.
+Initialize Atelier for one harness. Run the command again for each additional harness.
 
 ```bash
-bunx @martinffx/atelier@latest init [options]
+npx @martinffx/atelier@latest init --harness <claude|opencode|codex|cursor> [options]
 ```
 
-**Options:**
-- `--harness <type>` - Force harness type (`claude` or `opencode`)
-- `--all` - Also install skills via `npx skills add`
+Options:
+- `--harness <type>` - Harness type (`claude`, `opencode`, `codex`, or `cursor`)
 - `--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.
+You can safely re-run `init` for the same harness. It regenerates its files and does not delete existing files unless you switch harnesses.
 
 ### `update`
 
-Refresh hooks and agents from the latest templates without touching skills:
+Refresh agents and harness-native config for one harness without touching skills:
 
 ```bash
-bunx @martinffx/atelier@latest update
+npx @martinffx/atelier@latest update --harness <claude|opencode|codex|cursor>
 ```
 
 ### `remove`
 
-Remove all atelier-generated files from the project:
+Remove all atelier-generated files for one harness:
 
 ```bash
-bunx @martinffx/atelier@latest remove
+npx @martinffx/atelier@latest remove --harness <claude|opencode|codex|cursor>
 ```
 
 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.
+This repository includes 29 skills for agent workflows and stack-specific guidance.
 
-### Installing Skills
+### Installing skills
 
-If you didn't use `--all` during init, install skills manually:
+Install skills manually:
 
 ```bash
 # Install all skills
@@ -140,118 +169,117 @@ npx skills add martinffx/atelier --skill python-fastapi
 npx skills add martinffx/atelier --skill spec-brainstorm
 ```
 
-### Skill Types
+### Skill organization
 
-Skills fall into four categories based on what they do:
+Atelier has three core skill namespaces:
 
-#### Workflow Skills (`spec:*`)
+| Namespace | Type | Invocation | Output | Flexibility |
+|-----------|------|------------|--------|-------------|
+| `spec:` | Process | User or previous skill | Plan or artifact | Follow exactly |
+| `oracle:` | Analytical | Context-driven | Guidance | Adapt to context |
+| `code:` | Utility | User | Result | Use as needed |
 
-Process-oriented skills that guide you through structured development workflows. These produce artifacts and should be followed step-by-step.
+#### Workflow (`spec:*`)
 
-- `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
+These skills guide plan-first development. Inline Plans stay in the conversation; substantial
+work uses persisted spec artifacts.
 
-#### Thinking Skills (`oracle:*`)
+- `spec-orchestrator`: select Inline Plan or Spec-backed Plan and route the workflow
+- `spec-brainstorm` → `design.md`: discovery, requirements, and architecture for substantial work
+- `spec-plan`: produce a conversational Inline Plan or persisted `plan.json`
+- `spec-implement`: execute approved Spec-backed Plans with TDD
+- `spec-finish`: validate, review, and prepare Spec-backed Plans for a PR
 
-Analytical skills that provide patterns, principles, and deep reasoning. These adapt to your specific situation.
+#### Thinking (`oracle:*`)
 
-- `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
+These skills provide analytical methods and reasoning patterns that adapt to the problem at hand.
 
-#### Domain Knowledge (`python:*`, `typescript:*`)
+- `oracle-debug`: systematic debugging that finds the root cause before a fix
+- `oracle-grill-me`: Socratic review of plans, specs, decisions, and ideas until ambiguity is resolved, shared understanding is reached, and the resulting domain language and decisions are recorded
+- `oracle-domain-modelling`: build and refine the project's domain model
 
-Technology-specific patterns and best practices. These are like having a senior engineer for that stack.
+#### Utilities (`code:*`)
 
-**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
+These skills handle discrete tasks when you invoke them.
 
-**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
+- `code-commit`: generate and validate conventional commits
+- `code-handoff`: turn a conversation into a 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
 
-#### Utility Skills (`code:*`)
+#### Stack-specific knowledge
 
-Task-specific tools you invoke when you need them.
+Python and TypeScript skills provide technology-specific patterns and practices. They support work across the `spec`, `oracle`, and `code` namespaces.
 
-- `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
-
-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.
+**TypeScript (8 skills)**
+- `typescript-api-design`: REST conventions, error responses, and pagination
+- `typescript-fastify`: Fastify and TypeBox route handlers
+- `typescript-drizzle-orm`: type-safe SQL schemas and queries
+- `typescript-dynamodb-toolbox`: single-table design and GSIs
+- `typescript-functional-patterns`: ADTs, branded types, and Option/Result
+- `typescript-effect-ts`: functional effects, error handling, and resources
+- `typescript-build-tools`: Bun, Vitest, Biome, and Turborepo
+- `typescript-testing`: mocking, MSW, and snapshot testing
 
-## How Skills Work
+**Python (8 skills)**
+- `python-architecture`: functional core/shell, DDD, and layered architecture
+- `python-fastapi`: Pydantic validation, dependency injection, and OpenAPI
+- `python-sqlalchemy`: ORM patterns, queries, async, and upserts
+- `python-temporal`: workflow orchestration, activities, and error handling
+- `python-modern-python`: type hints, generics, and pattern matching
+- `python-monorepo`: uv workspaces and mise task orchestration
+- `python-testing`: stub-driven TDD and pytest patterns
+- `python-build-tools`: uv, ruff, basedpyright, and pytest configuration
 
-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.
+Skills load based on their descriptions when the work calls for them. Install them once, then agents can use them as needed.
 
-### Namespace Philosophy
+## How skills work
 
-Skills are organized into four categories based on their role:
+Skills load from context. For example, "create a spec for user auth" makes
+`spec-orchestrator` select the spec-backed route and invoke `spec-brainstorm`.
 
-| 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 |
+### The planning workflow
 
-- **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.
+For bounded work, `spec-plan` presents a simple Inline Plan for approval, then the agent
+implements it directly. No spec artifacts, task tracking, or persisted-spec execution
+workflow is involved.
 
-### The Spec Workflow
+The full planning workflow is:
 
 ```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
+    B[spec-brainstorm] --> D[design.md]
+    D --> G[oracle-grill-me]
+    G -->|design approved| P[spec-plan: review and approve]
+    G -.->|refine| D
+    P --> J[plan.json]
+    J --> I[spec-implement]
+    I --> F[spec-finish]
+    F --> PR[code-pull-request]
+    I -.->|revise plan| P
+    I -.->|design issue| B
 ```
 
-**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
+The orchestrator chooses one route and states why:
+
+- **Inline Plan (default):** bounded, well-understood work. The plan uses `context`, `scope`,
+  `changes`, `files`, and `validation` in conversation. It creates no spec or tracker artifacts.
+- **Spec-backed Plan:** substantial work that needs discovery, architectural decisions,
+  dependency tracking, durable handoff, or explicit spec artifacts. It uses `design.md` and
+  `plan.json`.
 
-**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
+Both routes require human approval before implementation. File count and estimated duration
+alone do not make work spec-worthy, and the human can override the selected route.
 
-### When to Use Which Skill
+### 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 |
+| "Create a spec for X" | spec-orchestrator → spec-brainstorm |
+| "What should we build" | spec-orchestrator selects the planning route |
+| "Write a plan" | spec-orchestrator → spec-plan (Inline by default) |
+| "Implement this" | spec-orchestrator |
 | "Review this code" | code-review |
 | "Open a PR" | code-pull-request |
 | "Merge this PR" | code-pull-request |
@@ -261,7 +289,7 @@ graph LR
 
 ## Development
 
-For local development with Claude Code, use the `--plugin-dir` flag to load skills directly:
+For local development with Claude Code, load skills directly with `--plugin-dir`:
 
 ```bash
 claude --plugin-dir ./atelier

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