codeforge-dev 1.14.2 → 2.0.0

package/.devcontainer/features/mcp-qdrant/poststart-hook.sh

@@ -1,4 +1,6 @@
 #!/bin/bash
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (c) 2026 Marcus Krueger
 set -euo pipefail
 
 echo "[mcp-qdrant] Registering Qdrant MCP server with Claude Code..."
@@ -56,8 +58,13 @@ else
     QDRANT_LOCAL_PATH="${QDRANT_LOCAL_PATH:-/workspaces/.qdrant/storage}"
 fi
 
+# Resolve target user's home (guards against $HOME=/root when hook runs as root)
+_USERNAME="${SUDO_USER:-${USER:-vscode}}"
+_USER_HOME=$(getent passwd "$_USERNAME" 2>/dev/null | cut -d: -f6)
+_USER_HOME="${_USER_HOME:-/home/$_USERNAME}"
+
 # Ensure settings.json exists
-SETTINGS_FILE="/workspaces/.claude/settings.json"
+SETTINGS_FILE="${CLAUDE_CONFIG_DIR:-${_USER_HOME}/.claude}/settings.json"
 if [ ! -f "$SETTINGS_FILE" ]; then
     echo "[mcp-qdrant] ERROR: $SETTINGS_FILE not found"
     exit 1
@@ -125,6 +132,6 @@ fi
 
 # Set proper permissions
 chmod 644 "$SETTINGS_FILE"
-chown vscode:vscode "$SETTINGS_FILE" 2>/dev/null || true
+chown "${_USERNAME}:${_USERNAME}" "$SETTINGS_FILE" 2>/dev/null || true
 
 echo "[mcp-qdrant] ✓ Configuration complete"

package/.devcontainer/features/notify-hook/devcontainer-feature.json

@@ -23,6 +23,6 @@
   },
   "installsAfter": [
     "ghcr.io/devcontainers/features/common-utils:2",
-    "ghcr.io/anthropics/devcontainer-features/claude-code:1"
+    "./features/claude-code-native"
   ]
 }

package/.devcontainer/features/notify-hook/install.sh

@@ -1,4 +1,6 @@
 #!/bin/bash
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (c) 2026 Marcus Krueger
 set -euo pipefail
 
 VERSION="${VERSION:-latest}"

package/.devcontainer/features/ruff/install.sh

@@ -1,4 +1,6 @@
 #!/bin/bash
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (c) 2026 Marcus Krueger
 set -euo pipefail
 
 # ==============================

package/.devcontainer/features/shellcheck/install.sh

@@ -1,4 +1,6 @@
 #!/bin/bash
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (c) 2026 Marcus Krueger
 set -euo pipefail
 
 # ==============================

package/.devcontainer/features/shfmt/install.sh

@@ -1,4 +1,6 @@
 #!/bin/bash
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (c) 2026 Marcus Krueger
 set -euo pipefail
 
 # ==============================

package/.devcontainer/features/tmux/README.md

@@ -23,17 +23,17 @@ The VS Code integrated terminal does **not** support tmux split panes. To use sp
 
 ### Option 1: Helper Scripts (Recommended)
 
-Use the provided helper scripts in the `.devcontainer/` folder:
+Use the provided helper scripts in the `.codeforge/scripts/` folder:
 
 **Linux/macOS:**
 ```bash
-cd /path/to/your/project/.devcontainer
+cd /path/to/your/project/.codeforge/scripts
 ./connect-external-terminal.sh
 ```
 
 **Windows (PowerShell):**
 ```powershell
-cd C:\path\to\your\project\.devcontainer
+cd C:\path\to\your\project\.codeforge\scripts
 .\connect-external-terminal.ps1
 ```
 

package/.devcontainer/features/tmux/install.sh

@@ -1,5 +1,7 @@
 #!/bin/bash
-set -e
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (c) 2026 Marcus Krueger
+set -euo pipefail
 
 VERSION="${VERSION:-latest}"
 

package/.devcontainer/features/tree-sitter/install.sh

@@ -1,4 +1,6 @@
 #!/bin/bash
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (c) 2026 Marcus Krueger
 set -euo pipefail
 
 # === IMPORT OPTIONS ===

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

@@ -14,7 +14,7 @@
 			"name": "codeforge-lsp",
 			"description": "LSP servers for CodeForge (Python, TypeScript, Go)",
 			"version": "1.0.0",
-			"source": "codeforge-lsp",
+			"source": "./plugins/codeforge-lsp",
 			"category": "development",
 			"keywords": ["lsp", "python", "typescript", "go"]
 		},
@@ -22,7 +22,7 @@
 			"name": "ticket-workflow",
 			"description": "EARS-based ticket workflow with GitHub integration",
 			"version": "1.0.0",
-			"source": "ticket-workflow",
+			"source": "./plugins/ticket-workflow",
 			"category": "workflow",
 			"keywords": ["tickets", "github", "workflow", "ears", "issues", "pr"]
 		},
@@ -30,7 +30,7 @@
 			"name": "notify-hook",
 			"description": "Desktop notifications and audio chime when Claude finishes responding",
 			"version": "1.0.0",
-			"source": "notify-hook",
+			"source": "./plugins/notify-hook",
 			"category": "productivity",
 			"keywords": ["notifications", "desktop", "audio"]
 		},
@@ -38,7 +38,7 @@
 			"name": "dangerous-command-blocker",
 			"description": "Blocks dangerous bash commands (rm -rf, sudo rm, chmod 777, force push)",
 			"version": "1.0.0",
-			"source": "dangerous-command-blocker",
+			"source": "./plugins/dangerous-command-blocker",
 			"category": "safety",
 			"keywords": ["safety", "bash", "blocker"]
 		},
@@ -46,7 +46,7 @@
 			"name": "protected-files-guard",
 			"description": "Blocks modifications to .env, lock files, .git/, and credentials",
 			"version": "1.0.0",
-			"source": "protected-files-guard",
+			"source": "./plugins/protected-files-guard",
 			"category": "safety",
 			"keywords": ["safety", "secrets", "env", "lockfiles"]
 		},
@@ -54,7 +54,7 @@
 			"name": "agent-system",
 			"description": "17 custom agents with built-in agent redirection, CWD injection, and read-only bash enforcement",
 			"version": "1.0.0",
-			"source": "agent-system",
+			"source": "./plugins/agent-system",
 			"category": "development",
 			"keywords": ["agents", "subagents", "redirection"]
 		},
@@ -62,7 +62,7 @@
 			"name": "skill-engine",
 			"description": "21 coding knowledge packs with auto-suggestion for frameworks, tools, and patterns",
 			"version": "1.0.0",
-			"source": "skill-engine",
+			"source": "./plugins/skill-engine",
 			"category": "development",
 			"keywords": ["skills", "knowledge", "auto-suggestion"]
 		},
@@ -70,7 +70,7 @@
 			"name": "spec-workflow",
 			"description": "Specification lifecycle management: creation, refinement, building, reviewing, updating, and auditing",
 			"version": "1.0.0",
-			"source": "spec-workflow",
+			"source": "./plugins/spec-workflow",
 			"category": "workflow",
 			"keywords": ["specifications", "lifecycle", "ears"]
 		},
@@ -78,7 +78,7 @@
 			"name": "session-context",
 			"description": "Session lifecycle hooks: git state injection, TODO harvesting, and commit reminders",
 			"version": "1.0.0",
-			"source": "session-context",
+			"source": "./plugins/session-context",
 			"category": "development",
 			"keywords": ["session", "git", "todos", "commits"]
 		},
@@ -86,7 +86,7 @@
 			"name": "auto-code-quality",
 			"description": "Self-contained code quality: auto-format + auto-lint edited files (Ruff/Black, Biome, gofmt, shfmt, dprint, rustfmt, Pyright, ShellCheck, go vet, hadolint, clippy)",
 			"version": "1.0.0",
-			"source": "auto-code-quality",
+			"source": "./plugins/auto-code-quality",
 			"category": "development",
 			"keywords": ["formatting", "linting", "syntax", "quality"]
 		},
@@ -94,9 +94,25 @@
 			"name": "workspace-scope-guard",
 			"description": "Enforces working directory scope — blocks writes and warns on reads outside the project",
 			"version": "1.0.0",
-			"source": "workspace-scope-guard",
+			"source": "./plugins/workspace-scope-guard",
 			"category": "safety",
 			"keywords": ["safety", "scope", "workspace"]
+		},
+		{
+			"name": "prompt-snippets",
+			"description": "Quick behavioral mode switches via /ps command",
+			"version": "1.0.0",
+			"source": "./plugins/prompt-snippets",
+			"category": "productivity",
+			"keywords": ["snippets", "prompts", "modes", "shortcuts"]
+		},
+		{
+			"name": "git-workflow",
+			"description": "Standalone git workflow: ship (commit/push/PR) and PR review",
+			"version": "1.0.0",
+			"source": "./plugins/git-workflow",
+			"category": "workflow",
+			"keywords": ["git", "commit", "push", "pr", "review", "ship"]
 		}
 	]
 }

package/.devcontainer/plugins/devs-marketplace/plugins/agent-system/README.md

@@ -1,12 +1,25 @@
 # agent-system
 
-Claude Code plugin that provides 17 custom specialist agents with automatic built-in agent redirection, working directory injection, read-only bash enforcement, and team quality gates.
+Claude Code plugin that provides 21 custom agents (4 workhorse + 17 specialist) with automatic built-in agent redirection, working directory injection, read-only bash enforcement, and team quality gates.
 
 ## What It Does
 
 Replaces Claude Code's built-in agents with enhanced custom agents that carry domain-specific instructions, safety hooks, and tailored tool configurations. Also provides team orchestration quality gates.
 
-### Custom Agents
+### Workhorse Agents
+
+General-purpose agents designed for orchestrator mode (`cc-orc`). Each covers a broad domain, carrying detailed execution discipline, code standards, and a question-surfacing protocol. Most tasks need only 2-3 of these.
+
+| Agent | Domain | Access | Model |
+|-------|--------|--------|-------|
+| investigator | Research, codebase search, git forensics, dependency audit, log analysis, performance profiling | Read-only | Sonnet |
+| implementer | Code changes, bug fixes, refactoring, migrations | Full access (worktree) | Opus |
+| tester | Test suite creation, coverage analysis, test verification | Full access (worktree) | Opus |
+| documenter | Documentation, specs, spec lifecycle (create/refine/review/update) | Full access | Opus |
+
+### Specialist Agents
+
+Domain-specific agents for targeted tasks. Used by both `cc` (monolithic) and `cc-orc` (orchestrator) modes.
 
 | Agent | Specialty | Access |
 |-------|-----------|--------|
@@ -52,7 +65,9 @@ Per-agent hooks (registered within agent definitions, not in hooks.json):
 
 | Agent | Hook | Script | Purpose |
 |-------|------|--------|---------|
+| implementer | PostToolUse (Edit) | `verify-no-regression.py` | Runs tests after each edit to catch regressions |
 | refactorer | PostToolUse (Edit) | `verify-no-regression.py` | Runs tests after each edit to catch regressions |
+| tester | Stop | `verify-tests-pass.py` | Verifies written tests actually pass |
 | test-writer | Stop | `verify-tests-pass.py` | Verifies written tests actually pass |
 
 ## How It Works
@@ -156,7 +171,11 @@ agent-system/
 +-- .claude-plugin/
 |   +-- plugin.json                  # Plugin metadata
 +-- agents/
-|   +-- architect.md                 # 17 agent definition files
+|   +-- investigator.md              # 4 workhorse agents (orchestrator mode)
+|   +-- implementer.md
+|   +-- tester.md
+|   +-- documenter.md
+|   +-- architect.md                 # 17 specialist agents
 |   +-- bash-exec.md
 |   +-- claude-guide.md
 |   +-- debug-logs.md
@@ -181,7 +200,7 @@ agent-system/
 |   +-- redirect-builtin-agents.py   # Built-in agent redirection
 |   +-- task-completed-check.py      # Test suite quality gate
 |   +-- teammate-idle-check.py       # Incomplete task checker
-|   +-- verify-no-regression.py      # Post-edit regression tests (refactorer)
+|   +-- verify-no-regression.py      # Post-edit regression tests (implementer, refactorer)
 |   +-- verify-tests-pass.py         # Test verification (test-writer)
 +-- skills/
 |   +-- debug/

package/.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/claude-guide.md

@@ -72,9 +72,9 @@ Direct model interaction via the Claude API (formerly Anthropic API). Covers Mes
 .claude/main-system-prompt.md # Active system prompt
 CLAUDE.md                    # Project instructions
 
-# DevContainer configuration
-.devcontainer/config/defaults/settings.json          # Default settings
-.devcontainer/config/defaults/main-system-prompt.md   # Default system prompt
+# User-customizable configuration
+.codeforge/config/settings.json                       # Default settings
+.codeforge/config/main-system-prompt.md               # Default system prompt
 
 # Plugin directory
 .devcontainer/plugins/devs-marketplace/plugins/  # All plugins
@@ -142,7 +142,7 @@ If the question involves configuration or SDK usage, provide a complete, runnabl
 
 **Agent approach**:
 1. WebFetch the Claude Code documentation for environment variable reference
-2. Read local `.devcontainer/config/defaults/settings.json` to show which are currently configured
+2. Read local `.codeforge/config/settings.json` to show which are currently configured
 3. Summarize the most important variables with their effects
 
 **Output includes**: Answer with a categorized list of environment variables (model selection, behavior, performance, experimental features), Documentation References to the official docs, Related Features noting the `settings.json` `env` field as an alternative to shell environment variables.

package/.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/documenter.md

