Skip to content

[Phase 1] Define the AGENTS.md structural rule set and spec-alignment reference #643

Closed

Description

@don-petry

Story

As a org standards maintainer,
I want define a documented, machine-readable structural rule set derived from the stable subset of the AAIF AGENTS.md spec,
so that the linter validates against a single, reviewable source of truth instead of hardcoded or contested assumptions.

Acceptance Criteria

  1. A reference doc at docs/initiatives/agents-md-validation.md documents the initiative scope, the stable structural elements to be validated (single H1 title, heading-hierarchy validity, cross-reference integrity, org-repo import consistency), and the informational-to-blocking promotion criteria.
  2. A machine-readable rule-set data file (e.g. a JSON under scripts/lib/) enumerates each structural check and tags every rule as either 'required' or 'recommended', so recommended items are reported but never fail the check.
  3. The rule set explicitly scopes OUT semantic/content checks; only structural elements are covered, matching the discussion's adversarial rebuttal.
  4. The doc restates the epic's measurable success metrics and the zero-token cost bound so downstream stories inherit them, and cross-links discussion 💡 AGENTS.md Specification Alignment & Automated Validation #534 and idea 💡 Cross-Repo Standards Drift Detection via Multi-Repo Analysis #341.

Tasks / Subtasks

Dev Notes

  • Home: keep the rule set DATA-DRIVEN (a config file the linter reads) so the evolving spec can be updated without code changes — this is the key design constraint given the spec is young and moving.
  • The framework this initiative extends is the compliance audit in scripts/aw-standards-sync.sh, which today only checks file PRESENCE (200 vs 404) against templates in petry-projects/.github, not structural validity.
  • The canonical source-of-truth is petry-projects/.github/AGENTS.md; downstream repos extend it and link back — e.g. this repo's AGENTS.md lines 3-4 reference the canonical file. That link is the basis for the later org-repo import-consistency check.
  • docs/initiatives/ already holds initiative writeups (e.g. idea-to-initiative-pipeline.md); follow that format and location.
  • Do NOT enumerate a contested 'required sections' list as hard-required — the exact required-vs-recommended split is an open question (see open_questions); start with structurally-stable rules marked 'required' (single H1, valid hierarchy, resolvable cross-references) and leave section-presence items 'recommended' until confirmed.

Project Structure Notes

New doc under docs/initiatives/; new rule-set data file under scripts/lib/ (co-located with other shared config like scripts/lib/consumer-manifest.json). No code changes in this story.

References

  • scripts/aw-standards-sync.sh
  • docs/initiatives/idea-to-initiative-pipeline.md
  • AGENTS.md
  • scripts/lib/consumer-manifest.json

Likely target surface

  • docs/initiatives/agents-md-validation.md (new)
  • scripts/lib/agents-md-rules.json (new)

Story prepared by the BMAD Scrum Master (Bob) for epic #642. Status: ready-for-dev.

