codeforge-dev 1.14.2 → 2.0.1

package/.devcontainer/plugins/devs-marketplace/plugins/prompt-snippets/skills/ps/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: ps
+description: Inject a behavioral prompt snippet by name.
+disable-model-invocation: true
+argument-hint: "[snippet-name]"
+---
+
+# /ps — Prompt Snippets
+
+Apply the prompt snippet matching `$ARGUMENTS` from the table below. Follow its instruction for the **remainder of this conversation** unless the user explicitly overrides it.
+
+If `$ARGUMENTS` does not match any snippet name, list all available snippets and ask the user to pick one.
+
+## Available Snippets
+
+| Snippet | Instruction |
+|---------|-------------|
+| `noaction` | Investigate and report only. Take no action — no edits, no commands, no file writes. |
+| `brief` | Be concise. Short answers, no filler, no preamble. Answer the question and stop. |
+| `plan` | Build a plan before taking any action. Do not implement until the plan is explicitly approved. |
+| `go` | Proceed without asking for confirmation. Use your best judgment on all decisions. |
+| `review` | Review and audit only. Report findings with specific file paths and line numbers. Do not modify anything. |
+| `ship` | Commit all staged changes, push to remote, and create a pull request. |
+| `deep` | Be thorough and comprehensive. Investigate in depth, consider edge cases, leave no stone unturned. |
+| `hold` | Complete the current task but do not commit, push, or publish. Await my review before any git operations. |
+| `recall` | Search past session history with `ccms --no-color --project "$(pwd)"` to find prior decisions, discussions, and context relevant to the current task. Summarize what you find before proceeding. |
+| `wait` | When done, stop. Do not suggest next steps, ask follow-up questions, or continue with related work. Await further instructions. |
+
+## Composing Snippets
+
+Multiple snippets can be applied in one invocation by separating names with spaces:
+
+```text
+/ps noaction brief
+```
+
+Apply all matching snippets. If instructions conflict, the **last snippet wins** for that specific behavior.

package/.devcontainer/plugins/devs-marketplace/plugins/protected-files-guard/README.md

@@ -10,7 +10,7 @@ Intercepts file operations and checks target paths against a set of protected pa
 
 | Category | Patterns | Reason |
 |----------|----------|--------|
