ai-forge-collective 1.0.1

A Python tool for programmatically building and validating Claude workflow instructions for AI Forge

AI Forge - Claude Collective Builder

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

# 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

# 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

• 🎯 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 command runner
• uv package manager

Setup

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

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

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

  ---
  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 file for details.

---

Built with ❤️ using uv