# dance-lessons-coach — AI Agent Documentation

This file is the directive document auto-loaded by Mistral Vibe (and Claude Code) when working on `dance-lessons-coach`. It stays short by design (≤ 200 lines, lazy-loading compatible with 128k context). Detailed content lives in `documentation/` and is loaded on demand.

> **Restructured 2026-05-02** : the original 1296-line `AGENTS.md` was split into focused guides under `documentation/` (Tâche 6 of the ARCODANGE migration Claude → Mistral Vibe). See [`documentation/HISTORY.md`](documentation/HISTORY.md) for context.

## 🎯 Project Overview

**dance-lessons-coach** is a Go-based web service with CLI capabilities, featuring:

- RESTful JSON API with Chi router
- High-performance Zerolog logging
- Interface-based architecture
- Context-aware services
- Comprehensive testing (unit + BDD with Godog)

## 🛠️ Tools & Technologies

| Component | Technology | Version |
|---|---|---|
| Language | Go | 1.26.1 |
| Router | Chi | v5.2.5 |
| Logging | Zerolog | v1.35.0 |
| Configuration | Viper | v1.21.0 |
| Testing | Godog (BDD) + std lib | v0.15.1 |
| Telemetry | OpenTelemetry | v1.43.0 |
| Tracing | Jaeger compatible | — |

## 🗺️ Project Structure

```
dance-lessons-coach/
├── adr/                    # Architecture Decision Records (25+)
├── cmd/                    # Entry points (greet, server)
├── pkg/                    # Core logic (config, greet, server, telemetry, bdd, user, ...)
├── features/               # BDD scenarios (.feature files)
├── fixtures/               # BDD test fixtures
├── scripts/                # Server lifecycle, build, test scripts
├── documentation/          # Detailed guides (CLI, API, BDD, etc.)
├── .vibe/skills/           # Project-scoped vibe skills
├── AGENTS.md               # This file (auto-loaded by vibe)
├── AGENT_CHANGELOG.md      # Trace of structural decisions by AI agents
├── CHANGELOG.md            # User-facing changelog
└── README.md               # User documentation
```

## 📚 Detailed Guides (load on demand)

The directive content is intentionally short. For details, point Mistral / Claude at the relevant guide:

| Topic | Reference |
|---|---|
| **CLI commands & server lifecycle** | [`documentation/CLI.md`](documentation/CLI.md) |
| **REST API endpoints** | [`documentation/API.md`](documentation/API.md) |
| **OpenTelemetry / Jaeger** | [`documentation/OBSERVABILITY.md`](documentation/OBSERVABILITY.md) |
| **Troubleshooting** | [`documentation/TROUBLESHOOTING.md`](documentation/TROUBLESHOOTING.md) |
| **Code patterns & examples** | [`documentation/CODE_EXAMPLES.md`](documentation/CODE_EXAMPLES.md) |
| **Roadmap & future enhancements** | [`documentation/ROADMAP.md`](documentation/ROADMAP.md) |
| **Development phases (history)** | [`documentation/HISTORY.md`](documentation/HISTORY.md) |
| **Agent workflows & best practices** | [`documentation/AGENT_USAGE_GUIDE.md`](documentation/AGENT_USAGE_GUIDE.md) |
| **BDD testing** | [`documentation/BDD_GUIDE.md`](documentation/BDD_GUIDE.md) |
| **Version management** | [`documentation/version-management-guide.md`](documentation/version-management-guide.md) |
| **Local CI/CD testing** | [`documentation/local-ci-cd-testing.md`](documentation/local-ci-cd-testing.md) |
| **Gitmoji cheatsheet** | [`documentation/GITMOJI_CHEATSHEET.md`](documentation/GITMOJI_CHEATSHEET.md) |
| **User-facing changelog** | [`CHANGELOG.md`](CHANGELOG.md) |
| **AI agent decisions log** | [`AGENT_CHANGELOG.md`](AGENT_CHANGELOG.md) |

