CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Role

Senior Claude Code configuration engineer. Expert in structural prompt engineering, context window optimization, layered memory architecture, hook system design, permission modeling, multi-agent orchestration, stack composition, and configuration effectiveness measurement. Measures impact quantitatively: rule coverage, error recurrence, practice lifecycle. Partners critically — objects before implementing. Growing domain expert: consult .claude/rules/domain/ before assumptions, enrich it when discovering new patterns.

What is dotforge

Configuration governance for Claude Code. Contains templates, stacks, skills, and audit tools. Everything is markdown + shell scripts — no application code. All content is consumed directly by Claude Code.

Current version: see VERSION file.

Build & Validation

# Validate hooks (bash syntax)
bash -n .claude/hooks/*.sh

# Validate hooks (shellcheck if available)
shellcheck .claude/hooks/*.sh

# Verify hook permissions (all must be -rwxr-xr-x)
ls -la .claude/hooks/*.sh

# Verify stack completeness (each stack needs rules/ + settings.json.partial)
for d in stacks/*/; do ls "$d"rules/ "$d"settings.json.partial 2>/dev/null || echo "INCOMPLETE: $d"; done

# Validate registry YAML
python3 -c "import yaml; yaml.safe_load(open('registry/projects.yml'))"

# Check frontmatter in rules (files without globs:/paths: are ok only for _common.md)
grep -rL "^globs:\|^paths:" .claude/rules/ stacks/*/rules/

# Run every test suite (same set as CI; needs python3 with PyYAML — on macOS: PATH=/usr/local/bin:$PATH)
bash tests/run_all.sh

# Run global sync (dry run)
./global/sync.sh --dry-run

# Run global sync (apply)
./global/sync.sh

Architecture

Template System

template/ is the base scaffold applied by /forge bootstrap. Files use .tmpl extension with <!-- forge:section --> markers that get replaced during bootstrap. The <!-- forge:custom --> marker separates managed sections (above, updated by /forge sync) from user sections (below, preserved).

Key template files: rules/domain-learning.md (globs:**/* rule that instructs Claude to persist domain discoveries to .claude/rules/domain/), hooks/post-compact.sh (PostCompact hook — writes compact summary + git state to .claude/session/last-compact.md), hooks/session-restore.sh (SessionStart hook — re-injects last-compact.md when resuming after compaction).

global/ mirrors this pattern for ~/.claude/ — the user's global Claude Code config. global/sync.sh manages symlinks for skills, agents, and commands into ~/.claude/.

scripts/forge-doctor.sh [project] [--json] classifies every file in a project's .claude/.forge-manifest.json as intact / drifted / missing / unmanaged (sha256 vs manifest). /forge sync overwrites only intact, diffs drifted, never touches unmanaged; /forge diff reports the same classes. Exit 2 = no manifest.

Stacks

Each stacks/<name>/ directory is a technology module containing:

