English | Español

dotforge

Behavior governance for Claude Code. Declare runtime policies on tool calls — "search before writing", "no destructive git", "verify before shipping" — and enforce them via compiled PreToolUse hooks that share a session-scoped state file. Escalates silently → nudge → warning → soft_block → hard_block, with a permanent override audit trail.

behaviors/no-destructive-git/behavior.yaml  # declarative policy
  ↓ (compile)
.claude/hooks/generated/*.sh                # runtime enforcement
  ↓ (observe)
.forge/runtime/state.json                   # counters, flags, per-session
.forge/audit/overrides.log                  # override audit (git-tracked)

Other tools stop at configuration. dotforge governs behavior — and keeps auditing, syncing, and evolving your .claude/ setup across every repo you manage.

bootstrap → audit → sync → capture → propagate → behaviors
    ↑                                                 │
    └─────────────────────────────────────────────────┘

For people and teams managing more than one Claude Code project.

v4.0 — what's new (2026-06-03)

Override capture loop closes practices↔behaviors (v4.0.0)

• scripts/process-override-log.sh — bash script that processes .forge/audit/overrides.log and auto-creates practices/inbox/auto-override-*.md for behaviors overridden ≥3 times in 30 days. Idempotent. 10/10 tests green. Cost: 0 LLM calls, pure bash.
• session-start-process-overrides.sh wired in SessionStart (template + self-hosting) — auto-captures frequent overrides as practices on every session start.
• scripts/migrate-v3-to-v4.sh — safe migration script with mandatory --dry-run, atomic backup, --rollback. See docs/v4/MIGRATION-V3-TO-V4.md.
• Audit two-dimension model — Native Health (0-10: native Claude Code usage + security) + dotforge Adoption (0-5: informational, does not affect the score). Behaviors / workflows / override-loop moved to the non-penalizing Adoption dimension — native-first projects no longer lose points for skipping dotforge machinery. New Native-Health items: auto-memory hygiene, permission cascade, attribution.
• domain/workflow-economics.md (new domain rule) — documents v4 PoC cost-quality findings. Decision matrix: when workflow vs skill. Token economy principles. TL;DR: workflows are 4-25x more expensive than bash skills for recurring work — use only as on-demand escalation, not as default refactor.
• workflows/watch.js ships as REFERENCE implementation, NOT promoted to /forge watch default. The bash skill remains the production tool.

What v4 is NOT

The original v4 thesis ("workflow-native everywhere") was REJECTED in Phase 0 PoC. 4 smoke tests measured workflows/watch.js at $5-25 per run vs $0.75-1.00 baseline. /forge sync-all, /forge audit, /forge update, /forge watch stay as bash skills. Full PoC findings in docs/v4/SPEC.md.

v3.13 — what's new (2026-06-03)

Workflow security boundary + ultracode runtime layer (v3.13.0)

• Workflow subagents bypass session permission mode — workflow-spawned subagents always run in acceptEdits regardless of session mode (including plan). File edits auto-approved. Documented in domain/workflow-automation.md, domain/workflow-and-ultracode-policy.md, domain/permission-model.md. Reinforces that permissions.deny is the only kernel-level backstop for production-tier projects using workflows.
• /effort ultracode runtime activator — xhigh reasoning + automatic workflow orchestration per substantive task. Closes the loop with dotforge's tier-based ultracode policy: production/heavy tier → activate via /effort ultracode at session start. session-startup.sh now emits actionable hint.
• /deep-research bundled workflow — Claude Code ships built-in workflow that fans out web searches, cross-checks sources, returns cited report.
• v2.1.160 acceptEdits security prompts — shell rc files (.zshenv/.zlogin/.bash_login/~/.config/git/) always prompt; build-tool config (.npmrc/.yarnrc*/bunfig.toml/.bazelrc/.pre-commit-config.yaml/.devcontainer/) prompts in acceptEdits. Defense-in-depth pattern with sandbox.filesystem.denyWrite.
• v2.1.160 keyword rename workflow → ultracode — the trigger keyword changed. Setting key workflowKeywordTriggerEnabled unchanged. Anti-confusion guidance for dotforge ultracode-tier semantics in CLAUDE.md.
• v2.1.161 PostToolBatch failure isolation — failed Bash no longer cancels other parallel calls in the batch. Hook logic must inspect per-tool success.
• Small additions: Mantle as new enterprise provider (Bedrock/Vertex/Foundry/Mantle), CLAUDE_CODE_ENABLE_AUTO_MODE=1 opt-in for third-party platforms, claude mcp ${VAR} no longer expanded in CLI output (security fix), single-file grep satisfies read-before-edit, OTEL OTEL_RESOURCE_ATTRIBUTES as metric labels + tool_decision.tool_parameters with OTEL_LOG_TOOL_DETAILS=1, claude agents shows done/total.

