Claude Forge

Token-optimized skills, orchestrated review agents, always-on workflow rules, and a deterministic enforcement layer for Claude Code. Four-tier system:

• Identity / rules (always active, pure prose): CLAUDE.md + rules/* define who Claude is and how it works.
• Agents (on-demand reviewers): launched by the orchestrator per file patterns.
• Skills (user-invoked): progressive disclosure for languages, tools, and personal workflows.
• Extensions / hooks (runtime, model-proof): Makefile gates, git-commit guards, ABOUTME enforcer, path protection. Text tells Claude what to do; hooks make sure it happens.

Tuned for Claude Opus 4.8 (effort-aware subagents, no stale version pins, no redundant didactics, fetch-don't-assume for language versions).

Quick Start

Option 1: One-liner (recommended)

curl -sL https://raw.githubusercontent.com/maroffo/claude-forge/main/get.sh | bash

Clones the repo to ~/.claude-forge, then runs the interactive installer. Pick skill categories, enter your name/paths/email, and it copies everything to ~/.claude/ with personalized values. Safe to re-run (backs up existing files, pulls latest on re-run).

Option 2: Symlink (for contributors)

git clone https://github.com/maroffo/claude-forge.git ~/Development/claude-forge

# Backup and symlink
mv ~/.claude/skills ~/.claude/skills.backup
ln -s ~/Development/claude-forge/skills ~/.claude/skills

mv ~/.claude/agents ~/.claude/agents.backup 2>/dev/null
ln -s ~/Development/claude-forge/agents ~/.claude/agents

mv ~/.claude/rules ~/.claude/rules.backup 2>/dev/null
ln -s ~/Development/claude-forge/rules ~/.claude/rules

mv ~/.claude/CLAUDE.md ~/.claude/CLAUDE.md.backup
ln -s ~/Development/claude-forge/CLAUDE.md.example ~/.claude/CLAUDE.md

Option 3: Manual copy

git clone https://github.com/maroffo/claude-forge.git
cp -r claude-forge/skills/* ~/.claude/skills/
cp -r claude-forge/agents/* ~/.claude/agents/
cp -r claude-forge/rules/* ~/.claude/rules/
cp claude-forge/CLAUDE.md.example ~/.claude/CLAUDE.md

Architecture

~/.claude/
├── CLAUDE.md           → Identity, philosophy, routing tables
├── AGENTS.md           → Symlink to CLAUDE.md (emerging cross-tool convention)
├── MEMORY.md           → Persistent [LEARN:x] corrections
├── rules/              → Always-on workflow guardrails (auto-loaded)
├── agents/             → On-demand agents (launched by orchestrator)
├── skills/             → User-invoked language/tool skills
├── hooks/              → PreToolUse/PostToolUse/SessionEnd enforcement scripts (local, not in repo)
├── settings.json       → Hook registration + path-protection deny rules
├── docs/solutions/     → Categorized solved problems (searchable knowledge base)
│
claude-forge repo
├── Makefile            → `make check` + `make test-e2e` (pre-commit gate)
├── scripts/            → check_repo.py (ABOUTME, em-dashes, frontmatter, schema)
├── hooks/              → Source for the enforcement hooks (installed to ~/.claude/hooks/)
├── quality_reports/    → traces/ (gitignored), token_baselines/ (gitignored), harness_changes/ (committed audit trail)
│
Obsidian Vault (Documents/)
├── Projects/           → Per-project artifacts (overview, log, solutions)
├── Plans/              → Cross-project plans (vault-first, local fallback)
└── Second Brain/       → Topic files with Skill Candidates for knowledge-sync

Rules auto-load every conversation — no invocation needed. Agents are launched by the orchestrator based on which files changed. Skills activate based on project context or user invocation.

Effort, not model downgrade, is the cost lever. The main session runs at xhigh (effortLevel in settings.example.json, Anthropic's coding/agentic recommendation for Opus 4.8). Each subagent pins its own effort: in frontmatter: review agents and research at medium, harness-mechanic at high, project-analyzer at low (plus model: haiku), software-engineer omits effort: to inherit the session. Opus 4.8 recalibrated effort (high thinks less, xhigh more), so these are 4.8 baselines, not ported 4.7 values. Override any session or task with /effort. See rules/orchestrator-protocol.md.

Rules (Always Active)

Enforcement Layer (Hooks + Gates)

Text in rules tells Claude what to do; the enforcement layer makes sure it happens even if Claude forgets. Hook scripts ship in hooks/ and are copied to ~/.claude/hooks/ by install.sh.

The matching settings fragment lives at hooks/settings.example.json: registration for all five hooks plus the permissions.deny path-protection rules. install.sh renders it at install time (replacing {{HOOKS_DIR}} with the real path) and prints it for a manual merge into ~/.claude/settings.json. Merge stays manual to avoid clobbering user-specific config.

The repo ships Makefile + scripts/check_repo.py implementing make check (ABOUTME, em-dashes scoped to skills/, frontmatter) and make test-e2e (skill schema smoke).

scripts/metrics-weekly.sh computes three signals to decide whether the enforcement is working: revert rate, fix-up rate, median time-to-next-touch. Run it as a baseline, apply enforcement, re-run after two weeks. If drift indicators don't drop, upgrade Tier A to Tier B (semantic check) or Tier C (full LLM agent).

Telemetry

If enforcement is "make Claude follow the rules", telemetry is "see what Claude actually did". Two skills, one rule, one hook, all driven by arxiv 2605.18747 §3.5 (Agentic Harness Engineering).

Trace JSONL and token baselines under quality_reports/ are gitignored (quality_reports/traces/*.jsonl, quality_reports/token_baselines/*.tsv): they are local-only, regenerated continuously by the hook. Change contracts in quality_reports/harness_changes/*.md ARE committed: they are the audit trail of harness mutations.

Getting traces

1. Run install.sh (copies session-end-trace.sh + .py into ~/.claude/hooks/).
2. Merge the printed SessionEnd block into ~/.claude/settings.json (the installer prints the full hooks/permissions fragment at the end).
3. Open a session in claude-forge and do real work. On /exit, Ctrl-C, or window close the hook fires automatically.
4. Inspect quality_reports/traces/<date>_<session_id>.jsonl. To regenerate a token baseline: cd skills/harness-trace && uv run -- harness-trace baseline --base-dir <repo-root> -o <repo-root>/quality_reports/token_baselines/.

The hook is no-op outside claude-forge: opening Claude Code in another project does not touch this directory.

Agents (On-Demand)

Launched by the orchestrator based on file patterns. All review agents are read-only (report findings, never edit).

Skills

Skills are markdown files that teach Claude domain-specific patterns. They load automatically when relevant or on demand via /skill-name in Claude Code.

How invocation works:

• Type /obsidian to activate the Obsidian vault skill
• Type /commit to use the source-control commit workflow
• Type /knowledge-sync to run the vault-to-skills sync
• Some skills auto-activate based on project context (e.g., golang/ loads when working in a Go project)

Shared reference files (_*.md) are not invocable. They provide configuration and patterns that other skills reference internally.

Languages & Frameworks

Large skills use a references/ subdirectory for detailed patterns (progressive disclosure: core in SKILL.md, details on demand). Currently: android-kotlin/, apple-swift/, bujo-sync/, golang/, humanizer/, python/, rails/, react-nextjs/, ruby/.

Shared Reference Files

Support & Integrations

Content & Images

Personal Workflows

Vault Integration (Obsidian)

An optional layer that turns an Obsidian vault into a knowledge backbone for Claude Code. Works across three layers; each is useful alone but they compound together.

Prerequisites

• Obsidian app installed and running (the CLI is built-in, see _OBSIDIAN.md for config)
• A vault named "Documents" (configurable in _OBSIDIAN.md)
• Without Obsidian: everything degrades gracefully to local quality_reports/ paths. No vault = no breakage.

Layer 1: Structured Storage

Plans, session logs, and solutions go to the vault instead of project-local folders.

Documents/
├── Projects/<project>/          Overview, Log, Solutions per project
├── Plans/                       Cross-project plans (draft → approved → done)
└── Second Brain/                Topic files (existing, unchanged)

Configured in rules/plan-first-workflow.md and rules/orchestrator-protocol.md.

Layer 2: Context Injection

Project CLAUDE.md files can reference vault notes via a ## Vault Context section:

## Vault Context
- Architecture: [[Projects/feed-brain/feed-brain - Overview]]
- Go patterns: [[Second Brain - Development#Go (Golang)]]

Claude reads linked notes on demand via obsidian read. Token budget rules prevent context bloat (< 5KB: read fully; 5-20KB: outline first; > 20KB: section only). See _VAULT_CONTEXT.md.

Layer 3: Knowledge Feedback Loop

Recurring patterns accumulate in Second Brain topic notes as ## Skill Candidates tables. The /knowledge-sync skill (run monthly) scans for strong signals (3+ projects) and proposes additions to skill files, with mandatory human approval.

learning-docs retrospective → annotate pattern (weak signal)
  → seen in 3+ projects → signal becomes strong
    → /knowledge-sync proposes skill update → human approves → skill improved

Onboarding a Project

Ask Claude to onboard the current project to the vault:

"Onboard this project to the vault"

Claude reads the project's CLAUDE.md (or asks for basics), then automatically:

1. Creates Overview, Log, and Solutions notes in Projects/<project>/
2. Registers in the Projects MOC
3. Adds ## Vault Context to the project's CLAUDE.md

This also runs automatically when using /project-analyzer on a new codebase.

The protocol is defined in _VAULT_CONTEXT.md (Project Onboarding section). It's idempotent: skips notes that already exist.

Obsidian Skills Map

Skill Conventions

Skills follow Anthropic's Complete Guide to Building Skills for Claude, with additional project conventions. Use /skill-forge to create or audit skills.

Token Optimization

Everything is aggressively optimized:

• Tables over verbose lists
• Condensed code examples
• No redundancy across files
• Rules/agents reference each other, never duplicate

Inspiration

Evolved from Harper Reed's dotfiles, Matteo Vaccari's AI-assisted modernization series, Pedro Santanna's orchestrated workflow, Every's compound-engineering-plugin (solutions directory, research agent, incremental commits), Get Shit Done v1 (requirements refinement, deviation rules), GSD 2 (append-only decisions, outcome verification, "don't hand-roll" research, anti-drift summaries), Anthropic's Complete Guide to Building Skills (progressive disclosure, trigger phrases, skill-forge), andlaf-ak's claude-code-agents (test-design-reviewer, cognitive load dimensions, hotspot analysis), and Scaling Coding Agents via Atomic Skills (atomic skill decomposition, localization/reproduction steps, cascade analysis).

License

MIT