codeforge-dev 1.8.0 → 1.10.0

package/.devcontainer/.env

@@ -20,5 +20,8 @@ SETUP_PLUGINS=true
 # Setup: auto-update Claude Code CLI to latest on container start (runs in background)
 SETUP_UPDATE_CLAUDE=true
 
+# Setup: configure VS Code Shift+Enter keybinding for Claude Code terminal
+SETUP_TERMINAL=true
+
 # Plugin blacklist (comma-separated plugin names to skip during auto-install)
 PLUGIN_BLACKLIST=""

package/.devcontainer/CHANGELOG.md

@@ -1,5 +1,112 @@
 # CodeForge Devcontainer Changelog
 
+## [v1.10.0] - 2026-02-13
+
+### Added
+
+#### New Skill: spec-refine (code-directive plugin — 26 skills total)
+- **`/spec-refine`** — iterative 6-phase spec refinement: assumption mining, requirement validation (`[assumed]` → `[user-approved]`), acceptance criteria review, scope audit, and final approval gate
+
+#### setup-terminal.sh
+- New setup script configures VS Code Shift+Enter keybinding for Claude Code multi-line terminal input (idempotent, merges into existing keybindings.json)
+
+### Changed
+
+#### Native Binary Preference
+- **setup-aliases.sh** — introduces `_CLAUDE_BIN` variable resolution: prefers `~/.local/bin/claude` (official `claude install` location), falls back to `/usr/local/bin/claude`, then PATH. All aliases (`cc`, `claude`, `ccraw`) use `"$_CLAUDE_BIN"`
+- **setup-update-claude.sh** — complete rewrite: delegates to `claude install` (first run) and `claude update` (subsequent starts) instead of manual binary download/checksum/swap. Logs to `/tmp/claude-update.log`
+
+#### Smart Test Selection
+- **advisory-test-runner.py** — rewritten to run only affected tests based on edited files. Maps source files to test files (pytest directory mirroring, vitest `--related`, jest `--findRelatedTests`, Go package mapping). Timeout reduced from 60s to 15s. Skips entirely if no files edited
+- **hooks.json** — advisory-test-runner timeout reduced from 65s to 20s
+
+#### Two-Level Project Detection
+- **setup-projects.sh** — two-pass scanning: depth-1 directories with project markers registered directly; directories without markers treated as containers and children scanned. Recursive inotifywait with noise exclusion. Clean process group shutdown
+
+#### Spec Approval Workflow
+- **spec-writer agent** — adds `**Approval:** draft` field, requires `[assumed]` tagging on all requirements, adds `## Resolved Questions` section, references `/spec-refine` before implementation
+- **spec-new skill** — pre-fills `**Approval:** draft`, notes features should come from backlog
+- **spec-check skill** — adds Unapproved (high) and Assumed Requirements (medium) issue checks, Approval column in health table, approval summary
+- **spec-update skill** — minor alignment with approval workflow
+- **spec-init templates** — backlog template expanded with P0–P3 priority grades + Infrastructure section; roadmap template rewritten with pull-from-backlog workflow
+- **specification-writing skill** — updated with approval field and requirement tagging guidance
+
+#### Spec Workflow Completeness
+- **spec-workflow.md (global rule)** — softened 200-line hard cap to "aim for ~200"; added approval workflow rules (spec-refine gate, requirement tags, spec-reminder hook); added `**Approval:**` and `## Resolved Questions` to standard template
+- **main-system-prompt.md** — softened 4× hard "≤200 lines" references to "~200 lines"
+- **spec-new skill** — fixed "capped at 200" internal contradiction; added explanation of what `/spec-refine` does and why
+- **spec-new template** — added Approval Workflow section explaining `[assumed]`/`[user-approved]` tags and `draft`/`user-approved` status
+- **spec-update skill** — added approval gate warning for draft specs; added spec-reminder hook documentation; added approval validation to checklist
+- **spec-check skill** — added `implemented + draft` (High) and `inconsistent approval` (High) checks
+- **spec-init skill** — expanded next-steps with full lifecycle (backlog → roadmap → spec → refine → implement → update → check)
+- **spec-reminder.py** — added `/spec-refine` mention in advisory message for draft specs
+
+#### Documentation Sizing
+- **Relaxed 200-line hard cap** to "aim for ~200 lines" across global rule, system prompt, spec-new skill, architect agent, doc-writer agent, documentation-patterns skill, and spec-check skill
+
+#### Other
+- **setup.sh** — added `SETUP_TERMINAL` flag, normalized update-claude invocation via `run_script` helper
+- **check-setup.sh** — removed checks for disabled features (shfmt, shellcheck, hadolint, dprint); checks RC files for alias instead of `type cc`
+- **connect-external-terminal.sh** — uses `${WORKSPACE_ROOT:-/workspaces}` instead of hardcoded path
+- **devcontainer.json** — formatting normalization
+- **main-system-prompt.md** — updates for spec approval workflow and requirement tagging
+
+### Removed
+- **test-project/README.md** — deleted (no longer needed)
+
+---
+
+## [v1.9.0] - 2026-02-10
+
+### Added
+
+#### Agent Context Inheritance (code-directive plugin)
+- **Project Context Discovery** — all 14 project-interacting agents now read `.claude/rules/*.md` and CLAUDE.md files before starting work. Agents walk up the directory tree from their working directory to the workspace root, applying conventions from each level (deeper files take precedence)
+- **Execution Discipline** — 7 agents (generalist, refactorer, migrator, test-writer, doc-writer, architect, researcher) gain structured pre/post-work verification: read before writing, verify after writing, no silent deviations, failure diagnosis before retry
+- **Code Standards** — 5 agents (generalist full; refactorer, migrator, test-writer, architect compact) gain SOLID, DRY/KISS/YAGNI, function size limits, error handling rules, and forbidden patterns (god classes, magic numbers, dead code)
+- **Professional Objectivity** — 10 agents gain explicit instruction to prioritize technical accuracy over agreement, present evidence when it conflicts with assumptions
+- **Communication Standards** — all 14 agents gain response brevity rules: substance-first responses, no preamble, explicit uncertainty marking, file:line references
+- **Documentation Convention** — 2 write agents (generalist, migrator) gain inline comment guidance (explain "why", not "what")
+- **Context Management** — generalist gains instruction to continue working normally when context runs low
+- **Testing Guidance** — generalist gains testing standards (verify behavior not implementation, max 3 mocks per test)
+- **Scope Discipline** — refactorer gains explicit constraint: never expand scope beyond the requested refactoring
+- **Tiered approach**: Tier 1 (generalist, 139→268 lines, all blocks), Tier 2 (4 write agents, full blocks), Tier 3 (9 read-only agents, compact blocks). 3 agents skipped (bash-exec, claude-guide, statusline-config — no project context needed)
+
+#### Specification Workflow System (code-directive plugin — 4 new skills, 25 total)
+- **`/spec-new`** — creates a new spec from the standard template in `.specs/`
+- **`/spec-update`** — performs as-built spec update after implementation (checks off criteria, adds implementation notes, updates paths)
+- **`/spec-check`** — audits spec health: stale specs, missing coverage, orphaned files
+- **`/spec-init`** — bootstraps `.specs/` directory structure for projects that don't have one
+- **`spec-reminder.py`** `[Stop]` — new advisory hook reminds about spec updates when implementation work is detected
+- **Spec skills assigned to agents** — generalist and spec-writer agents gain spec skill access in frontmatter
+
+#### Default Rules Distribution
+- **`config/defaults/rules/`** — new directory containing default `.claude/rules/` files distributed to all projects via file-manifest
+- **`spec-workflow.md`** — rule enforcing spec-before-implementation workflow, ≤200 line spec limit, `.specs/` directory convention, as-built update requirement
+- **`workspace-scope.md`** — rule restricting file operations to the current project directory
+
+#### New Plugin: auto-code-quality
+- **Self-contained code quality plugin** — combines auto-formatter + auto-linter into a single drop-in plugin with independent temp file namespace (`claude-cq-*`). Includes all 7 formatters (Ruff, Biome, gofmt, shfmt, dprint, rustfmt, Black fallback) and 7 linters (Pyright, Ruff, Biome, ShellCheck, go vet, hadolint, clippy) plus syntax validation. Designed for use outside the CodeForge devcontainer where auto-formatter and auto-linter aren't available separately
+
+### Changed
+
+#### Config System
+- **`file-manifest.json`** — added 2 new entries for default rules files (`defaults/rules/spec-workflow.md`, `defaults/rules/workspace-scope.md`) targeting `${CLAUDE_CONFIG_DIR}/rules`
+- **`setup-config.sh` bug fix** — fixed bash field-collapse bug where empty `destFilename` caused subsequent fields to shift. Uses `__NONE__` sentinel in jq output to prevent `read` from collapsing consecutive tab delimiters
+
+#### Plugin References
+- **`frontend-design` plugin name corrected** — fixed `frontend-design@claude-code-plugins` → `frontend-design@claude-plugins-official` in both `settings.json` and `CLAUDE.md`
+
+#### Code-Directive Plugin
+- **`hooks.json`** — added `spec-reminder.py` to Stop hooks (now 3 Stop hooks: advisory-test-runner, commit-reminder, spec-reminder)
+- **`marketplace.json`** — added `auto-code-quality` plugin entry (10 plugins total, was 9)
+- **Agent definitions** — 14 of 17 agents updated with orchestrator-mirrored instructions (see Agent Context Inheritance above)
+
+#### Formatting
+- **Whitespace normalization** — `settings.json`, `file-manifest.json`, `marketplace.json`, `hooks.json`, `package.json`, `setup-config.sh` reformatted to consistent tab indentation
+
+---
+
 ## [v1.8.0] - 2026-02-09
 
 ### Added

package/.devcontainer/CLAUDE.md

@@ -44,10 +44,12 @@ CodeForge devcontainer for AI-assisted development with Claude Code.
 
 | Command | Purpose |
 |---------|---------|
-| `claude` | Run Claude Code with auto-configuration (creates local `.claude/` if needed) |
+| `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) |
 | `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 |
@@ -89,6 +91,17 @@ Every local feature supports `"version": "none"` to skip installation entirely.
 
 When `version` is set to `"none"`, the feature's `install.sh` exits immediately with a skip message. The feature entry stays in `devcontainer.json` so re-enabling is a one-word change.
 
+**Currently disabled features** (not needed for Python/JS/TS workflow):
+
+| Feature | Handles | Reason |
+|---------|---------|--------|
+| `shfmt` | Shell formatting | Not needed — Python/JS/TS only |
+| `shellcheck` | Shell linting | Not needed — Python/JS/TS only |
+| `hadolint` | Dockerfile linting | Not needed — Python/JS/TS only |
+| `dprint` | Markdown/YAML/TOML/Dockerfile formatting | Not needed — Python/JS/TS only |
+
+The auto-formatter and auto-linter plugins gracefully skip missing tools at runtime.
+
 **All local features support this pattern:**
 ast-grep, biome, ccstatusline, claude-monitor, dprint, hadolint, lsp-servers, mcp-qdrant, mcp-reasoner, notify-hook, ruff, shfmt, shellcheck, splitrail, tmux
 
@@ -114,18 +127,26 @@ 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 |
+| `setup-aliases.sh` | Creates `cc`/`claude`/`ccraw` 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` | Background auto-update of Claude Code binary |
+| `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-symlink-claude.sh` | Symlinks ~/.claude for third-party tool compatibility |
 
+### External Terminal
+
+`connect-external-terminal.sh` connects to the running devcontainer from an external terminal with tmux support for Claude Code Agent Teams split-pane workflows. Run from the host:
+```bash
+.devcontainer/connect-external-terminal.sh
+```
+
 ## Installed Plugins
 
 Plugins are declared in `config/defaults/settings.json` under `enabledPlugins` and auto-activated on container start:
 
 ### Official (Anthropic)
-- `frontend-design@claude-code-plugins` — UI/frontend design skill
+- `frontend-design@claude-plugins-official` — UI/frontend design skill
 
 ### Local Marketplace (devs-marketplace)
 - `codeforge-lsp@devs-marketplace` — LSP for Python + TypeScript/JavaScript
@@ -133,9 +154,9 @@ Plugins are declared in `config/defaults/settings.json` under `enabledPlugins` a
 - `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/Black for Python, gofmt for Go, Biome for JS/TS/CSS/JSON/GraphQL/HTML, shfmt for Shell, dprint for Markdown/YAML/TOML/Dockerfile, rustfmt for Rust)
-- `auto-linter@devs-marketplace` — Auto-lints edited files at Stop (Pyright + Ruff for Python, Biome for JS/TS/CSS/GraphQL, ShellCheck for Shell, go vet for Go, hadolint for Dockerfile, clippy for Rust)
-- `code-directive@devs-marketplace` — 17 custom agents, 16 skills, syntax validation, skill suggestions, agent redirect hook
+- `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
 
 ### Local Marketplace
 
@@ -156,7 +177,7 @@ plugins/devs-marketplace/
 
 ## Agents & Skills
 
-The `code-directive` plugin includes 17 custom agent definitions and 16 coding reference skills.
+The `code-directive` plugin includes 17 custom agent definitions and 17 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
@@ -164,7 +185,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, specification-writing, sqlite, svelte5, testing
+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
 
 ## VS Code Keybinding Conflicts
 

package/.devcontainer/README.md

@@ -293,11 +293,70 @@ Agent definitions in `plugins/devs-marketplace/plugins/code-directive/agents/` p
 | `statusline-config` | ccstatusline configuration |
 | `test-writer` | Test authoring with pass verification |
 
-### Skills (16)
+### Skills (17)
 
 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` · `specification-writing` · `sqlite` · `svelte5` · `testing`
+`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`
+
+## Specification Workflow
+
+CodeForge includes a specification-driven development workflow. Every non-trivial feature gets a spec before implementation begins.
+
+### Quick Start
+
+```bash
+/spec-init                       # Bootstrap .specs/ directory (first time only)
+/spec-new auth-flow v0.2.0       # Create a feature spec
+/spec-refine auth-flow           # Validate assumptions with user
+# ... implement the feature ...
+/spec-update auth-flow           # As-built update after implementation
+/spec-check                      # Audit all specs for health
+```
+
+### 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`
+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
+6. **Update** — `/spec-update` performs the as-built update: sets status, checks off criteria, adds implementation notes
+7. **Health check** — `/spec-check` audits all specs for staleness, missing sections, unapproved status, and other issues
+
+### Approval Workflow
+
+Specs use a two-level approval system:
+
+- **Requirement-level:** each requirement starts as `[assumed]` (AI hypothesis) and becomes `[user-approved]` after explicit user validation via `/spec-refine`
+- **Spec-level:** the `**Approval:**` field starts as `draft` and becomes `user-approved` when all requirements pass review
+
+A spec-reminder advisory hook fires at Stop when code was modified but specs weren't updated.
+
+### Skills Reference
+
+| Skill | Purpose |
+|-------|---------|
+| `/spec-init` | Bootstrap `.specs/` directory with ROADMAP 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 |
+| `/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
+```
+
+Specs aim for ~200 lines each. Split by feature boundary when longer; link via a parent overview.
 
 ## Project Manager