docs(agents): fix broken steps and de-duplicate the instruction files - #100
Merged
Conversation
galatanovidiu
force-pushed
the
docs/agent-instructions-audit
branch
4 times, most recently
from
July 27, 2026 14:10
24517d2 to
4d53cf7
Compare
WHAT: - CLAUDE.md collapses to `@AGENTS.md`. The two files were byte-identical except for one word, so AGENTS.md is now the single source of truth and the purpose line no longer names a specific agent. - Reshape "Commit discipline" into "Commits". The agents.md convention asks this section for runnable steps, so it now leads with the pre-commit commands the repo was missing and states plainly that nothing enforces them. The scope rule stays as one line, minus the release number and the unrelated SOCKS detail. - Drop the canary and dist-tag-rollback steps from the release gate. Nothing an agent reading this file ever performs; publishing is a human operation. - Replace the `npx mcp-wordpress-remote --help` smoke test. There is no argv handling anywhere in src/, so the binary starts the stdio server and hangs with no output. The step could never pass. It now checks that the packed dist/proxy.js is the tsup bundle rather than per-file output. - Correct "run all tests", which ran only tests/unit/ and silently skipped the three integration suites. - Add a Version section: package.json and MCP_WORDPRESS_REMOTE_VERSION in src/lib/config.ts must move together. WHY: Two copies of one file drift, and an edit to either would silently miss the other. The two commands were wrong in ways that only surface when someone trusts them: --help hangs, and "all tests" reported green while skipping a fifth of the suites. The version rule is not inferable from the code and has broken twice, once shipping a token directory named wordpress-remote-undefined.
galatanovidiu
force-pushed
the
docs/agent-instructions-audit
branch
from
July 27, 2026 14:22
4d53cf7 to
8f2ae6f
Compare
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
1 participant
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.
Audit of
AGENTS.md/CLAUDE.md. Three of the findings are things that were actively wrong, not style.AGENTS.md and CLAUDE.md were the same file
diffreports one differing line out of 32 —CodexvsClaude Codein the purpose sentence.AGENTS.mdwas added later (9347182 chore: add AGENTS.md for Codex) by copyingCLAUDE.mdand swapping that word.Two copies of one file drift, and any edit to either would silently miss the other.
CLAUDE.mdis now just@AGENTS.md, and the purpose line no longer names a specific agent — the proxy sits between an MCP client and WordPress.--helpnever workedThe gate said to smoke-test the tarball with
npx mcp-wordpress-remote --help. There is no argv handling anywhere insrc/; the binary starts the stdio server and hangs. Measured: exit 124, zero bytes on both stdout and stderr. Published 0.3.5 behaves identically, so this step has never been passable.Replaced with a check that actually catches something — that the packed
dist/proxy.jsis the tsup bundle and not per-file output, which is exactly the failure mode #98 just fixed."Run all tests" did not run all tests
npx jest tests/unit/ --no-coveragecovers 12 suites and silently skips the 3 integration suites. It reported green while omitting a fifth of the tests. Corrected tonpx jest tests/unit/ tests/integration/ --no-coverage— 15 suites, 225 tests.Canary and dist-tag steps removed
Steps 6 and 7 described publishing a canary, soaking it, and rolling back a dist-tag. Those are human release operations; an agent reading this file never performs them. They belonged in a runbook, not in agent instructions.
Added: the version rule
Not inferable from the code and it has broken twice — once shipping a token directory named
wordpress-remote-undefined, once needing the follow-up in #85.package.jsonandMCP_WORDPRESS_REMOTE_VERSIONinsrc/lib/config.tsmust move together. Noted alongside it that the token store is namespaced by version, so a bump forces every user to re-authenticate.Left alone
Commit discipline and the architecture notes verify clean against the code —
InitResultatsession-utils.ts:130,transportType: nullat:93, and the nock endpoint matchestransport-detection.test.ts:17. Untouched.