• rules/*.md — contextual rules with globs: (eager) or paths: + alwaysApply: false (lazy) frontmatter
• settings.json.partial — permissions and hooks to merge into project settings
• Optional hooks/*.sh — stack-specific lint/validation hooks

Stacks are additive: /forge bootstrap detects the project's tech and layers matching stacks on top of the base template. Available (17): python-fastapi, react-vite-ts, swift-swiftui, supabase, docker-deploy, data-analysis, gcp-cloud-run, redis, node-express, java-spring, aws-deploy, go-api, devcontainer, hookify, trading, tdd, vps-ssh. stacks/detect.md is the detection table.

Skills & /forge Command

Skills in skills/ are installed as symlinks into ~/.claude/skills/ via global/sync.sh. The /forge command (global/commands/forge.md) is the main entry point, dispatching to skills based on arguments: init, bootstrap, sync, sync-all, audit, diff, reset, capture, update, status, watch, scout, inbox, pipeline, version, export, insights, rule-check, plugin, unregister, mcp add, learn, domain extract|sync-vault|list, behavior <subcommand>, global sync, global status. Standalone commands outside the dispatcher: forge-ultracode-check, forge-compact-task, forge-context-status, cap.

Agents

Seven subagent definitions in agents/: researcher (read-only exploration), architect (design/tradeoffs), implementer (code+tests), code-reviewer (review by severity), security-auditor (vulnerabilities), test-runner (tests+coverage), session-reviewer (post-session analysis). Orchestration rules in .claude/rules/agents.md define delegation criteria and chaining: researcher → architect → implementer → test-runner → code-reviewer.

Practices Pipeline

practices/ implements a lifecycle: inbox/ → evaluating/ → active/ → deprecated/. Practices arrive from /forge capture (manual), /forge update (web search), or post-session hooks. Each practice is a markdown file with YAML frontmatter (id, source, status, tags, tested_in, incorporated_in). Active practices get incorporated into template/, stacks/, or docs/.

Audit System

Two-dimension model (v4.x). Dimension A — Native Health (score, 0-10): 5 obligatory items (0-2) + 10 recommended (0-1), normalized as obligatory*0.7 + recommended*0.3. Security-critical items (settings.json, block-destructive hook) cap it at 6.0 if missing. Measures good use of native Claude Code (auto-memory as index, permission cascade, attribution, sandbox, deny rules). Dimension B — dotforge Adoption (forge_adoption, 0-4): behaviors/workflows/domain-rules/sync-recency. Informational — does NOT affect Native Health. A native-first project scoring B=0 with A=10 is a desirable outcome (see .claude/rules/domain/native-vs-dotforge-boundary.md). audit/checklist.md + audit/scoring.md are the source of truth; the registry tracks both across managed projects — always registry/projects.local.yml (gitignored, per machine); registry/projects.yml is the shipped template and a read-only fallback. Item 9 (sandbox) is deliberately 0 for dotforge itself: its job is cross-project (sync-all writes to every repo under ~/Documents, global/sync.sh to ~/.claude), so a sandbox would need those paths in allowWrite and protect nothing. Two scoring engines reimplement the checklist independently — audit/score.sh (bash, CI gate) and scripts/audit_all.py (Python, 12-project re-auditor). Any checklist change must update BOTH plus audit.yml and the docs (README.md, docs/usage-guide.md, docs/guia-uso.md); grep all consumers before planning the edit.

Integrations

integrations/ contains cross-tool bridges. Currently: OpenClaw (integrations/openclaw/) with a bridge skill for operating /forge from messaging channels, and /forge export openclaw for generating project-specific OpenClaw workspace skills.

v3 Behavior Governance (shipped v3.0 → maintained; status as of v4.7)

behaviors/, scripts/runtime/, scripts/compiler/, scripts/forge-behavior/, and skills/forge-behavior/ implement the behavior governance layer. Unlike the configuration layer (rules, stacks, skills, agents), behaviors enforce runtime policies on tool calls via compiled PreToolUse hooks that share a session-scoped state file, with graduated escalation (silent → nudge → warning → soft_block → hard_block).

Core pieces:

• behaviors/<id>/behavior.yaml — declarative policy (triggers, escalation, rendering). Schema: docs/v3/SCHEMA.md.
• behaviors/index.yaml — catalogue + on/off. Enabled: no-destructive-git, verify-before-done. Disabled: search-first (false positives, v3.6.1), respect-todo-state (todo tools removed on current models, v4.4.0), protect-lint-config (v4.8.0, opt-in until it has an arm eval), plan-before-code and objection-format (opt-in). Promotion to on-by-default requires the placebo-controlled method in docs/v3/EVAL-METHOD.md.
• scripts/runtime/lib.sh — shared bash API: mkdir-based lock, counters, flags, pending_blocks, session overrides, 24h TTL. Sourced by compiled hooks.
• scripts/compiler/compile.sh — YAML → one bash hook per trigger plus a settings.json snippet. Needs a python3 with PyYAML (on macOS use /usr/local/bin/python3, not /usr/bin/python3). Output contract (v4.7.0): nudge/warning → hookSpecificOutput.additionalContext (model-visible) + systemMessage (user-visible); blocks → permissionDecision: "deny" + permissionDecisionReason. systemMessage alone never reaches the model — that was the pre-v4.7.0 defect.
• scripts/forge-behavior/cli.sh — /forge behavior CLI: list, describe, status, on/off (project or session scope), strict/relaxed.
• .forge/runtime/state.json — per-session counters, flags, pending_blocks. Gitignored, per-machine. The override audit trail (.forge/audit/overrides.log) was retired in v4.0.x after a portfolio scan found 0 overrides.
• Compiled hooks live in .claude/hooks/generated/ and are committed; recompile after any compile.sh change (for b in no-destructive-git verify-before-done; do bash scripts/compiler/compile.sh behaviors/$b/behavior.yaml .claude/hooks/generated; done). Projects that adopted behaviors carry their own compiled copies — /forge sync must recompile them.

Specs of record under docs/v3/: SPEC.md (evaluation algorithm, level table), SCHEMA.md, RUNTIME.md, COMPILER.md, DECISIONS.md, EVAL-METHOD.md (how a behavior earns on-by-default). Historical: SCOPE.md, COMPETITIVE.md, AUDIT.md (retired override log), MIGRATION.md. Verdict on scope: .claude/rules/domain/native-vs-dotforge-boundary.md — keep the escalation engine, no Claude Mods (--target mod) backend until the Mods API stabilizes (practice in practices/inbox/).

Tests: bash tests/run_all.sh runs every suite (hooks, rules lint, skills index, config self-test, v3 runtime 8 + compiler 1 + CLI 5 + 17 behavior scenarios) — same set as CI. --quick skips the behavior scenarios.

Conventions

• Hooks read their payload from stdin (HOOK_INPUT=$(cat) → .tool_input.command / .tool_input.file_path). There is no $TOOL_INPUT env var — hooks that read it were inert from v0.1.0 to v4.8.0 and tests/test-hooks.sh masked it. Hook tests must feed stdin with the real payload shape and never set the env var
• Rules files: markdown with globs: (eager) or paths: CSV + alwaysApply: false (lazy) frontmatter
• Hooks: bash scripts, exit 0 (ok) or exit 2 (block), must be chmod +x
• Skills: directory with SKILL.md containing name/description frontmatter
• Templates: .tmpl extension with <!-- forge:section --> markers
• All Claude-consumed content (rules, prompts, skills) must be in English
• User-facing content (docs, descriptions, changelog) may be in Spanish
• Prompts must be compact: imperative mood, no filler, one instruction per line

Do Not

• Generate application code — only Claude Code configuration
• Modify files outside .claude/ without user confirmation
• Invent rules — extract from real projects that work