Dotforge MCP Server

English | Español

<p align="center"> <img src="docs/assets/dotforge-banner.svg" alt="dotforge" width="600"> </p>

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.

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

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.9 — what's new (2026-11-04)

Hotfix v4.8.1 — the security hook was inert since v0.1.0

A scout of the 23 top-starred Claude Code configuration repos exposed that block-destructive.sh, lint-on-save.sh, warn-missing-test.sh, detect-stack-drift.sh and every stack lint hook read a $TOOL_INPUT environment variable that Claude Code never sets. Hook input arrives only as JSON on stdin, so the command was always empty and the hooks exited 0 in every real session from v0.1.0 to v4.8.0. The test harness injected the variable by hand and masked it. All 14 hooks now read $(cat) and parse .tool_input.*; tests feed stdin with the real payload. Run /forge sync in every managed project — until then its security hook is still paper. Live proof after the fix: the hook blocked the commit that described it, and lint-on-save.sh fired for the first time ever.

The v4.8.0 context monitor (pre-compact-warning.sh) measured transcript bytes, which never shrink on compaction, and reported 230% after the first compaction. It now reads message.usage of the last assistant turn and derives the window from the model id.

v4.10.0 — domain rules verified against official docs

Every third-party claim from the scout was checked against code.claude.com/docs before landing: permission_mode, stop_hook_active, permissionDecision: ask, classifierContext, PermissionRequest message/interrupt, timeout fall-through + onFailure, blockable ConfigChange, status line prompt_cache.* fields. One scout claim was refuted and recorded. Stale overrides against system-prompt text that no longer exists ("DO NOT ADD ANY COMMENTS", "fewer than 4 lines") were replaced with the live directive from Piebald-AI/claude-code-system-prompts, now a /forge watch source. Four practices captured; the expanded deny-list proposal was declined by design.

v4.4 → v4.8 — upstream sync v2.1.219 → v2.1.291 and ECC scout

• v4.4–v4.7: 25 practices from the upstream sync. Auto mode is the session default when defaultMode is unset (audit item 8 adjusted); project scope cannot set auto/bypassPermissions; todo tools absent on current models (respect-todo-state disabled); agents use tools: (the allowed-tools: field was silently ignored); behaviors emit additionalContext / permissionDecision instead of the model-invisible systemMessage; AGENTS.md first-class in the audit; benchmark skill retired in favor of claude plugin eval.
• v4.8.0: scripts/forge-doctor.sh (intact / drifted / missing / unmanaged by sha256, drives /forge sync and /forge diff), protect-lint-config behavior (opt-in), docs/v3/EVAL-METHOD.md (placebo-controlled evals — how a behavior earns on-by-default), --no-verify / core.hooksPath blocked.

Full detail per version in docs/changelog.md.

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

Audit two-dimension model + override loop retired (v4.0.x)

• Override capture loop — shipped in v4.0.0, retired after validation. A portfolio scan found 0 overrides across all 12 projects in ~7 weeks (production included; only 4/12 adopted behaviors at all). The auditable override trail + capture loop (process-override-log.sh, overrides.log, SessionStart wiring) were removed as dead weight. The graduated escalation engine (soft_block) — which IS exercised; the happy path is "verify", not "override" — stays. See .claude/rules/domain/native-vs-dotforge-boundary.md.
• 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-4: informational, does not affect the score). Behaviors / workflows 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:

Tool	What it does	How dotforge helps
claude-skills	248+ skills collection	dotforge manages the config around your skills
gstack	AI-native full-stack framework	dotforge audits and syncs the .claude/ config gstack generates
duthaho/claudekit	Behavioral modes	dotforge adds lifecycle management: audit, sync, practices, registry

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

Stacks

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

Stack	Detects	Rules
python-fastapi	pyproject.toml, requirements.txt	backend.md, tests.md
react-vite-ts	package.json with react/vite	frontend.md
swift-swiftui	Package.swift, *.xcodeproj	ios.md
supabase	supabase/, @supabase/supabase-js	database.md
docker-deploy	Dockerfile, docker-compose*	infra.md
data-analysis	*.ipynb, *.csv, *.xlsx	data.md
gcp-cloud-run	app.yaml, cloudbuild.yaml	gcp.md
redis	redis in dependencies	redis.md
node-express	package.json with express/fastify	backend.md
java-spring	pom.xml, build.gradle, Spring	backend.md
aws-deploy	cdk.json, template.yaml (SAM)	aws.md
go-api	go.mod, *.go	backend.md
devcontainer	.devcontainer/	devcontainer.md
tdd	pytest.ini, vitest.config.*, jest.config.*	tdd-workflow.md
hookify	Custom hook framework	hooks.md
trading	Custom stack	trading.md

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:

