The round-3 fixes changed shipped skill content in three plugins without
touching their manifests, so installed copies would keep serving the old
content from cache. plugin-author requires a patch bump for exactly this
reason: consumers use the version to detect changes.
It matters most for lint — anyone installed at 1.1.2 has a cached
vale-run/SKILL.md stating that Vale exits non-zero on warnings, which is
backwards and would lead them to build a gate that passes everything.
- bin 1.1.0 -> 1.1.1 (caveman: suppression comments removed)
- kyberforge 1.2.3 -> 1.2.4 (skill-audit/agent-audit: Vale step reworked)
- lint 1.1.2 -> 1.1.3 (vale-run: exit-code and suppression-syntax fixes)
Marketplace entries carry no per-plugin version, so both marketplace.json
files are unchanged.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MCQ648fLSFXPHGZdQ8gn58
Round-3 review of PR #85 found the "enforcing" pre-commit hook enforced
nothing. Vale's exit code keys on error-level alerts alone: five of the
six rules were level: warning, so they exited 0, and pre-commit hides
output from a passing hook — the alerts were invisible and blocked
nothing. ADR-0013 rejected a report-only trial tier and then shipped one
by accident.
Flatten every rule to level: error. Vale's own exit code is then correct,
so the hook entry drops to a bare vale-wrap.sh call and the graded
error->FAIL / warning->SUGGESTION mapping disappears from both audit
skills: every alert is a FAIL, in the gate and the audit alike. No
ignorable tier, matching shellcheck, the test suite and
conventional-pre-commit.
Delete Kyberforge.VagueQualifier. Measured against the 41 skill/agent
files as they stood before the rule ever ran: 2 hits. One marginal
("very different" -> "fundamentally different"), one an unfixable false
positive — caveman/SKILL.md quotes "of course" as an example of filler,
a mention not a use — which forced the only Vale suppression comments in
the repo. Those four lines go with it; two of them were dead anyway,
suppressing a frontmatter-scoped rule on a body line. Held-out prose (273
files) fired 15 times, 9 inside out-of-scope research examples and the
rest one word in two idioms in a single doc. SentenceOpenerThereIs
survives: 22 held-out hits, both in-corpus hits clean rewrites, zero
suppressions.
Widen .vale.ini's globs to [**/SKILL.md], [**/agents/*.md] and
[**/*.agent.md]. The plugins/*/-prefixed globs scoped nothing — Vale's *
crosses /, so they already matched docs/research/examples/**/agents/*.md
and assets/templates/SKILL.md, the two paths CONTEXT.md claimed they
excluded. Scoping is and was the hook's files: regex. The old globs also
hid a silent false negative: a skill outside plugins/ matched no section,
so Vale reported 0 files and exited 0, which both audits read as clean.
They now treat a 0-file run as NOT RUN and fall back to full judgment.
Also:
- vale-wrap.sh resolves relative --config values and file arguments
against the caller's cwd, as vale does, instead of the repo root, which
hard-errored from a subdirectory and silently skipped flattening for
file args that did not resolve from the root. Absolute paths inside the
cwd are relativized so reports cite resolvable paths, not scratch ones.
- vale-run's exit-code model was documented backwards ("exits non-zero
whenever it finds an alert at or above MinAlertLevel") and would have
led anyone following it to build a gate that passes everything. Its
Markdown suppression syntax was MDX-only and does not suppress in .md;
corrected in the skill and its troubleshooting reference, with
backtick/fence exemption documented as the first resort.
- skill-size-check.sh fails only above 500 lines, agreeing with
skill-audit's validate.sh <= 500 pass.
- ADR-0013 and CONTEXT.md amended to match, recording why graded
severities cannot gate.
Verified: 9 test scripts / 15 vale-wrap cases pass; vale-audit-prefilter,
skill-size-check and shellcheck pass --all-files; check-manifests and
claude plugin validate --strict clean. New tests fail against the old
script (3 of them) and pass against the new one.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MCQ648fLSFXPHGZdQ8gn58
Addresses PR #85's outstanding review items after grilling the open
questions against ADR-0013/CONTEXT.md/ADR-0010:
Blocking fixes:
- vale-wrap.sh: replace json.dumps() escaping (which silently defeated
Vale's frontmatter scope on any description containing a quote,
backslash, or non-ASCII char — ~58% of the corpus) with a single-quoted
YAML scalar, substituting a Unicode right single quote for embedded
apostrophes rather than '' doubling (Vale's frontmatter scanner isn't a
full YAML parser and silently truncates on '' too).
- vale-wrap.sh: fix a blank-line-inside-a-folded-description truncation
bug via indentation-based, blank-line-tolerant body capture; narrow
flattening to `>`-style scalars only (`|` already works unflattened).
- skill-audit/agent-audit Step 1: make the vale-wrap.sh invocation
cwd-independent via git rev-parse --show-toplevel, fixing a bug where
no single cwd satisfied all three Step 1 commands.
- styles/Kyberforge/VagueQualifier.yml: prune 17 tokens verified
false-positive-dominated on this repo's own voice via a real corpus
sweep (obvious, clearly, usually, several, simple, easy, completely,
simply, tiny, etc.), keep 13 with real or unattested noise. Revert the
28 prose "fixes" those tokens drove across 14 skill files back to their
original, correct wording, including a functional regression to
caveman/SKILL.md's own filler-word list (a mention, not a use) — now
guarded with vale-off comments against recurrence.
Gaps:
- --minAlertLevel=warning on the pre-commit hook and Step 1 invocation
so warning-level rules actually surface, without collapsing the
FAIL/SUGGESTION severity mapping skill-audit/agent-audit rely on.
- vale-wrap.sh: fix --config=<path> equals-form, absolute-path silent
no-op, and a zero-file-argument stdin hang.
- Route vale-run and lint-runner through a documented wrapper script
when a target repo has one, instead of unconditionally recommending
bare `vale`.
- Wire Kyberforge.VagueQualifier/SentenceOpenerThereIs into skill-audit/
agent-audit's dimension-mapping prose (Body discipline).
- Add plugins/lint/sources.md provenance for lint-runner (ADR-0010).
- Sync both marketplace.json lint-entry descriptions with plugin.json.
- Retune skill-size-check.sh's MAX_WORDS 5000->2900 (measured ~1.6-1.7
tokens/word on this repo's corpus, the old value gated at ~8,500
tokens against a stated 5,000 ceiling); fix the >/>= line-count
boundary and wc -l undercount on files with no trailing newline.
- Document the vale binary as a Setup prerequisite in AGENTS.md.
- Fix SentenceOpenerThereIs's dead regex alternative and add a real
sentence-start anchor/scope.
- Fix a stale docs/research/docs/vale/ index pointer in kyberforge's
docs README (moved to plugins/lint/ in e1a5403).
- Rewrite ADR-0013's Consequences section past-tense to describe what
actually landed, and record the styles-portability limitation
(repo-root placement stays intentional; deferred to a separate
session per this PR's review).
Test coverage: 9 new vale-wrap.sh fixtures (quotes, backslash/unicode,
blank-line paragraphs, --config= form, zero-arg/absolute-path handling,
literal-block no-regression) and boundary-pair tests for
skill-size-check.sh's line/word ceilings.
bash tests/run-tests.sh: 9 scripts + 125 bats assertions, all passing.
scripts/check-manifests.sh and claude plugin validate --strict: clean.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MCQ648fLSFXPHGZdQ8gn58
Deferred item from PR #85 review. Per ADR-0013: cherry-picks two low-noise
rules from trialing write-good/alex against the real corpus (VagueQualifier,
SentenceOpenerThereIs) into styles/Kyberforge rather than adopting either
package wholesale (both are tuned for blog prose and were noisy on this
repo's terse, imperative instruction files - see the ADR's rejected-rule
list). Adds a new skill-size-check pre-commit hook enforcing agentskills.io's
500-line/5,000-token SKILL.md ceiling, currently unenforced. Fixes the 28
resulting violations across 20 existing SKILL.md/agent files so the
enforcing pre-commit hook lands clean.
governance.md/CONTROLS.md were evaluated and excluded as rule sources -
they're org/CI-infrastructure controls, not prose patterns Vale can express.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QUDczvw1H3eEeMD29Q9Lbi
plugins/bin loses a whole skill (gitea removed) — minor bump (1.0.5 ->
1.1.0) to reflect the capability-surface change. plugins/gitea gains a
reference file and a README fix, no new capability — patch bump
(1.3.1 -> 1.3.2).
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
The deep-module split in plugins/gitea/ (ADR 0011) already covers every
domain the old plugins/bin/skills/gitea/ flat skill handled. Move its
token-access.md into plugins/gitea/references/ first, since it held
empirical scope-test results (Actions/CI, Wiki, Notifications, Packages,
User/Org) not reproduced anywhere in the new plugin, then drop the old
skill and fix a stale cross-reference pointing at it.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
scripts/install.sh hardcoded $REPO_ROOT/.git/hooks, which breaks under any
git worktree checkout (.git is a file there, not a directory) — this is
what blocks every worktree-based agent from pushing cleanly. Resolve the
hooks directory via `git rev-parse --git-path hooks` instead, normalizing
to an absolute path since git returns it relative to the queried repo root
for plain checkouts but absolute for worktrees.
Also drops `agents`/`skills` fields from plugins/bin, plugins/core, and
plugins/gitea plugin.json where the referenced directories don't exist on
main yet (bin never had an agents/ dir; core and gitea's real skill/agent
content is still pending merge from an in-flight branch) — these were
failing scripts/check-manifests.sh and blocking pushes for unrelated work.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FNJWdVvdgvZCHi1hZGqgVQ
The gotcha claimed Gitea never auto-closes issues on merge. Confirmed
empirically (issue #63 / PR #64) that a regular merge preserving an
original commit's closing keyword does auto-close — only squash merges
(this skill's default) are unreliable. Also drops search_issues from
allowed-tools since no dispatch route calls it.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
## Why
Without this guard, the agent could bypass the skill and call Gitea MCP
tools directly, skipping owner/repo resolution and label-ID normalization.
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
## Why
The Obsidian MCP server config was living at the repo root, making it
a repo-level concern rather than part of the plugin it belongs to.
Moving it into plugins/bin/ means the plugin is self-contained and the
server travels with it on install.
## Implementation Notes
mcpServers is declared in the Copilot manifest (plugin.json) because
Copilot requires explicit path declarations. CC auto-discovers .mcp.json
from the plugin root so no change to the CC manifest is needed.
Bumps version to 1.0.3 in both manifests.
---
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
## Why
Version sync across all plugin manifest locations so the CC plugin loader,
the .github marketplace mirror, and the canonical plugin.json files all
report the same version.
## Impact
Consumers fetching the plugin via the marketplace will see the updated
version entry.
## Why
Plugin and marketplace management had no governed authoring path. Creating or
updating a plugin required knowing the dual-manifest convention, version parity
rules, and directory skeleton by memory — nothing enforced consistency or guided
the process.
`/plugin-author` closes that gap by owning the full plugin scaffold lifecycle:
create, update, rename, and release. `/marketplace-author` handles the
marketplace-facing side: register, deregister, and update plugin entries in
`marketplace.json`.
ADR-0016 codifies the version parity convention (identical `version` in both
`plugin.json` and `.claude-plugin/plugin.json`) that `/plugin-author` now
enforces. The two plugin.json files in this repo are backfilled to comply
(keys also sorted to pass the pretty-format-json hook). CONTEXT.md gains
glossary entries for "plugin scaffold" and "version parity" so future agents
have shared vocabulary for these concepts.
## Implementation Notes
`/plugin-author` ships a `scripts/new-plugin.sh` scaffold script that generates
the directory skeleton and both manifests in one shot; the skill calls the script
rather than generating files ad hoc so the scaffold is reviewable and repeatable.
Version parity is an invariant, not a suggestion — the skill will fail loudly
on create/update if the two versions would diverge.
ADR: docs/adr/0016-plugin-version-parity.md
Skills and evals migrated from .agents/ to plugins/bin/ plugin directory.
Remove .mcp.json, provider-manifest.sh, and skills-lock.json legacy artifacts.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
