A repo with its own AGENTS.md gets specd's four rules, not a second rulebook - #124
Merged
Merged
Conversation
…ulebook Reported from a real onboarding: portal-app already had an AGENTS.md saying much of what the template says, and setup appended the whole template under it. Two statements of the same practice is worse than either — an agent follows whichever it reads first, and a reader cannot tell which is current. The template is a complete set of engineering rules: read the docs before implementing, cite what you relied on, update them in the same PR, never rewrite a delivered spec. A team that has written its own AGENTS.md has usually said all of that already, in its own words, and it is their repository. So there are now two renderings. With no existing file, the full document, as before — nothing to duplicate. With one, `renderAgentsSupplement`: the four things specd's machinery actually enforces, and where the knowledge base is. Approved specs and `specd spec pull`, the branch and PR-title shape the webhook matches, the as-built record, and knowledge/. Everything general is left to the team, and the block says so — where the two overlap, theirs wins. Thirty-six lines instead of fifty-eight against a typical file, and none of them a restatement. The fence, the in-place update on re-grounding, and the untouched original are all as they were. The open question and the setup PR body described the old behaviour and now describe this one.
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
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.
Reported from a real onboarding: a repository that already had an
AGENTS.mdcovering much of what specd's template covers, with specd's whole template
appended underneath it.
That was the known weakness of the merge added in #115 — it kept the team's
file intact, which was the point, but had no way to avoid restating them.
Two statements of one practice is worse than either
specd's template is a complete set of engineering rules: read the docs before
implementing, cite what you relied on, update them in the same pull request,
never rewrite a delivered spec. A team that has written its own
AGENTS.mdhasusually said all of that already — in its own words, for its own repository.
Appending the template under theirs produces a file where an agent follows
whichever copy it reads first and a reader cannot tell which is current.
So: two renderings
AGENTS.mdrenderAgentsSupplement— only what is specd'sThe supplement is the four things specd's machinery actually enforces,
which is exactly the part a team cannot already have written:
specd spec pull <id>, and the serverrefuses an unapproved one.
spec/<ID>-<slug>, PR titled[<ID>] - <Title>— the shape the mergewebhook matches back to the spec.
knowledge/specs/.knowledge/, and specd re-indexes it on merge.Plus the MCP wiring, which is configuration rather than a rule.
Everything general is left to the team, and the block says so in its opening
line: "The agreements above still stand… where the two overlap, yours win and
this block is the one to correct." Only a human can resolve an overlap, so it
names who decides rather than pretending to decide.
36 lines instead of 58 against a typical existing file, and none of them a
restatement. The fence, the in-place update on re-grounding, and the untouched
original are all unchanged.
Also updated
The
knowledge/open-questions.mditem and the setup PR body both described theold behaviour — asking a reviewer to reconcile two rule sets that no longer
both exist. They now describe this one, as do the published docs and the README.
Verify
pnpm typecheck && pnpm test,pnpm build,pnpm site:check. Four new tests,including one asserting the merged file does not contain the template's
general rules, and one that an absent
AGENTS.mdstill gets the full document.For the reviewer
AGENTS.mdis oneline about commit messages gets the short block too, and loses guidance the
full template would have given. Detecting actual overlap would mean matching
rules semantically, which is a judgement call I did not want to make
deterministically — and dropping individual numbered rules would break the
cross-references between them (rule 9 refers to rule 3). Presence is the
honest proxy; a team in that position can paste more from
knowledge/README.md, which the scaffold writes regardless.