Crucible

Architecture-first development framework for AI-native applications

Crucible helps teams maintain architectural integrity through formal architecture definitions, automated validation, and seamless Claude Code integration.

Installation

Option 1: Using cargo-binstall (Recommended - Fast)

If you have cargo-binstall installed:

cargo binstall crucible-cli

This downloads prebuilt binaries from GitHub releases, making installation much faster than compiling from source.

Don't have cargo-binstall? Install it with:

cargo install cargo-binstall

Option 2: From crates.io (Standard)

cargo install crucible-cli

This compiles from source and may take a few minutes.

Option 3: From GitHub (Latest Development)

cargo install --git https://github.com/anvanster/crucible.git crucible-cli

This installs the latest unreleased version from the main branch.

Verify Installation

crucible --version

Quick Start

# Create a new project with architecture
crucible init --name my-app

# Or initialize in an existing project
cd my-existing-project
crucible init --here

# Reinitialize existing project (requires confirmation)
crucible init --here --force

# Validate architecture
crucible validate

# Initialize Claude Code integration (optional - init does this automatically)
crucible claude init --mode enhanced

Claude Code Integration

Crucible includes 8 native slash commands for Claude Code, automatically generated on crucible init:

Essential Commands:

• /crucible:validate - Run architecture validation with actionable fixes
• /crucible:architecture - Design architecture for new features (architecture-first TDD)
• /crucible:init - Initialize Crucible in current project

Module Management:

• /crucible:module - Create or update module definitions interactively
• /crucible:review - Comprehensive architecture review with health scoring

Sync & Analysis:

• /crucible:sync - Sync architecture ↔ code bidirectionally
• /crucible:analyze - Deep dive into module dependencies and usage
• /crucible:diff - Show git-style differences between architecture and code

Example Workflow

# 1. Initialize project (auto-creates slash commands)
crucible init --name healthcare-app

# 2. In Claude Code, design architecture
/crucible:architecture "Patient management service"

# 3. Write tests (TDD approach)
# [Write failing tests based on architecture]

# 4. Implement feature
# [Implement to make tests pass]

# 5. Validate compliance
/crucible:validate

# 6. Keep architecture in sync
/crucible:sync

See docs/CLAUDE_CODE_INTEGRATION.md for complete documentation.

Project Structure

• .crucible/ - Crucible's own architecture definition
• crucible-core/ - Core library implementation
• crucible-cli/ - Command-line interface
• spec/ - Specification documents

Development

This project uses Crucible to define its own architecture. Before making changes:

1. Update crucible-core/.crucible/ definitions
2. Validate: crucible validate --path crucible-core/.crucible --strict
3. Implement changes
4. Run tests: cargo test --all

Pre-push Checks

Before pushing to main, run all CI checks locally:

./scripts/pre-push.sh

This runs:

• Code formatting check (cargo fmt)
• Clippy lints (cargo clippy)
• Release build
• Architecture validation
• All tests
• Documentation check

See scripts/README.md for setup as a Git hook.

License

Crucible uses dual licensing:

• Specification (spec/): CC0 1.0 Universal (Public Domain) The Crucible specification, schema, and examples are freely available for anyone to implement.

• Implementation (crucible-core/, crucible-cli/): Apache License 2.0 The Rust implementation code is licensed under Apache 2.0.

See spec/LICENSING.md for detailed licensing information.