Skip to content

chore(agents): align instructions and skills - #586

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

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

Conversation

@CBenoit

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

Copy link
Copy Markdown
Member

Keep repository guidance accurate and concise, refresh shared skills from Gateway, and expose every skill through an individual Claude symlink.
Omit redundant opening titles and synchronize the authoring and review rules that prevent them.
Remove redundant skill-discovery and synchronization boilerplate from the root instructions.

Keep repository guidance accurate and concise, refresh shared skills
from Gateway, and expose every skill through an individual Claude symlink.
Remove redundant skill-discovery and synchronization boilerplate from
the root 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 5 AGENTS/CLAUDE pairs and 37 individual skill links resolve correctly; .claude/skills is a real directory. No local settings files remain.

All 3 changed repository-local skills 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.

The intent-review trigger retains the original broad filename patterns so shared intent parts are included. This correction passed an independent GPT-6.1 Sol High review, Tessl lint, the skill-creator validator, and git diff --check.

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 +90/−179 across 84 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 308c4d147.

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.
5 AGENTS files Remove 5 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.
37 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 Delete the two skills-discovery / weekly-sync openers. Explicit maintainer request: discovery/configuration already supplies these facts, so they need not be loaded on every task.
AGENTS.md Delete the RSA UNTESTED example. The preceding rule already requires the property, rationale, future check, and PR-comment placement. The example adds no requirement; those four obligations remain.
ffi/src/AGENTS.md Delete lengthy Drop examples and condense the repeated lifetime explanation. ffi/src/INTENT.md already owns the destructor/finalizer invariant. The short file retains the borrowing Drop ban, the non-obvious Ref destructor case, owning-secret cleanup, and manually_disposable policy.
picky-crypto/AGENTS.md Delete the native-provider capability and operation-derivability paragraphs. The Design principle and Minimality sections of picky-crypto/INTENT.md already impose them, including unsupported results and exceptions. Pinned evidence, Unknown reporting, and link requirements remain because they are separate review procedures.
.agents/skills/commit-scope/SKILL.md Delete four examples and the separate changelog-footer section. The examples merely repeat the scope-selection rules. Footer-parser behavior is directly available in cliff.toml and is a separate job from scope selection; canonical scopes and dependency/test ownership rules remain unchanged.
.agents/skills/spec-reviewer/SKILL.md Delete the extra “focus on standards conformance” sentence. The applicability test and conformance-only reporting rules already establish that focus. Source selection, checklists, normative distinctions, and citation requirements remain.
.github/skills/code-review/SKILL.md Remove the generic evidence admonition; retain the original intent-file patterns. The retained normalization and independent skeptical pass already specify how to verify evidence. INTENT*.md and .intent.md include the documented shared part files, INTENT..md and .intent..md; narrowing them would miss applicable intent.
.agents/skills/test-pruner/SKILL.md Refresh test-pruner and its three references from Gateway. Restore the configured mirror to the audited upstream version; no local semantic changes or new audit of Gateway text.
ffi/src/CLAUDE.md Add the missing sibling symlink to AGENTS.md. Claude reads CLAUDE.md; using a link makes the existing FFI guidance available without introducing a second copy.
.claude/skills Replace the whole-directory symlink with 37 individual skill symlinks. Claude does not discover the whole-folder link. Individual links include the local .github code-review skill as well as .agents skills.

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 8adc0df into master Oct 27, 2026
20 checks passed
@CBenoit
Benoît Cortier (CBenoit) deleted the codex/agent-instructions-maintenance branch October 27, 2026 15:20
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.

1 participant