@spardutti/claude-skills 2.26.0 → 2.28.0

package/README.md

@@ -133,7 +133,7 @@ Portable slash commands installed to `.claude/commands/`. Some orchestrate paral
 |---------|--------------|
 | `/ship` | Unified delivery pipeline — commit → gate → PR → merge → release. The gate is the one enforcement moment: it checks the diff's file lengths, audits it against the skills installed in the project, and mutation-tests the changed lines to prove the tests would catch a break — **fixing what it finds** rather than handing you a list. It runs before the **PR**, not before every commit: its scope is the whole branch, so gating each commit re-mutated every file the branch had ever touched. `--force` skips it. No argument steps through interactively; `/ship pr` runs through PR creation; `/ship release` runs the full pipeline |
 | `/discover` | Find the right problem before deciding what to build — diverges first: generates competing framings through blind subagents under forced constraints, stress-tests the winner with a blind critic, and refuses to converge until every open question is answered or deferred, then drafts scope, non-goals, edge cases and success criteria for you to correct. Run before `/plan-feature` |
-| `/plan-feature` | Integration-first feature planning — 3 parallel subagents scan for reusable code, patterns, and touch points before producing a short plan |
+| `/plan-feature` | Integration-first feature planning, then building — 3 parallel subagents scan for reusable code, patterns and touch points, and the plan lands with a contract and a per-worker file split; on your go it dispatches parallel implementation workers that each load their own skills and report back as one diff |
 | `/refactor` | Detect size / complexity / duplication / coupling issues via 4 parallel subagents, then refactor |
 | `/deep-review` | Multi-agent deep code review — 5 parallel subagents catch guard bypasses, lost async state, wrong-table queries, dead references, protocol violations |
 | `/test-review` | Write-then-verify test review — scopes to the diff, runs red-green + mutation gates, then an isolated read-only subagent proves each test would catch a regression instead of rubber-stamping it |

package/lib/setup-hook.mjs

@@ -4,7 +4,10 @@ import { spawn } from "node:child_process";
 import { homedir } from "node:os";
 
 // PreToolUse gate on Write|Edit|MultiEdit. Blocks the tool call unless
-// a per-session marker file exists at /tmp/claude-skill-gate-<SESSION_ID>.
+// a marker file exists at /tmp/claude-skill-gate-<KEY>, where KEY is the
+// subagent's agent_id when the call comes from one, and the session_id
+// otherwise — a subagent reports the parent's session_id, so keying on that
+// alone let a worker inherit the main thread's cleared gate.
 // Per-session (not per-prompt) so simple confirmations like "yes" don't
 // re-lock the gate after evaluation has already happened in the session.
 // The PostToolUse hook on Skill creates the marker automatically; for
@@ -30,10 +33,25 @@ if [ -z "$SESSION_ID" ]; then
   exit 0
 fi
 
-# The session marker is checked at the very bottom now, not here. A skill the
-# edited file's own stack demands is not something an already-cleared gate
-# excuses, so the required-skill scan below runs first.
-MARKER="/tmp/claude-skill-gate-$SESSION_ID"
+# A subagent reports the PARENT's session_id — measured, not assumed: a probe
+# hook dumped its own stdin from the main thread and from inside a subagent and
+# the two ids were identical. So a worker spawned to implement part of a plan
+# inherited the main thread's cleared markers and edited with none of the
+# skills loaded in its own context.
+#
+# agent_id is present only inside a subagent, and holds steady across that
+# subagent's turns, so keying on it gives each worker its own namespace and
+# costs it one Skill call per skill, not one per turn.
+AGENT_ID=$(printf '%s' "$INPUT" | grep -o '"agent_id":"[^"]*"' | head -1 | sed 's/"agent_id":"//; s/"$//')
+KEY="$SESSION_ID"
+if [ -n "$AGENT_ID" ]; then
+  KEY=$(printf '%s' "$AGENT_ID" | tr -cd 'A-Za-z0-9_-')
+fi
+
+# The marker is checked at the very bottom now, not here. A skill the edited
+# file's own stack demands is not something an already-cleared gate excuses,
+# so the required-skill scan below runs first.
+MARKER="/tmp/claude-skill-gate-$KEY"
 
 # Write|Edit|MultiEdit is not the only way to change a file. A session that edits
 # through \`python3 - <<'PY'\` in Bash walked past this gate entirely — twelve