-| Environment secrets | `.env`, `.env.*` | Contains secrets |
+| Environment secrets | `.env`, `.env.*` (except `.env.example`) | Contains secrets |
 | Git internals | `.git/` | Managed by git |
 | Lock files | `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, `Gemfile.lock`, `poetry.lock`, `Cargo.lock`, `composer.lock`, `uv.lock` | Must be modified via package manager |
 | Certificates & keys | `.pem`, `.key`, `.crt`, `.p12`, `.pfx` | Sensitive cryptographic material |
@@ -60,7 +60,7 @@ The Bash guard parses commands for write-indicating patterns and extracts the ta
 | Scenario | Behavior |
 |----------|----------|
 | JSON parse failure | Fails closed (exit 2) — blocks the operation |
-| Other exceptions | Fails open (exit 0) — logs error, allows the operation |
+| Other exceptions | Fails closed (exit 2) — logs error, blocks the operation |
 
 ### Timeout
 

package/.devcontainer/plugins/devs-marketplace/plugins/protected-files-guard/scripts/guard-protected-bash.py

@@ -10,13 +10,14 @@ Exit code 0 allows the command to proceed.
 
 import json
 import re
+import shlex
 import sys
 
 # Same patterns as guard-protected.py
 PROTECTED_PATTERNS = [
     (r"(^|/)\.env$", "Blocked: .env contains secrets - edit manually if needed"),
     (
-        r"(^|/)\.env\.[^/]+$",
+        r"(^|/)\.env\.(?!example$)[^/]+$",
         "Blocked: .env.* files contain secrets - edit manually if needed",
     ),
     (r"(^|/)\.git(/|$)", "Blocked: .git is managed by git"),
@@ -36,7 +37,7 @@ PROTECTED_PATTERNS = [
     (r"\.crt$", "Blocked: .crt certificate files should not be edited directly"),
     (r"\.p12$", "Blocked: .p12 files contain sensitive cryptographic material"),
     (r"\.pfx$", "Blocked: .pfx files contain sensitive cryptographic material"),
-    (r"(^|/)credentials\.json$", "Blocked: credentials.json contains secrets"),
+    (r"(^|/)\.?credentials\.json$", "Blocked: credentials.json contains secrets"),
     (r"(^|/)secrets\.yaml$", "Blocked: secrets.yaml contains secrets"),
     (r"(^|/)secrets\.yml$", "Blocked: secrets.yml contains secrets"),
     (r"(^|/)secrets\.json$", "Blocked: secrets.json contains secrets"),
@@ -57,8 +58,8 @@ PROTECTED_PATTERNS = [
 # Patterns that indicate a bash command is writing to a file
 # Each captures the target file path for checking against PROTECTED_PATTERNS
 WRITE_PATTERNS = [
-    # Redirect: > file, >> file
-    r"(?:>|>>)\s*([^\s;&|]+)",
+    # Redirect: >> file, > file (>> before > to avoid greedy match)
+    r"(?:>>|>)\s*([^\s;&|]+)",
     # tee: tee file, tee -a file
     r"\btee\s+(?:-a\s+)?([^\s;&|]+)",
     # cp/mv: cp src dest, mv src dest
@@ -67,9 +68,78 @@ WRITE_PATTERNS = [
     r'\bsed\s+-i[^\s]*\s+(?:\'[^\']*\'\s+|"[^"]*"\s+|[^\s]+\s+)*([^\s;&|]+)',
     # cat > file (heredoc style)
     r"\bcat\s+(?:<<[^\s]*\s+)?>\s*([^\s;&|]+)",
+    # --- Extended patterns (unified with guard-workspace-scope.py) ---
+    r"\btouch\s+(?:-[^\s]+\s+)*([^\s;&|]+)",  # touch file
+    r"\bmkdir\s+(?:-[^\s]+\s+)*([^\s;&|]+)",  # mkdir [-p] dir
+    r"\brm\s+(?:-[^\s]+\s+)*([^\s;&|]+)",  # rm [-rf] path
+    r"\bln\s+(?:-[^\s]+\s+)*[^\s]+\s+([^\s;&|]+)",  # ln [-s] src dest
+    r"\binstall\s+(?:-[^\s]+\s+)*[^\s]+\s+([^\s;&|]+)",  # install src dest
+    r"\brsync\s+(?:-[^\s]+\s+)*[^\s]+\s+([^\s;&|]+)",  # rsync src dest
+    r"\bchmod\s+(?:-[^\s]+\s+)*[^\s]+\s+([^\s;&|]+)",  # chmod mode path
+    r"\bchown\s+(?:-[^\s]+\s+)*[^\s:]+(?::[^\s]+)?\s+([^\s;&|]+)",  # chown owner[:group] path
+    r"\bdd\b[^;|&]*\bof=([^\s;&|]+)",  # dd of=path
+    r"\bwget\s+(?:-[^\s]+\s+)*-O\s+([^\s;&|]+)",  # wget -O path
+    r"\bcurl\s+(?:-[^\s]+\s+)*-o\s+([^\s;&|]+)",  # curl -o path
+    r"\btar\s+(?:-[^\s]+\s+)*-C\s+([^\s;&|]+)",  # tar -C dir
+    r"\bunzip\s+(?:-[^\s]+\s+)*-d\s+([^\s;&|]+)",  # unzip -d dir
+    r"\b(?:gcc|g\+\+|cc|c\+\+|clang)\s+(?:-[^\s]+\s+)*-o\s+([^\s;&|]+)",  # gcc -o out
+    r"\bsqlite3\s+([^\s;&|]+)",  # sqlite3 dbpath
 ]
 
 
+# Commands where all trailing non-flag arguments are file targets
+_MULTI_TARGET_CMDS = frozenset({"rm", "touch", "mkdir"})
+# Commands where the first non-flag arg is NOT a file (mode/owner), rest are
+_SKIP_FIRST_ARG_CMDS = frozenset({"chmod", "chown"})
+
+
+def _extract_multi_targets(command: str) -> list[str]:
+    """Extract all file targets from commands that accept multiple operands."""
+    try:
+        tokens = shlex.split(command)
+    except ValueError:
+        return []
+    if not tokens:
+        return []
+
+    # Handle prefixes like sudo, env, etc.
+    prefixes = {"sudo", "env", "nohup", "nice", "command"}
+    i = 0
+    while i < len(tokens) and tokens[i] in prefixes:
+        i += 1
+        # Skip sudo flags like -u root
+        if i > 0 and tokens[i - 1] == "sudo":
+            while i < len(tokens) and tokens[i].startswith("-"):
+                i += 1
+                if i < len(tokens) and not tokens[i].startswith("-"):
+                    i += 1  # skip flag argument
+        # Skip env VAR=val
+        if i > 0 and tokens[i - 1] == "env":
+            while i < len(tokens) and "=" in tokens[i]:
+                i += 1
+    if i >= len(tokens):
+        return []
+    cmd = tokens[i]
+
+    if cmd not in _MULTI_TARGET_CMDS and cmd not in _SKIP_FIRST_ARG_CMDS:
+        return []
+
+    # Collect non-flag arguments
+    args = []
+    j = i + 1
+    while j < len(tokens):
+        if tokens[j].startswith("-"):
+            j += 1
+            continue
+        args.append(tokens[j])
+        j += 1
+
+    if cmd in _SKIP_FIRST_ARG_CMDS and args:
+        args = args[1:]  # First arg is mode/owner, not a file
+
+    return args
+
+
 def extract_write_targets(command: str) -> list[str]:
     """Extract file paths that the command writes to."""
     targets = []
@@ -78,6 +148,10 @@ def extract_write_targets(command: str) -> list[str]:
             target = match.group(1).strip("'\"")
             if target:
                 targets.append(target)
+    # Supplement with multi-target extraction for commands like rm, touch, chmod
+    for target in _extract_multi_targets(command):
+        if target not in targets:
+            targets.append(target)
     return targets
 
 
@@ -113,9 +187,9 @@ def main():
         # Fail closed: can't parse means can't verify safety
         sys.exit(2)
     except Exception as e:
-        # Log error but don't block on hook failure
+        # Fail closed: unexpected errors should block, not allow
         print(f"Hook error: {e}", file=sys.stderr)
-        sys.exit(0)
+        sys.exit(2)
 
 
 if __name__ == "__main__":

package/.devcontainer/plugins/devs-marketplace/plugins/protected-files-guard/scripts/guard-protected.py

@@ -16,7 +16,7 @@ PROTECTED_PATTERNS = [
     # Environment secrets
     (r"(^|/)\.env$", "Blocked: .env contains secrets - edit manually if needed"),
     (
-        r"(^|/)\.env\.[^/]+$",
+        r"(^|/)\.env\.(?!example$)[^/]+$",
         "Blocked: .env.* files contain secrets - edit manually if needed",
     ),
     # Git internals
@@ -40,7 +40,7 @@ PROTECTED_PATTERNS = [
     (r"\.p12$", "Blocked: .p12 files contain sensitive cryptographic material"),
     (r"\.pfx$", "Blocked: .pfx files contain sensitive cryptographic material"),
     # Credential files
-    (r"(^|/)credentials\.json$", "Blocked: credentials.json contains secrets"),
+    (r"(^|/)\.?credentials\.json$", "Blocked: credentials.json contains secrets"),
     (r"(^|/)secrets\.yaml$", "Blocked: secrets.yaml contains secrets"),
     (r"(^|/)secrets\.yml$", "Blocked: secrets.yml contains secrets"),
     (r"(^|/)secrets\.json$", "Blocked: secrets.json contains secrets"),
@@ -100,9 +100,9 @@ def main():
         # Fail closed: can't parse means can't verify safety
         sys.exit(2)
     except Exception as e:
-        # Log error but don't block on hook failure
+        # Fail closed: unexpected errors should block, not allow
         print(f"Hook error: {e}", file=sys.stderr)
-        sys.exit(0)
+        sys.exit(2)
 
 
 if __name__ == "__main__":

package/.devcontainer/plugins/devs-marketplace/plugins/session-context/README.md

@@ -4,13 +4,14 @@ Claude Code plugin that injects contextual information at session boundaries. Pr
 
 ## What It Does
 
-Three hooks that run automatically at session lifecycle boundaries:
+Four hooks that run automatically at session lifecycle boundaries:
 
 | Phase | Script | What It Injects |
 |-------|--------|-----------------|
 | Session start | `git-state-injector.py` | Current branch, status, recent commits, uncommitted changes |
 | Session start | `todo-harvester.py` | Count and top 10 TODO/FIXME/HACK/XXX markers in the codebase |
-| Stop | `commit-reminder.py` | Advisory about staged/unstaged changes that should be committed |
+| PostToolUse (Edit/Write) | `collect-session-edits.py` | Tracks which files the session modified (tmp file) |
+| Stop | `commit-reminder.py` | Advisory about uncommitted changes (only if session edited files) |
 
 All hooks are non-blocking and cap their output to prevent context bloat.
 
@@ -31,12 +32,19 @@ Scans source files for tech debt markers and injects a summary:
 - Shows total count plus top 10 items
 - Output capped at 800 characters
 
+### Edit Tracking
+
+Lightweight PostToolUse hook on Edit/Write that records file paths to `/tmp/claude-session-edits-{session_id}`. Used by the commit reminder to determine if this session actually modified files.
+
 ### Commit Reminder
 
-Fires when Claude stops responding and checks for uncommitted work:
-- Detects staged and unstaged changes
-- Injects an advisory so Claude can naturally ask if the user wants to commit
-- Uses a guard flag to prevent infinite loops (the reminder itself is a Stop event)
+Fires when Claude stops responding, using tiered logic based on change significance:
+- Checks the session edit tracker — skips entirely if session was read-only
+- **Meaningful changes** (3+ files, 2+ source files, or test files): suggests committing via advisory `systemMessage`
+- **Small changes** (1-2 non-source files): silent, no output
+- Output wrapped in `<system-reminder>` tags — advisory only, never blocks
+- Instructs Claude not to commit without explicit user approval
+- Uses a guard flag to prevent infinite loops
 
 ## How It Works
 
@@ -58,6 +66,12 @@ Session starts
   |           +-> Injects count + top 10 as additionalContext
   |
   |  ... Claude works ...
+  |     |
+  |     +-> PostToolUse (Edit|Write) fires
+  |           |
+  |           +-> collect-session-edits.py
+  |                 |
+  |                 +-> Appends file path to /tmp/claude-session-edits-{session_id}
   |
 Claude stops responding
   |
@@ -65,14 +79,14 @@ Claude stops responding
         |
         +-> commit-reminder.py
               |
-              +-> Checks git status for changes
-              +-> Has changes? -> Inject commit advisory
-              +-> No changes? -> Silent (no output)
+              +-> Session edited files? (checks tmp file)
+              +-> No edits this session? -> Silent (no output)
+              +-> Has edits + uncommitted changes? -> Inject advisory systemMessage
 ```
 
 ### Exit Code Behavior
 
