codeforge-dev 1.10.0 → 1.12.0

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

@@ -0,0 +1,250 @@
+# 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/agents/architect.md

@@ -18,6 +18,7 @@ skills:
   - spec-new
   - spec-update
   - spec-init
+  - spec-review
 hooks:
   PreToolUse:
     - matcher: Bash

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/agents/claude-guide.md

@@ -11,7 +11,7 @@ description: >-
   spawning a new instance, check if there is already a running or recently
   completed claude-guide agent that you can resume using the "resume" parameter.
 tools: Glob, Grep, Read, WebFetch, WebSearch
-model: haiku
+model: sonnet
 color: cyan
 memory:
   scope: user
@@ -66,7 +66,7 @@ Direct model interaction via the Claude API (formerly Anthropic API). Covers Mes
 # Project-level configuration (relative to workspace root)
 .claude/settings.json        # Active settings
 .claude/keybindings.json     # Active keybindings
-.claude/system-prompt.md     # Active system prompt
+.claude/main-system-prompt.md # Active system prompt
 CLAUDE.md                    # Project instructions
 
 # DevContainer configuration

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/agents/debug-logs.md

@@ -5,7 +5,7 @@ description: >-
   application frameworks, and system services to identify errors, crashes,
   and performance issues. Reports structured findings with root cause assessment.
 tools: Bash, Read, Glob, Grep
-model: sonnet
+model: opus
 color: red
 skills:
   - debugging

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/agents/dependency-analyst.md

@@ -10,7 +10,7 @@ description: >-
   dependency analysis across Node.js, Python, Rust, or Go ecosystems.
   Reports findings without modifying any files.
 tools: Read, Bash, Glob, Grep
-model: haiku
+model: sonnet
 color: blue
 memory:
   scope: project

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/agents/doc-writer.md

@@ -267,10 +267,10 @@ Follow these principles in all documentation:
 - **Architecture docs requested**: Trace the system's component boundaries, data flows, and key decisions. Produce a document that would onboard a new developer effectively.
 - **No specific request**: Ask the user what documentation they need. If they point to a file or module, offer to add inline documentation to its public API.
 - **Behavior unclear**: If you read a function and cannot determine its exact behavior, document what you can verify and add a `TODO: verify — [specific question]` annotation so a human can fill in the gap.
-- **Version ships** (e.g., "consolidate v0.1.0 docs"): Read all build-time artifacts
-  for the version (architecture docs, decision records, phase plans). Consolidate
-  into a single as-built spec. Delete or merge superseded planning artifacts —
-  don't accumulate snapshot documents. Update the relevant spec in place.
+- **Milestone ships** (e.g., "consolidate milestone docs"): Read all build-time artifacts
+  for the milestone (architecture docs, decision records, phase plans). Consolidate
+  into as-built specs. Delete or merge superseded planning artifacts —
+  don't accumulate snapshot documents. Update the relevant specs in place.
 - **Always report** what was documented, what was verified versus assumed, and what needs human review.
 
 ## Output Format

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/agents/explorer.md

@@ -10,7 +10,7 @@ description: >-
   very thorough. Reports findings with absolute file paths and never
   modifies any files.
 tools: Read, Glob, Grep, Bash
-model: haiku
+model: sonnet
 color: blue
 memory:
   scope: project

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/agents/generalist.md

@@ -8,7 +8,7 @@ description: >-
   any complex task that doesn't fit a specialist agent's domain. Has access
   to all tools and can both read and write files.
 tools: "*"
-model: inherit
+model: opus
 color: green
 memory:
   scope: project
@@ -17,6 +17,7 @@ skills:
   - spec-update
   - spec-check
   - spec-init
+  - spec-review
 ---
 
 # Generalist Agent

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/agents/git-archaeologist.md

@@ -9,7 +9,7 @@ description: >-
   of this file", "who contributed to this module", "recover lost commit",
   "trace this function's evolution", or needs any git history forensics.
 tools: Read, Grep, Bash
-model: haiku
+model: sonnet
 color: blue
 memory:
   scope: project
