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

Once Humanize is installed in Claude Code or Droid, the primary user interface is the host REPL, not the raw CLI. The installed host plugin calls humanize behind the scenes.

With humanize init, both hosts expose the same /humanize-rs:* namespaced slash commands. ask-codex remains available as a skill.

Quick Start

Claude Code:

/humanize-rs:gen-plan --input draft.md --output docs/plan.md
/humanize-rs:start-rlcr-loop docs/plan.md
/humanize-rs:resume-rlcr-loop
/humanize-rs:start-pr-loop --claude
/humanize-rs:resume-pr-loop
/humanize-rs:cancel-rlcr-loop
/ask-codex Explain the latest review result

Droid:

/humanize-rs:gen-plan --input draft.md --output docs/plan.md
/humanize-rs:start-rlcr-loop docs/plan.md
/humanize-rs:resume-rlcr-loop
/humanize-rs:start-pr-loop --claude
/humanize-rs:resume-pr-loop
/humanize-rs:cancel-rlcr-loop
/ask-codex Explain the latest review result

Both hosts expose the same workflow families:

• generate a plan from a draft
• start an RLCR loop
• resume an existing RLCR loop from .humanize/
• start a PR loop
• resume an existing PR loop from .humanize/
• cancel an active RLCR or PR loop
• consult Codex directly

What Init Does For You

• Installs or updates the host plugin via the native Claude Code or Droid plugin CLI.
• Keeps a sync stamp tying the installed plugin to the current humanize CLI version.
• Future CLI runs warn when the host plugin was last synced by a different CLI version.

Doctor

Use humanize doctor to inspect:

• current CLI version
• marketplace configuration
• whether the host plugin is installed
• sync stamp status
• whether humanize init should be rerun

RLCR User Flow

1. In Claude Code or Droid, run /humanize-rs:gen-plan --input draft.md --output docs/plan.md.
2. Run /humanize-rs:start-rlcr-loop docs/plan.md.
3. Continue working normally in the host.
4. When the host stops, Humanize hooks automatically validate state, run Codex review, and decide whether to continue, block, or advance the phase.
5. Use the monitor from a terminal if you want a live view of the loop state.

If the host session is lost but .humanize/rlcr/ still exists, resume the loop instead of starting over:

• /humanize-rs:resume-rlcr-loop

Direct CLI Usage

Direct CLI usage is mainly for:

• monitor dashboards
• debugging
• manual recovery
• non-hook environments

Examples:

humanize gen-plan --input draft.md --output docs/plan.md
humanize setup rlcr docs/plan.md
humanize resume rlcr
humanize gate rlcr
humanize resume pr
humanize ask-codex "Explain the latest review result"

Monitor

One-shot snapshot:

humanize monitor rlcr --once
humanize monitor pr --once
humanize monitor skill --once

Interactive TUI:

humanize monitor rlcr
humanize monitor pr
humanize monitor skill

TUI controls:

• q / Esc: quit
• j / k or arrow keys: scroll
• PgUp / PgDn: page scroll
• g / G: top / bottom
• f: toggle follow mode
• r: refresh immediately

Example RLCR monitor TUI:

Manual Recovery / Hook Debugging

Direct stop invocation:

printf '{}' | humanize stop rlcr
printf '{}' | humanize stop pr

Skill-mode or non-hook gate:

humanize gate rlcr

Gate exit codes:

• 0: allowed
• 10: blocked
• 20: runtime / infrastructure error

Manual Hook Testing

Example: read validator

printf '%s\n' '{"tool_name":"Read","tool_input":{"file_path":"src/main.rs"}}' \
  | humanize hook read-validator

Example: bash validator

printf '%s\n' '{"tool_name":"Bash","tool_input":{"command":"git add -A"}}' \
  | humanize hook bash-validator

Prompt / Skill Maintenance

Update prompt templates in prompt-template/.

Examples:

• prompt-template/claude/next-round-prompt.md
• prompt-template/codex/full-alignment-review.md
• prompt-template/pr-loop/round-0-task-has-comments.md

Update host asset sources in:

• skills/
• hooks/
• commands/
• agents/
• .claude-plugin/

Then rerun humanize init --global for the host you use.

Additional Documentation

• docs/usage.md
• docs/install-for-claude.md
• docs/install-for-droid.md
• docs/install-for-codex.md

Build

cargo build
cargo test

License

MIT