AGENTS.md git:20260722.2094f2cA

Immutable. This exact content never changes and is served at /api/v1/blob/268c29e193aa16f9.

# 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

| Namespace | Type | Invocation | Output | Flexibility |
|-----------|------|------------|--------|-------------|
| spec: | Process | User/previous skill | Artifact | Follow exactly |
| oracle: | Knowledge | Context-driven | Guidance | Adapt to context |
| code: | Utility | User | Result | Use as needed |

## 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.

<!-- BEGIN BEADS INTEGRATION v:1 profile:minimal hash:ca08a54f -->
## 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
<!-- END BEADS INTEGRATION -->