@@ -52,7 +52,7 @@ Before starting work, read project-specific instructions:
 - **NEVER** change the working tree — no `git checkout`, `git reset`, `git restore`, `git clean`, or `git switch`. Changing the working tree could discard the user's uncommitted work.
 - **NEVER** modify refs — no `git tag`, `git branch -d`, `git branch -m`, or `git update-ref`.
 - **NEVER** modify configuration — no `git config` writes.
-- Your Bash usage is **git-read-only guarded**. Only these git subcommands are permitted: `log`, `blame`, `show`, `diff`, `bisect` (view mode only), `reflog`, `shortlog`, `rev-list`, `rev-parse`, `ls-files`, `ls-tree`, `cat-file`, `name-rev`, `describe`, `merge-base`, `branch -a` / `branch --list`, `remote -v`, `stash list`.
+- Your Bash usage is **git-read-only guarded**. Only these git subcommands are permitted: `log`, `blame`, `show`, `diff`, `bisect` (view mode only), `reflog`, `shortlog`, `rev-list`, `rev-parse`, `ls-files`, `ls-tree`, `cat-file`, `name-rev`, `describe`, `merge-base`, `branch -a` / `branch --list`, `remote -v`, `stash list`, `worktree list`.
 - You may also use `Read`, `Grep`, and non-git Bash commands that are read-only (`wc`, `sort`, `head`, `uniq`).
 
 ## Investigation Workflow

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/agents/researcher.md

@@ -9,7 +9,7 @@ description: >-
   technology comparison, or technical deep-dives. Reports structured findings
   with citations without modifying any files.
 tools: Read, Glob, Grep, WebSearch, WebFetch, Bash
-model: sonnet
+model: opus
 color: cyan
 memory:
   scope: user

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/agents/security-auditor.md

@@ -10,7 +10,7 @@ description: >-
   Reports findings with severity ratings and remediation guidance without
   modifying any files.
 tools: Read, Glob, Grep, Bash
-model: sonnet
+model: opus
 color: red
 memory:
   scope: user

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/agents/spec-writer.md

@@ -21,6 +21,7 @@ skills:
   - spec-check
   - spec-init
   - spec-refine
+  - spec-review
 ---
 
 # Spec Writer Agent
@@ -62,10 +63,9 @@ When uncertain, investigate first — read the code, check the docs — rather t
 - **ALL** requirements you generate MUST be tagged `[assumed]`. You never produce `[user-approved]` requirements — only `/spec-refine` does that after explicit user validation.
 - **ALL** specs you produce MUST carry `**Approval:** draft`. After presenting a draft, state: "This spec requires `/spec-refine` before implementation can begin. All requirements are marked [assumed] until user-approved."
 - **Aim for ~200 lines per spec.** When a spec grows beyond that, recommend
