codeforge-dev 1.13.0 → 1.14.2

package/.devcontainer/CHANGELOG.md

@@ -1,8 +1,152 @@
 # CodeForge Devcontainer Changelog
 
-## [v1.13.0] - 2026-02-21
+## [v1.14.2] - 2026-02-24
+
+### Fixed
+
+#### CI: Release Workflow (v1.14.1)
+- **test.js** — settings.json path updated from `config/settings.json` to `config/defaults/settings.json` to match config externalization refactor
+- **test.js** — Test 5 (executable check) result now included in exit condition; previously a failure was logged but did not affect the exit code
+- **setup.js** — file permissions changed from 644 to 755 (executable) to match shebang and `bin` declaration in package.json
+
+#### CI: Publish DevContainer Features Workflow (v1.14.1)
+- **features/README.md** — removed from features directory; `devcontainers/action@v1` treated it as a feature subdirectory and failed looking for `README.md/devcontainer-feature.json`
+- **11 devcontainer-feature.json files** — removed `"maintainer"` field (not in the DevContainer Feature spec schema, causing strict validation failure): ast-grep, ccburn, ccms, ccstatusline, ccusage, chromaterm, claude-monitor, claude-session-dashboard, lsp-servers, mcp-qdrant, tree-sitter
+
+#### CI: Publish DevContainer Features Workflow (v1.14.2)
+- **6 devcontainer-feature.json files** — removed `"proposals"` field that coexisted with `"enum"` on the same option (spec schema treats them as mutually exclusive via `anyOf`): ccburn, ccusage, claude-monitor, claude-session-dashboard, mcp-qdrant, tree-sitter
+
+#### Docs
+- **Active sidebar item** — increased background opacity from 0.08 to 0.14, added `font-weight: 600` and `color: var(--sl-color-accent-high)` for readable contrast against inactive items
+
+## [v1.14.0] - 2026-02-24
+
+### Fixed (CodeRabbit review)
+- **chromaterm/install.sh** — username auto-detection now resets to empty before candidate loop, so `${USERNAME:-root}` fallback works correctly
+- **biome/install.sh** — nvm.sh sourcing wrapped in `set +u` / `set -u` to prevent unbound variable abort under `set -euo pipefail`
+- **setup.js** — `ccstatusline-settings.json` added to DEFAULT_PRESERVE so user customizations survive `--force` package updates
+- **docs agent-system.md** — spec-writer moved from Full-Access to Read-Only agents table (matches its `permissionMode: plan` definition)
+- **guard-readonly-bash.py** — docstring corrected from "Returns JSON on stdout" to "Outputs block reason to stderr"
+- **git-forensics/SKILL.md** — misleading "Blame through renames" comment fixed to "Show patch history through renames"
+
+### Added
+
+#### Nuclear Workspace Scope Enforcement
+- **Blacklist system** — `/workspaces/.devcontainer/` permanently blocked for ALL operations (read, write, bash). Checked before allowlist, scope check, and cwd bypass. Cannot be overridden, even from workspace root
+- **Bash enforcement** — two-layer detection in `guard-workspace-scope.py`:
+  - Layer 1: 20+ regex patterns extract write targets (`>`, `tee`, `cp`, `mv`, `touch`, `mkdir`, `rm`, `ln`, `rsync`, `chmod`, `chown`, `dd`, `wget -O`, `curl -o`, `tar -C`, `unzip -d`, `gcc -o`, `sqlite3`). System command exemption only when ALL targets resolve to system paths
+  - Layer 2: regex scans entire command for any `/workspaces/` path string — catches inline scripts, variable assignments, quoted paths. No exemptions, always runs
+- **CWD context injector** (`inject-workspace-cwd.py`) — fires on SessionStart, UserPromptSubmit, PreToolUse, SubagentStart to reinforce working directory scope
+- **Fail-closed error handling** — JSON parse errors, exceptions, and unknown tools now exit 2 (block) instead of exit 0 (allow)
+
+#### Agent System Enhancements
+- **`task-completed-check.py`** — quality gate hook (TaskCompleted) runs test suite before allowing task completion
+- **`teammate-idle-check.py`** — quality gate hook (TeammateIdle) prevents teammates from going idle with incomplete tasks
+- **`skills/debug/SKILL.md`** — structured log investigation skill replacing the old `/debug` slash command
+- **`permissionMode`** declared on all 17 agent definitions (plan for read-only, default for write-capable)
+- **Agent-system README** — full plugin documentation with hook lifecycle, agent table, quality gates
+
+#### Skill Engine Enhancements
+- **6 new skill matchers** in `skill-suggester.py`: `spec-check`, `spec-init`, `spec-new`, `spec-refine`, `spec-update`, `team`
+- **Team skill expanded** (v0.2.0) — quality gate hooks, plan approval workflow, keyboard shortcuts, use case examples, best practices, limitations
+- **Skill-engine README** — full plugin documentation
+
+#### New Features
+- **chromaterm** — terminal output colorizer via ChromaTerm2 YAML rules
+- **kitty-terminfo** — xterm-kitty terminfo for Kitty terminal compatibility
+
+#### Documentation Site
+- **Astro/Starlight docs** (`docs/`) — full documentation portal with getting-started guides, plugin reference (12 pages), feature docs, customization, and API reference
+- **GitHub Actions** — `deploy-docs.yml` (docs deployment), `publish-features.yml` (GHCR feature publishing), `release.yml` (release workflow)
+- **Logos** — CodeForgeLogo.png, CodeForgeLogoTr.png, github-avatar.png
+
+#### Plugin Installation Documentation
+- **Remote install instructions** added to all 11 plugin READMEs — "From GitHub" section with clone + enabledPlugins setup from `https://github.com/AnExiledDev/CodeForge`
+- **GHCR feature paths** — features README updated with `ghcr.io/anexileddev/codeforge/<feature-name>:<version>` and devcontainer.json usage examples
+- **READMEs added** to session-context, skill-engine, spec-workflow plugins
+- **Install sections added** to workspace-scope-guard, codeforge-lsp, dangerous-command-blocker, protected-files-guard, notify-hook, ticket-workflow
+
+#### Other
+- **Marketplace metadata** — `marketplace.json` restructured with `metadata` object, `pluginRoot`, and `keywords` arrays for all plugins
+- **Port forwarding** for Claude Dashboard (port 7847) in devcontainer.json
+- **ChromaTerm wrapper** in setup-aliases.sh — `cc`/`claude`/`ccw` aliases pipe through `ct` when available
+- **`package.json` scripts** — added `prepublishOnly`, `docs:dev`, `docs:build`, `docs:preview`
+
+#### ccstatusline Config Externalization
+- **Widget config extracted** from inline `jq -n` generation in `install.sh` into `config/defaults/ccstatusline-settings.json` — editable JSON file, single source of truth
+- **File-manifest deployment** — two new entries deploy the config to `~/.config/ccstatusline/settings.json` (if-changed) and `/usr/local/share/ccstatusline/settings.template.json` (always)
+- **`${HOME}` variable expansion** added to `setup-config.sh` — enables manifest entries targeting user home directory paths
+
+#### Development Rules
+- **CLAUDE.md** (project root) — added changelog and documentation update rules: all changes must have a changelog entry and update relevant docs
+
+### Changed
 
-Claude Code is an idiot sandwich and ignored my instructions and workspace scope because it's a god damned idiot.
+#### ccstatusline Feature
+- `install.sh` simplified — removed ~90 lines of inline JSON config generation, validation, and template creation. Config deployment now handled by file-manifest system
+
+#### Workspace Scope Guard
+- Reads (Read, Glob, Grep) now **hard-blocked** outside scope — upgraded from warning (exit 0) to block (exit 2)
+- Allowlist trimmed to `/workspaces/.claude/` and `/tmp/` only — removed `/workspaces/.devcontainer/`, `/workspaces/.tmp/`, `/home/vscode/`
+- Hook timeout increased from 5s to 10s
+- Matcher expanded to include Bash tool
+
+#### Hook Output Schema Migration
+- All hooks migrated to `hookSpecificOutput` wrapper with explicit `hookEventName`
+- `commit-reminder.py` — upgraded from advisory to blocking (`decision: block`)
+- `spec-reminder.py` — upgraded from advisory to blocking (`decision: block`)
+- `advisory-test-runner.py` — test failures now block with `decision: block`; passes/timeouts use `systemMessage`
+- `ticket-linker.py` — output wrapped in `hookSpecificOutput`
+- `git-state-injector.py`, `todo-harvester.py` — output wrapped in `hookSpecificOutput`
+
+#### Ticket Workflow
+- Migrated from slash commands to skill-based approach — 4 slash commands and system-prompt.md replaced by skills directory
+
+#### Skill Definitions
+- All 21+ SKILL.md files rewritten with USE WHEN / DO NOT USE guidance, action-oriented descriptions, bumped to v0.2.0
+- `skill-suggester.py` keyword maps overhauled with natural phrases and concrete identifiers
+- Skill suggestion output changed to mandatory directive format
+- SubagentStart hook removed — suggestions now fire on UserPromptSubmit only
+
+#### Error Output
+- `block-dangerous.py` — errors now written to stderr (was JSON on stdout)
+- `guard-protected.py`, `guard-protected-bash.py` — errors now written to stderr
+
+#### Features
+- `ccstatusline` — compact 3-line layout (was 8-line), `rawValue: true` on token widgets
+- `claude-session-dashboard` — default port 3000 → 7847, `--host 0.0.0.0` for external access
+- `ccms` — build cache moved from `.devcontainer/.build-cache/` to `${TMPDIR:-/tmp}/ccms-build-cache`
+
+#### Configuration
+- `CLAUDE.md` (devcontainer) — condensed from ~308 to ~90 lines, removed redundant sections
+- `spec-workflow.md` rule — condensed, defers to system prompt `<specification_management>` section
+- `main-system-prompt.md` — expanded Agent Teams guidance: file ownership, task sizing, quality gate hooks, plan approval
+- Plugin `plugin.json` files — `version` field removed across all plugins
+
+### Fixed
+- Stale references to deleted features (mcp-reasoner, splitrail, claude-code) removed from docs
+- Documentation counts updated (features: 21, agents: 17, skills: 34)
+- Version mismatch in README.md corrected
+- Auto-formatter/auto-linter references consolidated to auto-code-quality throughout
+- Code-directive plugin references updated to agent-system, skill-engine, spec-workflow
+- Personal project paths removed from .gitignore and .npmignore
+- setup.js stale feature references fixed (Reasoner MCP, Go → Rust)
+- `.secrets` added to .npmignore for npm publish safety
+- Duplicate "### Fixed" header in v1.5.3 changelog entry
+- NVM sourcing added to biome install script
+- Cleanup trap added to shellcheck install script
+
+### Removed
+- **`auto-formatter` plugin** — deleted entirely (consolidated into auto-code-quality)
+- **`auto-linter` plugin** — deleted entirely (consolidated into auto-code-quality)
+- **`/debug` slash command** from agent-system (replaced by debug skill)
+- **4 ticket-workflow slash commands** (`ticket:new`, `ticket:work`, `ticket:review-commit`, `ticket:create-pr`) and `system-prompt.md` (replaced by skills)
+- **Optional features docs** for mcp-reasoner and splitrail (features no longer exist)
+- **SubagentStart hook** from skill-engine (suggestion now UserPromptSubmit only)
+
+---
+
+## [v1.13.0] - 2026-02-21
 
 ### Fixed
 
@@ -488,8 +632,6 @@ Claude Code is an idiot sandwich and ignored my instructions and workspace scope
 - **ccstatusline powerline glyphs**: Powerline separators/caps were empty strings, rendering as underscores. Now uses proper Nerd Font glyphs (U+E0B0, U+E0B4, U+E0B6)
 - **Unicode rendering in external terminals**: tmux rendered ALL Unicode as underscores because `docker exec` doesn't propagate locale vars. External terminal scripts now pass `LANG`/`LC_ALL=en_US.UTF-8` and use `tmux -u` to force UTF-8 mode. Locale exports also added to `.bashrc`/`.zshrc` as permanent fallback
 
-### Fixed
-
 - **cc/claude aliases**: Converted from shell functions to simple aliases — functions were not reliably invoked across shell contexts (tmux, docker exec, external terminals), causing Claude to launch without config
 - **CLAUDE_CONFIG_DIR export**: Now exported in `.bashrc`/`.zshrc` directly, so credentials are found in all shells (not just VS Code terminals where `remoteEnv` applies)
 

package/.devcontainer/CLAUDE.md

@@ -5,308 +5,93 @@ CodeForge devcontainer for AI-assisted development with Claude Code.
 ## Directory Structure
 
 ```
-/workspaces/
-├── .devcontainer/           # Container configuration (this directory)
-│   ├── devcontainer.json    # Main container definition
-│   ├── .env                 # Environment variables
-│   ├── config/              # Default configurations
-│   │   ├── file-manifest.json # Declarative file-copy manifest
-│   │   └── defaults/        # Files copied per manifest
-│   │       ├── settings.json    # Claude Code settings
-│   │       ├── keybindings.json # Claude Code keybindings
-│   │       ├── main-system-prompt.md
-│   │       └── writing-system-prompt.md
-│   ├── features/            # Custom devcontainer features
-│   ├── plugins/             # Local plugin marketplace
-│   │   └── devs-marketplace/
-│   └── scripts/             # Setup scripts
-├── .claude/                 # Runtime Claude config (created on first run)
-│   ├── settings.json        # Active settings (managed by file-manifest.json)
-│   ├── keybindings.json     # Active keybindings
-│   └── main-system-prompt.md # Active system prompt
-└── .gh/                     # GitHub CLI config (persists across rebuilds)
-    └── hosts.yml            # Authenticated hosts
+.devcontainer/
+├── devcontainer.json          # Container definition
+├── .env                       # Setup flags (SETUP_CONFIG, SETUP_ALIASES, etc.)
+├── config/
+│   ├── file-manifest.json     # Declarative config file deployment
+│   └── defaults/              # Source files deployed on start via file-manifest
+│       ├── settings.json      # Model, permissions, plugins, env vars
+│       ├── main-system-prompt.md
+│       ├── ccstatusline-settings.json  # Status bar widget layout
+│       └── rules/             # Deployed to .claude/rules/
+├── features/                  # Custom devcontainer features
+├── plugins/devs-marketplace/  # Local plugin marketplace
+└── scripts/                   # Setup scripts (run via postStartCommand)
 ```
 
-## Key Configuration Files
+## Key Configuration
 
 | File | Purpose |
 |------|---------|
-| `devcontainer.json` | Container definition: base image, features, mounts, environment |
-| `.env` | Environment variables controlling setup behavior |
-| `config/file-manifest.json` | Declarative manifest controlling which config files are copied and how |
-| `config/defaults/settings.json` | Claude Code defaults: model, tokens, permissions, plugins |
-| `config/defaults/keybindings.json` | Claude Code keybindings (empty by default — customizable) |
-| `config/defaults/main-system-prompt.md` | Default system prompt defining assistant behavior |
-| `config/defaults/writing-system-prompt.md` | Creative-writing system prompt used by `ccw` alias |
+| `config/defaults/settings.json` | Model, tokens, permissions, plugins, env vars |
+| `config/defaults/main-system-prompt.md` | System prompt defining assistant behavior |
+| `config/defaults/ccstatusline-settings.json` | Status bar widget layout (deployed to ~/.config/ccstatusline/) |
+| `config/file-manifest.json` | Controls which config files deploy and when |
+| `devcontainer.json` | Container definition: image, features, mounts |
+| `.env` | Boolean flags controlling setup steps |
 
-> **Note**: Config file copying is controlled by `config/file-manifest.json`. Each entry specifies `overwrite`: `"if-changed"` (default, sha256-based), `"always"`, or `"never"`. Persistent changes go in `.devcontainer/config/defaults/settings.json`.
+Config files deploy via `file-manifest.json` on every container start. Most deploy to `/workspaces/.claude/`; ccstatusline config deploys to `~/.config/ccstatusline/`. Each entry supports `overwrite`: `"if-changed"` (default, sha256), `"always"`, or `"never"`. Supported variables: `${CLAUDE_CONFIG_DIR}`, `${WORKSPACE_ROOT}`, `${HOME}`.
 
 ## Commands
 
 | Command | Purpose |
 |---------|---------|
-| `claude` | Run Claude Code with auto-configuration (prefers native binary at `~/.local/bin/claude`) |
-| `cc` | Shorthand for `claude` with config |
-| `ccraw` | Vanilla Claude Code without any config (bypasses function override) |
-| `ccw` | Claude Code with the writing system prompt — uses `writing-system-prompt.md` instead of `main-system-prompt.md`, optimized for creative and technical writing tasks |
-| `ccusage` | Analyze token usage history |
-| `ccburn` | Real-time token burn rate visualization |
-| `agent-browser` | Headless Chromium for browser automation (Playwright-based) |
-| `gh` | GitHub CLI for repo operations |
-| `uv` | Fast Python package manager |
-| `ast-grep` | Structural code search |
-| `ccms` | Search Claude Code session history (project-scoped) |
-| `cc-tools` | List all installed tools with version info |
+| `cc` / `claude` | Run Claude Code with auto-configuration |
+| `ccraw` | Vanilla Claude Code (bypasses config) |
+| `ccw` | Claude Code with writing system prompt |
+| `ccms` | Search session history (project-scoped) |
+| `ccusage` / `ccburn` | Token usage analysis / burn rate |
+| `agent-browser` | Headless Chromium (Playwright-based) |
 | `check-setup` | Verify CodeForge setup health |
-| `claude-dashboard` | Local session analytics dashboard (web UI on port 3000) |
+| `claude-dashboard` | Session analytics dashboard (port 7847) |
+| `cc-tools` | List all installed tools with versions |
+
+## Plugins
+
+Declared in `settings.json` under `enabledPlugins`, auto-activated on start:
+
+- **agent-system** — 17 custom agents + built-in agent redirection
+- **skill-engine** — 21 general coding skills + auto-suggestion
+- **spec-workflow** — 8 spec lifecycle skills + spec-reminder hook
+- **session-context** — Git state injection, TODO harvesting, commit reminders
+- **auto-code-quality** — Auto-format + auto-lint + advisory test runner
+- **workspace-scope-guard** — Blocks writes outside working directory
+- **dangerous-command-blocker** — Blocks destructive bash commands
+- **protected-files-guard** — Blocks edits to secrets/lock files
+- **codeforge-lsp** — LSP for Python + TypeScript/JavaScript
+- **ticket-workflow** — EARS ticket workflow + auto-linking
+- **notify-hook** — Desktop notifications on completion
+- **frontend-design** (Anthropic official) — UI/frontend design skill
 
-## Feature Development
-
-Custom features live in `./features/`. Each feature follows the [devcontainer feature spec](https://containers.dev/implementors/features/):
-
-```
-features/
-└── my-feature/
-    ├── devcontainer-feature.json   # Metadata and options
-    ├── install.sh                  # Installation script
-    └── README.md                   # Documentation
-```
-
-To test a feature locally, reference it in `devcontainer.json`:
-```json
-"features": {
-  "./features/my-feature": {}
-}
-```
-
-> **Note**: Claude Code is installed via `ghcr.io/anthropics/devcontainer-features/claude-code:1` (Anthropic's official feature).
-
-### Disabling Features with `version: "none"`
-
-Every local feature supports `"version": "none"` to skip installation entirely. This is useful for trimming build time or disabling tools you don't need without removing them from `devcontainer.json`.
-
-```json
-"features": {
-  "./features/ruff": { "version": "none" },
-  "./features/biome": {},
-  "./features/hadolint": { "version": "none" }
-}
-```
-
-When `version` is set to `"none"`, the feature's `install.sh` exits immediately with a skip message. The feature entry stays in `devcontainer.json` so re-enabling is a one-word change.
-
-**Currently disabled features** (not needed for Python/JS/TS workflow):
-
-| Feature | Handles | Reason |
-|---------|---------|--------|
-| `shfmt` | Shell formatting | Not needed — Python/JS/TS only |
-| `shellcheck` | Shell linting | Not needed — Python/JS/TS only |
-| `hadolint` | Dockerfile linting | Not needed — Python/JS/TS only |
-| `dprint` | Markdown/YAML/TOML/Dockerfile formatting | Not needed — Python/JS/TS only |
-
-The auto-formatter and auto-linter plugins gracefully skip missing tools at runtime.
-
-**All local features support this pattern:**
-ast-grep, biome, ccms, ccstatusline, claude-monitor, claude-session-dashboard, dprint, hadolint, lsp-servers, mcp-qdrant, mcp-reasoner, notify-hook, ruff, shfmt, shellcheck, splitrail, tmux
-
-**External features with `version: "none"` support:**
-`ghcr.io/devcontainers/features/node`, `ghcr.io/devcontainers/features/github-cli`, `ghcr.io/devcontainers/features/docker-outside-of-docker`, `ghcr.io/devcontainers/features/go` (all official Microsoft features)
-
-**External features without `version: "none"` support:**
-`ghcr.io/devcontainers-extra/features/uv`, `ghcr.io/anthropics/devcontainer-features/claude-code`, `ghcr.io/rails/devcontainer/features/bun`
-
-**External features with `version: "none"` support (Rust):**
-`ghcr.io/devcontainers/features/rust` (official Microsoft feature)
-
-> **Convention**: Every new local feature must include a `version` option (default `"latest"`) in its `devcontainer-feature.json` and a skip guard at the top of `install.sh`:
-> ```bash
-> if [ "${VERSION}" = "none" ]; then
->     echo "[feature-name] Skipping installation (version=none)"
->     exit 0
-> fi
-> ```
-
-## Setup Scripts
-
-Scripts in `./scripts/` run via `postStartCommand`:
-
-| Script | Purpose |
-|--------|---------|
-| `setup.sh` | Main orchestrator |
-| `setup-config.sh` | Copies config files per `config/file-manifest.json` to destinations |
-| `setup-aliases.sh` | Creates `cc`/`claude`/`ccraw`/`ccw` shell aliases (prefers native binary at `~/.local/bin/claude` via `_CLAUDE_BIN`) |
-| `setup-plugins.sh` | Registers local marketplace + installs official Anthropic plugins |
-| `setup-update-claude.sh` | Installs native Claude Code binary on first run; background auto-updates on subsequent starts |
-| `setup-terminal.sh` | Configures VS Code Shift+Enter keybinding for Claude Code multi-line input |
-| `setup-projects.sh` | Auto-detects projects for VS Code Project Manager |
-| `setup-auth.sh` | Configures Git and NPM auth from `.secrets` file or environment variables |
-| `check-setup.sh` | Verifies CodeForge setup health (binary paths, config files, features) |
-| `setup-symlink-claude.sh` | Symlinks ~/.claude for third-party tool compatibility |
-
-### External Terminal
-
-`connect-external-terminal.sh` connects to the running devcontainer from an external terminal with tmux support for Claude Code Agent Teams split-pane workflows. Run from the host:
-```bash
-.devcontainer/connect-external-terminal.sh
-```
-
-On Windows, use `connect-external-terminal.ps1` (PowerShell equivalent).
-
-## Installed Plugins
-
-Plugins are declared in `config/defaults/settings.json` under `enabledPlugins` and auto-activated on container start:
-
-### Official (Anthropic)
-- `frontend-design@claude-plugins-official` — UI/frontend design skill
-
-### Local Marketplace (devs-marketplace)
-- `codeforge-lsp@devs-marketplace` — LSP for Python + TypeScript/JavaScript
-- `ticket-workflow@devs-marketplace` — EARS-based ticket workflow with GitHub integration and auto-linking hook
-- `notify-hook@devs-marketplace` — Desktop notifications on completion
-- `dangerous-command-blocker@devs-marketplace` — Blocks destructive bash commands
-- `protected-files-guard@devs-marketplace` — Blocks edits to secrets/lock files
-- `agent-system@devs-marketplace` — 17 custom agents with built-in agent redirection, CWD injection, and read-only bash enforcement
-- `skill-engine@devs-marketplace` — 21 coding skills with auto-suggestion hook
-- `spec-workflow@devs-marketplace` — 8 spec lifecycle skills with spec-reminder hook
-- `session-context@devs-marketplace` — Session boundary hooks (git state injection, TODO harvesting, commit reminders)
-- `auto-code-quality@devs-marketplace` — Combined auto-format + auto-lint + advisory test runner
-- `workspace-scope-guard@devs-marketplace` — Blocks writes and warns on reads outside the working directory
-
-### Local Marketplace
-
-The `devs-marketplace` in `plugins/` provides locally-managed plugins:
-
-```
-plugins/devs-marketplace/
-├── .claude-plugin/
-│   └── marketplace.json      # Marketplace manifest
-└── plugins/
-    ├── codeforge-lsp/        # Combined LSP plugin
-    ├── ticket-workflow/      # EARS ticket workflow + auto-linking hook
-    ├── agent-system/         # 17 custom agents + redirection
-    ├── skill-engine/         # 21 coding skills + auto-suggestion
-    ├── spec-workflow/        # 8 spec lifecycle skills
-    ├── session-context/      # Session boundary hooks
-    ├── auto-code-quality/    # Combined format + lint + test runner
-    ├── workspace-scope-guard/ # Workspace scope enforcement
-    └── ...
-```
-
-## Agents & Skills
-
-Agents and skills are distributed across focused plugins:
-
-**Agents** (`plugins/devs-marketplace/plugins/agent-system/agents/`):
-architect, bash-exec, claude-guide, debug-logs, dependency-analyst, doc-writer, explorer, generalist, git-archaeologist, migrator, perf-profiler, refactorer, researcher, security-auditor, spec-writer, statusline-config, test-writer
-
-The `redirect-builtin-agents.py` hook (PreToolUse/Task) transparently swaps built-in agent types to these custom agents (e.g., Explore→explorer, Plan→architect).
-
-**General Skills** (`plugins/devs-marketplace/plugins/skill-engine/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, sqlite, svelte5, team, testing
-
-**Spec Skills** (`plugins/devs-marketplace/plugins/spec-workflow/skills/`):
-spec-build, spec-check, spec-init, spec-new, spec-refine, spec-review, spec-update, specification-writing
-
-## VS Code Keybinding Conflicts
-
-Claude Code runs inside VS Code's integrated terminal. VS Code intercepts some shortcuts before they reach the terminal:
+## Rules System
 
-| 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` |
+Rules in `config/defaults/rules/` deploy to `.claude/rules/` on every container start. They load into ALL sessions automatically.
 
-`Ctrl+P` and `Ctrl+F` are configured to pass through to the terminal via `terminal.integrated.commandsToSkipShell` in `devcontainer.json`. For other conflicts, use Meta (Alt) variants or customize via `config/defaults/keybindings.json`.
+**Current rules:** `spec-workflow.md`, `workspace-scope.md`, `session-search.md`
 
-## Environment Variables
+**Adding rules:** Create `.md` in `config/defaults/rules/`, add a manifest entry in `file-manifest.json`.
 
-Key environment variables set in the container:
+## Environment
 
 | Variable | Value |
 |----------|-------|
-| `WORKSPACE_ROOT` | `/workspaces` |
 | `CLAUDE_CONFIG_DIR` | `/workspaces/.claude` |
-| `GH_CONFIG_DIR` | `/workspaces/.gh` |
 | `ANTHROPIC_MODEL` | `claude-opus-4-6` |
-| `TMPDIR` | `/workspaces/.tmp` |
-| `CLAUDECODE` | `null` (unset) |
-
-Setting `"CLAUDECODE": null` in `remoteEnv` unsets this variable inside the container, which allows nested Claude Code sessions (claude-in-claude) that would otherwise be blocked by the outer session's detection flag.
-
-All setup steps are controlled by boolean flags in `.devcontainer/.env`. Set any to `false` to disable:
-`SETUP_CONFIG`, `SETUP_ALIASES`, `SETUP_AUTH`, `SETUP_PLUGINS`, `SETUP_UPDATE_CLAUDE`, `SETUP_TERMINAL`, `SETUP_PROJECTS`, `SETUP_POSTSTART`.
-
-### Experimental Environment Variables
-
-These are set in `config/defaults/settings.json` under `env` and control Claude Code experimental features:
-
-| Variable | Value | Description |
-|----------|-------|-------------|
-| `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` | `1` | Enables Agent Teams (multi-agent orchestration) |
-| `CLAUDE_CODE_EFFORT_LEVEL` | `high` | Sets reasoning effort level |
-| `CLAUDE_CODE_ENABLE_TASKS` | `true` | Enables the task/todo system |
-| `CLAUDE_CODE_PLAN_MODE_INTERVIEW_PHASE` | `true` | Enables interview phase before plan execution |
-| `CLAUDE_CODE_PLAN_V2_AGENT_COUNT` | `3` | Number of agents in Plan V2 orchestration |
-| `CLAUDE_CODE_PLAN_MODE_REQUIRED` | `true` | Forces plan mode for teammate agents |
-| `ENABLE_CLAUDE_CODE_SM_COMPACT` | `1` | Enables smart compaction for context management |
-| `CLAUDE_CODE_FORCE_GLOBAL_CACHE` | `1` | Forces global prompt caching |
-| `FORCE_AUTOUPDATE_PLUGINS` | `1` | Auto-updates plugins on every session start |
-
-## Git Worktrees
-
-CodeForge supports git worktrees for working on multiple branches simultaneously.
-
-### Layout
-
-Worktrees live in a `.worktrees/` directory alongside the main repo:
-
-```
-/workspaces/projects/
-├── CodeForge/           # main repo (.git directory)
-└── .worktrees/          # worktree container
-    ├── feature-a/       # worktree checkout (.git file)
-    └── bugfix-b/        # worktree checkout (.git file)
-```
-
-### Creating Compatible Worktrees
-
-```bash
-cd /workspaces/projects/CodeForge
-mkdir -p /workspaces/projects/.worktrees
-git worktree add /workspaces/projects/.worktrees/my-branch my-branch
-```
-
-### Project Detection
-
-- `setup-projects.sh` scans `.worktrees/` directories at depth 3 (inside container dirs like `projects/`)
-- Worktrees are detected by their `.git` file (containing `gitdir:`) and tagged with both `"git"` and `"worktree"` in Project Manager
-- Each worktree appears as an independent project in VS Code Project Manager
-
-### Compatibility
+| `WORKSPACE_ROOT` | `/workspaces` |
 
-- `workspace-scope-guard` resolves worktree paths correctly via `os.path.realpath()`
-- `protected-files-guard` protects both `.git/` directories and `.git` files (worktree pointers)
-- Read-only agents (e.g., git-archaeologist) can use `git worktree list` but cannot add/remove worktrees
+All experimental feature flags are in `settings.json` under `env`. Setup steps controlled by boolean flags in `.env`.
 
 ## Modifying Behavior
 
-1. **Change default model**: Edit `config/defaults/settings.json`, update `"model"` field
+1. **Change model**: Edit `config/defaults/settings.json` → `"model"` field
 2. **Change system prompt**: Edit `config/defaults/main-system-prompt.md`
-3. **Change keybindings**: Edit `config/defaults/keybindings.json`
-4. **Add a custom config file**: Add an entry to `config/file-manifest.json` with `src`, `dest`, and optional `overwrite`/`destFilename`
-5. **Add features**: Add to `"features"` in `devcontainer.json`
-6. **Disable auto-setup**: Set variables to `false` in `.env`
-
-## Rules System
-
-Rules live in `config/defaults/rules/` and are copied to `.claude/rules/` by the file manifest (`config/file-manifest.json`) on every container start. Unlike CLAUDE.md (which loads on demand when entering a project), rules load automatically on every Claude Code session.
+3. **Add config file**: Add entry to `config/file-manifest.json`
+4. **Add features**: Add to `"features"` in `devcontainer.json`
+5. **Disable features**: Set `"version": "none"` in the feature's config
+6. **Disable setup steps**: Set flags to `false` in `.env`
+7. **Customize status bar**: Edit `config/defaults/ccstatusline-settings.json`
 
-**Current rules**: `spec-workflow.md`, `workspace-scope.md`, `session-search.md`
+## Features
 
-**Adding custom rules**: Create a `.md` file in `config/defaults/rules/`, then add a manifest entry in `config/file-manifest.json` pointing to `${CLAUDE_CONFIG_DIR}/rules` as the destination. The rule will be deployed on the next container start.
+Custom features in `./features/` follow the [devcontainer feature spec](https://containers.dev/implementors/features/). Every local feature supports `"version": "none"` to skip installation. Claude Code is installed via `ghcr.io/anthropics/devcontainer-features/claude-code:1`.

package/.devcontainer/README.md

@@ -434,7 +434,7 @@ Common issues and solutions. For detailed troubleshooting, see [docs/troubleshoo
 **CodeForge Documentation**:
 - [Configuration Reference](docs/configuration-reference.md) — all env vars and config options
 - [Plugin System](docs/plugins.md) — plugin architecture and per-plugin docs
-- [Optional Features](docs/optional-features.md) — mcp-qdrant and other optional components
+- [Optional Features](docs/optional-features.md) — mcp-qdrant and other optional components, disabling features
 - [Keybinding Customization](docs/keybindings.md) — resolving VS Code conflicts
 - [Troubleshooting](docs/troubleshooting.md) — common issues and solutions