📝 docs(restructure): split AGENTS.md (1296 → 130 lines) + 9 focused guides #17

arcodange · 2026-05-02T23:57:24+02:00

arcodange commented

2026-05-02 23:57:24 +02:00

Summary

Refactor AGENTS.md from a 1296-line monolith into a 130-line directive file + 9 focused guides. Done as Tâche 6 of the ARCODANGE Phase 1 migration (Claude Code → Mistral Vibe), driven by the lazy-loading constraint of the 128k context Mistral.

Why — Mistral Vibe auto-loads AGENTS.md at every session start. A 1296-line file consumes ~30-40k tokens before the user's first prompt, leaving a small window for actual reasoning on a 128k-context model. Splitting into focused guides loaded on demand reclaims most of that context.

Changes

1. Created 9 new files (commit `41ee8c5`)

Seven focused guides under documentation/:

documentation/HISTORY.md — historical phases 1-9 of development
documentation/CLI.md — CLI commands, server lifecycle, DLC_* config
documentation/API.md — REST endpoints, OpenAPI, Greet v1/v2
documentation/OBSERVABILITY.md — OpenTelemetry + Jaeger, sampler types
documentation/TROUBLESHOOTING.md — known issues + pointers to specialized guides
documentation/CODE_EXAMPLES.md — endpoint/logging/context snippets, ADR pointers
documentation/ROADMAP.md — potential features, architectural improvements

Two root-level files:

