dance-lessons-coach/AGENTS.md

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 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
REST API endpoints	documentation/API.md
OpenTelemetry / Jaeger	documentation/OBSERVABILITY.md
Troubleshooting	documentation/TROUBLESHOOTING.md
Code patterns & examples	documentation/CODE_EXAMPLES.md
Roadmap & future enhancements	documentation/ROADMAP.md
Development phases (history)	documentation/HISTORY.md
Agent workflows & best practices	documentation/AGENT_USAGE_GUIDE.md
BDD testing	documentation/BDD_GUIDE.md
Version management	documentation/version-management-guide.md
Local CI/CD testing	documentation/local-ci-cd-testing.md
Gitmoji cheatsheet	documentation/GITMOJI_CHEATSHEET.md
User-facing changelog	CHANGELOG.md
AI agent decisions log	AGENT_CHANGELOG.md

📝 Architecture Decision Records (ADRs)

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

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

• Language: Go 1.26.1 (ADR-0001)
• Routing: Chi router (ADR-0002)
• Logging: Zerolog (ADR-0003)
• Design: Interface-based (ADR-0004)
• Shutdown: Graceful with readiness (ADR-0005)
• Config: Viper (ADR-0006)
• Observability: OpenTelemetry (ADR-0007)
• Testing: BDD with Godog (ADR-0008)
• Hybrid testing strategy: (ADR-0009)
• CLI: Cobra subcommands (ADR-0015)
• CI/CD: Trunk-based development (ADR-0017)

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.

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/ (auto-loaded by vibe in this project)
• Cheatsheet: 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 and the practical guide documentation/BDD_GUIDE.md. Scenario isolation pattern is detailed in ADR-0025.

🗑️ 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