Sync instruction files with tooling reality; fix strategy-doc drift - #8
Merged
Merged
Conversation
Summary: - AGENTS.md Validation said "no linter yet" though markdownlint, check.sh, and the doc-quality CI all exist; now points at ./scripts/check.sh and CI. - AGENTS.md / CLAUDE.md / Copilot mirror all claimed "no test runner" while CLAUDE.md documents a four-tier check suite; reworded all three consistently. - Strategy doc said "@AGENTS.md import" in three places, contradicting the recorded link-not-import decision in AGENTS.md; reconciled and noted the trade-off. - Moved "Single source, multi-host" next to "Layered instructions" (same theme); added BOOTSTRAP.md and docs/knowledge/ to the strategy references and layer table. - README dropped the stale "12 sources" count and gained highlight groups for the SPDD/Fowler and cc-connect sources. - Added lychee.toml excluding the <your-username> placeholder so the weekly online link check stops short of filing false-positive issues; CLAUDE.md and AGENTS.md note the file. - check.sh gained the informational staged-diff secrets scan CLAUDE.md's Tier 1 describes; CLAUDE.md now marks the secrets grep informational (rule files legitimately contain the word "secret"). Changed files: - AGENTS.md: Validation + Dev environment tips + File-by-file (lychee.toml). - CLAUDE.md: purpose line, markdownlint framing, lychee.toml framing, Tier-1 interpretation note. - .github/copilot-instructions.md: build/test bullet mirror. - docs/ai-agent-coding-strategy.md: three @AGENTS.md fixes, section move, references. - README.md: source-count fix + new highlight groups. - scripts/check.sh: informational secrets scan. - lychee.toml: new. Validation: - ./scripts/check.sh clean (tier 1 structural + tier 2 markdownlint, 0 errors; tiers 3-4 verified in CI). - Azure triple-mirror (CLAUDE.md / azure-ai.instructions.md / knowledge note) spot-checked in sync; no edits needed. Follow-ups: - Stale remote branches from merged PRs could be pruned (needs explicit authorization). https://claude.ai/code/session_01AmmEaVLpyeJz7TZ3iyXtWK
tomqwu
marked this pull request as ready for review
June 10, 2026 15:34
tomqwu
added a commit
that referenced
this pull request
Jun 10, 2026
Codifies the operating policy this session has been running under: builder agents may merge after the review gate passes (CI green + LGTM marker matching head SHA + no newer blocking feedback), replacing the previous "do not merge unless the user explicitly asks" rule. - AGENTS.md: adds the builder and reviewer prompt snippets, with explicit head-SHA tying. - CLAUDE.md: same builder/reviewer split with a pointer to the knowledge note for scheduler, lock, and state guardrails. - .github/copilot-instructions.md: mirrors the head-SHA approval gate for the Copilot baseline. - docs/knowledge/agentic-pr-review-loop.md: updates the prompts, the validation checklist, and the "let the builder bypass review" framing. Rebased onto current main (post #7 and #8); doc-quality CI passes on the rebased head.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Full repo review after the quality-gate work (PRs #4–#5) and the research merges (#7). The instruction files had drifted behind the tooling they now sit on top of. Fixes, smallest-change-first:
Stale claims about tooling (3 files, mirrored consistently)
AGENTS.md§Validation said "linter configured (none yet — add one if it lands)" —.markdownlint.json,scripts/check.sh, and thedoc-qualityworkflow all exist. Now: run./scripts/check.sh; CI runs the same tiers.AGENTS.md,CLAUDE.md, and.github/copilot-instructions.mdall claimed "no test runner" while CLAUDE.md itself documents the four-tier check suite with branch protection. Reworded all three the same way: no build, no package manager; the doc-quality checks are the test suite.Strategy-doc contradiction
docs/ai-agent-coding-strategy.mdsaid "@AGENTS.mdimport" in three places, contradicting the decision recorded inAGENTS.md§File-by-file (markdown link, not import, to keep the baseline out of always-loaded context). Reconciled, with the trade-off stated once.BOOTSTRAP.mdanddocs/knowledge/.Latent CI noise
lychee.tomlexcluding the<your-username>placeholder inBOOTSTRAP.md— without it, the weekly online link check would file false-positive "Link Checker Report" issues. CLAUDE.md anticipated this file; now it exists.Local runner gap
scripts/check.shgained the staged-diff secrets scan CLAUDE.md's Tier 1 describes — informational, not a hard fail, because rule files legitimately contain words like "secret". CLAUDE.md's interpretation note updated to match.README
Reviewed, no change needed: Azure triple-mirror (CLAUDE.md ↔ azure-ai.instructions.md ↔ knowledge note) in sync; Boundaries sections present everywhere; knowledge notes consistent with the knowledge README structure; BOOTSTRAP.md install paths match the file tree. PR #6's closed-unmerged decision (PR-gate prompts kept out of instruction files) respected — nothing resurrected.
Test plan
./scripts/check.shclean locally (tier 1 structural, tier 2 markdownlint 0 errors).doc-qualityCI jobs green (tiers 3–4 verified here).lychee --offlinepasses with the newlychee.tomlpresent.@AGENTS.md— remaining mentions only describe the import option, none state it as this repo's mechanism.Follow-ups
claude/research-repo-patterns-IvR3z,claude/research-three-more-repos,claude/readme-research-sources-link,docs/agentic-pr-review-loop,claude/research-spdd-and-cc-connect) plus closed-unmergeddocs/pr-review-gate-templatescould be pruned — branch deletion needs explicit authorization per AGENTS.md §Safety.https://claude.ai/code/session_01AmmEaVLpyeJz7TZ3iyXtWK
Generated by Claude Code