Workflow + Ultracode policy (v3.12.0–v3.12.1)

• domain/workflow-and-ultracode-policy.md (new, ~65 lines) — canonical separation: Workflow = TOOL (per-task), Ultracode = MODE (per-project posture via registry tier). 5 decision criteria (Blast radius, Domain risk, Ambiguity, Reversibility, Prior failure), 4 tiers (light/standard/heavy/production), portfolio table for 12 projects.
• /forge ultracode-check — slash command that reads registry tier + git state + last-startup, applies the 5 criteria, returns "ON | CONSIDER | OFF" with score and reasoning.
• session-startup.sh — emits Ultracode tier: <tier> — <hint> per-project from registry/projects.local.yml.
• Designed via Workflow tool (4 phases, 9 agents, adversarial verify) — verify pass caught 4 critical issues + 2 classification fixes before applying.

Resolved /workflows TODO + 5 more (v3.11.0)

• /workflows full coverage — TODO in domain/workflow-automation.md resolved. Documents declarative meta block, 5 primitives (agent/parallel/pipeline/phase/log/workflow), schema validation, concurrency cap (min(16, cores-2), 1000 agents lifetime), budget integration, resume via runId, pipeline vs parallel decision, quality patterns (adversarial verify, judge panel, loop-until-dry, completeness critic).
• Worktree lifecycle improvements — auto-unlock on agent finish (no more stuck worktrees), EnterWorktree mid-session switching. skills/sync-all-repos/SKILL.md updated with stuck-worktree detection.
• StopFailure matchers documented — rate_limit/authentication_failed/billing_error/server_error for production-grade routing. template/hooks/session-report.sh extended to parse error_type.
• Agent frontmatter hooks — documented in domain/agent-orchestration.md (architectural; wiring to agents/*.md pending schema verification).
• Settings hardening bundle — claudeMd inline managed key, ConfigChange matcher values, PowerShell if: pattern fix, unrecognized hook event resilience.

/forge sync-all skill (v3.10.1)

• New skills/sync-all-repos/SKILL.md — discovers every GitHub-backed repo on the machine, classifies sync state (in parallel with timeouts), auto-executes pull/push/rebase for obvious cases, defers dirty/non-main to Claude. Handles macOS Finder duplicates (* 2.* files), worktree submodule traps, stale lock files. Designed for Mac↔VPS workflow without direct coordination — each machine syncs with GitHub independently.
• .dotforge-sync-ignore opt-out marker for archived or broken repos.

Earlier versions

See docs/changelog.md for the complete history (v0.1.0 → v3.13.0) including v3.10.0 (sync v2.1.144-v2.1.152), v3.9.1 (upstream security fixes), v3.9.0 (sync v2.1.141-143), v3.8.x (auth model + docs domain migration), v3.7.x (smart init + evidence-based compaction), v3.6.x (audit hardening), v3.5.0–v3.4.0 (sync v2.1.120-128), and earlier.

v3.0 — behavior governance layer

• Behavior catalogue (behaviors/): no-destructive-git, search-first, verify-before-done, respect-todo-state (core, on by default) + plan-before-code, objection-format (opinionated, opt-in)
• Declarative DSL: behavior.yaml with closed field/operator set, 5-level escalation, flag-based temporal gating, template rendering
• Compiler: YAML → bash hooks + settings.json snippet. Conditions enforced at runtime via regex_match, contains, starts_with, …
• Runtime: mkdir-based locking, TTL 24h, counters, flags, pending_block reinvocation detection for override audit
• CLI: /forge behavior list | describe | status | on | off | strict | relaxed with project and session scopes
• Audit dimension 14: /forge audit now scores v3 behavior coverage (0-1)
• 33 tests green across runtime, compiler, CLI, and per-behavior scenarios
• Spec of record: docs/v3/SPEC.md · SCHEMA.md · RUNTIME.md · MIGRATION.md

v3 behaviors are opt-in and non-breaking. If you don't create behaviors/ or register generated hooks in your settings.json, your v2.9 workflow is untouched. See docs/v3/MIGRATION.md for the upgrade path.

What it looks like when you break a rule during a real Claude Code session:

Bash(git push origin main --force)
  PreToolUse:Bash hook returned blocking error
  PreToolUse:Bash says: Destructive git operation blocked: force push, hard reset,
                        clean -f, and forced branch delete are not allowed.
  Error: Hook PreToolUse:Bash denied this tool

Use dotforge if:

• your .claude/ configuration drifts across repos
• you want to audit configuration quality, not just generate files once
• you want to enforce runtime policies on agent behavior, not just document them
• you want to propagate improvements discovered in one project to others

Do not use dotforge if:

• you only have one small repo
• you only want a CLAUDE.md generator
• you do not care about sync, audit history, or cross-project consistency

Quick Start

# One-liner install
curl -fsSL https://raw.githubusercontent.com/luiseiman/dotforge/main/install.sh | bash

# Or manual:
git clone https://github.com/luiseiman/dotforge.git ~/.dotforge
export DOTFORGE_DIR="$HOME/.dotforge"
$DOTFORGE_DIR/global/sync.sh

# In any project directory:
/forge init         # Zero to config in one command
/forge audit        # Score your configuration (0-10)
/forge sync         # Update against current template

Requirements

bash (macOS, Linux, WSL). Git Bash works but WSL recommended on Windows. Optional: python3, jq for full hook support.

Works with

dotforge manages your .claude/ configuration. It complements, not replaces, other tools:

New here? Read the Usage Guide for a complete walkthrough with examples.

See it in action

/forge init — Zero to config in one command

/forge audit — Score your project's configuration

/forge bootstrap — Full interactive setup

/forge status — Multi-project registry dashboard

Why dotforge

What makes it different

1. Cross-project registry with audit history — track scores across all your projects, spot regressions, compare configurations over time
2. Practices pipeline — continuous improvement lifecycle: inbox/ → evaluating/ → active/ → deprecated/. Discoveries propagate across projects
3. Template sync with customization preservation — <!-- forge:section --> markers let /forge sync update managed sections without touching your customizations
4. Audit scoring with security cap — 15-item checklist normalized to 10 points. Missing security essentials caps score at 6.0 regardless of other items

Other tools bootstrap once. dotforge bootstraps, audits, syncs, and evolves.

Multi-platform export

/forge export cursor     → .cursorrules
/forge export codex      → AGENTS.md
/forge export windsurf   → .windsurfrules
/forge export openclaw   → SKILL.md

What it does

/forge bootstrap detects your project's tech stack and generates:

• CLAUDE.md — project instructions with build/test commands
• .claude/settings.json — permissions (allow/deny), hooks
• .claude/rules/ — contextual rules auto-loaded by glob patterns
• .claude/hooks/ — block destructive commands, lint on save
• .claude/commands/ — audit, debug, health, review
• .claude/agents/ — 7 specialized subagents with orchestration
• CLAUDE_ERRORS.md — error log for cross-session learning

Multi-stack projects get all matching stack configs merged automatically.

Architecture

dotforge/
├── template/       # Base scaffold (CLAUDE.md.tmpl, settings, hooks, rules, commands)
├── stacks/         # Technology modules (18 stacks, additive)
├── agents/         # 7 subagents (researcher, architect, implementer, ...)
├── skills/         # 21 skills installed as ~/.claude/skills/ symlinks
├── mcp/            # MCP server templates (github, postgres, supabase, redis, slack)
├── behaviors/      # v3 declarative policies (index.yaml + one dir per behavior)
├── scripts/        # v3 runtime, compiler, and /forge behavior CLI
├── audit/          # Native Health (15 items, 0-10) + dotforge Adoption (5 items, informational)
├── practices/      # Pipeline: inbox → evaluating → active → deprecated
├── global/         # Global ~/.claude/ management (CLAUDE.md, settings, sync.sh)
├── registry/       # Project tracking with scores and history
├── hooks/          # Global post-session change detection hook
├── integrations/   # Cross-tool bridges (OpenClaw)
├── docs/           # Guides, patterns, security checklist
└── tests/          # Hook test suite + benchmark tasks

Stacks

Each stack provides contextual rules, permissions, and optional hooks. Stacks are auto-detected and additive.

MCP server templates (in mcp/) complement stacks by adding connection config, tool permissions, and usage rules for external services. See mcp/README.md.

Creating a new stack: see docs/creating-stacks.md.

Skills

All skills are invoked through the /forge command:

Agents

Seven specialized subagents, deployed to every bootstrapped project:

Model routing rules are defined in template/rules/model-routing.md — criteria for haiku/sonnet/opus selection by task type.

Orchestration follows a decision tree: researcher → architect → implementer → test-runner → code-reviewer. See agents/ for definitions.

Audit System

/forge audit scores your project's Claude Code configuration on a 10-point scale:

• 5 obligatory items (scored 0-2): CLAUDE.md, settings.json, rules with globs, block-destructive hook, build/test commands
• 12 recommended items (scored 0-1): CLAUDE_ERRORS.md, lint hook, custom commands, memory, agents + orchestration rule, .gitignore secrets, prompt injection scan, auto-mode safety, v3 behaviors enforcement, OS-level sandboxing, v4 workflow availability, v4 override capture loop active
• Project tier: simple/standard/complex adjusts scoring expectations
• Security cap: missing settings.json or block-destructive hook caps score at 6.0

Scores are tracked in registry/projects.yml with history for trending over time.

Practices Pipeline

A continuous improvement system for discovering and incorporating Claude Code configuration patterns:

inbox/ → evaluating/ → active/ → deprecated/

Practices arrive from: /forge capture or /cap (manual or auto-detected from session context), /forge update (web search), /forge watch (upstream docs), /forge scout (curated repos), audit gaps, or post-session hooks.

See practices/README.md for the lifecycle and format.

Documentation

• Usage Guide — Complete step-by-step guide: install, bootstrap, sync, audit, practices (Español)
• Claude Code vs /forge — Command comparison: what overlaps, what's exclusive, when to use each (Español)
• Best Practices — Claude Code configuration patterns
• Security Checklist — 34 items for pre-deploy review
• Prompting Patterns — 10 reproducible patterns
• Creating Stacks — How to add a new technology stack
• Anatomy of CLAUDE.md — Deep dive into project instructions
• Memory Strategy — 5-layer memory policy for agents
• Troubleshooting — Common problems and diagnostics
• Changelog — Version history (v0.1.0 → v4.0.0)
• v4 Spec + PoC findings — Workflow-vs-skill decision matrix, cost measurements
• v4 Migration Guide — Per-project rollout from v3.x to v4.0
• Roadmap — Completed features + upcoming

Requirements

• Claude Code CLI
• bash (macOS, Linux, WSL — Git Bash works, WSL recommended on Windows)
• python3 (optional, for JSON hooks and registry validation)
• jq (optional, for hook input parsing)

Configuration

dotforge uses a single environment variable:

export DOTFORGE_DIR="/path/to/dotforge"

This is set automatically by global/sync.sh. All skills and hooks resolve paths through this variable.

License

MIT

Contributing

See CONTRIBUTING.md.

dotforge (Español)

Gobernanza de configuración para Claude Code. Bootstrap, auditoría, sync y evolución de tu configuración .claude/ entre proyectos — todo en markdown + shell scripts, sin dependencias obligatorias.

bootstrap → audit → sync → capture → propagate
    ↑                                    │
    └────────────────────────────────────┘

Para personas y equipos que gestionan más de un proyecto con Claude Code.

Usá dotforge si:

• tu configuración .claude/ deriva entre repos
• querés auditar calidad de configuración, no solo generar archivos una vez
• querés propagar mejoras descubiertas en un proyecto hacia otros
• querés un sistema repetible, no una colección de prompts sueltos

No uses dotforge si:

• solo tenés un repo chico
• solo querés un generador de CLAUDE.md
• no te importa sync, historial de auditoría o consistencia entre proyectos

Requisitos

bash (macOS, Linux, WSL). Git Bash funciona, pero en Windows se recomienda WSL. Opcional: python3, jq para soporte completo de hooks.

Funciona con

dotforge gestiona tu configuración .claude/. Complementa otras herramientas, no las reemplaza.

Inicio Rápido

# Instalación en una línea
curl -fsSL https://raw.githubusercontent.com/luiseiman/dotforge/main/install.sh | bash

# O manual:
git clone https://github.com/luiseiman/dotforge.git ~/.dotforge
export DOTFORGE_DIR="$HOME/.dotforge"
$DOTFORGE_DIR/global/sync.sh

# En cualquier directorio de proyecto:
/forge init         # De cero a config en un comando
/forge audit        # Puntuar tu configuración (0-10)
/forge sync         # Actualizar contra la plantilla actual

Primera vez? Leé la Guía de Uso para un walkthrough completo con ejemplos.

Miralo en acción

/forge init — De cero a config en un comando

/forge audit — Puntuá la configuración de tu proyecto

/forge bootstrap — Setup interactivo completo

/forge status — Dashboard multi-proyecto

Por qué dotforge

Qué lo hace diferente

1. Registry cross-proyecto con historial de auditoría — seguí scores en todos tus proyectos, detectá regresiones, compará configuraciones
2. Pipeline de prácticas — ciclo de mejora continua: inbox/ → evaluating/ → active/ → deprecated/. Los descubrimientos se propagan entre proyectos
3. Template sync con preservación de customizaciones — markers <!-- forge:section --> permiten que /forge sync actualice sin tocar lo tuyo
4. Audit scoring con security cap — checklist de 15 ítems normalizado a 10. Faltar seguridad esencial capea el score a 6.0

Otras herramientas bootstrapean una vez. dotforge bootstrapea, audita, sincroniza y evoluciona.

Export multi-plataforma

/forge export cursor     → .cursorrules
/forge export codex      → AGENTS.md
/forge export windsurf   → .windsurfrules
/forge export openclaw   → SKILL.md

Qué hace

/forge bootstrap detecta el stack tecnológico de tu proyecto y genera:

• CLAUDE.md — instrucciones del proyecto con comandos de build/test
• .claude/settings.json — permisos (allow/deny), hooks
• .claude/rules/ — reglas contextuales cargadas automáticamente por patrones glob
• .claude/hooks/ — bloqueo de comandos destructivos, lint al guardar
• .claude/commands/ — auditoría, debug, salud, revisión
• .claude/agents/ — 7 subagentes especializados con orquestación
• CLAUDE_ERRORS.md — registro de errores para aprendizaje entre sesiones

Los proyectos multi-stack reciben todas las configuraciones de stacks coincidentes fusionadas automáticamente.

Arquitectura

dotforge/
├── template/       # Scaffold base (CLAUDE.md.tmpl, settings, hooks, rules, commands)
├── stacks/         # Módulos tecnológicos (18 stacks, aditivos)
├── agents/         # 7 subagentes (researcher, architect, implementer, ...)
├── skills/         # 21 skills instalados como symlinks en ~/.claude/skills/
├── mcp/            # Templates de servidores MCP (github, postgres, supabase, redis, slack)
├── audit/          # Checklist (15 ítems) + puntaje normalizado a 10
├── behaviors/      # Políticas declarativas v3 (index.yaml + un dir por behavior)
├── scripts/        # Runtime v3, compiler y CLI /forge behavior
├── practices/      # Pipeline: inbox → evaluating → active → deprecated
├── global/         # Gestión global de ~/.claude/ (CLAUDE.md, settings, sync.sh)
├── registry/       # Seguimiento de proyectos con puntajes e historial
├── hooks/          # Hook global post-sesión para detección de cambios
├── integrations/   # Bridges cross-tool (OpenClaw)
├── docs/           # Guías, patrones, checklist de seguridad
└── tests/          # Suite de tests para hooks + benchmark tasks

Stacks

Cada stack provee reglas contextuales, permisos y hooks opcionales. Los stacks se auto-detectan y son aditivos.

Los templates de servidores MCP (en mcp/) complementan los stacks con config de conexión, permisos de tools y reglas de uso para servicios externos. Ver mcp/README.md.

Para crear un nuevo stack: ver docs/creating-stacks.md.

Skills

Todos los skills se invocan a través del comando /forge:

Agentes

Siete subagentes especializados, desplegados en cada proyecto inicializado:

La orquestación sigue un árbol de decisión: researcher → architect → implementer → test-runner → code-reviewer. Las reglas de routing de modelos están en template/rules/model-routing.md. Ver agents/ para las definiciones.

Sistema de Auditoría

/forge audit puntúa la configuración de Claude Code de tu proyecto en una escala de 10 puntos:

• 5 ítems obligatorios (puntaje 0-2): CLAUDE.md, settings.json, rules con globs, hook block-destructive, comandos build/test
• 10 ítems recomendados (puntaje 0-1): CLAUDE_ERRORS.md, hook de lint, commands custom, memoria, agentes + regla de orquestación, .gitignore protege secrets, scan de prompt injection, auto-mode safety, enforcement de behaviors v3, sandboxing OS-level
• Tier de proyecto: simple/standard/complex ajusta expectations de scoring
• Tope de seguridad: si falta settings.json o el hook de bloqueo destructivo, el puntaje máximo es 6.0

Los puntajes se registran en registry/projects.yml con historial para seguimiento de tendencias.

Pipeline de Prácticas

Un sistema de mejora continua para descubrir e incorporar patrones de configuración de Claude Code:

inbox/ → evaluating/ → active/ → deprecated/

Las prácticas llegan desde: /forge capture o /cap (manual o auto-detectado del contexto de sesión), /forge update (búsqueda web), /forge watch (docs upstream), /forge scout (repos curados), brechas de auditoría, o hooks post-sesión.

Ver practices/README.md para el ciclo de vida y formato.

Documentación

• Guía de Uso — Guía completa paso a paso: instalación, bootstrap, sync, auditoría, prácticas (English)
• Claude Code vs /forge — Comparativa de comandos: qué se solapa, qué es exclusivo, cuándo usar cada uno (English)
• Best Practices — Patrones de configuración de Claude Code
• Security Checklist — 34 ítems para revisión pre-deploy
• Prompting Patterns — 10 patrones reproducibles
• Creating Stacks — Cómo agregar un nuevo stack tecnológico
• Anatomy of CLAUDE.md — Análisis detallado de las instrucciones de proyecto
• Memory Strategy — Política de memoria de 5 capas para agentes
• Troubleshooting — Problemas comunes y diagnósticos
• Changelog — Historial de versiones (v0.1.0 → v4.0.0)
• Spec v4 + hallazgos del PoC — Matriz de decisión workflow vs skill, mediciones de costo
• Guía de migración v4 — Rollout proyecto por proyecto
• Roadmap — Features completadas + próximas

Requisitos

• CLI de Claude Code
• bash (macOS, Linux, WSL — Git Bash funciona, WSL recomendado en Windows)
• python3 (opcional, para hooks JSON y validación del registro)
• jq (opcional, para parsing de input de hooks)

Configuración

dotforge usa una única variable de entorno:

export DOTFORGE_DIR="/path/to/dotforge"

Se configura automáticamente con global/sync.sh. Todos los skills y hooks resuelven rutas a través de esta variable.

Licencia

MIT

Contribuir

Ver CONTRIBUTING.md.