Deliver capability instructions via SessionStart hook, retire CLAUDE.md seeding #190
Loading…
Reference in a new issue
No description provided.
Delete branch "fix/nexus-plugin"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Summary
Agents were intermittently never calling
notify-preview/notify-artifact, because those commands lived only in thenexusplugin'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. TheCLAUDE.mdbreadcrumb ahead of the skill only pointed at it ("read thenexusskill"), without stating the commands, so it didn't fix the gap.SessionStarthook (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 installedclaude2.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).nexusskill 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, sinceSessionStarthook context reaches only the top-level conversation, not a dispatched subagent (measured).agent-instructionsbackend subsystem: the module that seeded a default into~/.claude/CLAUDE.mdon 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 toCLAUDE.md— it's fully operator-owned, editable only via the pre-existing Config Explorer like any other file under~/.claude..gitattributesregression (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 errorspnpm lint— cleanpnpm test— 2216/2216 passingpnpm build— clean production buildworker/nexus-context.test.sh(new POSIX round-trip test) — 7/7, auto-discovered by the existing shell-test harnesshooks-parity.test.tsextended to cover both the report and context handler contracts, mutation-testedclaudebinary (see design doc's Task 9 section) — hook registration, stdout-injection, and a before/after reproduction of the original bugAgents 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/.624811ca64c802a89cb7