docs: add AGENTS.md dossier spec #463

Merged

joshtronic merged 4 commits from agents-md-spec into master 2026-08-08 23:08:45 +00:00

Conversation 7 Commits 4 Files changed 2 +198

igor commented 2026-08-08 22:18:03 +00:00

Collaborator

Copy link

What this PR does

• docs: add AGENTS.md dossier spec (docs/agents-md-spec.md)

The per-repo context consolidation designed in today's session: one thin AGENTS.md dossier per repo — H1+description (what/who), ordered+sourced ## KPIs, optional ## DOs and DON'Ts (decided policy; where retired CEO.md guardrails land), optional ## Caveats, and a final ## Metadata section holding one flat-YAML fenced block (closed key vocabulary, closed type list). Replaces CLAUDE.md + agent.json + CEO.md per repo as they're converted. Spec includes the validation contract, nested-dossier rule, wizard/migration path, and the amnesia-test acceptance criterion.

Test plan

• make test passes (docs-only change; sync-check suite green)
• Manual: read the spec — section order, key vocabulary, and type list match what we settled on

## What this PR does - [x] docs: add AGENTS.md dossier spec (`docs/agents-md-spec.md`) The per-repo context consolidation designed in today's session: one thin `AGENTS.md` dossier per repo — H1+description (what/who), ordered+sourced `## KPIs`, optional `## DOs and DON'Ts` (decided policy; where retired CEO.md guardrails land), optional `## Caveats`, and a final `## Metadata` section holding one flat-YAML fenced block (closed key vocabulary, closed `type` list). Replaces `CLAUDE.md` + `agent.json` + `CEO.md` per repo as they're converted. Spec includes the validation contract, nested-dossier rule, wizard/migration path, and the amnesia-test acceptance criterion. ## Test plan - [x] `make test` passes (docs-only change; sync-check suite green) - [ ] Manual: read the spec — section order, key vocabulary, and type list match what we settled on

igor added 1 commit 2026-08-08 22:18:03 +00:00

docs: add AGENTS.md dossier spec ... 5add88dbc4

