codeforge-dev 1.7.0 → 1.8.0

package/.devcontainer/config/{main-system-prompt.md → defaults/main-system-prompt.md}

@@ -396,6 +396,78 @@ offset = len(header) + 1  # null terminator in legacy format
 offset = len(header) + 1  # add one to header length
 </documentation>
 
+<specification_management>
+Specs and project-level docs live in `.specs/` at the project root.
+
+You (the orchestrator) own spec creation and maintenance. Agents do not update
+specs directly — they flag when specs need attention, and you handle it.
+
+Folder structure:
+```
+.specs/
+├── roadmap.md              # What each version delivers and why (≤150 lines)
+├── lessons-learned.md      # Workflow anti-patterns
+├── ci-cd.md                # CI/CD pipeline, environments, deploy process
+├── v0.1.0.md               # Feature spec (single file per version if ≤200 lines)
+├── v0.2.0/                 # Version folder when multiple specs needed
+│   ├── overview.md         # Parent linking sub-specs (≤50 lines)
+│   └── feature-name.md     # Sub-spec per feature (≤200 lines each)
+```
+
+Spec rules:
+- ≤200 lines per spec file. Split by feature boundary if larger; link via
+  a parent overview (≤50 lines). Monolithic specs rot — no AI context window
+  can use a 4,000-line spec.
+- Reference files, don't reproduce them. Write "see `src/engine/db/migrations/002.sql`
+  lines 48-70" — never paste full schemas, SQL DDL, or type definitions. The
+  code is the source of truth; duplicated snippets go stale.
+- Each spec is independently loadable. Include version, status, last-updated,
+  intent, key file paths, and acceptance criteria in every spec file.
+
+Standard template:
+```
+# Feature: [Name]
+**Version:** v0.X.0
+**Status:** implemented | partial | planned
+**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)
+```
+
+As-built workflow (after implementing a feature):
+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
+If no spec exists and the change is substantial, create one or note "spec needed."
+
+Document types — don't mix:
+- Roadmap (`.specs/roadmap.md`): what each version delivers and why. No
+  implementation detail — that belongs in feature specs. Target: ≤150 lines.
+- Feature spec (`.specs/v*.md` or `.specs/vX.Y.0/*.md`): how a feature works.
+  ≤200 lines.
+- CI/CD (`.specs/ci-cd.md`): pipeline stages, environments, deploy process,
+  and automation config. Keep declarative — reference workflow files, don't
+  reproduce them.
+- Lessons learned (`.specs/lessons-learned.md`): workflow anti-patterns.
+
+After a version ships, update feature specs to as-built status. Delete or
+merge superseded planning artifacts — don't accumulate snapshot documents.
+
+Delegate spec writing to the spec-writer agent when creating new specs.
+</specification_management>
+
 <code_standards>
 Files:
 - Small, focused, single reason to change

package/.devcontainer/config/file-manifest.json

@@ -0,0 +1,20 @@
+[
+  {
+    "src": "defaults/settings.json",
+    "dest": "${CLAUDE_CONFIG_DIR}",
+    "enabled": true,
+    "overwrite": "if-changed"
+  },
+  {
+    "src": "defaults/keybindings.json",
+    "dest": "${CLAUDE_CONFIG_DIR}",
+    "enabled": true,
+    "overwrite": "if-changed"
+  },
+  {
+    "src": "defaults/main-system-prompt.md",
+    "dest": "${CLAUDE_CONFIG_DIR}",
+    "enabled": true,
+    "overwrite": "if-changed"
+  }
+]

package/.devcontainer/devcontainer.json

@@ -12,6 +12,11 @@
     "TMPDIR": "/workspaces/.tmp"
   },
 
+  // Feature install order: external runtimes first (Node, uv, Go, Bun),
+  // then Claude Code (needs Node), then custom features.
+  // npm-dependent features (agent-browser, ccusage, ccburn, biome, lsp-servers)
+  // must come after Node. uv-dependent features (ruff, claude-monitor) must
+  // come after uv. notify-hook is last (lightweight, no dependencies).
   "overrideFeatureInstallOrder": [
     "ghcr.io/devcontainers/features/node",
     "ghcr.io/devcontainers/features/github-cli",
@@ -29,6 +34,11 @@
     "./features/ast-grep",
     "./features/tree-sitter",
     "./features/lsp-servers",
+    "./features/ruff",
+    "./features/shfmt",
+    "./features/dprint",
+    "./features/shellcheck",
+    "./features/hadolint",
     "./features/biome",
     "./features/notify-hook"
   ],
