Deliver capability instructions via SessionStart hook, retire CLAUDE.md seeding #190

Merged
lz merged 1 commit from fix/nexus-plugin into main 2026-09-21 23:43:02 +02:00
Owner

Summary

Agents were intermittently never calling notify-preview/notify-artifact, because those commands lived only in the nexus plugin's skill, and skill auto-invocation is conditional on the model's own judgment — documented by Anthropic as unreliable, and measured in the wild at 0% recall for custom-skill triggering in headless mode. The CLAUDE.md breadcrumb ahead of the skill only pointed at it ("read the nexus skill"), without stating the commands, so it didn't fix the gap.

  • Adds a new SessionStart hook (nexus-context.sh) that prints the must-know commands directly to stdout, which Claude Code injects into context unconditionally — no dependency on the model choosing to read a skill. Verified against the installed claude 2.1.278 binary: debug-log proof of the hook firing and its exact text being captured as context, plus a live before/after reproduction of the original bug from a fresh directory (no plugin: model hedges and won't guess the command; with the plugin: confident, correct, one-line answer, zero tool calls).
  • Trims the nexus skill to hold only genuinely occasional reference material (per-framework dev-server config, artifact re-registration nuances, worktree mechanics, dind stacks) — restored to be self-contained for Task-tool subagents, since SessionStart hook context reaches only the top-level conversation, not a dispatched subagent (measured).
  • Deletes the entire agent-instructions backend subsystem: the module that seeded a default into ~/.claude/CLAUDE.md on first boot, hashed it, detected drift, and served read/write/reset over an API, plus its settings tab. Nexus now has no code path that ever writes to CLAUDE.md — it's fully operator-owned, editable only via the pre-existing Config Explorer like any other file under ~/.claude.
  • Updates AGENTS.md facts #18, #19, #26 to match; fixes a stale Dockerfile comment and a genuine .gitattributes regression (deleting the file removed the only line-ending pin that existed anywhere in the repo, risking CRLF shell scripts baked into the Linux Docker image on a Windows checkout) caught during review.

Design and implementation plan under docs/superpowers/.

Related follow-ups filed separately, out of scope here: #187 (tmux focus-events investigation), #189 (a test-list existence guard).

Test plan

  • pnpm typecheck — 0 errors
  • pnpm lint — clean
  • pnpm test — 2216/2216 passing
  • pnpm build — clean production build
  • worker/nexus-context.test.sh (new POSIX round-trip test) — 7/7, auto-discovered by the existing shell-test harness
  • hooks-parity.test.ts extended to cover both the report and context handler contracts, mutation-tested
  • Live verification against the installed claude binary (see design doc's Task 9 section) — hook registration, stdout-injection, and a before/after reproduction of the original bug
  • Full whole-branch review pass, including a check for subagent-context reach that surfaced and fixed a real gap
## Summary Agents were intermittently never calling `notify-preview`/`notify-artifact`, because those commands lived only in the `nexus` plugin's skill, and skill auto-invocation is conditional on the model's own judgment — documented by Anthropic as unreliable, and measured in the wild at 0% recall for custom-skill triggering in headless mode. The `CLAUDE.md` breadcrumb ahead of the skill only pointed at it ("read the `nexus` skill"), without stating the commands, so it didn't fix the gap. - Adds a new `SessionStart` hook (`nexus-context.sh`) that prints the must-know commands directly to stdout, which Claude Code injects into context unconditionally — no dependency on the model choosing to read a skill. Verified against the installed `claude` 2.1.278 binary: debug-log proof of the hook firing and its exact text being captured as context, plus a live before/after reproduction of the original bug from a fresh directory (no plugin: model hedges and won't guess the command; with the plugin: confident, correct, one-line answer, zero tool calls). - Trims the `nexus` skill to hold only genuinely occasional reference material (per-framework dev-server config, artifact re-registration nuances, worktree mechanics, dind stacks) — restored to be self-contained for Task-tool subagents, since `SessionStart` hook context reaches only the top-level conversation, not a dispatched subagent (measured). - Deletes the entire `agent-instructions` backend subsystem: the module that seeded a default into `~/.claude/CLAUDE.md` on first boot, hashed it, detected drift, and served read/write/reset over an API, plus its settings tab. Nexus now has no code path that ever writes to `CLAUDE.md` — it's fully operator-owned, editable only via the pre-existing Config Explorer like any other file under `~/.claude`. - Updates AGENTS.md facts #18, #19, #26 to match; fixes a stale Dockerfile comment and a genuine `.gitattributes` regression (deleting the file removed the only line-ending pin that existed anywhere in the repo, risking CRLF shell scripts baked into the Linux Docker image on a Windows checkout) caught during review. Design and implementation plan under `docs/superpowers/`. Related follow-ups filed separately, out of scope here: #187 (tmux focus-events investigation), #189 (a test-list existence guard). ## Test plan - [x] `pnpm typecheck` — 0 errors - [x] `pnpm lint` — clean - [x] `pnpm test` — 2216/2216 passing - [x] `pnpm build` — clean production build - [x] `worker/nexus-context.test.sh` (new POSIX round-trip test) — 7/7, auto-discovered by the existing shell-test harness - [x] `hooks-parity.test.ts` extended to cover both the report and context handler contracts, mutation-tested - [x] Live verification against the installed `claude` binary (see design doc's Task 9 section) — hook registration, stdout-injection, and a before/after reproduction of the original bug - [x] Full whole-branch review pass, including a check for subagent-context reach that surfaced and fixed a real gap
feat(nexus-plugin): deliver capability instructions via SessionStart hook, retire CLAUDE.md seeding
Some checks failed
ci / nexus (pull_request) Successful in 9m22s
ci / images (pull_request) Has been cancelled
624811ca64
Agents were intermittently never calling notify-preview/notify-artifact,
because those commands lived only in the nexus plugin's skill, and skill
auto-invocation is conditional on the model's own judgment — documented by
Anthropic as unreliable, and measured in the wild at 0% recall for
custom-skill triggering in headless mode. The CLAUDE.md breadcrumb that used
to sit ahead of the skill only pointed at it ("read the nexus skill"),
without stating the commands, so it didn't fix the gap.

- Add a new SessionStart hook (nexus-context.sh) that prints the must-know
  commands directly to stdout, which Claude Code injects into context
  unconditionally — no dependency on the model choosing to read a skill.
  Verified against the installed claude 2.1.278 binary: debug-log proof of
  the hook firing and its exact text being captured as context, plus a live
  before/after reproduction of the original bug from a fresh directory
  (no plugin: model hedges and won't guess the command; with the plugin:
  confident, correct, one-line answer, zero tool calls).
- Trim the nexus skill to hold only genuinely occasional reference material
  (per-framework dev-server config, artifact re-registration nuances,
  worktree mechanics, dind stacks) — restored to be self-contained for
  Task-tool subagents, since SessionStart hook context reaches only the
  top-level conversation, not a dispatched subagent (measured).
- Delete the entire agent-instructions backend subsystem: the module that
  seeded a default into ~/.claude/CLAUDE.md on first boot, hashed it,
  detected drift, and served read/write/reset over an API, plus its
  settings tab. Nexus now has no code path that ever writes to CLAUDE.md —
  it's fully operator-owned, editable only via the pre-existing Config
  Explorer like any other file under ~/.claude.
- Update AGENTS.md facts #18, #19, #26 to match; fix a stale Dockerfile
  comment and a genuine .gitattributes regression (deleting the file
  removed the only line-ending pin that existed anywhere in the repo,
  risking CRLF shell scripts baked into the Linux Docker image on a
  Windows checkout) caught during review.

Design and implementation plan under docs/superpowers/.
lz force-pushed fix/nexus-plugin from 624811ca64
Some checks failed
ci / nexus (pull_request) Successful in 9m22s
ci / images (pull_request) Has been cancelled
to c802a89cb7
Some checks failed
ci / nexus (pull_request) Has been cancelled
ci / images (pull_request) Has been cancelled
pr-image-cleanup / delete-pr-images (pull_request) Successful in 34s
ci / images (push) Has been cancelled
ci / nexus (push) Has been cancelled
2026-09-21 23:32:26 +02:00
Compare
lz merged commit c802a89cb7 into main 2026-09-21 23:43:02 +02:00
lz deleted branch fix/nexus-plugin 2026-09-21 23:43:03 +02:00
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
lz/agent-nexus!190
No description provided.