Instead of injecting the full SKILL.md body as additionalContext, inject
"You must run the Skill(<name>) tool." — a more conventional way of
telling the agent to use the Skill tool for context loading.
- Add stemmer and shared contractions modules for lexical prompt matching
- Enhance lexical index and prompt patterns with stemming support
- Add promptSignals metadata to all 43 skill frontmatter files
- Add comprehensive documentation site (docs/)
- Add .claude-plugin marketplace and plugin metadata
- Add benchmark scenarios script
- Update skill manifest with prompt signal data
- Add lexical-index and stemmer tests, expand prompt-patterns tests
Add scorePromptWithLexical as an additive wrapper around the existing exact prompt matcher.
It preserves current matching behavior, then falls back to lexical index hits when the exact score stays below threshold.
Verified: bun test tests/prompt-patterns-lexical.test.ts
Verified: tsc -p hooks/tsconfig.json --noEmit
Swarm-Agent: codex-prompt-patterns
Add a MiniSearch-backed lexical index for retrieval frontmatter with synonym and contraction expansion so hooks can rank skills from short natural-language queries.
Verified: bun test hooks/lexical-index.test.ts
Verified: ./node_modules/.bin/tsc --noEmit --module NodeNext --moduleResolution NodeNext --target ES2022 --strict --skipLibCheck --types node hooks/src/lexical-index.mts
Swarm-Agent: codex-lexical-index
Add a shared rankSkills utility that combines path, command, import, profiler, prompt, lexical, and priority signals into a single sortable score with per-signal breakdowns.
Add a focused Bun regression test covering weighted scoring, ordering, and default field behavior for sparse candidates.
Verified: bun test tests/unified-ranker.test.ts
How to test: bun test tests/unified-ranker.test.ts
Swarm-Agent: codex-unified-ranker
Eval analysis of 9 real sessions showed 10 skills never triggering despite being
requested. Root causes: pathPatterns too narrow (agents write to lib/email-template.tsx
not emails/), promptSignals containing regex instead of plain text (vercel-sandbox),
and missing promptSignals entirely (v0-dev, vercel-firewall).
Skills updated: email, vercel-queues, edge-runtime, vercel-firewall, chat-sdk,
v0-dev, vercel-sandbox. New skill: next-forge (bootstrap detection).
Add a PreToolUse observer hook that records Agent tool launches as pending subagent spawn metadata for downstream bootstrap logic.
It preserves the existing no-mutation contract by always returning {} and now integrates with the committed subagent-state append API.
Verified: bun test tests/pretooluse-subagent-spawn-observe.test.ts
Verified: ./node_modules/.bin/tsc -p hooks/tsconfig.json --noEmit
How to test: run bun test tests/pretooluse-subagent-spawn-observe.test.ts
Swarm-Agent: codex-observer
- SubagentStart bootstrap hook injects project context (likely skills, summaries) into spawned subagents
with budget scaling by agent type (minimal for Explore/Plan, standard for general-purpose)
- SubagentStop sync hook writes agent metadata to a session-scoped JSONL ledger for observability
- SessionEnd cleanup extended to remove subagent ledger files
- Updated ai-elements/nextjs skills, benchmark-agents and eval skill definitions
Hook modules were creating separate logger instances, so a single PreToolUse run could emit multiple invocationIds once hook-env catch logging fired. Reusing one process-scoped invocationId keeps all lines from one hook invocation correlated.
This also demotes internal trigger diagnostics back to debug so summary mode stays limited to complete and issue events, matching the logger contract and tests.
Verified: bun test tests/pretooluse-skill-inject.test.ts (278 tests pass)
Verified: bun test tests/logger.test.ts (12 tests pass)
Verified: bun test tests/hook-sync.test.ts -t "logger .mts/.mjs sync|pretooluse-skill-inject .mts/.mjs sync" (6 tests pass)
Swarm-Agent: codex-invocation-id-fix
Make the session-start profiler resolve binaries from PATH safely before
invoking them, cap the version-check subprocesses at 3 seconds, and
avoid crashing when npm or agent-browser is missing.
Also expand the outdated Vercel CLI guidance to include the pnpm global
upgrade path and cover the new skip/timeout behavior in profiler tests.
Verified: bun test tests/session-start-profiler.test.ts
Swarm-Agent: codex-profiler-harden-split-2-v2
Replace empty catch blocks in hook-env and session-start-profiler with\nstructured debug logging using the shared hook logger.\nAlso make the Vercel CLI update check compare numeric version\nsegments so 1.9.0 correctly sorts below 1.10.0.\n\nVerified: bun test tests/session-start-profiler.test.ts\nHow to test: bun test tests/session-start-profiler.test.ts\nSwarm-Agent: codex-profiler-harden-split-1
Skill frontmatter (pathPatterns, bashPatterns, promptSignals, etc.)
was being injected alongside the skill body, wasting token budget on
metadata only useful for hook matching. Now uses extractFrontmatter()
to emit only the markdown body.
Brace groups like {ts,js,mjs} were being escaped literally, which prevented extension-list path patterns from matching. The glob parser now expands balanced brace groups into recursive regex alternations while preserving literal braces when no alternation is present.
Verified: bun test tests/patterns.test.ts
Verified: bun test tests/fuzz-glob.test.ts
Verified: bun test tests/hook-sync.test.ts
Verified: bun test tests/pretooluse-skill-inject.test.ts -t "matches src/middleware\.(mjs|mts) to routing-middleware skill"
Swarm-Agent: codex-brace-expand
Hash invalid session IDs before constructing dedup temp paths so crafted stdin values cannot smuggle traversal segments into recursive claim cleanup. Shared temp-path resolution now verifies the resolved target stays under tmpdir, and seen-skills tests cover both stable safe IDs and hashed invalid IDs.
Verified: bun test tests/session-start-seen-skills.test.ts
How to test: bun test tests/session-start-seen-skills.test.ts
Swarm-Agent: codex-path-traversal
New ai-generation-persistence skill (priority 6) injects guidance for treating
AI generations as first-class persistent resources — unique IDs, addressable
URLs, database/Blob storage, cost tracking, and generate-then-redirect UX
patterns. Triggers on AI SDK imports and broad prompt signals.
New verification skill added. Updated ecosystem graph, catalog, manifest,
fixtures, and snapshots.
Parallel PreToolUse hooks were racing on the same seen-skills file, causing 2-6x
duplicate injections. UserPromptSubmit hook didn't share dedup state at all.
Fix by implementing atomic per-skill claim files (Oracle session: fix-dedup-race-condition-plan):
1. In hooks/src/hook-env.mts, add tryClaimSessionKey(sessionId, kind, key) using
openSync(path, 'wx') for atomic exclusive create. Add listSessionKeys() to read
claim dir, syncSessionFileFromClaims() to derive the txt snapshot, and
removeSessionClaimDir() for cleanup. Claim files live in
<tmpdir>/vercel-plugin-<sessionId>-seen-skills.d/<skill-name>.
2. In hooks/src/patterns.mts, add mergeSeenSkillStates(...values) to union env var,
session file, and claim dir state. Add serializeSeenSkills(set) helper.
3. In hooks/src/pretooluse-skill-inject.mts, load merged state from env+file+claims.
Before injecting each skill, call tryClaimSessionKey — first process wins, others
get EEXIST and skip. Use same claim path for once-only keys (agent-browser warning,
vercel-env-help). Pass sessionId through InjectOptions.
4. In hooks/src/user-prompt-submit-skill-inject.mts, preserve sessionId from parsed
input, load merged seen state, pass sessionId to injection flow so it uses the
shared claim backend. Skills injected via promptSignals now visible to PreToolUse.
5. In hooks/src/session-end-cleanup.mts, add rmSync deletion of claim directories.
6. Update CLAUDE.md dedup contract to document atomic claim mechanism.
7. Bump .plugin/plugin.json to 0.6.0, rebuild.
UserPromptSubmit previously deduped only against VERCEL_PLUGIN_SEEN_SKILLS,
so prompt-signal injections were invisible to PreToolUse when session-file/claim
state diverged. This caused duplicate skill injection across hooks.
This change merges seen-skill state from env + session file + atomic claim keys,
passes sessionId through injectSkills, and syncs injected skills back into claim
state after injection so both hooks observe one dedup source of truth.
Verified: bun test hooks/user-prompt-submit-skill-inject.test.ts (2 pass)
Verified: bun run build:hooks (pass)
Swarm-Agent: codex-userprompt-dedup
PreToolUse dedup now merges env, legacy file, and per-key claim state so
parallel hooks converge on one seen-skills view.
Skill injection now performs per-skill atomic claims before appending content,
skipping skills already claimed by concurrent hooks and syncing env/file from
claim keys. Once-only warning/help keys now use the same claim path when a
session id is available, with previous in-process append fallback preserved
when no session id exists.
Verified: bun run build:hooks
Verified: bun test tests/pretooluse-skill-inject.test.ts
Swarm-Agent: codex-pretool-claims
SessionEnd cleanup previously removed only the legacy temp files.
This adds best-effort removal of the atomic claim directories for seen-skills and validated-files to avoid stale per-session artifacts.
Verified: bun run build:hooks
How to test: invoke hooks/src/session-end-cleanup.mts with a session_id and confirm *.txt and *.d temp artifacts are removed from tmpdir.
Swarm-Agent: codex-cleanup-claims
PreToolUse and PostToolUse dedup state was previously process-local, which broke across hook subprocess invocations.\nThis change adds session-scoped temp-file persistence and threads session_id through the relevant flows.\n\nPreToolUse now falls back to per-session seen-skills file state and writes back on every appendSeenSkill update.\nPostToolUse now checks persisted validated-files state and writes updates after marking files validated.\n\nVerified: bun run build:hooks\nVerified: bun test tests/pretooluse-skill-inject.test.ts tests/posttooluse-validate.test.ts\nSwarm-Agent: codex-dedup-core
The 0.5.4 release added session-scoped temp files for dedup persistence, but this
was wrong — CLAUDE_ENV_FILE env vars ARE propagated to hook subprocesses by Claude
Code. The temp file approach littered tmpdir with hundreds of small files.
Revert to the original env-var-only mechanism:
1. Remove readSessionFile/writeSessionFile/dedupFilePath from hooks/src/hook-env.mts
2. Remove all writeSessionFile calls from pretooluse-skill-inject.mts — revert to
pure process.env.VERCEL_PLUGIN_SEEN_SKILLS = appendSeenSkill(...) pattern
3. Remove sessionId from InjectOptions and the injectSkills call site
4. Remove sessionId from posttooluse-validate.mts ParsedInput — revert
isAlreadyValidated/markValidated to pure env-var signatures
5. Revert all test expectations back to "env-var" and "memory-only" strategies
6. Restore CLAUDE.md dedup contract to env-var-only documentation
Skill dedup is completely broken because CLAUDE_ENV_FILE vars are only available to Bash
tool commands, not hook subprocesses. Each PreToolUse invocation starts a fresh Node.js
process that never sees VERCEL_PLUGIN_SEEN_SKILLS.
To fix this:
1. In hooks/src/hook-env.mts, add readSessionFile(sessionId, kind) and
writeSessionFile(sessionId, kind, value) helpers that read/write
/tmp/vercel-plugin-<sessionId>-<kind>.txt for persistent dedup state.
2. In hooks/src/pretooluse-skill-inject.mts, read seen skills from the session file
at startup using readSessionFile(sessionId, "seen-skills"). Add a persistSeen()
closure inside injectSkills() that calls both appendSeenSkill and writeSessionFile.
Replace all process.env.VERCEL_PLUGIN_SEEN_SKILLS = appendSeenSkill(...) calls with
persistSeen() or inline writeSessionFile calls. Add "file" as the primary dedup
strategy when session_id is present, falling back to "env-var" then "memory-only".
Pass sessionId through InjectOptions to injectSkills().
3. In hooks/src/posttooluse-validate.mts, add sessionId to ParsedInput and extract it
from input.session_id in parseInput(). Pass sessionId to isAlreadyValidated() and
markValidated(), which should read/write via readSessionFile/writeSessionFile for
the "validated-files" kind.
4. Update tests: pretooluse-skill-inject.test.ts — rename "no env var" test to expect
file-based dedup persistence, update strategy assertions from "env-var" to "file",
use omitSessionId for memory-only test. subagent-fresh-env.test.ts — use a fresh
session ID for subagent calls, update strategy expectations to "file".
session-timeline-subagent.test.ts — add sessionId option to runHookEnv, use a
different session ID for the subagent call.
5. Update CLAUDE.md dedup contract section to document file-based mechanism.
6. Bump .plugin/plugin.json version to 0.5.4, run bun run build.
When hooks run as child processes, process.cwd() can point at the plugin root\ninstead of the user project.\n\nThis change threads cwd from PreToolUse stdin JSON through parseInput()\ninto appendAuditLog(), and uses it as fallback when CLAUDE_PROJECT_ROOT\nis not set.\n\nVerified: bun run build:hooks\nVerified: bun test tests/pretooluse-skill-inject.test.ts\nSwarm-Agent: codex-p0-audit-path
Add a Bash-triggered one-shot help block for vercel env add/update/pull.
This prevents repeated reminders under dedup while still allowing explicit repeats when dedup is off.
Verified: bun run build:hooks
Verified: bun test tests/subagent-fresh-env.test.ts
Swarm-Agent: codex-vercel-env-help
Skill injections now append JSONL audit records for post-run debugging and traceability.
Audit path resolves from VERCEL_PLUGIN_AUDIT_LOG_FILE with an opt-out mode and a project-local default.
Verified: bun run build:hooks
Verified: bun test tests/subagent-fresh-env.test.ts
Swarm-Agent: codex-audit-log
Injecting a greenfield-specific section steers fresh directories away from planning-only behavior and toward immediate execution with tool calls.\n\nVerified: bun run build:hooks\nVerified: output now joins vercel.md plus optional greenfield block with double newlines\nSwarm-Agent: codex-greenfield-nudge
Greenfield projects were exiting before writing likely skills and setup mode, which caused cold-start misses for subagents.\n\nThis change removes the early exit, applies explicit greenfield defaults, preserves the greenfield env marker, and writes likely skills/setup mode through the shared env-write path.\n\nVerified: bun run build:hooks\nVerified: bun test tests/subagent-fresh-env.test.ts\nSwarm-Agent: codex-greenfield-profiler
melkeydev