apply documentation-layout to agentic-os itself - flatten skills, fix size violations, wire the hook #81

New issue

Open

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

coilysiren commented

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

Owner

Problem

Now that documentation-layout has two new rules (#80: generalized examples/ carve-out, mandatory flat skill folders) and the existing skill conventions in agentic-os use <skill>/references/<file>.md and <skill>/templates/<file>.md, agentic-os itself fails its own hook. Same applies to size caps: ~20 Markdown files in this repo exceed 80 lines / 4000 chars.

Symptom

.venv/bin/check-documentation-layout against the repo produces (representative):

FAIL: docs/skill-discipline/examples: docs/ must stay flat
FAIL: docs/skill-discipline/templates: docs/ must stay flat
FAIL: .agents/skills/coding-discord-bot-architect/references: skill folders must be flat
FAIL: .agents/skills/coding-discord-bot-architect/references/patterns.md: 829 lines exceeds the 80-line cap
... (~40 violations total)

Plus the hook is not currently invoked by this repo's .pre-commit-config.yaml (only catalog-block-present, closes-issue, warp-go-vet run), so this drift has been invisible.

Scope of work (expected to span multiple sessions)

This is not a single-commit cleanup. The sweep is broad and touches every skill in the repo. Plan to break it into many small commits, each closing this issue with relates to (then a final commit with closes), or split into per-skill child issues.

Flatten every skill folder. Move <skill>/references/<file>.md and <skill>/templates/<file>.md up to <skill>/<file>.md. Update every internal link, SKILL.md frontmatter, and any cross-repo references that pointed at the old paths.
Restructure docs/skill-discipline/. It has subdirectories (examples/, templates/). Either move into the skill that owns the convention, or flatten into docs/*.md with filename prefixes.
Handle size violations. Many skill bodies and references exceed 80 / 4000. Either resolve via the tier-policy work (see #TODO — pointer references issue) or split each oversized file. Order matters: do tier policy first or the splits get redone.
Wire the hook into this repo's pre-commit config. Add the canonical documentation-layout (and catalog-doc-size) entries. Run the hook against the now-clean tree; assert zero violations.
Update apply-agentic-os-hooks.py so downstream consumers (agentic-os-kai etc.) also get documentation-layout rolled out automatically. See agentic-os-kai#370.
Move CHANGELOG.md. Root-level CHANGELOG.md is not on the root allowlist. Either add it to the allowlist with rationale, or move to docs/CHANGELOG.md.

Why this can take time

Each skill flatten requires updating every [link](references/foo.md) inside the skill body and any sibling skill that cross-references it. Easy to miss.
Skill renames break downstream symlinks (agentic-os-kai/setup.sh walks this dir and symlinks each skill into ~/.claude/skills/).
Some reference files are genuinely long-form (handbook.md 188 lines, patterns.md 829 lines). Splitting them well takes editorial judgment, not just sed.
Tier policy decision (separate issue) is upstream of any size-split work. Doing splits first wastes effort.

Track partial progress in commit messages. This issue stays open until step 4 (zero violations) lands.

Acceptance

.venv/bin/check-documentation-layout against coilysiren/agentic-os HEAD exits 0.
.pre-commit-config.yaml includes documentation-layout and catalog-doc-size.
apply-agentic-os-hooks.py propagates the change to consumers.
agentic-os-kai#370 unblocked.

**Problem** Now that `documentation-layout` has two new rules (#80: generalized `examples/` carve-out, mandatory flat skill folders) and the existing skill conventions in `agentic-os` use `<skill>/references/<file>.md` and `<skill>/templates/<file>.md`, **`agentic-os` itself fails its own hook**. Same applies to size caps: ~20 Markdown files in this repo exceed 80 lines / 4000 chars. **Symptom** `.venv/bin/check-documentation-layout` against the repo produces (representative): ``` FAIL: docs/skill-discipline/examples: docs/ must stay flat FAIL: docs/skill-discipline/templates: docs/ must stay flat FAIL: .agents/skills/coding-discord-bot-architect/references: skill folders must be flat FAIL: .agents/skills/coding-discord-bot-architect/references/patterns.md: 829 lines exceeds the 80-line cap ... (~40 violations total) ``` Plus the hook is not currently invoked by this repo's `.pre-commit-config.yaml` (only `catalog-block-present`, `closes-issue`, `warp-go-vet` run), so this drift has been invisible. **Scope of work (expected to span multiple sessions)** This is not a single-commit cleanup. The sweep is broad and touches every skill in the repo. Plan to break it into many small commits, each closing this issue with `relates to` (then a final commit with `closes`), or split into per-skill child issues. 1. **Flatten every skill folder.** Move `<skill>/references/<file>.md` and `<skill>/templates/<file>.md` up to `<skill>/<file>.md`. Update every internal link, SKILL.md frontmatter, and any cross-repo references that pointed at the old paths. 2. **Restructure `docs/skill-discipline/`.** It has subdirectories (`examples/`, `templates/`). Either move into the skill that owns the convention, or flatten into `docs/*.md` with filename prefixes. 3. **Handle size violations.** Many skill bodies and references exceed 80 / 4000. Either resolve via the tier-policy work (see #TODO — pointer references issue) or split each oversized file. Order matters: do tier policy first or the splits get redone. 4. **Wire the hook into this repo's pre-commit config.** Add the canonical `documentation-layout` (and `catalog-doc-size`) entries. Run the hook against the now-clean tree; assert zero violations. 5. **Update `apply-agentic-os-hooks.py`** so downstream consumers (agentic-os-kai etc.) also get `documentation-layout` rolled out automatically. See agentic-os-kai#370. 6. **Move CHANGELOG.md.** Root-level `CHANGELOG.md` is not on the root allowlist. Either add it to the allowlist with rationale, or move to `docs/CHANGELOG.md`. **Why this can take time** - Each skill flatten requires updating every `[link](references/foo.md)` inside the skill body and any sibling skill that cross-references it. Easy to miss. - Skill renames break downstream symlinks (`agentic-os-kai/setup.sh` walks this dir and symlinks each skill into `~/.claude/skills/`). - Some reference files are genuinely long-form (handbook.md 188 lines, patterns.md 829 lines). Splitting them well takes editorial judgment, not just `sed`. - Tier policy decision (separate issue) is upstream of any size-split work. Doing splits first wastes effort. Track partial progress in commit messages. This issue stays open until step 4 (zero violations) lands. **Acceptance** - `.venv/bin/check-documentation-layout` against `coilysiren/agentic-os` HEAD exits 0. - `.pre-commit-config.yaml` includes `documentation-layout` and `catalog-doc-size`. - `apply-agentic-os-hooks.py` propagates the change to consumers. - agentic-os-kai#370 unblocked.

coilysiren referenced this issue

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

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

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

2026-05-28 01:38:15 +00:00

revert(documentation-layout): drop loader-bound tier, single 80/4000 cap for all Markdown

coilysiren referenced this issue

2026-05-28 03:22:02 +00:00

documentation-layout - per-repo AGENTS.md cap override, relocate doctrine to skills #84