@@ -57,7 +75,9 @@ if [ "$TOOL" != "Bash" ]; then
   TARGET=$(printf '%s' "$INPUT" | grep -o '"file_path":[[:space:]]*"[^"]*"' | head -1 | sed 's/.*:[[:space:]]*"//; s/"$//')
   case "$TARGET" in
     # The settings file that configures the escape hatch cannot sit behind the
-    # gate, or a denied ack has no way to be un-denied.
+    # gate, or a denied ack has no way to be un-denied. The bare relative form
+    # matters: a skill claiming **/* gated it, and nothing could re-open it.
+    .claude/settings.json|.claude/settings.local.json) exit 0 ;;
     */.claude/settings.json|*/.claude/settings.local.json) exit 0 ;;
     *.*) printf '%s' "$TARGET" | grep -qiE "\.($PROSE_EXT)$" && exit 0 ;;
   esac
@@ -90,8 +110,9 @@ if [ "$TOOL" = "Bash" ]; then
     *"<<"*|*python*" -c"*|*node*" -e"*|*perl*" -e"*|*ruby*" -e"*) WRITES=1 ;;
   esac
   [ -z "$WRITES" ] && exit 0
-  # A Bash write names its files in the command itself.
-  TARGETS=$(printf '%s' "$CMD" | grep -oiE "[A-Za-z0-9_./-]+\.($CODE_EXT)" 2>/dev/null)
+  # A Bash write names its files in the command itself. Dockerfile and
+  # .dockerignore carry no extension, so they are matched by name.
+  TARGETS=$(printf '%s' "$CMD" | grep -oiE "[A-Za-z0-9_./-]+\.($CODE_EXT)|[A-Za-z0-9_./-]*(Dockerfile[A-Za-z0-9_.-]*|\.dockerignore)" 2>/dev/null)
 fi
 
 # --- mandatory skills -------------------------------------------------------
@@ -106,18 +127,26 @@ fi
 # without both fields keep the old behaviour, so this tightens nothing that was
 # not deliberately declared.
 MISSING=""
+MANIFESTS=""
 if [ -n "$TARGETS" ]; then
   MANIFESTS=$(find "$PROJECT_DIR" -maxdepth 4 \\( -name node_modules -o -name .git -o -name .venv -o -name dist \\) -prune -o \\( -name package.json -o -name pyproject.toml -o -name requirements.txt \\) -print 2>/dev/null)
 fi
-if [ -n "$TARGETS" ] && [ -n "$MANIFESTS" ]; then
+if [ -n "$TARGETS" ]; then
   for SKILL_FILE in $(find "$PROJECT_DIR" -path '*/.claude/skills/*/SKILL.md' 2>/dev/null); do
-    # paths: must be quoted in YAML — a scalar opening with * is an alias.
+    # Read gate-paths from under metadata:, never a bare paths: key. A bare
+    # paths: made Claude Code drop the skill from its registry outright —
+    # every Skill(name) call returned "Unknown skill" and, with no SKIP for a
+    # mandatory skill, the session could not edit code at all. metadata is
+    # documented as free-form and ignored by Claude Code, and the docs say in
+    # so many words not to reuse paths as a key inside it.
+    #
+    # The value must be quoted in YAML either way: a scalar opening with * is
+    # an alias indicator.
     UNQUOTE='s/^["'"'"']//; s/["'"'"']$//'
-    SPATHS=$(sed -n 's/^paths:[[:space:]]*//p' "$SKILL_FILE" | head -1 | sed "$UNQUOTE")
+    SPATHS=$(sed -n 's/^[[:space:]]*gate-paths:[[:space:]]*//p' "$SKILL_FILE" | head -1 | sed "$UNQUOTE")
     STRACKS=$(sed -n 's/^tracks:[[:space:]]*//p' "$SKILL_FILE" | head -1 | sed "$UNQUOTE")
     SNAME=$(sed -n 's/^name:[[:space:]]*//p' "$SKILL_FILE" | head -1 | sed "$UNQUOTE")
     [ -z "$SPATHS" ] && continue
-    [ -z "$STRACKS" ] && continue
     [ -z "$SNAME" ] && continue
 
     HIT=""
@@ -134,9 +163,14 @@ if [ -n "$TARGETS" ] && [ -n "$MANIFESTS" ]; then
 
     # A .tsx file is not proof of React — it could be Astro, Solid or Preact.
     # The packages the skill tracks are the proof, so the manifests decide.
+    #
+    # Some skills need no such proof: a .sql file is SQL and a Dockerfile is a
+    # Dockerfile, and no package declares either. A skill that names paths and
+    # no tracks is taken at its word.
     PY=""
     case "$STRACKS" in *pypi*) PY=1 ;; esac
     DEP=""
+    [ -z "$STRACKS" ] && DEP=1
     for P in $(printf '%s' "$STRACKS" | tr ',' ' '); do
       case "$P" in *@*) ;; *) continue ;; esac
       PKG=$(printf '%s' "$P" | sed 's/@[^@]*$//')
@@ -152,7 +186,7 @@ if [ -n "$TARGETS" ] && [ -n "$MANIFESTS" ]; then
     [ -z "$DEP" ] && continue
 
     SAFE=$(printf '%s' "$SNAME" | tr -cd 'A-Za-z0-9_-')
-    [ -f "/tmp/claude-skill-loaded-$SESSION_ID-$SAFE" ] && continue
+    [ -f "/tmp/claude-skill-loaded-$KEY-$SAFE" ] && continue
     case " $MISSING " in *" $SNAME "*) ;; *) MISSING="$MISSING $SNAME" ;; esac
   done
 fi
@@ -172,7 +206,7 @@ fi
 
 
 cat <<EOF
