Skip to content

chore: add shared agent guidance - #121

Merged
Benoît Cortier (CBenoit) merged 4 commits into
masterfrom
codex/agent-instructions-maintenance
Oct 27, 2026
Merged

Benoît Cortier (CBenoit) merged 4 commits into
masterfrom
codex/agent-instructions-maintenance

Conversation

@CBenoit

@CBenoit Benoît Cortier (CBenoit) commented Oct 27, 2026 •

Copy link
Copy Markdown
Member

Add concise repository policy and shared skills with scheduled synchronization.
Expose each skill through an individual Claude symlink so Claude can discover shared and repository-specific instructions.
Omit redundant opening titles and inherit the shared prevention rules while preserving useful section headings.

Add concise repository policy and shared skills with scheduled
synchronization.
Expose each skill through an individual Claude symlink so Claude can
discover the shared and repository-specific instructions.

Benoît Cortier (CBenoit) commented Oct 27, 2026 •

Copy link
Copy Markdown
Member Author

Validation: all 34 configured skill directories match Gateway's recursive file sets and SHA-256 hashes. All 1 AGENTS/CLAUDE pairs and 35 individual skill links resolve correctly; .claude/skills is a real directory. No local settings files remain.

All 1 changed repository-local skill passed Tessl and the skill-creator validator; 66 unique canonical skills passed both across the eight repositories. Independent review, exact title-only comparisons, frontmatter checks, and git diff --check pass. The rebased heading/instruction patches are unchanged by range-diff; the final two-file shared-test refresh was independently verified byte-for-byte against Gateway.

No application or intent files are changed by this PR. The sspi-rs and IronRDP branches now include their merged compile fixes through the updated base.

Lines changed: production code +0/−0; tests +0/−0; other files +2257/−0 across 91 files.

Intent naming consistency: all eight root AGENTS files cover shared parts, all eight intent-files skills match Gateway byte-for-byte, and the Gateway/IronVNC documentation copies are identical. Independent GPT-6.1 Sol High review and git diff --check passed; all 420 tracked symlinks remain symbolic links.

Note

Human-tuned, LLM-assisted content.

Benoît Cortier (CBenoit) commented Oct 27, 2026 •

Copy link
Copy Markdown
Member Author

Instruction change rationale — reviewed diff at 785076a01.

File / instruction block Addition, deletion, or replacement Rationale / where the guidance remains
AGENTS.md Use INTENT*.md and .intent.md in the intent-file rule. Includes the documented INTENT..md and .intent..md shared parts; ownership and read-before-edit obligations are unchanged.
1 AGENTS files Remove 1 opening repository/path/topic banners. Their scope or purpose is already clear from the location and retained body; these titles organize no distinct sections. The instructions themselves remain.
35 skill opening titles Remove opening titles that repeat skill names or frontmatter descriptions. The metadata already supplies the identity and purpose. Title-only edits preserve frontmatter, the remaining body, code blocks, and organizing headings.
Shared authoring/review rules Mirror the three prevention rules from Gateway unchanged. Keeps agents-md, agents-md-review, and skill-discipline aligned with the authoritative source rather than creating local variants.
Shared test guidance Refresh test-oracle-reviewer and test-pruner from latest Gateway master. Those upstream files changed while these PRs were being rebased. Exact copies restore source parity; their bodies were not independently customized or semantically re-audited.
AGENTS.md Add the /contribute entry point. Establish the shared contribution-flow selection policy without copying its workflow into always-loaded instructions.
AGENTS.md Add human-owned intent protection. Intent ownership is organization policy that cannot be inferred from code, including the requirement to stop on conflict. It protects future intent files even where none exist today.
AGENTS.md Add the rationale-not-history rule for permanent text. This is an organization writing policy that manifests, formatting tools, and source inspection cannot enforce.
AGENTS.md Add the UNTESTED comment and PR-placement requirements. Passing tests cannot establish an untested property. Requiring the property, its reason, and the future check preserves that maintenance obligation; PR-comment placement keeps process detail out of squash history.
AGENTS.md Add the protocols/README.md coupling pointer and the centralized protocol-test destination. Protocol changes require coordinated specification, Rust, and .NET updates; the dedicated suite is protocols/rust/now-proto-testsuite. These nonstandard cross-language/test-layout requirements are costly to discover after implementing at the wrong seam.
.github/skills-sync.yml Select 34 generic Gateway skills; omit Gateway product-specific workflows. The Rust repositories need contribution, intent/contract, writing, review, dependency, test, and instruction-maintenance workflows. Installer, Gateway runtime, and release-ticket workflows would be inappropriate here.
.agents/skills Add the configured skill directories and their references unchanged. Reusing the already-audited upstream text supplies the workflows without maintaining divergent local rewrites. References and scripts are part of the skill, not optional duplicate documentation; Gateway skill semantics were not re-audited.
.github/workflows/sync-skills.yml Add the existing scheduled/manual sync workflow and companion action. Initial copies alone would go stale. The IronVNC workflow/action provides the established update mechanism for the explicit skill list.
.github/skills/code-review/SKILL.md Add a small local review dispatcher. The imported contribute/lead workflows call code-review, which Gateway does not supply as a shared skill. This file connects them to the installed focused reviewers, invokes oracle review through test-reviewer once, and runs skeptical-reviewer last.
CLAUDE.md Add a sibling symlink to AGENTS.md. Claude reads CLAUDE.md. A symlink exposes exactly the same instructions without a second policy file that can drift.
.claude/skills Add a real directory containing 35 individual skill symlinks. Claude does not discover a symlink of the entire skills folder. Per-skill links expose the 34 shared skills plus local code-review while retaining one copy of each.

Human-owned intent files and application code are unchanged.

Shared heading and prevention-rule changes originate in Gateway #2163.
Merge that source PR first so scheduled skill synchronization preserves the cleanup.

Note

Human-tuned, LLM-assisted content.

Remove opening banners that repeat skill metadata or repository context.
Synchronize the shared authoring and review rules that prevent redundant
titles while retaining headings that organize instructions or add context.
Keep test-oracle review and pruning rules aligned with the shared
Gateway definitions.
@CBenoit
Benoît Cortier (CBenoit) merged commit a955763 into master Oct 27, 2026
9 checks passed
@CBenoit
Benoît Cortier (CBenoit) deleted the codex/agent-instructions-maintenance branch October 27, 2026 14:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

3 participants