docs(agents): document <PROJECT> vs <project>, and catch spaced variants - #1154
Merged
Merged
Conversation
Two gaps that surfaced while reviewing apache#1144. `<PROJECT>` (display name, 84 uses) and `<project>` (infrastructure slug, 313 uses) are both load-bearing across skills, tool docs, the ASF organization manifest, and PRINCIPLES.md — but neither appeared in the placeholder table in AGENTS.md, which closes with "do not invent new placeholders". Answering "is `<project>` an invented placeholder?" required a repo-wide grep rather than a table lookup. Both now have a row, plus a note stating the difference explicitly: they hold two different values, not one value in two casings. Substituting one where the other belongs yields something wrong rather than mis-cased — `Apache Foo.apache.org` is not a hostname. The same case-only difference is a linter hazard. `FORBIDDEN_PATTERNS` is matched with `grep -F`, so the `name:"airflow"` entry added in apache#1144 only caught the no-space spelling; GraphQL, YAML and JSON all accept `name: "airflow"` equally, and that form passed every pattern in the list. Rather than add a second fixed string per spacing, patterns whose surrounding syntax admits optional whitespace move to a new `FORBIDDEN_REGEXES` array matched with `grep -E`; the two arrays share one match-reporting path. Fixed strings stay the default — they are easier to read and cannot misfire on regex metacharacters. Verified: `check-placeholders.sh` is clean on the current tree, and flags both `name:"airflow"` and `name: "airflow"` when either is planted in `skills/`. `prek run` passes on both changed files, including `lychee` and `doctoc`. Generated-by: Claude Code (Opus 5)
4 tasks
potiuk
added a commit
that referenced
this pull request
Sep 8, 2026
The marker sat at a1cff44, 17 commits behind main. Bumping it alone would claim those commits are described by the specs, so the drift is closed first. Specs updated for what actually shipped: - meta-and-quality-tooling: skill-evals errors, rather than passing, when a case's CLI produced no gradeable output (#1161). - security-reporting: the tracker dashboard projects the current partial bucket to its end-of-bucket value, splitting RATE series (accumulate from zero) from LEVEL series (carry over), and deliberately not projecting mean-based signals (#1158). - project-agnosticism: <PROJECT> and <project> are two placeholders holding different values, and the lint carries both spellings plus spaced variants (#1154). - adapters: the forwarder relay's contact_handle defaults to an org-level shared inbox rather than a named individual (#1135). The multi-hop coordinator case is designed in RFC-AI-0008 and unimplemented. - issue-management-family: the family's eval suites, and the note that --cli runs belong outside a credential-denying sandbox (#1145). Commits needing no spec change: #1152, #1143 and #1156 updated their own specs in-commit; #1149, #1147, #1151 are behaviour-preserving bug fixes; #1155 and #1141 are CI and dependency chores; #1159's spec edits landed with it; #1144 removes hardcoded literals that no spec asserted. One genuine gap recorded rather than papered over: no spec covers marketplace distribution or the dev-version stamping rule from #1160, which is load-bearing because `claude plugin update` compares version strings, not commit SHAs. Logged in adoption-and-setup as wanting its own spec. Generated-by: Claude Code (Opus 5)
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
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
<PROJECT>(display name, 84 uses) and<project>(infrastructure slug, 313 uses) are both load-bearing — across skills, tool docs,organizations/ASF/organization.mdandPRINCIPLES.md— yet neither had a row in the placeholder table inAGENTS.md, which closes with "do not invent new placeholders". Answering "is<project>an invented placeholder?" needed a repo-wide grep instead of a table lookup. Both now have a row, plus a note stating the difference explicitly: two placeholders holding two different values, not one value in two casings. Substituting one where the other belongs produces something wrong rather than mis-cased —Apache Foo.apache.orgis not a hostname.FORBIDDEN_PATTERNSis matched withgrep -F, so thename:"airflow"entry added in fix(skills): derive the two remaining Airflow literals from project config #1144 only caught the no-space spelling — GraphQL, YAML and JSON all acceptname: "airflow"equally, and that form passed every pattern in the list. Patterns whose surrounding syntax admits optional whitespace now live in a newFORBIDDEN_REGEXESarray matched withgrep -E; the two arrays share one match-reporting path. Fixed strings stay the default — easier to read, and they cannot misfire on regex metacharacters.Both gaps surfaced while reviewing #1144; this is the follow-up that PR's review nit pointed at.
Type of change
prek, workflows, validators)Test plan
prek runpasses on both changed files — includinglychee(the new link totools/dev/check-placeholders.shresolves) anddoctoc(no headings changed, so the TOC is untouched).tools/dev/check-placeholders.shexits 0.repository(owner: "apache", name: "airflow")inskills/is now caught — it was not caught before this change.repository(owner:"apache",name:"airflow")is still caught, so thegrep -F→grep -Emove loses no coverage.bash -n tools/dev/check-placeholders.shclean.SKILL.mdor step prompt material changes, so perAGENTS.md§ When the rule fires this is the prose/tooling row that needs no fixture rerun.RFC-AI-0004 compliance
Linked issues
Follow-up to #1144.