-All three scripts exit 0 (advisory only). They never block operations.
+All four scripts exit 0 (advisory only). They never block operations.
 
 ### Error Handling
 
@@ -88,6 +102,7 @@ All three scripts exit 0 (advisory only). They never block operations.
 |------|---------|
 | Git state injection | 10s |
 | TODO harvesting | 8s |
+| Edit tracking | 3s |
 | Commit reminder | 8s |
 
 ## Installation
@@ -125,11 +140,12 @@ session-context/
 +-- .claude-plugin/
 |   +-- plugin.json            # Plugin metadata
 +-- hooks/
-|   +-- hooks.json             # Hook registrations (SessionStart + Stop)
+|   +-- hooks.json               # Hook registrations (SessionStart + PostToolUse + Stop)
 +-- scripts/
-|   +-- git-state-injector.py  # Git state context (SessionStart)
-|   +-- todo-harvester.py      # Tech debt markers (SessionStart)
-|   +-- commit-reminder.py     # Uncommitted changes advisory (Stop)
+|   +-- git-state-injector.py    # Git state context (SessionStart)
+|   +-- todo-harvester.py        # Tech debt markers (SessionStart)
+|   +-- collect-session-edits.py # Edit tracking (PostToolUse)
+|   +-- commit-reminder.py       # Uncommitted changes advisory (Stop)
 +-- README.md                  # This file
 ```
 

package/.devcontainer/plugins/devs-marketplace/plugins/session-context/hooks/hooks.json

@@ -1,6 +1,18 @@
 {
-	"description": "Context injection at session boundaries: git state, TODO harvesting, commit reminders",
+	"description": "Context injection at session boundaries: git state, TODO harvesting, edit tracking, commit reminders",
 	"hooks": {
+		"PostToolUse": [
+			{
+				"matcher": "Edit|Write",
+				"hooks": [
+					{
+						"type": "command",
+						"command": "python3 ${CLAUDE_PLUGIN_ROOT}/scripts/collect-session-edits.py",
+						"timeout": 3
+					}
+				]
+			}
+		],
 		"SessionStart": [
 			{
 				"matcher": "",

package/.devcontainer/plugins/devs-marketplace/plugins/session-context/scripts/collect-session-edits.py

@@ -0,0 +1,44 @@
+#!/usr/bin/env python3
+"""
+Collect edited file paths for session-aware Stop hooks.
+
+Lightweight PostToolUse hook that appends the edited file path
+to a session-scoped temp file. The commit-reminder Stop hook
+reads this file to determine if the session modified any files.
+
+Non-blocking: always exits 0. Runs in <10ms.
+"""
+
+import json
+import os
+import sys
+
+
+def main():
+    try:
+        input_data = json.load(sys.stdin)
+    except (json.JSONDecodeError, ValueError):
+        sys.exit(0)
+
+    session_id = input_data.get("session_id", "")
+    tool_input = input_data.get("tool_input", {})
+    file_path = tool_input.get("file_path", "")
+
+    if not file_path or not session_id:
+        sys.exit(0)
+
+    if not os.path.isfile(file_path):
+        sys.exit(0)
+
+    tmp_path = f"/tmp/claude-session-edits-{session_id}"
+    try:
+        with open(tmp_path, "a") as f:
+            f.write(file_path + "\n")
+    except OSError:
+        pass  # non-critical, don't block Claude
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/.devcontainer/plugins/devs-marketplace/plugins/session-context/scripts/commit-reminder.py

@@ -2,21 +2,31 @@
 """
 Commit reminder — Stop hook that advises about uncommitted changes.
 
-On Stop, checks for uncommitted changes (staged + unstaged) and injects
-an advisory reminder as additionalContext. Claude sees it and can
-naturally ask the user if they want to commit.
+On Stop, checks whether this session edited any files (via the tmp file
+written by collect-session-edits.py) and whether uncommitted changes exist.
+Uses tiered logic: meaningful changes (3+ files, 2+ source files, or test
+files touched) get an advisory suggestion; small changes are silent.
 
-Reads hook input from stdin (JSON). Returns JSON on stdout.
-Blocks with decision/reason so Claude addresses uncommitted changes
-before finishing. The stop_hook_active guard prevents infinite loops.
+Output is a systemMessage wrapped in <system-reminder> tags — advisory only,
+never blocks. The stop_hook_active guard prevents loops.
 """
 
 import json
+import os
 import subprocess
 import sys
 
 GIT_CMD_TIMEOUT = 5
 
+# Extensions considered source code (not config/docs)
+SOURCE_EXTS = frozenset((
+    ".py", ".ts", ".tsx", ".js", ".jsx", ".go", ".rs",
+    ".java", ".kt", ".rb", ".svelte", ".vue", ".c", ".cpp", ".h",
+))
+
+# Patterns that indicate test files
+TEST_PATTERNS = ("test_", "_test.", ".test.", ".spec.", "/tests/", "/test/")
+
 
 def _run_git(args: list[str]) -> str | None:
     """Run a git command and return stdout, or None on any failure."""
@@ -34,6 +44,58 @@ def _run_git(args: list[str]) -> str | None:
     return None
 
 
+def _read_session_edits(session_id: str) -> list[str]:
+    """Read the list of files edited this session."""
+    tmp_path = f"/tmp/claude-session-edits-{session_id}"
+    try:
+        with open(tmp_path, "r") as f:
+            raw = f.read()
+    except OSError:
+        return []
+
+    seen: set[str] = set()
+    result: list[str] = []
+    for line in raw.strip().splitlines():
+        path = line.strip()
+        if path and path not in seen:
+            seen.add(path)
+            result.append(path)
+    return result
+
+
+def _is_source_file(path: str) -> bool:
+    """Check if a file path looks like source code."""
+    _, ext = os.path.splitext(path)
+    return ext.lower() in SOURCE_EXTS
+
+
+def _is_test_file(path: str) -> bool:
+    """Check if a file path looks like a test file."""
+    lower = path.lower()
+    return any(pattern in lower for pattern in TEST_PATTERNS)
+
+
+def _is_meaningful(edited_files: list[str]) -> bool:
+    """Determine if the session's edits are meaningful enough to suggest committing.
+
+    Meaningful when any of:
+    - 3+ total files edited
+    - 2+ source code files edited
+    - Any test files edited (suggests feature work)
+    """
+    if len(edited_files) >= 3:
+        return True
+
+    source_count = sum(1 for f in edited_files if _is_source_file(f))
+    if source_count >= 2:
+        return True
+
+    if any(_is_test_file(f) for f in edited_files):
+        return True
+
+    return False
+
+
 def main():
     try:
         input_data = json.load(sys.stdin)
@@ -44,7 +106,20 @@ def main():
     if input_data.get("stop_hook_active"):
         sys.exit(0)
 
-    # Check if there are any changes at all
+    # Only fire if this session actually edited files
+    session_id = input_data.get("session_id", "")
+    if not session_id:
+        sys.exit(0)
+
+    edited_files = _read_session_edits(session_id)
+    if not edited_files:
+        sys.exit(0)
+
+    # Small changes — stay silent
+    if not _is_meaningful(edited_files):
+        sys.exit(0)
+
+    # Check if there are any uncommitted changes
     porcelain = _run_git(["status", "--porcelain"])
     if porcelain is None:
         # Not a git repo or git not available
@@ -79,11 +154,15 @@ def main():
     summary = ", ".join(parts) if parts else f"{total} changed"
 
     message = (
-        f"[Uncommitted Changes] {total} files with changes ({summary}).\n"
-        "Consider asking the user if they'd like to commit before finishing."
+        "<system-reminder>\n"
+        f"[Session Summary] Modified {total} files ({summary}). "
+        "This looks like a complete unit of work.\n"
+        "Consider asking the user if they would like to commit.\n"
+        "Do NOT commit without explicit user approval.\n"
+        "</system-reminder>"
     )
 
-    json.dump({"decision": "block", "reason": message}, sys.stdout)
+    json.dump({"systemMessage": message}, sys.stdout)
     sys.exit(0)
 
 

package/.devcontainer/plugins/devs-marketplace/plugins/skill-engine/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
 	"name": "skill-engine",
-	"description": "21 coding knowledge packs with auto-suggestion for frameworks, tools, and patterns",
+	"description": "22 coding knowledge packs with auto-suggestion for frameworks, tools, and patterns",
 	"author": {
 		"name": "AnExiledDev"
 	}

package/.devcontainer/plugins/devs-marketplace/plugins/skill-engine/README.md

@@ -1,12 +1,12 @@
 # skill-engine
 
-Claude Code plugin that provides 21 coding knowledge packs (skills) with automatic suggestion based on user prompts. Each skill contains domain-specific instructions and reference material that Claude loads on demand via the `/skill` command.
+Claude Code plugin that provides 22 coding knowledge packs (skills) with automatic suggestion based on user prompts. Each skill contains domain-specific instructions and reference material that Claude loads on demand via the `/skill` command.
 
 ## What It Does
 
 Two capabilities:
 
-1. **Skill library** — 21 skills covering frameworks, tools, and development patterns. Each skill is a structured knowledge pack with a `SKILL.md` entrypoint and `references/` subdirectory containing detailed reference docs.
+1. **Skill library** — 22 skills covering frameworks, tools, and development patterns. Each skill is a structured knowledge pack with a `SKILL.md` entrypoint and `references/` subdirectory containing detailed reference docs.
 
 2. **Auto-suggestion** — A `UserPromptSubmit` hook watches user prompts for keyword matches and suggests relevant skills as context, so Claude can proactively load the right knowledge.
 
@@ -35,14 +35,18 @@ Two capabilities:
 | svelte5 | Runes, reactivity, components, SPA routing, LayerCake |
 | team | Agent team orchestration, parallel workstreams, task coordination |
 | testing | Testing frameworks, FastAPI testing, Svelte testing |
+| worktree | Git worktree lifecycle, EnterWorktree, parallel development |
 
 ### Auto-Suggestion
 
-The `skill-suggester.py` hook matches user prompts against keyword maps defined in each skill. When a match is found, it injects a suggestion via `additionalContext` so Claude knows a relevant skill is available.
+The `skill-suggester.py` hook scores user prompts against keyword maps for each skill using weighted matching. Suggestions are ranked by confidence and capped at **3 skills maximum** per prompt.
 
-Keywords are defined per skill as:
-- **Phrases** — Multi-word patterns (e.g., "docker compose", "REST API")
-- **Terms** — Single keywords (e.g., "FastAPI", "pytest")
+Each skill defines:
+- **Phrases** — `(substring, weight)` tuples. Weight 0.0–1.0 reflects specificity (e.g., `("build a fastapi app", 1.0)` vs `("pydantic model", 0.3)`)
+- **Terms** — Whole-word regex patterns, all scored at 0.6
+- **Negative patterns** — Substrings that instantly disqualify a skill (e.g., `"pydanticai"` suppresses `fastapi`)
+- **Context guards** — Required co-occurring words for low-confidence matches. When the best score is below 0.6, at least one guard word must appear in the prompt or the match is dropped
+- **Priority** — Integer tie-breaker (10 = commands, 7 = tech, 5 = patterns, 3 = generic)
 
 ## How It Works
 
@@ -55,9 +59,12 @@ User submits a prompt
         |
         +-> skill-suggester.py
               |
-              +-> Scan prompt against all skill keyword maps
-              +-> Match found? -> Inject skill suggestion as additionalContext
-              +-> No match? -> Silent (no output)
+              +-> Check negative patterns (instant disqualify)
+              +-> Score phrases (best weight) and terms (0.6)
+              +-> Enforce context guards on low-confidence matches
+              +-> Rank by score desc, priority desc
+              +-> Return top 3 as additionalContext
+              +-> No matches above threshold? -> Silent (no output)
 ```
 
 ### Skill Structure
@@ -126,9 +133,9 @@ skill-engine/
 +-- hooks/
 |   +-- hooks.json                   # UserPromptSubmit hook registration
 +-- scripts/
-|   +-- skill-suggester.py           # Keyword-based skill auto-suggestion
+|   +-- skill-suggester.py           # Weighted scoring skill auto-suggestion
 +-- skills/
-|   +-- api-design/                  # 21 skill directories
+|   +-- api-design/                  # 22 skill directories
 |   +-- ast-grep-patterns/
 |   +-- claude-agent-sdk/
 |   +-- claude-code-headless/
@@ -149,6 +156,7 @@ skill-engine/
 |   +-- svelte5/
 |   +-- team/
 |   +-- testing/
+|   +-- worktree/
 +-- README.md                        # This file
 ```