Add an AGENTS.md that routes rather than restates

[alanhc]

elfuse carries no file at the path an agent's harness opens first.
CONTRIBUTING.md is found by name, and the skills under .claude/skills/
are loaded by description rather than read in order, so an agent starting
cold chooses its own entry point.

AGENTS.md is that entry point, and it routes rather than restates: the
scope in a paragraph, CONTRIBUTING.md before any C, one line per skill for
what each covers, the gate commands, the two prose rules that bind a first
sentence, and the rule about other people's untracked working docs. A rule
copied into it is a rule that can drift, so it carries none of its own.
CLAUDE.md is a symlink to it, the way .agents/skills already symlinks
.claude/skills.

scripts/check-skill-refs.py already took a routing document as an argument,
so make check-skill-refs and the lint workflow name AGENTS.md now. Every
path, make target and skill name in it resolves under the gate a skill file
gets.

Verified on macOS 26.5.2 (25F84), SDK 26.5, Apple M1 Pro:
make check-skill-refs passes its 29 self-test cases and resolves 13 files,
and scripts/check-commit-log.sh passes over the commit. make check does
not run on this machine, which has no aarch64-none-elf-as; the change
touches no C, only one markdown file, one symlink, one make recipe, one
workflow line, and a comment.

The prose-register change that shared this branch is #363 now, since it is a
different subject from a routing file.

[cubic-dev-ai]

2 issues found across 6 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="AGENTS.md">

<violation number="1" location="AGENTS.md:52">
P2: The file's stated purpose is to route and restate nothing, because "a rule copied to a second place is a rule that can drift," but the `## Prose` section restates the two prose rules (ASCII with no markdown syntax; em dash ban) that are already settled in `.claude/skills/elfuse-conventions/references/prose-register.md` ("The two rules that come first, ASCII with no markdown syntax and the em dash ban"), the conventions `SKILL.md`, and `CONTRIBUTING.md`. This creates exactly the drift the opening claim warns against: if the em dash or ASCII rule changes in the skill, this section goes stale silently. Route to the canonical home (prose-register.md / elfuse-conventions) in the section instead of restating the rules, or qualify the "restates nothing" claim to say the two grep-checkable prose rules are restated deliberately.</violation>
</file>

<file name="CLAUDE.md">

<violation number="1" location="CLAUDE.md:1">
P3: CLAUDE.md is committed as a symlink, so it is not what this PR promises in checkouts where symlinks are not preserved: GitHub's Download ZIP (git archive) and Windows/`core.symlinks=false` checkouts materialize it as a regular file whose entire content is the string `AGENTS.md`, breaking the entry-point guarantee for an agent that opens CLAUDE.md first. Nothing in the CI gate (`check-skill-refs.py` reads AGENTS.md, not CLAUDE.md) catches either case. If keeping the symlink is intended, add a gate that asserts CLAUDE.md exists and resolves to AGENTS.md, or note the constraint in README; otherwise commit the content as a real file with a CI equality check so it cannot drift.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

P2: The file's stated purpose is to route and restate nothing, because "a rule copied to a second place is a rule that can drift," but the ## Prose section restates the two prose rules (ASCII with no markdown syntax; em dash ban) that are already settled in .claude/skills/elfuse-conventions/references/prose-register.md ("The two rules that come first, ASCII with no markdown syntax and the em dash ban"), the conventions SKILL.md, and CONTRIBUTING.md. This creates exactly the drift the opening claim warns against: if the em dash or ASCII rule changes in the skill, this section goes stale silently. Route to the canonical home (prose-register.md / elfuse-conventions) in the section instead of restating the rules, or qualify the "restates nothing" claim to say the two grep-checkable prose rules are restated deliberately.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At AGENTS.md, line 52:

<comment>The file's stated purpose is to route and restate nothing, because "a rule copied to a second place is a rule that can drift," but the `## Prose` section restates the two prose rules (ASCII with no markdown syntax; em dash ban) that are already settled in `.claude/skills/elfuse-conventions/references/prose-register.md` ("The two rules that come first, ASCII with no markdown syntax and the em dash ban"), the conventions `SKILL.md`, and `CONTRIBUTING.md`. This creates exactly the drift the opening claim warns against: if the em dash or ASCII rule changes in the skill, this section goes stale silently. Route to the canonical home (prose-register.md / elfuse-conventions) in the section instead of restating the rules, or qualify the "restates nothing" claim to say the two grep-checkable prose rules are restated deliberately.</comment>

<file context>
@@ -0,0 +1,70 @@
+
+## Prose
+
+Two rules bind before the first sentence. Source comments and commit
+messages are ASCII with no markdown syntax, which `make check-ascii` and the
+commit-message hook enforce. The em dash (U+2014) is banned on every surface,
</file context>

[cubic-dev-ai]

P3: CLAUDE.md is committed as a symlink, so it is not what this PR promises in checkouts where symlinks are not preserved: GitHub's Download ZIP (git archive) and Windows/core.symlinks=false checkouts materialize it as a regular file whose entire content is the string AGENTS.md, breaking the entry-point guarantee for an agent that opens CLAUDE.md first. Nothing in the CI gate (check-skill-refs.py reads AGENTS.md, not CLAUDE.md) catches either case. If keeping the symlink is intended, add a gate that asserts CLAUDE.md exists and resolves to AGENTS.md, or note the constraint in README; otherwise commit the content as a real file with a CI equality check so it cannot drift.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At CLAUDE.md, line 1:

<comment>CLAUDE.md is committed as a symlink, so it is not what this PR promises in checkouts where symlinks are not preserved: GitHub's Download ZIP (git archive) and Windows/`core.symlinks=false` checkouts materialize it as a regular file whose entire content is the string `AGENTS.md`, breaking the entry-point guarantee for an agent that opens CLAUDE.md first. Nothing in the CI gate (`check-skill-refs.py` reads AGENTS.md, not CLAUDE.md) catches either case. If keeping the symlink is intended, add a gate that asserts CLAUDE.md exists and resolves to AGENTS.md, or note the constraint in README; otherwise commit the content as a real file with a CI equality check so it cannot drift.</comment>

<file context>
@@ -0,0 +1 @@
+AGENTS.md
\ No newline at end of file
</file context>

[jserv]

Don't do that. Both AGENTS.md and CLAUDE.md should be personal and never checked in repository. Consolidate existing skills instead.