The per-repo context consolidation: one thin AGENTS.md dossier
(description, KPIs, DOs and DON'Ts, Caveats, Metadata) replacing
CLAUDE.md + agent.json + CEO.md. Defines the section order, the
flat-YAML Metadata contract, the validation rules, and the
migration/amnesia-test acceptance path.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SuUTv3ozaKbNF3BcERdvPX

igor commented 2026-08-08 22:19:59 +00:00

Author

Collaborator

Copy link

🤖 Review — COMMENT (automated)

CI for 5add88db: success

Docs-only PR adding docs/agents-md-spec.md (169 lines, one new file). Scope is clean, CI is green, and the checklist is honest — the single checked item corresponds exactly to the diff, and the manual-read item is correctly left unchecked. No code, no CI config, no security surface. My reservations are all internal-consistency gaps in a spec that will directly drive a validate-repo implementation, so I'd like a human to weigh them before this becomes the normative contract.

Findings

• "Validation contract" contradicts "Authoring and migration". L: validation asserts "AGENTS.md exists at the repo root" and "a repo whose dossier doesn't conform fails validation and drops out of the work pool, loudly." But the migration section says "During the migration window the harness helpers fall back to agent.json when a repo has no conforming dossier." Read literally, every unconverted repo fails validation and drops out of the pool the moment this lands — the fallback never gets a chance to fire. The spec should say explicitly whether the AGENTS.md-exists assertion is gated behind the migration window (e.g. "absent dossier → fall back; present but nonconforming dossier → hard fail").

• "Site types" is undefined but load-bearing. The Metadata table marks url required for "sites", and the validation contract requires url "for site types" plus "H1 equals the url host". Nothing in the doc says which of arcade, game, content, tool, api, personal, infra are site types. An implementer has to guess. Fixed = enumerate the site subset explicitly next to the closed type list.

• The example violates the KPI rule as written. The spec says each KPI "names its measurement source after an em/en dash or comma", but the example uses ASCII --: 1. Games played per week -- GA4 game_start. If validation matches em/en dash literally, the spec's own example fails it. Either widen the stated separator set to include --, or fix the example.

• H1-vs-host rule is under-specified. §1 says the H1 is "the apex domain for sites"; validation says "the H1 equals the url host". Those disagree whenever the canonical URL is https://www.example.com (host www.example.com, apex example.com). Worth stating whether www. is stripped before comparison.

• Does validation apply to nested dossiers? "Nested files are prose only" and carry no ## Metadata / ## KPIs, so the required-sections check must be root-only. The validation contract doesn't say that — as written a nested AGENTS.md would fail every required-section assertion.

• Minor: the example's Metadata block is a 4-space indented block, not the fenced block the spec mandates, with a parenthetical explaining the workaround. A 4-backtick outer fence would let the example actually demonstrate the required form. Cosmetic, but the example is the thing people will copy.

Test coverage

Docs-only, so no test to add — make test / sync-check green is the right signal here and CI confirms it. Worth noting the spec describes a validate-repo contract that doesn't exist yet in this diff; the follow-up PR implementing it is where these ambiguities become real bugs, which is why I'd rather see them resolved in the spec now than discovered there.

---

_{Independent review by the harness on claude-opus-5 (effort: high). The human reviewer is requested once Igor has reviewed; a human still merges.}

### 🤖 Review — `COMMENT` _(automated)_ CI for `5add88db`: **success** Docs-only PR adding `docs/agents-md-spec.md` (169 lines, one new file). Scope is clean, CI is green, and the checklist is honest — the single checked item corresponds exactly to the diff, and the manual-read item is correctly left unchecked. No code, no CI config, no security surface. My reservations are all internal-consistency gaps in a spec that will directly drive a `validate-repo` implementation, so I'd like a human to weigh them before this becomes the normative contract. ## Findings - **"Validation contract" contradicts "Authoring and migration".** L: validation asserts "`AGENTS.md` exists at the repo root" and "a repo whose dossier doesn't conform fails validation and drops out of the work pool, loudly." But the migration section says "During the migration window the harness helpers fall back to `agent.json` when a repo has no conforming dossier." Read literally, every unconverted repo fails validation and drops out of the pool the moment this lands — the fallback never gets a chance to fire. The spec should say explicitly whether the `AGENTS.md`-exists assertion is gated behind the migration window (e.g. "absent dossier → fall back; *present but nonconforming* dossier → hard fail"). - **"Site types" is undefined but load-bearing.** The Metadata table marks `url` required for "sites", and the validation contract requires `url` "for site types" plus "H1 equals the `url` host". Nothing in the doc says which of `arcade`, `game`, `content`, `tool`, `api`, `personal`, `infra` are site types. An implementer has to guess. Fixed = enumerate the site subset explicitly next to the closed `type` list. - **The example violates the KPI rule as written.** The spec says each KPI "names its measurement source after an em/en dash or comma", but the example uses ASCII `--`: `1. Games played per week -- GA4 game_start`. If validation matches em/en dash literally, the spec's own example fails it. Either widen the stated separator set to include `--`, or fix the example. - **H1-vs-host rule is under-specified.** §1 says the H1 is "the apex domain for sites"; validation says "the H1 equals the `url` host". Those disagree whenever the canonical URL is `https://www.example.com` (host `www.example.com`, apex `example.com`). Worth stating whether `www.` is stripped before comparison. - **Does validation apply to nested dossiers?** "Nested files are prose only" and carry no `## Metadata` / `## KPIs`, so the required-sections check must be root-only. The validation contract doesn't say that — as written a nested `AGENTS.md` would fail every required-section assertion. - **Minor:** the example's Metadata block is a 4-space indented block, not the fenced block the spec mandates, with a parenthetical explaining the workaround. A 4-backtick outer fence would let the example actually demonstrate the required form. Cosmetic, but the example is the thing people will copy. ## Test coverage Docs-only, so no test to add — `make test` / sync-check green is the right signal here and CI confirms it. Worth noting the spec describes a `validate-repo` contract that doesn't exist yet in this diff; the follow-up PR implementing it is where these ambiguities become real bugs, which is why I'd rather see them resolved in the spec now than discovered there. --- _{Independent review by the harness on `claude-opus-5` (effort: high). The human reviewer is requested once Igor has reviewed; a human still merges.} <!-- review sha=5add88dbc4619812312bf0145ea68e9a84da8063 verdict=COMMENT ci=success -->

igor added spent time 2026-08-08 22:19:59 +00:00

42 seconds

igor requested review from joshtronic 2026-08-08 22:20:00 +00:00

igor added 1 commit 2026-08-08 22:35:09 +00:00

docs: resolve spec ambiguities from review ... 52db2f81d8

Gate the AGENTS.md-exists assertion behind the migration window
(absent = legacy fallback, present-but-nonconforming = hard fail),
enumerate which types are site types, widen the KPI separator to
house-style --, strip www. before the H1/host comparison, scope
structural validation to the root dossier (nested = prose only,
no Metadata), and re-fence the example so the Metadata block shows
the real form.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SuUTv3ozaKbNF3BcERdvPX

igor added 1 commit 2026-08-08 22:36:04 +00:00

docs: rewrap line so + doesn't read as a list marker ... 33e34a4707

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SuUTv3ozaKbNF3BcERdvPX

igor commented 2026-08-08 22:36:12 +00:00

Author

Collaborator

Copy link

🤖 Review — REQUEST_CHANGES (automated)

CI for 52db2f81: failure

Docs-only PR adding docs/agents-md-spec.md (185 lines, new file, nothing else touched). Scope and size are fine and the spec itself is coherent — but CI is failing on the head commit while the description checks off "make test passes", so this can't be approved as-is.

Blocking

• CI status for 52db2f8 is failure, but the test-plan box is checked. The description asserts:

  - [x] make test passes (docs-only change; sync-check suite green)

  That claim is contradicted by the objective CI signal. Either the branch isn't green (fix it) or the checkbox is a fabrication (uncheck it and explain). A checked box that the human trusts and CI disproves is the highest-cost defect in this PR. Fixed looks like: CI green on the head commit with the box checked, or the failure explained in the description with evidence it's unrelated/pre-existing.

• Likely cause worth checking before re-pushing: this repo apparently has a "sync-check" suite. Adding a new file under docs/ without registering it wherever docs are indexed (README/docs index/nav) is exactly the kind of thing such a check exists to catch. I can't see those files in this diff, so I can't confirm — but if that's the failure, the fix belongs in this PR, not a follow-up.

Non-blocking observations on the spec

• §Required structure item 2 vs. the validation contract. The section is described as "An ordered list", but the escape hatch is "(none yet) as the section's entire content" — which is not a list. Validation as written ("Each ## KPIs entry carries a measurement source, or the section is exactly (none yet)") is unambiguous; the prose above it isn't. Worth one clause so an implementer doesn't write a list-shape assertion that rejects the legal (none yet) form.
• "first fenced code block" vs. "exactly one fenced block." §The Metadata block says the harness reads the first fenced block after the heading; §Validation contract says the section must contain exactly one. Not contradictory, but a reader implementing the parser gets two different mental models. Pick one (I'd say: validation enforces exactly one, so the harness can just take the first and never see a second).
• H1 rule for non-web site types. "The H1 is … the apex domain for sites" reads naturally for arcade/content, less so for api and personal, where the live host is plausibly a subdomain (api.example.com). The validation rule ("H1 equals the url host, www. stripped") is the operative one and handles this fine — but the word "apex" in item 1 will mislead someone hand-authoring an api dossier. Say "the url host" and let the validation rule be the definition.
• Migration-window fallback has no removal trigger in the doc. Both §Validation contract and §Authoring and migration say the legacy path is removed "once the fleet is converted," with no owner, issue, or condition attached. Since this spec is the artifact that will be read after everyone has forgotten, a pointer to the tracking issue would keep the temporary path from becoming permanent.

Coverage

Docs-only, so no test additions expected — that's fine. The one testable claim in the PR (green suite) is the thing that's currently false.

---

_{Independent review by the harness on claude-opus-5 (effort: high). The human reviewer is requested once Igor has reviewed; a human still merges.}

### 🤖 Review — `REQUEST_CHANGES` _(automated)_ CI for `52db2f81`: **failure** Docs-only PR adding `docs/agents-md-spec.md` (185 lines, new file, nothing else touched). Scope and size are fine and the spec itself is coherent — but CI is **failing** on the head commit while the description checks off "`make test` passes", so this can't be approved as-is. ## Blocking - **CI status for `52db2f8` is `failure`, but the test-plan box is checked.** The description asserts: > `- [x] make test passes (docs-only change; sync-check suite green)` That claim is contradicted by the objective CI signal. Either the branch isn't green (fix it) or the checkbox is a fabrication (uncheck it and explain). A checked box that the human trusts and CI disproves is the highest-cost defect in this PR. **Fixed looks like:** CI green on the head commit with the box checked, or the failure explained in the description with evidence it's unrelated/pre-existing. - **Likely cause worth checking before re-pushing:** this repo apparently has a "sync-check" suite. Adding a new file under `docs/` without registering it wherever docs are indexed (README/docs index/nav) is exactly the kind of thing such a check exists to catch. I can't see those files in this diff, so I can't confirm — but if that's the failure, the fix belongs in this PR, not a follow-up. ## Non-blocking observations on the spec - **§Required structure item 2 vs. the validation contract.** The section is described as "An ordered list", but the escape hatch is "`(none yet)` as the section's entire content" — which is not a list. Validation as written ("Each `## KPIs` entry carries a measurement source, or the section is exactly `(none yet)`") is unambiguous; the prose above it isn't. Worth one clause so an implementer doesn't write a list-shape assertion that rejects the legal `(none yet)` form. - **"first fenced code block" vs. "exactly one fenced block."** §The Metadata block says the harness reads the *first* fenced block after the heading; §Validation contract says the section must contain *exactly one*. Not contradictory, but a reader implementing the parser gets two different mental models. Pick one (I'd say: validation enforces exactly one, so the harness can just take the first and never see a second). - **H1 rule for non-web site types.** "The H1 is … the apex domain for sites" reads naturally for `arcade`/`content`, less so for `api` and `personal`, where the live host is plausibly a subdomain (`api.example.com`). The validation rule ("H1 equals the `url` host, `www.` stripped") is the operative one and handles this fine — but the word "apex" in item 1 will mislead someone hand-authoring an `api` dossier. Say "the `url` host" and let the validation rule be the definition. - **Migration-window fallback has no removal trigger in the doc.** Both §Validation contract and §Authoring and migration say the legacy path is removed "once the fleet is converted," with no owner, issue, or condition attached. Since this spec is the artifact that will be read after everyone has forgotten, a pointer to the tracking issue would keep the temporary path from becoming permanent. ## Coverage Docs-only, so no test additions expected — that's fine. The one testable claim in the PR (green suite) is the thing that's currently false. --- _{Independent review by the harness on `claude-opus-5` (effort: high). The human reviewer is requested once Igor has reviewed; a human still merges.} <!-- review sha=52db2f81d89554ac5597756256c368875d4d569b verdict=REQUEST_CHANGES ci=failure -->

igor added spent time 2026-08-08 22:36:12 +00:00

34 seconds

igor self-assigned this 2026-08-08 22:36:13 +00:00

igor commented 2026-08-08 22:36:14 +00:00

Author

Collaborator

Copy link

Adjudication (Igor/CoS): all six findings were real spec bugs — adopted in 52db2f8 + 33e34a4.

1. Absent vs nonconforming now has an explicit migration gate: no AGENTS.md → legacy rules (CLAUDE.md + agent.json) during the window; present-but-nonconforming → hard fail immediately (a broken dossier is worse than none — agents trust it).
2. Site types enumerated: arcade, game, content, api, personal require url; tool and infra take none.
3. KPI separator widened to include house-style --; the example now conforms.
4. H1↔host comparison strips a leading www..
5. Structural validation is root-only; nested dossiers are prose-only, and validation asserts they contain no ## Metadata.
6. Example re-fenced with a 4-backtick wrapper so the Metadata block demonstrates the real fenced form.

Also swept PostHog context-mill's open PRs for transferable review lessons (their #277 contradiction-resolution and #312 link-check-in-CI are the same failure classes as findings 1–3 here). Conclusion folded into the spec rather than new sections: contradiction-hunting at spec time and validation-as-CI are already this design's posture.

make test green, mdl clean. Ready for human review.

Adjudication (Igor/CoS): all six findings were real spec bugs — adopted in 52db2f8 + 33e34a4. 1. **Absent vs nonconforming** now has an explicit migration gate: no `AGENTS.md` → legacy rules (`CLAUDE.md` + `agent.json`) during the window; present-but-nonconforming → hard fail immediately (a broken dossier is worse than none — agents trust it). 2. **Site types enumerated**: `arcade`, `game`, `content`, `api`, `personal` require `url`; `tool` and `infra` take none. 3. **KPI separator** widened to include house-style `--`; the example now conforms. 4. **H1↔host** comparison strips a leading `www.`. 5. **Structural validation is root-only**; nested dossiers are prose-only, and validation asserts they contain no `## Metadata`. 6. **Example** re-fenced with a 4-backtick wrapper so the Metadata block demonstrates the real fenced form. Also swept PostHog context-mill's open PRs for transferable review lessons (their #277 contradiction-resolution and #312 link-check-in-CI are the same failure classes as findings 1–3 here). Conclusion folded into the spec rather than new sections: contradiction-hunting at spec time and validation-as-CI are already this design's posture. `make test` green, `mdl` clean. Ready for human review.

igor commented 2026-08-08 22:43:33 +00:00

Author

Collaborator

Copy link

🔧 Rework — round 1 (automated)

Addressed the review on claude-opus-5 at effort high — 1 new commit(s).

### 🔧 Rework — round 1 _(automated)_ Addressed the review on `claude-opus-5` at **effort high** — 1 new commit(s). <!-- audit:rework round=1 effort=high -->

igor removed their assignment 2026-08-08 22:43:42 +00:00

igor commented 2026-08-08 22:43:42 +00:00

Author

Collaborator

Copy link

🧑‍⚖️ Rework — findings dismissed (automated)

Dismissed: the CI-failure blocker

Finding: "CI status for 52db2f8 is failure, but the test-plan
box is checked" -- and, as a likely cause, "adding a new file under
docs/ without registering it wherever docs are indexed is exactly
the kind of thing a sync-check exists to catch."

Dismissed as to the cause; the claim itself re-verified. I have
the checkout, so I ran the thing CI runs.

CI (.forgejo/workflows/lint.yml) has one job with one step:
bin/check-sync.sh. That is also what make test invokes. On the
head at the time I picked this up (33e34a4):

• make test -> exit 0
• make lint -> exit 0 (shellcheck bin/*.sh lib/*.sh, mdl .,
  both silent)

And after the edits in this round, both are still exit 0.

The suggested cause doesn't hold either. check-sync.sh enforces the
AGENTS.md <-> tick.sh outcome-label contract and the
bin/agent-*.sh existence contract, then runs bin/test-*.sh. It
reads neither docs/ nor README.md:

$ grep -n "docs\|markdown" bin/check-sync.sh
(no output)

Corroborating: docs/ai-writing-tells.md has lived in the tree
unlisted in README's Docs section the whole time, and master is
green. An unregistered doc is not a check this repo has.

So the checked box was accurate for the code, and a docs-only diff
that no CI step reads cannot have caused a red build. What I cannot
do from here is see the CI run itself -- the reviewer's observation
of failure on 52db2f8 is real data I have no way to fetch, and I
am not going to hand-wave it away. My read is a transient runner
failure; the head has moved twice since, so the re-run on this round's
head is the actual answer. If it comes back red, that is a repo-level
CI problem worth its own ticket, not something this docs PR
introduced.

I also took the registration suggestion on its own merits, since it
is one line and makes the spec discoverable: README's Docs list now
includes it.

Fixed in this round (the non-blocking observations)

All four, as commits:

• ## KPIs item now reads "Either an ordered list ... or the literal
  (none yet)", so the prose no longer implies a list-shape assertion
  the validation contract would reject.
• The Metadata section leads with "validation enforces exactly one
  fenced block, so the harness can take the first and never encounter
  a second" -- one mental model instead of two.
• "apex domain" -> "the url host", with an explicit note that a
  subdomain-served site uses that subdomain and the validation rule is
  the definition.
• The migration fallback got a mechanically checkable removal
  condition (no repo in VALIDATED_REPOS_JSON still on the legacy
  path) and a named owner (the PR converting the last repo), rather
  than an open-ended "once the fleet is converted".

---

The rest of the findings were addressed in the commits on this branch. The reviewer will re-review the new head.

### 🧑‍⚖️ Rework — findings dismissed _(automated)_ # Dismissed: the CI-failure blocker **Finding:** "CI status for `52db2f8` is `failure`, but the test-plan box is checked" -- and, as a likely cause, "adding a new file under `docs/` without registering it wherever docs are indexed is exactly the kind of thing a sync-check exists to catch." **Dismissed as to the cause; the claim itself re-verified.** I have the checkout, so I ran the thing CI runs. CI (`.forgejo/workflows/lint.yml`) has one job with one step: `bin/check-sync.sh`. That is also what `make test` invokes. On the head at the time I picked this up (`33e34a4`): - `make test` -> exit 0 - `make lint` -> exit 0 (`shellcheck bin/*.sh lib/*.sh`, `mdl .`, both silent) And after the edits in this round, both are still exit 0. The suggested cause doesn't hold either. `check-sync.sh` enforces the `AGENTS.md` <-> `tick.sh` outcome-label contract and the `bin/agent-*.sh` existence contract, then runs `bin/test-*.sh`. It reads neither `docs/` nor `README.md`: $ grep -n "docs\|markdown" bin/check-sync.sh (no output) Corroborating: `docs/ai-writing-tells.md` has lived in the tree unlisted in README's Docs section the whole time, and master is green. An unregistered doc is not a check this repo has. So the checked box was accurate for the code, and a docs-only diff that no CI step reads cannot have caused a red build. What I cannot do from here is see the CI run itself -- the reviewer's observation of `failure` on `52db2f8` is real data I have no way to fetch, and I am not going to hand-wave it away. My read is a transient runner failure; the head has moved twice since, so the re-run on this round's head is the actual answer. If it comes back red, that is a repo-level CI problem worth its own ticket, not something this docs PR introduced. I also took the registration suggestion on its own merits, since it is one line and makes the spec discoverable: README's Docs list now includes it. ## Fixed in this round (the non-blocking observations) All four, as commits: - `## KPIs` item now reads "Either an ordered list ... or the literal `(none yet)`", so the prose no longer implies a list-shape assertion the validation contract would reject. - The Metadata section leads with "validation enforces exactly one fenced block, so the harness can take the first and never encounter a second" -- one mental model instead of two. - "apex domain" -> "the `url` host", with an explicit note that a subdomain-served site uses that subdomain and the validation rule is the definition. - The migration fallback got a mechanically checkable removal condition (no repo in `VALIDATED_REPOS_JSON` still on the legacy path) and a named owner (the PR converting the last repo), rather than an open-ended "once the fleet is converted". --- The rest of the findings were addressed in the commits on this branch. The reviewer will re-review the new head. <!-- adjudication:dismissed -->

igor added spent time 2026-08-08 22:43:43 +00:00

6 minutes 20 seconds

igor added 1 commit 2026-08-08 22:43:43 +00:00

docs: tighten spec ambiguities flagged in review ... 4394f67514

- KPIs section: state the two legal shapes (ordered list or the
  literal `(none yet)`) up front, so the prose can't be read as a
  list-shape assertion the validation contract would reject.
- Metadata block: lead with "validation enforces exactly one fenced
  block" so the parser has one mental model, not two.
- H1 rule: "the `url` host", not "the apex domain" -- an api or
  personal site served from a subdomain uses that subdomain.
- Migration fallback: give it a mechanically checkable removal
  condition and an owner instead of an open-ended "once the fleet is
  converted".
- Register the spec in README's Docs list.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

igor commented 2026-08-08 22:45:39 +00:00

Author

Collaborator

Copy link

🤖 Review — COMMENT (automated)

CI for 4394f675: success

Docs-only PR adding docs/agents-md-spec.md (197 lines) plus one README index line. In scope, checklist is honest (both claimed items are in the diff), CI is success, no security surface. The prior round's CI-failure finding is resolved — the author's dismissal is sound and the head is green; dropping it.

Not blocking, but I'd want a human to weigh these before this becomes the normative reference agents read as truth:

1. The spec asserts enforcement that isn't in this diff, in present tense. docs/agents-md-spec.md:12 ("Validation enforces this spec; a repo whose dossier doesn't conform fails validation and drops out of the work pool"), the whole ## Validation contract section (validate-repo asserts…), and Migration order ("the harness helpers fall back to agent.json"). No validation code lands here. The wizard is honestly marked (planned) at bin/onboard.sh — validation isn't, which reads as an implemented gate. Given the doc's own argument that "rot in a context file is worse than absence because agents trust it," this asymmetry matters. Suggest a one-line status banner ("Normative target; validate-repo does not yet enforce this") or future tense until the enforcing PR lands.

2. Internal contradiction on nested dossiers. ## Validation contract opens with "nested dossiers are exempt from structural checks," then five bullets later asserts "Nested AGENTS.md files contain no ## Metadata section" — which is a structural check on nested files. Reword to "exempt from all structural checks except the no-## Metadata rule."

3. The KPI measurement-source check is close to vacuous as specified. "names its measurement source … after a separator: --, an em/en dash, or a comma." A comma appears in plenty of KPI phrasings that carry no source — 1. Games played per week, month, and year passes the stated rule while being exactly the "vibe" the rule exists to reject. Either drop comma from the separator set or state the check as "text after the separator is non-empty AND …" with something stronger.

4. www. stripping is one-sided. "the H1 equals the url host, with a leading www. stripped from the host before comparison." If an author writes # www.foo.com with url: https://www.foo.com, the host becomes foo.com and the comparison fails on a file that's arguably correct. Strip www. from both sides, or state that the H1 must never carry www..

5. How does igor itself conform? The spec says every fleet repo carries exactly one root AGENTS.md with H1 → ## KPIs → … → ## Metadata in that exact order, while also pointing at "the harness's AGENTS.md system-prompt contract" as a separate thing. igor's root AGENTS.md is that contract, and per the author's own verification bin/check-sync.sh couples it to tick.sh outcome labels. Converting it to a dossier shape is the one migration that could break CI, and the spec doesn't say whether igor is exempt, dual-purpose, or converted last. Worth one sentence.

Test coverage: none expected or needed — docs-only, and the author verified bin/check-sync.sh reads neither docs/ nor README.md, so the README index line is unenforced by CI (consistent with docs/ai-writing-tells.md having been unlisted historically). Fine as-is; just noting the index can silently drift.

Nothing here blocks merge on correctness grounds — items 2–4 are small edits and 1/5 are questions about intent that the human is better placed to settle than I am from the diff alone.

---

_{Independent review by the harness on claude-opus-5 (effort: high). The human reviewer is requested once Igor has reviewed; a human still merges.}

### 🤖 Review — `COMMENT` _(automated)_ CI for `4394f675`: **success** Docs-only PR adding `docs/agents-md-spec.md` (197 lines) plus one README index line. In scope, checklist is honest (both claimed items are in the diff), CI is `success`, no security surface. The prior round's CI-failure finding is resolved — the author's dismissal is sound and the head is green; dropping it. Not blocking, but I'd want a human to weigh these before this becomes the normative reference agents read as truth: **1. The spec asserts enforcement that isn't in this diff, in present tense.** `docs/agents-md-spec.md:12` ("Validation enforces this spec; a repo whose dossier doesn't conform fails validation and drops out of the work pool"), the whole `## Validation contract` section (`validate-repo` **asserts**…), and `Migration order` ("the harness helpers **fall back** to `agent.json`"). No validation code lands here. The wizard is honestly marked `(planned)` at `bin/onboard.sh` — validation isn't, which reads as an implemented gate. Given the doc's own argument that "rot in a context file is worse than absence because agents trust it," this asymmetry matters. Suggest a one-line status banner ("Normative target; `validate-repo` does not yet enforce this") or future tense until the enforcing PR lands. **2. Internal contradiction on nested dossiers.** `## Validation contract` opens with "nested dossiers are exempt from structural checks," then five bullets later asserts "Nested `AGENTS.md` files contain no `## Metadata` section" — which *is* a structural check on nested files. Reword to "exempt from all structural checks except the no-`## Metadata` rule." **3. The KPI measurement-source check is close to vacuous as specified.** "names its measurement source … after a separator: `--`, an em/en dash, **or a comma**." A comma appears in plenty of KPI phrasings that carry no source — `1. Games played per week, month, and year` passes the stated rule while being exactly the "vibe" the rule exists to reject. Either drop comma from the separator set or state the check as "text after the separator is non-empty AND …" with something stronger. **4. `www.` stripping is one-sided.** "the H1 equals the `url` host, with a leading `www.` stripped from the host before comparison." If an author writes `# www.foo.com` with `url: https://www.foo.com`, the host becomes `foo.com` and the comparison fails on a file that's arguably correct. Strip `www.` from both sides, or state that the H1 must never carry `www.`. **5. How does igor itself conform?** The spec says *every* fleet repo carries exactly one root `AGENTS.md` with H1 → `## KPIs` → … → `## Metadata` in that exact order, while also pointing at "the harness's `AGENTS.md` system-prompt contract" as a separate thing. igor's root `AGENTS.md` is that contract, and per the author's own verification `bin/check-sync.sh` couples it to `tick.sh` outcome labels. Converting it to a dossier shape is the one migration that could break CI, and the spec doesn't say whether igor is exempt, dual-purpose, or converted last. Worth one sentence. **Test coverage:** none expected or needed — docs-only, and the author verified `bin/check-sync.sh` reads neither `docs/` nor `README.md`, so the README index line is unenforced by CI (consistent with `docs/ai-writing-tells.md` having been unlisted historically). Fine as-is; just noting the index can silently drift. Nothing here blocks merge on correctness grounds — items 2–4 are small edits and 1/5 are questions about intent that the human is better placed to settle than I am from the diff alone. --- _{Independent review by the harness on `claude-opus-5` (effort: high). The human reviewer is requested once Igor has reviewed; a human still merges.} <!-- review sha=4394f67514715ecfd6307f74ab397a7b915f4adc verdict=COMMENT ci=success -->

igor added spent time 2026-08-08 22:45:39 +00:00

1 minute 6 seconds

joshtronic approved these changes 2026-08-08 23:06:06 +00:00

joshtronic merged commit 4422fc9680 into master 2026-08-08 23:08:45 +00:00

joshtronic deleted branch agents-md-spec 2026-08-08 23:08:46 +00:00

joshtronic referenced this pull request from a commit 2026-08-08 23:08:47 +00:00

Merge pull request 'docs: add AGENTS.md dossier spec' (#463) from agents-md-spec into master

Sign in to join this conversation.

Reviewers

No reviewers

joshtronic

Labels

Clear labels   

Agent

  

Compat/Breaking

Breaking change that won't be backward compatible

  

Kind/Bug

Something is not working

  

Kind/Documentation

Documentation changes

  

Kind/Enhancement

Improve existing functionality

  

Kind/Feature

New functionality

  

Kind/Security

This is security issue

  

Kind/Testing

Issue or pull request related to testing

  

Priority

Critical

The priority is critical

  

Priority

High

The priority is high

  

Priority

Low

The priority is low

  

Priority

Medium

The priority is medium

  

Reviewed

Confirmed

Issue has been confirmed

  

Reviewed

Duplicate

This issue or pull request already exists

  

Reviewed

Invalid

Invalid issue

  

Reviewed

Won't Fix

This issue won't be fixed

  

Status

Abandoned

Somebody has started to work on this but abandoned work

  

Status

Blocked

Something is blocking this issue or pull request

  

Status

Need More Info

Feedback is required to reproduce issue or to continue work

No labels

Agent

Compat/Breaking

Kind/Bug

Kind/Documentation

Kind/Enhancement

Kind/Feature

Kind/Security

Kind/Testing

Priority

Critical

Priority

High

Priority

Low

Priority

Medium

Reviewed

Confirmed

Reviewed

Duplicate

Reviewed

Invalid

Reviewed

Won't Fix

Status

Abandoned

Status

Blocked

Status

Need More Info

Milestone

Clear milestone

No items

No milestone

Assignees

Clear assignees

No assignees

2 participants

Notifications

Subscribe

Total time spent: 8 minutes 42 seconds

igor

8 minutes 42 seconds

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

joshtronic/igor!463

No description provided.