CHANGELOG.md — user-facing changelog (Keep a Changelog format)
AGENT_CHANGELOG.md — trace of structural decisions by AI agents (was referenced in AGENTS.md but didn't exist)

2. Rewrote `AGENTS.md` (commit `88a934d`)

1296 → 130 lines (-1242 lines, -90% bytes)
Preserved: project overview, tools/tech, structure, retention policy
Replaced detail sections with explicit pointers to the 9 new guides + existing guides (AGENT_USAGE_GUIDE.md, BDD_GUIDE.md, version-management-guide.md, local-ci-cd-testing.md, GITMOJI_CHEATSHEET.md)
Removed ~150 lines of "Version Management" (entirely redundant with documentation/version-management-guide.md)
All 25 internal links verified valid
Fixed broken link: original [ADR-0019](adr/0019-bdd-feature-structure.md) (file doesn't exist) replaced with references to [ADR-0008](adr/0008-bdd-testing.md) (BDD testing) and [ADR-0025](adr/0025-bdd-scenario-isolation-strategies.md) (scenario isolation), which are the actual authoritative sources

3. Fixed ADR header dates (commit `732eee7`)

adr/0018-user-management-auth-system.md: **Date:** 2024-04-06 → 2026-04-06
adr/0019-postgresql-integration.md: **Date:** 2024-04-07 → 2026-04-07

Confirmed typos: implementation dates in both files are 2026-04-08, the project itself started 2026-04-01 (CHANGELOG.md). The 2024 was a clear off-by-2-years.

Test plan

Pre-commit hooks pass on all 3 commits (verified locally: go mod tidy, go fmt, swag fmt)
All internal links in new AGENTS.md resolve to existing files (verified via shell loop)
vibe lazy-load behavior verified (with caveats — see below)
Test prompts run against Mistral (with caveats — see below)
No regression in existing skills (gitea-client, bdd-testing, commit-message) — not tested in this PR; tracked separately

Honest results from the vibe lazy-load tests

The lazy-load promise is half-confirmed. Two distinct modes diverge:

Interactive mode (vibe then prompt) — works as expected. AGENTS.md auto-loads at session start; documentation/X.md files load on demand when the agent reads them. The 130-line AGENTS.md keeps the upfront context budget low.
Programmatic mode (vibe -p "...") — diverges from interactive in two ways now documented in ~/.vibe/memory/reference/mistral-quirks.md:
- Q-024: [knowledge].sources are NOT auto-loaded in -p mode (only in interactive).
- Q-026: task tool returns "Tool execution not permitted" in -p mode for sub-agent delegation.
Test prompts run against -p mode showed:
- "Comment je teste l'API du projet ?" → an agent answered curl http://localhost:8080/api/v1/health (HALLUCINATION — the real endpoint is /api/health, documented in documentation/API.md). The agent did not consult the doc file even though it was listed in [knowledge].sources (Q-024 explains why).
- "Quelle est la décision de routing ?" / "Comment manager les versions ?" — not run yet; expected to behave the same way under -p (i.e. potentially hallucinate; reliable in interactive).

Mitigations now in place (post-PR)

Mistral quirks documented in ~/.vibe/memory/reference/mistral-quirks.md (Q-024, Q-026, Q-029).
All ~/.vibe/agents/*.toml patched with anti-hallucination directive: "AVANT de répondre à toute question factuelle, TOUJOURS read_file/grep le fichier de doc pertinent. Ne pas répondre depuis tes connaissances générales."
Workaround for -p mode: pass --workdir to the directory containing the docs and call read_file/grep directly from the prompt instead of relying on auto-load.

The PR's lazy-load goal IS met for the primary use case (interactive vibe inside the project). The -p mode is a separate gap, tracked and being worked on.

Migration context

This PR is part of Phase 1 of a larger migration from Claude Code to Mistral Vibe (ARCODANGE strategic move toward European tech sovereignty). 6 of 11 curriculum tasks now complete.

🤖 Generated with Claude Code (Opus 4.7, 1M context) collaborating with Mistral Vibe (intent-router agent for the analysis phase).

Co-Authored-By: Claude Opus 4.7 (1M context) noreply@anthropic.com
Co-Authored-By: Mistral Vibe (devstral-2 / mistral-medium-3.5)

## Summary Refactor `AGENTS.md` from a 1296-line monolith into a 130-line directive file + 9 focused guides. Done as Tâche 6 of the ARCODANGE Phase 1 migration (Claude Code → Mistral Vibe), driven by the lazy-loading constraint of the 128k context Mistral. **Why** — Mistral Vibe auto-loads `AGENTS.md` at every session start. A 1296-line file consumes ~30-40k tokens before the user's first prompt, leaving a small window for actual reasoning on a 128k-context model. Splitting into focused guides loaded on demand reclaims most of that context. ## Changes ### 1. Created 9 new files (commit `41ee8c5`) Seven focused guides under `documentation/`: - `documentation/HISTORY.md` — historical phases 1-9 of development - `documentation/CLI.md` — CLI commands, server lifecycle, `DLC_*` config - `documentation/API.md` — REST endpoints, OpenAPI, Greet v1/v2 - `documentation/OBSERVABILITY.md` — OpenTelemetry + Jaeger, sampler types - `documentation/TROUBLESHOOTING.md` — known issues + pointers to specialized guides - `documentation/CODE_EXAMPLES.md` — endpoint/logging/context snippets, ADR pointers - `documentation/ROADMAP.md` — potential features, architectural improvements Two root-level files: - `CHANGELOG.md` — user-facing changelog (Keep a Changelog format) - `AGENT_CHANGELOG.md` — trace of structural decisions by AI agents (was referenced in `AGENTS.md` but didn't exist) ### 2. Rewrote `AGENTS.md` (commit `88a934d`) - **1296 → 130 lines** (-1242 lines, -90% bytes) - Preserved: project overview, tools/tech, structure, retention policy - Replaced detail sections with explicit pointers to the 9 new guides + existing guides (`AGENT_USAGE_GUIDE.md`, `BDD_GUIDE.md`, `version-management-guide.md`, `local-ci-cd-testing.md`, `GITMOJI_CHEATSHEET.md`) - Removed ~150 lines of "Version Management" (entirely redundant with `documentation/version-management-guide.md`) - All 25 internal links verified valid - Fixed broken link: original `[ADR-0019](adr/0019-bdd-feature-structure.md)` (file doesn't exist) replaced with references to `[ADR-0008](adr/0008-bdd-testing.md)` (BDD testing) and `[ADR-0025](adr/0025-bdd-scenario-isolation-strategies.md)` (scenario isolation), which are the actual authoritative sources ### 3. Fixed ADR header dates (commit `732eee7`) - `adr/0018-user-management-auth-system.md`: `**Date:** 2024-04-06` → `2026-04-06` - `adr/0019-postgresql-integration.md`: `**Date:** 2024-04-07` → `2026-04-07` Confirmed typos: implementation dates in both files are `2026-04-08`, the project itself started `2026-04-01` (CHANGELOG.md). The `2024` was a clear off-by-2-years. ## Test plan - [x] Pre-commit hooks pass on all 3 commits (verified locally: `go mod tidy`, `go fmt`, `swag fmt`) - [x] All internal links in new `AGENTS.md` resolve to existing files (verified via shell loop) - [x] `vibe` lazy-load behavior verified (with caveats — see below) - [x] Test prompts run against Mistral (with caveats — see below) - [ ] No regression in existing skills (`gitea-client`, `bdd-testing`, `commit-message`) — *not tested in this PR; tracked separately* ### Honest results from the vibe lazy-load tests The lazy-load promise is **half-confirmed**. Two distinct modes diverge: 1. **Interactive mode** (`vibe` then prompt) — works as expected. AGENTS.md auto-loads at session start; `documentation/X.md` files load on demand when the agent reads them. The 130-line `AGENTS.md` keeps the upfront context budget low. 2. **Programmatic mode** (`vibe -p "..."`) — diverges from interactive in two ways now documented in `~/.vibe/memory/reference/mistral-quirks.md`: - **Q-024**: `[knowledge].sources` are NOT auto-loaded in `-p` mode (only in interactive). - **Q-026**: `task` tool returns "Tool execution not permitted" in `-p` mode for sub-agent delegation. Test prompts run against `-p` mode showed: - "Comment je teste l'API du projet ?" → an agent answered `curl http://localhost:8080/api/v1/health` (HALLUCINATION — the real endpoint is `/api/health`, documented in `documentation/API.md`). The agent did not consult the doc file even though it was listed in `[knowledge].sources` (Q-024 explains why). - "Quelle est la décision de routing ?" / "Comment manager les versions ?" — not run yet; expected to behave the same way under `-p` (i.e. potentially hallucinate; reliable in interactive). ### Mitigations now in place (post-PR) - Mistral quirks documented in `~/.vibe/memory/reference/mistral-quirks.md` (Q-024, Q-026, Q-029). - All `~/.vibe/agents/*.toml` patched with anti-hallucination directive: "AVANT de répondre à toute question factuelle, TOUJOURS read_file/grep le fichier de doc pertinent. Ne pas répondre depuis tes connaissances générales." - Workaround for `-p` mode: pass `--workdir` to the directory containing the docs and call `read_file`/`grep` directly from the prompt instead of relying on auto-load. The PR's lazy-load goal IS met for the primary use case (interactive vibe inside the project). The `-p` mode is a separate gap, tracked and being worked on. ## Migration context This PR is part of Phase 1 of a larger migration from Claude Code to Mistral Vibe (ARCODANGE strategic move toward European tech sovereignty). 6 of 11 curriculum tasks now complete. 🤖 Generated with [Claude Code](https://claude.com/claude-code) (Opus 4.7, 1M context) collaborating with Mistral Vibe (intent-router agent for the analysis phase). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> Co-Authored-By: Mistral Vibe (devstral-2 / mistral-medium-3.5)

arcodange added 5 commits 2026-05-02 23:57:25 +02:00

📝 docs: add two missing ADR files (0011 validation, 0014 gRPC) 8bae62c28e

ADR 0011 and 0014 were referenced in the README list but their files
were absent from the repository. Reconstruct them from available context:

- 0011: go-playground/validator selection (already implemented in go.mod)
- 0014: gRPC adoption strategy (evaluated and deferred/rejected)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

📝 docs: audit and correct all ADR statuses and content 73a3af1552

Full pass over all 25 ADRs to align documentation with actual
implementation state. Changes by ADR:

README index: completely rewritten — previous table mapped numbers to
wrong titles from 0010 onward.

0008 (BDD Testing): added note that flat features/ structure and godog
CLI invocation are superseded by ADR-0024; framework decision stands.

0009 (Hybrid Testing): renamed from "Combine BDD and Swagger-based
testing" to "BDD Testing with OpenAPI Documentation"; clarified that
the SDK-testing layer was never built and has no open issue.

0013 (OpenAPI/Swagger): removed leftover merge conflict artifact
(=======) and duplicated 60-line block.

0015 (Cobra CLI): fixed status contradiction — body said "Implemented"
while footer said "Proposed". Now Accepted.

0018 (User Management): status Proposed → Accepted; system is fully
implemented (JWT, bcrypt, GORM repos all present).

0019 (PostgreSQL): status Proposed → Accepted (Partial); added warning
that sqlite_repository.go and gorm/driver/sqlite still present contrary
to ADR intent.

0021 (JWT Retention): fixed wrong cross-reference (previously cited
ADR-0009 "Hybrid Testing" as source of JWT multi-secret support); fixed
title number from "10" to "21"; clarified that base JWT is implemented
but the retention cleanup job is not.

0022 (Rate Limiting/Cache): added warning block linking to open Gitea
issue #13; changed all 20 false ✅ implementation checkboxes to ❌.

0023 (Config Hot Reloading): added note that BDD scenarios exist for
this feature but the feature itself is not yet implemented.

0024 (BDD Organization): status Proposed → Accepted; modular domain
structure is fully built.

0025 (BDD Scenario Isolation): status Proposed → Accepted (Partial);
Phase 1 done, Phase 2 blocked on ADR-0022.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

📝 docs(restructure): split AGENTS.md into focused guides (Tâche 6 Phase B) 41ee8c56ac

Création de 9 fichiers neufs pour décharger AGENTS.md (1296 lignes →
~130) en documents lazy-loadables, compatibles avec la limite de
contexte 128k de Mistral Vibe (cf. ARCODANGE migration Phase 1,
Tâche 6 du curriculum).

Sept guides ciblés sous documentation/ :
- HISTORY.md            : phases historiques 1-9 du développement
- CLI.md                : commandes CLI, server lifecycle, config DLC_*
- API.md                : endpoints REST, OpenAPI, Greet v1/v2
- OBSERVABILITY.md      : OpenTelemetry + Jaeger, sampler types, test
- TROUBLESHOOTING.md    : issues connues + pointeurs vers guides spé
- CODE_EXAMPLES.md      : snippets endpoint/logging/context, pointeurs ADR
- ROADMAP.md            : potential features, architectural improvements

Deux fichiers racine :
- CHANGELOG.md          : user-facing, format Keep a Changelog
- AGENT_CHANGELOG.md    : décisions structurantes des agents AI
                          (référencé par AGENTS.md, n'existait pas)

Le contenu est extrait fidèlement d'AGENTS.md sans réinterprétation.
Phase C (réécriture AGENTS.md court) suit dans le commit suivant.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

📝 docs(restructure): rewrite AGENTS.md as short directive (Tâche 6 Phase C) 88a934dfd2

AGENTS.md passe de 1296 → 130 lignes, sous la cible 200 fixée en
D-004 (lazy loading 128k). Ne contient plus que :
- Project overview (court)
- Tools & technologies (table)
- Project structure (tree)
- Tableau "Detailed Guides" pointant vers documentation/*.md
  (12 entrées, tous liens vérifiés valides)
- Index des ADR-clés avec liens (13 entrées, tous valides)
- AI agent info (court, pointe vers AGENT_USAGE_GUIDE)
- Commit conventions (court, pointe vers .vibe/skills/commit-message/)
- BDD feature structure (court, pointe vers ADR-0008 + BDD_GUIDE)
- Retention policy (gardée intégralement, directive ARCODANGE)
- Support (procédure escalade en 5 étapes)

Section Version Management (ex-928-1076, ~150 lignes) entièrement
SUPPRIMÉE — totalement redondante avec documentation/version-management-
guide.md (cf. analyse Phase A `~/.vibe/plans/task-6-phase-a-results.md`).

Lien cassé ligne 1277 corrigé : `0019-bdd-feature-structure.md`
(inexistant) remplacé par référence à ADR-0008 (bdd-testing) + ADR-0025
(scenario-isolation) qui sont les vraies sources autoritaires.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

🐛 fix(adr): correct ADR 0018-0019 dates (2024 → 2026) — Tâche 6 Phase D 732eee7586

Friction documentaire identifiée pendant l'audit Phase A : les ADRs
0018 (User Management) et 0019 (PostgreSQL Integration) avaient des
dates 2024-04-XX dans leur header, alors que le projet a démarré
le 2026-04-01 (cf. CHANGELOG.md, première entrée).

C'est un typo. Implementation Date était bien à 2026-04-08 dans les
deux fichiers, ce qui confirme le diagnostic.

Fix :
- adr/0018-user-management-auth-system.md : 2024-04-06 → 2026-04-06
- adr/0019-postgresql-integration.md     : 2024-04-07 → 2026-04-07

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

arcodange added 2 commits 2026-05-03 00:02:31 +02:00

📝 docs(api): add /api/version endpoint reference acebea353b

Endpoint introduced in PR #16 (commit c17fb4f) was missing from our
restructured documentation/API.md. Catching up before merging origin/main
into this feature branch.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

🔀 merge: integrate origin/main (PR #16 JSON logging fix) into restructure branch

CI/CD Pipeline / Build Docker Cache (push) Successful in 26s

Details

CI/CD Pipeline / CI Pipeline (push) Failing after 5m46s

Details

CI/CD Pipeline / Trigger Docker Push (push) Has been skipped

Details

29272b8fba

PR #16 (commit c17fb4f) introduced 2 things while this restructure branch
was in flight:
1. A fix in pkg/config/config.go (peekJSONLogging) so the very first log
   line is JSON when DLC_LOGGING_JSON=true.
2. Its own attempt to shorten AGENTS.md (1296 → 191 lines).

Resolution:
- Code/scripts changes from #16 (config.go, server.go, scripts/*,
  gitea-client.sh) accepted as-is via auto-merge.
- AGENTS.md conflict resolved by keeping our version (130 lines,
  fully externalized to documentation/*.md). Our approach goes further
  in the lazy-loading direction (D-004, 128k context constraint),
  externalizing every detail instead of keeping minimal inline content.

Caught up the missing /api/version endpoint in documentation/API.md
(commit acebea3 just before this merge) so we don't regress on the
new endpoint introduced by #16.

Pre-commit hooks already validated each upstream commit. Re-running
on the merge to confirm.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>