Activity

  1. don-petry commented on Sep 1, 2026

    @don-petry
    ContributorAuthor

    Dev-Lead Implementation Plan

    Issue: #643 — [Phase 1] Define the AGENTS.md structural rule set and spec-alignment reference

    Scope

    Deliver the documented, machine-readable structural rule set for AGENTS.md validation — a reference doc capturing scope + promotion gate + inherited epic metrics, plus a data-driven rule-set JSON that tags each structural check required vs recommended — with no linter code (that is Phase 2, epic #642).

    Implementation Checklist

    • scripts/lib/agents-md-rules.json (new) — machine-readable rule set: each structural check enumerated and tagged required/recommended; scope: structural; explicit out_of_scope semantic exclusions; captured AAIF/agents.md spec snapshot (source + date); promotion criteria (2 clean cycles + maintainer sign-off); reuses the pr-limits/rate-limits config conventions (_note, _schema_version, inert-on-merge).
    • docs/initiatives/agents-md-validation.md (new) — initiative reference: scope, the stable structural elements (single H1, heading hierarchy, cross-reference integrity, org-repo import consistency), informational→blocking promotion criteria, restated epic AGENTS.md Specification Alignment & Automated Structural Validation #642 success metrics + zero-token cost bound, cross-links to discussion 💡 AGENTS.md Specification Alignment & Automated Validation #534 and idea 💡 Cross-Repo Standards Drift Detection via Multi-Repo Analysis #341.
    • .github/workflows/agents-md-rules-tests.yml (new) — per-suite CI gate (copy-adapted from agent-rate-limits-tests.yml) so the contract test actually runs.

    Tests to Write

    • tests/test_agents_md_rules_config.bats (new) — contract tests mirroring test_agent_rate_limits_config.bats: file parses as JSON; required top-level keys exist; every rule tagged exactly required or recommended; the structurally-stable rules (single H1, valid heading hierarchy, resolvable cross-references) are required; section-presence rules stay recommended; scope is structural and semantic checks are listed out-of-scope; the spec snapshot records source + date; the promotion gate encodes 2 clean cycles + maintainer sign-off.

    Test Command

    bats --print-output-on-failure tests/test_agents_md_rules_config.bats (full lint gate: bash .dev-lead/scripts/dev-lead-lint.sh)

    Notes

    • Story Dev Notes said "no code changes"; per the org's mandatory TDD standard and the direct precedent ([Phase 2] standards/agent-rate-limits.json config + standard doc (single source of truth) #638 shipped its data file with a bats contract test + a per-suite CI workflow), this delivers the data file with its validating test so the "machine-readable rule set" is actually enforced. No linter logic is added — that remains Phase 2.
    • Referenced paths in the story were slightly stale: aw-standards-sync.sh lives at .dev-lead/scripts/, and consumer-manifest.json at .dev-lead/scripts/lib/. The new JSON goes in the main-repo scripts/lib/ per the story's target surface.
  2. don-petry commented on Sep 1, 2026

    @don-petry
    ContributorAuthor

    Dev-Lead: Implementation Complete

    Plan Execution

    Acceptance Criteria

    Test Results

    1..17
    ok 1 rule-set file exists
    ok 2 rule set parses as valid JSON
    ok 3 _schema_version is a positive integer
    ok 4 an inline _note documents the file is inert (no linter consumes it yet)
    ok 5 all required top-level keys exist
    ok 6 scope is 'structural' (AC #3)
    ok 7 out_of_scope is a non-empty array explicitly excluding semantic/content checks (AC #3)
    ok 8 spec_snapshot records a source and a date (AC #1 task 2)
    ok 9 rules is a non-empty array
    ok 10 every rule has a unique id, a description and an element
    ok 11 every rule is tagged exactly 'required' or 'recommended' (AC #2)
    ok 12 at least one required and at least one recommended rule exist (AC #2)
    ok 13 the three structurally-stable rules exist and are 'required' (Dev Notes)
    ok 14 org-repo import-consistency rule is present (AC #1 / epic scope)
    ok 15 contested section-presence rules stay 'recommended', never 'required' (Dev Notes)
    ok 16 promotion gate encodes two clean cycles and maintainer sign-off (AC #1 task 4)
    ok 17 promotion default_severity starts informational (non-blocking) (epic scope)
    

    Also passing: bash .dev-lead/scripts/dev-lead-lint.sh (shellcheck 31 files + CODEOWNERS), markdownlint-cli2 on the new doc (0 issues), jq -e . on the JSON, and workflow YAML parse. All relative links in the doc resolve to existing files.

    Files Changed

    • scripts/lib/agents-md-rules.json (new): the data-driven structural rule set the Phase-2 linter will read. Inert on merge — no consumer yet.
    • docs/initiatives/agents-md-validation.md (new): the reviewable source-of-truth reference for scope, spec snapshot, inherited metrics, and the promotion gate.
    • tests/test_agents_md_rules_config.bats (new): contract tests guarding the rule set (TDD, written before the JSON).
    • .github/workflows/agents-md-rules-tests.yml (new): runs the contract tests on changes to the rule set / test / workflow.

    Notes

    • Phase-2 TDD, not a doc-only exception. The story Dev Notes said "no code changes," but the org's mandatory TDD standard and the direct precedent ([Phase 2] standards/agent-rate-limits.json config + standard doc (single source of truth) #638 shipped its data file with a bats contract test + a per-suite CI workflow) mean the "machine-readable rule set" is delivered with its validating test so the contract is actually enforced. No linter/decision logic was added — that remains Phase 2.
    • Stale references in the story corrected: aw-standards-sync.sh lives at .dev-lead/scripts/ and consumer-manifest.json at .dev-lead/scripts/lib/; the story-referenced docs/initiatives/idea-to-initiative-pipeline.md does not exist, so the ADR docs already in docs/initiatives/ were used as the format model. The new JSON is placed at scripts/lib/agents-md-rules.json per the story's "Likely target surface."
    • Design constraint honored: rules live in the data file (not the linter), so the evolving AAIF/agents.md spec can be updated without code changes. Section-presence rules are kept recommended (contested split, epic AGENTS.md Specification Alignment & Automated Structural Validation #642 open question); only the structurally-stable rules are required.
    • No follow-up issues needed; Phases 2–4 are already tracked under epic AGENTS.md Specification Alignment & Automated Structural Validation #642.
  3. added a commit that references this issue on Sep 1, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions