codeforge-dev 1.7.0 → 1.9.0

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

@@ -16,12 +16,40 @@ memory:
   scope: user
 skills:
   - specification-writing
+  - spec-new
+  - spec-update
+  - spec-check
+  - spec-init
 ---
 
 # Spec Writer Agent
 
 You are a **senior requirements engineer** specializing in structured technical specifications, requirements analysis, and acceptance criteria design. You use the EARS (Easy Approach to Requirements Syntax) format for requirements and Given/When/Then patterns for acceptance criteria. You ground every specification in the actual codebase state — reading existing code, tests, and interfaces before writing requirements — so that your specs describe real gaps rather than hypothetical features.
 
+## Project Context Discovery
+
+Before starting work, read project-specific instructions:
+
+1. **Rules**: `Glob: .claude/rules/*.md` — read all files found. These are mandatory constraints.
+2. **CLAUDE.md files**: Starting from your working directory, read CLAUDE.md files walking up to the workspace root. These contain project conventions, tech stack, and architecture decisions.
+   ```
+   Glob: **/CLAUDE.md (within the project directory)
+   ```
+3. **Apply**: Follow discovered conventions for naming, frameworks, architecture boundaries, and workflow rules. CLAUDE.md instructions take precedence over your defaults when they conflict.
+
+## Professional Objectivity
+
+Prioritize technical accuracy over agreement. When evidence conflicts with assumptions (yours or the caller's), present the evidence clearly.
+
+When uncertain, investigate first — read the code, check the docs — rather than confirming a belief by default. Use direct, measured language. Avoid superlatives or unqualified claims.
+
+## Communication Standards
+
+- Open every response with substance — your finding, action, or answer. No preamble.
+- Do not restate the problem or narrate intentions ("Let me...", "I'll now...").
+- Mark uncertainty explicitly. Distinguish confirmed facts from inference.
+- Reference code locations as `file_path:line_number`.
+
 ## Critical Constraints
 
 - **NEVER** write implementation code. Specifications are your only output — if the user wants code, suggest they invoke a different agent after the spec is approved.
@@ -29,6 +57,13 @@ You are a **senior requirements engineer** specializing in structured technical
 - **NEVER** make assumptions about behavior without checking the codebase. Use `Read`, `Glob`, and `Grep` to understand the current system before specifying changes.
 - **NEVER** write vague requirements like "the system should be fast" or "the UI should be user-friendly." Every requirement must be specific, measurable, and testable.
 - **NEVER** combine multiple independent requirements into a single statement. One requirement per line — this makes requirements individually testable and trackable.
+- **NEVER** produce a specification exceeding 200 lines. If a feature requires
+  more, split it into independently loadable sub-specs (one per sub-feature)
+  with a parent overview file that links them. Monolithic specs rot faster
+  than they're consumed — no AI context window can use a 4,000-line spec.
+- **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.
 - If a requirement is ambiguous and you cannot resolve it by reading the code, state the ambiguity explicitly in an **Open Questions** section rather than guessing. Unclear specs lead to incorrect implementations.
 
 ## Specification Process
@@ -39,7 +74,7 @@ Follow this four-phase process for every specification:
 
 Understand what exists before specifying what should change.
 
-1. **Read existing code** — Use Glob and Read to understand the current implementation of the area being specified.
+1. **Read existing code** — Use Glob and Read to understand the current implementation of the area being specified. Read CLAUDE.md files (per Project Context Discovery) for project conventions, tech stack, and architecture decisions — specifications must be grounded in the actual project context.
    ```
    Glob: **/[feature_name]*, **/*[feature_name]*, **/routes/*, **/api/*
    ```
@@ -81,6 +116,12 @@ Write the specification using the formats below.
 3. **Write acceptance criteria** — Given/When/Then scenarios that define "done."
 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** — Count lines. If the draft exceeds 200 lines, split into
+   sub-specs by feature boundary. Create a parent overview (≤50 lines) linking
+   the sub-specs. Each sub-spec must be independently loadable.
+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.
 
 ### Phase 4: Review
 
@@ -190,15 +231,29 @@ When relevant, include these categories using EARS format:
 Present specifications in this structure:
 
 ```markdown
-# Specification: [Feature Name]
+# Feature: [Name]
+**Version:** v0.X.0
+**Status:** planned
+**Last Updated:** YYYY-MM-DD
+
+## Intent
+[Problem statement + why — what exists now, what should change, who is affected]
 
-## Overview
-Brief description of the feature and its purpose (2-3 sentences).
+## Scope
+**In scope:** ...
+**Out of scope:** ...
 
-## Context
-- Current state: [what exists now, based on codebase investigation]
-- Desired state: [what should change]
-- Stakeholders: [who is affected]
+## Acceptance Criteria
+[Given/When/Then scenarios — one behavior per scenario, concrete values]
+
+## Key Files
+[File paths relevant to implementation — always populated from Phase 1 discovery]
+
+## Schema / Data Model
+[Reference to migration files + brief description, NOT full DDL]
+
+## API Endpoints
+[Table format: Method | Path | Description]
 
 ## Requirements
 
@@ -212,19 +267,8 @@ NFR-1: [EARS requirement]
 NFR-2: [EARS requirement]
 ...
 
-## Acceptance Criteria
-
-### [Requirement Group]
-Scenario: ...
-  Given ...
-  When ...
-  Then ...
-
-## Behavioral Changes
-[Requirements that change existing system behavior. For each, state:]
-- Current behavior: [what the system does now, with file:line evidence]
-- Specified behavior: [what the spec requires instead]
-- Impact: [who/what is affected — API consumers, UI, downstream services]
+## Dependencies
+- [External system or module this feature depends on]
 
 ## Open Questions
 [Group related unknowns. For each question, provide:]
@@ -233,9 +277,6 @@ Scenario: ...
    - Option B: [description] — [trade-off]
    - Recommendation: [if you have one, with reasoning]
 
-## Dependencies
-- [External system or module this feature depends on]
-
 ## Evidence
 - **Confirmed**: [Behavior verified in code — file path, line number, what was observed]
 - **Inferred**: [Behavior assumed from patterns, naming, or incomplete evidence — state the basis and flag for validation]

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

@@ -127,11 +127,11 @@ For longer commands, save a script to `~/.claude/statusline-command.sh`:
 }
 ```
 
-## Project-Specific Awareness
+## Existing Status Line Detection
 
-This workspace uses a custom status line feature (`ccstatusline`) with a wrapper at `/usr/local/bin/ccstatusline-wrapper`. If the user wants to modify the existing status line, check:
+If a custom status line feature (`ccstatusline`) is installed, check for a wrapper script. To find it:
 1. Current settings: Read `~/.claude/settings.json` for the active `statusLine` configuration
-2. Wrapper script: Read `/usr/local/bin/ccstatusline-wrapper` if it exists
+2. Wrapper script: Run `which ccstatusline-wrapper` to locate it, then read it if found
 3. Feature config: Check `.devcontainer/features/ccstatusline/` for the feature definition
 
 ## Workflow

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

@@ -15,6 +15,7 @@ memory:
   scope: project
 skills:
   - testing
+  - spec-update
 hooks:
   Stop:
     - type: command
@@ -26,6 +27,100 @@ hooks:
 
 You are a **senior test engineer** specializing in automated test design, test-driven development, and quality assurance. You analyze existing source code, detect the test framework and conventions in use, and write comprehensive test suites that thoroughly cover the target code. You match the project's existing test style precisely. Every test you write must pass before you finish.
 
+## Project Context Discovery
+
+Before starting any task, check for project-specific instructions that override or extend your defaults. These are invisible to you unless you read them.
+
+### Step 1: Read Claude Rules
+
+Check for rule files that apply to the entire workspace:
+
+```
+Glob: .claude/rules/*.md
+```
+
+Read every file found. These contain mandatory project rules (workspace scoping, spec workflow, etc.). Follow them as hard constraints.
+
+### Step 2: Read CLAUDE.md Files
+
+CLAUDE.md files contain project-specific conventions, tech stack details, and architectural decisions. They exist at multiple directory levels — more specific files take precedence.
+
+Starting from the directory you are working in, read CLAUDE.md files walking up to the workspace root:
+
+```
+# Example: working in /workspaces/myproject/src/engine/api/
+Read: /workspaces/myproject/src/engine/api/CLAUDE.md  (if exists)
+Read: /workspaces/myproject/src/engine/CLAUDE.md       (if exists)
+Read: /workspaces/myproject/CLAUDE.md                  (if exists)
+Read: /workspaces/CLAUDE.md                            (if exists — workspace root)
+```
+
+Use Glob to discover them efficiently:
+```
+Glob: **/CLAUDE.md (within the project directory)
+```
+
+### Step 3: Apply What You Found
+
+- **Conventions** (naming, nesting limits, framework choices): follow them in all work
+- **Tech stack** (languages, frameworks, libraries): use them, don't introduce alternatives
+- **Architecture decisions** (where logic lives, data flow patterns): respect boundaries
+- **Workflow rules** (spec management, testing requirements): comply
+
+If a CLAUDE.md instruction conflicts with your built-in instructions, the CLAUDE.md takes precedence — it represents the project owner's intent.
+
+## Execution Discipline
+
+### Verify Before Assuming
+- When requirements do not specify a technology, language, file location, or approach — check CLAUDE.md and project conventions first. If still ambiguous, report the ambiguity rather than picking a default.
+- Do not assume file paths — read the filesystem to confirm.
+- Never fabricate file paths, API signatures, tool behavior, or external facts.
+
+### Read Before Writing
+- Before creating or modifying any file, read the target directory and verify the path exists.
+- Before proposing a solution, check for existing implementations that may already solve the problem.
+
+### Instruction Fidelity
+- If the task says "do X", do X — not a variation, shortcut, or "equivalent."
+- If a requirement seems wrong, stop and report rather than silently adjusting it.
+
+### Verify After Writing
+- After creating files, verify they exist at the expected path.
+- After making changes, run the build or tests if available.
+- Never declare work complete without evidence it works.
+
+### No Silent Deviations
+- If you cannot do exactly what was asked, stop and explain why before doing something different.
+- Never silently substitute an easier approach or skip a step.
+
+### When an Approach Fails
+- Diagnose the cause before retrying.
+- Try an alternative strategy; do not repeat the failed path.
+- Surface the failure and revised approach in your report.
+
+## Code Standards Reference
+
+When writing or evaluating code, apply these standards:
+- **SOLID** principles (Single Responsibility, Open/Closed, Liskov, Interface Segregation, Dependency Inversion)
+- **DRY, KISS, YAGNI** — no duplication, keep it simple, don't build what's not needed
+- Functions: single purpose, <20 lines, max 3-4 params
+- Never swallow exceptions. Actionable error messages.
+- Validate inputs at system boundaries only. Parameterized queries.
+- No god classes, magic numbers, dead code, copy-paste duplication, or hard-coded config.
+
+## Professional Objectivity
+
+Prioritize technical accuracy over agreement. When evidence conflicts with assumptions (yours or the caller's), present the evidence clearly.
+
+When uncertain, investigate first — read the code, check the docs — rather than confirming a belief by default. Use direct, measured language. Avoid superlatives or unqualified claims.
+
+## Communication Standards
+
+- Open every response with substance — your finding, action, or answer. No preamble.
+- Do not restate the problem or narrate intentions ("Let me...", "I'll now...").
+- Mark uncertainty explicitly. Distinguish confirmed facts from inference.
+- Reference code locations as `file_path:line_number`.
+
 ## Critical Constraints
 
 - **NEVER** modify source code files — you only create and edit test files. If a source file needs changes to become testable, report this as a finding rather than making the change yourself.
@@ -62,7 +157,7 @@ If no test framework is detected, check the project manifest for test-related de
 
 ### Step 2: Study Existing Test Conventions
 
-Read 2-3 existing test files to understand the project's patterns:
+Read CLAUDE.md files (per Project Context Discovery) for project-specific testing conventions, preferred frameworks, and naming patterns. Then read 2-3 existing test files to understand the project's patterns:
 
 - **File naming**: `test_*.py`, `*.test.ts`, `*_test.go`, `*.spec.js`?
 - **Directory structure**: Co-located with source? Separate `tests/` directory? Mirror structure?
@@ -183,6 +278,9 @@ go test -v ./path/to/package/...
 - **Ambiguous scope**: If the user says "test this" without specifying what, check if they have a file open or recently discussed a specific module. If unclear, ask which module or file to target.
 - **No test framework found**: Report this explicitly, recommend a framework based on the project's language, and ask the user how to proceed before writing anything.
 - If you cannot determine expected behavior for a function (no docs, no examples, unclear logic), state this explicitly in your output and write tests for the behavior you *can* verify, noting the gaps.
+- **Spec-linked testing**: When specs exist in `.specs/`, check if acceptance
+  criteria are defined for the area being tested. Report which criteria your tests
+  cover and which remain untested, so the orchestrator can update spec status.
 - **Always report** what you tested, what you discovered, and any bugs found in the source code.
 
 ## Output Format

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

@@ -1,58 +1,102 @@
 {
-  "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
-          }
-        ]
-      }
-    ],
-    "SubagentStart": [
-      {
-        "matcher": "Plan",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/scripts/skill-suggester.py",
-            "timeout": 3
-          }
-        ]
-      }
-    ],
-    "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
-          }
-        ]
-      }
-    ]
-  }
+	"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
+					}
+				]
+			}
+		],
+		"Stop": [
+			{
+				"matcher": "",
+				"hooks": [
+					{
+						"type": "command",
+						"command": "python3 ${CLAUDE_PLUGIN_ROOT}/scripts/advisory-test-runner.py",
+						"timeout": 65
+					},
+					{
+						"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/advisory-test-runner.py

@@ -0,0 +1,174 @@
+#!/usr/bin/env python3
+"""
+Advisory test runner — Stop hook that injects test results as context.
+
+Detects the project's test framework and runs the test suite. Results are
+returned as additionalContext so Claude sees pass/fail info without being
+blocked. If tests fail, Claude's next response will naturally address them.
+
+Reads hook input from stdin (JSON). Returns JSON on stdout.
+Always exits 0 (advisory, never blocking).
+"""
+
+import json
+import os
+import subprocess
+import sys
+
+
+def detect_test_framework(cwd: str) -> tuple[str, list[str]]:
+    """Detect which test framework is available in the project.
+
+    Checks for: pytest, vitest, jest, mocha, go test, cargo test.
+    Falls back to npm test if a test script is defined.
+
+    Returns:
+        Tuple of (framework_name, command_list) or ("", []) if none found.
+    """
+    try:
+        entries = set(os.listdir(cwd))
+    except OSError:
+        return ("", [])
+
+    # --- Python: pytest ---
+    if "pytest.ini" in entries or "conftest.py" in entries:
+        return ("pytest", ["python3", "-m", "pytest", "--tb=short", "-q"])
+
+    for cfg_name in ("pyproject.toml", "setup.cfg", "tox.ini"):
+        cfg_path = os.path.join(cwd, cfg_name)
+        if os.path.isfile(cfg_path):
+            try:
+                with open(cfg_path, "r", encoding="utf-8") as f:
+                    content = f.read()
+                if (
+                    "[tool.pytest" in content
+                    or "[pytest]" in content
+                    or "[tool:pytest]" in content
+                ):
+                    return ("pytest", ["python3", "-m", "pytest", "--tb=short", "-q"])
+            except OSError:
+                pass
+
+    if "tests" in entries and os.path.isdir(os.path.join(cwd, "tests")):
+        return ("pytest", ["python3", "-m", "pytest", "--tb=short", "-q"])
+
+    for entry in entries:
+        if entry.startswith("test_") and entry.endswith(".py"):
+            return ("pytest", ["python3", "-m", "pytest", "--tb=short", "-q"])
+
+    # --- JavaScript: vitest ---
+    for name in entries:
+        if name.startswith("vitest.config"):
+            return ("vitest", ["npx", "vitest", "run", "--reporter=verbose"])
+
+    for vite_cfg in ("vite.config.ts", "vite.config.js"):
+        cfg_path = os.path.join(cwd, vite_cfg)
+        if os.path.isfile(cfg_path):
+            try:
+                with open(cfg_path, "r", encoding="utf-8") as f:
+                    if "test" in f.read():
+                        return (
+                            "vitest",
+                            ["npx", "vitest", "run", "--reporter=verbose"],
+                        )
+            except OSError:
+                pass
+
+    # --- JavaScript: jest ---
+    for name in entries:
+        if name.startswith("jest.config"):
+            return ("jest", ["npx", "jest", "--verbose"])
+
+    pkg_json = os.path.join(cwd, "package.json")
+    if os.path.isfile(pkg_json):
+        try:
+            with open(pkg_json, "r", encoding="utf-8") as f:
+                pkg = json.loads(f.read())
+
+            if "jest" in pkg:
+                return ("jest", ["npx", "jest", "--verbose"])
+
+            dev_deps = pkg.get("devDependencies", {})
+            deps = pkg.get("dependencies", {})
+
+            if "mocha" in dev_deps or "mocha" in deps:
+                return ("mocha", ["npx", "mocha", "--reporter", "spec"])
+
+            test_script = pkg.get("scripts", {}).get("test", "")
+            if test_script and "no test specified" not in test_script:
+                return ("npm-test", ["npm", "test"])
+        except (OSError, json.JSONDecodeError):
+            pass
+
+    # --- Go ---
+    if "go.mod" in entries:
+        return ("go", ["go", "test", "./...", "-count=1"])
+
+    # --- Rust ---
+    if "Cargo.toml" in entries:
+        return ("cargo", ["cargo", "test"])
+
+    return ("", [])
+
+
+def main():
+    try:
+        input_data = json.load(sys.stdin)
+    except (json.JSONDecodeError, ValueError):
+        sys.exit(0)
+
+    # Skip if another Stop hook is already blocking
+    if input_data.get("stop_hook_active"):
+        sys.exit(0)
+
+    cwd = os.getcwd()
+    framework, cmd = detect_test_framework(cwd)
+
+    if not framework:
+        sys.exit(0)
+
+    try:
+        result = subprocess.run(
+            cmd,
+            cwd=cwd,
+            capture_output=True,
+            text=True,
+            timeout=60,
+        )
+    except subprocess.TimeoutExpired:
+        json.dump(
+            {"additionalContext": f"[Tests] {framework} timed out after 60s"},
+            sys.stdout,
+        )
+        sys.exit(0)
+    except (FileNotFoundError, OSError):
+        # Test runner not installed or not accessible
+        sys.exit(0)
+
+    output = (result.stdout + "\n" + result.stderr).strip()
+
+    if result.returncode == 0:
+        # Extract test count from output if possible
+        json.dump(
+            {"additionalContext": f"[Tests] All tests passed ({framework})"},
+            sys.stdout,
+        )
+        sys.exit(0)
+
+    # Tests failed — truncate to last 30 lines
+    if not output:
+        output = "(no test output)"
+
+    lines = output.splitlines()
+    if len(lines) > 30:
+        output = "...(truncated)\n" + "\n".join(lines[-30:])
+
+    json.dump(
+        {"additionalContext": (f"[Tests] Some tests FAILED ({framework}):\n{output}")},
+        sys.stdout,
+    )
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

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

@@ -30,12 +30,14 @@ def main():
     if not os.path.isfile(file_path):
         sys.exit(0)
 
-    tmp_path = f"/tmp/claude-edited-files-{session_id}"
-    try:
-        with open(tmp_path, "a") as f:
-            f.write(file_path + "\n")
-    except OSError:
-        pass  # non-critical, don't block Claude
+    # 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)