Docs Gardening
Keep the harness honest: every doc reflects current code, cross-links resolve, frontmatter is valid, and each file earns its place. Stale docs are worse than none — agents trust them.
This is maintenance, not writing. Default to fixing or deleting, not adding.
Principles
- Docs exist to cut re-instruction cost. If a page doesn't help an agent ship correctly, it's dead weight.
AGENTS.md is a map (< ~100 lines) pointing into docs/. Growth is drift.docs/ is the system of record, an OKF bundle: markdown + YAML frontmatter, one concept per file, file path = identity, index.md per folder for progressive disclosure, log.md for chronology, relative markdown links for the graph..agents/rules/*.md are the always-on digest; they summarize and link to docs/conventions/, never restate at length.- Duplication is drift — one home per fact, cross-link elsewhere.
- Code wins over docs. Update or delete the doc; never "fix" code to match a stale doc.
Layout being gardened
AGENTS.md (CLAUDE.md is just @AGENTS.md)
.agents/rules/ .agents/skills/ (.claude/{rules,skills} are symlinks)
docs/
index.md log.md
architecture/ conventions/ decisions/ domain/ features/ screens/
tooling/ platforms/ learnings/ exec-plans/{index.md,backlog,active,completed}
brainstorm/ code-review/
Passes (report findings after each; ask before mass edits; single-file fixes go straight through)
1 — Inventory
List every .md under docs/, AGENTS.md, .agents/rules/. Note sizes and git log -1 --format=%ci <file>. Flag files outside the layout.
2 — Frontmatter (OKF)
Every docs/**/*.md (except .gitkeep) starts with YAML frontmatter containing at least type; expect title, description, tags, timestamp (ISO 8601). decisions/ also carry status and date; exec-plans/ carry status. Fix missing/invalid fields.
3 — Staleness (docs vs code)
- File paths mentioned → exist? Class/function names → grep them.
- Bloc list (
architecture/state-management.md) ↔ lib/blocs/. Provider list ↔ lib/providers/.
- Routes (
screens/flows.md) ↔ lib/router/routes.dart + router.dart.
- Models/typeIds/box keys (
architecture/data-layer.md, domain/alquran-cloud-api.md) ↔ packages/al_quran_api/lib/src/.
- Widget catalogue (
architecture/configs.md, rules) ↔ lib/ui/widgets/.
- Versions (
tooling/fvm-and-sdk.md, platforms/android.md, conventions/release.md) ↔ .fvmrc, pubspec.yaml, android/**/*.kts, .github/workflows/run_test.yml.
- Commands in
AGENTS.md/tooling/ still valid?
- Feature docs' "Known gaps" — fixed already? Remove.
4 — Cross-links
Grep every markdown link (text in square brackets followed by a parenthesised path) and verify each relative target exists. AGENTS.md Docs section points to real folders/files. Every folder has an index.md listing its files.
5 — Duplication
Same fact in two places (commands, versions, layer rules, typeIds)? Pick the canonical home, cut elsewhere, link.
6 — Structural rules
| File |
Rule |
AGENTS.md |
< ~100 lines, map only |
.agents/rules/*.md |
digest + link; has paths: frontmatter |
docs/decisions/*.md |
append-only; supersede with a new ADR, never edit history |
docs/log.md |
newest first, one line per change, dated |
docs/exec-plans/index.md |
matches the files in backlog/active/completed |
| other docs |
first line after frontmatter states purpose; no TODOs (surface in report) |
7 — Obsolete files
Candidates: docs for removed features, superseded pages. Never delete without asking.
Reporting format
### Pass N — <name>
**Fine:** …
**Needs fixing (applying now):** file:line — issue
**Needs confirmation:** …
**Verified against code:** …
Finish with a docs/log.md line summarizing the gardening.
What NOT to do
- Write new docs unless asked. Add TODOs. Rewrite prose for style. Edit past ADRs. Assume old == stale (check the code).
1---2name: docs-gardening3description: Audit and maintain The Holy Qur'an app's knowledge base (AGENTS.md, .agents/rules/, docs/ OKF bundle) for staleness, broken cross-links, drift from code, and OKF structural issues. Use when asked to review, garden, audit, update, or clean up the docs. Also use proactively after any architectural change, convention shift, dependency/SDK bump, or feature merge.4---56# Docs Gardening78Keep the harness honest: every doc reflects current code, cross-links resolve, frontmatter is valid, and each file earns its place. Stale docs are worse than none — agents trust them.910This is **maintenance**, not writing. Default to fixing or deleting, not adding.1112## Principles131. Docs exist to cut re-instruction cost. If a page doesn't help an agent ship correctly, it's dead weight.142. `AGENTS.md` is a map (< ~100 lines) pointing into `docs/`. Growth is drift.153. `docs/` is the system of record, an **OKF bundle**: markdown + YAML frontmatter, one concept per file, file path = identity, `index.md` per folder for progressive disclosure, `log.md` for chronology, relative markdown links for the graph.164. `.agents/rules/*.md` are the always-on digest; they summarize and link to `docs/conventions/`, never restate at length.175. Duplication is drift — one home per fact, cross-link elsewhere.186. Code wins over docs. Update or delete the doc; never "fix" code to match a stale doc.1920## Layout being gardened21```22AGENTS.md (CLAUDE.md is just @AGENTS.md)23.agents/rules/ .agents/skills/ (.claude/{rules,skills} are symlinks)24docs/25 index.md log.md26 architecture/ conventions/ decisions/ domain/ features/ screens/27 tooling/ platforms/ learnings/ exec-plans/{index.md,backlog,active,completed}28 brainstorm/ code-review/29```3031## Passes (report findings after each; ask before mass edits; single-file fixes go straight through)32### 1 — Inventory33List every `.md` under `docs/`, `AGENTS.md`, `.agents/rules/`. Note sizes and `git log -1 --format=%ci <file>`. Flag files outside the layout.3435### 2 — Frontmatter (OKF)36Every `docs/**/*.md` (except `.gitkeep`) starts with YAML frontmatter containing at least `type`; expect `title`, `description`, `tags`, `timestamp` (ISO 8601). `decisions/` also carry `status` and `date`; `exec-plans/` carry `status`. Fix missing/invalid fields.3738### 3 — Staleness (docs vs code)39- File paths mentioned → exist? Class/function names → grep them.40- Bloc list (`architecture/state-management.md`) ↔ `lib/blocs/`. Provider list ↔ `lib/providers/`.41- Routes (`screens/flows.md`) ↔ `lib/router/routes.dart` + `router.dart`.42- Models/typeIds/box keys (`architecture/data-layer.md`, `domain/alquran-cloud-api.md`) ↔ `packages/al_quran_api/lib/src/`.43- Widget catalogue (`architecture/configs.md`, rules) ↔ `lib/ui/widgets/`.44- Versions (`tooling/fvm-and-sdk.md`, `platforms/android.md`, `conventions/release.md`) ↔ `.fvmrc`, `pubspec.yaml`, `android/**/*.kts`, `.github/workflows/run_test.yml`.45- Commands in `AGENTS.md`/`tooling/` still valid?46- Feature docs' "Known gaps" — fixed already? Remove.4748### 4 — Cross-links49Grep every markdown link (text in square brackets followed by a parenthesised path) and verify each relative target exists. `AGENTS.md` Docs section points to real folders/files. Every folder has an `index.md` listing its files.5051### 5 — Duplication52Same fact in two places (commands, versions, layer rules, typeIds)? Pick the canonical home, cut elsewhere, link.5354### 6 — Structural rules55| File | Rule |56|---|---|57| `AGENTS.md` | < ~100 lines, map only |58| `.agents/rules/*.md` | digest + link; has `paths:` frontmatter |59| `docs/decisions/*.md` | append-only; supersede with a new ADR, never edit history |60| `docs/log.md` | newest first, one line per change, dated |61| `docs/exec-plans/index.md` | matches the files in backlog/active/completed |62| other docs | first line after frontmatter states purpose; no TODOs (surface in report) |6364### 7 — Obsolete files65Candidates: docs for removed features, superseded pages. **Never delete without asking.**6667## Reporting format68```69### Pass N — <name>70**Fine:** …71**Needs fixing (applying now):** file:line — issue72**Needs confirmation:** …73**Verified against code:** …74```75Finish with a `docs/log.md` line summarizing the gardening.7677## What NOT to do78- Write new docs unless asked. Add TODOs. Rewrite prose for style. Edit past ADRs. Assume old == stale (check the code).
mhmzdev