codeforge-dev 1.14.1 → 2.0.0

package/.devcontainer/docs/keybindings.md

@@ -1,100 +0,0 @@
-# Keybinding Customization
-
-Claude Code runs inside VS Code's integrated terminal. Some VS Code shortcuts are intercepted before reaching the terminal, conflicting with Claude Code's keybindings.
-
-## Conflicts
-
-| Shortcut | VS Code Action | Claude Code Action |
-|----------|---------------|-------------------|
-| `Ctrl+G` | Go to Line | `chat:externalEditor` |
-| `Ctrl+S` | Save File | `chat:stash` |
-| `Ctrl+T` | Open Symbol | `app:toggleTodos` |
-| `Ctrl+O` | Open File | `app:toggleTranscript` |
-| `Ctrl+B` | Toggle Sidebar | `task:background` |
-| `Ctrl+P` | Quick Open | `chat:modelPicker` |
-| `Ctrl+R` | Open Recent | `history:search` |
-| `Ctrl+F` | Find in Terminal | (navigation) |
-
-## Already Resolved
-
-`Ctrl+P` and `Ctrl+F` are configured to pass through to Claude Code via `terminal.integrated.commandsToSkipShell` in `devcontainer.json`:
-
-```json
-"terminal.integrated.commandsToSkipShell": [
-    "-workbench.action.quickOpen",
-    "-workbench.action.terminal.focusFind"
-]
-```
-
-The `-` prefix removes the shortcut from VS Code's interception list when the terminal is focused.
-
-## Resolving Other Conflicts
-
-### Option 1: Use Meta (Alt) Variants
-
-Claude Code binds Meta (Alt) variants for all shortcuts. Use `Alt+G` instead of `Ctrl+G`, etc. No configuration needed.
-
-### Option 2: Add to VS Code's Skip List
-
-Add more shortcuts to `terminal.integrated.commandsToSkipShell` in `devcontainer.json`:
-
-```json
-"terminal.integrated.commandsToSkipShell": [
-    "-workbench.action.quickOpen",
-    "-workbench.action.terminal.focusFind",
-    "-workbench.action.gotoLine",
-    "-workbench.action.files.save"
-]
-```
-
-Common command IDs:
-| Shortcut | Command ID |
-|----------|-----------|
-| `Ctrl+G` | `workbench.action.gotoLine` |
-| `Ctrl+S` | `workbench.action.files.save` |
-| `Ctrl+T` | `workbench.action.showAllSymbols` |
-| `Ctrl+O` | `workbench.action.files.openFile` |
-| `Ctrl+B` | `workbench.action.toggleSidebarVisibility` |
-| `Ctrl+R` | `workbench.action.openRecent` |
-
-### Option 3: Custom Claude Code Keybindings
-
-Edit `config/defaults/keybindings.json` to remap Claude Code actions to non-conflicting shortcuts:
-
-```json
-{
-  "bindings": [
-    {
-      "key": "ctrl+shift+g",
-      "command": "chat:externalEditor",
-      "description": "Open external editor (remapped from Ctrl+G)"
-    },
-    {
-      "key": "ctrl+shift+s",
-      "command": "chat:stash",
-      "description": "Stash conversation (remapped from Ctrl+S)"
-    }
-  ]
-}
-```
-
-The keybindings file is copied to `/workspaces/.claude/keybindings.json` on container start (controlled by `file-manifest.json`).
-
-## Claude Code Keybinding Reference
-
-Full list of default Claude Code shortcuts (these work when Claude Code has terminal focus):
-
-| Key | Action |
-|-----|--------|
-| `Ctrl+C` / `Esc` | Cancel / Interrupt |
-| `Ctrl+L` | Clear screen |
-| `Ctrl+P` | Model picker |
-| `Ctrl+R` | Search history |
-| `Ctrl+G` | External editor |
-| `Ctrl+S` | Stash conversation |
-| `Ctrl+T` | Toggle todos |
-| `Ctrl+O` | Toggle transcript |
-| `Ctrl+B` | Background current task |
-| `Ctrl+F` | Find in output |
-
-All of these also have `Meta` (Alt) variants that work even when VS Code intercepts the `Ctrl` version.

package/.devcontainer/docs/optional-features.md

@@ -1,64 +0,0 @@
-# Optional Features
-
-CodeForge includes several features that are available but not enabled by default. This guide covers how to enable and configure them.
-
-## mcp-qdrant (Vector Memory for Claude)
-
-Adds persistent vector memory to Claude Code via a Qdrant MCP server. Claude can store and retrieve information across sessions.
-
-### Enabling
-
-Add to `devcontainer.json` under `"features"`:
-
-```json
-"./features/mcp-qdrant": {
-    "collectionName": "my-project-memory",
-    "embeddingModel": "all-MiniLM-L6-v2"
-}
-```
-
-### Options
-
-| Option | Default | Description |
-|--------|---------|-------------|
-| `collectionName` | `agent-memory` | Qdrant collection name |
-| `embeddingModel` | `all-MiniLM-L6-v2` | Embedding model for vector search |
-| `qdrantUrl` | (empty) | Remote Qdrant server URL. If empty, uses local storage. |
-| `qdrantApiKey` | (empty) | API key for remote Qdrant server |
-| `qdrantLocalPath` | `/workspaces/.qdrant/storage` | Local storage path (when no URL set) |
-
-### Supported Embedding Models
-
-- `all-MiniLM-L6-v2` (default, smallest, fastest)
-- `BAAI/bge-small-en-v1.5`
-- `BAAI/bge-base-en-v1.5`
-- `sentence-transformers/all-mpnet-base-v2`
-
-### Prerequisites
-
-Already met by default container: Python 3.14 and uv are pre-installed.
-
-### How It Works
-
-1. During container build, the embedding model is pre-downloaded from GCS (not HuggingFace, to avoid network issues in containers).
-2. On container start, a post-start hook registers the Qdrant MCP server in Claude Code's `settings.json`.
-3. Claude Code can then use `qdrant-store` and `qdrant-find` tools to persist and search memories.
-
-### Verification
-
-```bash
-uvx mcp-server-qdrant --help
-```
-
----
-
-## Disabling Default Features
-
-Any feature can be disabled without removing it from `devcontainer.json` by setting `"version": "none"`:
-
-```json
-"./features/hadolint": { "version": "none" },
-"./features/shellcheck": { "version": "none" }
-```
-
-The feature entry stays in the config for easy re-enabling — just remove `"version": "none"` or set it to `"latest"`.

package/.devcontainer/docs/plugins.md

@@ -1,176 +0,0 @@
-# Plugin System
-
-CodeForge includes a local plugin marketplace that provides specialized tools and hooks for Claude Code.
-
-## Architecture
-
-```
-plugins/devs-marketplace/
-├── .claude-plugin/
-│   └── marketplace.json       # Marketplace manifest (lists all plugins)
-└── plugins/
-    ├── codeforge-lsp/         # LSP language servers
-    ├── ticket-workflow/       # EARS ticket workflow
-    ├── notify-hook/           # Desktop notifications
-    ├── dangerous-command-blocker/  # Safety: block destructive commands
-    ├── protected-files-guard/ # Safety: protect sensitive files
-    ├── auto-code-quality/     # Batch formatter + linter + advisory test runner
-    ├── agent-system/          # 17 custom agents + redirection hooks
-    ├── skill-engine/          # 21 coding skills + auto-suggestion
-    ├── spec-workflow/         # 8 spec lifecycle skills + spec-reminder
-    ├── session-context/       # Git state, TODO harvesting, commit reminders
-    └── workspace-scope-guard/ # Workspace scope enforcement
-```
-
-Each plugin has a `.claude-plugin/plugin.json` manifest defining its name, description, and capabilities.
-
-## Enabling/Disabling Plugins
-
-Plugins are enabled in `config/defaults/settings.json` under `enabledPlugins`:
-
-```json
-"enabledPlugins": [
-    "auto-code-quality@devs-marketplace",
-    "agent-system@devs-marketplace",
-    "skill-engine@devs-marketplace",
-    "spec-workflow@devs-marketplace",
-    "session-context@devs-marketplace"
-]
-```
-
-To disable a plugin, remove its entry from the `enabledPlugins` array.
-
-## PLUGIN_BLACKLIST
-
-To skip a plugin during the installation/registration step (without editing `settings.json`), add it to `PLUGIN_BLACKLIST` in `.env`:
-
-```bash
-PLUGIN_BLACKLIST="ticket-workflow,auto-linter"
-```
-
-This prevents the plugin from being registered on container start but doesn't remove it from `enabledPlugins`.
-
----
-
-## Plugin Reference
-
-### codeforge-lsp
-
-**Purpose**: Provides Language Server Protocol servers for code intelligence.
-
-**Servers**:
-- **Pyright** — Python type checking and completion (`.py`, `.pyi`)
-- **TypeScript Language Server** — TypeScript/JavaScript (`.ts`, `.tsx`, `.js`, `.jsx`, `.mts`, `.cts`, `.mjs`, `.cjs`)
-- **gopls** — Go language server (`.go`, `.mod`, `.sum`)
-
-Claude Code automatically uses these for hover info, go-to-definition, and find-references.
-
-### ticket-workflow
-
-**Purpose**: EARS-based ticket workflow with GitHub integration.
-
-Provides structured ticket management using EARS (Easy Approach to Requirements Syntax) format. Integrates with GitHub Issues for tracking.
-
-**Commands**: `/ticket:new`, `/ticket:work`, `/ticket:review-commit`, `/ticket:create-pr`
-
-### notify-hook
-
-**Purpose**: Desktop notifications when Claude Code finishes responding.
-
-Sends an OSC escape sequence and terminal bell when Claude completes a response, triggering desktop notifications in supported terminals (WezTerm, iTerm2, VS Code with the OSC notifier extension).
-
-**Configuration**: Enabled via `devcontainer.json` feature options:
-```json
-"./features/notify-hook": {
-    "enableBell": true,
-    "enableOsc": true
-}
-```
-
-### dangerous-command-blocker
-
-**Purpose**: Prevents Claude Code from executing destructive bash commands.
-
-**Blocked patterns**:
-- `rm -rf /` and variants
-- `sudo rm` on system directories
-- `chmod 777` on sensitive paths
-- `git push --force` to protected branches
-- `dd` with output to block devices
-- Other destructive system commands
-
-The blocker runs as a PreToolUse hook on Bash commands. It checks the command against a pattern list and rejects matches.
-
-### protected-files-guard
-
-**Purpose**: Prevents Claude Code from modifying sensitive files.
-
-**Protected patterns**:
-- `.env` and `.secrets` files
-- Lock files (`package-lock.json`, `uv.lock`, `Cargo.lock`, etc.)
-- `.git/` directory contents
-- Credential files and SSH keys
-
-Runs as a PreToolUse hook on Write and Edit operations.
-
-### auto-code-quality
-
-**Purpose**: Batch-formats, lints, and runs advisory tests on files edited during a Claude Code session.
-
-**Supported formatters**:
-| Language | Formatter |
-|----------|-----------|
-| Python | Ruff |
-| Go | gofmt |
-| JavaScript/TypeScript/CSS/JSON/GraphQL/HTML | Biome |
-| Shell scripts | shfmt |
-| Markdown/YAML/TOML/Dockerfile | dprint |
-| Rust | rustfmt |
-
-**Supported linters**:
-| Language | Linter |
-|----------|--------|
-| Python | Pyright + Ruff |
-| JavaScript/TypeScript/CSS/GraphQL | Biome |
-| Shell scripts | ShellCheck |
-| Go | go vet |
-| Dockerfile | hadolint |
-| Rust | clippy |
-
-**How it works**: Runs as a Stop hook. When Claude Code stops, it checks which files were edited, detects their language, and runs the appropriate formatter and linter. Also includes an advisory test runner that runs affected tests. Results are informational — they don't block.
-
-### agent-system
-
-**Purpose**: 17 specialized agent definitions with built-in agent redirection.
-
-**Components**:
-- **17 custom agents** — Specialized agent definitions for different task types (architect, explorer, test-writer, refactorer, security-auditor, researcher, doc-writer, etc.)
-- **Agent redirection hook** — Transparently swaps built-in agent types to custom agents (e.g., `Explore` → `explorer`, `Plan` → `architect`)
-- **CWD injection hook** — Injects current working directory into agent prompts
-- **Read-only bash enforcement** — Prevents read-only agents from executing write operations
-
-For detailed agent documentation, see `plugins/devs-marketplace/plugins/agent-system/agents/`.
-
-### skill-engine
-
-**Purpose**: 21 domain-specific coding reference skills with auto-suggestion.
-
-**Skills**: fastapi, svelte5, docker, docker-py, pydantic-ai, sqlite, testing, debugging, security-checklist, refactoring-patterns, git-forensics, performance-profiling, documentation-patterns, migration-patterns, dependency-management, claude-code-headless, claude-agent-sdk, ast-grep-patterns, api-design, skill-building, team
-
-**How it works**: Skills are loaded on demand via the Skill tool. A PreToolUse hook auto-suggests relevant skills based on conversation context.
-
-For skill details, see `plugins/devs-marketplace/plugins/skill-engine/skills/`.
-
-### spec-workflow
-
-**Purpose**: 8 spec lifecycle skills with spec-reminder hook.
-
-**Skills**: spec-new, spec-refine, spec-build, spec-review, spec-update, spec-check, spec-init, specification-writing
-
-**How it works**: Provides a structured specification workflow. A Stop hook reminds users to update specs when code was modified but specs weren't.
-
-### workspace-scope-guard
-
-**Purpose**: Enforces workspace scope by blocking writes outside the working directory and warning on out-of-scope reads.
-
-Runs as a PreToolUse hook on Write, Edit, and Read operations. Compares file paths against the current working directory and rejects modifications to files outside the project scope. Read operations outside scope produce a warning but are not blocked. Resolves symlinks and worktree paths correctly via `os.path.realpath()`.

package/.devcontainer/docs/troubleshooting.md

@@ -1,128 +0,0 @@
-# Troubleshooting
-
-Common issues and solutions for the CodeForge devcontainer.
-
-## Container Build Failures
-
-**Problem**: Container fails to build during feature installation.
-
-- Check Docker has sufficient memory (6GB+ recommended). CodeForge sets `--memory=6g` by default.
-- If a specific feature fails, disable it temporarily by setting `"version": "none"` in `devcontainer.json`.
-- Check internet connectivity — most features download binaries from GitHub releases.
-- If hitting GitHub API rate limits during build, set `GH_TOKEN` or `GITHUB_TOKEN` as an environment variable.
-
-**Problem**: Build is slow or hangs.
-
-- The mcp-qdrant feature downloads an embedding model (~90MB). This is normal on first build.
-- The mcp-reasoner feature clones and builds a Node.js project. This takes 1-2 minutes.
-- Use `"version": "none"` to skip optional features you don't need.
-
-## Authentication Issues
-
-**Problem**: `claude` command fails with authentication error.
-
-- Run `claude` once interactively to complete authentication.
-- If using API key auth, verify `ANTHROPIC_API_KEY` is set correctly.
-- Background update may be in progress — wait 10 seconds and retry.
-
-**Problem**: `gh` CLI not authenticated.
-
-- Run `gh auth status` to check current state.
-- Run `gh auth login` for interactive setup.
-- Or configure `.devcontainer/.secrets` with `GH_TOKEN` for automatic auth on container start.
-- Credentials persist in `/workspaces/.gh/` across rebuilds.
-
-**Problem**: Git push fails with permission error.
-
-- Run `gh auth status` to verify authentication.
-- Check git remote URL: `git remote -v`. HTTPS remotes require `gh` auth; SSH remotes require SSH keys.
-- Verify `git config --global user.name` and `user.email` are set.
-
-**Problem**: NPM publish/install fails with 401.
-
-- Set `NPM_TOKEN` in `.devcontainer/.secrets` or as environment variable.
-- Verify token: `npm whoami`.
-
-## Feature Installation Failures
-
-**Problem**: Feature checksum verification fails.
-
-- This usually means a corrupted download. Rebuild the container to retry.
-- If persistent, the release may have been re-tagged. Try pinning a specific version in `devcontainer.json`.
-
-**Problem**: Feature download fails after retries.
-
-- Check internet connectivity.
-- GitHub may be experiencing issues — check [githubstatus.com](https://www.githubstatus.com/).
-- Set `GH_TOKEN` environment variable to avoid rate limiting.
-
-**Problem**: Permission denied during feature install.
-
-- Features run as root during build. This shouldn't happen in normal use.
-- If modifying features, ensure `install.sh` has `chmod +x` and starts with `#!/bin/bash`.
-
-## Plugin Issues
-
-**Problem**: Plugin not loading or not appearing in Claude Code.
-
-- Check `enabledPlugins` in `config/defaults/settings.json` — the plugin must be listed there.
-- Verify the plugin directory exists under `plugins/devs-marketplace/plugins/`.
-- Run `check-setup` to verify core configuration is correct.
-- Check plugin blacklist: ensure it's not in `PLUGIN_BLACKLIST` in `.env`.
-
-**Problem**: Auto-formatter or auto-linter not running.
-
-- These run on the Stop hook — they only trigger when Claude Code stops (end of conversation turn).
-- Verify the underlying tools are installed: `cc-tools` lists all available tools.
-- Check the 30-second timeout hasn't been exceeded (large file sets may hit this).
-
-## Agent Teams / tmux Issues
-
-**Problem**: Split panes not working.
-
-- Agent Teams requires tmux. Use the **"Claude Teams (tmux)"** terminal profile in VS Code.
-- Verify tmux is installed: `tmux -V`.
-- If using an external terminal, connect via `connect-external-terminal.sh`.
-
-**Problem**: tmux Unicode/emoji rendering broken.
-
-- Ensure locale is set: `echo $LANG` should show `en_US.UTF-8`.
-- If not, run `source ~/.bashrc` or open a new terminal.
-
-## "Command Not Found" Errors
-
-**Problem**: `cc: command not found` or similar.
-
-- Run `source ~/.bashrc` (or `~/.zshrc`) to reload aliases.
-- Or open a new terminal.
-- Verify setup ran: check for `# Claude Code environment and aliases` in your rc file.
-
-**Problem**: Tool not found (e.g., `ruff`, `dprint`).
-
-- Run `cc-tools` to see which tools are installed.
-- Check if the feature was disabled with `"version": "none"` in `devcontainer.json`.
-- Some tools (like `ruff`) install to `~/.local/bin` — ensure it's in your PATH.
-
-## Performance Issues
-
-**Problem**: Container is slow or running out of memory.
-
-- CodeForge defaults to 6GB RAM / 12GB swap. Increase in `devcontainer.json` `runArgs`.
-- Disable features you don't need with `"version": "none"`.
-- The background Claude Code update runs once on startup — it's not persistent.
-
-**Problem**: Slow startup.
-
-- First start is slower due to `postStartCommand` running all setup scripts.
-- Subsequent starts skip unchanged config files (sha256 comparison).
-- Disable steps you don't need via `.env` (e.g., `SETUP_PROJECTS=false`).
-
-## How to Reset to Defaults
-
-1. **Reset config files**: Delete `/workspaces/.claude/` and restart the container. `setup-config.sh` will recopy all files from `config/defaults/`.
-
-2. **Reset aliases**: Delete the `# Claude Code environment and aliases` block from `~/.bashrc` and `~/.zshrc`, then run `bash /workspaces/.devcontainer/scripts/setup-aliases.sh`.
-
-3. **Full reset**: Rebuild the container from scratch (VS Code: "Dev Containers: Rebuild Container").
-
-4. **Reset a single feature**: Set it to `"version": "none"`, rebuild, then set it back to the desired version and rebuild again.

package/.devcontainer/scripts/setup-symlink-claude.sh

@@ -1,36 +0,0 @@
-#!/bin/bash
-# Symlink $HOME/.claude → $CLAUDE_CONFIG_DIR so third-party tools
-# (ccburn, ccusage, etc.) that hardcode ~/.claude can find auth and config.
-
-CLAUDE_DIR="${CLAUDE_CONFIG_DIR:=/workspaces/.claude}"
-HOME_CLAUDE="$HOME/.claude"
-
-echo "[setup-symlink] Ensuring $HOME_CLAUDE → $CLAUDE_DIR ..."
-
-# Already a correct symlink — nothing to do
-if [ -L "$HOME_CLAUDE" ]; then
-    CURRENT_TARGET="$(readlink "$HOME_CLAUDE")"
-    if [ "$CURRENT_TARGET" = "$CLAUDE_DIR" ]; then
-        echo "[setup-symlink] Symlink already correct, skipping"
-        exit 0
-    fi
-    # Points somewhere else — remove stale symlink
-    echo "[setup-symlink] Removing stale symlink ($CURRENT_TARGET)"
-    rm "$HOME_CLAUDE"
-fi
-
-# Real directory exists — merge contents into target, then remove
-if [ -d "$HOME_CLAUDE" ]; then
-    echo "[setup-symlink] Moving existing $HOME_CLAUDE contents into $CLAUDE_DIR"
-    mkdir -p "$CLAUDE_DIR"
-    # Copy contents preserving attributes; skip files that already exist in target
-    cp -rn "$HOME_CLAUDE/." "$CLAUDE_DIR/" 2>/dev/null || true
-    rm -rf "$HOME_CLAUDE"
-fi
-
-# Ensure target exists
-mkdir -p "$CLAUDE_DIR"
-
-# Create symlink
-ln -s "$CLAUDE_DIR" "$HOME_CLAUDE"
-echo "[setup-symlink] Created symlink: $HOME_CLAUDE → $CLAUDE_DIR"