Skip to content

docs: reconcile instruction files that disagreed with each other - #188

Merged
kyle-sexton merged 2 commits into
mainfrom
docs/reconcile-instruction-conflicts
Nov 14, 2026
Merged

kyle-sexton merged 2 commits into
mainfrom
docs/reconcile-instruction-conflicts

Conversation

@kyle-sexton

Copy link
Copy Markdown
Member

No related issue: findings from a prompt audit of this repository's instruction files, fixed in the same session.

Summary

Five places where instruction files disagreed with each other or with the repository's own standards. Documentation and one skill sentence; no behavior of the validator or scripts changes.

  • User goal and vertical slice: an agent reading AGENTS.md, the playbook, the cheat sheet or migrate-plugin gets one answer per question.
  • Native surfaces selected: AGENTS.md, repository docs, one SKILL.md. No new mechanism.
  • Ports and adapters introduced: none.
  • Defaults, configuration, and fallbacks: migrate-plugin step 2 now applies the repository preflight only when the active repository has the named files; otherwise it falls back to the official-documentation fetch in the same step.
  • Context inputs and precedence: unchanged.
  • Migration dispositions: not a migration.

Fix

  1. AGENTS.md preflight: "Read only the sections relevant" contradicted "read all of" two docs. It now scopes the live upstream pages, matching docs/official-docs.md ("Read the smallest complete set").
  2. docs/codex-capability-cheat-sheet.md: the guide claim said only "@plugin-creator as a built-in in ChatGPT"; the copies added in fix(plugin-ops): stop citing the removed $plugin-creator skill #114 were fuller. Brought up to the guide's current wording.
  3. AGENTS.md and docs/migration-playbook.md: the $plugin-creator removal was restated as a version history note (docs/standards/reference-dont-duplicate.md, "History lives in version control"). Both now state the current rule and link the cheat sheet, which holds the version, date and recheck trigger. README.md and the two skills keep their copies: onboarding prose may restate, and an installed skill cannot link repository docs.
  4. AGENTS.md validation: listed five behavioral cases where the release gates list seven. It now cites the release gates and the playbook matrix.
  5. plugins/plugin-ops/skills/migrate-plugin/SKILL.md: "In this marketplace" is not something an installed copy can detect. Now "When the active repository has them". plugin-ops 0.2.4 to 0.2.5.

Verification

  • npm test: 202 pass, 0 fail, 0 skipped.
  • npm run validate: PASS, 0 errors, 0 warnings.
  • lychee --offline on the three edited docs: 0 errors (the two new anchors resolve).
  • Live page consulted 2026-11-14: https://developers.openai.com/plugins/build/plugins. It names @plugin-creator in Work mode in ChatGPT and $plugin-creator in Codex, which is what fix 2 records.
  • Not run: the $skill-creator quick validator and a behavioral run of migrate-plugin in a new Codex task. This session has no Codex CLI task surface; the changed sentence is covered structurally by tests/plugin-ops-plugin.test.mjs.

Related

🤖 Generated with Claude Code

https://claude.ai/code/session_015XWwmeQBXsRaYpmqMJbwsf

The preflight said to read all of two docs and then only the relevant
sections; the second sentence now scopes the live upstream pages.

AGENTS.md and the migration playbook restated the $plugin-creator removal
as a version history note. They now state the current rule and point at
the cheat sheet, the dated record, whose guide claim is brought up to the
wording the packaging guide uses today.

AGENTS.md listed five behavioral test cases where the release gates list
seven; it now cites the release gates and the playbook matrix.

migrate-plugin told an installed copy to act "in this marketplace", which
it cannot detect; the step now applies when the active repository has the
named files. plugin-ops 0.2.5.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015XWwmeQBXsRaYpmqMJbwsf
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 14, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-14T17:55:56.194038Z c931033 PR opened
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@github-actions

github-actions Bot commented Nov 14, 2026 •

Copy link
Copy Markdown

claude-security-review needs no new review of 3258dbc603d4774b01cc8fed9ad9ba4c5c4405c6: every file in scope matches docs-only-paths.

No security findings. I posted no inline comments.

Scope: All 6 files are documentation, one skill text edit, a version bump (plugin-ops 0.2.4 to 0.2.5) and its matching test. There is no code, workflow, hook, token or userConfig change.

Instruction-surface lens: I read each softened instruction, and none removes a control.

  • AGENTS.md preflight: The wording is clarified to apply to the live upstream pages. The mandatory preflight is still in place.
  • AGENTS.md and docs wording: The Codex CLI version-specific notes are swapped for pointers to the cheat sheet and the release gates. The validation requirements are unchanged and now point at the named gates.
  • migrate-plugin step 2: The root AGENTS.md preflight and the philosophy and playbook reads are now conditional on the active repository having them. This is a workflow-ordering rule about reading documentation. It does not gate any write, approval, secret or trust boundary, so it falls in no protected class. It also matches the repository's rule that plugins stay repository-agnostic.
  • Instruction exception register: I did not read docs/contracts/instruction-exception-register/README.md. I judged by consequence instead.

Manifest: The only plugin.json change is the version field, which is on the inert list.

  • manifest version: pass

critical-findings: 0

@github-actions

github-actions Bot commented Nov 14, 2026 •

Copy link
Copy Markdown

claude-review reviewed 3258dbc603d4774b01cc8fed9ad9ba4c5c4405c6: 0 finding(s), 0 as inline comments.

Incremental review of docs/codex-capability-cheat-sheet.md since c931033. The only change adds the read date, "(read 2026-11-14)", to the plugin-packaging-guide claim. It matches the "(read )" convention used elsewhere in the file and the verification date in the PR body. It adds no new claim and no copied upstream prose, and the link and wording are unchanged. The PR has no closing issue ("No related issue"), so there were no acceptance criteria to check.

No findings. I did not run the tests or the validator and did not re-check the live upstream page. The date and verification are the author's claim.

Verifier dropped 0 of 0 candidates.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

Claude-Session: https://claude.ai/code/session_015XWwmeQBXsRaYpmqMJbwsf
@kyle-sexton
kyle-sexton merged commit c88eb12 into main Nov 14, 2026
8 checks passed
@kyle-sexton
kyle-sexton deleted the docs/reconcile-instruction-conflicts branch November 14, 2026 17:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant