@oneie/claude 0.3.0 → 0.3.1

package/commands/skill-create.md

@@ -0,0 +1,100 @@
+# /skill-create — crystallise a cycle's learnings into a reusable skill
+
+Run after a `/do` cycle closes (or any meaningful session). Reads the recent git
+diff and the last `learnings.md` entry, then drafts a `SKILL.md` under
+`.claude/skills/<slug>/` — so the pattern compounds instead of evaporating.
+
+---
+
+## When to invoke
+
+- After `/do` closes a cycle and `learnings.md` has a new entry
+- When you notice a pattern being repeated across sessions
+- Explicitly: `/skill-create [slug]`
+
+If `[slug]` is omitted, derive it from the most recent `learnings.md` entry
+(the slug of the last `/do` cycle).
+
+---
+
+## What it does
+
+**Step 1 — Gather raw material (zero LLM)**
+
+```bash
+# Last learnings entry
+tail -5 plans/learnings.md
+
+# Recent cycle diff (what actually changed)
+git diff HEAD~1 HEAD --stat
+git diff HEAD~1 HEAD -- $(git diff HEAD~1 HEAD --name-only | grep -v 'plans/\|text/' | head -20)
+```
+
+**Step 2 — Extract the pattern (Haiku · low)**
+
+From the diff + learnings entry, identify:
+- What recurring problem this cycle solved
+- The specific shape of the solution (code pattern, file layout, command sequence)
+- When it applies (trigger condition)
+- When it doesn't (anti-patterns / exclusions)
+
+Ignore one-off specifics (feature names, slugs). Keep the reusable skeleton.
+
+**Step 3 — Write `.claude/skills/<slug>/SKILL.md`**
+
+Use this template:
+
+```markdown
+# <title> skill
+
+<one-sentence description — what this skill does for the model>
+
+## When to use
+<trigger phrase or condition that should invoke this skill>
+
+## Pattern
+<the reusable shape — code snippet, command, or process>
+
+## Don't
+- <anti-pattern 1>
+- <anti-pattern 2>
+
+## Example
+<minimal concrete example>
+```
+
+**Step 4 — Wire it (if applicable)**
+
+- If the skill has a natural trigger phrase, append a row to the skills table in
+  `.claude/CLAUDE.md` so it auto-loads.
+- If it extends an existing skill, note the relation.
+
+**Step 5 — Close**
+
+Emit `signal("learning:harden", 1, "skill=<slug>")` and append one line to
+`plans/learnings.md`:
+
+```
+- YYYY-MM-DD · skill:<slug> · crystallised from <source-slug> · source=skill-create
+```
+
+---
+
+## Rules
+
+- **Extract, don't invent.** The pattern must be in the diff or learnings entry — no
+  generalising beyond what the cycle actually did.
+- **One skill = one pattern.** If the cycle contains two independent patterns, create
+  two skills.
+- **Lean.** A skill that fits in 30 lines is more likely to be read than one that
+  doesn't. Cut examples to the minimum that makes the pattern clear.
+- **No cycle-specific names.** Slug and title describe the pattern, not the feature
+  that spawned it (`worktree-isolation`, not `do-auto-fix`).
+
+---
+
+## Close
+
+After writing the skill file: `[ ] skill-create:<slug> done` appended to
+`plans/learnings.md`, signal emitted, session stop-reflect will pick it up as
+a new primitive on the next session start.

package/hooks/hooks.json

