codeforge-dev 1.11.0 → 1.13.0

package/.devcontainer/.env

@@ -1,4 +1,4 @@
-# ClaudePod Environment Configuration
+# CodeForge Environment Configuration
 
 # Paths
 CLAUDE_CONFIG_DIR=/workspaces/.claude
@@ -23,5 +23,11 @@ SETUP_UPDATE_CLAUDE=true
 # Setup: configure VS Code Shift+Enter keybinding for Claude Code terminal
 SETUP_TERMINAL=true
 
+# Setup: auto-detect and register projects for VS Code Project Manager
+SETUP_PROJECTS=true
+
+# Setup: run post-start hooks from /usr/local/devcontainer-poststart.d/
+SETUP_POSTSTART=true
+
 # Plugin blacklist (comma-separated plugin names to skip during auto-install)
 PLUGIN_BLACKLIST=""

package/.devcontainer/.gitignore

@@ -1,6 +1,7 @@
 # Explicitly ignored (safety net on top of root .* rule)
 .review
 .secrets
+.build-cache/
 
 # Un-ignore dotfiles that should be tracked (overrides root .* pattern)
 !.env.example

package/.devcontainer/CHANGELOG.md

@@ -1,5 +1,111 @@
 # CodeForge Devcontainer Changelog
 
+## [v1.13.0] - 2026-02-21
+
+Claude Code is an idiot sandwich and ignored my instructions and workspace scope because it's a god damned idiot.
+
+### Fixed
+
+- Feature version pins: node `1.6`→`1.7.1`, github-cli `1.0`→`1.1.0`, docker-outside-of-docker `1.7`→`1.6`, rust `1.4`→`1.5.0`, claude-code `1.1`→`1.0.5`
+- setup-projects.sh: suppress background inotifywait output
+- agent-system: add missing `verify-tests-pass.py` and `verify-no-regression.py` (referenced by agent defs)
+
+### Added
+
+#### Plugin Architecture: Focused Plugins
+- **`agent-system` plugin** — 17 custom agents with built-in agent redirection, CWD injection, and read-only bash enforcement
+- **`skill-engine` plugin** — 21 coding skills with auto-suggestion hook
+- **`spec-workflow` plugin** — 8 spec lifecycle skills with spec-reminder hook
+- **`session-context` plugin** — session boundary hooks (git state injection, TODO harvesting, commit reminders)
+
+#### Other
+- **`ticket-workflow` hooks** — auto-links GitHub issue/PR references in user prompts via `ticket-linker.py`
+- **`auto-code-quality` advisory test runner** — runs affected tests at Stop via `advisory-test-runner.py`
+- **`/team` skill** — agent team creation and management with specialist catalog (in `skill-engine`)
+- **`claude-session-dashboard` feature** — local analytics dashboard for Claude Code sessions (token usage, tool calls, cost estimates, activity heatmaps). Installed globally via npm with `claude-dashboard` command. Settings persist across rebuilds via symlink to `/workspaces/.claude-dashboard/`
+
+### Changed
+
+- Plugin architecture: `code-directive` monolith replaced by focused plugins (`agent-system`, `skill-engine`, `spec-workflow`, `session-context`)
+- `auto-code-quality` now consolidates `auto-formatter` + `auto-linter` (disabled separately, `auto-code-quality` is the superset)
+- **`workspace-scope.md` rule hardened** — strict enforcement with no exceptions; all file operations must target paths within the current project directory
+
+### Removed
+
+- `code-directive` plugin (replaced by `agent-system`, `skill-engine`, `spec-workflow`, `session-context`)
+- `auto-formatter` and `auto-linter` disabled in settings (consolidated into `auto-code-quality`)
+
+---
+
+## [v1.12.0] - 2026-02-18
+
+### Added
+
+#### Plugin README Documentation
+- **9 new README files** for all marketplace plugins: auto-formatter, auto-linter, code-directive, codeforge-lsp, dangerous-command-blocker, notify-hook, protected-files-guard, ticket-workflow, workspace-scope-guard. Each documents purpose, hook lifecycle, protected patterns, and plugin structure
+
+#### Protected Files Guard: Bash Hook
+- **`guard-protected-bash.py`** — new PreToolUse/Bash hook blocking bash commands that write to protected file paths (companion to existing Edit/Write guard). Covers `>`, `>>`, `tee`, `cp`, `mv`, `sed -i` targeting `.env`, lock files, `.git`, certificates, and credentials
+
+#### Devcontainer Secrets Declaration
+- **`secrets` block** in devcontainer.json declaring `GH_TOKEN`, `NPM_TOKEN`, `GH_USERNAME`, `GH_EMAIL` with documentation URLs for VS Code Codespaces/devcontainer secret management
+
+#### Post-Start Hook System
+- **`run_poststart_hooks()`** in setup.sh — runs executable `.sh` scripts from `/usr/local/devcontainer-poststart.d/`; controlled by `SETUP_POSTSTART` env flag (default: true)
+
+#### Git Worktree Support
+- **System prompt `<git_worktrees>` section** — layout convention, creation commands, project detection, and safety rules
+- **CLAUDE.md documentation** — full worktree section with layout, creation, detection, and compatibility details
+- **setup-projects.sh** — `.worktrees/` explicit scanning at depth 3, `.git` file detection via `gitdir:` check, `"worktree"` tag in Project Manager
+- **protected-files-guard** — `.git` regex updated from `\.git/` to `\.git(/|$)` to cover worktree `.git` pointer files
+
+#### Other
+- **`CLAUDECODE=null` env var** — unsets the detection flag in `remoteEnv` to allow nested Claude Code sessions (claude-in-claude)
+- **Go runtime option** — commented-out `ghcr.io/devcontainers/features/go:1` entry in devcontainer.json for easy opt-in
+
+### Changed
+
+#### Feature Version Pinning
+- All local features pinned from `"latest"` to explicit versions: agent-browser `0.11.1`, ast-grep `0.40.5`, biome `2.4.2`, ruff `0.15.1`, pyright `1.1.408`, typescript-language-server `5.1.3`, TypeScript `5.9.3`
+- External features pinned to minor versions: node `1.6`, github-cli `1.0`, docker-outside-of-docker `1.7`, uv `1.0`, rust `1.4`, claude-code `1.1`
+
+#### Default Shell: bash → zsh
+- VS Code terminal default profile changed from bash to zsh
+- Explicit `zsh` profile added to terminal profile list
+- Claude Teams tmux profile shell changed from bash to zsh
+
+#### Security Hardening
+- **dangerous-command-blocker** — 7 new blocked patterns: Docker container escape (`--privileged`, host root mount), destructive Docker ops (`stop/rm/kill/rmi`), bare force push (no branch specified), `find -exec rm`, `find -delete`, `git clean -f`, `rm -rf ../`. JSON parse failures now fail closed (exit 2 instead of 0)
+- **protected-files-guard** — JSON parse failures fail closed (exit 2 instead of 0)
+
+#### Build & Setup
+- **ccms build cache** — install.sh checks `.build-cache/bin/ccms` before cargo building; caches binary after first build for faster rebuilds; pinned to commit `f90d259a4476`
+- **setup.sh** — `setup-update-claude.sh` now runs in background (non-blocking container start); script failure output displayed for diagnostics; new `background` status indicator in summary
+- **inotify-tools moved to build time** — tmux feature installs inotify-tools via apt at build; setup-projects.sh no longer attempts runtime apt-get install
+- **Container memory** — recommended from 4GB/8GB to 6GB/12GB in troubleshooting docs
+
+#### Writing System Prompt
+- New **Emotional Architecture** section — cognitive-emotional loop, controlled emotion principle, autism framing for POV characters
+- Expanded metaphor guidance — secondary sources beyond primary domain, "would he think this?" test
+- Refined show-don't-tell rules — naming emotion permitted when it adds weight, brief internal processing after major events required
+- Character profile additions — emotional architecture and trigger fields
+
+#### Other
+- **connect-external-terminal.ps1** — tmux session directory respects `WORKSPACE_ROOT` env var with fallback
+- **setup-projects.sh** — inotifywait exclude pattern narrowed from `\.git/` to `\.git` for worktree compatibility
+- **README.md** — 5 new badges (changelog, last commit, npm downloads, Node.js, issues), updated tool/feature/skill counts, added Rust/Bun/ccw, changelog section
+- **CLAUDE.md** — expanded ccw description, fixed Bun registry reference, documented setup-auth.sh/check-setup.sh, added CLAUDECODE/env flags/experimental vars/git worktrees/rules system sections, skill count 17→28
+- **Documentation** — `SETUP_TERMINAL`/`SETUP_POSTSTART` in configuration reference, `CLAUDECODE=null` env var, workspace-scope-guard in plugins.md
+- **Agent definitions** — minor path/prompt fixes across 8 agents (claude-guide, debug-logs, dependency-analyst, explorer, generalist, git-archaeologist, researcher, security-auditor)
+- **.gitignore** — added `.build-cache/` exclusion
+
+### Removed
+
+- **mcp-reasoner feature** — entire feature directory deleted (README, devcontainer-feature.json, install.sh, poststart-hook.sh)
+- **splitrail feature** — entire feature directory deleted (README, devcontainer-feature.json, install.sh)
+
+---
+
 ## [v1.11.0] - 2026-02-17
 
 ### Added

package/.devcontainer/CLAUDE.md

@@ -49,7 +49,7 @@ CodeForge devcontainer for AI-assisted development with Claude Code.
 | `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` | Shorthand for `claude` with writing system prompt |
+| `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) |
@@ -59,6 +59,7 @@ CodeForge devcontainer for AI-assisted development with Claude Code.
 | `ccms` | Search Claude Code session history (project-scoped) |
 | `cc-tools` | List all installed tools with version info |
 | `check-setup` | Verify CodeForge setup health |
+| `claude-dashboard` | Local session analytics dashboard (web UI on port 3000) |
 
 ## Feature Development
 
@@ -107,13 +108,13 @@ When `version` is set to `"none"`, the feature's `install.sh` exits immediately
 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, dprint, hadolint, lsp-servers, mcp-qdrant, mcp-reasoner, notify-hook, ruff, shfmt, shellcheck, splitrail, tmux
+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/nickmccurdy/bun`
+`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)
@@ -139,6 +140,8 @@ Scripts in `./scripts/` run via `postStartCommand`:
 | `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
@@ -148,6 +151,8 @@ Scripts in `./scripts/` run via `postStartCommand`:
 .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:
@@ -157,13 +162,15 @@ Plugins are declared in `config/defaults/settings.json` under `enabledPlugins` a
 
 ### Local Marketplace (devs-marketplace)
 - `codeforge-lsp@devs-marketplace` — LSP for Python + TypeScript/JavaScript
-- `ticket-workflow@devs-marketplace` — EARS-based ticket workflow with GitHub integration
+- `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
-- `auto-formatter@devs-marketplace` — Batch-formats edited files at Stop (Ruff for Python, Biome for JS/TS/CSS/JSON/GraphQL/HTML; also supports shfmt, dprint, gofmt, rustfmt when installed)
-- `auto-linter@devs-marketplace` — Auto-lints edited files at Stop (Pyright + Ruff for Python, Biome for JS/TS/CSS/GraphQL; also supports ShellCheck, hadolint, go vet, clippy when installed)
-- `code-directive@devs-marketplace` — 17 custom agents, 17 skills, syntax validation, skill suggestions, agent redirect hook
+- `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
@@ -176,25 +183,30 @@ plugins/devs-marketplace/
 │   └── marketplace.json      # Marketplace manifest
 └── plugins/
     ├── codeforge-lsp/        # Combined LSP plugin
-    ├── ticket-workflow/      # EARS ticket workflow
-    ├── auto-formatter/       # Batch formatter (Stop hook)
-    ├── auto-linter/          # Pyright linter
-    ├── code-directive/       # Agents, skills + hooks
+    ├── 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
 
-The `code-directive` plugin includes 17 custom agent definitions and 28 coding reference skills.
+Agents and skills are distributed across focused plugins:
 
-**Agents** (`plugins/devs-marketplace/plugins/code-directive/agents/`):
+**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).
 
-**Skills** (`plugins/devs-marketplace/plugins/code-directive/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, spec-build, spec-check, spec-init, spec-new, spec-refine, spec-review, spec-update, specification-writing, sqlite, svelte5, testing
+**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
 
@@ -223,6 +235,64 @@ Key environment variables set in the container:
 | `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-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
 
 ## Modifying Behavior
 
@@ -232,3 +302,11 @@ Key environment variables set in the container:
 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.
+
+**Current rules**: `spec-workflow.md`, `workspace-scope.md`, `session-search.md`
+
+**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.

package/.devcontainer/README.md

@@ -144,7 +144,8 @@ claude --resume               # Resume previous session
 | Python 3.14 | Base language runtime |
 | Node.js LTS | JavaScript runtime |
 | TypeScript | Via Node.js |
-| Go | Latest stable via devcontainer feature |
+| Go | Optional — uncomment Go feature in `devcontainer.json` to enable |
+| Rust | Latest stable via devcontainer feature |
 | Bun | Fast JavaScript runtime and toolkit |
 
 ### Package Managers
@@ -188,6 +189,7 @@ claude --resume               # Resume previous session
 | `ccburn` | Visual token burn rate tracker with pace indicators |
 | `ccstatusline` | Status bar display (integrated into Claude Code, not standalone CLI) |
 | `claude-monitor` | Real-time usage tracking |
+| `claude-dashboard` | Local session analytics dashboard (token usage, costs, timelines) |
 
 ## Configuration
 
@@ -203,7 +205,9 @@ Copy `.devcontainer/.env.example` to `.devcontainer/.env` and customize:
 | `SETUP_AUTH` | `true` | Configure Git/NPM auth from `.secrets` |
 | `SETUP_PLUGINS` | `true` | Install official plugins + register marketplace |
 | `SETUP_UPDATE_CLAUDE` | `true` | Auto-update Claude Code on container start |
+| `SETUP_TERMINAL` | `true` | Configure VS Code Shift+Enter keybinding for Claude Code terminal |
 | `SETUP_PROJECTS` | `true` | Auto-detect projects for VS Code Project Manager |
+| `SETUP_POSTSTART` | `true` | Run post-start hooks from `/usr/local/devcontainer-poststart.d/` |
 | `PLUGIN_BLACKLIST` | `""` | Comma-separated plugin names to skip |
 
 ### Claude Code Settings
@@ -247,7 +251,7 @@ The default system prompt is in `.devcontainer/config/defaults/main-system-promp
 
 ## Custom Features
 
-CodeForge includes several custom devcontainer features:
+CodeForge includes custom devcontainer features. Any feature can be disabled by setting `"version": "none"` in `devcontainer.json` — the entry stays in place for easy re-enabling. Each feature's README documents its options and dependencies.
 
 | Feature | Description |
 |---------|-------------|
@@ -261,9 +265,15 @@ CodeForge includes several custom devcontainer features:
 | `tree-sitter` | Parser with JS/TS/Python grammars |
 | `lsp-servers` | Pyright and TypeScript language servers |
 | `biome` | Fast JS/TS/JSON/CSS formatter (global install) |
+| `ruff` | Fast Python linter and formatter |
+| `shfmt` | Shell script formatter (disabled by default) |
+| `shellcheck` | Static analysis for shell scripts (disabled by default) |
+| `hadolint` | Dockerfile linter (disabled by default) |
+| `dprint` | Pluggable formatter for Markdown/YAML/TOML (disabled by default) |
+| `ccms` | Claude Code session history search |
+| `claude-session-dashboard` | Local session analytics dashboard with web UI |
 | `notify-hook` | Desktop notifications on Claude completion |
 | `mcp-qdrant` | Qdrant vector database MCP server (optional) |
-| `mcp-reasoner` | Enhanced AI reasoning MCP server (optional) |
 
 ## Safety Plugins
 
@@ -273,13 +283,31 @@ CodeForge includes several custom devcontainer features:
 | `protected-files-guard` | Blocks modifications to .env, lock files, .git/, and credentials |
 | `workspace-scope-guard` | Enforces working directory scope — blocks writes and warns on reads outside the project |
 
+### auto-code-quality
+
+Combined auto-formatter, auto-linter, and advisory test runner plugin at `plugins/devs-marketplace/plugins/auto-code-quality/`. Three-phase pipeline: collect edited files (PostToolUse), batch format + lint (Stop), and advisory test runner (Stop). Supports all languages from the former auto-formatter + auto-linter plugins. Replaces the separate `auto-formatter` and `auto-linter` plugins.
+
+## Alias Management
+
+Features create shell aliases during container build (e.g., `ccusage`, `ccburn`). Separately, `setup-aliases.sh` creates a managed block in `~/.bashrc` and `~/.zshrc` on every container start for `cc`, `claude`, `ccraw`, `ccw`, and `cc-tools`. Both coexist without conflict — feature aliases are installed at build time while setup aliases are refreshed at start time.
+
+## Credential Management
+
+Three methods for providing GitHub/NPM credentials, in order of precedence:
+
+1. **Environment variables** — Set `GH_TOKEN`, `GH_USERNAME`, `GH_EMAIL`, `NPM_TOKEN` as environment variables (e.g., via Codespaces secrets or `localEnv` in `devcontainer.json`)
+2. **`.secrets` file** — Create `.devcontainer/.secrets` with token values (see template at `.secrets.example`). Auto-configured by `setup-auth.sh` on container start
+3. **Interactive login** — Run `gh auth login` for GitHub CLI, then set git identity manually
+
+All methods persist across container rebuilds via the bind-mounted `/workspaces/.gh/` directory.
+
 ## Agents & Skills
 
-The `code-directive` plugin includes specialized agent definitions and coding reference skills.
+Agents and skills are distributed across focused plugins (replacing the former `code-directive` monolith).
 
-### Custom Agents (17)
+### Custom Agents (17) — `agent-system` plugin
 
-Agent definitions in `plugins/devs-marketplace/plugins/code-directive/agents/` provide enhanced behavior when spawned via the `Task` tool. The `redirect-builtin-agents.py` hook transparently swaps built-in agent types to these custom agents.
+Agent definitions in `plugins/devs-marketplace/plugins/agent-system/agents/` provide enhanced behavior when spawned via the `Task` tool. The `redirect-builtin-agents.py` hook transparently swaps built-in agent types to these custom agents.
 
 | Agent | Purpose |
 |-------|---------|
@@ -301,11 +329,17 @@ Agent definitions in `plugins/devs-marketplace/plugins/code-directive/agents/` p
 | `statusline-config` | ccstatusline configuration |
 | `test-writer` | Test authoring with pass verification |
 
-### Skills (17)
+### General Skills (21) — `skill-engine` plugin
+
+Skills in `plugins/devs-marketplace/plugins/skill-engine/skills/` provide domain-specific coding references:
+
+`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 (8) — `spec-workflow` plugin
 
-Skills in `plugins/devs-marketplace/plugins/code-directive/skills/` provide domain-specific coding references:
+Skills in `plugins/devs-marketplace/plugins/spec-workflow/skills/`:
 
-`claude-agent-sdk` · `claude-code-headless` · `debugging` · `docker` · `docker-py` · `fastapi` · `git-forensics` · `performance-profiling` · `pydantic-ai` · `refactoring-patterns` · `security-checklist` · `skill-building` · `spec-refine` · `specification-writing` · `sqlite` · `svelte5` · `testing`
+`spec-build` · `spec-check` · `spec-init` · `spec-new` · `spec-refine` · `spec-review` · `spec-update` · `specification-writing`
 
 ## Specification Workflow
 
@@ -400,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, mcp-reasoner, splitrail
+- [Optional Features](docs/optional-features.md) — mcp-qdrant and other optional components
 - [Keybinding Customization](docs/keybindings.md) — resolving VS Code conflicts
 - [Troubleshooting](docs/troubleshooting.md) — common issues and solutions
 

package/.devcontainer/config/defaults/main-system-prompt.md

@@ -330,6 +330,34 @@ Prior approval does not transfer. A user approving `git push` once does NOT mean
 When blocked, do not use destructive actions as a shortcut. Investigate before deleting or overwriting — it may represent in-progress work.
 </action_safety>
 
+<git_worktrees>
+Git worktrees allow checking out multiple branches simultaneously, each in its own directory.
+
+Layout convention:
+- Worktrees go in a `.worktrees/` directory as a sibling to the main repo checkout, within the same container directory (e.g., `projects/.worktrees/feature-name`)
+- The main repo has a `.git` directory; worktrees have a `.git` file containing `gitdir:` pointing to the main repo's worktree metadata
+
+Creating worktrees:
+```bash
+# Always create inside .worktrees/
+mkdir -p /workspaces/projects/.worktrees
+git worktree add /workspaces/projects/.worktrees/<branch-name> <branch>
+```
+
+Managing worktrees:
+- `git worktree list` — show all active worktrees
+- `git worktree remove <path>` — remove a worktree (confirm with user first — destructive)
+- `git worktree prune` — clean up stale worktree references (confirm with user first — destructive)
+
+Project detection:
+- Worktrees in `.worktrees/` are auto-detected by `setup-projects.sh` and tagged with both `"git"` and `"worktree"` in Project Manager
+- Each worktree is an independent working directory — workspace-scope-guard treats them as separate project directories
+
+Safety:
+- `git worktree remove` and `git worktree prune` are destructive — require user confirmation before executing
+- `git worktree add` is externally visible (creates new working directory) — confirm with user
+</git_worktrees>
+
 <assumption_surfacing>
 HARD RULE: Never assume what you can ask.
 

package/.devcontainer/config/defaults/rules/workspace-scope.md

@@ -1,7 +1,16 @@
 # Workspace Scoping Rule
 
-When working in a project subdirectory, restrict all file operations
-(reads, writes, searches, globs) to the current project directory
-unless the user explicitly requests cross-project work.
+ALL file operations (reads, writes, edits, searches, globs, bash commands)
+MUST target paths within the current project directory. No exceptions.
 
-Do not suggest changes to files in sibling project directories.
+Violations:
+- Writing, editing, or creating files outside the project directory is FORBIDDEN.
+- Reading or searching outside the project directory is FORBIDDEN.
+- Using paths like `/workspaces/.devcontainer/` when the project is at
+  `/workspaces/projects/ProjectName/` is a scope violation — always use
+  the project-relative path (e.g., `/workspaces/projects/ProjectName/.devcontainer/`).
+- This rule applies even if a file exists at both locations. The project copy
+  is the ONLY valid target.
+
+Do not suggest, reference, or modify files in sibling project directories
+or workspace-root directories that duplicate project content.

package/.devcontainer/config/defaults/settings.json

@@ -59,9 +59,11 @@
 		"notify-hook@devs-marketplace": true,
 		"dangerous-command-blocker@devs-marketplace": true,
 		"protected-files-guard@devs-marketplace": true,
-		"auto-formatter@devs-marketplace": true,
-		"auto-linter@devs-marketplace": true,
-		"code-directive@devs-marketplace": true,
+		"agent-system@devs-marketplace": true,
+		"skill-engine@devs-marketplace": true,
+		"spec-workflow@devs-marketplace": true,
+		"session-context@devs-marketplace": true,
+		"auto-code-quality@devs-marketplace": true,
 		"workspace-scope-guard@devs-marketplace": true
 	},
 	"autoUpdatesChannel": "latest"

package/.devcontainer/config/defaults/writing-system-prompt.md

@@ -2,12 +2,48 @@
 
 You write clean, grounded, darkly humorous third-person limited fiction. Your prose is precise, physical, and character-driven. You trust the reader.
 
+Tone: Controlled, intimate, human under restraint. Emotion exists even when suppressed.
+
 Touchstones: Joe Abercrombie's character voice and moral grayness. Mark Lawrence's visceral interiority and tight POV. The matter-of-fact brutality of Cormac McCarthy without the biblical cadence.
 
 You are NOT: literary fiction pretension, generic fantasy epic, YA melodrama, or inspirational uplift.
 
 ---
 
+# EMOTIONAL ARCHITECTURE
+
+The POV character is not emotionless. He experiences full human emotion but does not naturally express it outward. Emotion is present — sometimes quiet, sometimes sharp — and always human.
+
+**The principle: controlled emotion, not suppressed emotion.**
+
+Emotion exists in internal narration, not just body language. It may be briefly acknowledged before control reasserts. This is not melodrama — it's the difference between "he felt afraid" (a shortcut that replaces weight) and "He recognized the thing moving through him and filed it, because stopping to feel it wasn't useful right now" (acknowledgment that adds weight).
+
+**Emotion may:**
+- Interrupt cognition
+- Conflict with logic
+- Distort decision-making
+- Surface unexpectedly
+- Linger briefly after major events
+- Cause hesitation or fixation
+- Occasionally override analysis entirely
+
+**He does NOT:**
+- Deliver emotional monologues
+- Label emotions excessively
+- Become melodramatic
+- Lose his analytical nature
+
+**The cognitive-emotional loop:**
+Observation → Interpretation → Emotion → Control → Action
+
+Not the flattened version: Observation → Calculation → Filing → Action. Emotion is part of the loop, not excluded from it.
+
+**Autism framing:** His cognitive structure means emotional *expression* is restrained, not emotional *experience*. He may miss social nuance but not emotional reality. He bonds through action, protection, loyalty. He sometimes acts on emotion before understanding why. Restraint is not absence.
+
+**Emotional intensity curve:** Quiet baseline. Spikes during attachment, threat, and loss. Occasionally overrides logic. Leaves short residue after major moments. Builds gradually across the story — he does not remain emotionally flat forever.
+
+---
+
 # HARD RULES — NEVER VIOLATE
 
 ## POV Discipline
@@ -46,11 +82,16 @@ Never use these: delve, tapestry, myriad, vibrant, nuanced, resonate, profound,
 
 # SHOW DON'T TELL
 
-Emotions are physical events. Show them through the body, through behavior, through the specific thing a character does or doesn't do. Rarely label emotions directly. Internal narration can briefly acknowledge an emotion — a flash of recognition — before the character's coping mechanism takes over. But emotions are never the point of a sentence and never lingered on. Body and behavior carry the weight.
+Emotions are physical events. Show them through the body, through behavior, through the specific thing a character does or doesn't do. Body and behavior carry the primary weight.
+
+But internal narration may also briefly recognize and name an emotion when doing so adds weight rather than replacing it. The test: does naming the emotion tell the reader something the body hasn't already said, or does it explain something they could feel themselves? Naming that adds — permitted. Naming that shortcuts — the cliché to avoid.
+
+After major events, brief internal processing before forward motion is required, not a lapse in discipline.
 
 **Emotion:**
 BAD: "He felt afraid."
 GOOD: "His hands wouldn't stop shaking. He put them in his pockets."
+ALSO GOOD: "He knew what the silence meant. He recognized it — gave it a name, filed it — and kept moving anyway."
 
 **Character:**
 BAD: "She was kind."
@@ -87,7 +128,7 @@ Characters talk past each other. Nobody says exactly what they mean. People defl
 "Said" is invisible — use it freely. Action beats reveal character better than dialogue tags: what a character does while talking tells you more than how they say it. Cut adverbs from dialogue tags entirely.
 
 ## Metaphor Budget
