Claude Forge

Production-ready governance framework for Claude Code.

Claude Forge provides security guardrails, TDD workflows, and consistent configuration for Claude Code across all your projects.

Features

• Skills Architecture (v0.2.0): Modular, on-demand context loading for reduced token overhead
• Security-first configuration with blocked access to secrets, credentials, and sensitive files
• Test-driven development workflows built-in
• Multi-language support (Python, Rust, Node/TypeScript, C, C++, Bash, Terraform, Terragrunt, Ansible)
• MkDocs documentation standard with mkdocs-material theme
• Personalized setup via interactive questionnaire
• Per-repository auto-configuration on first session
• Automatic backup before any changes
• Cross-platform (Linux, macOS, Windows)
• AGENTS.md symlink for cross-tool compatibility (Cursor, Codex, etc.)

Quick Start

Linux / macOS

curl -sSL https://raw.githubusercontent.com/martimramos/claude-forge/main/install.sh | bash

Windows (PowerShell)

iwr -useb https://raw.githubusercontent.com/martimramos/claude-forge/main/install.ps1 | iex

Installation

The installer will:

1. Check prerequisites (git required, claude CLI recommended)
2. Backup existing ~/.claude/ if present
3. Run an interactive questionnaire
4. Generate personalized configuration
5. Install skills to ~/.claude/skills/
6. Install to ~/.claude/

Prerequisites

• git (required)
• claude CLI (recommended) - install with npm install -g @anthropic-ai/claude-code

What Gets Installed

~/.claude/
├── CLAUDE.md           # Slim config with skill pointers (~50 lines)
├── settings.json       # Permissions + claude-forge metadata
├── .forge-answers      # Saved questionnaire answers
├── commands/
│   ├── init-repo.md    # Per-repo initialization
│   └── tdd.md          # TDD workflow
└── skills/             # Modular skills (v0.2.0)
    ├── security/
    │   ├── SKILL.md
    │   └── reference/
    ├── tdd/
    │   ├── SKILL.md
    │   └── scripts/
    ├── conventions/
    │   ├── SKILL.md
    │   └── reference/
    ├── docs/
    │   └── SKILL.md
    └── languages/
        ├── python/
        ├── rust/
        ├── node/
        ├── typescript/
        ├── c/
        ├── cpp/
        ├── bash/
        ├── terraform/
        ├── terragrunt/
        └── ansible/

Skills Architecture (v0.2.0)

Claude Forge v0.2.0 introduces a modular skills architecture following Anthropic's Agent Skills best practices.

Benefits

• Reduced Token Overhead: Context loads on-demand, not all at startup
• Executable Validation: Scripts for TDD gates and Terraform checks
• Maintainability: Easy to extend or customize individual skills
• Backward Compatible: Previous configs are backed up and migrated

Core Skills

Skill	Description	Contents
security	Credential protection, blocked patterns	SKILL.md + reference docs
tdd	Test-driven workflow, gates	SKILL.md + validation scripts
conventions	Git commit style, branch naming	SKILL.md + examples
docs	MkDocs documentation standards	SKILL.md + templates

Language Skills

Each language skill includes testing, linting, formatting commands and project structure templates:

• languages/python - pytest, ruff, mypy
• languages/rust - cargo test, clippy, rustfmt
• languages/node - npm test, eslint, prettier
• languages/typescript - tsc, jest, eslint
• languages/c - make, gcc, cppcheck, valgrind
• languages/cpp - cmake, clang++, clang-tidy
• languages/bash - bats, shellcheck, shfmt
• languages/terraform - terraform validate, tflint, plan scripts
• languages/terragrunt - terragrunt validate, hclfmt
• languages/ansible - ansible-lint, molecule

Configuration

Questionnaire Options

During installation, you'll be asked:

Question	Options	Default
Name	Free text	Required
Organization	Free text	Optional
Role	Free text	Optional
Languages	python rust node typescript bash c cpp terraform terragrunt ansible	python
Git style	Conventional Commits / Freeform	Conventional
Branch naming	feature/ / initials/ / Freeform	feature/
Test gate	Soft (warn) / Hard (block)	Soft
Network mode	Ask each time / Allow known registries	Ask

