Skip to content

CLAUDE.md

Latest commit

 

History

History
118 lines (73 loc) · 8.96 KB

CLAUDE.md

File metadata and controls

118 lines (73 loc) · 8.96 KB
Raw

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 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/.

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: 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.

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, audit, diff, reset, capture, update, status, watch, scout, inbox, pipeline, version, export, insights, rule-check, benchmark, plugin, unregister, mcp add, domain extract|sync-vault|list, global sync, global status.

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; registry in registry/projects.yml tracks both across managed projects. 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 (alpha — Phase 1 complete)

behaviors/, scripts/runtime/, scripts/compiler/, scripts/forge-behavior/, and skills/forge-behavior/ together implement the v3 behavior governance layer. Unlike the v2 configuration layer (rules, stacks, skills, agents), v3 behaviors enforce runtime policies on tool calls via compiled PreToolUse hooks that share a session-scoped state file.

Core pieces:

  • behaviors/<id>/behavior.yaml — declarative policy (triggers, escalation, rendering). Schema: docs/v3/SCHEMA.md.
  • behaviors/index.yaml — active behavior catalogue, evaluation order.
  • scripts/runtime/lib.sh — shared bash API: mkdir-based lock, counters, flags, pending_blocks, overrides. Sourced by compiled hooks. Tested via scripts/runtime/tests/run_all.sh.
  • scripts/compiler/compile.sh — YAML → bash hook per trigger, plus settings.json snippet. Tested via scripts/compiler/tests/run_all.sh.
  • scripts/forge-behavior/cli.sh — /forge behavior CLI: status, on/off (project or session scope), strict/relaxed. Tested via scripts/forge-behavior/tests/run_all.sh.
  • .forge/runtime/state.json — per-session counters, flags, pending_blocks. Gitignored, per-machine.
  • .forge/audit/overrides.log — permanent append-only soft_block override audit trail. Committed to git.

Specs of record live under docs/v3/: SPEC.md (evaluation algorithm, level table), SCHEMA.md (behavior.yaml v1), RUNTIME.md (state shape, locking, flags §4, TTL §7, reinvocation override detection §12), AUDIT.md (override log format), COMPILER.md (generation rules), SCOPE.md (Phase 1–3 milestones), DECISIONS.md (design decisions), COMPETITIVE.md (differentiation).

Phase 1 (this alpha): runtime + compiler + search-first end-to-end + override detection + /forge behavior CLI. 18 unit/integration tests green, full live smoke test executed in a real Claude Code session.

Phase 2: catalogue (verify-before-done, no-destructive-git, respect-todo-state, plan-before-code, objection-format), /forge audit behaviors-coverage dimension, scope: project for session-clear-resistant behaviors, reorder check_flag template to surface override detection ahead of flag consume.

Phase 3: README rewrite, CHANGELOG v3, migration guide, benchmark, marketplace update, tag v3.0.0.

Conventions

  • 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