Repository navigation
Closed
Labels
Description
Story
As a repo maintainer,
I want run the structural linter against this repo's own canonical AGENTS.md on pull requests,
so that structural regressions to the source-of-truth AGENTS.md are caught at PR time before they propagate downstream.
Acceptance Criteria
- lint.yml runs scripts/agents-md-lint.sh against the repo's AGENTS.md on pull_request in informational mode (annotates but does not fail the build in this phase).
- The check emits GitHub ::warning:: annotations for each structural finding.
- No new required status check is added while the check is informational; promotion to a blocking/required check is deferred to Phase 4.
- The change is limited to workflow wiring; shellcheck stays clean and the workflow remains valid YAML.
Tasks / Subtasks
- Add a job/step in lint.yml that runs the linter against AGENTS.md in informational mode on pull_request (AC: Addressing PR comments #1)
- Emit ::warning:: annotations for findings (reuse the run-bats.sh annotation convention) (AC: Add multi-agent isolation strategy using git worktrees #2)
- Ensure no branch-protection required-check is introduced yet, and document that in the workflow header (AC: Add coding standards & principles section to AGENTS.md #3)
- Verify workflow YAML validity and shellcheck cleanliness (AC: Add workflow, environment, and orchestration guidance #4)
Dev Notes
- lint.yml already has shellcheck and bats jobs on pull_request; add a lightweight informational job/step that invokes the linter — do not make it a required check (that is Phase 4).
- run-bats.sh demonstrates the ::warning:: annotation convention used in this repo for non-fatal signals; mirror it so findings surface without failing the build.
- The linter's informational default mode (from Story 2) is what keeps this non-blocking; do not pass the failing-mode flag here.
- This validates only THIS repo's AGENTS.md; org-wide validation is the audit integration (Story 3).
Project Structure Notes
Edit .github/workflows/lint.yml only. Any repo-specific-workflow exception should be noted per the AGENTS.md convention for documented repo-specific additions.
References
- .github/workflows/lint.yml
- scripts/run-bats.sh
- AGENTS.md
Likely target surface
.github/workflows/lint.yml
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: #646 — [Phase 3] Add local canonical-AGENTS.md self-validation to CI (informational)
Scope
Wire the existing
scripts/agents-md-lint.shstructural linter into CI so this repo's own canonicalAGENTS.mdis validated in informational mode on every pull request, surfacing each structural finding as a GitHub::warning::annotation without failing the build.Reconciliation note (repo reality vs. story references)
The story references
.github/workflows/lint.ymlandscripts/run-bats.sh, neither of which exists in this repo. The actual equivalents are:.github/workflows/ci.yml— the repo's canonical PR lint/test workflow (jobs:Lint,ShellCheck,Agent Security Scan,Secret scan); runs on everypull_requesttomain(not path-filtered), so it is the correct home for a self-check that must catch AGENTS.md regressions on any PR..dev-lead/scripts/run-bats.sh— the::warning::annotation convention referenced by the story.The pre-existing
agents-md-rules-tests.ymlis path-filtered to the linter's own files, so it would not run on a PR that only editsAGENTS.md— hence it is unsuitable andci.ymlis used instead.Implementation Checklist
agents-md-selfcheckjob to.github/workflows/ci.ymlthat runsscripts/agents-md-lint.sh AGENTS.mdin default (informational) mode and emits::warning::annotations per finding (AC Addressing PR comments #1, Add multi-agent isolation strategy using git worktrees #2)--mode failing(keeps it non-blocking) (AC Add coding standards & principles section to AGENTS.md #3)Tests to Write
test/workflows/ci/agents-md-selfcheck.bats— assert the job exists, targetsAGENTS.md, runs the linter in informational mode (no--mode failing), and emits::warning::annotations (mirrors the existingsecret-scan-config.batsstatic-wiring test pattern; auto-run byci-tests.ymlovertest/workflows/ci/)Test Command
bats --print-output-on-failure test/workflows/ci/(plusshellcheckvia.dev-lead/scripts/dev-lead-lint.shandbash scripts/agents-md-lint.sh AGENTS.mdsanity run)don-petry commentedon Sep 1, 2026
Dev-Lead: Implementation Complete
Plan Execution
agents-md-selfcheckjob to.github/workflows/ci.ymlthat runsscripts/agents-md-lint.sh AGENTS.mdin default (informational) mode on every PR (AC Addressing PR comments #1)::warning::annotations (file/line-scoped), mirroringrun-bats.sh's non-fatal-signal convention (AC Add multi-agent isolation strategy using git worktrees #2)--mode failing; workflow stays valid YAML and shellcheck-clean (AC Add workflow, environment, and orchestration guidance #4)test/workflows/ci/agents-md-selfcheck.bats(auto-run byci-tests.yml)Reconciliation note
The story referenced
.github/workflows/lint.ymlandscripts/run-bats.sh, neither of which exists in this repo. The wiring was placed in the repo's actual canonical PR lint/test workflow.github/workflows/ci.yml(which already runs shellcheck + other lint jobs on everypull_requesttomain, so it catches AGENTS.md regressions on any PR). The pre-existingagents-md-rules-tests.ymlis path-filtered to the linter's own files and would not fire on an AGENTS.md-only PR, so it was unsuitable. The::warning::convention is mirrored from.dev-lead/scripts/run-bats.sh.Test Results
Additional verification:
bash .dev-lead/scripts/dev-lead-lint.sh→ all checks passed (shellcheck on 34 files + CODEOWNERS)yamllint(CI config) onci.yml→ cleanactionlint1.7.7 (runs shellcheck on therun:block) onci.yml→ cleanbash -eo pipefail: exits 0 against the clean repo AGENTS.md (no annotations) and against a fixture with arequired-level finding (annotations emitted, still exit 0) — confirming the check is non-blocking.tests/agents_md_lint.bats+tests/test_agents_md_rules_config.bats→ 40/40 pass (unaffected).Files Changed
.github/workflows/ci.yml: new informationalagents-md-selfcheckjob (+ header documenting the Phase-4-deferred, non-required status).test/workflows/ci/agents-md-selfcheck.bats: static-wiring regression test (job present, targets AGENTS.md, informational — no--mode failing, emits::warning::, documents Phase 4 deferral).Notes
AGENTS.mdwere ever deleted, the linter returns exit 2 and the (non-required) job would go red — intentional fail-loud behavior that cannot block merge.feat: implement issue #646 — [Phase 3] Add local canonical-AGENTS.md …