Reconfiguring

Run the installer again to reconfigure. Your previous config will be backed up automatically.

Security Model

Blocked File Access (Deny)

These files are NEVER accessible, regardless of any prompt or instruction:

• .env, .env.*, *.env
• Files containing secret, credential, password, token in name
• ~/.ssh/* (SSH keys)
• ~/.aws/* (AWS credentials)
• ~/.config/gcloud/* (GCP credentials)
• ~/.azure/* (Azure credentials)
• *_rsa, *_ed25519, *.pem, *.key
• .npmrc, .pypirc, .netrc, *kubeconfig*

Requires Confirmation (Ask)

• Network requests (WebFetch, curl, wget)
• git push, merge, rebase
• terraform plan, terragrunt plan
• ansible-playbook --check

Always Blocked Commands

Infrastructure commands that could cause damage:

• terraform apply, terraform destroy, terraform import
• terragrunt apply, terragrunt destroy, terragrunt run-all apply/destroy
• ansible-playbook (without --check)
• kubectl apply, kubectl delete, kubectl create
• pulumi up, pulumi destroy
• helm install, helm upgrade, helm delete
• rm -rf, sudo rm, chmod 777

Claude must show the plan/diff first and wait for explicit human approval.

TDD Workflow

Claude Forge enforces test-driven development:

TDD Phases

1. Red: Write failing tests first. No implementation code.
2. Green: Write minimal code to pass tests. No extras.
3. Refactor: Clean up while keeping tests green.
4. Document: Update docs only after tests pass.
5. Commit: Stage and commit with proper message.

Test Gate Modes

Soft (default): Warns when tests fail but allows continuing. Recommended for exploratory work.

Hard: Blocks all progress until tests pass. Recommended for production code.

Validation Scripts

# Check current gate status
~/.claude/skills/tdd/scripts/gate-status.sh

# Run project tests
~/.claude/skills/tdd/scripts/check-tests.sh

Per-Repository Setup

On first session in a new repository (no CLAUDE.md present), Claude will:

1. Detect project languages
2. Ask about project conventions
3. Ask if MkDocs should be initialized
4. Generate project CLAUDE.md
5. Generate .claude/settings.json
6. Create AGENTS.md symlink
7. Offer to commit the configuration

Updating

Run the installer again:

curl -sSL https://raw.githubusercontent.com/martimramos/claude-forge/main/install.sh | bash

Your existing config is backed up automatically. Previous answers are preserved.

Uninstalling

Linux / macOS

curl -sSL https://raw.githubusercontent.com/martimramos/claude-forge/main/uninstall.sh | bash

Windows (PowerShell)

iwr -useb https://raw.githubusercontent.com/martimramos/claude-forge/main/uninstall.ps1 | iex

Backups

Backups are created automatically before:

• Installing (if ~/.claude/ exists)
• Updating
• Uninstalling

Location: ~/.claude.backup.YYYYMMDD-HHMMSS/

Retention: Last 3 backups are kept. Older ones are pruned automatically.

Project Structure

claude-forge/
├── README.md                # This file
├── LICENSE                  # The Unlicense (public domain)
├── CHANGELOG.md
├── install.sh               # Bash installer
├── install.ps1              # PowerShell installer
├── uninstall.sh             # Bash uninstaller
├── uninstall.ps1            # PowerShell uninstaller
├── templates/               # Configuration templates
│   ├── global/
│   ├── project/
│   └── commands/
├── skills/                  # Modular skills (v0.2.0)
│   ├── security/
│   ├── tdd/
│   ├── conventions/
│   ├── docs/
│   └── languages/
└── lib/                     # Shared utilities

Contributing

Contributions welcome. Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test on Linux/macOS and Windows if possible
5. Submit a pull request

License

This is free and unencumbered software released into the public domain.

See LICENSE for details.