codeforge-dev 1.12.0 → 1.14.1

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/README.md

@@ -1,250 +0,0 @@
-# code-directive
-
-The core Claude Code plugin for CodeForge. Provides 17 custom agent definitions, 28 coding reference skills, and 12 hook scripts spanning 6 lifecycle events. Handles agent redirection, skill suggestion, syntax validation, edited file collection, advisory testing, and session-start context injection.
-
-## What It Does
-
-### Agents (17)
-
-Custom agent definitions that replace Claude Code's built-in subagents with enhanced, purpose-built alternatives. Each agent is a markdown prompt file in `agents/` that defines the agent's role, constraints, tools, and workflow.
-
-| Agent | Role |
-|-------|------|
-| `architect` | System design, planning, architecture decisions |
-| `bash-exec` | Shell command execution with safety guardrails |
-| `claude-guide` | Claude Code usage guidance and troubleshooting |
-| `debug-logs` | Log analysis and debugging |
-| `dependency-analyst` | Dependency auditing, upgrades, and vulnerability analysis |
-| `doc-writer` | Documentation authoring |
-| `explorer` | Codebase exploration and context gathering |
-| `generalist` | General-purpose tasks |
-| `git-archaeologist` | Git history investigation and forensics |
-| `migrator` | Code migration and framework upgrades |
-| `perf-profiler` | Performance profiling and optimization |
-| `refactorer` | Code refactoring and restructuring |
-| `researcher` | Research and information gathering |
-| `security-auditor` | Security review and vulnerability assessment |
-| `spec-writer` | Specification authoring |
-| `statusline-config` | Status line configuration |
-| `test-writer` | Test authoring |
-
-### Agent Redirection
-
-The `redirect-builtin-agents.py` PreToolUse hook transparently swaps built-in agent types to custom agents whenever Claude spawns a subagent via the Task tool:
-
-| Built-in Agent | Redirects To |
-|----------------|--------------|
-| `Explore` | `explorer` |
-| `Plan` | `architect` |
-| `general-purpose` | `generalist` |
-| `Bash` | `bash-exec` |
-| `claude-code-guide` | `claude-guide` |
-| `statusline-setup` | `statusline-config` |
-
-See `AGENT-REDIRECTION.md` for the full technical guide on how the PreToolUse hook contract works.
-
-### Skills (28)
-
-Reference skill packages that provide domain-specific knowledge. Each skill lives in its own directory under `skills/` with a `SKILL.md` entry point and optional `references/` subdirectory. Skills are loaded on demand via slash commands.
-
-| Skill | Domain |
-|-------|--------|
-| `api-design` | REST conventions, error handling |
-| `ast-grep-patterns` | Structural code search patterns |
-| `claude-agent-sdk` | Claude Agent SDK (TypeScript) |
-| `claude-code-headless` | Claude Code CLI, SDK, and MCP |
-| `debugging` | Error patterns, log analysis |
-| `dependency-management` | Package ecosystems, license compliance |
-| `docker` | Dockerfile patterns, Compose services |
-| `docker-py` | Docker SDK for Python |
-| `documentation-patterns` | API docs, docstring formats |
-| `fastapi` | FastAPI routing, Pydantic, SSE, middleware |
-| `git-forensics` | Git investigation commands, playbooks |
-| `migration-patterns` | Python and JavaScript migration guides |
-| `performance-profiling` | Profiling tools, result interpretation |
-| `pydantic-ai` | PydanticAI agents, tools, models |
-| `refactoring-patterns` | Safe transformations, code smell catalog |
-| `security-checklist` | OWASP patterns, secrets management |
-| `skill-building` | Skill authoring patterns and principles |
-| `spec-build` | Specification-driven implementation lifecycle |
-| `spec-check` | Specification health audit |
-| `spec-init` | Initialize `.specs/` directory |
-| `spec-new` | Create new specification from template |
-| `spec-refine` | Validate spec assumptions with user |
-| `spec-review` | Verify implementation against spec |
-| `spec-update` | As-built spec update |
-| `specification-writing` | EARS templates, criteria patterns |
-| `sqlite` | SQLite patterns (Python, JavaScript, advanced) |
-| `svelte5` | Svelte 5 runes, components, routing |
-| `testing` | FastAPI testing, Svelte testing |
-
-### Hook Scripts (12)
-
-| Script | Hook Event | Matcher | Purpose |
-|--------|-----------|---------|---------|
-| `redirect-builtin-agents.py` | PreToolUse | Task | Redirects built-in agents to custom agents |
-| `skill-suggester.py` | UserPromptSubmit | * | Suggests relevant skills based on prompt keywords |
-| `ticket-linker.py` | UserPromptSubmit | * | Auto-fetches GitHub issues/PRs referenced by #123 or URL |
-| `skill-suggester.py` | SubagentStart | Plan | Suggests skills for planning agents |
-| `inject-cwd.py` | SubagentStart | * | Injects working directory into subagent context |
-| `advisory-test-runner.py` | Stop | * | Runs affected tests and injects results as context |
-| `commit-reminder.py` | Stop | * | Advises about uncommitted changes |
-| `spec-reminder.py` | Stop | * | Advises about spec updates after code changes |
-| `git-state-injector.py` | SessionStart | * | Injects branch, status, and recent commits at session start |
-| `todo-harvester.py` | SessionStart | * | Surfaces TODO/FIXME/HACK/XXX comments from the codebase |
-| `syntax-validator.py` | PostToolUse | Edit\|Write | Validates JSON, JSONC, YAML, TOML syntax after edits |
-| `collect-edited-files.py` | PostToolUse | Edit\|Write | Records edited file paths for batch formatting/linting |
-
-## How It Works
-
-### Hook Lifecycle
-
-```
-Session starts
-  │
-  ├─→ git-state-injector.py     Injects branch, status, recent commits
-  └─→ todo-harvester.py         Surfaces TODO/FIXME markers
-
-User submits a prompt
-  │
-  ├─→ skill-suggester.py        Suggests skills matching prompt keywords
-  └─→ ticket-linker.py          Fetches GitHub issues referenced by #123 or URL
-
-Claude spawns a subagent
-  │
-  ├─→ redirect-builtin-agents.py  Swaps built-in agents for custom ones (Task matcher)
-  ├─→ skill-suggester.py          Suggests skills for Plan agents
-  └─→ inject-cwd.py               Tells subagent the working directory
-
-Claude edits a file (Edit/Write)
-  │
-  ├─→ syntax-validator.py       Validates JSON/YAML/TOML syntax immediately
-  └─→ collect-edited-files.py   Appends path to session temp files
-
-Claude stops responding
-  │
-  ├─→ advisory-test-runner.py   Runs affected tests, injects results
-  ├─→ commit-reminder.py        Advises about uncommitted changes
-  └─→ spec-reminder.py          Advises about spec updates
-```
-
-### Temp File Convention
-
-Edited file paths are stored in session-scoped temp files for downstream consumption:
-- `/tmp/claude-edited-files-{session_id}` — consumed by the `auto-formatter` plugin
-- `/tmp/claude-lint-files-{session_id}` — consumed by the `auto-linter` plugin
-
-### Advisory Test Runner
-
-The test runner maps edited source files to their corresponding test files, runs only affected tests, and injects pass/fail results as `additionalContext`. It never blocks Claude — results are purely informational.
-
-### Skill Suggester
-
-Matches user prompts against keyword maps (phrases + individual terms) for each skill. When a skill matches, it injects a suggestion as `systemMessage` (UserPromptSubmit) or `additionalContext` (SubagentStart) so Claude knows which skill to load.
-
-### Ticket Linker
-
-Detects `#123` references and full GitHub issue/PR URLs in user prompts, fetches the ticket body via `gh`, and injects it as `additionalContext`. Handles up to 3 references per prompt with a 1500-character cap per ticket body.
-
-### Timeouts
-
-| Script | Timeout |
-|--------|---------|
-| redirect-builtin-agents.py | 5s |
-| skill-suggester.py | 3s |
-| ticket-linker.py | 12s |
-| inject-cwd.py | 3s |
-| advisory-test-runner.py | 20s |
-| commit-reminder.py | 8s |
-| spec-reminder.py | 8s |
-| git-state-injector.py | 10s |
-| todo-harvester.py | 8s |
-| syntax-validator.py | 5s |
-| collect-edited-files.py | 3s |
-
-## Documentation
-
-- `AGENT-REDIRECTION.md` — Technical guide to the PreToolUse hook contract for agent redirection
-- `REVIEW-RUBRIC.md` — Quality rubric for agent and skill design, based on Anthropic's prompt engineering documentation
-
-## Plugin Structure
-
-```
-code-directive/
-├── .claude-plugin/
-│   ├── plugin.json              # Plugin metadata
-│   └── commands/
-│       └── debug.md             # /debug slash command
-├── agents/                      # 17 custom agent definitions
-│   ├── architect.md
-│   ├── bash-exec.md
-│   ├── claude-guide.md
-│   ├── debug-logs.md
-│   ├── dependency-analyst.md
-│   ├── doc-writer.md
-│   ├── explorer.md
-│   ├── generalist.md
-│   ├── git-archaeologist.md
-│   ├── migrator.md
-│   ├── perf-profiler.md
-│   ├── refactorer.md
-│   ├── researcher.md
-│   ├── security-auditor.md
-│   ├── spec-writer.md
-│   ├── statusline-config.md
-│   └── test-writer.md
-├── skills/                      # 28 coding reference skills
-│   ├── api-design/
-│   ├── 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/
-│   ├── spec-build/
-│   ├── spec-check/
-│   ├── spec-init/
-│   ├── spec-new/
-│   ├── spec-refine/
-│   ├── spec-review/
-│   ├── spec-update/
-│   ├── specification-writing/
-│   ├── sqlite/
-│   ├── svelte5/
-│   └── testing/
-├── hooks/
-│   └── hooks.json               # All hook registrations (6 events, 12 scripts)
-├── scripts/
-│   ├── advisory-test-runner.py  # Stop: runs affected tests
-│   ├── collect-edited-files.py  # PostToolUse: records edited file paths
-│   ├── commit-reminder.py       # Stop: uncommitted changes advisory
-│   ├── git-state-injector.py    # SessionStart: injects git state
-│   ├── guard-readonly-bash.py   # Read-only bash guard (used by agents)
-│   ├── inject-cwd.py            # SubagentStart: injects working directory
-│   ├── redirect-builtin-agents.py # PreToolUse: agent redirection
-│   ├── skill-suggester.py       # UserPromptSubmit/SubagentStart: skill suggestions
-│   ├── spec-reminder.py         # Stop: spec update advisory
-│   ├── syntax-validator.py      # PostToolUse: JSON/YAML/TOML validation
-│   ├── ticket-linker.py         # UserPromptSubmit: auto-fetch GitHub issues
-│   ├── todo-harvester.py        # SessionStart: TODO/FIXME surfacing
-│   ├── verify-no-regression.py  # Test verification utility
-│   └── verify-tests-pass.py     # Test verification utility
-├── AGENT-REDIRECTION.md         # Agent redirection technical guide
-└── REVIEW-RUBRIC.md             # Agent & skill quality rubric
-```
-
-## Requirements
-
-- Python 3.11+
-- Claude Code with plugin hook support
-- [GitHub CLI](https://cli.github.com/) (`gh`) for ticket-linker functionality

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/hooks/hooks.json

@@ -1,112 +0,0 @@
-{
-	"description": "Code quality hooks and skill suggestions for the CodeDirective project",
-	"hooks": {
-		"PreToolUse": [
-			{
-				"matcher": "Task",
-				"hooks": [
-					{
-						"type": "command",
-						"command": "python3 ${CLAUDE_PLUGIN_ROOT}/scripts/redirect-builtin-agents.py",
-						"timeout": 5
-					}
-				]
-			}
-		],
-		"UserPromptSubmit": [
-			{
-				"matcher": "*",
-				"hooks": [
-					{
-						"type": "command",
-						"command": "python3 ${CLAUDE_PLUGIN_ROOT}/scripts/skill-suggester.py",
-						"timeout": 3
-					},
-					{
-						"type": "command",
-						"command": "python3 ${CLAUDE_PLUGIN_ROOT}/scripts/ticket-linker.py",
-						"timeout": 12
-					}
-				]
-			}
-		],
-		"SubagentStart": [
-			{
-				"matcher": "Plan",
-				"hooks": [
-					{
-						"type": "command",
-						"command": "python3 ${CLAUDE_PLUGIN_ROOT}/scripts/skill-suggester.py",
-						"timeout": 3
-					}
-				]
-			},
-			{
-				"matcher": "",
-				"hooks": [
-					{
-						"type": "command",
-						"command": "python3 ${CLAUDE_PLUGIN_ROOT}/scripts/inject-cwd.py",
-						"timeout": 3
-					}
-				]
-			}
-		],
-		"Stop": [
-			{
-				"matcher": "",
-				"hooks": [
-					{
-						"type": "command",
-						"command": "python3 ${CLAUDE_PLUGIN_ROOT}/scripts/advisory-test-runner.py",
-						"timeout": 20
-					},
-					{
-						"type": "command",
-						"command": "python3 ${CLAUDE_PLUGIN_ROOT}/scripts/commit-reminder.py",
-						"timeout": 8
-					},
-					{
-						"type": "command",
-						"command": "python3 ${CLAUDE_PLUGIN_ROOT}/scripts/spec-reminder.py",
-						"timeout": 8
-					}
-				]
-			}
-		],
-		"SessionStart": [
-			{
-				"matcher": "",
-				"hooks": [
-					{
-						"type": "command",
-						"command": "python3 ${CLAUDE_PLUGIN_ROOT}/scripts/git-state-injector.py",
-						"timeout": 10
-					},
-					{
-						"type": "command",
-						"command": "python3 ${CLAUDE_PLUGIN_ROOT}/scripts/todo-harvester.py",
-						"timeout": 8
-					}
-				]
-			}
-		],
-		"PostToolUse": [
-			{
-				"matcher": "Edit|Write",
-				"hooks": [
-					{
-						"type": "command",
-						"command": "python3 ${CLAUDE_PLUGIN_ROOT}/scripts/syntax-validator.py",
-						"timeout": 5
-					},
-					{
-						"type": "command",
-						"command": "python3 ${CLAUDE_PLUGIN_ROOT}/scripts/collect-edited-files.py",
-						"timeout": 3
-					}
-				]
-			}
-		]
-	}
-}

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/scripts/collect-edited-files.py

@@ -1,46 +0,0 @@
-#!/usr/bin/env python3
-"""
-Collect edited file paths for batch formatting at Stop.
-
-Lightweight PostToolUse hook that appends the edited file path
-to a session-scoped temp file. The auto-formatter Stop hook
-reads this file to know which files need formatting.
-
-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)
-
-    # Write to both formatter and linter temp files (independent pipelines)
-    for prefix in ("claude-edited-files", "claude-lint-files"):
-        tmp_path = f"/tmp/{prefix}-{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/code-directive/scripts/syntax-validator.py

@@ -1,146 +0,0 @@
-#!/usr/bin/env python3
-"""
-Data file syntax validator.
-
-Validates JSON, JSONC, YAML, and TOML files after editing.
-Uses Python stdlib only (plus PyYAML if available).
-
-Reads tool input from stdin, validates syntax, reports errors.
-Non-blocking: always exits 0.
-"""
-
-import json
-import os
-import re
-import sys
-from pathlib import Path
-
-EXTENSIONS = {".json", ".jsonc", ".yaml", ".yml", ".toml"}
-
-
-def strip_jsonc_comments(text: str) -> str:
-    """Remove // and /* */ comments from JSONC text.
-
-    Handles URLs (https://...) by only stripping // comments that are
-    preceded by whitespace or appear at line start, not those inside strings.
-    """
-    # Remove multi-line comments first
-    text = re.sub(r"/\*.*?\*/", "", text, flags=re.DOTALL)
-    # Remove single-line comments: // preceded by start-of-line or whitespace
-    # This avoids stripping :// in URLs
-    text = re.sub(r"(^|[\s,\[\{])//.*$", r"\1", text, flags=re.MULTILINE)
-    return text
-
-
-def validate_json(file_path: str, is_jsonc: bool) -> str:
-    """Validate JSON/JSONC syntax.
-
-    Returns:
-        Error message string, or empty string if valid.
-    """
-    with open(file_path, "r", encoding="utf-8") as f:
-        content = f.read()
-
-    if is_jsonc:
-        content = strip_jsonc_comments(content)
-
-    try:
-        json.loads(content)
-        return ""
-    except json.JSONDecodeError as e:
-        return f"[Syntax] JSON error at line {e.lineno}, col {e.colno}: {e.msg}"
-
-
-def validate_yaml(file_path: str) -> str:
-    """Validate YAML syntax.
-
-    Returns:
-        Error message string, or empty string if valid.
-    """
-    try:
-        import yaml
-    except ImportError:
-        return ""  # PyYAML not available, skip
-
-    try:
-        with open(file_path, "r", encoding="utf-8") as f:
-            yaml.safe_load(f)
-        return ""
-    except yaml.YAMLError as e:
-        if hasattr(e, "problem_mark"):
-            mark = e.problem_mark
-            return f"[Syntax] YAML error at line {mark.line + 1}, col {mark.column + 1}: {e.problem}"
-        return f"[Syntax] YAML error: {e}"
-
-
-def validate_toml(file_path: str) -> str:
-    """Validate TOML syntax.
-
-    Returns:
-        Error message string, or empty string if valid.
-    """
-    try:
-        import tomllib
-    except ImportError:
-        return ""  # Python < 3.11, skip
-
-    try:
-        with open(file_path, "rb") as f:
-            tomllib.load(f)
-        return ""
-    except tomllib.TOMLDecodeError as e:
-        return f"[Syntax] TOML error: {e}"
-
-
-def validate(file_path: str) -> str:
-    """Validate file syntax based on extension.
-
-    Returns:
-        Error message string, or empty string if valid.
-    """
-    ext = Path(file_path).suffix.lower()
-
-    if ext == ".jsonc":
-        return validate_json(file_path, is_jsonc=True)
-    elif ext == ".json":
-        return validate_json(file_path, is_jsonc=False)
-    elif ext in {".yaml", ".yml"}:
-        return validate_yaml(file_path)
-    elif ext == ".toml":
-        return validate_toml(file_path)
-
-    return ""
-
-
-def main():
-    try:
-        input_data = json.load(sys.stdin)
-        tool_input = input_data.get("tool_input", {})
-        file_path = tool_input.get("file_path", "")
-
-        if not file_path:
-            sys.exit(0)
-
-        ext = Path(file_path).suffix.lower()
-        if ext not in EXTENSIONS:
-            sys.exit(0)
-
-        if not os.path.isfile(file_path):
-            sys.exit(0)
-
-        message = validate(file_path)
-
-        if message:
-            print(json.dumps({"additionalContext": message}))
-
-        sys.exit(0)
-
-    except json.JSONDecodeError:
-        sys.exit(0)
-    except Exception as e:
-        print(f"Hook error: {e}", file=sys.stderr)
-        sys.exit(0)
-
-
-if __name__ == "__main__":
-    main()