Skip to content

docs: align agent instructions with CI and drop incident history - #157

Merged
kyle-sexton merged 1 commit into
mainfrom
docs/prompt-audit-fixes
Nov 14, 2026
Merged

kyle-sexton merged 1 commit into
mainfrom
docs/prompt-audit-fixes

Conversation

@kyle-sexton

Copy link
Copy Markdown
Member

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

Summary

Agent instruction files stated facts the repository contradicts and stated rules as past incidents.

Fix

  • AGENTS.md: the shell-lint command is CI's (shellcheck scripts/*.sh .cursor/install.sh); the bash -n fallback loops per file, because bash -n a b parses only a; the workflow trigger reads "every pull request and every push to main"; the lint heading drops "there is no configured linter" and its anchor follows; the second suite, scripts/test-check-docs-naming.sh, is named; the pinned-cases list states current behavior.
  • plugin-ops skills: sync-local, install-marketplace and update-plugins state the rule and its reason in place of the incident that produced it. install-marketplace, update-plugins and verify-plugin descriptions say when to use the skill.
  • design-automation: the generated prompt covers the listed parts without a fixed order, with numbered steps only where order matters.
  • docs/plugin-philosophy.md: the design boundary records the sync-local fallback (org env var, known checkout paths, repository URL) as an exception.
  • .claude/ecosystems/bash.yaml: line citations of AGENTS.md follow the edit, and the note on the narrower AGENTS.md file list is removed.

The 2026-08-30 dates in the two skills are unchanged; no Cursor page was fetched.

Verification

Run locally on the branch: skill frontmatter check, bash scripts/check-docs-naming.sh --check, typos over the changed paths, and an offline lychee run with fragments over AGENTS.md and docs/plugin-philosophy.md. All passed.

Related

None.

🤖 Generated with Claude Code

https://claude.ai/code/session_015XWwmdRVNmhT8VQkrZ53Fw

AGENTS.md named a shell-lint file list narrower than CI's, a bash -n
fallback that parsed only its first file, and a push trigger wider than
the workflow's. Three plugin-ops skills and the test notes stated rules
as past incidents. The design boundary now records the sync-local
fallback as an exception.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015XWwmdRVNmhT8VQkrZ53Fw
@kyle-sexton
kyle-sexton enabled auto-merge (squash) November 14, 2026 17:54
@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:16.388538Z 72fbf0e 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.

@kyle-sexton
kyle-sexton merged commit d1450f3 into main Nov 14, 2026
12 checks passed
@kyle-sexton
kyle-sexton deleted the docs/prompt-audit-fixes branch November 14, 2026 17:55
@github-actions

Copy link
Copy Markdown

claude-security-review reviewed 72fbf0ebba2bc8c1b0d60a5d0d9bc0530ec9da0c: 0 finding(s), 0 as inline comments.

No security findings on PR #157 at 72fbf0e.