@@ -69,6 +79,16 @@
     "./features/tree-sitter": {},
     "./features/lsp-servers": {},
     "./features/agent-browser": {},
+    "./features/ruff": {
+      "version": "latest",
+      "username": "automatic"
+    },
+    "./features/shfmt": {},
+    "./features/dprint": {
+      "username": "automatic"
+    },
+    "./features/shellcheck": {},
+    "./features/hadolint": {},
     "./features/biome": {},
     "./features/notify-hook": {
       "enableBell": true,

package/.devcontainer/docs/configuration-reference.md

@@ -0,0 +1,90 @@
+# Configuration Reference
+
+Quick reference for all CodeForge configuration options.
+
+## Which File to Edit
+
+| Task | File to Edit |
+|------|-------------|
+| Change default model | `config/defaults/settings.json` |
+| Change system prompt | `config/defaults/main-system-prompt.md` |
+| Customize keybindings | `config/defaults/keybindings.json` |
+| Control setup steps | `.env` |
+| Add custom config file | `config/file-manifest.json` |
+| Disable a feature | `devcontainer.json` (set `"version": "none"`) |
+| Disable a plugin | `config/defaults/settings.json` (remove from `enabledPlugins`) |
+| Skip a plugin install | `.env` (`PLUGIN_BLACKLIST`) |
+| Change container memory | `devcontainer.json` (`runArgs`) |
+| Add VS Code extension | `devcontainer.json` (`customizations.vscode.extensions`) |
+
+## `.env` Variables (Setup Behavior)
+
+These control what `setup.sh` does on each container start. Copy `.env.example` to `.env` and customize.
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CLAUDE_CONFIG_DIR` | `/workspaces/.claude` | Where Claude Code config files are stored |
+| `CONFIG_SOURCE_DIR` | `(auto-detected)` | Source directory for config defaults |
+| `SETUP_CONFIG` | `true` | Copy config files per `file-manifest.json` |
+| `SETUP_ALIASES` | `true` | Add cc/claude/ccraw/cc-tools aliases to shell |
+| `SETUP_AUTH` | `true` | Configure Git/NPM auth from `.secrets` file |
+| `SETUP_PLUGINS` | `true` | Install Anthropic plugins + register local marketplace |
+| `SETUP_UPDATE_CLAUDE` | `true` | Background-update Claude Code CLI binary |
+| `SETUP_PROJECTS` | `true` | Auto-detect projects for VS Code Project Manager |
+| `PLUGIN_BLACKLIST` | `""` | Comma-separated plugin names to skip during installation |
+
+## `devcontainer.json` `remoteEnv` (Container Runtime)
+
+These environment variables are set in every terminal session inside the container.
+
+| Variable | Value | Description |
+|----------|-------|-------------|
+| `WORKSPACE_ROOT` | `/workspaces` | Workspace root directory |
+| `CLAUDE_CONFIG_DIR` | `/workspaces/.claude` | Claude Code config directory |
+| `GH_CONFIG_DIR` | `/workspaces/.gh` | GitHub CLI config directory |
+| `TMPDIR` | `/workspaces/.tmp` | Temporary files directory |
+
+## `config/file-manifest.json` (File Copy Rules)
+
+Each entry in the manifest array controls how a config file is deployed:
+
+```json
+{
+  "src": "defaults/settings.json",
+  "dest": "${CLAUDE_CONFIG_DIR}",
+  "destFilename": "settings.json",
+  "overwrite": "if-changed",
+  "enabled": true
+}
+```
+
+| Field | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `src` | Yes | — | Source file path relative to `config/` |
+| `dest` | Yes | — | Destination directory (supports `${CLAUDE_CONFIG_DIR}`, `${WORKSPACE_ROOT}`) |
+| `destFilename` | No | basename of `src` | Override the destination filename |
+| `overwrite` | No | `"if-changed"` | `"always"`, `"never"`, or `"if-changed"` (sha256 comparison) |
+| `enabled` | No | `true` | Set `false` to skip this entry |
+
+## Feature Options
+
+Each feature in `devcontainer.json` supports options defined in its `devcontainer-feature.json`. Common options:
+
+| Option | Description | Used By |
+|--------|-------------|---------|
+| `version` | Tool version to install. `"none"` skips installation. | All local features |
+| `username` | Container user to install for. `"automatic"` auto-detects. | dprint, ruff, ccusage, ccburn, etc. |
+| `shells` | Which shell rc files to modify (`"both"`, `"bash"`, `"zsh"`). | ccusage, ccburn |
+
+## `.secrets` File (Authentication)
+
+Create `.devcontainer/.secrets` with tokens for automatic authentication:
+
+```bash
+GH_TOKEN=ghp_your_token_here
+GH_USERNAME=your-github-username
+GH_EMAIL=your-email@example.com
+NPM_TOKEN=npm_your_token_here
+```
+
+Environment variables with the same names take precedence over `.secrets` file values (useful for Codespaces).

package/.devcontainer/docs/keybindings.md

@@ -0,0 +1,100 @@
+# 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

@@ -0,0 +1,129 @@
+# 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
+```
+
+---
+
+## mcp-reasoner (Enhanced Reasoning)
+
+Adds a reasoning MCP server that gives Claude Code access to structured thinking tools (beam search, Monte Carlo tree search, etc.).
+
+### Enabling
+
+Add to `devcontainer.json` under `"features"`:
+
+```json
+"./features/mcp-reasoner": {}
+```
+
+### Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `version` | `latest` | Version to install. `"none"` to skip. |
+| `username` | `automatic` | Container user to install for |
+
+### Prerequisites
+
+Already met by default container: Node.js LTS is pre-installed.
+
+### How It Works
+
+1. During build, clones and builds the mcp-reasoner Node.js project.
+2. On container start, a post-start hook registers it as an MCP server in `settings.json`.
+3. Claude Code gains access to reasoning tools: `beam_search`, `mcts`, `hypothesis_test`, etc.
+
+### Verification
+
+```bash
+node ~/mcp-reasoner/dist/index.js --help
+```
+
+---
+
+## splitrail (Terminal Splitting)
+
+A terminal multiplexer utility for splitting panes. Useful for Agent Teams workflows.
+
+### Enabling
+
+Add to `devcontainer.json` under `"features"`:
+
+```json
+"./features/splitrail": {}
+```
+
+### Prerequisites
+
+Requires Rust toolchain. Add the Rust devcontainer feature first:
+
+```json
+"ghcr.io/devcontainers/features/rust:1": {}
+```
+
+Then add splitrail to `overrideFeatureInstallOrder` after the Rust feature.
+
+### How It Works
+
+splitrail is a Rust-based tool that provides tmux pane management for Claude Code Agent Teams. It works alongside the tmux feature to provide split-pane terminal sessions.
+
+---
+
+## 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

@@ -0,0 +1,154 @@
+# 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-formatter/        # Batch formatter (Stop hook)
+    ├── auto-linter/           # Batch linter (Stop hook)
+    └── code-directive/        # Agents, skills, hooks
+```
+
+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-formatter@devs-marketplace",
+    "auto-linter@devs-marketplace",
+    "code-directive@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-formatter
+
+**Purpose**: Batch-formats all files edited during a Claude Code session.
+
+**Supported languages**:
+| Language | Formatter |
+|----------|-----------|
+| Python | Ruff |
+| Go | gofmt |
+| JavaScript/TypeScript/CSS/JSON/GraphQL/HTML | Biome |
+| Shell scripts | shfmt |
+| Markdown/YAML/TOML/Dockerfile | dprint |
+| Rust | rustfmt |
+
+**How it works**: Runs as a Stop hook. When Claude Code stops (end of a conversation turn), it checks which files were edited, detects their language, and runs the appropriate formatter. Has a 30-second timeout.
+
+### auto-linter
+
+**Purpose**: Batch-lints all files edited during a Claude Code session.
+
+**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 alongside auto-formatter. Checks edited files and runs the appropriate linter. Results are reported but don't block — they're informational.
+
+### code-directive
+
+**Purpose**: The main intelligence layer — custom agents, coding skills, and behavior hooks.
+
+**Components**:
+- **17 custom agents** — Specialized agent definitions for different task types (architect, test-writer, refactorer, etc.)
+- **16 coding skills** — Domain-specific reference materials (FastAPI, Docker, testing patterns, etc.)
+- **Agent redirection hook** — Transparently swaps built-in agent types to custom agents (e.g., `Explore` → `explorer`, `Plan` → `architect`)
+- **Syntax validation hook** — Validates code syntax before commits
+- **Skill auto-suggestion hook** — Suggests relevant skills based on conversation context
+
+For detailed agent and skill documentation, see the agent markdown files in `plugins/devs-marketplace/plugins/code-directive/agents/` and skill files in `plugins/devs-marketplace/plugins/code-directive/skills/`.