documentation-layout - tier the validator, replace hardcoded cap numbers in docs with pointer references #82

New issue

Closed

opened 2026-05-28 01:29:28 +00:00 by coilysiren · 0 comments

coilysiren commented

2026-05-28 01:29:28 +00:00

Owner

Problem

Markdown size caps are restated in at least 8 places across agentic-os and agentic-os-kai, with two conflicting numbers depending on which doc you land on:

500 lines / 10 KB (loader-bound files: AGENTS.md, SKILL.md)
80 lines / 4000 chars (regular Markdown via documentation-layout hook)

agentic-os-kai/AGENTS.md contradicts itself within the same file (L5 says 500/10KB, L68 says 80/4000, L304 says 500/10KB again).

Inventory of hardcoded numbers:

agentic-os-kai/AGENTS.md lines 5, 68, 304
agentic-os/docs/skill-discipline/handbook.md line 178
agentic-os/docs/skill-discipline/authoring-walkthrough.md line 40
agentic-os/docs/skill-discipline/templates/SKILL.md.template line 24
agentic-os/.agents/skills/tooling-skill-authoring/references/authoring-walkthrough.md lines 36, 56
agentic-os/.agents/skills/tooling-skill-authoring/references/handbook.md lines 104, 245, 247, 267

Fix

Two parts:

Tier the validator. agentic_os/check_documentation_layout.py currently has a single cap. Add LOADER_BOUND_BASENAMES = {"AGENTS.md", "CLAUDE.md", "SKILL.md"} with LOADER_MAX_LINES = 500, LOADER_MAX_CHARS = 10_000. Apply the higher tier when basename matches; fall back to MAX_MARKDOWN_LINES / MAX_MARKDOWN_CHARS (80 / 4_000) otherwise. After this, the validator is a single source of truth for both caps.
Replace hardcoded numbers in docs with pointer references. Each callsite gets rewritten to point at the validator instead of restating the number, so the docs can never drift again. Format:

Size caps are enforced by documentation-layout. AGENTS.md / SKILL.md are loader-bound at the higher tier; everything else uses the standard tier.

No numbers in the prose. The validator is read directly when anyone needs the value.

Out of scope

The long sweep to make agentic-os itself pass the hook (#81). This issue just stops the docs from disagreeing; it doesn't fix any size violations.

Acceptance

check_documentation_layout has two named cap tiers, both as module-level constants.
grep -rn '500 lines\|10 KB\|80 lines\|4000 char' against both repos returns only matches inside the validator source file itself.
AGENTS.md no longer contradicts itself.

**Problem** Markdown size caps are restated in at least 8 places across `agentic-os` and `agentic-os-kai`, with **two conflicting numbers** depending on which doc you land on: - `500 lines / 10 KB` (loader-bound files: AGENTS.md, SKILL.md) - `80 lines / 4000 chars` (regular Markdown via `documentation-layout` hook) `agentic-os-kai/AGENTS.md` contradicts itself within the same file (L5 says 500/10KB, L68 says 80/4000, L304 says 500/10KB again). Inventory of hardcoded numbers: - `agentic-os-kai/AGENTS.md` lines 5, 68, 304 - `agentic-os/docs/skill-discipline/handbook.md` line 178 - `agentic-os/docs/skill-discipline/authoring-walkthrough.md` line 40 - `agentic-os/docs/skill-discipline/templates/SKILL.md.template` line 24 - `agentic-os/.agents/skills/tooling-skill-authoring/references/authoring-walkthrough.md` lines 36, 56 - `agentic-os/.agents/skills/tooling-skill-authoring/references/handbook.md` lines 104, 245, 247, 267 **Fix** Two parts: 1. **Tier the validator.** `agentic_os/check_documentation_layout.py` currently has a single cap. Add `LOADER_BOUND_BASENAMES = {"AGENTS.md", "CLAUDE.md", "SKILL.md"}` with `LOADER_MAX_LINES = 500`, `LOADER_MAX_CHARS = 10_000`. Apply the higher tier when basename matches; fall back to `MAX_MARKDOWN_LINES` / `MAX_MARKDOWN_CHARS` (80 / 4_000) otherwise. After this, the validator is a single source of truth for both caps. 2. **Replace hardcoded numbers in docs with pointer references.** Each callsite gets rewritten to point at the validator instead of restating the number, so the docs can never drift again. Format: > Size caps are enforced by [`documentation-layout`](https://github.com/coilysiren/agentic-os/blob/main/agentic_os/check_documentation_layout.py). AGENTS.md / SKILL.md are loader-bound at the higher tier; everything else uses the standard tier. No numbers in the prose. The validator is read directly when anyone needs the value. **Out of scope** - The long sweep to make `agentic-os` itself pass the hook (#81). This issue just stops the docs from disagreeing; it doesn't fix any size violations. **Acceptance** - `check_documentation_layout` has two named cap tiers, both as module-level constants. - `grep -rn '500 lines\|10 KB\|80 lines\|4000 char'` against both repos returns only matches inside the validator source file itself. - AGENTS.md no longer contradicts itself.

coilysiren referenced this issue from a commit

2026-05-28 01:32:27 +00:00

feat(documentation-layout): tier size caps by loader-bound basename, replace hardcoded numbers in docs with pointer references

coilysiren closed this issue

2026-05-28 01:32:27 +00:00

coilysiren referenced this issue from a commit

2026-05-28 01:33:05 +00:00

docs(AGENTS): replace hardcoded size caps with pointer references to the upstream validator

coilysiren referenced this issue

2026-05-28 01:36:14 +00:00

documentation-layout - revert tier policy, single 80/4000 cap for all Markdown including AGENTS.md and SKILL.md #83

coilysiren referenced this issue from a commit