git:20260717.e373c12 to git:20260722.2094f2c

1 added, 1 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.

- **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

- **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 interrogation of plans against domain model and documented decisions

+ - `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