# 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

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

### Windows (PowerShell)

```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

```bash
# 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:

```bash
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

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

### Windows (PowerShell)

```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](LICENSE) for details.