Restructure README.md and AGENTS.md for the v0.5.0 agentic-os ruleset #18

New issue

Closed

opened 2026-05-27 20:11:38 +00:00 by coilysiren · 1 comment

coilysiren commented

2026-05-27 20:11:38 +00:00

Owner

Problem

After bumping the pinned coilysiren/agentic-os pre-commit rev to v0.5.0 (in the working tree from coilysiren/otel-a2a-relay#17), the catalog-trifecta and documentation-layout hooks fail on baseline content that is unrelated to the doc-cap migration. Each failure is structural and editorial enough that it deserves Kai's hand on the prose. While these remain, no commit can land in the repo.

Concrete failures from the latest pre-commit run:

README.md - 146 lines / 11704 chars. Over the 80-line / 4000-char cap by ~3x. Needs a heavy split into multiple flat docs/*.md files or an aggressive trim.
AGENTS.md - 4600 chars. Slightly over cap, and missing the 9 required H2 sections introduced in v0.5.0 of agentic-os: ## Scope, ## Project shape, ## Repo boundaries, ## Commands, ## Validation, ## Safety, ## Cross-repo contracts, ## Release, ## Agent rules. Needs a restructure that probably wants to inherit whatever canonical pattern is settled on elsewhere in coilysiren/*.
catalog-trifecta cite - README.md, AGENTS.md, and docs/FEATURES.md currently cite coilysiren/coilyco-ai#313. The v0.5.0 hook accepts only coilysiren/agentic-os#59 or the legacy coilysiren/agentic-os-kai#313. One-line footer fix per file.

Out of scope (already landed in coilysiren/otel-a2a-relay#17 working tree)

All three oversized docs/*.md files split (channels-protocol, protocol, protocols-survey).
All three oversized skills/*/SKILL.md files trimmed (grafana split into peer files).
examples/luca-flow/README.md trimmed, overflow in docs/luca-flow-spans.md.
docs/FEATURES.md condensed.
pyproject.toml excludes for workspace-member READMEs, docs/generated/, generated test artifacts, and .claude/.
.pre-commit-config.yaml bumped to v0.5.0 so the excludes mechanism actually loads (added in v0.4.0).

Why this is a separate issue

The doc-cap migration (#17) was sized for the 8 files that pre-commit explicitly flagged for size. The v0.5.0 rev bump pulled in two additional rules that v0.3.0 did not enforce (the catalog-trifecta convention citation, and the required-H2-sections check on AGENTS.md). Those rules apply to README.md and AGENTS.md, which were not on the size list because they were under the v0.3.0 ruleset's radar (catalog-trifecta was advisory in older revs).

Completion contract. This issue was filed as a sidequest, so its session is expected to finish hands-off. When the work is fully complete and verified - committed, pushed, and merged to main, checks green - and it needed no human decision to land (humans can post-review after the fact), do not stop at an idle prompt. End the session by running coily session end from a Bash tool call. That verb walks the process ancestry to the claude CLI process and signals it, so the session exits cleanly and Warp shows the big red "process exited" banner. The verb is allowlisted because Kai authorized this exact, accurately-named capability, and the audit row records the deliberate end. This is expected and safe: the dangerous failure mode is an agent that resists shutdown, not one that ends itself when its work is done.

Do NOT end the session if the work genuinely needs a human decision before it can land (an irreversible op, a design fork only Kai can call, a blocked dependency). In that case stop at the prompt and say plainly what you need. "Humans can review later" is fine and still self-ends. "A human must decide before merge" is not - leave that session open.

**Problem** After bumping the pinned `coilysiren/agentic-os` pre-commit rev to v0.5.0 (in the working tree from coilysiren/otel-a2a-relay#17), the `catalog-trifecta` and `documentation-layout` hooks fail on baseline content that is unrelated to the doc-cap migration. Each failure is structural and editorial enough that it deserves Kai's hand on the prose. While these remain, no commit can land in the repo. Concrete failures from the latest pre-commit run: 1. `README.md` - 146 lines / 11704 chars. Over the 80-line / 4000-char cap by ~3x. Needs a heavy split into multiple flat `docs/*.md` files or an aggressive trim. 2. `AGENTS.md` - 4600 chars. Slightly over cap, and missing the 9 required H2 sections introduced in v0.5.0 of agentic-os: `## Scope`, `## Project shape`, `## Repo boundaries`, `## Commands`, `## Validation`, `## Safety`, `## Cross-repo contracts`, `## Release`, `## Agent rules`. Needs a restructure that probably wants to inherit whatever canonical pattern is settled on elsewhere in `coilysiren/*`. 3. `catalog-trifecta` cite - `README.md`, `AGENTS.md`, and `docs/FEATURES.md` currently cite `coilysiren/coilyco-ai#313`. The v0.5.0 hook accepts only `coilysiren/agentic-os#59` or the legacy `coilysiren/agentic-os-kai#313`. One-line footer fix per file. **Out of scope (already landed in coilysiren/otel-a2a-relay#17 working tree)** - All three oversized `docs/*.md` files split (channels-protocol, protocol, protocols-survey). - All three oversized `skills/*/SKILL.md` files trimmed (grafana split into peer files). - `examples/luca-flow/README.md` trimmed, overflow in `docs/luca-flow-spans.md`. - `docs/FEATURES.md` condensed. - `pyproject.toml` excludes for workspace-member READMEs, `docs/generated/`, generated test artifacts, and `.claude/`. - `.pre-commit-config.yaml` bumped to v0.5.0 so the excludes mechanism actually loads (added in v0.4.0). **Why this is a separate issue** The doc-cap migration (#17) was sized for the 8 files that pre-commit explicitly flagged for size. The v0.5.0 rev bump pulled in two additional rules that v0.3.0 did not enforce (the catalog-trifecta convention citation, and the required-H2-sections check on AGENTS.md). Those rules apply to README.md and AGENTS.md, which were not on the size list because they were under the v0.3.0 ruleset's radar (`catalog-trifecta` was advisory in older revs). > **Completion contract.** This issue was filed as a sidequest, so its session is expected to finish hands-off. When the work is fully complete and verified - committed, pushed, and merged to `main`, checks green - and it needed no human decision to land (humans can post-review after the fact), do not stop at an idle prompt. End the session by running `coily session end` from a Bash tool call. That verb walks the process ancestry to the `claude` CLI process and signals it, so the session exits cleanly and Warp shows the big red "process exited" banner. The verb is allowlisted because Kai authorized this exact, accurately-named capability, and the audit row records the deliberate end. This is expected and safe: the dangerous failure mode is an agent that resists shutdown, not one that ends itself when its work is done. > > Do NOT end the session if the work genuinely needs a human decision before it can land (an irreversible op, a design fork only Kai can call, a blocked dependency). In that case stop at the prompt and say plainly what you need. "Humans can review later" is fine and still self-ends. "A human must decide before merge" is not - leave that session open.

coilysiren commented

2026-05-30 05:44:02 +00:00

Author

Owner

Merged into #11 in the 2026-05-29 backlog burn-down. Same catalog-trifecta/doc restructure as #11 Reopen if it should stand alone.

coilysiren closed this issue

2026-05-30 05:44:02 +00:00

coilysiren added the

label

2026-05-31 01:55:14 +00:00

No labels

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

coilyco-flight-deck/otel-a2a-relay#18

No description provided.

Rows
Columns