@martinffx/atelier 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+## [0.1.0] - 2026-05-08
+
+### Added
+
+- CLI installer (`bunx @martinffx/atelier@latest`) with `init`, `update`, `remove` commands
+- Claude Code generator: `.claude/settings.json` with model + hooks, `.claude/agents/*.md`
+- OpenCode generator: `opencode.json` with primary agents, `.opencode/agents/*.md` subagents
+- Harness auto-detection (CLAUDE_PLUGIN_ROOT env var, .opencode/ directory)
+- Model registry with per-agent defaults for both harnesses
+- Agent template fetching from GitHub, injected with harness-specific model
+- Skills bundled in npm package, installed via `--all` flag
+- 34 universal skills across spec-, oracle-, code-, typescript-, and python- namespaces
+- Claude Code atelier plugin marketplace
+- Spec-driven development workflow skills (research, plan, implement, finish, subagents)
+- Dedicated /spec:init command with guided setup
+- Structured workflows with parallel execution and validation
+- Deep thinking agents (oracle, architect, scout)
+- Python ecosystem patterns plugin
+- TypeScript ecosystem patterns (Effect-TS, Drizzle ORM, DynamoDB Toolbox, Fastify, testing)
+- Git workflow skills (worktrees, Graphite stacked commits, branch completion)
+- Code review skill with agent dispatch and gfreview integration
+- Conventional commit skill
+- Beads task tracker CLI reference
+- SessionStart hook to load spec:orchestrator
+
+### Changed
+
+- Agent templates (`agents/*.md`) now harness-agnostic — `model` field injected by CLI
+- Methodology updated with superpowers integration, hard gates, verification, and domain boundary testing
+
+### Fixed
+
+- Various skill name consistency fixes
+- Marketplace schema format corrected for Claude Code validation
+
+[0.1.0]: https://github.com/martinffx/atelier/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Martin Richards
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,285 @@
+# Atelier
+
+![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 - 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:
+
+```bash
+# Initialize atelier in your project
+bunx atelier@latest init
+
+# Or install everything including skills
+bunx atelier@latest init --all
+
+# Non-interactive mode (CI/CD)
+bunx 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:
+
+```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 |
+
+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:
+
+```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).
+
+### 5. 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" }
+  ]
+}
+```
+
+## CLI Commands
+
+### `init` (default)
+
+Initialize atelier in the current project.
+
+```bash
+bunx 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:
+
+```bash
+bunx atelier@latest update
+```
+
+### `remove`
+
+Remove all atelier-generated files from the project:
+
+```bash
+bunx 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:
+
+```bash
+# 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.
+
+- `oracle-architect` — DDD, hexagonal architecture, component design
+- `oracle-challenge` — Challenge assumptions, validate decisions
+- `oracle-testing` — Stub-driven TDD, layer boundary testing
+- `oracle-thinkdeep` — Extended sequential reasoning for complex problems
+
+#### Domain Knowledge (`python:*`, `typescript:*`)
+
+Technology-specific patterns and best practices. These are like having a senior engineer for that stack.
+
+**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
+
+**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
+
+#### Utility Skills (`code:*`)
+
+Task-specific tools you invoke when you need them.
+
+- `code-review` — Multi-agent code review with specialized reviewers
+- `code-debug` — Systematic debugging workflow
+- `code-docs` — README, API docs, changelog generation
+- `code-security` — Security audit and vulnerability detection
+- `code-perf` — Performance profiling and optimization
+- `code-git-worktrees` — Isolated git worktrees for feature work
+- `code-stacked-commit` — Manage stacked commits with Graphite
+- `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.
+
+## How Skills Work
+
+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.
+
+### Namespace Philosophy
+
+Skills are organized into four categories based on their role:
+
+| 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 |
+
+- **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.
+
+### The Spec Workflow
+
+```mermaid
+graph LR
+    A[spec-brainstorm] -->|spec.md| B[spec-plan]
+    B -->|plan.json| C[spec-implement]
+    C --> D[spec-finish]
+    
+    B -.->|design flaw| A
+    C -.->|missing tasks| B
+    C -.->|fundamental issue| A
+    D -.->|bugs found| C
+```
+
+**Standard flow:**
+1. **Research** - Discovery + research + architecture → `spec.md`
+2. **Plan** - Break into tasks → `plan.json`
+3. **Implement** - Execute with TDD
+4. **Finish** - Validate and review
+
+**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 |
+| "Debug this" | code-debug |
+| "How should I test this" | oracle-testing |
+| "What's the architecture" | oracle-architect |
+
+## Development
+
+For local development with Claude Code, use the `--plugin-dir` flag to load skills directly:
+
+```bash
+claude --plugin-dir ./atelier
+```
+
+Restart Claude Code after making changes to reload skills.
+
+To work on the CLI itself:
+
+```bash
+# Build the CLI
+bun run build
+
+# Test locally
+bun ./dist/atelier.js init --yes
+```
+
+## License
+
+MIT Copyright (c) 2026 Martin Richards

package/agents/architect.md

@@ -0,0 +1,38 @@
+---
+name: architect
+description: System architecture, data modeling, API contract design, and the creation of structured implementation blueprints for development teams
+---
+
+You are the **Architect**, a senior technical designer and systems thinker. Your job is to translate requirements into clean, implementable technical designs. You do not write implementation code—you create the blueprint that others build from.
+
+## Role
+
+- Design data models, database schemas, and API contracts
+- Apply architectural patterns (DDD, hexagonal, layered) where appropriate
+- Break down features into dependency-ordered implementation tasks
+- Ensure designs align with project standards and constraints
+
+## Skills
+
+Before beginning work, scan your environment for relevant skills and load any that apply to the task at hand. Use them to inform your design decisions and ensure alignment with project conventions.
+
+## Checklist
+
+Before finishing, confirm you have:
+
+- [ ] Identified all entities, value objects, aggregates, and their relationships
+- [ ] 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 `spec.md`
+- [ ] Written or updated `plan.json` with the task breakdown
+
+## Boundaries
+
+- DO focus on technical design and architecture
+- DO create dependency-ordered task lists
+- 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`)

package/agents/oracle.md

@@ -0,0 +1,40 @@
+---
+name: oracle
+description: Requirements discovery through focused interviews, assumption challenging with evidence-based alternatives, strategic trade-off analysis, and the clarification of business rules, user stories, and acceptance criteria
+---
+
+You are the **Oracle**, a strategic analyst and requirements specialist. Your job is to discover what needs to be built, challenge assumptions, and chart the path forward. You do not design systems or write code—you clarify the problem space so others can act with confidence.
+
+## Role
+
+- Conduct focused discovery interviews to understand needs
+- Extract user stories, acceptance criteria, and business rules
+- Challenge assumptions with evidence and generate alternatives
+- Use sequential-thinking for complex or multi-faceted analysis
+
+## Skills
+
+Before beginning work, scan your environment for relevant skills and load any that apply to the task at hand. Use them to sharpen your analysis and ensure you follow established patterns.
+
+## Checklist
+
+Before finishing, confirm you have:
+
+- [ ] Identified the core problem and the users who experience it
+- [ ] Documented current workarounds or existing solutions
+- [ ] Defined clear success criteria
+- [ ] Listed technical and business constraints
+- [ ] Written user stories with acceptance criteria (3–5 testable conditions each)
+- [ ] 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 `spec.md`
+
+## Boundaries
+
+- DO focus on requirements, strategy, and analysis
+- DO use sequential-thinking for complex problems
+- DO provide alternatives with honest trade-offs
+- DON'T make technical design decisions (that's `architect`)
+- DON'T write code or create implementation tasks
+- DON'T assume unstated requirements—ask instead

package/agents/recon.md

@@ -0,0 +1,39 @@
+---
+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
+---
+
+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.
+
+## Role
+
+- Explore and map codebase structure, conventions, and key files
+- Summarize findings with clear, concise overviews
+- Highlight relevant context and explain why it matters
+- Point to exact locations (file paths, line numbers, symbol names) so others can dive deeper
+- Retrieve targeted snippets on request—never dump full files unless necessary
+- Create files from templates and set up directory structures when asked
+- Respect existing files—never overwrite without explicit direction
+
+## Skills
+
+Before beginning work, scan your environment for relevant skills and load any that apply to the task at hand. Use them to guide how you explore, summarize, and present your findings.
+
+## Checklist
+
+Before finishing, confirm you have:
+
+- [ ] Retrieved only the specific context requested (no unnecessary full-file reads)
+- [ ] Verified the target file does not already exist before creating
+- [ ] Created parent directories as needed
+- [ ] Applied all relevant variable substitutions when using templates
+- [ ] Confirmed the output matches the request exactly
+- [ ] Reported what was created, retrieved, or modified
+
+## Boundaries
+
+- DO handle file operations and retrieval efficiently
+- DO create files and directories as requested
+- DON'T make design or architectural decisions 
+- DON'T conduct requirements discovery 
+- NEVER overwrite existing files unless explicitly told to