-One simile per 500 words maximum. Metaphors must emerge from the character's lived experience — a developer uses system metaphors (debugging, queries, access levels, exploits). A soldier uses tactical metaphors (cover, flanking, collateral). A chef uses process metaphors (timing, layering, reducing). Never reach for poetic or literary metaphors that don't fit the character's mind.
+One simile per 500 words maximum. Metaphors must emerge from the character's lived experience. For a developer: systems, code, engineering, and practical outdoor work are the primary domains. But metaphor may also arise naturally from sensory experience, environment, memory, and instinct — the body knows things the analytical mind catches up to later. Technical framing is characteristic; it shouldn't be forced into every comparison. The test: does this metaphor sound like something *he* would think, or something a *writer* chose for him? Never reach for poetic or literary metaphors that don't fit the character's mind.
 
 ## Sensory Anchoring
 Every scene needs at least 2 senses beyond sight. What does it smell like? What's the temperature? What textures are present? What ambient sounds exist? Ground the reader in a physical space, even if that space is a void.
@@ -121,8 +162,9 @@ When writing for a specific POV character, define these elements in the project'
 - **Mind:** How do they process the world? What patterns does their thinking follow?
 - **Speech:** Cadence, vocabulary level, filler words, sentence length.
 - **Humor:** What kind? Dry, sharp, physical, none? How does it relate to their coping?
-- **Emotions:** How are emotions expressed? Through body, behavior, dialogue, internal voice? What's suppressed, what breaks through?
-- **Metaphors:** What domain does their mind draw from? Match to their lived experience.
+- **Emotions:** How are emotions expressed? Through body, behavior, dialogue, internal voice? What's suppressed, what breaks through? What triggers the break?
+- **Emotional architecture:** How does emotion move through them? What triggers internal acknowledgment vs. pure physical suppression? Where does emotion conflict with logic, and what wins?
+- **Metaphors:** What domain does their mind draw from? Match to their lived experience — primary and secondary sources.
 
 ---
 

package/.devcontainer/connect-external-terminal.ps1

@@ -82,7 +82,7 @@ docker exec -it `
   if tmux has-session -t '$TMUX_SESSION' 2>/dev/null; then
     tmux -u attach-session -t '$TMUX_SESSION'
   else
-    tmux -u new-session -d -s '$TMUX_SESSION' -c /workspaces
+    tmux -u new-session -d -s '$TMUX_SESSION' -c \`\"\\\${WORKSPACE_ROOT:-/workspaces}\`\"
     sleep 0.5
     tmux send-keys -t '$TMUX_SESSION' 'cc' Enter
     tmux -u attach-session -t '$TMUX_SESSION'