codeforge-dev 1.10.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,143 @@
 # 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
+
+#### New Feature: ccms (Session History Search)
+- **`ccms` devcontainer feature** — Rust-based CLI for searching Claude Code session JSONL files. Installed via `cargo install`. Supports boolean queries, role filtering, time scoping, project isolation, and JSON output
+- **`session-search.md` rule** — global rule requiring project-scoped `ccms` usage and documenting CLI flags/query syntax
+- **Rust runtime** — added `ghcr.io/devcontainers/features/rust:1` as a devcontainer feature (required by ccms)
+- **System prompt `<session_search>` section** — inline reference for ccms usage with key flags and examples
+- **Context management updated** — `<context_management>` now references ccms as the primary recovery tool for compacted sessions (three-source recovery: session history → source files → plan/requirement files)
+
+#### New Feature: ccw (Writing Mode)
+- **`ccw` alias** — launches Claude with `writing-system-prompt.md` for creative-writing tasks
+- **`writing-system-prompt.md`** — dedicated system prompt for writing mode, distributed via file-manifest
+
+#### New Plugin: workspace-scope-guard
+- **`workspace-scope-guard`** — safety plugin that blocks writes and warns on reads outside the working directory. Registered in marketplace.json and enabled by default in settings.json
+
+#### New Skills: spec-build, spec-review (code-directive plugin — 28 skills total)
+- **`/spec-build`** — orchestrates the full implementation lifecycle from an approved spec: plan, build, review, and close in one pass. 5-phase workflow with acceptance criteria markers (`[ ]` → `[~]` → `[x]`)
+- **`/spec-review`** — standalone deep implementation review against a spec. Reads code, verifies requirements and acceptance criteria, recommends `/spec-update` when done
+
+#### New Hook: inject-cwd.py
+- **`inject-cwd.py`** (PostToolUse, all tools) — injects current working directory into every tool response via `additionalContext`
+
+#### Status Line: CWD Widget
+- **`ccstatusline-cwd`** — new custom-command widget showing the basename of Claude Code's working directory. Layout expanded from 7 to 8 lines (16 → 17 widgets)
+
+### Changed
+
+#### setup-aliases.sh Idempotency Fix
+- **Block-marker strategy** — replaced cleanup+guard approach (which left aliases missing on re-run) with a delete-and-rewrite strategy using `START`/`END` block markers. The managed block is removed wholesale by sed range match, then always re-written fresh — no guard/`continue` needed
+- **Legacy cleanup expanded** — added removal of v1.10.0 orphaned aliases/exports/`_CLAUDE_BIN`/`cc-tools()` that existed outside block markers, in addition to pre-v1.10.0 function forms
+- **cc-tools expanded** — added `ccw`, `ccms`, `cargo` to the tool listing
+
+#### Spec Workflow: Version-Based → Domain-Based Organization
+- **Directory structure** — specs now live in domain subfolders (`.specs/{domain}/{feature}.md`) instead of version directories (`.specs/v0.1.0/feature.md`)
+- **ROADMAP.md → MILESTONES.md** — version tracker renamed to milestone tracker throughout all skills, templates, and system prompt
+- **`**Version:**` → `**Domain:**`** — spec template metadata field renamed across spec-new template, spec-writer agent, specification-writing skill, spec-update, spec-check
+- **`roadmap-template.md` → `milestones-template.md`** — reference template replaced
+- **Acceptance criteria markers** — three-state progress tracking: `[ ]` (not started), `[~]` (implemented, not yet verified), `[x]` (verified). Used by `/spec-build` phases and recognized by `/spec-check` and `/spec-update`
+- **Spec lifecycle expanded** — `/spec-review` inserted before `/spec-update` in the recommended post-implementation workflow. `spec-reminder.py` advisory message updated accordingly
+- **Agent skill lists** — architect, generalist, and spec-writer agents gained `/spec-review` access
+
+#### LSP Plugin: Declarative Server Configuration
+- **`codeforge-lsp/plugin.json`** — added `lspServers` block with pyright (Python), typescript-language-server (JS/TS), and gopls (Go) declarative configurations replacing implicit setup
+
+#### git-state-injector.py Enhancements
+- **Working directory injection** — always outputs cwd with scope restriction message, even outside git repos
+- **cwd from hook input** — reads `cwd` from Claude Code's hook JSON input (falls back to `os.getcwd()`)
+
+#### System Prompt Formatting
+- **Line unwrapping** — long wrapped lines consolidated to single lines throughout (no content changes, only formatting)
+
+#### Documentation
+- **CLAUDE.md** — added `ccw`, `ccms` commands; added `writing-system-prompt.md` to directory tree and config table; added workspace-scope-guard to plugin list; skill count 17 → 28; added Rust to `version: "none"` support; updated setup-aliases.sh description
+- **README.md** — added Safety Plugins section; updated spec workflow commands/lifecycle/structure for domain-based organization; added `/spec-build` and `/spec-review` to skill table; fixed system prompt override path (`system-prompt.md` → `main-system-prompt.md`)
+- **claude-guide agent** — fixed system prompt path reference (`system-prompt.md` → `main-system-prompt.md`)
+- **doc-writer agent** — "Version ships" → "Milestone ships" terminology
+- **marketplace.json** — skill count updated (16 → 28); workspace-scope-guard added
+- **skill-suggester.py** — added keyword mappings for `spec-build` and `spec-review`
+- **spec-workflow.md rule** — added `/spec-build` and `/spec-review` rules (#10, #11); added acceptance criteria markers section; updated directory convention to domain-based
+
+### Removed
+
+- **`spec-init/references/roadmap-template.md`** — replaced by `milestones-template.md`
+
+---
+
 ## [v1.10.0] - 2026-02-13
 
 ### Added

package/.devcontainer/CLAUDE.md

@@ -14,7 +14,8 @@ CodeForge devcontainer for AI-assisted development with Claude Code.
 │   │   └── defaults/        # Files copied per manifest
 │   │       ├── settings.json    # Claude Code settings
 │   │       ├── keybindings.json # Claude Code keybindings
-│   │       └── main-system-prompt.md
+│   │       ├── main-system-prompt.md
+│   │       └── writing-system-prompt.md
 │   ├── features/            # Custom devcontainer features
 │   ├── plugins/             # Local plugin marketplace
 │   │   └── devs-marketplace/
@@ -22,7 +23,7 @@ CodeForge devcontainer for AI-assisted development with Claude Code.
 ├── .claude/                 # Runtime Claude config (created on first run)
 │   ├── settings.json        # Active settings (managed by file-manifest.json)
 │   ├── keybindings.json     # Active keybindings
-│   └── system-prompt.md     # Active system prompt
+│   └── main-system-prompt.md # Active system prompt
 └── .gh/                     # GitHub CLI config (persists across rebuilds)
     └── hosts.yml            # Authenticated hosts
 ```
@@ -37,6 +38,7 @@ CodeForge devcontainer for AI-assisted development with Claude Code.
 | `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 |
 
 > **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`.
 
@@ -47,12 +49,14 @@ 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` | 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 |
 | `check-setup` | Verify CodeForge setup health |
 
@@ -103,13 +107,16 @@ 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, 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, 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)
 
 > **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
@@ -127,11 +134,13 @@ Scripts in `./scripts/` run via `postStartCommand`:
 |--------|---------|
 | `setup.sh` | Main orchestrator |
 | `setup-config.sh` | Copies config files per `config/file-manifest.json` to destinations |
-| `setup-aliases.sh` | Creates `cc`/`claude`/`ccraw` shell aliases (prefers native binary at `~/.local/bin/claude` via `_CLAUDE_BIN`) |
+| `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
@@ -141,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:
@@ -156,7 +167,8 @@ 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
 
@@ -172,12 +184,13 @@ plugins/devs-marketplace/
     ├── auto-formatter/       # Batch formatter (Stop hook)
     ├── auto-linter/          # Pyright linter
     ├── code-directive/       # Agents, skills + hooks
+    ├── workspace-scope-guard/ # Workspace scope enforcement
     └── ...
 ```
 
 ## Agents & Skills
 
-The `code-directive` plugin includes 17 custom agent definitions and 17 coding reference skills.
+The `code-directive` plugin includes 17 custom agent definitions and 28 coding reference skills.
 
 **Agents** (`plugins/devs-marketplace/plugins/code-directive/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
@@ -185,7 +198,7 @@ architect, bash-exec, claude-guide, debug-logs, dependency-analyst, doc-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/`):
-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
 
 ## VS Code Keybinding Conflicts
 
