codeforge-dev 1.12.0 → 1.14.1

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

@@ -0,0 +1,158 @@
+# 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.
+
+## 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.
+
+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.
+
+### Skill Catalog
+
+| Skill | Domain |
+|-------|--------|
+| api-design | REST conventions, error handling, API patterns |
+| ast-grep-patterns | Semantic code search patterns by language |
+| claude-agent-sdk | Building custom agents with the Agent SDK (TypeScript) |
+| claude-code-headless | CLI flags, output parsing, SDK and MCP integration |
+| debugging | Error patterns, log locations, diagnosis procedures |
+| dependency-management | Package managers, ecosystem commands, license compliance |
+| docker | Dockerfile patterns, docker-compose services |
+| docker-py | Docker SDK for Python, container lifecycle |
+| documentation-patterns | API doc templates, docstring formats |
+| fastapi | Routing, Pydantic v2, SSE streaming, middleware, dependencies |
+| git-forensics | Advanced git commands, blame history, investigation playbooks |
+| migration-patterns | Framework/version migrations for JavaScript and Python |
+| performance-profiling | Profiling tools, interpreting results, optimization |
+| pydantic-ai | Building AI agents with Pydantic, tools, models, streaming |
+| refactoring-patterns | Safe transformations, code smell catalog |
+| security-checklist | OWASP patterns, secrets management, vulnerability detection |
+| skill-building | How to author skills, patterns and anti-patterns |
+| sqlite | Schema, pragmas, advanced queries, FTS5, JS/Python patterns |
+| svelte5 | Runes, reactivity, components, SPA routing, LayerCake |
+| team | Agent team orchestration, parallel workstreams, task coordination |
+| testing | Testing frameworks, FastAPI testing, Svelte testing |
+
+### 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.
+
+Keywords are defined per skill as:
+- **Phrases** — Multi-word patterns (e.g., "docker compose", "REST API")
+- **Terms** — Single keywords (e.g., "FastAPI", "pytest")
+
+## How It Works
+
+### Hook Lifecycle
+
+```
+User submits a prompt
+  |
+  +-> UserPromptSubmit fires
+        |
+        +-> skill-suggester.py
+              |
+              +-> Scan prompt against all skill keyword maps
+              +-> Match found? -> Inject skill suggestion as additionalContext
+              +-> No match? -> Silent (no output)
+```
+
+### Skill Structure
+
+Each skill follows a standard layout:
+
+```
+skills/
++-- skill-name/
+    +-- SKILL.md             # Entrypoint: instructions, patterns, key concepts
+    +-- references/          # Detailed reference material
+        +-- topic-a.md
+        +-- topic-b.md
+```
+
+Skills are loaded via Claude Code's `/skill` slash command (e.g., `/skill fastapi`). The `SKILL.md` file is the primary document Claude reads; references are loaded as needed for deeper detail.
+
+### Exit Code Behavior
+
+| Exit Code | Meaning |
+|-----------|---------|
+| 0 | Suggestion injected (or no match — silent) |
+
+The hook never blocks operations.
+
+### Timeouts
+
+| Hook | Timeout |
+|------|---------|
+| Skill suggestion (UserPromptSubmit) | 3s |
+
+## Installation
+
+### CodeForge DevContainer
+
+Pre-installed and activated automatically — no setup needed.
+
+### From GitHub
+
+Use this plugin in any Claude Code setup:
+
+1. Clone the [CodeForge](https://github.com/AnExiledDev/CodeForge) repository:
+
+   ```bash
+   git clone https://github.com/AnExiledDev/CodeForge.git
+   ```
+
+2. Enable the plugin in your `.claude/settings.json`:
+
+   ```json
+   {
+     "enabledPlugins": {
+       "skill-engine@<clone-path>/.devcontainer/plugins/devs-marketplace": true
+     }
+   }
+   ```
+
+   Replace `<clone-path>` with the absolute path to your CodeForge clone.
+
+## Plugin Structure
+
+```
+skill-engine/
++-- .claude-plugin/
+|   +-- plugin.json                  # Plugin metadata
++-- hooks/
+|   +-- hooks.json                   # UserPromptSubmit hook registration
++-- scripts/
+|   +-- skill-suggester.py           # Keyword-based skill auto-suggestion
++-- skills/
+|   +-- api-design/                  # 21 skill directories
+|   +-- ast-grep-patterns/
+|   +-- claude-agent-sdk/
+|   +-- claude-code-headless/
+|   +-- debugging/
+|   +-- dependency-management/
+|   +-- docker/
+|   +-- docker-py/
+|   +-- documentation-patterns/
+|   +-- fastapi/
+|   +-- git-forensics/
+|   +-- migration-patterns/
+|   +-- performance-profiling/
+|   +-- pydantic-ai/
+|   +-- refactoring-patterns/
+|   +-- security-checklist/
+|   +-- skill-building/
+|   +-- sqlite/
+|   +-- svelte5/
+|   +-- team/
+|   +-- testing/
++-- README.md                        # This file
+```
+
+## Requirements
+
+- Python 3.11+
+- Claude Code with plugin hook support (skills)

package/.devcontainer/plugins/devs-marketplace/plugins/skill-engine/hooks/hooks.json

@@ -0,0 +1,16 @@
+{
+	"description": "Skill auto-suggestion on user prompts",
+	"hooks": {
+		"UserPromptSubmit": [
+			{
+				"hooks": [
+					{
+						"type": "command",
+						"command": "python3 ${CLAUDE_PLUGIN_ROOT}/scripts/skill-suggester.py",
+						"timeout": 3
+					}
+				]
+			}
+		]
+	}
+}

package/.devcontainer/plugins/devs-marketplace/plugins/{code-directive → skill-engine}/scripts/skill-suggester.py

@@ -2,7 +2,7 @@
 """Skill suggester hook for UserPromptSubmit and SubagentStart events.
 
 Detects which hook event called it via input JSON shape:
-- UserPromptSubmit: {"prompt": "..."} -> {"systemMessage": "..."}
+- UserPromptSubmit: {"prompt": "..."} -> {"additionalContext": "..."}
 - SubagentStart:    {"subagent_type": "Plan", "prompt": "..."} -> {"additionalContext": "..."}
 
 Matches user prompts against skill keyword maps (phrases + terms) and suggests
@@ -16,30 +16,33 @@ import sys
 SKILLS = {
     "fastapi": {
         "phrases": [
-            "rest api",
+            "build a fastapi app",
+            "rest api with fastapi",
             "fastapi",
             "fast api",
+            "add sse streaming",
+            "dependency injection in fastapi",
+            "define pydantic models",
+            "stream llm responses",
+            "add middleware to fastapi",
             "pydantic model",
-            "sse streaming",
-            "server-sent event",
-            "dependency injection",
-            "asgi middleware",
-            "api endpoint",
-            "api route",
         ],
-        "terms": ["fastapi", "pydantic", "uvicorn", "starlette"],
+        "terms": ["fastapi", "pydantic", "uvicorn", "starlette", "sse-starlette"],
     },
     "sqlite": {
         "phrases": [
             "sqlite",
+            "set up a sqlite database",
             "wal mode",
             "fts5",
             "full-text search",
             "better-sqlite3",
             "cloudflare d1",
-            "json1 extension",
+            "store json in sqlite",
+            "write ctes",
+            "window functions",
         ],
-        "terms": ["aiosqlite"],
+        "terms": ["aiosqlite", "better-sqlite3"],
     },
     "claude-code-headless": {
         "phrases": [
@@ -49,31 +52,39 @@ SKILLS = {
             "claude code headless",
             "run claude in ci",
             "claude in pipeline",
+            "parse stream-json output",
+            "track costs programmatically",
+            "permissions for scripts",
         ],
-        "terms": [],
+        "terms": ["--output-format stream-json", "--permission-mode"],
     },
     "claude-agent-sdk": {
         "phrases": [
             "agent sdk",
             "claude agent sdk",
-            "build an agent",
-            "create an agent",
+            "build an agent with the claude agent sdk",
             "canusetool",
             "sdk permissions",
+            "create mcp tools",
+            "define subagents",
+            "configure sdk hooks",
+            "stream sdk messages",
         ],
-        "terms": ["claude-agent-sdk", "claude_agent_sdk"],
+        "terms": ["claude-agent-sdk", "claude_agent_sdk", "createSdkMcpServer"],
     },
     "pydantic-ai": {
         "phrases": [
             "pydantic ai",
             "pydantic-ai",
             "pydanticai",
-            "ai agent",
-            "runcontext",
-            "vercel ai adapter",
-            "model fallback",
+            "build a pydanticai agent",
+            "add tools to an agent",
+            "stream responses with pydanticai",
+            "test a pydanticai agent",
+            "connect pydanticai to svelte",
+            "configure model fallbacks",
         ],
-        "terms": ["pydanticai"],
+        "terms": ["pydanticai", "RunContext", "VercelAIAdapter", "FallbackModel"],
     },
     "testing": {
         "phrases": [
@@ -87,12 +98,11 @@ SKILLS = {
             "mock dependencies",
             "test endpoint",
             "test component",
+            "test sse streaming",
             "unit test",
             "integration test",
-            "run tests",
-            "run the tests",
         ],
-        "terms": ["pytest", "vitest"],
+        "terms": ["pytest", "vitest", "pytest-anyio", "httpx AsyncClient"],
     },
     "docker-py": {
         "phrases": [
@@ -102,8 +112,12 @@ SKILLS = {
             "docker engine api",
             "docker from python",
             "docker api",
+            "manage docker containers from python",
+            "create containers programmatically",
+            "stream container logs",
+            "monitor container health from python",
         ],
-        "terms": ["aiodocker"],
+        "terms": ["aiodocker", "DockerClient"],
     },
     "svelte5": {
         "phrases": [
@@ -113,12 +127,11 @@ SKILLS = {
             "svelte rune",
             "svelte 5",
             "svelte5",
-            "layercake",
-            "layer cake",
-            "svelte-dnd-action",
-            "svelte dnd",
+            "migrate from svelte 4",
+            "manage state with $state",
+            "drag and drop to svelte",
         ],
-        "terms": ["sveltekit", "svelte"],
+        "terms": ["sveltekit", "svelte", "svelte-dnd-action", "@ai-sdk/svelte"],
     },
     "docker": {
         "phrases": [
@@ -129,11 +142,10 @@ SKILLS = {
             "multi-stage build",
             "health check",
             "healthcheck",
-            "docker network",
-            "docker volume",
-            "docker image",
+            "docker compose watch",
+            "optimize docker image",
         ],
-        "terms": ["dockerfile", "compose"],
+        "terms": ["dockerfile", "compose.yaml", "BuildKit"],
     },
     "skill-building": {
         "phrases": [
@@ -144,6 +156,8 @@ SKILLS = {
             "skill instructions",
             "skill authoring",
             "design a skill",
+            "improve a skill description",
+            "optimize skill content",
         ],
         "terms": [],
     },
@@ -151,49 +165,46 @@ SKILLS = {
         "phrases": [
             "debug logs",
             "check logs",
+            "check container logs",
             "find error",
             "investigate failure",
-            "container logs",
             "what went wrong",
             "why did this crash",
             "diagnose the issue",
             "look at the logs",
             "read the logs",
+            "read docker logs",
             "analyze error",
         ],
-        "terms": ["diagnose", "troubleshoot"],
+        "terms": ["diagnose", "troubleshoot", "OOMKilled", "ECONNREFUSED"],
     },
     "refactoring-patterns": {
         "phrases": [
             "refactor this",
             "clean up code",
-            "improve code structure",
-            "reduce complexity",
-        ],
-        "terms": [
-            "refactor",
-            "refactoring",
-            "code smell",
-            "extract function",
-            "dead code",
+            "clean up this function",
+            "extract a method",
+            "fix code smells",
+            "reduce code duplication",
+            "simplify this class",
+            "break up this large function",
+            "remove dead code",
         ],
+        "terms": ["refactor", "refactoring", "code smell", "feature envy", "god class"],
     },
     "security-checklist": {
         "phrases": [
             "security review",
+            "security issues",
+            "security vulnerabilities",
             "check for vulnerabilities",
+            "scan for secrets",
             "audit security",
-            "find security issues",
-        ],
-        "terms": [
-            "security",
-            "vulnerability",
-            "owasp",
-            "injection",
-            "xss",
-            "secrets",
-            "cve",
+            "review for injection",
+            "owasp compliance",
+            "hardcoded credentials",
         ],
+        "terms": ["owasp", "injection", "xss", "cve", "trivy", "gitleaks"],
     },
     "git-forensics": {
         "phrases": [
@@ -201,62 +212,67 @@ SKILLS = {
             "who changed this",
             "when did this break",
             "git blame",
+            "bisect a regression",
+            "recover a lost commit",
+            "search git history",
+            "find when code was removed",
+            "trace the history",
+            "use git reflog",
         ],
-        "terms": ["bisect", "blame", "archaeology", "git log", "pickaxe", "reflog"],
+        "terms": ["bisect", "blame", "pickaxe", "reflog", "git log -S"],
     },
     "specification-writing": {
         "phrases": [
             "write a spec",
+            "write requirements",
             "define requirements",
             "acceptance criteria",
             "user stories",
+            "use ears format",
+            "given/when/then",
+            "write given/when/then scenarios",
+            "structure requirements",
         ],
-        "terms": [
-            "specification",
-            "requirements",
-            "ears",
-            "gherkin",
-            "given when then",
-        ],
+        "terms": ["specification", "ears", "gherkin", "given when then"],
     },
     "performance-profiling": {
         "phrases": [
+            "profile this code",
             "profile performance",
             "find bottleneck",
+            "find the bottleneck",
             "benchmark this",
+            "create a flamegraph",
+            "find memory leaks",
             "why is this slow",
+            "measure execution time",
+            "reduce latency",
         ],
-        "terms": [
-            "profiling",
-            "benchmark",
-            "flamegraph",
-            "bottleneck",
-            "latency",
-            "throughput",
-        ],
+        "terms": ["cProfile", "py-spy", "scalene", "flamegraph", "hyperfine"],
     },
     "api-design": {
         "phrases": [
             "api design",
             "rest api design",
             "design an api",
-            "design a rest",
-            "api convention",
-            "endpoint design",
+            "design rest endpoints",
             "api versioning",
-            "pagination pattern",
-            "error response format",
+            "pagination strategy",
+            "design error responses",
+            "rate limiting",
+            "openapi documentation",
         ],
-        "terms": ["openapi", "swagger", "rfc7807"],
+        "terms": ["openapi", "swagger", "rfc7807", "rfc 7807"],
     },
     "ast-grep-patterns": {
         "phrases": [
             "ast-grep",
             "ast grep",
             "structural search",
-            "structural code search",
             "syntax-aware search",
-            "tree-sitter",
+            "find code patterns",
+            "search with ast-grep",
+            "use tree-sitter",
         ],
         "terms": ["sg run", "ast-grep", "tree-sitter"],
     },
@@ -269,6 +285,7 @@ SKILLS = {
             "license check",
             "unused dependencies",
             "vulnerability scan",
+            "find unused dependencies",
         ],
         "terms": ["pip-audit", "npm audit", "cargo audit", "govulncheck"],
     },
@@ -279,10 +296,10 @@ SKILLS = {
             "add docstrings",
             "add jsdoc",
             "document the api",
-            "documentation template",
+            "create architecture docs",
             "update the docs",
         ],
-        "terms": ["docstring", "jsdoc", "tsdoc", "godoc", "rustdoc"],
+        "terms": ["docstring", "jsdoc", "tsdoc", "rustdoc", "Sphinx"],
     },
     "migration-patterns": {
         "phrases": [
@@ -293,8 +310,10 @@ SKILLS = {
             "bump python",
             "upgrade pydantic",
             "migrate express",
+            "modernize the codebase",
+            "commonjs to esm",
         ],
-        "terms": ["migrate", "migration", "upgrade"],
+        "terms": ["migrate", "migration"],
     },
     "spec-build": {
         "phrases": [
@@ -302,10 +321,9 @@ SKILLS = {
             "build from spec",
             "start building",
             "spec-build",
-            "implement this feature from the spec",
+            "implement this feature",
             "build what the spec describes",
-            "implement from the spec",
-            "build the feature",
+            "run spec-build",
         ],
         "terms": ["spec-build"],
     },
@@ -317,9 +335,86 @@ SKILLS = {
             "spec-review",
             "does code match spec",
             "audit implementation",
+            "run spec-review",
+            "regression check",
         ],
         "terms": ["spec-review"],
     },
+    "spec-check": {
+        "phrases": [
+            "check spec health",
+            "audit specs",
+            "which specs are stale",
+            "find missing specs",
+            "review spec quality",
+            "run spec-check",
+            "are my specs up to date",
+        ],
+        "terms": ["spec-check"],
+    },
+    "spec-init": {
+        "phrases": [
+            "initialize specs",
+            "specs directory",
+            "set up specs",
+            "bootstrap specs",
+            "start using specs",
+            "create spec directory",
+            "init specs",
+            "set up .specs",
+        ],
+        "terms": ["spec-init"],
+    },
+    "spec-new": {
+        "phrases": [
+            "create a spec",
+            "new spec",
+            "new feature spec",
+            "write a spec for",
+            "spec this feature",
+            "start a new spec",
+            "plan a feature",
+            "add a spec",
+        ],
+        "terms": ["spec-new"],
+    },
+    "spec-refine": {
+        "phrases": [
+            "refine the spec",
+            "review spec assumptions",
+            "validate spec decisions",
+            "approve the spec",
+            "walk me through the spec",
+            "check spec for assumptions",
+            "iterate on the spec",
+        ],
+        "terms": ["spec-refine"],
+    },
+    "spec-update": {
+        "phrases": [
+            "update the spec",
+            "mark spec as implemented",
+            "as-built update",
+            "finish the spec",
+            "close the spec",
+            "update spec status",
+            "sync spec with code",
+        ],
+        "terms": ["spec-update"],
+    },
+    "team": {
+        "phrases": [
+            "spawn a team",
+            "create a team",
+            "team of agents",
+            "use a swarm",
+            "work in parallel",
+            "coordinate multiple agents",
+            "split this across agents",
+            "team up",
+        ],
+        "terms": ["TeamCreate", "SendMessage"],
+    },
 }
 
 # Pre-compile term patterns for whole-word matching
@@ -370,25 +465,19 @@ def main() -> None:
         return
 
     skill_list = ", ".join(f'"{s}"' for s in skills)
-    is_subagent = "subagent_type" in data
 
-    if is_subagent:
-        output = {
+    output = {
+        "hookSpecificOutput": {
+            "hookEventName": "UserPromptSubmit",
             "additionalContext": (
-                f"Available skills matching this planning task: {skill_list}. "
-                "These skills contain project-specific patterns, conventions, "
-                "and reference material. Consider their guidance when designing "
-                "the implementation approach."
-            )
-        }
-    else:
-        output = {
-            "systemMessage": (
-                f"<system-reminder>The user's prompt matches available skill(s): "
-                f"{skill_list}. Load the relevant skill(s) using the Skill tool "
-                f"before responding.</system-reminder>"
-            )
+                f"MANDATORY — Skill activation required. The user's prompt matches: {skill_list}. "
+                f"Before responding, evaluate each matched skill: is it relevant to this specific request? "
+                f"For each relevant skill, activate it using the Skill tool NOW. "
+                f"Skip any that are not relevant to the user's actual intent. "
+                f"Do not proceed with implementation until relevant skills are loaded."
+            ),
         }
+    }
 
     json.dump(output, sys.stdout)