-  splitting into sub-specs in a feature subdirectory with a parent overview
-  that links them. Shorter specs are easier to consume and maintain, but
-  complex features sometimes need more space — don't sacrifice completeness
-  for an arbitrary cap.
+  splitting into separate specs in the domain folder. Shorter specs are
+  easier to consume and maintain, but complex features sometimes need more
+  space — don't sacrifice completeness for an arbitrary cap.
 - **NEVER** reproduce source code, SQL schemas, or type definitions inline.
   Reference file paths instead (e.g., "see `src/engine/db/migrations/002.sql`
   lines 48-70"). The code is the source of truth; duplicated snippets go stale.
@@ -122,9 +122,9 @@ Write the specification using the formats below.
 4. **Define non-functional requirements** — Performance, security, accessibility where relevant.
 5. **List open questions** — Any unresolved decisions or unknowns that need stakeholder input.
 6. **Check length** — If the draft exceeds ~200 lines, consider whether it
-   would be clearer as sub-specs split by feature boundary with a parent
-   overview linking them. Each sub-spec should be independently loadable.
-   If the length is justified by complexity, note it and proceed.
+   would be clearer as separate specs in the domain folder. Each spec
+   should be independently loadable. If the length is justified by
+   complexity, note it and proceed.
 7. **Reference, don't reproduce** — Scan your draft for inline code blocks
    containing schemas, SQL, type definitions, or configuration. Replace with
    file path references and brief descriptions of what's there.
@@ -238,7 +238,7 @@ Present specifications in this structure:
 
 ```markdown
 # Feature: [Name]
-**Version:** v0.X.0
+**Domain:** [domain-name]
 **Status:** planned
 **Last Updated:** YYYY-MM-DD
 **Approval:** draft

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

@@ -40,6 +40,16 @@
 						"timeout": 3
 					}
 				]
+			},
+			{
+				"matcher": "",
+				"hooks": [
+					{
+						"type": "command",
+						"command": "python3 ${CLAUDE_PLUGIN_ROOT}/scripts/inject-cwd.py",
+						"timeout": 3
+					}
+				]
 			}
 		],
 		"Stop": [

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/scripts/git-state-injector.py

@@ -47,20 +47,31 @@ def _cap_lines(text: str, limit: int) -> str:
 
 
 def main():
+    # Parse hook input to get cwd from Claude Code (falls back to os.getcwd())
+    cwd = os.getcwd()
     try:
-        json.load(sys.stdin)
+        input_data = json.load(sys.stdin)
+        cwd = input_data.get("cwd", cwd)
     except (json.JSONDecodeError, ValueError):
         pass
 
-    cwd = os.getcwd()
-
     # Check if we're in a git repo at all
     branch = _run_git(["branch", "--show-current"], cwd)
     if branch is None:
-        # Not a git repo or git not available
+        # Not a git repo or git not available — still inject working directory
+        output = (
+            f"[Git State]\n"
+            f"Working Directory: {cwd} — restrict all file operations to this "
+            f"directory unless explicitly instructed otherwise."
+        )
+        json.dump({"additionalContext": output}, sys.stdout)
         sys.exit(0)
 
     sections = []
+    sections.append(
+        f"Working Directory: {cwd} — restrict all file operations to this "
+        f"directory unless explicitly instructed otherwise."
+    )
     sections.append(f"Branch: {branch or '(detached HEAD)'}")
 
     # Git status

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/scripts/inject-cwd.py

@@ -0,0 +1,37 @@
+#!/usr/bin/env python3
+"""
+CWD injector — SubagentStart hook that tells subagents the working directory.
+
+Reads hook input from stdin (JSON), extracts cwd, and returns it as
+additionalContext so every subagent knows where to scope its work.
+
+Always exits 0 (advisory, never blocking).
+"""
+
+import json
+import os
+import sys
+
+
+def main():
+    cwd = os.getcwd()
+    try:
+        input_data = json.load(sys.stdin)
+        cwd = input_data.get("cwd", cwd)
+    except (json.JSONDecodeError, ValueError):
+        pass
+
+    json.dump(
+        {
+            "additionalContext": (
+                f"Working Directory: {cwd} — restrict all file operations to "
+                f"this directory unless explicitly instructed otherwise."
+            )
+        },
+        sys.stdout,
+    )
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/scripts/skill-suggester.py

@@ -296,6 +296,30 @@ SKILLS = {
         ],
         "terms": ["migrate", "migration", "upgrade"],
     },
+    "spec-build": {
+        "phrases": [
+            "implement the spec",
+            "build from spec",
+            "start building",
+            "spec-build",
+            "implement this feature from the spec",
+            "build what the spec describes",
+            "implement from the spec",
+            "build the feature",
+        ],
+        "terms": ["spec-build"],
+    },
+    "spec-review": {
+        "phrases": [
+            "review the spec",
+            "check spec adherence",
+            "verify implementation",
+            "spec-review",
+            "does code match spec",
+            "audit implementation",
+        ],
+        "terms": ["spec-review"],
+    },
 }
 
 # Pre-compile term patterns for whole-word matching

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/scripts/spec-reminder.py

@@ -109,8 +109,9 @@ def main():
     message = (
         f"[Spec Reminder] Code was modified in {dirs_str} "
         "but no specs were updated. "
-        "Use /spec-update to update the relevant spec, "
-        "/spec-new if no spec exists for this feature, "
+        "Use /spec-review to verify implementation against the spec, "
+        "then /spec-update to close the loop. "
+        "Use /spec-new if no spec exists for this feature, "
         "or /spec-refine if the spec is still in draft status."
     )