@@ -214,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
 
@@ -223,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
@@ -243,11 +246,11 @@ For conflicting shortcuts, use Meta (Alt) variants or add custom keybindings.
 
 ### System Prompt
 
-The default system prompt is in `.devcontainer/config/defaults/main-system-prompt.md`. Override it by creating a `.claude/system-prompt.md` in your project directory.
+The default system prompt is in `.devcontainer/config/defaults/main-system-prompt.md`. Override it by creating a `.claude/main-system-prompt.md` in your project directory.
 
 ## 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,13 +264,44 @@ 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
+
+| Plugin | Description |
+|--------|-------------|
+| `dangerous-command-blocker` | Blocks destructive bash commands (rm -rf, sudo rm, chmod 777, force push) |
+| `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)
 
@@ -293,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
 
@@ -307,7 +341,7 @@ CodeForge includes a specification-driven development workflow. Every non-trivia
 
 ```bash
 /spec-init                       # Bootstrap .specs/ directory (first time only)
-/spec-new auth-flow v0.2.0       # Create a feature spec
+/spec-new auth-flow              # Create a feature spec (domain is inferred)
 /spec-refine auth-flow           # Validate assumptions with user
 # ... implement the feature ...
 /spec-update auth-flow           # As-built update after implementation
@@ -317,7 +351,7 @@ CodeForge includes a specification-driven development workflow. Every non-trivia
 ### The Lifecycle
 
 1. **Backlog** — features live in `.specs/BACKLOG.md` with priority grades (P0–P3)
-2. **Roadmap** — when starting a version, pull features from backlog into `.specs/ROADMAP.md`
+2. **Milestone** — when starting a milestone, pull features from backlog into `.specs/MILESTONES.md`
 3. **Spec** — `/spec-new` creates a spec from the standard template with all requirements tagged `[assumed]`
 4. **Refine** — `/spec-refine` walks through every assumption with the user, converting `[assumed]` → `[user-approved]`. The spec's approval status moves from `draft` → `user-approved`. **No implementation begins until approved.**
 5. **Implement** — build the feature using the spec's acceptance criteria as the definition of done
@@ -337,26 +371,29 @@ A spec-reminder advisory hook fires at Stop when code was modified but specs wer
 
 | Skill | Purpose |
 |-------|---------|
-| `/spec-init` | Bootstrap `.specs/` directory with ROADMAP and BACKLOG |
+| `/spec-init` | Bootstrap `.specs/` directory with MILESTONES and BACKLOG |
 | `/spec-new` | Create a feature spec from the standard template |
 | `/spec-refine` | Validate assumptions and get user approval (required before implementation) |
 | `/spec-update` | As-built update after implementation |
 | `/spec-check` | Audit all specs for health issues |
+| `/spec-build` | Orchestrate full implementation from an approved spec (plan, build, review, close) |
+| `/spec-review` | Standalone deep implementation review against a spec |
 | `/specification-writing` | EARS format templates and acceptance criteria patterns |
 
 ### Directory Structure
 
 ```
 .specs/
-├── ROADMAP.md        # Current version scope
-├── BACKLOG.md        # Priority-graded feature backlog
-├── v0.1.0.md         # Single-file spec (small versions)
-└── v0.2.0/           # Multi-feature version
-    ├── _overview.md   # Parent linking sub-specs
-    └── feature.md     # Individual feature spec
+├── MILESTONES.md      # Milestone tracker linking to feature specs
+├── BACKLOG.md         # Priority-graded feature backlog
+├── auth/              # Domain folder
+│   ├── login-flow.md  # Feature spec
+│   └── oauth.md       # Feature spec
+└── search/            # Domain folder
+    └── full-text.md   # Feature spec
 ```
 
-Specs aim for ~200 lines each. Split by feature boundary when longer; link via a parent overview.
+All specs live in domain subfolders. Specs aim for ~200 lines each; split into separate specs in the domain folder when longer.
 
 ## Project Manager
 
@@ -389,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