@@ -1,9 +1,35 @@
 {
+  "PreToolUse": [
+    {
+      "matcher": "Edit|Write|MultiEdit",
+      "hooks": [
+        {
+          "id": "hook:gate-guard",
+          "type": "command",
+          "command": "bash \"$CLAUDE_PLUGIN_ROOT/hooks/scripts/gate-guard.sh\"",
+          "timeout": 5000,
+          "blocking": true
+        }
+      ]
+    }
+  ],
   "PostToolUse": [
+    {
+      "matcher": "Read",
+      "hooks": [
+        {
+          "id": "hook:read-tracker",
+          "type": "command",
+          "command": "bash \"$CLAUDE_PLUGIN_ROOT/hooks/scripts/read-tracker.sh\"",
+          "timeout": 3000
+        }
+      ]
+    },
     {
       "matcher": "Write|Edit",
       "hooks": [
         {
+          "id": "hook:post-edit",
           "type": "command",
           "command": "bash \"$CLAUDE_PLUGIN_ROOT/hooks/scripts/post-edit-check.sh\"",
           "timeout": 15000
@@ -14,6 +40,7 @@
       "matcher": "Write|Edit|MultiEdit",
       "hooks": [
         {
+          "id": "hook:sync-todo-docs",
           "type": "command",
           "command": "bash \"$CLAUDE_PLUGIN_ROOT/hooks/scripts/sync-todo-docs.sh\"",
           "timeout": 5000
@@ -24,6 +51,7 @@
       "matcher": "Write|Edit|MultiEdit",
       "hooks": [
         {
+          "id": "hook:design-check",
           "type": "command",
           "command": "bash \"$CLAUDE_PLUGIN_ROOT/hooks/scripts/design-check.sh\"",
           "timeout": 5000,
@@ -35,6 +63,7 @@
       "matcher": "*",
       "hooks": [
         {
+          "id": "hook:tool-signal",
           "type": "command",
           "command": "bash \"$CLAUDE_PLUGIN_ROOT/hooks/scripts/tool-signal.sh\"",
           "timeout": 3000
@@ -47,6 +76,7 @@
       "matcher": "*",
       "hooks": [
         {
+          "id": "hook:task-complete",
           "type": "command",
           "command": "bash \"$CLAUDE_PLUGIN_ROOT/hooks/scripts/task-complete-verify.sh\"",
           "timeout": 120000,
@@ -60,12 +90,14 @@
       "matcher": "*",
       "hooks": [
         {
+          "id": "hook:session-end",
           "type": "command",
           "command": "bash \"$CLAUDE_PLUGIN_ROOT/hooks/scripts/session-end-verify.sh\"",
           "timeout": 30000,
           "blocking": false
         },
         {
+          "id": "hook:stop-reflect",
           "type": "command",
           "command": "bash \"$CLAUDE_PLUGIN_ROOT/hooks/scripts/stop-reflect.sh\"",
           "timeout": 10000,
@@ -79,6 +111,7 @@
       "matcher": "*",
       "hooks": [
         {
+          "id": "hook:session-start",
           "type": "command",
           "command": "bash \"$CLAUDE_PLUGIN_ROOT/hooks/scripts/session-start.sh\"",
           "timeout": 5000,

package/hooks/lib/hook.sh

@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+# Shared hook utilities. Source from any hook:
+#   source "$CLAUDE_PROJECT_DIR/.claude/hooks/lib/hook.sh"
+#
+# is_hook_disabled <id>  — returns 0 (skip) or 1 (run)
+# hook_session_key <json-arg>  — stable per-session key for temp files
+
+# ── Runtime toggles ──────────────────────────────────────────────────────────
+#
+# ECC_DISABLED_HOOKS=hook:gate-guard,hook:stop-reflect
+#   Comma-separated hook IDs to skip. Useful in CI or setup scripts.
+#
+# ECC_HOOK_PROFILE=minimal|standard (default: standard)
+#   minimal  — skips signal emissions, reflect, session-end, post-edit lint
+#   standard — all hooks active
+#
+# Per-hook disable: ECC_GATEGUARD=off  (alias for hook:gate-guard)
+
+is_hook_disabled() {
+  local id="$1"
+  local profile="${ECC_HOOK_PROFILE:-standard}"
+
+  # Explicit disable list (comma-separated)
+  if [[ -n "${ECC_DISABLED_HOOKS:-}" ]]; then
+    local IFS=','
+    for entry in $ECC_DISABLED_HOOKS; do
+      # trim whitespace
+      entry="${entry#"${entry%%[![:space:]]*}"}"
+      entry="${entry%"${entry##*[![:space:]]}"}"
+      [[ "$entry" == "$id" ]] && return 0
+    done
+  fi
+
+  # Profile-based skips
+  case "$profile" in
+    minimal)
+      case "$id" in
+        hook:tool-signal|hook:stop-reflect|hook:session-end|hook:post-edit) return 0 ;;
+      esac
+      ;;
+  esac
+
+  # Per-hook env aliases
+  case "$id" in
+    hook:gate-guard)
+      local v="${ECC_GATEGUARD:-}"
+      [[ "$v" =~ ^(0|off|false|disabled|disable)$ ]] && return 0
+      ;;
+  esac
+
+  return 1  # not disabled — run
+}
+
+# Derive a stable per-session key from the hook JSON payload ($1).
+# Uses session_id from JSON if present; falls back to a cksum of the
+# project dir so the key is consistent across hook invocations in one
+# session even when CLAUDE_SESSION_ID isn't set.
+hook_session_key() {
+  local payload="${1:-}"
+  local sid
+  sid=$(printf '%s' "$payload" | jq -r '.session_id // empty' 2>/dev/null)
+  if [[ -n "$sid" ]]; then
+    # Sanitise to filesystem-safe chars
+    printf '%s' "$sid" | tr -dc 'a-zA-Z0-9_-' | cut -c1-48
+    return
+  fi
+  # Fallback: hash of project dir
+  printf '%s' "${CLAUDE_PROJECT_DIR:-$(pwd)}" | cksum | awk '{print $1}'
+}

package/hooks/scripts/gate-guard.sh

@@ -0,0 +1,84 @@
+#!/usr/bin/env bash
+# GATE-GUARD — PreToolUse(Edit|Write|MultiEdit): require Read before edit.
+#
+# Blocks the first attempt to Edit/Write an existing file that hasn't been
+# Read in this session. Forces "understand before you change."
+#
+# Rules:
+#   - New files (Write creating a file that doesn't exist yet) → always allowed
+#   - Settings files (.claude/settings*.json) → always allowed
+#   - Subagent calls → allowed (parent session's reads cover the session)
+#   - File already in this session's read registry → allowed
+#   - Existing file NOT yet read → BLOCK with instructions
+#
+# Disable for the session: ECC_GATEGUARD=off
+# Disable one-off:         ECC_DISABLED_HOOKS=hook:gate-guard
+# Skip globally in CI:     add hook:gate-guard to ECC_DISABLED_HOOKS in env
+
+# shellcheck source=lib/hook.sh
+_HOOK_LIB="${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR/.claude}/hooks/lib"
+source "$_HOOK_LIB/hook.sh"
+is_hook_disabled "hook:gate-guard" && exit 0
+
+PAYLOAD="${1:-}"
+[[ -z "$PAYLOAD" ]] && exit 0
+
+TOOL=$(printf '%s' "$PAYLOAD" | jq -r '.tool_name // empty' 2>/dev/null)
+case "$TOOL" in Edit|Write|MultiEdit) ;; *) exit 0 ;; esac
+
+# Subagents: parent session already passed the gate for these files
+SUBAGENT=$(printf '%s' "$PAYLOAD" | jq -r '.parent_tool_use_id // .parentToolUseId // empty' 2>/dev/null)
+[[ -n "$SUBAGENT" ]] && exit 0
+
+SESSION_KEY=$(hook_session_key "$PAYLOAD")
+READS_FILE="/tmp/oneie-gate-reads-${SESSION_KEY}"
+
+_deny() {
+  # Claude Code PreToolUse block format
+  printf '%s' "$(jq -nc --arg msg "$1" \
+    '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":$msg}}')"
+  exit 0
+}
+
+_is_settings() {
+  [[ "$1" =~ \.claude/settings[^/]*\.json$ ]]
+}
+
+_was_read() {
+  local fp="$1"
+  [[ -f "$READS_FILE" ]] && grep -qF "$fp" "$READS_FILE" 2>/dev/null
+}
+
+_block_msg() {
+  local fp="$1" verb="$2"
+  printf '[Gate-Guard] Read %s before you %s it.\n\nUse the Read tool on this file first to prove you understand it, then retry.\n\nTo disable for this session: set ECC_GATEGUARD=off\nTo disable permanently:   add hook:gate-guard to ECC_DISABLED_HOOKS in your environment.' \
+    "$fp" "$verb"
+}
+
+check() {
+  local fp="$1" tool="$2"
+  [[ -z "$fp" ]] && return 0
+  _is_settings "$fp" && return 0
+  # New file being created — no prior read needed
+  [[ "$tool" == "Write" && ! -f "$fp" ]] && return 0
+  # Previously read this session — allowed
+  _was_read "$fp" && return 0
+  # Existing file not read → block
+  [[ -f "$fp" ]] && { _deny "$(_block_msg "$fp" "$(printf '%s' "$tool" | tr '[:upper:]' '[:lower:]')")"; }
+  return 0
+}
+
+case "$TOOL" in
+  Edit|Write)
+    FILE=$(printf '%s' "$PAYLOAD" | jq -r '.tool_input.file_path // empty' 2>/dev/null)
+    check "$FILE" "$TOOL"
+    ;;
+  MultiEdit)
+    while IFS= read -r fp; do
+      [[ -z "$fp" ]] && continue
+      check "$fp" "Edit"
+    done < <(printf '%s' "$PAYLOAD" | jq -r '.tool_input.edits[].file_path // empty' 2>/dev/null)
+    ;;
+esac
+
+exit 0

package/hooks/scripts/read-tracker.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+# READ-TRACKER — PostToolUse(Read): record file_path as read this session.
+#
+# Feeds gate-guard.sh: once a file appears in the reads registry,
+# Edit/Write on that file is allowed. Disable both with ECC_GATEGUARD=off
+# or ECC_DISABLED_HOOKS=hook:gate-guard.
+#
+# Non-blocking, always exits 0. Failure to write the registry is silent
+# (gate-guard falls back to allow on missing registry).
+
+# shellcheck source=lib/hook.sh
+_HOOK_LIB="${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR/.claude}/hooks/lib"
+source "$_HOOK_LIB/hook.sh"
+is_hook_disabled "hook:gate-guard" && exit 0
+
+PAYLOAD="${1:-}"
+[[ -z "$PAYLOAD" ]] && exit 0
+
+FILE=$(printf '%s' "$PAYLOAD" | jq -r '.tool_input.file_path // empty' 2>/dev/null)
+[[ -z "$FILE" ]] && exit 0
+
+SESSION_KEY=$(hook_session_key "$PAYLOAD")
+READS_FILE="/tmp/oneie-gate-reads-${SESSION_KEY}"
+
+# Append absolute path — idempotent (duplicates are fine, grep is fast)
+echo "$FILE" >> "$READS_FILE" 2>/dev/null || true
+exit 0

package/hooks/scripts/stop-reflect.sh

@@ -73,6 +73,18 @@ check_drift '^packages/sdk/src/'   'packages/sdk/CLAUDE.md'
 check_drift '^one\.ie/web/src/'    'one.ie/web/CLAUDE.md'
 check_drift '^api/src/'            'api/CLAUDE.md'
 
+# (4) Completed /do cycle → suggest /skill-create to crystallise the pattern.
+# Heuristic: learnings.md was touched AND W3 edited >=3 non-plan/non-text files.
+if echo "$CHANGED" | grep -qF 'plans/learnings.md'; then
+  CYCLE_FILES=$(echo "$CHANGED" | grep -vE '^plans/|^text/|^\.claude/' | wc -l | awk '{print $1}')
+  if [ "$CYCLE_FILES" -ge 3 ]; then
+    # Extract the cycle slug from the last learnings entry
+    CYCLE_SLUG=$(grep -oE 'cycle [0-9]+|· [a-z][a-z0-9-]+' plans/learnings.md 2>/dev/null | tail -1 | sed 's/^· //')
+    BUF+="- **skill-create** cycle closed with ${CYCLE_FILES} file(s) changed — run \`/skill-create ${CYCLE_SLUG}\` to crystallise the pattern as a reusable skill.\n"
+    PROPOSALS=$((PROPOSALS + 1))
+  fi
+fi
+
 # Only write the file if we found something worth reviewing
 if [ "$PROPOSALS" -gt 0 ]; then
   {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oneie/claude",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "ONE Claude Code plugin — /do lifecycle, W1-W4 BUILD engine, ONE substrate via MCP, signals, and rules",
   "files": [
     ".claude-plugin",
@@ -19,11 +19,27 @@
     "@oneie/cli": ">=0.2.0"
   },
   "peerDependenciesMeta": {
-    "@oneie/sdk": { "optional": true },
-    "@oneie/mcp": { "optional": true },
-    "@oneie/cli": { "optional": true }
+    "@oneie/sdk": {
+      "optional": true
+    },
+    "@oneie/mcp": {
+      "optional": true
+    },
+    "@oneie/cli": {
+      "optional": true
+    }
   },
-  "keywords": ["claude-code", "plugin", "do", "lifecycle", "mcp", "signals", "typedb", "agents", "one"],
+  "keywords": [
+    "claude-code",
+    "plugin",
+    "do",
+    "lifecycle",
+    "mcp",
+    "signals",
+    "typedb",
+    "agents",
+    "one"
+  ],
   "license": "SEE LICENSE IN https://one.ie/free-license",
   "repository": {
     "type": "git",