Repository navigation
Closed
Labels
Description
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
- 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.
- 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.
- The rule set explicitly scopes OUT semantic/content checks; only structural elements are covered, matching the discussion's adversarial rebuttal.
- 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
- Draft docs/initiatives/agents-md-validation.md capturing scope, the stable structural elements, and the promotion gate (AC: Addressing PR comments #1, Add workflow, environment, and orchestration guidance #4)
- Capture the AAIF/agents.md spec snapshot used to derive the stable rule subset (record source + date in the doc) (AC: Addressing PR comments #1, Add coding standards & principles section to AGENTS.md #3)
- Create the machine-readable rule-set data file enumerating checks, each tagged required vs recommended (AC: Add multi-agent isolation strategy using git worktrees #2, Add coding standards & principles section to AGENTS.md #3)
- Document the informational-to-blocking promotion criteria (2 clean cycles + maintainer sign-off) (AC: Addressing PR comments #1)
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
don-petry commentedon Sep 1, 2026
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
requiredvsrecommended— 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 taggedrequired/recommended;scope: structural; explicitout_of_scopesemantic 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 fromagent-rate-limits-tests.yml) so the contract test actually runs.Tests to Write
tests/test_agents_md_rules_config.bats(new) — contract tests mirroringtest_agent_rate_limits_config.bats: file parses as JSON; required top-level keys exist; every rule tagged exactlyrequiredorrecommended; the structurally-stable rules (single H1, valid heading hierarchy, resolvable cross-references) arerequired; section-presence rules stayrecommended;scopeis 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
aw-standards-sync.shlives at.dev-lead/scripts/, andconsumer-manifest.jsonat.dev-lead/scripts/lib/. The new JSON goes in the main-reposcripts/lib/per the story's target surface.don-petry commentedon Sep 1, 2026
Dev-Lead: Implementation Complete
Plan Execution
scripts/lib/agents-md-rules.json— machine-readable structural rule set (8 rules, each taggedrequired/recommended;scope: structural; explicitout_of_scopesemantic exclusions;spec_snapshotsource+date;promotiongate).docs/initiatives/agents-md-validation.md— reference doc: scope, stable structural elements, out-of-scope semantics, spec snapshot, restated epic AGENTS.md Specification Alignment & Automated Structural Validation #642 metrics + zero-token cost bound, promotion criteria, cross-links to discussion 💡 AGENTS.md Specification Alignment & Automated Validation #534 and idea 💡 Cross-Repo Standards Drift Detection via Multi-Repo Analysis #341.tests/test_agents_md_rules_config.bats— 17 contract tests (written first, red → green)..github/workflows/agents-md-rules-tests.yml— per-suite CI gate (copy-adapted fromagent-rate-limits-tests.yml, same pinned checkout SHA).Acceptance Criteria
scripts/lib/; every rule taggedrequiredorrecommended; recommended reported-but-never-failing. ✅scope: structuralwith an explicitout_of_scopelist excluding semantic/content checks (matches discussion 💡 AGENTS.md Specification Alignment & Automated Validation #534's adversarial rebuttal). ✅Test Results
Also passing:
bash .dev-lead/scripts/dev-lead-lint.sh(shellcheck 31 files + CODEOWNERS),markdownlint-cli2on 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
aw-standards-sync.shlives at.dev-lead/scripts/andconsumer-manifest.jsonat.dev-lead/scripts/lib/; the story-referenceddocs/initiatives/idea-to-initiative-pipeline.mddoes not exist, so the ADR docs already indocs/initiatives/were used as the format model. The new JSON is placed atscripts/lib/agents-md-rules.jsonper the story's "Likely target surface."recommended(contested split, epic AGENTS.md Specification Alignment & Automated Structural Validation #642 open question); only the structurally-stable rules arerequired.feat: implement issue #643 — [Phase 1] Define the AGENTS.md structura…