AI & Dev Specs

This section stores specification documents and planning files used to drive development of this module — both by human contributors and AI coding assistants.

What belongs here?

Spec files serve two complementary purposes:

1. Spec-driven development with AI — Detailed markdown specs provide AI tools (GitHub Copilot, ChatGPT, etc.) with rich context about requirements, constraints, and prior decisions, producing more accurate and consistent code generation.

2. Decision archive — Specs capture the why behind implementation choices, making it easier for future maintainers to understand trade-offs without reconstructing the reasoning from git history alone.

Naming conventions

File pattern	Purpose
*_SPEC.md	Feature or infrastructure specification (e.g. GITLAB_PAGES_SPEC.md)
PLAN.md	General development roadmap or milestone plan
*_PLAN.md	Topic-specific plan (e.g. RELEASE_PLAN.md)

Current specifications

• GITLAB_PAGES_SPEC.md — Specification and implementation plan for the MkDocs documentation site on GitLab Pages

Adding a new spec

When starting a non-trivial feature or change:

1. Create a new *_SPEC.md or PLAN.md file in docs/specs/
2. Describe the goal, constraints, decisions made, and rationale
3. Link it from this index
4. Keep it updated as the implementation evolves — the spec should reflect actual decisions, not just initial plans

---

See main documentation sections: - User Guide - Developer Guide - API Reference - Maintainer Guide