feat: scaffold layered agent instruction files from shipped templates - #1
Merged
Conversation
Every assistant reads project law from a different filename in the repository root, so the law gets written three times and drifts. Ship one layered set instead: AGENTS.md is canonical and read natively by Codex and opencode, while CLAUDE.md and GEMINI.md import it and carry only assistant-specific mechanics. relay setup writes any of the three that are missing from templates/agent-instructions/ and adds all three to the project's local git exclude state; relay doctor reports which are present. An existing file is never touched - by then it is the project's own law and a template is only a starting point. The test covers both branches plus a rerun, since the project fixture already ships its own copies. The exclude entries and this repository's own .gitignore lines are root-anchored. An unanchored `AGENTS.md` matches at every depth, which would ignore both the shipped templates here and a package-level AGENTS.md an adopting project tracks. The templates carry only what is true for any project: the inherited-BEADS_DIR trap that silently routes bd calls into another project's store, verify-don't-trust delegation, no AI attribution, and Beads as the only durable task system. Project-specific content is left as explicit placeholders. The files stay local and uncommitted: they name per-machine tooling and model choices, and a project's rules are not Agent Relay's to version. Verified: 117 pass / 0 fail, lint and check green.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Ships one layered set of agent instruction files so project law is written once instead of three times.
AGENTS.mdis canonical — Codex and opencode read it natively — whileCLAUDE.mdandGEMINI.mdimport it and carry only assistant-specific mechanics.Changes
templates/agent-instructions/{AGENTS,CLAUDE,GEMINI}.md— generic templates for adopting projects, with explicit placeholders for project-specific content.src/lib/agent-instructions.mjs— scaffold missing files, report status; never overwrite an existing file.relay setupwrites the missing files and adds all three to the project's local git exclude state.relay doctorreports which are present..gitignorekeeps this repository's own copies local.skills/relay/SKILL.mdguidance.Evidence
npm test— 117 pass / 0 fail (was 116; one new test).npm run lint— green (link check, privacy scan, site and marketplace validation).npm run check— green (byte-identity of generated role and adapter output).git check-ignore -vreports the root paths ignored and exits non-zero for the template paths.Notes
Two details worth a reviewer's attention:
Root-anchored ignore patterns. A bare
AGENTS.mdpattern matches at every depth. Unanchored, it silently ignored the shipped templates in this repository, and in an adopting project it would ignore a package-levelAGENTS.mdthat project legitimately tracks. Both the.gitignorelines and the generated exclude entries are/-anchored, with a comment saying why.No-overwrite is under test. The project fixture already ships its own three files, so the test asserts the preserve branch against it, then removes them to assert the write branch, then edits one and reruns to confirm neither the file nor the exclude entry is touched twice.
Out of scope
The instruction files themselves stay uncommitted by design — they name per-machine tooling and model choices, and a project's rules are not Agent Relay's to version. That also means
git clean -xfddeletes them; the templates are the recovery path.