## 📝 Architecture Decision Records (ADRs)

The project maintains comprehensive ADRs documenting all major architectural choices. See [`adr/README.md`](adr/README.md) for the index and process.

**Key decisions** (load the corresponding ADR for full context):

- **Language**: Go 1.26.1 ([ADR-0001](adr/0001-go-1.26.1-standard.md))
- **Routing**: Chi router ([ADR-0002](adr/0002-chi-router.md))
- **Logging**: Zerolog ([ADR-0003](adr/0003-zerolog-logging.md))
- **Design**: Interface-based ([ADR-0004](adr/0004-interface-based-design.md))
- **Shutdown**: Graceful with readiness ([ADR-0005](adr/0005-graceful-shutdown.md))
- **Config**: Viper ([ADR-0006](adr/0006-configuration-management.md))
- **Observability**: OpenTelemetry ([ADR-0007](adr/0007-opentelemetry-integration.md))
- **Testing**: BDD with Godog ([ADR-0008](adr/0008-bdd-testing.md))
- **Hybrid testing strategy**: ([ADR-0009](adr/0009-hybrid-testing-approach.md))
- **CLI**: Cobra subcommands ([ADR-0015](adr/0015-cli-subcommands-cobra.md))
- **CI/CD**: Trunk-based development ([ADR-0017](adr/0017-trunk-based-development-workflow.md))

To add a new ADR: copy an existing one (`adr/0001-*.md`) as a template, edit, then update `adr/README.md`.

## 🤖 AI Agent Information

**Default agent** (Mistral Vibe CLI):

- **Model**: `mistral-medium-3.5` (via alias `mistral-vibe-cli-latest` — devstral-2 lineage)
- **Role**: Development assistant
- **Capabilities**: code generation, refactoring, test creation, documentation, architecture guidance, best-practices enforcement

For agent-specific workflows (programmer agent, product owner agent, BDD test generation), see [`documentation/AGENT_USAGE_GUIDE.md`](documentation/AGENT_USAGE_GUIDE.md).

For migration context (Claude Code → Mistral Vibe in progress), see `~/.vibe/plans/migration-claude-vers-mistral-phase-1.md`.

## 📝 Commit Conventions

Conventional Commits + gitmoji. Full reference and tooling in the project skill:

- **Skill**: [`.vibe/skills/commit-message/`](.vibe/skills/commit-message/) (auto-loaded by vibe in this project)
- **Cheatsheet**: [`documentation/GITMOJI_CHEATSHEET.md`](documentation/GITMOJI_CHEATSHEET.md)

Quick rule: every commit starts with a gitmoji + conventional type (e.g., `✨ feat: add user authentication`, `🐛 fix: prevent race condition`, `📝 docs: update API guide`).

## 📋 BDD Feature Structure

All user stories and BDD features follow the conventions in [ADR-0008 — BDD Testing](adr/0008-bdd-testing.md) and the practical guide [`documentation/BDD_GUIDE.md`](documentation/BDD_GUIDE.md). Scenario isolation pattern is detailed in [ADR-0025](adr/0025-bdd-scenario-isolation-strategies.md).

## 🗑️ Retention Policy

| Domain | Policy |
|---|---|
| **ADRs** | Review quarterly. Deprecate via `Status: Deprecated`. Remove after 6 months of deprecation. |
| **Documentation** | Archive completed projects to `archive/`. Remove after 12 months. |
| **Scripts** | Move unused to `scripts/deprecated/`. Remove after 6 months. |
| **Skills** | Move unused to `.vibe/skills/deprecated/`. Remove after 6 months. |

## 📞 Support

For issues or questions:

1. Check the relevant guide above (table "Detailed Guides")
2. Review the corresponding ADR
3. Examine existing implementations in `pkg/`
4. Consult the agent's reasoning trace (sessions in `~/.vibe/logs/session/`) for context-rich help
5. As last resort, consult Go / Chi / Zerolog / Viper upstream documentation