Managed AGENTS.md pointer block: replace dangling relative cross-repo refs with org-aware base URLs #196

New issue

Closed

opened 2026-06-07 20:03:58 +00:00 by coilysiren · 0 comments

coilysiren commented

2026-06-07 20:03:58 +00:00

Owner

Per-repo AGENTS.md files carry a hand-written intro line pointing at the workspace base. It has drifted into 3 styles and several dangle (e.g. See ../AGENTS.md resolves to a non-existent coilyco-bridge/AGENTS.md). The repos live in different org dirs and aren't checked out in a guaranteed sibling layout, so relative FS paths can't work. The canonical content already loads globally via ~/.claude/CLAUDE.md, so the intro line's real job is to orient a reader WITHOUT that load point (foreign agent, single-repo clone, CI), for whom only an absolute URL is true.

Fix: a rendered managed block (mirrors generate_repo_pointer_skill + check_repo_pointer_skills), single-source-of-truth generator, validator regenerates-and-fails-on-drift.

Org-aware target (each org points at its own base, on the host appropriate to its trust tier):

coilyco-flight-deck/* -> GitHub URL to coilyco-flight-deck/agentic-os/AGENTS.md (public base)
coilyco-bridge/* -> public agentic-os/AGENTS.md (GitHub) with private agentic-os-kai/AGENTS.md (Forgejo) layered on top, expressing the layering (aos-pub first, aos-kai on top)
coilysiren/* deferred to a later pass

This issue covers the AUTHORED core only (generator, validator, .pre-commit-hooks.yaml entry, applier script, tests, FEATURES). Fleet rollout (ansible role + bulk render across ~30 repos) is a separate issue per the authoring-vs-rollout split.

Per-repo AGENTS.md files carry a hand-written intro line pointing at the workspace base. It has drifted into 3 styles and several dangle (e.g. `See ../AGENTS.md` resolves to a non-existent coilyco-bridge/AGENTS.md). The repos live in different org dirs and aren't checked out in a guaranteed sibling layout, so relative FS paths can't work. The canonical content already loads globally via ~/.claude/CLAUDE.md, so the intro line's real job is to orient a reader WITHOUT that load point (foreign agent, single-repo clone, CI), for whom only an absolute URL is true. Fix: a rendered managed block (mirrors generate_repo_pointer_skill + check_repo_pointer_skills), single-source-of-truth generator, validator regenerates-and-fails-on-drift. Org-aware target (each org points at its own base, on the host appropriate to its trust tier): - coilyco-flight-deck/* -> GitHub URL to coilyco-flight-deck/agentic-os/AGENTS.md (public base) - coilyco-bridge/* -> public agentic-os/AGENTS.md (GitHub) with private agentic-os-kai/AGENTS.md (Forgejo) layered on top, expressing the layering (aos-pub first, aos-kai on top) - coilysiren/* deferred to a later pass This issue covers the AUTHORED core only (generator, validator, .pre-commit-hooks.yaml entry, applier script, tests, FEATURES). Fleet rollout (ansible role + bulk render across ~30 repos) is a separate issue per the authoring-vs-rollout split.

coilysiren referenced this issue from a commit

2026-06-07 20:13:03 +00:00

feat: add managed AGENTS.md workspace-pointer block

coilysiren closed this issue

2026-06-07 20:13:03 +00:00

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

2026-06-07 20:13:55 +00:00

Roll out the managed AGENTS.md pointer block across consumer repos (ansible + bulk render) #269

coilysiren referenced this issue from a commit

2026-06-07 20:44:36 +00:00

feat: add AGENTS.md pointer-block rollout (migration script + check role)