codeforge-dev 1.11.0 → 1.12.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,74 @@
 # CodeForge Devcontainer Changelog
 
+## [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) |
@@ -113,7 +113,7 @@ ast-grep, biome, ccms, ccstatusline, claude-monitor, dprint, hadolint, lsp-serve
 `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 +139,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 +150,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:
@@ -163,7 +167,7 @@ Plugins are declared in `config/defaults/settings.json` under `enabledPlugins` a
 - `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
+- `code-directive@devs-marketplace` — 17 custom agents, 28 skills, syntax validation, skill suggestions, agent redirect hook
 - `workspace-scope-guard@devs-marketplace` — Blocks writes and warns on reads outside the working directory
 
 ### Local Marketplace
@@ -223,6 +227,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 +294,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
@@ -203,7 +204,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 +250,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 +264,14 @@ 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 |
 | `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,9 +281,27 @@ 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 (Not Active by Default)
+
+A self-contained combined auto-formatter and auto-linter plugin available in the marketplace at `plugins/devs-marketplace/plugins/auto-code-quality/`. It bundles formatting and linting into a single plugin with a three-phase pipeline: collect edited files (PostToolUse), batch format (Stop), and batch lint (Stop). Supports the same languages as auto-formatter + auto-linter. **Do not enable alongside auto-formatter or auto-linter** — they overlap in functionality.
+
+## 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.
+The `code-directive` plugin includes 17 custom agent definitions and 28 coding reference skills.
 
 ### Custom Agents (17)
 
@@ -301,11 +327,11 @@ Agent definitions in `plugins/devs-marketplace/plugins/code-directive/agents/` p
 | `statusline-config` | ccstatusline configuration |
 | `test-writer` | Test authoring with pass verification |
 
-### Skills (17)
+### Skills (28)
 
 Skills in `plugins/devs-marketplace/plugins/code-directive/skills/` provide domain-specific coding references:
 
-`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`
+`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`
 
 ## Specification Workflow
 
@@ -400,7 +426,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/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'

package/.devcontainer/devcontainer.json

@@ -9,7 +9,25 @@
 		"WORKSPACE_ROOT": "/workspaces",
 		"CLAUDE_CONFIG_DIR": "/workspaces/.claude",
 		"GH_CONFIG_DIR": "/workspaces/.gh",
-		"TMPDIR": "/workspaces/.tmp"
+		"TMPDIR": "/workspaces/.tmp",
+		"CLAUDECODE": null
+	},
+
+	"secrets": {
+		"GH_TOKEN": {
+			"description": "GitHub Personal Access Token (optional - for git auth)",
+			"documentationUrl": "https://github.com/settings/tokens"
+		},
+		"NPM_TOKEN": {
+			"description": "NPM auth token (optional - for npm registry)",
+			"documentationUrl": "https://www.npmjs.com/settings/~/tokens"
+		},
+		"GH_USERNAME": {
+			"description": "GitHub username for git config (optional)"
+		},
+		"GH_EMAIL": {
+			"description": "GitHub email for git config (optional)"
+		}
 	},
 
 	// Feature install order: external runtimes first (Node, uv, Rust, Bun),
@@ -46,20 +64,22 @@
 	],
 
 	"features": {
-		"ghcr.io/devcontainers/features/node:1": {
+		"ghcr.io/devcontainers/features/node:1.6": {
 			"version": "lts",
 			"nodeGypDependencies": true
 		},
-		"ghcr.io/devcontainers/features/github-cli:1": {},
-		"ghcr.io/devcontainers/features/docker-outside-of-docker:1": {
+		"ghcr.io/devcontainers/features/github-cli:1.0": {},
+		"ghcr.io/devcontainers/features/docker-outside-of-docker:1.7": {
 			"moby": false
 		},
-		"ghcr.io/devcontainers-extra/features/uv:1": {},
+		"ghcr.io/devcontainers-extra/features/uv:1.0": {},
 		"ghcr.io/rails/devcontainer/features/bun:1.0.2": {},
-		"ghcr.io/devcontainers/features/rust:1": {
+		"ghcr.io/devcontainers/features/rust:1.4": {
 			"version": "latest"
 		},
-		"ghcr.io/anthropics/devcontainer-features/claude-code:1": {},
+		// Uncomment to add Go runtime (not installed by default):
+		// "ghcr.io/devcontainers/features/go:1": {},
+		"ghcr.io/anthropics/devcontainer-features/claude-code:1.1": {},
 		"./features/tmux": {},
 		"./features/ccusage": {
 			"version": "latest",
@@ -111,18 +131,21 @@
 		"vscode": {
 			"settings": {
 				"terminal.integrated.profiles.linux": {
+					"zsh": {
+						"path": "zsh"
+					},
 					"bash": {
 						"path": "bash"
 					},
 					"Claude Teams (tmux)": {
-						"path": "bash",
+						"path": "zsh",
 						"args": [
 							"-c",
 							"if tmux has-session -t claude-teams 2>/dev/null; then exec tmux -u new-session -t claude-teams; else exec tmux -u new-session -s claude-teams; fi"
 						]
 					}
 				},
-				"terminal.integrated.defaultProfile.linux": "bash",
+				"terminal.integrated.defaultProfile.linux": "zsh",
 				"terminal.integrated.enableBell": true,
 				"terminal.integrated.commandsToSkipShell": [
 					"-workbench.action.quickOpen",

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

@@ -30,7 +30,9 @@ These control what `setup.sh` does on each container start. Copy `.env.example`
 | `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_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 during installation |
 
 ## `devcontainer.json` `remoteEnv` (Container Runtime)
@@ -43,6 +45,7 @@ These environment variables are set in every terminal session inside the contain
 | `CLAUDE_CONFIG_DIR` | `/workspaces/.claude` | Claude Code config directory |
 | `GH_CONFIG_DIR` | `/workspaces/.gh` | GitHub CLI config directory |
 | `TMPDIR` | `/workspaces/.tmp` | Temporary files directory |
+| `CLAUDECODE` | `null` (unset) | Unsets the variable to allow nested Claude Code sessions (claude-in-claude) |
 
 ## `config/file-manifest.json` (File Copy Rules)
 

package/.devcontainer/docs/plugins.md

@@ -16,7 +16,8 @@ plugins/devs-marketplace/
     ├── protected-files-guard/ # Safety: protect sensitive files
     ├── auto-formatter/        # Batch formatter (Stop hook)
     ├── auto-linter/           # Batch linter (Stop hook)
-    └── code-directive/        # Agents, skills, hooks
+    ├── code-directive/        # Agents, skills, hooks
+    └── workspace-scope-guard/ # Workspace scope enforcement
 ```
 
 Each plugin has a `.claude-plugin/plugin.json` manifest defining its name, description, and capabilities.
@@ -146,9 +147,15 @@ Runs as a PreToolUse hook on Write and Edit operations.
 
 **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.)
+- **28 coding skills** — Domain-specific reference materials (FastAPI, Docker, testing patterns, spec workflow, 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/`.
+
+### workspace-scope-guard
+
+**Purpose**: Enforces workspace scope by blocking writes outside the working directory and warning on out-of-scope reads.
+
+Runs as a PreToolUse hook on Write, Edit, and Read operations. Compares file paths against the current working directory and rejects modifications to files outside the project scope. Read operations outside scope produce a warning but are not blocked. Resolves symlinks and worktree paths correctly via `os.path.realpath()`.

package/.devcontainer/docs/troubleshooting.md

@@ -6,7 +6,7 @@ Common issues and solutions for the CodeForge devcontainer.
 
 **Problem**: Container fails to build during feature installation.
 
-- Check Docker has sufficient memory (4GB+ recommended). CodeForge sets `--memory=4g` by default.
+- Check Docker has sufficient memory (6GB+ recommended). CodeForge sets `--memory=6g` by default.
 - If a specific feature fails, disable it temporarily by setting `"version": "none"` in `devcontainer.json`.
 - Check internet connectivity — most features download binaries from GitHub releases.
 - If hitting GitHub API rate limits during build, set `GH_TOKEN` or `GITHUB_TOKEN` as an environment variable.
@@ -107,7 +107,7 @@ Common issues and solutions for the CodeForge devcontainer.
 
 **Problem**: Container is slow or running out of memory.
 
-- CodeForge defaults to 4GB RAM / 8GB swap. Increase in `devcontainer.json` `runArgs`.
+- CodeForge defaults to 6GB RAM / 12GB swap. Increase in `devcontainer.json` `runArgs`.
 - Disable features you don't need with `"version": "none"`.
 - The background Claude Code update runs once on startup — it's not persistent.
 

package/.devcontainer/features/README.md

@@ -10,16 +10,20 @@ This directory contains DevContainer Features for AI coding agent environments.
 | `agent-browser` | Headless browser automation for AI agents | ✅ |
 | `claude-monitor` | Real-time token usage monitoring | ✅ |
 | `ccusage` | Token usage analytics CLI | ✅ |
-| `ccburn` | Visual token burn rate tracker with pace indicators | ✅ New |
+| `ccburn` | Visual token burn rate tracker with pace indicators | ✅ |
 | `ccstatusline` | 6-line powerline status display (v1.1.0) | ✅ |
 | `ast-grep` | Structural code search using AST patterns | ✅ |
 | `tree-sitter` | Parser with JS/TS/Python grammars | ✅ |
 | `lsp-servers` | Pyright and TypeScript language servers | ✅ |
 | `biome` | Fast JS/TS/JSON/CSS formatter | ✅ |
+| `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 | ✅ |
 | `notify-hook` | Desktop notifications on Claude completion | ✅ |
-| `splitrail` | Git worktree management for parallel branches | ✅ |
 | `mcp-qdrant` | Qdrant vector database MCP server | ✅ (optional) |
-| `mcp-reasoner` | Enhanced AI reasoning MCP server | ✅ (optional) |
 | `claude-code` | Fallback config for Anthropic's official Claude Code feature | ✅ (config only) |
 
 > **Note**: Claude Code itself is installed via `ghcr.io/anthropics/devcontainer-features/claude-code:1` (Anthropic's official feature). The local `claude-code/` directory provides only fallback configuration.
@@ -99,16 +103,11 @@ ghcr.io/yourorg/codeforge-features/feature-name:1
 
 ## Migration from Modules
 
-CodeForge modules are being converted to DevContainer Features:
+CodeForge modules have been converted to DevContainer Features:
 
 | Old Module | New Feature | Status |
 |-----------|-------------|---------|
 | mcp_qdrant | mcp-qdrant | ✅ Complete |
-| mcp_reasoner | mcp-reasoner | ✅ Complete |
-| mcp_browser | mcp-browser | 🔜 Planned |
-| mcp_sourcerer | mcp-sourcerer | 🔜 Planned |
-| mcp_obsidian | mcp-obsidian | 🔜 Planned |
-| mcp_code_runner | mcp-code-runner | 🔜 Planned |
 
 ## Resources