Command	What it does
/forge init	Quick-start: auto-detect stack, 3 questions, generate personalized config
/forge bootstrap	Full interactive bootstrap with preview and confirmation
/forge sync	Update config against current template (merge, not overwrite)
/forge audit	Audit configuration + calculate score (0-10)
/forge diff	Show what changed in dotforge since last sync
/forge reset	Restore .claude/ from template with backup
/forge capture	Register a practice in practices/inbox/ (with args) or auto-detect from session context (no args)
/cap	Shorthand alias for /forge capture — same behavior, 4 chars
/forge update	Process practices: inbox → evaluate → incorporate
/forge watch	Search for upstream changes in Anthropic docs
/forge scout	Review curated repos for useful patterns
/forge export	Export config to Cursor, Codex, Windsurf, or OpenClaw format
/forge learn	Scan code to detect patterns (ORM, auth, testing) and propose domain rules
/forge insights	dotforge-data insights (errors, metrics, registry) fed into practices — cross-project friction is native /insights
/forge rule-check	Detect inert rules by cross-referencing globs against git history (content/cost: /doctor prompt-audit, /skill-doctor)
/forge plugin	Generate Claude Code plugin package for marketplace submission (benchmark it with claude plugin eval)
/forge unregister	Remove a project from the registry
/forge global sync	Auto-update dotforge + sync global ~/.claude/ config
/forge global status	Show global config status

Agents

Seven specialized subagents, deployed to every bootstrapped project:

Agent	Role	Model	Memory
researcher	Read-only codebase exploration	haiku	transactional
architect	Design decisions, tradeoff analysis	opus	persistent
implementer	Code + tests	sonnet	persistent
code-reviewer	Review by severity (critical/warning/suggestion)	sonnet	persistent
security-auditor	Vulnerability scanning	opus	persistent
test-runner	Run tests + report coverage	sonnet	transactional
session-reviewer	Post-session analysis and pattern detection	sonnet	persistent

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, domain rules
• 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.

Herramienta	Qué hace	Cómo ayuda dotforge
claude-skills	Colección de 248+ skills	dotforge gestiona la configuración alrededor de tus skills
gstack	Framework full-stack AI-native	dotforge audita y sincroniza la config .claude/ que genera gstack
duthaho/claudekit	Modos de comportamiento	dotforge agrega gestión del ciclo de vida: audit, sync, prácticas y registry

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

Stacks

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

Stack	Detecta	Reglas
python-fastapi	pyproject.toml, requirements.txt	backend.md, tests.md
react-vite-ts	package.json con react/vite	frontend.md
swift-swiftui	Package.swift, *.xcodeproj	ios.md
supabase	supabase/, @supabase/supabase-js	database.md
docker-deploy	Dockerfile, docker-compose*	infra.md
data-analysis	*.ipynb, *.csv, *.xlsx	data.md
gcp-cloud-run	app.yaml, cloudbuild.yaml	gcp.md
redis	redis en dependencias	redis.md
node-express	package.json con express/fastify	backend.md
java-spring	pom.xml, build.gradle, Spring	backend.md
aws-deploy	cdk.json, template.yaml (SAM)	aws.md
go-api	go.mod, *.go	backend.md
devcontainer	.devcontainer/	devcontainer.md
tdd	pytest.ini, vitest.config.*, jest.config.*	tdd-workflow.md
hookify	Framework de hooks custom	hooks.md
trading	Stack custom	trading.md

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:

Comando	Qué hace
/forge init	Setup rápido: auto-detecta stack, 3 preguntas, config personalizada
/forge bootstrap	Bootstrap completo con preview y confirmación
/forge sync	Actualizar configuración contra la plantilla actual (merge, no sobreescritura)
/forge audit	Auditar configuración + calcular puntaje (0-10)
/forge diff	Mostrar qué cambió en dotforge desde la última sincronización
/forge reset	Restaurar .claude/ desde la plantilla con backup
/forge capture	Registrar una práctica (con args) o auto-detectar desde el contexto de sesión (sin args)
/cap	Alias corto para /forge capture — mismo comportamiento, 4 chars
/forge update	Procesar prácticas: inbox → evaluar → incorporar
/forge watch	Buscar cambios upstream en la documentación de Anthropic
/forge scout	Revisar repos curados en busca de patrones útiles
/forge export	Exportar config a formato Cursor, Codex, Windsurf u OpenClaw
/forge learn	Escanear código para detectar patrones (ORM, auth, testing) y proponer domain rules
/forge insights	Insights con datos dotforge (errores, métricas, registry) → practices; la fricción cross-project es el /insights nativo
/forge rule-check	Detectar reglas inertes cruzando globs contra historial de git (contenido/costo: /doctor prompt-audit, /skill-doctor)
/forge plugin	Generar paquete de plugin para el marketplace de Claude Code (benchmark con claude plugin eval)
/forge unregister	Eliminar proyecto del registro
/forge global sync	Auto-actualizar dotforge + sincronizar ~/.claude/
/forge global status	Mostrar estado de la configuración global

Agentes

Siete subagentes especializados, desplegados en cada proyecto inicializado:

Agente	Rol	Modelo	Memoria
researcher	Exploración de código (solo lectura)	haiku	transaccional
architect	Decisiones de diseño, análisis de tradeoffs	opus	persistente
implementer	Código + tests	sonnet	persistente
code-reviewer	Revisión por severidad (crítico/advertencia/sugerencia)	sonnet	persistente
security-auditor	Escaneo de vulnerabilidades	opus	persistente
test-runner	Ejecución de tests + reporte de cobertura	sonnet	transaccional
session-reviewer	Análisis post-sesión y detección de patrones	sonnet	persistente

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.