docs(plugin-quality): cover plugin-shipped harness config in the config lens

[kyle-sexton]

No linked issue.

Summary

Doc-alignment (ROSTER row 141, "Create plugins", https://code.claude.com/docs/en/plugins, fetched 2026-08-04). The plugins guide specifies three plugin-root config surfaces the audit skill's config lens predated, each carrying a silent failure mode worth auditing:

• settings.json — only agent and subagentStatusLine are supported; unknown keys are silently ignored; takes priority over settings in plugin.json. An unsupported key reads as configuration but does nothing.
• .lsp.json — an entry with an invalid configuration is silently skipped (only claude --debug says why); a server that fails to start surfaces in the /plugin Errors tab.
• monitors/monitors.json — monitors auto-start while the plugin is active and every stdout line from command reaches Claude as a notification (volume/portability concerns).

Changes:

• references/component-types/config.md: name the three surfaces in "Read first" and add one doc-grounded check bullet per surface.
• SKILL.md: widen the config lens index row so these surfaces route there.
• plugin-quality 0.4.0 → 0.5.0 + CHANGELOG entry (Added → minor, per this plugin's precedent).

Repo-conformance audit for the same row found no defect: all 61 plugin manifests conform (name matches directory, description and version present, documented-schema keys only), structure conforms (only plugin.json under .claude-plugin/, hooks in hooks/hooks.json with a top-level hooks key, no commands/ dirs), and claude plugin validate passes for all 61 plugins plus --strict on the marketplace catalog, zero warnings (Claude Code 2.1.221, 2026-08-04).

Related

• .work/doc-alignment/ROSTER.md row 141 (memory-tier, not committed)
• Sibling roster rows 139/142 own the marketplace and plugins-reference pages

🤖 Generated with Claude Code

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

[claude]

Claude finished @kyle-sexton's task in 3m 12s —— View job

---

Review complete

• Gather context (diff, CLAUDE.md, changed files)
• Understand the request (code review of PR docs(plugin-quality): cover plugin-shipped harness config in the config lens #1930)
• Review config.md changes for doc-accuracy and correctness
• Review SKILL.md change
• Review plugin.json version bump + CHANGELOG.md entry
• Check alignment with fresh-docs mandate and plugin design rules
• Post final review

This is a clean, well-scoped doc-alignment change. Summary of what I checked:

Doc-accuracy (fresh-docs mandate) — I re-fetched https://code.claude.com/docs/en/plugins myself and checked all three new claims in config.md against the live page:

• settings.json — confirmed: "Currently, only the agent and subagentStatusLine keys are supported... Settings from settings.json take priority over settings declared in plugin.json. Unknown keys are silently ignored."
• .lsp.json — confirmed: "a language server that fails to start appears [in the /plugin Errors tab]... An entry with an invalid configuration is skipped instead; run claude --debug to see why."
• monitors/monitors.json — confirmed: "Claude Code starts each monitor automatically when the plugin is active... Each stdout line from command is delivered to Claude as a notification."

All three bullets are accurate, correctly cited, and dated. No drift found.

Scope/architecture — the change follows the skill's own extension contract at SKILL.md#L495 ("Add coverage = ONE reference file + ONE index row. Never grow this hub") exactly — one reference file gets new content, one index row gets widened. No new files, no hub bloat. No overlap with hook.md (which owns hooks/hooks.json, a distinct surface).

Versioning/CHANGELOG — 0.4.0 → 0.5.0 for an Added entry is the correct SemVer minor bump per this plugin's own precedent (0.4.0 did the same for an Added entry). Format matches Keep a Changelog, entry is newest-first, dated 2026-08-04 (matches today's date). This repo has an automated changelog-parity-gate CI check that verifies version bumps are paired with a CHANGELOG entry — I couldn't execute it in this sandbox (script execution required approval I didn't have), but a manual read confirms the pairing is present and well-formed.

PR mechanics — body satisfies the pr-issue-linkage contract (No linked issue. + non-empty ## Related). Title uses a valid Conventional Commits type (docs).

Minor, non-blocking observation: docs/OFFICIAL-DOCS.md's "Create plugins" row still shows verified date 2026-07-17, even though this PR performed a live fetch of that exact page on 2026-08-04 and confirmed it still matches. The file's own rule only mandates an update when a fetch reveals drift (none was found here), so this isn't a defect — but bumping the date would let the ceiling reflect the more recent confirmation. Optional.

No correctness issues, no architecture concerns, nothing to request changes on. Security review (if applicable) is left to the dedicated security lane per REVIEW.md's scope split.

[claude]

Claude finished @kyle-sexton's task in 39s —— View job

---

Security review

• Gather context (PR diff, changed files)
• Review each changed file for security issues
• Post findings

Scope reviewed: plugins/plugin-quality/.claude-plugin/plugin.json, plugins/plugin-quality/CHANGELOG.md, plugins/plugin-quality/skills/audit/SKILL.md, plugins/plugin-quality/skills/audit/references/component-types/config.md (full diff via git diff origin/main...HEAD).

Findings: none.

All four changed files are documentation/metadata:

• plugin.json — a version string bump (0.4.0 → 0.5.0), no schema or permission changes.
• CHANGELOG.md — a prose changelog entry.
• SKILL.md — one reference-index table cell widened with descriptive text.
• config.md — added "Read first" bullets and "Check" guidance describing three plugin-shipped harness config surfaces (settings.json, .lsp.json, monitors/monitors.json) for auditors to check in other plugins.

None of this diff introduces or modifies executable code, hooks, workflows, MCP server wiring, secrets handling, or userConfig/permission surfaces — it's audit-skill prose telling a human/agent auditor what to look for elsewhere. No command execution, no injection surface, no trust-boundary or authorization logic changed. No security issues found.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 1bdcdaa1fa

ℹ️ 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".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[github-actions]

Claude has reviewed this PR 2 times. The lane skips further automatic reviews after 5; deleting this comment resets the count.

[claude]

Claude finished @kyle-sexton's task in 1m 26s —— View job

---

Review complete

• Gather context (diff, CLAUDE.md, changed files)
• Understand the request (code review of PR docs(plugin-quality): cover plugin-shipped harness config in the config lens #1930, re-run after synchronize)
• Review changed files for correctness and CLAUDE.md alignment
• Check whether Codex's P2 finding (monitor when trigger) was addressed
• Post final review

This PR was previously reviewed at 1bdcdaa and found clean. Since then, commit 10e10c0 landed, addressing the P2 finding from Codex's review on the monitor bullet. I re-reviewed the full diff against origin/main and re-verified the new claim against a fresh fetch of the live docs.

Codex's finding is correctly and precisely fixed. The old bullet in config.md said monitors "auto-start while the plugin is active," which conflated "always" (session-start) monitors with "on-skill-invoke:<skill-name>" (on-demand) monitors — exactly the misclassification risk Codex flagged, consistent with the distinction already on record at docs/MIGRATION-PLAYBOOK.md:1364-1367. The fix at config.md#L37-L43 now instructs the auditor to inspect each monitor's when trigger before assessing volume, and I independently re-fetched https://code.claude.com/docs/en/plugins-reference#monitors and confirmed the wording tracks the source almost verbatim:

when — Controls when the monitor starts. "always" starts it at session start and on plugin reload, and is the default. "on-skill-invoke:<skill-name>" starts it the first time the named skill in this plugin is dispatched.

The config.md bullet, the updated citation (adds plugins-reference#monitors alongside the original plugins guide link — both already ROSTER-tracked in docs/OFFICIAL-DOCS.md), and the CHANGELOG.md entry were all updated consistently in the same commit — no stale copy left behind in either file.

Architecture/scope — still exactly one reference file + the existing index row per the skill's own extension contract; no new files, no hub bloat.

No new issues found. The fix-up commit is scoped tightly to the one bullet Codex flagged, doesn't touch the settings.json/.lsp.json bullets (unaffected, previously verified), and the CHANGELOG/config.md wording stay in sync. Nothing to request changes on.

Security review is out of scope for this lane per REVIEW.md's split (already covered by the dedicated security-review run on this PR, which found no issues).

[claude]

Claude finished @kyle-sexton's task in 45s —— View job

---

Security review

• Gather context (PR diff, changed files)
• Review each changed file for security issues
• Post findings

Scope reviewed: plugins/plugin-quality/.claude-plugin/plugin.json, plugins/plugin-quality/CHANGELOG.md, plugins/plugin-quality/skills/audit/SKILL.md, plugins/plugin-quality/skills/audit/references/component-types/config.md — full diff via git diff origin/main...HEAD at HEAD 10e10c0.

Findings: none.

All four changed files are documentation/metadata, with no executable code, workflow, hook, MCP, or permission surface touched:

• plugin.json — version bump 0.4.0 → 0.5.0 only; no schema, permission, or userConfig changes.
• CHANGELOG.md — static prose changelog entry.
• SKILL.md — one reference-index table cell widened with descriptive text.
• config.md — added "Read first" bullets and "Check" guidance describing three plugin-shipped harness config surfaces (settings.json, .lsp.json, monitors/monitors.json) for auditors to check in other plugins. This is inert prose consumed by a human/agent auditor — it does not execute, parse untrusted input, or grant any capability.

No command execution, injection surface (command/SQL/path/template), token/credential handling, permissions:/trust-boundary change, or supply-chain risk (no dependency/action pins touched) in this diff. Consistent with the earlier security-review pass on this PR (comment at 16:19:07Z) — the follow-up commit (10e10c0, addressing the Codex when-trigger review comment) is documentation-only as well and doesn't change this conclusion.