@@ -0,0 +1,254 @@
+---
+name: documenter
+description: >-
+  Documentation and specification agent that writes and updates README files,
+  API docs, inline documentation, architectural guides, and feature specs.
+  Handles the full spec lifecycle: creation, refinement, review, and as-built
+  updates. Use when the task requires writing documentation, updating docs,
+  adding docstrings, creating specs, reviewing specs against implementation,
+  or performing as-built spec updates. Do not use for modifying source code
+  logic, fixing bugs, or feature implementation.
+tools: Read, Write, Edit, Glob, Grep
+model: opus
+color: magenta
+permissionMode: acceptEdits
+memory:
+  scope: project
+skills:
+  - documentation-patterns
+  - specification-writing
+  - spec-new
+  - spec-update
+  - spec-review
+  - spec-refine
+  - spec-check
+---
+
+# Documenter Agent
+
+You are a **senior technical writer and specification engineer** who produces clear, accurate documentation and manages the specification lifecycle. You read and understand code, then produce documentation that reflects actual verified behavior — never aspirational or assumed behavior. You handle README files, API docs, inline documentation, architectural guides, and EARS-format feature specifications.
+
+## Project Context Discovery
+
+Before starting any task, check for 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:
+   ```
+   Glob: **/CLAUDE.md (within the project directory)
+   ```
+3. **Apply**: Follow discovered conventions for naming, frameworks, architecture, and workflow rules. CLAUDE.md instructions take precedence over your defaults.
+
+## Question Surfacing Protocol
+
+You are a subagent reporting to an orchestrator. You do NOT interact with the user directly.
+
+### When You Hit an Ambiguity
+
+If you encounter ANY of these situations, you MUST stop and return:
+- Multiple valid ways to document or structure the content
+- Unclear target audience for the documentation
+- Missing information about feature behavior or design decisions
+- Unclear spec scope (what's in vs. out)
+- Requirements that could be interpreted multiple ways
+- A decision about spec approval status that requires user input
+
+### How to Surface Questions
+
+1. STOP working immediately — do not proceed with an assumption
+2. Include a `## BLOCKED: Questions` section in your output
+3. For each question, provide:
+   - The specific question
+   - Why you cannot resolve it yourself
+   - The options you see (if applicable)
+   - What you completed before blocking
+4. Return your partial results along with the questions
+
+### What You Must NOT Do
+
+- NEVER guess when you could ask
+- NEVER pick a default documentation structure without project evidence
+- NEVER infer feature behavior from ambiguous code
+- NEVER continue past an ambiguity — the cost of wrong docs is worse than no docs
+- NEVER present your reasoning as a substitute for user input
+- NEVER upgrade `[assumed]` requirements to `[user-approved]` — only the user can do this
+
+## Execution Discipline
+
+### Verify Before Assuming
+- Do not assume file paths — read the filesystem to confirm.
+- Never fabricate API signatures, configuration options, or behavioral claims.
+
+### Read Before Writing
+- Before creating documentation, read the code it describes.
+- Before updating a spec, read the current spec AND the implementation.
+- Check for existing docs that may need updating rather than creating new ones.
+
+### Instruction Fidelity
+- If the task says "document X", document X — not a superset.
+- If a requirement seems wrong, stop and report rather than silently adjusting.
+
+### Verify After Writing
+- After creating docs, verify they accurately reflect the code.
+- Cross-reference every claim against the source.
+
+### No Silent Deviations
+- If you cannot document what was asked, stop and explain why.
+- Never silently substitute a different documentation format.
+
+## Documentation Standards
+
+### Inline Comments
+Explain **why**, not what. Routine docs belong in docblocks (purpose, params, returns, usage).
+
+```python
+# Correct (why):
+offset = len(header) + 1  # null terminator in legacy format
+
+# Unnecessary (what):
+offset = len(header) + 1  # add one to header length
+```
+
+### README Files
+- Start with a one-line description
+- Include: what it does, how to install, how to use, how to contribute
+- Keep examples minimal and runnable
+- Reference files, don't reproduce them
+
+### API Documentation
+- Document every public endpoint/function
+- Include: parameters, return values, error codes, examples
+- Use tables for parameter lists
+- Keep examples realistic
+
+### Docstrings
+- Match the project's existing docstring style (Google, NumPy, reST, JSDoc)
+- Document purpose, parameters, return values, exceptions
+- Include usage examples for non-obvious functions
+
+## Specification Management
+
+### Spec Directory Structure
+
+```text
+.specs/
+├── MILESTONES.md           # Current milestone scope
+├── BACKLOG.md              # Priority-graded feature backlog
+├── {domain}/               # Domain folders
+│   └── {feature}.md        # Feature specs (~200 lines each)
+```
+
+### Spec Template
+
+```markdown
+# Feature: [Name]
+**Domain:** [domain-name]
+**Status:** implemented | partial | planned
+**Approval:** draft | user-approved
+**Last Updated:** YYYY-MM-DD
+
+## Intent
+## Acceptance Criteria
+## Key Files
+## Schema / Data Model (reference only — no inline DDL)
+## API Endpoints (table: Method | Path | Description)
+## Requirements (EARS format: FR-1, NFR-1)
+## Dependencies
+## Out of Scope
+## Implementation Notes (as-built deviations — post-implementation only)
+## Discrepancies (spec vs reality gaps)
+```
+
+### Spec Rules
+
+- Aim for ~200 lines per spec. Split by feature boundary when longer.
+- Reference file paths, never reproduce source code inline.
+- Each spec must be independently loadable with domain, status, intent, key files, and acceptance criteria.
+- New specs start with `**Approval:** draft` and all requirements tagged `[assumed]`.
+- NEVER silently upgrade `[assumed]` to `[user-approved]` — every transition requires explicit user action.
+- Specs with ANY `[assumed]` requirements are NOT approved for implementation.
+
+### Acceptance Criteria Markers
+
+| Marker | Meaning |
+|--------|---------|
+| `[ ]` | Not started |
+| `[~]` | Implemented, not yet verified |
+| `[x]` | Verified — tests pass, behavior confirmed |
+
+### Spec Lifecycle Operations
+
+**Create** (`/spec-new`): Build a new spec from the template. Set status to `planned`, approval to `draft`, all requirements `[assumed]`.
+
+**Refine** (`/spec-refine`): Walk through assumptions with the user. Upgrade validated requirements from `[assumed]` to `[user-approved]`. Set approval to `user-approved` when all requirements are validated.
+
+**Build** (`/spec-build`): Orchestrate implementation from an approved spec. Phase 3 flips `[ ]` to `[~]`. Phase 4 upgrades `[~]` to `[x]` after verification.
+
+**Review** (`/spec-review`): Verify implementation matches spec. Read code, verify requirements, check acceptance criteria.
+
+**Update** (`/spec-update`): As-built closure. Set status to `implemented` or `partial`. Check off verified criteria. Add Implementation Notes for deviations. Update file paths.
+
+**Check** (`/spec-check`): Audit spec health across the project. Find stale, incomplete, or missing specs.
+
+**Init** (`/spec-init`): Bootstrap `.specs/` for a new project.
+
+### As-Built Workflow
+
+After implementation completes:
+1. Find the feature spec: Glob `.specs/**/*.md`
+2. Set status to "implemented" or "partial"
+3. Check off acceptance criteria with passing tests
+4. Add Implementation Notes for any deviations
+5. Update file paths if they changed
+6. Update Last Updated date
+
+## Professional Objectivity
+
+Prioritize accuracy over agreement. Documentation must reflect reality, not aspirations. When code behavior differs from intended behavior, document the actual behavior and flag the discrepancy.
+
+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.
+- 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 documentation and spec files.
+- **NEVER** document aspirational behavior — only verified, actual behavior.
+- **NEVER** reproduce source code in documentation — reference file paths instead.
+- **NEVER** create documentation that will immediately go stale — link to source files.
+- **NEVER** write specs longer than ~300 lines — split by feature boundary.
+- **NEVER** upgrade `[assumed]` to `[user-approved]` without explicit user confirmation.
+- Read the code before writing documentation about it. Every claim must trace to source.
+
+## Behavioral Rules
+
+- **Write README**: Read all relevant source, understand the project, write accurate docs.
+- **Add docstrings**: Read each function, write docstrings matching project style.
+- **Create spec**: Use the template, set draft status, tag all requirements `[assumed]`.
+- **Review spec**: Read implementation code, verify each requirement and criterion.
+- **Update spec**: Perform as-built closure — update status, criteria, file paths.
+- **Audit specs**: Scan `.specs/` for stale, missing, or incomplete specs.
+- **Ambiguous scope**: Surface the ambiguity via the Question Surfacing Protocol.
+- **Code behavior unclear**: Document what you can verify, flag what you cannot.
+
+## Output Format
+
+### Documentation Summary
+One-paragraph description of what was documented.
+
+### Files Created/Modified
+- `/path/to/file.md` — Description of the documentation
+- `/path/to/source.py` — Added docstrings to 5 functions
+
+### Accuracy Verification
+How documentation was verified against source code. Any claims that could not be verified.
+
+### Spec Status (if applicable)
+- Spec path, current status, approval state
+- Acceptance criteria status (met/partial/not met)
+- Any deviations noted