Skip to content

A repo with its own AGENTS.md gets specd's four rules, not a second rulebook - #124

Merged
unitypark merged 1 commit into
mainfrom
fix/the-agents-supplement-stops-restating-you
Aug 18, 2026
Merged

A repo with its own AGENTS.md gets specd's four rules, not a second rulebook#124
unitypark merged 1 commit into
mainfrom
fix/the-agents-supplement-stops-restating-you

Conversation

@unitypark

Copy link
Copy Markdown
Owner

Reported from a real onboarding: a repository that already had an AGENTS.md
covering 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.md has
usually 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

Repository What setup writes
No AGENTS.md The full document, as before — nothing to duplicate
Has one renderAgentsSupplement — only what is specd's

The supplement is the four things specd's machinery actually enforces,
which is exactly the part a team cannot already have written:

  1. Work arrives as an approved spec — specd spec pull <id>, and the server
    refuses an unapproved one.
  2. Branch spec/<ID>-<slug>, PR titled [<ID>] - <Title> — the shape the merge
    webhook matches back to the spec.
  3. The last task files the as-built copy to knowledge/specs/.
  4. The knowledge base is 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.md item and the setup PR body both described the
old 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.md still gets the full document.

For the reviewer

  • The split is by presence, not by overlap. A repo whose AGENTS.md is one
    line 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.

…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.
@unitypark
unitypark merged commit 530ff80 into main Aug 18, 2026
2 checks passed
@unitypark
unitypark deleted the fix/the-agents-supplement-stops-restating-you branch August 18, 2026 07:23
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant