codeforge-dev 1.9.0 → 1.11.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,130 @@
 # CodeForge Devcontainer Changelog
 
+## [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
+
+#### 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

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`.
 
@@ -44,13 +46,17 @@ 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) |
+| `ccw` | Shorthand for `claude` with writing system prompt |
 | `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 |
 
@@ -89,8 +95,19 @@ 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
+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)
@@ -98,6 +115,9 @@ ast-grep, biome, ccstatusline, claude-monitor, dprint, hadolint, lsp-servers, mc
 **External features without `version: "none"` support:**
 `ghcr.io/devcontainers-extra/features/uv`, `ghcr.io/anthropics/devcontainer-features/claude-code`, `ghcr.io/nickmccurdy/bun`
 
+**External features with `version: "none"` support (Rust):**
+`ghcr.io/devcontainers/features/rust` (official Microsoft feature)
+
 > **Convention**: Every new local feature must include a `version` option (default `"latest"`) in its `devcontainer-feature.json` and a skip guard at the top of `install.sh`:
 > ```bash
 > if [ "${VERSION}" = "none" ]; then
@@ -114,12 +134,20 @@ 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`/`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` | 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:
@@ -133,9 +161,10 @@ 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
+- `workspace-scope-guard@devs-marketplace` — Blocks writes and warns on reads outside the working directory
 
 ### Local Marketplace
 
@@ -151,12 +180,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 16 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
@@ -164,7 +194,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
+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
 

package/.devcontainer/README.md

@@ -243,7 +243,7 @@ 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
 
@@ -265,6 +265,14 @@ CodeForge includes several custom devcontainer features:
 | `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 |
+
 ## Agents & Skills
 
 The `code-directive` plugin includes specialized agent definitions and coding reference skills.
@@ -293,11 +301,73 @@ 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              # 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
+/spec-check                      # Audit all specs for health
+```
+
+### The Lifecycle
+
+1. **Backlog** — features live in `.specs/BACKLOG.md` with priority grades (P0–P3)
+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
+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 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/
+├── 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
+```
+
+All specs live in domain subfolders. Specs aim for ~200 lines each; split into separate specs in the domain folder when longer.
 
 ## Project Manager