| name | docs-gardening |
| description | 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. |
| argument-hint | optional scope — e.g. architecture, features, decisions, all |
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).