-{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"BLOCKED: skill evaluation required before file edits in this session.\\n\\nStep 1 — evaluate every available skill as ACTIVATE or SKIP with a one-line reason.\\n\\nStep 2 — you MUST take EXACTLY ONE of these tool actions to clear the gate. Listing skills in text is NOT enough; retrying the edit without doing one of these will be denied again:\\n  (a) If any skill is ACTIVATE → call Skill(name) for it. This auto-clears the gate.\\n  (b) If ALL skills are SKIP → run this Bash tool call: touch /tmp/claude-skill-gate-$SESSION_ID\\n\\nStep 3 — only after Step 2 completes, retry the file edit."}}
+{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"BLOCKED: skill evaluation required before file edits in this session.\\n\\nStep 1 — evaluate every available skill as ACTIVATE or SKIP with a one-line reason.\\n\\nStep 2 — you MUST take EXACTLY ONE of these tool actions to clear the gate. Listing skills in text is NOT enough; retrying the edit without doing one of these will be denied again:\\n  (a) If any skill is ACTIVATE → call Skill(name) for it. This auto-clears the gate.\\n  (b) If ALL skills are SKIP → run this Bash tool call: touch /tmp/claude-skill-gate-$KEY\\n\\nStep 3 — only after Step 2 completes, retry the file edit."}}
 EOF
 exit 0
 `;
@@ -191,14 +225,24 @@ if [ -z "$SESSION_ID" ]; then
   exit 0
 fi
 
-touch "/tmp/claude-skill-gate-$SESSION_ID"
+# Keyed exactly as the gate keys it. A subagent carries the parent's
+# session_id, so both scripts fall back to agent_id when one is present — and
+# they must agree, or a loaded skill writes a marker the gate never looks for
+# and every edit is denied forever.
+AGENT_ID=$(printf '%s' "$INPUT" | grep -o '"agent_id":"[^"]*"' | head -1 | sed 's/"agent_id":"//; s/"$//')
+KEY="$SESSION_ID"
+if [ -n "$AGENT_ID" ]; then
+  KEY=$(printf '%s' "$AGENT_ID" | tr -cd 'A-Za-z0-9_-')
+fi
+
+touch "/tmp/claude-skill-gate-$KEY"
 
 SKILL_NAME=$(printf '%s' "$INPUT" | grep -o '"skill":"[^"]*"' | head -1 | sed 's/"skill":"//; s/"$//')
 if [ -n "$SKILL_NAME" ]; then
   # Sanitize: only allow [A-Za-z0-9_-] in the marker filename.
   SAFE_NAME=$(printf '%s' "$SKILL_NAME" | tr -cd 'A-Za-z0-9_-')
   if [ -n "$SAFE_NAME" ]; then
-    touch "/tmp/claude-skill-loaded-$SESSION_ID-$SAFE_NAME"
+    touch "/tmp/claude-skill-loaded-$KEY-$SAFE_NAME"
   fi
 fi
 
@@ -222,8 +266,16 @@ if [ -z "$SESSION_ID" ]; then
   exit 0
 fi
 
-# Defer to the loading gate until it's been satisfied this session.
-if [ ! -f "/tmp/claude-skill-gate-$SESSION_ID" ]; then
+# Keyed exactly as the loading gate and the automark key it — see those two.
+# A subagent carries the parent's session_id, so all three must agree.
+AGENT_ID=$(printf '%s' "$INPUT" | grep -o '"agent_id":"[^"]*"' | head -1 | sed 's/"agent_id":"//; s/"$//')
+KEY="$SESSION_ID"
+if [ -n "$AGENT_ID" ]; then
+  KEY=$(printf '%s' "$AGENT_ID" | tr -cd 'A-Za-z0-9_-')
+fi
+
+# Defer to the loading gate until it's been satisfied for this key.
+if [ ! -f "/tmp/claude-skill-gate-$KEY" ]; then
   exit 0
 fi
 
@@ -274,10 +326,10 @@ fi
 
 # Collect every loaded-but-unacked skill so a single ack clears them all.
 UNACKED=""
-for marker in /tmp/claude-skill-loaded-$SESSION_ID-*; do
+for marker in /tmp/claude-skill-loaded-$KEY-*; do
   [ ! -f "$marker" ] && continue
-  skill_name="\${marker##/tmp/claude-skill-loaded-$SESSION_ID-}"
-  if [ ! -f "/tmp/claude-skill-acked-$SESSION_ID-$skill_name" ]; then
+  skill_name="\${marker##/tmp/claude-skill-loaded-$KEY-}"
+  if [ ! -f "/tmp/claude-skill-acked-$KEY-$skill_name" ]; then
     UNACKED="$UNACKED $skill_name"
   fi
 done
@@ -293,7 +345,7 @@ ACK_CMD="touch"
 NAMES=""
 RULES_BLOCKS=""
 for skill in $UNACKED; do
-  ACK_CMD="$ACK_CMD /tmp/claude-skill-acked-$SESSION_ID-$skill"
+  ACK_CMD="$ACK_CMD /tmp/claude-skill-acked-$KEY-$skill"
   NAMES="$NAMES, '$skill'"
   SKILL_MD="$PROJECT_DIR/.claude/skills/$skill/SKILL.md"
   RULES=""

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spardutti/claude-skills",
-  "version": "2.26.0",
+  "version": "2.28.0",
   "description": "Guardrails for Claude Code — best-practice skills, planning commands, and delivery gates.",
   "type": "module",
   "repository": {