open-workspace-builder 1.11.0

Scaffold, maintain, and secure AI coding workspaces

owb — Open Workspace Builder

An open-source internal developer platform (IDP) for AI coding assistants, with built-in policy-as-code and supply chain security for the workspace itself.

OWB is designed for individual developers who use AI coding assistants daily. It is not a team collaboration tool, a hosted service, or a SaaS platform.

Workspace as a platform. owb init scaffolds a structured workspace from a single command: Obsidian knowledge vault, context files, development rules, custom skills, and a workspace config entry point. An interactive wizard handles model selection, vault structure, and security settings. Drift detection and interactive migration keep the workspace current as projects evolve.

Policy as code. Security and development policies are expressed as machine-readable rules enforced automatically. Inline rules govern dependency installation, coding standards, and TDD workflow. Pre-commit hooks run secrets scanning (gitleaks), linting (ruff), SAST (Semgrep), and vulnerability scanning (Trivy). A three-layer security scanner with 58 attack signatures blocks prompt injection, data exfiltration, and MCP manipulation before content reaches your sessions.

Supply chain security. Every dependency and content update passes through a security gate. Package quarantine (7-day aging), pre-install SCA (pip-audit + GuardDog), license auditing, OSS health scoring, suppression monitoring, and content provenance tracking protect the workspace from compromised packages and malicious upstream changes.

OWB also serves as a shared core library. Downstream packages (like vendor-specific wrappers) depend on OWB for engine, security, and configuration infrastructure, then overlay their own defaults.

Quick Start

pip install open-workspace-builder

# First run launches an interactive setup wizard
owb init

# Generate config from an existing Obsidian vault
owb init --from-vault ~/path/to/vault

# Skip the wizard and use defaults
owb init --no-wizard

# Scaffold to a specific directory
owb init --target ~/my-workspace

# Preview without writing anything
owb init --dry-run

This creates an output/ directory (or your chosen target) containing:

output/
├── .ai/
│   └── WORKSPACE.md              # Workspace config entry point
├── .skills/
│   └── skills/                   # Custom skills
├── Context/
│   ├── about-me.md               # Template — your background
│   ├── brand-voice.md            # Template — your writing style
│   ├── working-style.md          # Template — your preferences
│   └── Obsidian/                 # Knowledge vault with 18 note templates
│       ├── _bootstrap.md
│       ├── _index.md
│       ├── _templates/
│       ├── self/, research/, projects/, decisions/, code/, business/
│       └── ...

ECC (Everything Claude Code) agent/command/rule installation is disabled by default. Enable it by setting ecc.enabled: true in your config file.

Already have a vault? See the First Run Guide for a step-by-step walkthrough of running OWB against an existing Obsidian vault, including how to safely test on a copy before touching the live vault.

Configuration

OWB uses a three-layer configuration system:

1. Built-in defaults — sensible values that work out of the box
2. User config file — ~/.owb/config.yaml (auto-detected) or any file via --config
3. CLI flags — override any config value from the command line

Any key you omit falls back to the layer below. See config.example.yaml for the full schema with comments.

Key sections:

Section	Controls
vault	Obsidian vault name, parent directory, assistant name, templates
ecc	ECC catalog enabled/disabled, target directory, agent/command/rule lists
skills	Which custom skills to install
agent_config	Workspace config file directory and filename
models	Per-operation LLM model strings (LiteLLM provider/model format)
security	Active pattern sets, scanner layer selection
trust	Trust tier policy selection
marketplace	Output format (generic, anthropic, openai)
paths	Config, data, and credentials directory paths
context_templates	Whether to deploy personal context files

The setup wizard (owb init on first run) generates ~/.owb/config.yaml interactively. Subsequent runs load it automatically.

Commands

owb init — Scaffold a Workspace

Creates the full directory structure. On first run, launches an interactive wizard to configure your model provider, vault structure, and security settings. Use --config to provide a pre-written config, --from-vault to generate config from an existing Obsidian vault, or --no-wizard to skip the wizard and use defaults.

owb diff — Detect Drift

Compares an existing workspace against the reference state and reports what is missing, outdated, or modified.

owb diff ./output                 # prints human-readable report
owb diff ./output -o report.json  # also writes JSON for automation

