coilyco-flight-deck/agentic-os

Watch

docs band migration: 468 docs to merge, 531 files to trim, 24 repos #1102

New issue

Open

opened 2026-08-16 06:58:55 +00:00 by coilyco-ops · 1 comment

coilyco-ops commented

2026-08-16 06:58:55 +00:00

Member

Fleet cost, measured

Measured by pointing the real validator at each checkout rather than by
restating its rules, so these are the numbers the hook itself will print.
check_markdown_sizes emits one violation per cap breached, so these are
deduped by path: files to edit, not violations to clear.

468 docs/*.md files to merge away - the count cap
531 files to trim - the line and char caps
24 of 24 repos need at least one of the two

The decision this needs before engineers start

Only 301 of the 531 files to trim are in docs/. The other 230 are not
documentation in the folder sense, and three groups of them are worth a ruling:

.agents/skills/*/SKILL.md and .agents/composed/*/COMPOSED.md - 121
files. A skill is not a docs page. It was on the old 80-line cap with a
per-file escape, and the small band moves it to 40 lines with no escape. Nine
SKILL.md exclusions in one repo were cited as evidence the escape hatch had
to go, and removing it is right, but the cap those files now land on was
chosen for prose pages. deploy's change-deploy-repo/SKILL.md is 75 lines.
Co-located README.md and module docs - 56 files. deploy alone has 38
chart READMEs. These already sit on the tight outpost / homestead shape, and
the band cap now applies on top.
Content that is the product rather than documentation of it - 49 files.
website's src/pages/posts/*.md are blog posts. eco-app's
investigation/*.md are investigation logs. agentic-os-kai's data/*.md
is reference data. A 40-line cap on a blog post is not a documentation rule
reaching its target.

"no docs-as-product" ruled out an exception for voice-corpus and aosh, and
I have not treated that as covering blog posts, because a post is not
documentation being sold as a product - it is a different kind of file that the
same glob happens to catch. The three repos holding those 49 files are marked
autonomy/async-consult rather than headless for that reason: an engineer
should not unilaterally rewrite your posts to hit a line cap.

Options, no work blocked on picking one - every repo's docs/ work can start
today either way:

Nothing changes. The caps are the caps, and skills and posts get trimmed
like everything else.
A separate cap for skills and composed sources, the way README.md and
AGENTS.md already carry their own, sized for what those files are.
Placement-based scope. The band caps reach docs/ and skills; content
trees are out of scope for a documentation rule, named explicitly rather
than excluded per-file.

I would take 2 for skills and 3 for content trees, and leave co-located READMEs
on the band. But this is your call, and it is the only part of the migration
that is.

Per-repo state

Band, docs to merge, files to trim:

coilyco-gaming/sirens-echo - large - merge 118, trim 0 - docs 158/40
coilysiren/lore - small - merge 49, trim 52 - docs 69/20
coilyco-flight-deck/agent-proxy - small - merge 48, trim 43 - docs 68/20
coilyco-flight-deck/infrastructure - large - merge 87, trim 2 - docs 127/40
coilyco-bridge/agentic-os-kai - small - merge 0, trim 87 - docs 18/20
coilyco-flight-deck/agentic-os - large - merge 61, trim 0 - docs 101/40
coilyco-flight-deck/umbra - small - merge 29, trim 29 - docs 49/20
coilyco-flight-deck/ward - large (declaration blocked, ward#1668) - merge 22, trim 36 - docs 42/20
coilyco-gaming/galaxy-gen - small - merge 21, trim 34 - docs 41/20
coilyco-bridge/deploy - small - merge 0, trim 53 - docs 20/20
coilyco-bridge/agentic-os-xxx - small - merge 0, trim 43 - docs 13/20
coilyco-gaming/eco-app - small - merge 0, trim 42 - docs 20/20
coilyco-bridge/agentic-os-hardware - small - merge 0, trim 29 - docs 6/20
coilyco-gaming/factory-game-v3 - small - merge 8, trim 19 - docs 28/20
coilyco-flight-deck/agent-compose - large - merge 25, trim 0 - docs 65/40
coilysiren/voice-corpus - small - merge 0, trim 20 - docs 15/20
coilysiren/website - small - merge 0, trim 16 - docs 5/20
coilyco-gaming/eco-ops - small - merge 0, trim 13 - docs 3/20
coilyco-flight-deck/node-stats-mcp - small - merge 0, trim 5 - docs 6/20
coilyco-flight-deck/lunch-money-k8s - small - merge 0, trim 3 - docs 3/20
coilysiren/coilysiren - small - merge 0, trim 2 - docs 3/20
coilyco-flight-deck/scoop-bucket - small - merge 0, trim 1 - docs 2/20
coilyco-flight-deck/reddit-mcp - small - merge 0, trim 1 - docs 2/20
coilyco-gaming/steam-ops - small - merge 0, trim 1 - docs 1/20

What "done" means in a child issue

pre-commit run --all-files green, with no new entry under
[tool.agentic-os.documentation-layout] excludes. Excludes still govern
placement and flatness and no longer reach either size cap or the count, so
adding one cannot close a child issue.

The count cap is implemented and tested but deliberately not wired into
main() yet - a strict cap cannot ship from inside a repo that violates it,
and this repo is at 101 docs against 40. It gets wired in the same commit that
lands this repo's own migration, at which point every unfinished child goes
red. Until then a child's docs-count work is verifiable but not enforced.

Rationale for the numbers: docs/documentation-bands.md.
Validator: agentic-os#1090.

Every repo now declares a documentation band, and the caps that come with it put all 24 hooked repos out of compliance. This is the tracking issue for the big-bang migration: one engineer per repo, each child issue linked below. ## Fleet cost, measured Measured by pointing the real validator at each checkout rather than by restating its rules, so these are the numbers the hook itself will print. `check_markdown_sizes` emits one violation per cap breached, so these are deduped by path: files to edit, not violations to clear. * **468 `docs/*.md` files to merge away** - the count cap * **531 files to trim** - the line and char caps * **24 of 24 repos** need at least one of the two ## The decision this needs before engineers start **Only 301 of the 531 files to trim are in `docs/`.** The other 230 are not documentation in the folder sense, and three groups of them are worth a ruling: * **`.agents/skills/*/SKILL.md` and `.agents/composed/*/COMPOSED.md` - 121 files.** A skill is not a docs page. It was on the old 80-line cap with a per-file escape, and the small band moves it to 40 lines with no escape. Nine `SKILL.md` exclusions in one repo were cited as evidence the escape hatch had to go, and removing it is right, but the cap those files now land on was chosen for prose pages. `deploy`'s `change-deploy-repo/SKILL.md` is 75 lines. * **Co-located `README.md` and module docs - 56 files.** `deploy` alone has 38 chart READMEs. These already sit on the tight outpost / homestead shape, and the band cap now applies on top. * **Content that is the product rather than documentation of it - 49 files.** `website`'s `src/pages/posts/*.md` are blog posts. `eco-app`'s `investigation/*.md` are investigation logs. `agentic-os-kai`'s `data/*.md` is reference data. A 40-line cap on a blog post is not a documentation rule reaching its target. "no docs-as-product" ruled out an exception for `voice-corpus` and `aosh`, and I have not treated that as covering blog posts, because a post is not documentation being sold as a product - it is a different kind of file that the same glob happens to catch. The three repos holding those 49 files are marked `autonomy/async-consult` rather than `headless` for that reason: an engineer should not unilaterally rewrite your posts to hit a line cap. Options, no work blocked on picking one - every repo's `docs/` work can start today either way: 1. **Nothing changes.** The caps are the caps, and skills and posts get trimmed like everything else. 2. **A separate cap for skills and composed sources**, the way `README.md` and `AGENTS.md` already carry their own, sized for what those files are. 3. **Placement-based scope.** The band caps reach `docs/` and skills; content trees are out of scope for a documentation rule, named explicitly rather than excluded per-file. I would take 2 for skills and 3 for content trees, and leave co-located READMEs on the band. But this is your call, and it is the only part of the migration that is. ## Per-repo state Band, docs to merge, files to trim: * **coilyco-gaming/sirens-echo** - `large` - merge 118, trim 0 - docs 158/40 * **coilysiren/lore** - `small` - merge 49, trim 52 - docs 69/20 * **coilyco-flight-deck/agent-proxy** - `small` - merge 48, trim 43 - docs 68/20 * **coilyco-flight-deck/infrastructure** - `large` - merge 87, trim 2 - docs 127/40 * **coilyco-bridge/agentic-os-kai** - `small` - merge 0, trim 87 - docs 18/20 * **coilyco-flight-deck/agentic-os** - `large` - merge 61, trim 0 - docs 101/40 * **coilyco-flight-deck/umbra** - `small` - merge 29, trim 29 - docs 49/20 * **coilyco-flight-deck/ward** - `large` (declaration blocked, ward#1668) - merge 22, trim 36 - docs 42/20 * **coilyco-gaming/galaxy-gen** - `small` - merge 21, trim 34 - docs 41/20 * **coilyco-bridge/deploy** - `small` - merge 0, trim 53 - docs 20/20 * **coilyco-bridge/agentic-os-xxx** - `small` - merge 0, trim 43 - docs 13/20 * **coilyco-gaming/eco-app** - `small` - merge 0, trim 42 - docs 20/20 * **coilyco-bridge/agentic-os-hardware** - `small` - merge 0, trim 29 - docs 6/20 * **coilyco-gaming/factory-game-v3** - `small` - merge 8, trim 19 - docs 28/20 * **coilyco-flight-deck/agent-compose** - `large` - merge 25, trim 0 - docs 65/40 * **coilysiren/voice-corpus** - `small` - merge 0, trim 20 - docs 15/20 * **coilysiren/website** - `small` - merge 0, trim 16 - docs 5/20 * **coilyco-gaming/eco-ops** - `small` - merge 0, trim 13 - docs 3/20 * **coilyco-flight-deck/node-stats-mcp** - `small` - merge 0, trim 5 - docs 6/20 * **coilyco-flight-deck/lunch-money-k8s** - `small` - merge 0, trim 3 - docs 3/20 * **coilysiren/coilysiren** - `small` - merge 0, trim 2 - docs 3/20 * **coilyco-flight-deck/scoop-bucket** - `small` - merge 0, trim 1 - docs 2/20 * **coilyco-flight-deck/reddit-mcp** - `small` - merge 0, trim 1 - docs 2/20 * **coilyco-gaming/steam-ops** - `small` - merge 0, trim 1 - docs 1/20 ## What "done" means in a child issue `pre-commit run --all-files` green, with no new entry under `[tool.agentic-os.documentation-layout] excludes`. Excludes still govern placement and flatness and no longer reach either size cap or the count, so adding one cannot close a child issue. The count cap is implemented and tested but deliberately not wired into `main()` yet - a strict cap cannot ship from inside a repo that violates it, and this repo is at 101 docs against 40. It gets wired in the same commit that lands this repo's own migration, at which point every unfinished child goes red. Until then a child's docs-count work is verifiable but not enforced. Rationale for the numbers: [docs/documentation-bands.md](docs/documentation-bands.md). Validator: agentic-os#1090.

coilyco-ops referenced this issue from coilyco-flight-deck/agent-compose

2026-08-16 06:59:40 +00:00

docs band migration: merge 25 docs #292

coilyco-ops referenced this issue from coilyco-flight-deck/agent-proxy

2026-08-16 06:59:41 +00:00

docs band migration: merge 48 docs, trim 43 files #132

coilyco-ops referenced this issue

2026-08-16 06:59:42 +00:00

docs band migration: merge 61 docs #1103

coilyco-ops referenced this issue from coilyco-flight-deck/infrastructure

2026-08-16 06:59:43 +00:00

docs band migration: merge 87 docs, trim 2 files #855

coilyco-ops referenced this issue from coilyco-flight-deck/lunch-money-k8s

2026-08-16 06:59:44 +00:00

docs band migration: trim 3 files #43

coilyco-ops referenced this issue from coilyco-flight-deck/node-stats-mcp

2026-08-16 06:59:45 +00:00

docs band migration: trim 5 files #24

coilyco-ops referenced this issue from coilyco-flight-deck/scoop-bucket

2026-08-16 06:59:47 +00:00

docs band migration: trim 1 files #12

coilyco-ops referenced this issue from coilyco-flight-deck/umbra

2026-08-16 06:59:48 +00:00

docs band migration: merge 29 docs, trim 29 files #299

coilyco-ops referenced this issue from coilyco-flight-deck/ward

2026-08-16 06:59:49 +00:00

docs band migration: merge 22 docs, trim 36 files #1669

coilyco-ops referenced this issue from coilyco-gaming/eco-app

2026-08-16 06:59:50 +00:00

docs band migration: trim 42 files #307

coilyco-ops referenced this issue from coilyco-gaming/factory-game-v3

2026-08-16 06:59:52 +00:00

docs band migration: merge 8 docs, trim 19 files #91

coilyco-ops referenced this issue from coilyco-gaming/galaxy-gen

2026-08-16 06:59:53 +00:00

docs band migration: merge 21 docs, trim 34 files #87

coilyco-ops referenced this issue from coilyco-gaming/sirens-echo

2026-08-16 06:59:54 +00:00

docs band migration: merge 118 docs #865

coilyco-ops referenced this issue from coilyco-gaming/steam-ops

2026-08-16 06:59:56 +00:00

docs band migration: trim 1 files #19

coilyco-ops referenced this issue from coilysiren/coilysiren

2026-08-16 06:59:57 +00:00

docs band migration: trim 2 files #31

coilyco-ops referenced this issue from coilysiren/website

2026-08-16 07:00:00 +00:00

docs band migration: trim 16 files #117

coilyco-ops added the

labels

2026-08-16 07:01:40 +00:00

coilyco-ops commented

2026-08-16 07:03:24 +00:00

Author

Member

Children

One per repo, each carrying its own measured numbers.

coilyco-gaming/sirens-echo#865 - large - merge 118
coilyco-flight-deck/infrastructure#855 - large - merge 87, trim 2
coilyco-flight-deck/agentic-os#1103 - large - merge 61
coilysiren/lore#18 - small - merge 49, trim 52
coilyco-flight-deck/agent-proxy#132 - small - merge 48, trim 43
coilyco-flight-deck/umbra#299 - small - merge 29, trim 29 - blocked on umbra#298
coilyco-flight-deck/ward#1669 - large - merge 22, trim 36 - blocked on ward#1668
coilyco-flight-deck/agent-compose#292 - large - merge 25
coilyco-gaming/galaxy-gen#87 - small - merge 21, trim 34
coilyco-gaming/factory-game-v3#91 - small - merge 8, trim 19
coilyco-bridge/agentic-os-kai#879 - small - trim 87 - async-consult, 26 content files
coilyco-bridge/deploy#579 - small - trim 53
coilyco-bridge/agentic-os-xxx#36 - small - trim 43
coilyco-gaming/eco-app#307 - small - trim 42 - async-consult, 11 content files
coilyco-bridge/agentic-os-hardware#97 - small - trim 29
coilysiren/voice-corpus#16 - small - trim 20
coilysiren/website#117 - small - trim 16 - async-consult, 12 content files
coilyco-gaming/eco-ops#77 - small - trim 13
coilyco-flight-deck/node-stats-mcp#24 - small - trim 5
coilyco-flight-deck/lunch-money-k8s#43 - small - trim 3
coilysiren/coilysiren#31 - small - trim 2
coilyco-flight-deck/reddit-mcp#18 - small - trim 1
coilyco-flight-deck/scoop-bucket#12 - small - trim 1 - blocked on scoop-bucket#11
coilyco-gaming/steam-ops#19 - small - trim 1

The four coilysiren/* children carry no labels: that namespace is a user
account and cannot hold the scoped taxonomy (agentic-os#1106).

Four repos cannot commit at all until their own pre-commit clears, unrelated to
this work: umbra#298, ward#1668, scoop-bucket#11, website#116.

## Children One per repo, each carrying its own measured numbers. * coilyco-gaming/sirens-echo#865 - large - merge 118 * coilyco-flight-deck/infrastructure#855 - large - merge 87, trim 2 * coilyco-flight-deck/agentic-os#1103 - large - merge 61 * coilysiren/lore#18 - small - merge 49, trim 52 * coilyco-flight-deck/agent-proxy#132 - small - merge 48, trim 43 * coilyco-flight-deck/umbra#299 - small - merge 29, trim 29 - blocked on umbra#298 * coilyco-flight-deck/ward#1669 - large - merge 22, trim 36 - blocked on ward#1668 * coilyco-flight-deck/agent-compose#292 - large - merge 25 * coilyco-gaming/galaxy-gen#87 - small - merge 21, trim 34 * coilyco-gaming/factory-game-v3#91 - small - merge 8, trim 19 * coilyco-bridge/agentic-os-kai#879 - small - trim 87 - async-consult, 26 content files * coilyco-bridge/deploy#579 - small - trim 53 * coilyco-bridge/agentic-os-xxx#36 - small - trim 43 * coilyco-gaming/eco-app#307 - small - trim 42 - async-consult, 11 content files * coilyco-bridge/agentic-os-hardware#97 - small - trim 29 * coilysiren/voice-corpus#16 - small - trim 20 * coilysiren/website#117 - small - trim 16 - async-consult, 12 content files * coilyco-gaming/eco-ops#77 - small - trim 13 * coilyco-flight-deck/node-stats-mcp#24 - small - trim 5 * coilyco-flight-deck/lunch-money-k8s#43 - small - trim 3 * coilysiren/coilysiren#31 - small - trim 2 * coilyco-flight-deck/reddit-mcp#18 - small - trim 1 * coilyco-flight-deck/scoop-bucket#12 - small - trim 1 - blocked on scoop-bucket#11 * coilyco-gaming/steam-ops#19 - small - trim 1 The four coilysiren/* children carry no labels: that namespace is a user account and cannot hold the scoped taxonomy (agentic-os#1106). Four repos cannot commit at all until their own pre-commit clears, unrelated to this work: umbra#298, ward#1668, scoop-bucket#11, website#116.