git:20260722.2094f2c to git:20260727.c30bc12

3 added, 181 removed. Audit A to A.

# AGENTS.md

This file provides guidance to AI agents when working with code in this repository.

## Repository Overview

This is Atelier - a personal development toolkit with 29 skills for spec-driven development, deep thinking, code quality, and ecosystem patterns.

## Skills Structure

Skills are located in the `skills/` directory. Each skill is a self-contained module with:

```

skills/{category}-{name}/

├── SKILL.md # Main skill definition

└── references/ # Optional additional context

├── topic-a.md

└── topic-b.md

```

### Skill File Format

Skills use YAML frontmatter for metadata:

```yaml

---

name: skill-name

description: When to use this skill (AI reads this to auto-load)

user-invocable: false # or true if user can call directly

---

```

Skills are auto-invoked based on description match to current context.

## Namespace Philosophy

Skills are organized into three namespaces based on their role:

### spec: - Workflow Skills

- Sequential, state-transforming steps that produce artifacts.

+ Sequential, state-transforming steps that produce an approved plan and may produce artifacts.

- **Process-oriented**: Each skill is a step in a workflow

- **User-invoked**: Called explicitly by user or previous skill

- - **Artifact-producing**: Each produces a concrete output

+ - **Output-producing**: Each produces conversational or persisted output

- **Disciplined**: Must be followed exactly, not adapted

### oracle: - Thinking Skills

Analytical, knowledge-providing skills that inform decisions.

- **Knowledge-oriented**: Provide patterns, principles, guidance

- **Context-driven**: Auto-invoked when relevant context detected

- **Adaptable**: Principles adapted to specific situation

- **Supportive**: Inform workflow decisions, don't produce artifacts

### code: - Utility Skills

Tools and helpers for specific tasks.

- **Task-oriented**: Solve specific problems

- **User-invoked**: Called when needed

- **Standalone**: Can be used independently or within workflow

### Namespace Semantics

|-----------|------|------------|--------|-------------|

- ## Skill Workflow

- ```mermaid

- graph TB

- subgraph "spec-orchestrator"

- O[Route to skill]

- end

- O --> R

- subgraph "spec-brainstorm"

- R1[Discovery] --> R2[Research]

- R2 --> R3[Design]

- R3 --> R4[design.md]

- end

- R4 --> P

- subgraph "spec-plan"

- P1[Draft] --> P2[Annotate]

- P2 --> P3[plan.json]

- end

- P3 --> I

- subgraph "spec-implement"

- I1[TDD] --> I2[Track]

- I2 --> I3[Report]

- end

- I3 --> F

- subgraph "spec-finish"

- F1[Validate] --> F2[Review]

- F2 --> F3[Open PR]

- F3 -.->|invokes| U1[code-pull-request]

- end

- P -.->|design flaw| R

- I -.->|missing tasks| P

- I -.->|fundamental issue| R

- F -.->|bugs found| I

- ```

- ### Hard Transitions

- | After completing... | The ONLY next step is... |

- |---------------------|--------------------------|

- | spec-brainstorm | spec-plan |

- | spec-plan | spec-implement |

- | spec-implement | spec-finish |

- Do NOT jump from requirements to code. Do NOT jump from research to implementation.

- ### Iteration Patterns

- The workflow is not purely linear. Expect backflows:

- - **Plan → Research**: Planning reveals design assumptions are wrong

- - **Implement → Plan**: Implementation reveals missing tasks

- - **Implement → Research**: Implementation reveals fundamental design issue

- - **Finish → Implement**: Validation finds bugs

- If you loop 2+ times on the same issue, stop and ask the human:

- > "We've looped on [issue] twice. Should we reconsider the approach?"

- ### Skill Types

- **Process skills** (spec-brainstorm, spec-plan, spec-implement, spec-finish): Follow exactly.

- Don't adapt away discipline.

- **Knowledge skills** (oracle-grill-me, oracle-domain-modelling): Adapt principles to

- context. These inform decisions within the workflow.

- **Discipline skills** (oracle-debug): Strict methodology that must be followed

- exactly — no adaptation that bypasses root-cause investigation.