owb migrate — Update a Workspace

Brings an existing workspace up to date. Reviews each changed file interactively (or use --accept-all for batch mode). Files that fail security scanning are blocked.

owb migrate ./output              # interactive review
owb migrate ./output --accept-all # batch mode
owb migrate ./output --dry-run    # preview without writing

owb ecc update — Sync Upstream ECC Content

Fetches the latest Everything Claude Code catalog, diffs against your vendored copy, runs the security scanner, and lets you accept or reject each update.

owb ecc update                    # interactive review
owb ecc update --accept-all       # auto-accept clean files
owb ecc status                    # show pinned commit, flag history

owb security scan — Three-Layer Content Scanner

owb security scan ./path          # scan file or directory
owb security scan ./path --layers 1,2   # structural + pattern only
owb security scan ./path -o report.json # write JSON report

owb update — Multi-Source Content Update

Updates content from named upstream sources. Replaces the single-source owb ecc update path with a config-driven pipeline supporting arbitrary sources.

owb update ecc                    # update ECC source
owb update <source>               # update any configured source
owb ecc update                    # backward-compatible alias

owb eval — Skill Evaluation

Evaluates skills using a multi-stage pipeline: classify, generate tests, execute against baseline and candidate, score, and decide.

owb eval ./path/to/skill          # evaluate a new skill
owb eval ./path/to/skill --compare  # compare against existing version

owb metrics — Token Tracking and Cost Analysis

owb metrics tokens                              # consumption report
owb metrics tokens --format json --since 20260301  # filtered JSON
owb metrics export --format gsheets --sheet-id ID  # export to Sheets
owb metrics record --story OWB-S076             # record to local ledger
owb metrics sync --sheet-id ID                  # record + export
owb metrics forecast                            # monthly cost projection
owb metrics budget-check --threshold 200        # budget alert (exit 2 if over)
owb metrics by-story                            # cost per story ID

Requires [sheets] extra for Google Sheets or [xlsx] for Excel export.

Phase Model

OWB uses a phase model to describe workspace maturity. Phase 0 (cold start) and Phase 1 (interactive sessions) are fully operational and represent the project's scope ceiling. The codebase is model-agnostic through LiteLLM, supporting any provider that speaks the protocol. Phase 2 and Phase 3 have been extracted to a separate Volcanix commercial product (see DRN-066).

Security Scanner

The scanner uses a defense-in-depth approach to catch malicious content in workspace files.

Layer	Method	What It Catches
1 — Structural	File type, size, encoding analysis	Binary files, executables, oversized files, zero-width characters, RTL overrides, homoglyphs
2 — Pattern	Regex matching against registry patterns	Shell injection, credential harvesting, data exfiltration, prompt injection, known-malicious signatures
3 — Semantic	LLM analysis via configured model	Behavioral manipulation, social engineering, stealth language, obfuscated payloads, self-modification

Patterns are loaded from the extensible registry. The default set (owb-default) includes 58 patterns across 12 categories. Add custom pattern files to the registry overlay directory for project-specific rules.

Layer 3 requires a configured model in models.security_scan and the llm extra:

pip install "open-workspace-builder[llm]"

Without the extra, layers 1 and 2 still provide coverage for the most common attack patterns.

Using as a Library

OWB is designed to be used as a dependency by downstream packages. A vendor-specific wrapper can:

1. Depend on open-workspace-builder>=0.1.0
2. Provide a pre-baked config YAML with vendor-specific defaults
3. Register its own CLI entry point that sets cli_name in the Click context
4. Use OWB's evaluator, sources, and security infrastructure directly, or add vendor-specific modules on top

OWB's config system resolves paths based on the CLI name, so cwb loads from ~/.cwb/config.yaml while owb loads from ~/.owb/config.yaml. The claude_md YAML key is accepted as a backward-compatible alias for agent_config.

Development

git clone https://github.com/originalrgsec/open-workspace-builder.git
cd open-workspace-builder
uv sync --all-extras

# Run tests (1253 tests)
uv run pytest tests/

# Lint
uv run ruff check src/ tests/
uv run ruff format --check src/ tests/

License

MIT