humania-rs

Humanize

Rust implementation of the Humanize workflow for iterative development with independent Codex review.

Chinese version: README_ZH.md

Project Origin

This repository is a Rust rewrite of the original Humanize project:

• Original project: https://github.com/humania-org/humanize/tree/main

The workflow model remains compatible, but the implementation and runtime orchestration are now handled by Rust.

Overview

Humanize provides three main workflow families:

• RLCR: iterative implementation plus Codex review
• PR loop: review-bot tracking and validation for pull requests
• ask-codex: one-shot Codex consultation

Workflow

RLCR workflow overview:

State is stored under .humanize/ in the working project:

• .humanize/rlcr/
• .humanize/pr-loop/
• .humanize/skill/

Architecture

Humanize is now organized as one shipped runtime plus one external backend:

1. humanize binary The Rust runtime engine. It embeds the prompt templates and owns all loop, hook, validation, monitor, and Codex orchestration logic.
2. Codex CLI The review backend used by RLCR, PR validation, and ask-codex.

There is no separate Codex-host or Kimi-host installation path anymore. Codex is kept only as the independent reviewer backend.

Repository Layout

• crates/core: shared state, filesystem, git, codex, and template logic
• crates/cli: the humanize executable
• prompt-template/: source prompt templates embedded into the binary
• skills/: plugin package SKILL.md source files
• hooks/: plugin hook configuration source files
• commands/: plugin slash-command source files
• agents/: Claude agent and Droid droid source definitions
• .claude-plugin/: legacy plugin metadata kept for compatibility
• docs/: installation and usage docs

Runtime Assets

Prompt Templates

Prompt templates live under prompt-template/:

• prompt-template/block/
• prompt-template/claude/
• prompt-template/codex/
• prompt-template/plan/
• prompt-template/pr-loop/

The humanize binary embeds these templates. The top-level prompt-template/ directory is the source of truth for development and maintenance.

Host Skills

Source skill definitions live under skills/:

• skills/ask-codex/SKILL.md
• skills/humanize/SKILL.md
• skills/humanize-gen-plan/SKILL.md
• skills/humanize-rlcr/SKILL.md

These skills are installed into the host by humanize init.

Installation

The recommended model is:

1. install humanize on PATH
2. install codex on PATH
3. install Humanize into the host

1. Install humanize on PATH

From crates.io:

cargo install humanize-cli --bin humanize

From this repository:

cargo install --path crates/cli --bin humanize

Or build a release binary and place it on PATH manually:

cargo build --release
cp target/release/humanize /usr/local/bin/humanize

Verify:

which humanize
humanize --help

2. Install Codex CLI

Humanize uses Codex as an independent reviewer backend. Install Codex CLI separately and make sure codex is on PATH.

Verify:

codex --version

3. Install into the Host

Claude Code:

humanize init --global

This runs Claude Code's native plugin manager for you:

• adds the Humanize marketplace source if needed
• installs or updates the humanize-rs plugin in user scope
• records the synced CLI version so future CLI/plugin mismatches can be detected

Validate:

humanize init --global --show
humanize doctor
humanize uninstall --global

Droid:

humanize init --global --target droid

This runs Droid's native plugin manager for you:

• adds the Humanize marketplace source if needed
• installs or updates the humanize-rs plugin in user scope
• records the synced CLI version so future CLI/plugin mismatches can be detected

Validate:

humanize init --global --target droid --show
humanize doctor --target droid
humanize uninstall --global --target droid

The humanize executable still comes from PATH. humanize init is now the primary installation path. Use humanize uninstall for the reverse host-side cleanup. This removes the installed host plugin bundle for the selected target/scope, including host-managed skills and slash commands.

Local Development

Inspect the CLI:

humanize --help
humanize setup rlcr --help
humanize setup pr --help
humanize monitor rlcr --help

If humanize is not installed on PATH yet, you can temporarily replace these examples with cargo run -- ... while developing locally.

Versioning

Use the root Cargo.toml workspace version as the single source of truth.

When bumping versions:

cargo xtask sync-version
cargo xtask verify-version-sync

sync-version updates the plugin manifests under .claude-plugin/.

Using Humanize in the Host