- Process skills come first. Knowledge skills get invoked by process skills when needed.

- ## Available Skills

- **Spec-Driven Development** (5 skills)

- - `spec-finish` - Post-implementation validation

- - `spec-implement` - Execute tasks from plan.json

- - `spec-plan` - Implementation plan + tasks → plan.json

- - `spec-brainstorm` - Discovery + research + architecture → design.md

- - `spec-orchestrator` - Skill routing and workflow orchestration

- **Deep Thinking** (3 skills)

- - `oracle-debug` - Systematic debugging, root cause before fixes

- - `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 sharpen the project's domain model

- **TypeScript Patterns** (8 skills)

- - `typescript-api-design` - REST API design patterns

- - `typescript-build-tools` - Bun, Vitest, Biome, Turborepo

- - `typescript-drizzle-orm` - Type-safe SQL for PostgreSQL/MySQL/SQLite/D1

- - `typescript-dynamodb-toolbox` - Single-table design, GSI patterns

- - `typescript-effect-ts` - Functional effects, error handling

- - `typescript-fastify` - Fastify + TypeBox route handlers

- - `typescript-functional-patterns` - ADTs, branded types, Option/Result

- - `typescript-testing` - Mocking, MSW, snapshot testing

- **Python Patterns** (8 skills)

- - `python-architecture` - Functional core/imperative shell, DDD

- - `python-build-tools` - uv, mise, ruff, basedpyright

- - `python-fastapi` - Pydantic validation, dependency injection

- - `python-modern-python` - Type hints, generics, async/await

- - `python-monorepo` - uv workspaces, mise task orchestration

- - `python-sqlalchemy` - ORM patterns, queries, async

- - `python-temporal` - Workflow orchestration, activities

- - `python-testing` - Stub-Driven TDD, layer boundary testing

- **Code Utilities** (5 skills)

- - `code-commit` - Generate and validate conventional commits

- - `code-handoff` - Compact conversation into handoff document for next agent

- - `code-pull-request` - Create, comment on, and merge GitHub pull requests or GitLab merge requests

- - `code-review` - Multi-agent code review with parallel reviewers

- - `code-subagents` - Subagent dispatch patterns for implementation tasks

- ## Installation

- ```bash

- # Install all skills

- npx skills add martinffx/atelier

- # Install specific skill

- npx skills add martinffx/atelier --skill typescript-drizzle-orm

- ```

## Development

For local development with Claude Code:

```bash

claude --plugin-dir ./atelier

```

Restart Claude Code after making changes to reload skills.

-

- ## Beads Issue Tracker

- This project uses **bd (beads)** for issue tracking. Run `bd prime` to see full workflow context and commands.

- ### Quick Reference

- ```bash

- bd ready # Find available work

- bd show <id> # View issue details

- bd update <id> --claim # Claim work

- bd close <id> # Complete work

- ```

- ### Rules

- - Use `bd` for ALL task tracking — do NOT use TodoWrite, TaskCreate, or markdown TODO lists

- - Run `bd prime` for detailed command reference and session close protocol

- - Use `bd remember` for persistent knowledge — do NOT use MEMORY.md files

- ## Session Completion

- **When ending a work session**, you MUST complete ALL steps below. Work is NOT complete until `git push` succeeds.

- **MANDATORY WORKFLOW:**

- 1. **File issues for remaining work** - Create issues for anything that needs follow-up

- 2. **Run quality gates** (if code changed) - Tests, linters, builds

- 3. **Update issue status** - Close finished work, update in-progress items

- 4. **PUSH TO REMOTE** - This is MANDATORY:

- ```bash

- git pull --rebase

- bd dolt push

- git push

- git status # MUST show "up to date with origin"

- ```

- 5. **Clean up** - Clear stashes, prune remote branches

- 6. **Verify** - All changes committed AND pushed

- 7. **Hand off** - Provide context for next session

- **CRITICAL RULES:**

- - Work is NOT complete until `git push` succeeds

- - NEVER stop before pushing - that leaves work stranded locally

- - NEVER say "ready to push when you are" - YOU must push

- - If push fails, resolve and retry until it succeeds

-