All 8 changed files are Markdown or YAML prose. The diff has no scripts, workflows, plugin or marketplace manifests, userConfig keys, hooks, MCP servers, trusted-path files or token-scope changes. Of the trust controls the lane names, none is touched.

  • Instruction surface (AGENTS.md, SKILL.md bodies): I read each changed rule for removed or softened guardrails.
    • AGENTS.md changes are doc alignment with CI: the shellcheck command now covers scripts/*.sh, the bash -n fallback gets a loop, test-suite and CI wording is updated, and an anchor link is fixed. No rule is removed.
    • The sync-local skill still forbids recursive disk searches under $HOME, OneDrive, Documents and AppData. The change only rewords the rationale.
    • The design-automation skill now lets the prompt sections come in any order, with step numbers only where order matters. The guardrails item, "adapted to the lane, never removed", is unchanged.
    • The install-marketplace and update-plugins edits replace "Verified" with "Observed", still say to re-fetch the docs before advising, and add "Use when…" trigger text to skill descriptions. The verify-plugin edit adds the same kind of trigger text. This improves accuracy and weakens no control.
    • I did not check the instruction exception register at docs/contracts/instruction-exception-register/README.md. I judged each removal by its consequence. None of them removes a check that guarded a protected action.
  • docs/plugin-philosophy.md: this adds a recorded exception to the design boundary. When no source is passed, sync-local falls back to MELODIC_CURSOR_PLUGINS, a short list of known checkout paths, then the repository URL. This describes existing behaviour. The diff changes no script, so the fallback path handling is not reviewed here, and the text does not widen any trust.
  • .claude/ecosystems/bash.yaml: only line-number citations and notes text changed. There are no commands or pins.

Under the throughput-phase section, no named friction hold is weakened.

critical-findings: 0

@github-actions

Copy link
Copy Markdown

claude-review reviewed 72fbf0ebba2bc8c1b0d60a5d0d9bc0530ec9da0c: 0 finding(s), 0 as inline comments.

No findings. The PR only changes docs and skill text, and I checked each factual claim it makes against the repository at head.

  • CI trigger: AGENTS.md now says "every pull request and every push to main". pr-require-checks.yml has push: branches: [main] and pull_request, so that matches. The workflow's own header comment still says "every push and pull request". It is unchanged by this PR and is not a finding.
  • Lint commands: the shellcheck scripts/*.sh .cursor/install.sh command and the per-file bash -n loop in AGENTS.md match the workflow's steps.
  • Anchor: the new #lint--validate anchor matches the renamed ### Lint / validate heading. No other file references the old anchor.
  • Line citations in .claude/ecosystems/bash.yaml: AGENTS.md:36 is the "Only bash, git, python3 and jq" line, and AGENTS.md:97-100 is the python3 / marketplace.json bullet. The removed AGENTS.md:42-43 citation has no remaining references.
  • 2026-08-30 dates: "Verified" became "Observed" with a "re-fetch before advising" note, and the dates are unchanged. That fits the rule that a Verified date moves only on a live fetch.
  • Design boundary: the new exception paragraph in docs/plugin-philosophy.md matches the fallback order in plugins/plugin-ops/skills/sync-local/SKILL.md: MELODIC_CURSOR_PLUGINS, the known checkout paths, then the repository URL.
  • Not run: I did not run the shell scripts, typos or lychee. The Verification section of the PR body is author-claimed and I did not confirm it.

The PR names no closing issue, only the no-issue escape with a reason. There were no settled-threads or prior-findings files, and no manifests changed. The ls .claude/rules check was cut off by a failed multi-command call and I did not retry it.

Verifier dropped 0 of 0 candidates.

kyle-sexton added a commit that referenced this pull request Nov 14, 2026
No related issue: a one-line comment correction left over from the
prompt audit merged in #157.

## Summary

The header comment of `.github/workflows/pr-require-checks.yml` said the
checks run on every push. The trigger is `pull_request` and `push:
branches: [main]`.

## Fix

The comment now reads "every pull request and every push to `main`",
matching `AGENTS.md`. No workflow behavior changes.

## Verification

Comment-only change; the workflow's own run on this pull request parses
the file.

## Related

- #157

🤖 Generated with [Claude Code](https://claude.com/claude-code)

https://claude.ai/code/session_015XWwmdRVNmhT8VQkrZ53Fw

Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
kyle-sexton added a commit that referenced this pull request Nov 16, 2026
…the cross-cutting record (#166)

Refs: melodic-software/claude-code-plugins#15723

## Summary

Since #154 and #156, #164 moved the check-managed-files pin to
ci-workflows v0.74.0 (`944d346`), and #163 added a header line to
`pr-automerge-dependabot.yml`. The cross-cutting record's notes still
named v0.71.0 and line ranges one line short. This change corrects those
three citations and nothing else.

## Fix

- `check-managed-files@8e1076f v0.71.0` becomes `@944d346 v0.74.0`,
matching `pr-check-managed-files-hosted.yml:118`.
- `pr-automerge-dependabot.yml:21-29` becomes `:22-30` (the job), and
`:3-7` becomes `:3-8` (the header sentence).

No command, version or checksum changes. #162 also moved the
lychee-offline and typos composites to v0.74.0. I diffed them against
v0.39.8 (`594987a`): their version, sha256 and argument defaults are
unchanged. lychee-offline moved its run step into `run.sh` unchanged,
and it now falls back to a bundled `lychee.toml` only when the caller
has none; this repository has one. The other records' citations still
hold: apart from that header line, every CI edit since #156 changed
lines in place.

## Verification

- Schema: `check-jsonschema --schemafile
docs/contracts/ecosystem-commands/ecosystem.schema.json`
(claude-code-plugins `origin/main`) over all six records printed `ok --
validation done`.
- Method: a throwaway `git clone --shared` of this branch, with
`refs/remotes/origin/main` at #156's merge `c12a04f`. The range runs
#157 through this commit: 16 files, covering workflows, dependabot,
AGENTS.md, REVIEW.md, docs and five SKILL.md. Every tool runs with `env
-C <clone>`. Toolchain skill text is 1.4.0.
- Run 1, `/toolchain:check all`, 11:37 PM to 11:38 PM EST 2026-11-15.
Overall line: `Overall: PASS (3 of 3 ecosystems passed)`.

| Ecosystem | Build | Test | Lint | Status |
|---|---|---|---|---|
| bash | — | pass | pass | PASS |
| powershell | — | — | pass | PASS |
| markdown | — | — | pass | PASS |
| typescript | — | — | — | — |

- bash: the sync-local suite has 73 passed, 0 failed and 0 skipped (pwsh
present), and the docs-naming suite has 9 ok. shellcheck and `bash -n`
over CI's list exited 0.
  - powershell: PSScriptAnalyzer reported 0 findings.
  - typescript: every command is null.
  - No dotnet, python or go project files exist.
  - The output contains no `skip (unresolved`.
- Run 2, `/toolchain:lint`, 11:38 PM to 11:39 PM EST. Overall line:
`Overall: PASS (2 of 2 ecosystems passed)`.
  - markdown passed, and yaml is all null.
- cross-cutting passed: check-docs-naming, jq, the relative-link check,
lychee (0 errors), typos, and `gitleaks dir . --config .gitleaks.toml
--no-banner --redact` (no leaks).
  - Installed typos is 1.52.2; the pin is 1.50.3.
- The verify gate passed on this commit: schema validation plus the
cross-cutting check-cmd.

## Remaining

melodic-software/claude-code-plugins#15723 stays open after this pull
request. Its baseline steps are still owed: a `/toolchain:check all` and
a `/toolchain:lint` with the bundled defaults (records removed) on one
range, then the comparison of their command lists with the record runs
above. This pass had a two-run budget, which went to the record runs.

## Related

- #154 and #156, which merged the records this change corrects
- melodic-software/claude-code-plugins#15723,
melodic-software/claude-code-plugins#15703 (parent)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
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