Repository navigation
docs(agents): split AGENTS.md core rules from on-demand pi-rules instructions - #339
Merged
Merged
Conversation
added 4 commits
September 3, 2026 06:54
Slim the always-loaded AGENTS.md from 48.7 KB (~12k tokens per session) to ~12 KB by moving long-form rationale and reference material into glob-scoped instruction files under backend/.github/instructions/ (loaded on demand by pi-rules / GitHub Copilot instructions). What stays in AGENTS.md (normative core, always loaded): - hard rules as one-liners with enforcement pointers and exception syntax (CQRS boundary, no-panics, no string-interpolated SQL, AUTHZ-GATE, ADR-031 error surface, reliability lessons) - handoff/task-spec review checklist (unchanged) - kameo_es code example, licensing, UUIDv7 rule What moved (verbatim, verified line-by-line): - hard-rule long forms -> architecture-hard-rules.instructions.md - domain model digest -> domain-model.instructions.md - photo bounded context + env -> photo-context.instructions.md - AI import runtime/GC/recovery -> ai-import.instructions.md - integration-test docs/gotchas -> integration-tests.instructions.md - local dev runtime/OIDC -> local-dev-runtime.instructions.md - CI guardrail job detail -> ci-hardening.instructions.md Section numbering and titles (§1-§5, §7) are kept stable because source-code comments and CI workflows reference them. A new §6 reference register documents the instruction files and their glob scopes. Rule bodies stay under the pi-rules 12k-char per-rule cap; glob matching was validated against the extension's picomatch semantics (project root = backend/). Co-authored-by: glm-5.3 (neuralwatt)
…ions pi-rules discovers project rule directories from the directory it walks up from the pi session cwd to the project root. Sessions launched from the monorepo root therefore only see `.github/instructions/` at the repo root, not `backend/.github/instructions/` — move the seven rule files accordingly (also the correct location for GitHub Copilot instruction files). Glob patterns are now repo-root-relative (`backend/crates/**/...`, `.github/workflows/**`, ...), and the local-dev rule additionally matches the root-level `scripts/**` (seed-logto-dev.sh) and root `.env*`. ci-hardening now anchors workflow/dependabot globs at the repo root and covers `backend/rules/**`/`backend/rules-tests/**`. backend/AGENTS.md pointers now reference `../.github/instructions/` and the §6 register documents the repo-root location plus the dynamic-only nature of glob rules (/rules lists always-on rules only). Glob matching re-validated against the extension's picomatch semantics. Caveat documented in AGENTS.md §6: sessions launched from `backend/` (project root = backend/ due to the Cargo.toml marker) do not discover the root instructions — launch pi from the repo root for full rule coverage. Co-authored-by: glm-5.3 (neuralwatt)
Root-launched pi sessions did not load any AGENTS.md (pi loads context files only from the session cwd and its parents, never from subdirectories), so backend core rules were invisible when launching from the repo root. Add a minimal root AGENTS.md that: - dispatches to the area files before code is generated: backend/AGENTS.md (slimmed core + on-demand instructions via .github/instructions/) and frontend-flutter/AGENTS.md (explicitly marked as not yet reworked / comprehensive long-form, candidate for the same core/instructions split), including the pi-context boundary (a backend session does not auto-load the Flutter file and vice versa); - carries the cross-cutting rules (AGPL-3.0 + SPDX/Co-authored-by tooling, openapi.yaml as wire-contract artifact, gitleaks, workflow hardening applied to every workflow); - points to the pi-rules instruction register and documents the repo-root launch requirement plus the static/dynamic /rules distinction. At 2.7 KB it stays small on purpose: it is the only file loaded in every session of the monorepo (root, backend and frontend cwd alike). Co-authored-by: glm-5.3 (neuralwatt)
pi-rules resolves the project root per read file via the first project marker walking up (per-crate Cargo.toml in a workspace), so: - backend-scoped rules live in backend/.github/instructions/ with backend-relative globs (crates/**/*.rs, rules/**, docker-compose*, scripts/**, .env*, dev-certs/**) — they fire for backend reads from any session launch directory; - repo-level rules stay in the monorepo root .github/instructions/ (workflow-hardening for .github/workflows/** + dependabot, and local-dev-root as pointer rule for root scripts/ and .env*); - ci-hardening was split accordingly: workflow hardening (SHA-pinning, script-injection hygiene) at the root, ast-grep guardrail rule detail at the backend level (rules/**, rules-tests/**, scripts/**). backend/AGENTS.md pointers and the §6 register document the per-target project-root semantics; the root AGENTS.md §3 explains the two-level layout and recommends backend/ launches for backend-heavy sessions. Verified empirically (headless pi from the repo root): reading backend/crates/core/src/lib.rs now injects architecture-hard-rules, domain-model and backend/AGENTS.md (once per session, not per file); reading backend/crates/infra/src/photo/sagas/mod.rs additionally injects photo-context; reading backend/rules/cqrs-boundary.yml injects only ci-hardening. Co-authored-by: glm-5.3 (neuralwatt)
|
Important
This repository does not receive automatic reviews because it has fewer than 10 stars. ⚙️ Run configurationConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Team Run ID: Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
The add-spdx-headers.sh tooling covers .rs/.typ/.dart/.sh/.feature/.ya?ml but not .md, so the nine new instruction files shipped without license headers in the previous commits. Add the standard AGPL-3.0 header block (HTML comments, per the AGENTS.md convention) directly after the YAML frontmatter so the pi-rules parser still recognizes the frontmatter at file start — a header before it would degrade the rule to plain body text and stop it from ever matching. Verified live: the rules still inject on matching reads and the license header travels with the injected body. Co-authored-by: glm-5.3 (neuralwatt)
3 tasks done
Owner
Author
|
@coderabbitai approve |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
✅ Action performedComments resolved and changes approved. |
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
Splits the always-loaded
backend/AGENTS.md(48.7 KB, ~12k tokens injected into every session) into a ~12 KB normative core file plus nine glob-scoped on-demand rule files, loaded bypi-rules/ GitHub-Copilot-style instructions when matching files are read.Problem
backend/AGENTS.mdcarried both the normative core rules and large reference material (local dev runtime, AI import tables, integration-test troubleshooting, guardrail job details, domain-model digest). Everything was paid for in every session's context — even for trivial questions — and the descriptive content was also the primary drift hazard (it paraphrases state that lives in code, ADRs and specs).Solution
Split along the two content types: normative (invariants, hard rules, workflow contract) stays in
AGENTS.mdas one-liners with enforcement pointers and exception syntax; descriptive long-form material moves into instruction files whose globs scope them to matching file reads.backend/AGENTS.md(48.7 KB → ~12 KB): core rules only (CQRS boundary, no-panics, no string-interpolated SQL, AUTHZ-GATE, ADR-031 error surface, reliability lessons, handoff/task-spec checklist, kameo_es example, licensing). Section numbering and titles unchanged (§1–§5, §7 — referenced by CI workflows and source comments). New §6 reference register documents the instruction files, their glob scopes and the discovery semantics.backend/.github/instructions/(backend-relative globs, fire forbackend/**reads from any session cwd):architecture-hard-rules(long-form rationale of the hard rules),domain-model(hierarchy/aggregate invariants),photo-context,ai-import,integration-tests,local-dev-runtime,ci-hardening(ast-grep rule/job detail)..github/instructions/(repo-level globs):workflow-hardening(SHA-pinning, Dependabot, script-injection hygiene for.github/workflows/**) andlocal-dev-root(pointer rule for rootscripts/**/.env*).AGENTS.md(2.7 KB area dispatcher): monorepo-level dispatch table tobackend/AGENTS.md(slimmed) andfrontend-flutter/AGENTS.md(explicitly marked not-yet-reworked), cross-cutting rules (license/SPDX tooling,backend/openapi.yamlwire-contract artifact, gitleaks, workflow hardening), and the pi context-loading semantics explanation.Content integrity
Every moved passage was verified line-exact against the previous file (only intentionally compressed §1/§3/§4 bullet headers and renamed headings differ), so no rule or reference material is lost. Hard rules in particular remain fully intact in
AGENTS.mdso they stay visible even without any rule-loading extension.Enforcement note (pi-rules monorepo support)
pi-rulesresolves the project root per read file (innermost project marker), which in this Cargo workspace stops the walk at the member crate — workspace-level instructions never fired forcrates/**reads. That upstream limitation is fixed by code-yeongyu/pi-rules#31; until it is merged and installed, the backend-level instructions fire only for files directly underbackend/(scripts, rules, compose, env) and the root-level rules for repo-level files.Testing
git diff main...HEAD --statconfirms only.mdfiles).crates/**/*.rsrules do not matchCargo.toml, workflow rules do not match crate files).backend/crates/core/src/lib.rsinjects architecture-hard-rules + domain-model +backend/AGENTS.md(once per session); readingbackend/crates/infra/src/photo/sagas/mod.rsadds photo-context; readingbackend/rules/cqrs-boundary.ymlinjects only ci-hardening; repo-rootAGENTS.mdis natively deduplicated.Follow-ups
frontend-flutter/AGENTS.md(documented as candidate in the root dispatcher).Co-authored-by: glm-5.3 (neuralwatt)