# AI Forge - Claude Collective Builder

<p align="center">
  <a href="https://pypi.org/project/ai-forge-collective/"><img src="https://img.shields.io/pypi/v/ai-forge-collective.svg" alt="PyPI version"></a>
  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.12+-blue.svg" alt="Python 3.12+"></a>
  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
  <a href="https://github.com/astral-sh/ruff"><img src="https://img.shields.io/badge/code%20style-ruff-000000.svg" alt="Code style: ruff"></a>
</p>

<p align="center">
  <img src="docs/ai-forge_logo.png" alt="AI Forge Logo" width="300"/>
</p>

A CLI tool for initializing Claude Collective projects with comprehensive workflow instructions, settings, and validation hooks. Transform modular documentation snippets into complete, validated Claude workflows.

## 🚀 Quick Start

### Installation

```bash
# Install from PyPI (recommended)
pip install ai-forge-collective

# Install from GitHub (latest development version)
pip install git+https://github.com/ddlaws0n/ai-forge.git

# Install specific version
pip install ai-forge-collective==1.0.0
```

> **Note**: The package is distributed as `ai-forge-collective` on PyPI, but the CLI command remains `ai-forge` for convenience.

### Basic Usage

```bash
# Initialize a Claude Collective project (default: current directory)
ai-forge init

# Initialize in a specific directory
ai-forge init /path/to/project

# Initialize with custom snippets and templates
ai-forge init --snippets-dir my-snippets --templates-dir my-templates
```

## 📋 Commands

| Command | Description |
|---------|-------------|
| `ai-forge init [PATH]` | Initialize a Claude Collective project with all required files |
| `ai-forge init --help` | Show help and available options |

### What `ai-forge init` Creates:

- **CLAUDE.md** - Complete Claude workflow instructions
- **.claude/settings.json** - Claude Code configuration with hooks
- **.claude/hooks/** - Python and shell hook scripts for workflow automation
- **.claude/commands/** - Custom slash commands for enhanced Claude interactions
- **artifacts/** - Directory for build outputs and state management
- **contracts/** - Directory for API specifications and data models
- **TASK_BOARD.md** - Project task tracking board
- **PROJECT_CHARTER.md** - Project goals and constraints

## 📚 Features

<p align="center">
  <img src="docs/diagram.png" width="500" alt="AI Forge Architecture Diagram"/>
</p>

- **🎯 Project Scaffolding**: Complete Claude Collective project setup in one command
- **📝 Flexible Sections**: Numbered files with YAML frontmatter for dynamic document structure
- **🔧 Multi-Target Building**: Generate CLAUDE.md, settings.json, hooks, and commands
- **🎨 Template System**: Jinja2-based templates with conditional section rendering
- **🪝 Hook System**: Automated pre/post-tool execution with Python and shell scripts
- **⚡ Custom Commands**: Slash commands for enhanced Claude Code interactions
- **✅ Built-in Validation**: Structural integrity and reference consistency checks
- **🔄 Backward Compatible**: Supports both new numbered files and legacy snippet systems
- **🚀 CI/CD Ready**: Integrates with automated workflows

## 🔧 Configuration

You can customize the initialization with command-line options:

| Option | Default | Description |
|--------|---------|-------------|
| `--snippets-dir` | `snippets` | Directory containing snippet files |
| `--templates-dir` | `templates` | Directory containing Jinja2 templates |
| `[PATH]` | `.` (current directory) | Output directory for generated files |

## 🔍 Generated File Validation

The generated CLAUDE.md includes built-in validation for:

- ✅ Required sections present
- ✅ Proper heading hierarchy  
- ✅ Agent and artifact references
- ✅ Token budget consistency
- ✅ Content structure integrity

## 🎯 Use Cases

Perfect for:
- **AI Teams**: Standardize Claude workflows across projects
- **Documentation**: Create consistent, validated Claude instructions
- **CI/CD**: Integrate Claude workflow generation into build pipelines
- **Templates**: Maintain reusable Claude workflow components
- **Project Scaffolding**: Generate complete project structures with artifacts, contracts, and task boards

---

## 🛠️ Development & Contributing

### Prerequisites

- Python 3.12+
- [Just](https://github.com/casey/just) command runner
- [uv](https://github.com/astral-sh/uv) package manager

### Setup

```bash
# Clone the repository
git clone https://github.com/ddlaws0n/ai-forge.git
cd ai-forge

# Install dependencies
uv install --group dev
```

### Repository Structure

```
ai-forge/
├── src/ai_forge/           # Main package code
│   ├── builder.py          # Document building logic
│   ├── document_builder.py # Core document assembly
│   ├── project_builder.py  # Multi-target project building
│   ├── validator.py        # Validation logic
│   └── models.py           # Data models
├── snippets/               # Modular documentation snippets
│   ├── 01-core-mission.md  # Core mission section
│   ├── 02-fundamental-principles.md  # Principles section
│   ├── 03-agent-specifications.md   # Agent definitions
│   ├── 04-communication-formats.md  # Communication patterns
│   ├── 05-execution-workflow.md     # Workflow execution
│   ├── hooks/              # Hook scripts (Python/shell)
│   ├── commands/           # Custom slash commands
│   └── logs/               # Generated logs directory
├── templates/              # Jinja2 templates
├── tests/                  # Test suite
└── output/                 # Generated files
```

### Development Commands

Use the provided Justfile for all development tasks:

```bash
# Build and validate
just build-all              # Build final CLAUDE.md
just validate               # Validate output

# Testing
just test                   # Run tests

# Code quality
just format                 # Format code with ruff
just lint                   # Lint code with ruff
just typecheck              # Type check with mypy
```

You can also use the development CLI commands:

```bash
# Build commands (for development)
ai-forge dev build                    # Build CLAUDE.md only
ai-forge dev build --all-targets      # Build all targets

# Validation commands (for development)
ai-forge dev validate output/CLAUDE.md  # Validate generated file
ai-forge dev build-and-validate         # Build and validate in one step
```

### Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run `just format lint typecheck test` to ensure code quality
5. Submit a pull request

### Adding New Features

- **Document Sections**: Create numbered `.md` files (e.g., `06-new-section.md`) in `snippets/` with YAML frontmatter:
  ```yaml
  ---
  title: "Section Title"
  section_type: "content"  # content|core_mission|principles|agents
  order: 6
  ---
  Your content here...
  ```
- **Hooks**: Add Python (`.py`) or shell (`.sh`) scripts to `snippets/hooks/`
- **Commands**: Add custom slash commands as `.md` files to `snippets/commands/`
- **Templates**: Modify Jinja2 templates in `templates/` to handle new section types
- **Validation**: Add new validation rules to `validator.py`
- **Tests**: Include tests for all new functionality

#### Document Section System

The new system uses numbered files with frontmatter for flexible document generation:

- **Numbering**: Files are processed in order (01-, 02-, 03-, etc.)
- **Frontmatter**: YAML metadata controls rendering behavior
- **Section Types**: `core_mission`, `content`, `principles`, `agents`
- **Backward Compatibility**: Falls back to legacy hardcoded sections if no numbered files exist

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

---

<p align="center">
  <img src="docs/ai-forge_banner.png" alt="AI Forge Banner"/>
</p>

**Built with ❤️ using [uv](https://github.com/astral-sh/uv)**
